Runs

14 routes. Every path starts at https://cloud-api.qaldy.com. Sign-in, tokens, errors and limits are on the overview.

Routes#

Reference#

GET /v1/dead-letters/{id}#

One dead letter, with the input it kept (for people who may edit the app).

• Authentication: the console’s session cookie.
• Token: a personal access token or an MCP sign-in with the read scope.
• Who: can_view on the app, else 404

Response 200

Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).

POST /v1/dead-letters/{id}/discard#

Set a dead letter aside: it is kept for a week as a record, then removed.

• Authentication: the console’s session cookie.
• Token: not available. This route is for a signed-in person in the console (403 console_only for a token).
• Who: can_edit

Request body (application/json)

An empty object: {}.

Response 200

Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).

POST /v1/dead-letters/{id}/replay#

Replay a dead letter as a new run, with its input as kept or an edited one.

• Authentication: the console’s session cookie.
• Token: a personal access token or an MCP sign-in with the write scope.
• Who: can_edit

Request body (application/json)

Response 200

Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).

GET /v1/runs/{id}#

One run with its step timeline.

• Authentication: the console’s session cookie.
• Token: a personal access token or an MCP sign-in with the read scope.
• Who: can_view on the app

Response 200

…and 4 more fields. The full schema is in openapi.json.

Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).

GET /v1/runs/{id}/ask#

What a run did, why, and what changed since the last good run (rules; free).

• Authentication: the console’s session cookie.
• Token: a personal access token or an MCP sign-in with the read scope.
• Who: can_view on the app; tokens: yes, read scope

Response 200

…and 6 more fields. The full schema is in openapi.json.

Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).

POST /v1/runs/{id}/ask#

Ask about this run: a model writes the answer when the workspace has a key for one.

• Authentication: the console’s session cookie.
• Token: a personal access token or an MCP sign-in with the read scope.
• Who: can_view; a model answer needs can_edit; tokens: yes, read scope

Request body (application/json)

Response 200

…and 6 more fields. The full schema is in openapi.json.

Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).

POST /v1/runs/{id}/change#

Plan the change a refused run suggests (let the app reach the host the gate refused): the diff, nothing built.

• Authentication: the console’s session cookie.
• Token: not available. This route is for a signed-in person in the console (403 console_only for a token).
• Who: can_edit and a builder; console only (tokens: no)

Request body (application/json)

An empty object: {}.

Response 200

…and 2 more fields. The full schema is in openapi.json.

Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).

GET /v1/runs/{id}/explain#

Explain & fix: what happened, why, and the next step.

• Authentication: the console’s session cookie.
• Token: a personal access token or an MCP sign-in with the read scope.
• Who: can_view on the app

Response 200

Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).

POST /v1/runs/{id}/replay#

Replay a failed run as a new run, optionally with an edited input.

• Authentication: the console’s session cookie.
• Token: a personal access token or an MCP sign-in with the write scope.
• Who: can_edit on the app; over a token, version: original is refused with approval_needs_console when that version may do more than the app does now

Request body (application/json)

Response 200

Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).

GET /v1/runs/{id}/trace#

What the platform recorded around a run: gate decisions and its last log lines.

• Authentication: the console’s session cookie.
• Token: a personal access token or an MCP sign-in with the read scope.
• Who: can_view on the app

Response 200

Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).

GET /v1/workspaces/{ws}/dead-letters#

Failed runs and refused webhook calls kept for replay (apps you can open).

• Authentication: the console’s session cookie.
• Token: a personal access token or an MCP sign-in with the read scope.
• Who: member (filtered to can_view)

Response 200

Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).

POST /v1/workspaces/{ws}/dead-letters/bulk#

Replay or discard up to 50 open dead letters as they were kept.

• Authentication: the console’s session cookie.
• Token: not available. This route is for a signed-in person in the console (403 console_only for a token).
• Who: member; can_edit per app

Request body (application/json)

Response 200

Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).

GET /v1/workspaces/{ws}/queue-health#

Work in flight, how long the oldest has waited and what finished (apps you can open).

• Authentication: the console’s session cookie.
• Token: a personal access token or an MCP sign-in with the read scope.
• Who: member (filtered to can_view)

Response 200

…and 7 more fields. The full schema is in openapi.json.

Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).

GET /v1/workspaces/{ws}/runs#

Runs, newest first (only apps you can view).

• Authentication: the console’s session cookie.
• Token: a personal access token or an MCP sign-in with the read scope.
• Who: member (filtered to can_view)

Response 200

Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).