Skip to content
Open the app

API reference ​

The Kadmo API 1.3.0 at https://app.kadmo.ai/api/v1 has 13 operations. This page lists each one with its parameters, its answers and a call to copy, then the objects they answer. How to authenticate, the errors, the limits and idempotency are on API; how to get a token is on API tokens.

The page is generated from the API's OpenAPI 3.1.0 document: download it, or read the one the app serves at https://app.kadmo.ai/api/v1/openapi.json (no token needed). A tool that generates a client or tests calls reads either.

The examples read the token from the environment variable KADMO_API_TOKEN.

Operations at a glance ​

OperationCallDoes
Who the token isGET /meThe member the token acts as, their account and role, and the token itself. A cheap call to test a credential.
List recent jobsGET /jobsThe account’s jobs, newest first, a page at a time.
Dispatch a jobPOST /jobsQueue a workflow in a workspace. The job starts queued and an agent of the account takes it. A job can spend the account’s credit.
Get a jobGET /jobs/{id}The job with its status, its agent, its playbook run, what it waits on and, once finished, its result.
Create a taskPOST /tasksFile a ticket in the workspace’s tracker, or as an internal task, and add it to Tasks as pending. It does not start: run a playbook on it to start work.
Get a taskGET /tasks/{key}A task of the account’s Tasks, with its status, its playbook and its runs.
Run a playbook on a taskPOST /tasks/{key}/runsApprove the task with a playbook. The run starts when nothing holds it — the tasks it depends on, its workspace’s pool, a step only a person can do: 201 with the run when it started in the call, 202 with what it waits on when it did not, and it then starts on its own. A task not in Tasks yet is added from its tracker. A run can spend the account’s credit.
List subscriptionsGET /webhooksThe token’s member’s subscriptions, newest first, without their secrets.
Subscribe a URL to eventsPOST /webhooksMake a subscription of the token’s member: each event it lists is POSTed to the URL, signed with the subscription’s secret, and retried for 24 hours when the endpoint fails. The answer carries the secret, this once.
UnsubscribeDELETE /webhooks/{id}Delete one of the token’s member’s subscriptions: nothing more is delivered to it, the deliveries still waiting included.
List workspacesGET /workspacesThe account’s active workspaces: what workspace names in a call, and where each files a new task.
List workflowsGET /workflowsThe workflows a dispatch can name — the enabled ones — with the inputs each reads.
List playbooksGET /playbooksThe playbooks a run can name — the enabled ones — with their steps.

Account ​

Who the token is ​

GET /me · getMe

The member the token acts as, their account and role, and the token itself. A cheap call to test a credential.

bash
curl https://app.kadmo.ai/api/v1/me \
  -H "Authorization: Bearer $KADMO_API_TOKEN"
StatusAnswer
200Me. The token’s member and account.
401Refused: unauthorized. With WWW-Authenticate.
405Refused: method_not_allowed.
429Refused: rate_limited. With Retry-After.
500Refused: internal_error.

Jobs ​

List recent jobs ​

GET /jobs · listJobs

The account’s jobs, newest first, a page at a time.

ParameterInTypeRequiredMeaning
statusquerystringnoComma-separated: queued, running, needs_input, succeeded, failed, cancelled, or finished for the last three.
workspacequerystringnoA workspace’s slug. At most 200 characters.
workflowquerystringnoA workflow’s name. At most 200 characters.
taskquerystringnoA task’s key. At most 200 characters.
app_job_idqueryintegernoThe app’s job number.
limitqueryintegernoAt most this many, 1 to 100; 20 when unset.
cursorquerystringnoThe next_cursor of the previous page. At most 40 characters.
bash
curl https://app.kadmo.ai/api/v1/jobs \
  -H "Authorization: Bearer $KADMO_API_TOKEN"
StatusAnswer
200JobList. A page of jobs.
400Refused: invalid_request.
401Refused: unauthorized. With WWW-Authenticate.
405Refused: method_not_allowed.
429Refused: rate_limited. With Retry-After.
500Refused: internal_error.

Dispatch a job ​

POST /jobs · createJob

Queue a workflow in a workspace. The job starts queued and an agent of the account takes it. A job can spend the account’s credit.

ParameterInTypeRequiredMeaning
Idempotency-KeyheaderstringnoOptional. The same key with the same request within 24 hours answers the first answer again and writes nothing. 1 to 255 characters.

The body is a JSON object; a field it does not list is refused.

