REST API
How the API behaves
Ids you make, safe retries, whole-row updates, pages and cursors, errors in plain words, rate limits, dates and how the API changes.
The API is plain JSON over HTTPS. Field names are camelCase, values such as statuses are lowercase words (inProgress, done), and every request needs your key.
Ids you make, and retries
Things you create carry an id you choose: a UUID for a checklist, a section, a step or a template. If a request times out and you send it again with the same id, the server answers 409 Conflict: the thing already exists, and nothing was made twice. Treat that 409 as success.
Starting a checklist from a template is the one create where the id may be left out; the server then makes it. Send one anyway whenever you might retry.
Deleting something that is already gone answers 404. Treat that as success too.
Updating a row
A PUT sends the row's whole state, so sending the same PUT twice changes nothing the second time. To tick a step, send its status and answers:
curl -X PUT https://api.checklistsquad.com/api/items/9a2c… \
-H "Authorization: Bearer $CSQ_KEY" \
-H "Content-Type: application/json" \
-d '{ "status": "done", "answers": { "meter-reading": "4821" } }'
done needs every required field answered. blocked and skipped need a statusReason. The server checks what changed: a key that may tick a step but not edit it can send the step's title back unchanged.
Pages
Every list is a page:
{ "data": [ … ], "nextCursor": "c3ViXz…" }
Pass nextCursor back as ?cursor= for the next page, until it is null. pageSize is 100 by default and at most 1000. A list only ever holds what the key may see; there is no total count.
Most lists take a filter: checklistId on sections, items, assignments and activity, id on checklists, and organizationId and public on templates.
Errors
Errors are problem details whose title is the rule, in words you can show a person:
{ "status": 400, "title": "Wash and dry needs every required field answered: Meter reading." }
| Status | Means |
|---|---|
400 | The request broke a rule: a missing field, an unknown template, a cursor this list never issued. |
401 | No key, or a key that is wrong, expired or revoked. The body says nothing more, on purpose. |
403 | The key's role does not allow this here. |
404 | Not there, or not something the key may see. |
409 | Already exists: a retried create. |
429 | Too many requests. Wait for Retry-After. |
Rate limits
A key may make 300 requests a minute. Past that, requests answer 429 with Retry-After (seconds), X-RateLimit-Limit and X-RateLimit-Reset. Too many wrong keys from one address are refused for a minute.
Dates
Dates are ISO 8601 in UTC: 2026-10-30T15:00:00Z. Send them the same way.
Changes to the API
The API changes by adding: new routes, new fields, new values. Ignore fields you do not know. Anything that would break an integration will come as a new path, announced here first. Each page here says when it was last updated.