HTTP API

Available

The SDK is Python-only. If you work in another language, go straight to HTTP.

Create an execution

POST /v1/executions
Authorization: Bearer <service-JWT>
Content-Type: application/json

{
  "tenant_id": "bank-uz",
  "actor":     { "type": "user", "id": "u-42" },
  "input":     { "text": "Block the card ending 7731" },
  "agent_id":  "card-support",
  "idempotency_key": "order-2026-08-12-0001"
}

Required: tenant_id · actor · input.

Response

{
  "execution_id": "exe_0123…",
  "status": "created",
  "thread_id": "thr_0f3c9d"
}

Fetch state

GET /v1/executions/{execution_id}
Authorization: Bearer <service-JWT>

{
  "execution_id": "exe_0123…",
  "status": "completed",
  "operations": [
    {
      "operation_id": "op_77…",
      "capability_id": "sales.order.create",
      "status": "VERIFIED",
      "resource_ref": "deal:10001",
      "verification_method": "read_after_write",
      "verification_evidence": "closed=N"
    }
  ]
}

⚡ status and operations[].status are separate answers. Why.

Streaming (SSE)

GET /v1/executions/{execution_id}/stream
Accept: text/event-stream

An event arrives on every state change. If the connection drops, fetch the current state with GET and reconnect.

Idempotency

Case	Result
Same key + same body	The existing execution is returned (`200`)
Same key + different body	`409` — no silent overwrite

⚠ Send a stable key per logical action. Details.

Error envelope

{
  "error": {
    "code": "rate_limited",
    "message": "…",
    "retryable": false
  }
}

The field is code, not type. Internal details (host, URL, secrets, stack traces) are never exposed.

What is not available

⛔	Note
`gRPC`	Not planned
Client-facing `WebSocket`	Internal channel and voice layer only
Outbound webhooks	⏳ not yet — use SSE or polling