FieldTypeRequiredMeaning
workflowstringyesThe workflow to run, by name (GET /workflows). 1 to 200 characters.
workspacestringyesThe workspace it runs in, by slug (GET /workspaces). 1 to 200 characters.
inputobject of stringsnoThe workflow’s inputs, by name: ticket_url and hint among them when it reads them.
effortstringnoAn effort tier of the account (low, medium, high, or one of its own); unset, the workflow’s default.
bash
curl -X POST https://app.kadmo.ai/api/v1/jobs \
  -H "Authorization: Bearer $KADMO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"workflow":"se-work","workspace":"main","input":{"ticket_url":"https://example.atlassian.net/browse/PROJ-123"}}'
StatusAnswer
201Job. The job, queued.
400Refused: invalid_idempotency_key, invalid_request.
401Refused: unauthorized. With WWW-Authenticate.
402Refused: budget_reached, no_credit, trial_expired.
404Refused: workflow_not_found, workspace_not_found.
405Refused: method_not_allowed.
409Refused: duplicate_job, idempotency_in_progress, idempotency_key_reused, workspace_archived. With Retry-After.
413Refused: payload_too_large.
415Refused: unsupported_media_type.
422Refused: model_not_in_plan, role_not_enabled, role_not_runnable, workflow_not_runnable.
429Refused: daily_cap_reached, rate_limited. With Retry-After.
500Refused: internal_error.
503Refused: authorisation_unavailable.

Get a job ​

GET /jobs/{id} · getJob

The job with its status, its agent, its playbook run, what it waits on and, once finished, its result.

ParameterInTypeRequiredMeaning
idpathintegeryesThe job’s id.
bash
curl https://app.kadmo.ai/api/v1/jobs/9001 \
  -H "Authorization: Bearer $KADMO_API_TOKEN"
StatusAnswer
200Job. The job.
401Refused: unauthorized. With WWW-Authenticate.
404Refused: job_not_found.
405Refused: method_not_allowed.
429Refused: rate_limited. With Retry-After.
500Refused: internal_error.

Tasks ​

Create a task ​

POST /tasks · createTask

File a ticket in the workspace’s tracker, or as an internal task, and add it to Tasks as pending. It does not start: run a playbook on it to start work.

ParameterInTypeRequiredMeaning
Idempotency-KeyheaderstringnoOptional. The same key with the same request within 24 hours answers the first answer again and writes nothing. 1 to 255 characters.

The body is a JSON object; a field it does not list is refused.

FieldTypeRequiredMeaning
workspacestringyesThe workspace the task belongs to, by slug (GET /workspaces). 1 to 200 characters.
titlestringyesThe ticket’s title. 1 to 255 characters.
descriptionstringnoThe ticket’s description, as plain text or Markdown. At most 100000 characters.
typestringnoAn issue type: Task when unset. An internal task takes a type of the account’s routing map. 1 to 100 characters.
priorityhighest, high, medium, low, lowestno
trackerworkspace, internalnoworkspace (the default) files where the workspace files new tasks (GET /workspaces); internal files a Kadmo task.
bash
curl -X POST https://app.kadmo.ai/api/v1/tasks \
  -H "Authorization: Bearer $KADMO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"workspace":"main","title":"Fix the sign-in redirect"}'
StatusAnswer
201Task. The task, pending.
400Refused: invalid_idempotency_key, invalid_request.
401Refused: unauthorized. With WWW-Authenticate.
402Refused: trial_expired.
404Refused: workspace_not_found.
405Refused: method_not_allowed.
409Refused: idempotency_in_progress, idempotency_key_reused, workspace_archived. With Retry-After.
413Refused: payload_too_large.
415Refused: unsupported_media_type.
422Refused: invalid_issue_type, tracker_not_connected.
429Refused: rate_limited. With Retry-After.
500Refused: internal_error.
502Refused: tracker_error.

Get a task ​

GET /tasks/{key} · getTask

A task of the account’s Tasks, with its status, its playbook and its runs.

ParameterInTypeRequiredMeaning
keypathstringyesThe task’s key, as its tracker or Kadmo gave it.
bash
curl https://app.kadmo.ai/api/v1/tasks/PROJ-123 \
  -H "Authorization: Bearer $KADMO_API_TOKEN"
