Reference
API
The A22A REST API at https://api.a22a.sh.
Authentication
Send your API key in the x-api-key header. Keys are created on API keys in the A22A dashboard.
curl https://api.a22a.sh/v1/deploy/acme -H "x-api-key: $A22A_API_KEY"A missing or unknown key returns 401 with unauthorized. Request and response bodies are JSON. Every response carries an x-request-id header; quote it when reporting a problem. An error body is { "error": "<code>" }; see Errors.
Deploying a project
POST /v1/deployStores the project as its next version. The body is the project's name and its workflows; see Workflows for steps.
{
"project": "acme",
"workflows": {
"summarise": {
"steps": [
{ "id": "extract", "prompt": "Pull the key facts from {{input.text}}", "model": "anthropic/claude-haiku-4.5" }
]
}
}
}Returns 200:
{ "project": "acme", "version": 1, "workflows": ["summarise"] }| Status Code | Error |
|---|---|
| 400 | invalid_body, invalid_structure |
| 500 | deploy_failed |
Retrieving a project
GET /v1/deploy/:projectReturns 200 with the latest version, its id, and the stored document with every default filled in:
{
"id": "0f6c…",
"project": "acme",
"version": 1,
"manifest": {
"project": "acme",
"workflows": {
"summarise": {
"steps": [
{ "id": "extract", "prompt": "…", "model": "anthropic/claude-haiku-4.5", "retries": 2, "needs": [] }
]
}
}
}
}| Status Code | Error |
|---|---|
| 404 | not_found |
| 500 | find_failed |
Invoking a workflow
POST /v1/run/:project/:workflowQueues a run on the project's latest version. input is optional and defaults to {}.
{ "input": { "text": "…" } }Returns 202:
{ "run_id": "4b3e…" }| Status Code | Error |
|---|---|
| 400 | invalid_body, invalid_input |
| 402 | no_plan, insufficient_credits |
| 404 | not_found |
| 409 | model_unavailable |
| 429 | too_many_runs |
| 500 | create_failed |
Retrieving a run
GET /v1/runs/:idReturns 200 with the run and its steps; see Runs.
{
"run_id": "4b3e…",
"status": "running",
"steps": [
{ "step_id": "extract", "status": "completed", "output": "…" },
{ "step_id": "write", "status": "running" }
]
}| Status Code | Error |
|---|---|
| 404 | not_found |
| 500 | find_failed |