Skip to content

api-reference.md

Latest commit

 

History

History
407 lines (267 loc) · 11.8 KB

api-reference.md

File metadata and controls

407 lines (267 loc) · 11.8 KB
Raw

← Agents | Pipelines →

Docs: Getting Started · Tutorial · Configuration · Agents · API Reference · Pipelines · Async Jobs · Webhooks · Client Usage · Tools Proxy · Security · Process Pool · Testing · Troubleshooting

API Reference

All endpoints require Authorization: Bearer <token> unless noted otherwise.

Agents

GET /agents

List all registered agents.

curl -s http://localhost:18010/agents \
  -H "Authorization: Bearer $ACP_BRIDGE_TOKEN"

Response:

{
  "agents": [
    {"name": "kiro", "mode": "acp", "description": "Kiro CLI agent"},
    {"name": "claude", "mode": "acp", "description": "Claude Code agent"}
  ]
}

Runs

POST /runs

Synchronous or streaming agent call.

Input format note: The input field uses the ACP protocol message format (nested parts array). If this feels verbose, use acp-client.sh which wraps it for you:

./skill/scripts/acp-client.sh -a kiro "Hello"   # no JSON needed

Request body:

Field Type Required Description
agent_name string Yes Agent to call
input array Yes ACP input: [{"parts": [{"content": "...", "content_type": "text/plain"}]}]
stream boolean No true for SSE streaming (default: false)
session_id string No Reuse an existing session for multi-turn
cwd string No Working directory override 
# Sync
curl -s -X POST http://localhost:18010/runs \
  -H "Authorization: Bearer $ACP_BRIDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent_name":"kiro","input":[{"parts":[{"content":"Hello","content_type":"text/plain"}]}]}'

# Streaming (SSE)
curl -N -X POST http://localhost:18010/runs \
  -H "Authorization: Bearer $ACP_BRIDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent_name":"kiro","input":[{"parts":[{"content":"Hello","content_type":"text/plain"}]}],"stream":true}'

⚠️ Use input with a parts array — NOT prompt. Using {"prompt":"..."} returns invalid_input: Field required.

Jobs

POST /jobs

Submit an async background job. See Async Jobs for full details.

Field Type Required Description
agent_name string Yes Agent to run
prompt string Yes Task prompt
target string No Webhook push target (e.g. channel:123, user:456)
channel string No IM channel (discord, feishu)
callback_meta object No Extra webhook metadata (e.g. {"account_id": "default"})

GET /jobs

List all jobs with status stats.

GET /jobs/{job_id}

Query a single job by ID.

Pipelines

POST /pipelines

Submit a multi-agent pipeline. See Pipelines for full details.

Field Type Required Description
mode string Yes sequence, parallel, race, or conversation
steps array Yes [{"agent": "kiro", "prompt": "..."}]
max_turns integer No Conversation mode only (default: 6, max: 12)
target string No Webhook push target
channel string No IM channel

GET /pipelines

List all pipelines.

GET /pipelines/{id}

Query a single pipeline by ID.

GET /stats/pipelines

Per-mode aggregation stats. Optional ?hours=N query param (default: 168 = 7 days).

Harness

POST /harness

Create a dynamic harness agent at runtime.

curl -X POST http://localhost:18010/harness \
  -H "Authorization: Bearer $ACP_BRIDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"profile":"reviewer","system_prompt":"Review Python code for security issues"}'
Field Type Required Description
profile string Yes Preset name (e.g. reviewer, developer, operator)
system_prompt string No Custom system prompt
model string No Model alias (default: auto)

GET /harness

List dynamic harness agents. Response includes resolved_model (populated after first call).

DELETE /harness/{name}

Delete a dynamic harness agent.

Files

POST /files

Upload a file (multipart form data).

curl -X POST http://localhost:18010/files \
  -H "Authorization: Bearer $ACP_BRIDGE_TOKEN" \
  -F "file=@data.csv"

GET /files

List uploaded files.

DELETE /files/{filename}

Delete an uploaded file.

Tools Proxy

GET /tools

List available OpenClaw tools. See Tools Proxy.

POST /tools/invoke

Invoke an OpenClaw tool.

curl -X POST http://localhost:18010/tools/invoke \
  -H "Authorization: Bearer $ACP_BRIDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tool":"message","action":"send","args":{"channel":"discord","target":"channel:123","message":"Hello"}}'

A2A Mesh

Mesh endpoints are registered only when mesh.enabled: true. See A2A Mesh for setup details.

GET /.well-known/agent.json

Public A2A Agent Card. No Bearer token is required.

curl -s http://localhost:18010/.well-known/agent.json

POST /a2a/announce

Peer discovery endpoint. Uses mesh.token, not the global Bridge token.

curl -s -X POST http://localhost:18010/a2a/announce \
  -H "Authorization: Bearer $MESH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent_card":{"url":"http://peer:18010","skills":[]},"peers":[]}'

GET /a2a/peers

Peer table for debugging. Requires the global Bridge token.

curl -s http://localhost:18010/a2a/peers \
  -H "Authorization: Bearer $ACP_BRIDGE_TOKEN"

Chat (Web UI)

POST /chat/messages

Save a chat message.