StatusAnswer
200Task. The task.
401Refused: unauthorized. With WWW-Authenticate.
404Refused: task_not_found.
405Refused: method_not_allowed.
429Refused: rate_limited. With Retry-After.
500Refused: internal_error.

Run a playbook on a task ​

POST /tasks/{key}/runs · runTask

Approve the task with a playbook. The run starts when nothing holds it — the tasks it depends on, its workspace’s pool, a step only a person can do: 201 with the run when it started in the call, 202 with what it waits on when it did not, and it then starts on its own. A task not in Tasks yet is added from its tracker. A run can spend the account’s credit.

ParameterInTypeRequiredMeaning
keypathstringyesThe task’s key, as its tracker or Kadmo gave it.
Idempotency-KeyheaderstringnoOptional. The same key with the same request within 24 hours answers the first answer again and writes nothing. 1 to 255 characters.

The body is a JSON object; a field it does not list is refused.

FieldTypeRequiredMeaning
playbookstringyesThe playbook to run, by slug (GET /playbooks). 1 to 200 characters.
workspacestringnoThe workspace to run in, by slug; unset, the task’s own. 1 to 200 characters.
effortstringnoAn effort tier of the account (low, medium, high, or one of its own); unset, the account’s default.
hintstringnoA note every step’s agent reads. At most 20000 characters.
sync_statusbooleannoMove the ticket’s status in its tracker as the run goes; unset, the playbook’s default.
validatebooleannoCheck the delivered work once the run ends; unset, the account’s default.
bash
curl -X POST https://app.kadmo.ai/api/v1/tasks/PROJ-123/runs \
  -H "Authorization: Bearer $KADMO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"playbook":"bug-fix"}'
StatusAnswer
201TaskRunResult. The run started.
202TaskRunResult. The task is approved; the run starts once what it waits on clears.
400Refused: invalid_idempotency_key, invalid_request.
401Refused: unauthorized. With WWW-Authenticate.
402Refused: trial_expired.
404Refused: playbook_not_found, task_not_found, workspace_not_found.
405Refused: method_not_allowed.
409Refused: idempotency_in_progress, idempotency_key_reused, run_active, workspace_archived. With Retry-After.
413Refused: payload_too_large.
415Refused: unsupported_media_type.
422Refused: playbook_not_runnable, tracker_not_connected.
429Refused: rate_limited. With Retry-After.
500Refused: internal_error.
502Refused: orchestrator_error, tracker_error.

Webhooks ​

List subscriptions ​

GET /webhooks · listWebhooks

The token’s member’s subscriptions, newest first, without their secrets.

bash
curl https://app.kadmo.ai/api/v1/webhooks \
  -H "Authorization: Bearer $KADMO_API_TOKEN"
StatusAnswer
200WebhookList. The subscriptions.
401Refused: unauthorized. With WWW-Authenticate.
405Refused: method_not_allowed.
429Refused: rate_limited. With Retry-After.
500Refused: internal_error.

Subscribe a URL to events ​

POST /webhooks · createWebhook

Make a subscription of the token’s member: each event it lists is POSTed to the URL, signed with the subscription’s secret, and retried for 24 hours when the endpoint fails. The answer carries the secret, this once.

ParameterInTypeRequiredMeaning
Idempotency-KeyheaderstringnoOptional. The same key with the same request within 24 hours answers the first answer again and writes nothing. 1 to 255 characters.

The body is a JSON object; a field it does not list is refused.

FieldTypeRequiredMeaning
urlstringyesThe https URL to POST each event to. Every address its host resolves to must be public. 1 to 2000 characters.
eventsarray of job.finished, job.needs_input, task.doneyesThe events to deliver: at least one.
workspacestringnoOnly this workspace’s events, by slug (GET /workspaces); unset, every workspace’s. 1 to 200 characters.
bash
curl -X POST https://app.kadmo.ai/api/v1/webhooks \
  -H "Authorization: Bearer $KADMO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"url":"https://hooks.example.com/kadmo","events":["job.finished","job.needs_input"]}'
StatusAnswer
201WebhookCreated. The subscription, with its secret. With Location.
400Refused: invalid_idempotency_key, invalid_request.
401Refused: unauthorized. With WWW-Authenticate.
402Refused: trial_expired.
404Refused: workspace_not_found.
405Refused: method_not_allowed.
409Refused: idempotency_in_progress, idempotency_key_reused, webhook_limit_reached, workspace_archived. With Retry-After.
413Refused: payload_too_large.
415Refused: unsupported_media_type.
422Refused: invalid_webhook_url.
429Refused: rate_limited. With Retry-After.
500Refused: internal_error.
503Refused: webhook_check_unavailable.

