API endpoint reference · ClientStack docs

Authentication

All endpoints below start with /api and require a team bearer token. Send Accept: application/json. For a JSON body, also send Content-Type: application/json.

Run endpoints

Method and path	Ability
`POST /runs`	`runs:write`
`POST /runs/{run_id}/answers`	`runs:write`
`POST /runs/{run_id}/cancel`	`runs:write`
`GET /runs`	`runs:read`
`GET /runs/{run_id}`	`runs:read`
`GET /runs/{run_id}/judgments`	`runs:read`
`POST /runs/{run_id}/handled`	`runs:handle`
`DELETE /runs/{run_id}/handled`	`runs:handle`

The run list returns runs and next_cursor. Pass the cursor to request the next page. The maximum limit is 100.

Request type endpoints

Method and path	Ability
`GET /case-type-templates`	`case-types:read`
`GET /case-types`	`case-types:read`
`GET /case-types/{slug}`	`case-types:read`
`GET /case-types/{slug}/versions/{version}`	`case-types:read`
`GET /case-types/{slug}/editor`	`case-types:read`
`POST /case-types/{slug}/judgments`	`case-types:read`; also `case-types:write` for fresh judgments
`POST /case-types`	`case-types:write`
`PUT /case-types/{slug}/draft`	`case-types:write`
`POST /case-types/{slug}/checks`	`case-types:write`
`POST /case-types/{slug}/publish`	`case-types:write`
`PATCH /case-types/{slug}`	`case-types:write`
`POST /case-types/{slug}/archive`	`case-types:write`
`POST /case-types/{slug}/restore`	`case-types:write`
`POST /case-types/{slug}/probe`	`case-types:write`

Draft writes use the contract’s expected hash to detect a changed draft. Read the current document before a change. Treat a conflict as a request to review the newer draft.

Examples and replay

Method and path	Ability
`GET /case-types/{slug}/examples`	`case-types:read`
`POST /case-types/{slug}/examples`	`examples:write`
`DELETE /examples/{example}`	`examples:write`
`POST /runs/{run_id}/examples`	`examples:write`
`POST /case-types/{slug}/replays`	`examples:write`
`GET /replays/{replay}`	`case-types:read`

An example contains answers and expected. Each answer has a step_id and value. The expected value is an outcome code.

Read an error

{
  "error": {
    "code": "stale_step",
    "message": "This step was already answered."
  }
}

HTTP status	Meaning
401	Missing, expired, revoked, or invalid token.
403	Missing ability or an action that demo mode refuses.
404	Missing resource or a resource in another team.
409	Conflicting state, answer, draft, or idempotency key.
422	Invalid body, answer, publish checks, or unavailable request type.
429	Rate limit reached; read `Retry-After`.

Engine failure is part of the run view. It can return HTTP 200 with a handoff or a retry on the same step.

Limits

The current contract permits 600 requests per minute per API token and 30 answers per minute per run. Hosted creation has separate limits. Always handle 429 responses even if your average usage is lower.

Continue

Follow a complete API request before implementing advanced request type editing.