Client API v1

The Client API is the stable boundary for business systems, agent platforms, and automation tools. It is not the Executor Protocol or Agent Client Runtime.

Submit a job

POST /run
Authorization: Bearer <client-token>
Content-Type: application/json

{
  "request_id": "order-10001-ai-001",
  "route": "order_assistant",
  "input": "Explain why this order has not shipped",
  "metadata": {
    "principal": { "id": "u_42", "tenant": "t_100" },
    "order_id": "10001"
  },
  "callback_url": "https://biz.example.com/ai/callback"
}

Field	Rule
`request_id`	Client-scoped idempotency key; retries must reuse it
`route`	Stable route key configured and allowlisted for this client
`input`	Untrusted task text; never an authorization source
`metadata`	Optional context; final authorization remains in the business system
`callback_url`	Optional HTTP(S) completion callback

The contract rejects unknown top-level fields. Do not use the old callback spelling or add an arbitrary source field.

Poll a job

GET /jobs/{job_id}
Authorization: Bearer <client-token>

Statuses are queued, running, dispatched, done, error, or rejected. After a timeout or network interruption, reconcile the same job_id; do not create a new write request blindly.

Completion callbacks

BailingHub signs callback bodies. Verify the timestamp, HMAC, and accepted time window before consuming a result. Callback delivery failure does not prove that the job failed, so retain polling as a recovery path.