Unsubscribe ​

DELETE /webhooks/{id} · deleteWebhook

Delete one of the token’s member’s subscriptions: nothing more is delivered to it, the deliveries still waiting included.

ParameterInTypeRequiredMeaning
idpathintegeryesThe subscription’s id.
bash
curl -X DELETE https://app.kadmo.ai/api/v1/webhooks/9001 \
  -H "Authorization: Bearer $KADMO_API_TOKEN"
StatusAnswer
200WebhookDeleted. The subscription is deleted.
401Refused: unauthorized. With WWW-Authenticate.
404Refused: webhook_not_found.
405Refused: method_not_allowed.
429Refused: rate_limited. With Retry-After.
500Refused: internal_error.

Catalog ​

List workspaces ​

GET /workspaces · listWorkspaces

The account’s active workspaces: what workspace names in a call, and where each files a new task.

bash
curl https://app.kadmo.ai/api/v1/workspaces \
  -H "Authorization: Bearer $KADMO_API_TOKEN"
StatusAnswer
200WorkspaceList. The workspaces.
401Refused: unauthorized. With WWW-Authenticate.
405Refused: method_not_allowed.
429Refused: rate_limited. With Retry-After.
500Refused: internal_error.

List workflows ​

GET /workflows · listWorkflows

The workflows a dispatch can name — the enabled ones — with the inputs each reads.

bash
curl https://app.kadmo.ai/api/v1/workflows \
  -H "Authorization: Bearer $KADMO_API_TOKEN"
StatusAnswer
200WorkflowList. The workflows.
401Refused: unauthorized. With WWW-Authenticate.
405Refused: method_not_allowed.
429Refused: rate_limited. With Retry-After.
500Refused: internal_error.

List playbooks ​

GET /playbooks · listPlaybooks

The playbooks a run can name — the enabled ones — with their steps.

bash
curl https://app.kadmo.ai/api/v1/playbooks \
  -H "Authorization: Bearer $KADMO_API_TOKEN"
StatusAnswer
200PlaybookList. The playbooks.
401Refused: unauthorized. With WWW-Authenticate.
405Refused: method_not_allowed.
429Refused: rate_limited. With Retry-After.
500Refused: internal_error.

Objects ​

What the operations answer. A field may be added to an object later, so a client should accept fields it does not know.

Me ​

FieldTypeMeaning
userobjectThe member the token belongs to and acts as.
user.idinteger
user.namestring
user.emailstring
accountobjectThe member’s account: everything the token reads and starts is in it.
account.idinteger
account.namestring
account.slugstring
roleadmin, memberThe member’s role in the account.
tokenobjectThe token this call presented — its name as the member gave it.
token.idinteger
token.namestring

Job ​

FieldTypeMeaning
idintegerThe job’s id: given when it is dispatched, kept for its whole life.
statusqueued, running, needs_input, succeeded, failed, cancelledqueued until an agent takes it; needs_input while it waits on a person; the last three are its end.
workflowstringThe workflow it runs, by name.
workspaceobject or nullThe workspace the job belongs to.
workspace.slugstring
workspace.namestring
taskobject or nullThe task it works on, when it names one.
task.keystring
task.urlstring or nullAn absolute link.
inputobject of stringsThe workflow’s inputs it was dispatched with.
created_byobject or nullThe member who dispatched it.
created_by.idinteger
created_by.namestring
agentobject or nullThe agent that took it; null while queued.
agent.idinteger
agent.namestring
runobject or nullThe playbook run the job is a step of.
run.idinteger
run.statusrunning, waiting, paused, finished, failed, cancelledpaused waits on a person (an approval or a fork to pick); finished carries its outcome.
run.outcomeresolved, no_action, escalated, rework or nullHow a finished run ended; null until then.
run.step_indexintegerThe step the run is on, from 0.
run.playbookobject
run.playbook.slugstring
run.playbook.namestring
run.urlstringAn absolute link.
needs_inputobject or nullWhile needs_input: an approval a gate waits on, or a question of the agent — the oldest one open. Answer it in the app.
needs_input.reasonapproval, question
needs_input.questionstringWhat the person is asked: the agent’s question, plan or request, or that a gate waits for approval.
needs_input.optionsarray of stringsThe answers the agent offered, when it offered some.
needs_input.asked_atstring or nullWhen it was asked.
needs_input.urlstringWhere it is answered: the job’s page in the app.
resultobject or nullWhat the agent reported, once it has; null before.
result.verdictstring
result.summarystring
result.pull_requestsarray of objects
result.pull_requests[].urlstringAn absolute link.
result.pull_requests[].numberinteger or null
result.pull_requests[].repositorystring
result.evidencearray of objects
result.evidence[].labelstring
result.evidence[].urlstringAn absolute link.
filesarray of objectsThe files the job published, in the order they arrived; empty before the first.
files[].idintegerThe file’s id in the app.
files[].namestringIts file name.
files[].urlstringIts page in the app, behind sign-in.
errorstring or nullWhy it failed or was cancelled, when something recorded why.
app_job_idinteger or nullThe app’s job number, once an agent took it.
urlstringThe job in the app: its page once an agent took it, the queue before.
created_atstringAn instant, ISO 8601 in UTC.
started_atstring or nullAn instant, ISO 8601 in UTC.
finished_atstring or nullAn instant, ISO 8601 in UTC.

