Skip to content
Open the app

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:

bash
curl https://app.kadmo.ai/api/v1/me \
  -H "Authorization: Bearer $KADMO_API_TOKEN"
json
{
  "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.

RuleWhat it means
Only an API tokenThe 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 APIAn API token opens nothing else: the MCP server, the app's own pages and Kadmo Git refuse it.
It acts as youA 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 refusalA 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 cacheA 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": "…" }. error is a sentence for a person. code is what a client branches on. Some refusals carry a field more, named under Error.
  • A fault in Kadmo is 500 with code internal_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.

StatusCodeWhen
400invalid_requestThe 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.
400invalid_idempotency_keyIdempotency-Key is not 1 to 255 visible ASCII characters.
400workspace_requiredNo workspace was found for the work.
401unauthorizedSee Authenticate.
402trial_expiredA write on an account whose trial has ended. See An ended trial.
402no_credit, budget_reachedThe account's credit, or a budget that covers the work, has nothing left. See Models and credit.
404not_foundNo such route, or a path parameter that names nothing.
404job_not_found, task_not_found, workspace_not_found, workflow_not_found, playbook_not_found, webhook_not_foundThe 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.
405method_not_allowedThe route does not take the method. Allow names the ones it does.
409idempotency_key_reused, idempotency_in_progressSee Idempotency.
409duplicate_jobThe same workflow is already queued or running for the same task.
409workspace_archivedThe workspace is archived.
409run_activeA run already drives the task. run is that run, and nothing was written.
409webhook_limit_reachedYou hold 100 webhook subscriptions already.
413payload_too_largeThe body is over 512 KB.
415unsupported_media_typeA write's body is not application/json.
422role_not_runnableNo agent of the account can run the workflow's role. role names it.
422role_not_enabledThe account does not enable the workflow's role.
422model_not_in_planThe work's model is not one the account's plan allows. See What your plan decides.
422workflow_not_runnable, playbook_not_runnableThe workflow or the playbook has no steps.
422invalid_issue_typeA new task's type is not one the account files there. issue_types lists the ones it does.
422invalid_webhook_urlA webhook's URL is not https, or its host is not public. See Subscribe.
422tracker_not_connectedThe workspace files tasks in a tracker the account has not connected, or names no project there.
429rate_limitedSee Rate limits.
429daily_cap_reachedThe account's daily usage cap is reached. Retry-After counts to its reset at midnight UTC.
500internal_errorA fault in Kadmo.
502tracker_errorThe tracker refused or failed. If the ticket was filed first, ticket_key names it.
502orchestrator_errorA run was created for the task but would not start. ticket_key and run name them.
503authorisation_unavailableThe work could not be priced just now. Retry later.
503webhook_check_unavailableA 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.

LimitCalls a minuteAt once
Per API token12040
Per account600120

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 sendKadmo answers
A new keyIt runs the call and keeps its answer.
The same key and the same requestThe kept answer again, with Idempotent-Replayed: true. Nothing is written.
The same key and another request409 idempotency_key_reused.
The same key while the first call still runs409 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.

  • input is the workflow's parameters, string to string. GET /workflows lists each workflow's parameters, and which of them are required. A ticket_url names the job's task.
  • The keys Kadmo reads for itself are refused in input: recording, allow_duplicate, goal_url, role and skip. A job started over the API is never pinned to one agent and never recorded.
  • effort names 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 ​

StatusMeans
queuedNo agent has taken it yet.
runningAn agent works on it.
needs_inputIt 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, cancelledIt 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 409 run_active.
  • workspace replaces 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 seeWhyWhat to do
401 unauthorized on every callThe header is missing or malformed, the token was revoked or mistyped, or it is not an API tokenSend 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 tokenAn API token opens only the APIConnect the MCP client with OAuth or a personal MCP token: see MCP server.
402 trial_expiredThe trial has endedReads still work. See An ended trial.
409 idempotency_key_reusedA key was reused for a different requestSend a new key for each new request, and the same key only for a retry.
429 rate_limitedToo many calls in a short timeWait 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 appIt is in another account, or the workflow or playbook is disabledCheck the token's account with GET /me, and the names with GET /workspaces, GET /workflows and GET /playbooks.