API authentication, responses and errors

Send the key in a header

Use one of these headers for authenticated requests:

X-API-Key: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

Send exactly one credential header. Private job, space and connection routes reject URL credentials, even alongside a valid header. Store keys on the server.

Permissions and key types

Scope	Use
`read`	Read resources covered by the API.
`write`	Read and write resources; includes read access.
`jobs:read`	Read job listings.
`jobs:draft`, `jobs:publish`, `jobs:edit`, `jobs:lifecycle`	Save drafts, publish or repost, edit, or unpublish respectively. Older `jobs:write` grants retain supported job actions.
`spaces:read`	Read space endpoints.
`cities:read`	Read city lookups; broad `read` also covers this.
`events:read`	Read event endpoints.

cwk_rstr_ keys are read-only; cwk_live_ keys allow the configured write permissions. A prefix is not a permission grant by itself. The key’s configured scopes and space restrictions still apply. A job-write scope alone does not grant every read scope; choose the permissions needed for both setup and writing.

Response format

Success responses contain success, status and data. The shape of data depends on the endpoint: jobs use data.jobs, while cities and spaces return arrays.

{
  "success": false,
  "status": 422,
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "details": ["Job title is required"]
  }
}

error.details is not always an array. For rate limits and permission errors it can be an object. Check its type before iterating. Handle network errors and non-JSON responses as well as API errors.

Fix common errors

HTTP status	Action
`400`	Check JSON syntax and the request format.
`401`	Check the key, expiry, revoked status and any IP restrictions.
`403`	Check the required scope and whether the job belongs to the key’s space.
`404`	Check the endpoint or resource identifier. Removed v1 paths can return this status; use API v2.
`405`	Use the endpoint’s supported HTTP method.
`409`	Inspect the error code. For `job_exists`, read the existing job. For a stale revision, read again before confirming a change.
`410`	`api_version_retired`: migrate the request to API v2. Retrying the same v1 request or rotating its key will not restore access. See v1 retirement and migration.
`422`	Correct the fields listed in `error.details`.
`429`	Wait for `error.details.retry_after_seconds`, then retry with backoff and jitter.
`500`	Retry cautiously; include context in a support report without sharing secrets.

Job write operations are rate-limited per key. The reference gives a fallback of 120 writes per minute, but a key’s configured limit takes precedence. Use the returned limit and retry delay rather than assuming a quota.

Reuse the same Idempotency-Key and body for an exact retry. Ordinary cached receipts last up to 24 hours and can be unavailable. Check the owned job after an uncertain result before retrying. See Jobs API.