API Reference

Errors

Failures use standard HTTP status codes and a small JSON envelope.

Error response shape

Example
{
  "statusCode": 403,
  "message": "API token is not authorised for this workspace.",
  "error": "Forbidden"
}

Status codes

400
Bad request
Malformed body, missing required field, or a domain rule rejected the request (e.g. trying to edit a snapshot).
401
Unauthorized
Missing or invalid Authorization header, or the token has been revoked.
403
Forbidden
The token authenticated but the resource lives in a different workspace than the token, or the action requires admin (which API tokens never have).
404
Not found
The resource id (workflow, run, item, token) does not exist or is hidden from the caller.
500
Server error
Something on our end. Safe to retry idempotent reads; for writes (Create a run) check Get a run before retrying so you don't double-charge.

Retry guidance

  • Reads (GET) are safe to retry. Use exponential backoff for 5xx responses.
  • Run creation is not idempotent. If a POST /workflows/:id/runs call times out, list the workflow's recent runs to see whether one was already created before retrying.
  • 401 / 403 will not become 200 by retrying. Check the token, that the resource lives in the token's workspace, and the workspaceId query param on workspace-wide endpoints.