Api / Agents

POST/v1/agents/:id/chat

Auth: tenant — Status: stable

RESTful equivalent of POST/v1/orchestrate with a path-bound agent id. Same SSE shape, same billing-service gating, same safety policies.

The path :id resolves through the same chain as /v1/orchestrate — inline agent_def first, then the tenant's stored catalog, then the built-in index. So you can hit a stored agent with no body beyond message.

Request

Path paramTypeDescription
idstringAgent id. Same resolution rules as /v1/orchestrate.

Body

FieldTypeRequiredDescription
messagestringyesThe prompt.
agent_defobjectnoInline agent definition. If present, its id MUST match the path :id.
agentstring—Ignored — the path wins.
curl -N \
  -H "Authorization: Bearer atr_…" \
  -H "Content-Type: application/json" \
  -d '{"message":"write a haiku about SQLite"}' \
  http://arbiter.example.com/v1/agents/researcher/chat

Headers

Idempotency-Key is honoured here with the same semantics as POST/v1/orchestrate: a retry with the same key replays the original execution as SSE rather than triggering a second one.

With an inline agent_def (UUID-keyed memory persistence):

curl -N \
  -H "Authorization: Bearer atr_…" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "what did we decide about the migration last time?",
    "agent_def": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Migration Reviewer",
      "role": "reviewer",
      "model": "claude-haiku-4-5",
      "goal": "review migrations and remember decisions"
    }
  }' \
  http://arbiter.example.com/v1/agents/550e8400-e29b-41d4-a716-446655440000/chat

Response

Identical SSE stream to POST/v1/orchestrate. See the SSE event catalog for shapes.

Failure modes

Identical to POST/v1/orchestrate, plus:

StatusWhenBody
400Body's agent_def.id ≠ path :id.{"error": "agent_def.id must match path :id"}

See also