GET /chat/messages

Load recent chat messages. Optional ?session_id= query param.

DELETE /chat/messages

Clear all chat messages.

POST /chat/fold

Fold (collapse) a session's messages in the UI.

Templates

GET /templates

List available prompt templates.

POST /templates/render

Render a template with variables.

curl -X POST http://localhost:18010/templates/render \
  -H "Authorization: Bearer $ACP_BRIDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template":"code-review","variables":{"file":"src/agents.py"}}'

Sessions

DELETE /sessions/{agent}/{session_id}

Close a session and release its subprocess.

Health & Stats

GET /live (no auth)

Lightweight liveness probe. Returns HTTP 200 when the Bridge HTTP process is running.

GET /ready (no auth)

Readiness probe. Returns HTTP 200 when at least one agent is configured. A lazy ACP process pool may still be cold; agents are spawned on the first request.

GET /health (no auth)

Detailed three-state health check: ok, degraded, unhealthy. Includes process pool watermark, system memory, uptime, and agent_states counts. Agent state is cold before its first on-demand spawn, ready when a process is alive, and down only after an explicit health failure. A cold pool returns HTTP 200.

GET /health/agents

Per-agent status with high-level state (cold/ready/down/on_demand/remote) and per-session connection state (idle/busy/stale/dead).

GET /stats

Agent call statistics: total calls, durations, tool usage by category.

GET /ui (no auth)

Web UI chat interface (requires --ui flag or server.ui: true).

LiteLLM Proxy & Usage Tracking

ANY /litellm/{path} — LiteLLM Proxy

Transparent pass-through to the LiteLLM instance. Forwards any GET/POST request.

curl -s http://localhost:18010/litellm/v1/chat/completions \
  -H "Authorization: Bearer $ACP_BRIDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"bedrock/deepseek.v3.2","messages":[{"role":"user","content":"hi"}],"max_tokens":10}'

GET /usage — Aggregated Usage Stats

Query token usage, cache rates, and per-model breakdown.

Param Default Description
hours 24 Time window
model Filter by model name 
curl -s http://localhost:18010/usage -H "Authorization: Bearer $ACP_BRIDGE_TOKEN"

Response:

{
  "hours": 24.0,
  "calls": 5,
  "input_tokens": 120,
  "output_tokens": 85,
  "total_tokens": 205,
  "cached_tokens": 40,
  "cache_rate_pct": 33.3,
  "avg_duration_s": 0.82,
  "by_model": [
    {"model": "bedrock/deepseek.v3.2", "calls": 3, "input_tokens": 60, ...}
  ]
}

GET /usage/recent — Recent Call Details

Param Default Description
limit 20 Number of records

POST /internal/llm-callback (loopback only, no Bearer auth)

Receives StandardLoggingPayload from LiteLLM generic_api callback. Requests from non-loopback clients are rejected with HTTP 403. Not intended for direct use.

Prompt Log

Every prompt actually sent to an agent (across pipelines, jobs, and heartbeats) is recorded into data/jobs.db for post-mortem and replay. Each record stores:

  • template — the original user-supplied prompt (for pipeline steps: prompt_template; for jobs: raw input)
  • rendered — after {{var}} substitution from pipeline context
  • final — what actually reached the agent (includes shared_workspace*.txt hint and get_prompt_suffix())
  • decorations — list of layers applied, e.g. ["shared_workspace_zh", "prompt_suffix"]

Default response omits the large prompt fields. Pass ?include=final to retrieve them.

Privacy: With prompt_log.redact_secrets: true (default), values matching OPERATIONS.md sensitive patterns are masked before write — see Security.

GET /pipelines/{pipeline_id}/prompts

Records for every step (and every conversation turn) in a pipeline.

Param Default Description
include (none) Comma-separated extras: final to also return template/rendered/final 
curl -s "http://localhost:18010/pipelines/$PID/prompts?include=final" \
  -H "Authorization: Bearer $ACP_BRIDGE_TOKEN"

GET /jobs/{job_id}/prompts

Records for a job (one per attempt, if fallback fired).

curl -s "http://localhost:18010/jobs/$JID/prompts?include=final" \
  -H "Authorization: Bearer $ACP_BRIDGE_TOKEN"

GET /admin/prompts

Cross-cutting search across all parent types.

Param Default Description
parent_type (any) job / pipeline_step / heartbeat
agent (any) Filter by agent name
limit 50 Max records (1–500)
include (none) final to include large fields 
# Latest 10 prompts sent to opengame across any path
curl -s "http://localhost:18010/admin/prompts?agent=opengame&limit=10" \
  -H "Authorization: Bearer $ACP_BRIDGE_TOKEN"

GET /admin/prompts/{record_id}

Direct single-record lookup; returns final by default.

curl -s "http://localhost:18010/admin/prompts/<record_id>" \
  -H "Authorization: Bearer $ACP_BRIDGE_TOKEN"

Disabling

Set prompt_log.enabled: false in config.yaml and restart. The endpoints will return 503 prompt logging disabled.

Request Tracing

All requests receive an X-Request-Id response header. Pass your own via the request header to stitch traces across services (e.g. OpenClaw → Bridge → agent logs).

See Also