Trigger a job
POST/run
{
"request_id": "order-10001-ai-001",
"route": "order_assistant",
"input": "Analyze why this order has not shipped.",
"metadata": {
"tenant_id": "t_100",
"operator_uid": "u_42",
"order_id": "SO20260701001"
},
"callback": "https://business.example.com/ai/callback"
}request_id is the business idempotency key. route is the stable scenario key configured in the hub console.
Poll status
GET/jobs/{job_id}
{
"id": "job_...",
"status": "queued | running | done | error",
"result": { "summary": "...", "detail": {} },
"error": null
}Callback signature
POSTBusiness callback URL
X-Bailing-Signature: sha256=<hmac>
X-Bailing-Timestamp: 1782912000
{
"job_id": "job_...",
"route": "order_assistant",
"status": "done",
"result": { "summary": "..." }
}Always verify the signature before consuming callback or tool call payloads. A valid signature proves the request came from the hub; it does not replace your own business permission checks.
Contract rules
| Rule | Meaning |
|---|---|
| Metadata is an object | Do not send JSON strings where structured objects are expected. |
| Hub owns runtime state | Jobs, messages, trace, audit, and approval data live in the hub database. |
| Business owns authority | Your backend verifies signatures and checks whether the on-behalf-of subject can perform the action. |
| Use graceful degradation | Your system should keep working if the AI hub is paused or temporarily unavailable. |