JobList ​

FieldTypeMeaning
dataarray of JobNewest first.
has_moreboolean
next_cursorstring or nullPass as cursor for the next page; null on the last.

Workspace ​

FieldTypeMeaning
slugstringWhat workspace names in a call.
namestring
new_tasksobjectWhere a task created in the workspace is filed.
new_tasks.trackerinternal, jira, linear, notion
new_tasks.projectstring or nullThe tracker’s project or team; null for internal.

WorkspaceList ​

FieldTypeMeaning
dataarray of Workspace

Workflow ​

FieldTypeMeaning
namestringWhat workflow names in a dispatch.
descriptionstring
parametersarray of objectsThe inputs it reads, as keys of a dispatch’s input.
parameters[].namestring
parameters[].requiredbooleanFalse when the workflow has a default for it.
parameters[].defaultstring or null

WorkflowList ​

FieldTypeMeaning
dataarray of Workflow

Playbook ​

FieldTypeMeaning
slugstringWhat playbook names in a run.
namestring
descriptionstring
stepsarray of objects
steps[].rolestring or null
steps[].workflowstring or null

PlaybookList ​

FieldTypeMeaning
dataarray of Playbook

TaskRun ​

A playbook run on the task.

FieldTypeMeaning
idinteger
statusrunning, waiting, paused, finished, failed, cancelledpaused waits on a person (an approval or a fork to pick); finished carries its outcome.
outcomeresolved, no_action, escalated, rework or nullHow a finished run ended; null until then.
step_indexintegerThe step the run is on, from 0.
playbookobject
playbook.slugstring
playbook.namestring
urlstringAn absolute link.
created_atstringAn instant, ISO 8601 in UTC.
finished_atstring or nullAn instant, ISO 8601 in UTC.

Task ​

FieldTypeMeaning
keystringThe task’s key, as its tracker names it: what {key} is in a path.
idintegerThe task’s id in Kadmo.
titlestring
typestringIts issue type: Task, Bug, Story …
statuspending, waiting, running, paused, done, failed, cancelledpending awaits an approval; waiting is approved and waits on a blocker or a pool slot; the last three are its end.
in_poolbooleanFalse once the task was archived from Tasks.
trackerinternal, jira, linear, notionWhere the ticket lives: internal is Kadmo’s own.
workspaceobject or nullThe workspace the task belongs to; null while none is known.
workspace.slugstring
workspace.namestring
priorityhighest, high, medium, low, lowest or null
playbookobject or nullThe playbook a run of it starts; null until one is chosen.
playbook.slugstring
playbook.namestring
runTaskRun or nullThe run the task is bound to now; null while none is.
runsarray of TaskRunIts runs, newest first, at most 20.
urlstring or nullThe task’s page in the app for an internal task, else its tracker’s.
created_atstringAn instant, ISO 8601 in UTC.
updated_atstringAn instant, ISO 8601 in UTC.

TaskRunResult ​

FieldTypeMeaning
taskTask
runTaskRun or nullThe run that started; null while it waits.
waiting_onobject or nullWhat the start waits on; null once the run started.
waiting_on.reasonblocked_by, pool_full, person_step, blocker_failed, role_not_runnable, retryingblocked_by: tasks it depends on are not done; pool_full: its workspace runs as many playbooks as it may; person_step: a step only a person can do comes first; blocker_failed: a task it depends on failed or was cancelled; role_not_runnable: no agent of the account can run a step’s role; retrying: the start failed and is retried.
waiting_on.blockersarray of stringsThe keys it waits on, for blocked_by and blocker_failed.
waiting_on.messagestring or null

