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
| Operation | Call | Does |
|---|---|---|
| Who the token is | GET /me | The member the token acts as, their account and role, and the token itself. A cheap call to test a credential. |
| List recent jobs | GET /jobs | The account’s jobs, newest first, a page at a time. |
| Dispatch a job | POST /jobs | 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. |
| Get a job | GET /jobs/{id} | The job with its status, its agent, its playbook run, what it waits on and, once finished, its result. |
| Create a task | POST /tasks | 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. |
| Get a task | GET /tasks/{key} | A task of the account’s Tasks, with its status, its playbook and its runs. |
| Run a playbook on a task | POST /tasks/{key}/runs | 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. |
| List subscriptions | GET /webhooks | The token’s member’s subscriptions, newest first, without their secrets. |
| Subscribe a URL to events | POST /webhooks | 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. |
| Unsubscribe | DELETE /webhooks/{id} | Delete one of the token’s member’s subscriptions: nothing more is delivered to it, the deliveries still waiting included. |
| List workspaces | GET /workspaces | The account’s active workspaces: what workspace names in a call, and where each files a new task. |
| List workflows | GET /workflows | The workflows a dispatch can name — the enabled ones — with the inputs each reads. |
| List playbooks | GET /playbooks | The 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.
curl https://app.kadmo.ai/api/v1/me \
-H "Authorization: Bearer $KADMO_API_TOKEN"| Status | Answer |
|---|---|
| 200 | Me. The token’s member and account. |
| 401 | Refused: unauthorized. With WWW-Authenticate. |
| 405 | Refused: method_not_allowed. |
| 429 | Refused: rate_limited. With Retry-After. |
| 500 | Refused: internal_error. |
Jobs
List recent jobs
GET /jobs · listJobs
The account’s jobs, newest first, a page at a time.
| Parameter | In | Type | Required | Meaning |
|---|---|---|---|---|
status | query | string | no | Comma-separated: queued, running, needs_input, succeeded, failed, cancelled, or finished for the last three. |
workspace | query | string | no | A workspace’s slug. At most 200 characters. |
workflow | query | string | no | A workflow’s name. At most 200 characters. |
task | query | string | no | A task’s key. At most 200 characters. |
app_job_id | query | integer | no | The app’s job number. |
limit | query | integer | no | At most this many, 1 to 100; 20 when unset. |
cursor | query | string | no | The next_cursor of the previous page. At most 40 characters. |
curl https://app.kadmo.ai/api/v1/jobs \
-H "Authorization: Bearer $KADMO_API_TOKEN"| Status | Answer |
|---|---|
| 200 | JobList. A page of jobs. |
| 400 | Refused: invalid_request. |
| 401 | Refused: unauthorized. With WWW-Authenticate. |
| 405 | Refused: method_not_allowed. |
| 429 | Refused: rate_limited. With Retry-After. |
| 500 | Refused: 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.
| Parameter | In | Type | Required | Meaning |
|---|---|---|---|---|
Idempotency-Key | header | string | no | Optional. 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.
| Field | Type | Required | Meaning |
|---|---|---|---|
workflow | string | yes | The workflow to run, by name (GET /workflows). 1 to 200 characters. |
workspace | string | yes | The workspace it runs in, by slug (GET /workspaces). 1 to 200 characters. |
input | object of strings | no | The workflow’s inputs, by name: ticket_url and hint among them when it reads them. |
effort | string | no | An effort tier of the account (low, medium, high, or one of its own); unset, the workflow’s default. |
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"}}'| Status | Answer |
|---|---|
| 201 | Job. The job, queued. |
| 400 | Refused: invalid_idempotency_key, invalid_request. |
| 401 | Refused: unauthorized. With WWW-Authenticate. |
| 402 | Refused: budget_reached, no_credit, trial_expired. |
| 404 | Refused: workflow_not_found, workspace_not_found. |
| 405 | Refused: method_not_allowed. |
| 409 | Refused: duplicate_job, idempotency_in_progress, idempotency_key_reused, workspace_archived. With Retry-After. |
| 413 | Refused: payload_too_large. |
| 415 | Refused: unsupported_media_type. |
| 422 | Refused: model_not_in_plan, role_not_enabled, role_not_runnable, workflow_not_runnable. |
| 429 | Refused: daily_cap_reached, rate_limited. With Retry-After. |
| 500 | Refused: internal_error. |
| 503 | Refused: 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.
| Parameter | In | Type | Required | Meaning |
|---|---|---|---|---|
id | path | integer | yes | The job’s id. |
curl https://app.kadmo.ai/api/v1/jobs/9001 \
-H "Authorization: Bearer $KADMO_API_TOKEN"| Status | Answer |
|---|---|
| 200 | Job. The job. |
| 401 | Refused: unauthorized. With WWW-Authenticate. |
| 404 | Refused: job_not_found. |
| 405 | Refused: method_not_allowed. |
| 429 | Refused: rate_limited. With Retry-After. |
| 500 | Refused: 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.
| Parameter | In | Type | Required | Meaning |
|---|---|---|---|---|
Idempotency-Key | header | string | no | Optional. 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.
| Field | Type | Required | Meaning |
|---|---|---|---|
workspace | string | yes | The workspace the task belongs to, by slug (GET /workspaces). 1 to 200 characters. |
title | string | yes | The ticket’s title. 1 to 255 characters. |
description | string | no | The ticket’s description, as plain text or Markdown. At most 100000 characters. |
type | string | no | An issue type: Task when unset. An internal task takes a type of the account’s routing map. 1 to 100 characters. |
priority | highest, high, medium, low, lowest | no | |
tracker | workspace, internal | no | workspace (the default) files where the workspace files new tasks (GET /workspaces); internal files a Kadmo task. |
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"}'| Status | Answer |
|---|---|
| 201 | Task. The task, pending. |
| 400 | Refused: invalid_idempotency_key, invalid_request. |
| 401 | Refused: unauthorized. With WWW-Authenticate. |
| 402 | Refused: trial_expired. |
| 404 | Refused: workspace_not_found. |
| 405 | Refused: method_not_allowed. |
| 409 | Refused: idempotency_in_progress, idempotency_key_reused, workspace_archived. With Retry-After. |
| 413 | Refused: payload_too_large. |
| 415 | Refused: unsupported_media_type. |
| 422 | Refused: invalid_issue_type, tracker_not_connected. |
| 429 | Refused: rate_limited. With Retry-After. |
| 500 | Refused: internal_error. |
| 502 | Refused: tracker_error. |
Get a task
GET /tasks/{key} · getTask
A task of the account’s Tasks, with its status, its playbook and its runs.
| Parameter | In | Type | Required | Meaning |
|---|---|---|---|---|
key | path | string | yes | The task’s key, as its tracker or Kadmo gave it. |
curl https://app.kadmo.ai/api/v1/tasks/PROJ-123 \
-H "Authorization: Bearer $KADMO_API_TOKEN"| Status | Answer |
|---|---|
| 200 | Task. The task. |
| 401 | Refused: unauthorized. With WWW-Authenticate. |
| 404 | Refused: task_not_found. |
| 405 | Refused: method_not_allowed. |
| 429 | Refused: rate_limited. With Retry-After. |
| 500 | Refused: 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.
| Parameter | In | Type | Required | Meaning |
|---|---|---|---|---|
key | path | string | yes | The task’s key, as its tracker or Kadmo gave it. |
Idempotency-Key | header | string | no | Optional. 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.
| Field | Type | Required | Meaning |
|---|---|---|---|
playbook | string | yes | The playbook to run, by slug (GET /playbooks). 1 to 200 characters. |
workspace | string | no | The workspace to run in, by slug; unset, the task’s own. 1 to 200 characters. |
effort | string | no | An effort tier of the account (low, medium, high, or one of its own); unset, the account’s default. |
hint | string | no | A note every step’s agent reads. At most 20000 characters. |
sync_status | boolean | no | Move the ticket’s status in its tracker as the run goes; unset, the playbook’s default. |
validate | boolean | no | Check the delivered work once the run ends; unset, the account’s default. |
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"}'| Status | Answer |
|---|---|
| 201 | TaskRunResult. The run started. |
| 202 | TaskRunResult. The task is approved; the run starts once what it waits on clears. |
| 400 | Refused: invalid_idempotency_key, invalid_request. |
| 401 | Refused: unauthorized. With WWW-Authenticate. |
| 402 | Refused: trial_expired. |
| 404 | Refused: playbook_not_found, task_not_found, workspace_not_found. |
| 405 | Refused: method_not_allowed. |
| 409 | Refused: idempotency_in_progress, idempotency_key_reused, run_active, workspace_archived. With Retry-After. |
| 413 | Refused: payload_too_large. |
| 415 | Refused: unsupported_media_type. |
| 422 | Refused: playbook_not_runnable, tracker_not_connected. |
| 429 | Refused: rate_limited. With Retry-After. |
| 500 | Refused: internal_error. |
| 502 | Refused: orchestrator_error, tracker_error. |
Webhooks
List subscriptions
GET /webhooks · listWebhooks
The token’s member’s subscriptions, newest first, without their secrets.
curl https://app.kadmo.ai/api/v1/webhooks \
-H "Authorization: Bearer $KADMO_API_TOKEN"| Status | Answer |
|---|---|
| 200 | WebhookList. The subscriptions. |
| 401 | Refused: unauthorized. With WWW-Authenticate. |
| 405 | Refused: method_not_allowed. |
| 429 | Refused: rate_limited. With Retry-After. |
| 500 | Refused: 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.
| Parameter | In | Type | Required | Meaning |
|---|---|---|---|---|
Idempotency-Key | header | string | no | Optional. 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.
| Field | Type | Required | Meaning |
|---|---|---|---|
url | string | yes | The https URL to POST each event to. Every address its host resolves to must be public. 1 to 2000 characters. |
events | array of job.finished, job.needs_input, task.done | yes | The events to deliver: at least one. |
workspace | string | no | Only this workspace’s events, by slug (GET /workspaces); unset, every workspace’s. 1 to 200 characters. |
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"]}'| Status | Answer |
|---|---|
| 201 | WebhookCreated. The subscription, with its secret. With Location. |
| 400 | Refused: invalid_idempotency_key, invalid_request. |
| 401 | Refused: unauthorized. With WWW-Authenticate. |
| 402 | Refused: trial_expired. |
| 404 | Refused: workspace_not_found. |
| 405 | Refused: method_not_allowed. |
| 409 | Refused: idempotency_in_progress, idempotency_key_reused, webhook_limit_reached, workspace_archived. With Retry-After. |
| 413 | Refused: payload_too_large. |
| 415 | Refused: unsupported_media_type. |
| 422 | Refused: invalid_webhook_url. |
| 429 | Refused: rate_limited. With Retry-After. |
| 500 | Refused: internal_error. |
| 503 | Refused: 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.
| Parameter | In | Type | Required | Meaning |
|---|---|---|---|---|
id | path | integer | yes | The subscription’s id. |
curl -X DELETE https://app.kadmo.ai/api/v1/webhooks/9001 \
-H "Authorization: Bearer $KADMO_API_TOKEN"| Status | Answer |
|---|---|
| 200 | WebhookDeleted. The subscription is deleted. |
| 401 | Refused: unauthorized. With WWW-Authenticate. |
| 404 | Refused: webhook_not_found. |
| 405 | Refused: method_not_allowed. |
| 429 | Refused: rate_limited. With Retry-After. |
| 500 | Refused: 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.
curl https://app.kadmo.ai/api/v1/workspaces \
-H "Authorization: Bearer $KADMO_API_TOKEN"| Status | Answer |
|---|---|
| 200 | WorkspaceList. The workspaces. |
| 401 | Refused: unauthorized. With WWW-Authenticate. |
| 405 | Refused: method_not_allowed. |
| 429 | Refused: rate_limited. With Retry-After. |
| 500 | Refused: internal_error. |
List workflows
GET /workflows · listWorkflows
The workflows a dispatch can name — the enabled ones — with the inputs each reads.
curl https://app.kadmo.ai/api/v1/workflows \
-H "Authorization: Bearer $KADMO_API_TOKEN"| Status | Answer |
|---|---|
| 200 | WorkflowList. The workflows. |
| 401 | Refused: unauthorized. With WWW-Authenticate. |
| 405 | Refused: method_not_allowed. |
| 429 | Refused: rate_limited. With Retry-After. |
| 500 | Refused: internal_error. |
List playbooks
GET /playbooks · listPlaybooks
The playbooks a run can name — the enabled ones — with their steps.
curl https://app.kadmo.ai/api/v1/playbooks \
-H "Authorization: Bearer $KADMO_API_TOKEN"| Status | Answer |
|---|---|
| 200 | PlaybookList. The playbooks. |
| 401 | Refused: unauthorized. With WWW-Authenticate. |
| 405 | Refused: method_not_allowed. |
| 429 | Refused: rate_limited. With Retry-After. |
| 500 | Refused: 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
| Field | Type | Meaning |
|---|---|---|
user | object | The member the token belongs to and acts as. |
user.id | integer | |
user.name | string | |
user.email | string | |
account | object | The member’s account: everything the token reads and starts is in it. |
account.id | integer | |
account.name | string | |
account.slug | string | |
role | admin, member | The member’s role in the account. |
token | object | The token this call presented — its name as the member gave it. |
token.id | integer | |
token.name | string |
Job
| Field | Type | Meaning |
|---|---|---|
id | integer | The job’s id: given when it is dispatched, kept for its whole life. |
status | queued, running, needs_input, succeeded, failed, cancelled | queued until an agent takes it; needs_input while it waits on a person; the last three are its end. |
workflow | string | The workflow it runs, by name. |
workspace | object or null | The workspace the job belongs to. |
workspace.slug | string | |
workspace.name | string | |
task | object or null | The task it works on, when it names one. |
task.key | string | |
task.url | string or null | An absolute link. |
input | object of strings | The workflow’s inputs it was dispatched with. |
created_by | object or null | The member who dispatched it. |
created_by.id | integer | |
created_by.name | string | |
agent | object or null | The agent that took it; null while queued. |
agent.id | integer | |
agent.name | string | |
run | object or null | The playbook run the job is a step of. |
run.id | integer | |
run.status | running, waiting, paused, finished, failed, cancelled | paused waits on a person (an approval or a fork to pick); finished carries its outcome. |
run.outcome | resolved, no_action, escalated, rework or null | How a finished run ended; null until then. |
run.step_index | integer | The step the run is on, from 0. |
run.playbook | object | |
run.playbook.slug | string | |
run.playbook.name | string | |
run.url | string | An absolute link. |
needs_input | object or null | While 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.reason | approval, question | |
needs_input.question | string | What the person is asked: the agent’s question, plan or request, or that a gate waits for approval. |
needs_input.options | array of strings | The answers the agent offered, when it offered some. |
needs_input.asked_at | string or null | When it was asked. |
needs_input.url | string | Where it is answered: the job’s page in the app. |
result | object or null | What the agent reported, once it has; null before. |
result.verdict | string | |
result.summary | string | |
result.pull_requests | array of objects | |
result.pull_requests[].url | string | An absolute link. |
result.pull_requests[].number | integer or null | |
result.pull_requests[].repository | string | |
result.evidence | array of objects | |
result.evidence[].label | string | |
result.evidence[].url | string | An absolute link. |
files | array of objects | The files the job published, in the order they arrived; empty before the first. |
files[].id | integer | The file’s id in the app. |
files[].name | string | Its file name. |
files[].url | string | Its page in the app, behind sign-in. |
error | string or null | Why it failed or was cancelled, when something recorded why. |
app_job_id | integer or null | The app’s job number, once an agent took it. |
url | string | The job in the app: its page once an agent took it, the queue before. |
created_at | string | An instant, ISO 8601 in UTC. |
started_at | string or null | An instant, ISO 8601 in UTC. |
finished_at | string or null | An instant, ISO 8601 in UTC. |
JobList
| Field | Type | Meaning |
|---|---|---|
data | array of Job | Newest first. |
has_more | boolean | |
next_cursor | string or null | Pass as cursor for the next page; null on the last. |
Workspace
| Field | Type | Meaning |
|---|---|---|
slug | string | What workspace names in a call. |
name | string | |
new_tasks | object | Where a task created in the workspace is filed. |
new_tasks.tracker | internal, jira, linear, notion | |
new_tasks.project | string or null | The tracker’s project or team; null for internal. |
WorkspaceList
| Field | Type | Meaning |
|---|---|---|
data | array of Workspace |
Workflow
| Field | Type | Meaning |
|---|---|---|
name | string | What workflow names in a dispatch. |
description | string | |
parameters | array of objects | The inputs it reads, as keys of a dispatch’s input. |
parameters[].name | string | |
parameters[].required | boolean | False when the workflow has a default for it. |
parameters[].default | string or null |
WorkflowList
| Field | Type | Meaning |
|---|---|---|
data | array of Workflow |
Playbook
| Field | Type | Meaning |
|---|---|---|
slug | string | What playbook names in a run. |
name | string | |
description | string | |
steps | array of objects | |
steps[].role | string or null | |
steps[].workflow | string or null |
PlaybookList
| Field | Type | Meaning |
|---|---|---|
data | array of Playbook |
TaskRun
A playbook run on the task.
| Field | Type | Meaning |
|---|---|---|
id | integer | |
status | running, waiting, paused, finished, failed, cancelled | paused waits on a person (an approval or a fork to pick); finished carries its outcome. |
outcome | resolved, no_action, escalated, rework or null | How a finished run ended; null until then. |
step_index | integer | The step the run is on, from 0. |
playbook | object | |
playbook.slug | string | |
playbook.name | string | |
url | string | An absolute link. |
created_at | string | An instant, ISO 8601 in UTC. |
finished_at | string or null | An instant, ISO 8601 in UTC. |
Task
| Field | Type | Meaning |
|---|---|---|
key | string | The task’s key, as its tracker names it: what {key} is in a path. |
id | integer | The task’s id in Kadmo. |
title | string | |
type | string | Its issue type: Task, Bug, Story … |
status | pending, waiting, running, paused, done, failed, cancelled | pending awaits an approval; waiting is approved and waits on a blocker or a pool slot; the last three are its end. |
in_pool | boolean | False once the task was archived from Tasks. |
tracker | internal, jira, linear, notion | Where the ticket lives: internal is Kadmo’s own. |
workspace | object or null | The workspace the task belongs to; null while none is known. |
workspace.slug | string | |
workspace.name | string | |
priority | highest, high, medium, low, lowest or null | |
playbook | object or null | The playbook a run of it starts; null until one is chosen. |
playbook.slug | string | |
playbook.name | string | |
run | TaskRun or null | The run the task is bound to now; null while none is. |
runs | array of TaskRun | Its runs, newest first, at most 20. |
url | string or null | The task’s page in the app for an internal task, else its tracker’s. |
created_at | string | An instant, ISO 8601 in UTC. |
updated_at | string | An instant, ISO 8601 in UTC. |
TaskRunResult
| Field | Type | Meaning |
|---|---|---|
task | Task | |
run | TaskRun or null | The run that started; null while it waits. |
waiting_on | object or null | What the start waits on; null once the run started. |
waiting_on.reason | blocked_by, pool_full, person_step, blocker_failed, role_not_runnable, retrying | blocked_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.blockers | array of strings | The keys it waits on, for blocked_by and blocker_failed. |
waiting_on.message | string or null |
Webhook
| Field | Type | Meaning |
|---|---|---|
id | integer | The subscription’s id: what DELETE /webhooks/{id} names. |
url | string | The https URL each event is POSTed to. |
events | array of job.finished, job.needs_input, task.done | The events it takes. |
workspace | object or null | The one workspace whose events it takes; null for every workspace. |
workspace.slug | string | |
workspace.name | string | |
status | active, disabled | disabled receives nothing until it is enabled again on the Integrations page. |
disabled_reason | failing, gone or null | Why it was disabled: failing — its endpoint failed every delivery for 24 hours; gone — its endpoint answered 410. Null while active. |
created_by | object | The member who made it: it is theirs, and goes when they leave the account. |
created_by.id | integer | |
created_by.name | string | |
created_at | string | An instant, ISO 8601 in UTC. |
last_delivery_at | string or null | When its endpoint last took a delivery; null before the first. |
WebhookCreated
| Field | Type | Meaning |
|---|---|---|
id | integer | The subscription’s id: what DELETE /webhooks/{id} names. |
url | string | The https URL each event is POSTed to. |
events | array of job.finished, job.needs_input, task.done | The events it takes. |
workspace | object or null | The one workspace whose events it takes; null for every workspace. |
workspace.slug | string | |
workspace.name | string | |
status | active, disabled | disabled receives nothing until it is enabled again on the Integrations page. |
disabled_reason | failing, gone or null | Why it was disabled: failing — its endpoint failed every delivery for 24 hours; gone — its endpoint answered 410. Null while active. |
created_by | object | The member who made it: it is theirs, and goes when they leave the account. |
created_by.id | integer | |
created_by.name | string | |
created_at | string | An instant, ISO 8601 in UTC. |
last_delivery_at | string or null | When its endpoint last took a delivery; null before the first. |
secret | string | The secret every delivery is signed with (Kadmo-Signature). Shown this once: keep it where the receiver reads it. |
WebhookList
| Field | Type | Meaning |
|---|---|---|
data | array of Webhook | Newest first. |
WebhookDeleted
| Field | Type | Meaning |
|---|---|---|
id | integer | |
deleted | boolean |
WebhookEvent
| Field | Type | Meaning |
|---|---|---|
id | integer | The delivery’s id: the same on every retry of it, so a receiver drops a repeat by it. |
type | job.finished, job.needs_input, task.done, ping | The event; ping is a test delivery sent from the Integrations page. |
api_version | string | The payload’s version: fields are added to it, never renamed or removed. |
created_at | string | When the payload was composed, before its first attempt. |
webhook_id | integer | The subscription it was delivered to. |
data | object | The object the event is about; empty for a ping. |
data.job | Job | For job.finished and job.needs_input: the job, as GET /jobs/{id} answers it. |
data.task | Task | For task.done: the task, as GET /tasks/{key} answers it. |
Error
| Field | Type | Meaning |
|---|---|---|
error | string | What went wrong, as a sentence for a person. |
code | invalid_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_unavailable | What a client branches on: stable, one per kind of refusal. |
details | array of objects | For invalid_request: each field refused, by its path in the body. |
details[].path | string | |
details[].message | string | |
issue_types | array of strings | For invalid_issue_type: the types the account files. |
ticket_key | string | For 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. |
run | TaskRun | For run_active: the run that drives the task. For orchestrator_error: the run that did not start. |
role | string | For role_not_runnable: the role no agent of the account can run. |