API
Kadmo's API at https://app.kadmo.ai/api/v1 lets an automation platform such as n8n, Zapier, Pipedream, Make or Power Automate (through Kadmo's connector), or a script of your own, start and follow work in your account over plain HTTP. It dispatches a job, creates a task and runs a playbook on it, and reads jobs and tasks back. It also lists the workspaces, workflows and playbooks a call can name, and subscribes a URL to webhooks, which Kadmo calls when a job finishes, a job needs a person or a task is done. It answers an API token and nothing else.
This page covers what every call shares: the token, the answers and errors, the limits, idempotency and what a version promises. Every operation, with its parameters and a call to copy, is on API reference. Creating a token is on API tokens.
How a call reaches your account
The API is for servers. It sends no cross-origin headers, except on its OpenAPI document, so a web page cannot call it from a visitor's browser.
Authenticate
Send the token in the Authorization header of every call:
curl https://app.kadmo.ai/api/v1/me \
-H "Authorization: Bearer $KADMO_API_TOKEN"{
"user": { "id": 12, "name": "Ada", "email": "ada@example.com" },
"account": { "id": 3, "name": "Example", "slug": "example" },
"role": "member",
"token": { "id": 41, "name": "n8n" }
}GET /me answers who the token is. It is the cheap call to test a credential.
| Rule | What it means |
|---|---|
| Only an API token | The API answers an API token (kadmo_api_ followed by a secret) and nothing else. A signed-in browser session, an MCP client's sign-in, a personal MCP token and a Kadmo Git token all get 401 here. |
| Only the API | An API token opens nothing else: the MCP server, the app's own pages and Kadmo Git refuse it. |
| It acts as you | A call does what its member may do in the app, with the member's role, on the member's account. Nothing a token reads or starts is outside that account. |
| One refusal | A missing, unknown or revoked token gets 401 with code unauthorized and WWW-Authenticate: Bearer. So does a token whose member was removed or whose account is blocked. |
| No cache | A revoked token fails on its very next call. |
Answers
- Every answer is JSON, and none is cached.
- Ids are numbers. Every link in an answer is an absolute address in the app, such as a job's page.
- A refusal is
{ "error": "…", "code": "…" }.erroris a sentence for a person.codeis what a client branches on. Some refusals carry a field more, named under Error. - A fault in Kadmo is
500withcodeinternal_error. Its cause is logged, never answered.
Errors
The codes are a closed list. A code may be added, but it is never renamed or moved to another status. The reference lists which codes each operation can answer.
| Status | Code | When |
|---|---|---|
| 400 | invalid_request | The body is not a JSON object, or not the operation's fields. details names each field refused, an unknown one by name. A query parameter of the wrong kind is also named. |
| 400 | invalid_idempotency_key | Idempotency-Key is not 1 to 255 visible ASCII characters. |
| 400 | workspace_required | No workspace was found for the work. |
| 401 | unauthorized | See Authenticate. |
| 402 | trial_expired | A write on an account whose trial has ended. See An ended trial. |
| 402 | no_credit, budget_reached | The account's credit, or a budget that covers the work, has nothing left. See Models and credit. |
| 404 | not_found | No such route, or a path parameter that names nothing. |
| 404 | job_not_found, task_not_found, workspace_not_found, workflow_not_found, playbook_not_found, webhook_not_found | The id, key, slug or name is not your account's, or the webhook subscription is not yours. Another account's answers exactly like a missing one, and a disabled workflow or playbook is not found. |
| 405 | method_not_allowed | The route does not take the method. Allow names the ones it does. |
| 409 | idempotency_key_reused, idempotency_in_progress | See Idempotency. |
| 409 | duplicate_job | The same workflow is already queued or running for the same task. |
| 409 | workspace_archived | The workspace is archived. |
| 409 | run_active | A run already drives the task. run is that run, and nothing was written. |
| 409 | webhook_limit_reached | You hold 100 webhook subscriptions already. |
| 413 | payload_too_large | The body is over 512 KB. |
| 415 | unsupported_media_type | A write's body is not application/json. |
| 422 | role_not_runnable | No agent of the account can run the workflow's role. role names it. |
| 422 | role_not_enabled | The account does not enable the workflow's role. |
| 422 | model_not_in_plan | The work's model is not one the account's plan allows. See What your plan decides. |
| 422 | workflow_not_runnable, playbook_not_runnable | The workflow or the playbook has no steps. |
| 422 | invalid_issue_type | A new task's type is not one the account files there. issue_types lists the ones it does. |
| 422 | invalid_webhook_url | A webhook's URL is not https, or its host is not public. See Subscribe. |
| 422 | tracker_not_connected | The workspace files tasks in a tracker the account has not connected, or names no project there. |
| 429 | rate_limited | See Rate limits. |
| 429 | daily_cap_reached | The account's daily usage cap is reached. Retry-After counts to its reset at midnight UTC. |
| 500 | internal_error | A fault in Kadmo. |
| 502 | tracker_error | The tracker refused or failed. If the ticket was filed first, ticket_key names it. |
| 502 | orchestrator_error | A run was created for the task but would not start. ticket_key and run name them. |
| 503 | authorisation_unavailable | The work could not be priced just now. Retry later. |
| 503 | webhook_check_unavailable | A webhook's host could not be looked up just now. Retry after Retry-After. |
Rate limits
Each call counts against two limits: its token's and its account's, which every API token of the account shares.
| Limit | Calls a minute | At once |
|---|---|---|
| Per API token | 120 | 40 |
| Per account | 600 | 120 |
A limit refills continuously, and a short burst may use the "at once" allowance. A call over either limit gets 429 with code rate_limited and Retry-After in whole seconds. It is refused before anything is read or written, and it does not count against either limit. Wait the seconds Retry-After names, then retry.
Idempotency
Every POST takes an optional Idempotency-Key header: any 1 to 255 visible ASCII characters, such as a UUID. Send one, and a retry after a timeout or a dropped connection cannot start the same work twice. A key belongs to its token and is kept for 24 hours.
| You send | Kadmo answers |
|---|---|
| A new key | It runs the call and keeps its answer. |
| The same key and the same request | The kept answer again, with Idempotent-Replayed: true. Nothing is written. |
| The same key and another request | 409 idempotency_key_reused. |
| The same key while the first call still runs | 409 idempotency_in_progress with Retry-After: 1. |
Kadmo keeps every answer below 500 except a 429. It also keeps a 502 that came after something was written: a tracker_error after the ticket was filed, or an orchestrator_error after the run was created. Its retry answers the same 502 with the same ticket_key, so it never files a second ticket. A 500 that came after the job was queued, the ticket was filed or the task was approved is kept the same way. Any other 429 or 5xx frees the key, and a retry runs the call again.
Jobs
A job is one workflow run by one of your agents. POST /jobs names the workflow, the workspace it runs in and its input. It then goes through the same checks a dispatch meets in the app: the trial, the daily cap, the credit and budgets, the roles, and the guard against the same work twice. Each refusal answers its own code. A job can spend the account's credit.
inputis the workflow's parameters, string to string.GET /workflowslists each workflow's parameters, and which of them are required. Aticket_urlnames the job's task.- The keys Kadmo reads for itself are refused in
input:recording,allow_duplicate,goal_url,roleandskip. A job started over the API is never pinned to one agent and never recorded. effortnames an effort tier. Unset, the workflow's default applies.
A job's id
A job's id is given when it is dispatched. It stays the same from queued to the end, also for a dispatch that ends before an agent takes it. Once an agent takes the job, the app's own job number joins the answer as app_job_id, and url moves from the queue to the job's page in the app.
Its status
| Status | Means |
|---|---|
queued | No agent has taken it yet. |
running | An agent works on it. |
needs_input | It waits on a person: needs_input.reason is approval (a gate) or question (the agent asks), with the question, the options the agent offered, asked_at and the url of the job's page, where it is answered. |
succeeded, failed, cancelled | It ended. result holds the agent's report and the pull requests it reported; error holds why it failed or was cancelled, when something recorded why. |
Read a job with GET /jobs/{id} until its status is one of the last three, or subscribe to job.finished and job.needs_input and be told (Webhooks). GET /jobs lists the account's jobs newest first, a page at a time. Pass next_cursor as cursor for the next page. A page never repeats or skips a job while new ones arrive. status=finished stands for the three ends.
Tasks
A task is a ticket in your account's Tasks.
Creating a task. POST /tasks files the ticket where the Tasks page's Create files it. With tracker workspace, the default, it goes to the workspace's bound project in a connected tracker, or becomes an internal task when the workspace has none. With tracker internal, it is always an internal task. GET /workspaces says where each workspace files (new_tasks). Routing is explained on Tracker routing. The ticket's type is Task when unset. An internal task's type must be one of the account's delivery types. The new task joins Tasks as pending and does not start.
Running a playbook on a task. POST /tasks/{key}/runs approves the task with a playbook and hands it to Tasks, which starts it as it starts any approved task: after the tasks it depends on, when its workspace has a free slot, and after a step only a person can do. The call answers 201 with the run when it started at once. Otherwise it answers 202 with waiting_on, and the run then starts on its own. Read the task with GET /tasks/{key} to follow it.
- A key not in Tasks yet is read from its tracker and added first. A finished task goes back to the pool.
- A run already driving the task is
409run_active. workspacereplaces the task's own workspace for this run.- The run's activity in the app names the token: by Ada via API token n8n.
An ended trial
When the account's trial has ended, the API still reads but no longer starts or changes work: every POST gets 402 with code trial_expired until the account has a plan. Deleting a webhook subscription still works, and the subscriptions keep receiving. What else an ended trial allows is on The trial.
Versions
/api/v1 changes by addition only: new operations, new fields in an answer, new codes. A field is never renamed or removed, a code never renamed or given another status, and a status list such as a job's never loses a value. Write a client that ignores a field it does not know. A change that would break a client is a new path, /api/v2.
The OpenAPI document
The API is described by an OpenAPI 3.1 document. The app serves it at https://app.kadmo.ai/api/v1/openapi.json, without a token, and this site carries a copy at /openapi/kadmo-api-v1.json. A tool that generates a client, or tests calls against the API, reads either. The API reference is generated from it.
Troubleshooting
| You see | Why | What to do |
|---|---|---|
401 unauthorized on every call | The header is missing or malformed, the token was revoked or mistyped, or it is not an API token | Send Authorization: Bearer and the token. A personal MCP token or a Kadmo Git token does not open the API: create an API token. |
401 on the MCP server with an API token | An API token opens only the API | Connect the MCP client with OAuth or a personal MCP token: see MCP server. |
402 trial_expired | The trial has ended | Reads still work. See An ended trial. |
409 idempotency_key_reused | A key was reused for a different request | Send a new key for each new request, and the same key only for a retry. |
429 rate_limited | Too many calls in a short time | Wait Retry-After seconds. Spread polling out: one read of a job every few seconds is plenty. |
404 for a job, task, workspace or workflow you can see in the app | It is in another account, or the workflow or playbook is disabled | Check the token's account with GET /me, and the names with GET /workspaces, GET /workflows and GET /playbooks. |