Webhook ​

FieldTypeMeaning
idintegerThe subscription’s id: what DELETE /webhooks/{id} names.
urlstringThe https URL each event is POSTed to.
eventsarray of job.finished, job.needs_input, task.doneThe events it takes.
workspaceobject or nullThe one workspace whose events it takes; null for every workspace.
workspace.slugstring
workspace.namestring
statusactive, disableddisabled receives nothing until it is enabled again on the Integrations page.
disabled_reasonfailing, gone or nullWhy it was disabled: failing — its endpoint failed every delivery for 24 hours; gone — its endpoint answered 410. Null while active.
created_byobjectThe member who made it: it is theirs, and goes when they leave the account.
created_by.idinteger
created_by.namestring
created_atstringAn instant, ISO 8601 in UTC.
last_delivery_atstring or nullWhen its endpoint last took a delivery; null before the first.

WebhookCreated ​

FieldTypeMeaning
idintegerThe subscription’s id: what DELETE /webhooks/{id} names.
urlstringThe https URL each event is POSTed to.
eventsarray of job.finished, job.needs_input, task.doneThe events it takes.
workspaceobject or nullThe one workspace whose events it takes; null for every workspace.
workspace.slugstring
workspace.namestring
statusactive, disableddisabled receives nothing until it is enabled again on the Integrations page.
disabled_reasonfailing, gone or nullWhy it was disabled: failing — its endpoint failed every delivery for 24 hours; gone — its endpoint answered 410. Null while active.
created_byobjectThe member who made it: it is theirs, and goes when they leave the account.
created_by.idinteger
created_by.namestring
created_atstringAn instant, ISO 8601 in UTC.
last_delivery_atstring or nullWhen its endpoint last took a delivery; null before the first.
secretstringThe secret every delivery is signed with (Kadmo-Signature). Shown this once: keep it where the receiver reads it.

WebhookList ​

FieldTypeMeaning
dataarray of WebhookNewest first.

WebhookDeleted ​

FieldTypeMeaning
idinteger
deletedboolean

WebhookEvent ​

FieldTypeMeaning
idintegerThe delivery’s id: the same on every retry of it, so a receiver drops a repeat by it.
typejob.finished, job.needs_input, task.done, pingThe event; ping is a test delivery sent from the Integrations page.
api_versionstringThe payload’s version: fields are added to it, never renamed or removed.
created_atstringWhen the payload was composed, before its first attempt.
webhook_idintegerThe subscription it was delivered to.
dataobjectThe object the event is about; empty for a ping.
data.jobJobFor job.finished and job.needs_input: the job, as GET /jobs/{id} answers it.
data.taskTaskFor task.done: the task, as GET /tasks/{key} answers it.

Error ​

FieldTypeMeaning
errorstringWhat went wrong, as a sentence for a person.
codeinvalid_request, invalid_idempotency_key, workspace_required, unauthorized, trial_expired, no_credit, budget_reached, not_found, job_not_found, workspace_not_found, workflow_not_found, task_not_found, playbook_not_found, webhook_not_found, method_not_allowed, idempotency_key_reused, idempotency_in_progress, duplicate_job, workspace_archived, run_active, webhook_limit_reached, payload_too_large, unsupported_media_type, role_not_runnable, role_not_enabled, model_not_in_plan, workflow_not_runnable, playbook_not_runnable, invalid_issue_type, tracker_not_connected, invalid_webhook_url, rate_limited, daily_cap_reached, internal_error, tracker_error, orchestrator_error, authorisation_unavailable, webhook_check_unavailableWhat a client branches on: stable, one per kind of refusal.
detailsarray of objectsFor invalid_request: each field refused, by its path in the body.
details[].pathstring
details[].messagestring
issue_typesarray of stringsFor invalid_issue_type: the types the account files.
ticket_keystringFor a tracker_error or an orchestrator_error after the ticket was filed or the run created: its key. A retry with the same Idempotency-Key answers this again.
runTaskRunFor run_active: the run that drives the task. For orchestrator_error: the run that did not start.
rolestringFor role_not_runnable: the role no agent of the account can run.