HTTP API

This page is for someone writing a program that drives Cadence over HTTP. If you work with Cadence through an MCP client or the browser, you do not need it. See MCP or Web interface instead.

The HTTP API covers much of what MCP does, though not all of it. Each domain page under Reference says which routes serve a capability, and says so when there is no /api/v1 route for it. This page covers the conventions every route shares.

Base URL

Every route is under /api/v1 on your instance:

https://cadence.example.com/api/v1

Replace https://cadence.example.com with your instance's address.

Authentication

Send a bearer token in the Authorization header of every request:

curl https://cadence.example.com/api/v1/tasks/OPS-42 \
  -H "Authorization: Bearer smc_your_token_here"

For the kinds of token, how to create one, and what your role in a space lets you call, see Authentication.

Requests and responses

Send a request body as JSON, with Content-Type: application/json. Responses are JSON, including most errors. There are three exceptions:

• Downloading an attachment returns the file itself.
• Deleting a property, a dependency, a check, a check rule or a worker version answers 204 No Content with no body.
• Some lease routes, called for a lease that has already ended, answer 410 Gone with no body. The 410 row in the status table below lists which.

Deleting a task's or a doc's attachment is not one of the exceptions. It answers 200 with the attachment it removed:

{ "attachment": { "id": 7, "filename": "notes.txt" } }

curl -X PATCH https://cadence.example.com/api/v1/tasks/OPS-42 \
  -H "Authorization: Bearer smc_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "priority": "P1" }'

Uploading an attachment is the one exception to JSON request bodies. See Task data § Attachments.

Errors

A refused request returns an HTTP error status and, except for 410, a body with an error object. The object carries a code your program can branch on and a message a person can read:

{ "error": { "code": "space_not_found", "message": "Space not found" } }

Some refusals add a key inside the error object:

• A 403 from a role or scope check adds target. See A 403 refusal.

• A 422 with invalid_filter adds details, naming the filter it refused and the value you sent. For priority and gate_status the value is a list of the values refused. For every other filter it is a single value, including stage and stage_group, which take several values but report only the first one that matched nothing. On audit events, sending only one of actor_type and actor_id (or of subject_type and subject_id) puts an object with both under actor (or subject), for example "details": { "actor": { "type": "User", "id": null } }. A list filter looks like this:

  { "error": { "code": "invalid_filter", "message": "invalid priority value", "details": { "priority": ["P9"] } } }

  { "error": { "code": "invalid_filter", "message": "limit out of range", "details": { "limit": "500" } } }

• A 422 with unpermitted_fields adds details with the fields Cadence does not accept on that route, for example "details": { "fields": ["colour"] }.

• A 422 with invalid_request that comes from a field failing validation adds details, which maps each field that failed to its error messages. An invalid_request about the request as a whole, such as a missing stage, has no details.

Two refusals add a key at the top level, next to error rather than inside it:

• A doc edit refused with stale_doc adds doc, holding the doc as it now stands. See A 409 refusal.
• A lease route refused with protocol_version_unsupported adds supported, for example "supported": { "current": 2, "min": 1 }.

A 403 refusal

A 403 from a role or scope check names why it refused in code, and its error object carries a target naming the kind of thing you tried to reach, such as Task. target is null when the call had no target. The codes are:

• role_insufficient — you have no role in the space (no membership on space), your role is below what the call needs (for example role viewer cannot perform tasks_update (write)), or your role is not one Cadence recognises (unknown role …). An action on something shared by the whole instance, such as an image or an agent skill, needs an instance administrator, and the message says so, for example instance-wide image actions require an instance admin.
• scope_violation — the token is limited to part of a space, and the target is outside it (target outside principal scope), or the target belongs to no space (target has no Space).
• space_archived — the space is archived and read-only, for example space OPS is archived (read-only).
• unknown_action — the call is not one Cadence recognises for authorization.

{
  "error": {
    "code": "role_insufficient",
    "message": "role viewer cannot perform tasks_update (write)",
    "target": "Task"
  }
}

A few 403s come from the route itself rather than from a role or scope check. They carry only code and message, with no target:

• lease_token_mismatch — The lease token does not authorize this request. You get it when:

  • a lease's token lists leases, reads a lease, cancels a lease or asks where a lease runs, even for its own lease
  • a lease's token fetches the payload of a lease other than its own
  • anything other than the lease named in the path reports that lease's usage or outcome, or adds an attachment to it. This includes a person's token, even an admin's.

  See Leases.

• lease_task_mismatch — a lease's token tried to add an attachment to a task that is not its own (a lease may only attach to its own task).

• lease_forbidden — a lease's token tried to delete a task's or a doc's attachment (a lease may not delete an attachment), or to post a comment on a task the lease can reach (Posting a comment requires a user API token.). On a task outside the lease's reach, the refusal is scope_violation.

• time_log_owner_mismatch — the time log belongs to someone else (The time log belongs to another user.). See Usage and time logs § Time logs.

A 409 refusal

A 409 means the request conflicts with the current state of what it names. Read code to see which conflict it is. What to do depends on it.

stale_write_conflict. When two writes to the same task race, Cadence re-reads the task and tries your request again, up to three attempts in all. Only if every attempt loses does it refuse:

{ "error": { "code": "stale_write_conflict", "message": "This task changed concurrently; reload and retry." } }

Read the task again, decide whether your change still applies, and send it again.

The other 409 codes are not races, and retrying the same request does not help:

Idempotency keys

Two routes require an Idempotency-Key header: creating a task and posting a comment on a task. Use a fresh unique value, such as a UUID, for each new task or comment. If you send the same key with the same body again within 24 hours, Cadence replays the first response and does not create a second task or post a second comment. This makes either call safe to retry after a timeout.

• A call with no key is refused with 422 and missing_idempotency_key (Idempotency-Key header required).
• Reusing a key with a different body is refused with 422 and idempotency_fingerprint_mismatch (Idempotency-Key reused with a different request body).

See Tasks § Create a task and Tasks § Post a comment over the API.

Sending a message takes an optional key, either in the Idempotency-Key header or as idempotency_key in the body. If you send both, the header is used. See Messaging § Send a message.

Reporting a lease's or a time log's usage requires an idempotency_key in the body. A report without one is refused with 422 and the code invalid_usage. The first report with a key answers 201. A repeat with the same key answers 200 with the row the first report created, and records nothing new.

Paging

Some list routes return one page at a time, with a next_cursor next to the list. To read the next page, repeat the request with that value as cursor. When next_cursor is null, you have the last page.

curl "https://cadence.example.com/api/v1/spaces/OPS/tasks?cursor=eyJ..." \
  -H "Authorization: Bearer smc_your_token_here"

These routes page this way:

On the task and audit-event lists, a limit outside its range is refused with 422 and invalid_filter (limit out of range). The lease list does not refuse a larger limit. It returns at most 100 instead. A cursor that Cadence cannot read is refused with 422: invalid_filter on the task and audit-event lists, and invalid_cursor on the lease list.

Other list routes, such as GET /api/v1/time_logs and GET /api/v1/spaces/:space_key/docs, return the whole list in one response, with no next_cursor.

Search routes do not page. They take a limit instead. See Search.

Paging a lease's logs

GET /api/v1/leases/:id/logs also returns a next_cursor, but it works differently. next_cursor is set on every page that has events, even the last one. Keep reading until a page comes back with no events. That page's next_cursor is null. There is no default page size. tail caps how many events a page returns, and a tail that is not a positive whole number is ignored. See Leases § Read a worker's logs.