REST API reference

The basics

• Base URL: https://cheqq.ai/api/platform/v1
• Authentication: Authorization: Bearer cqk_… with an API key, or an access token from a connected app.
• Requests: GET and DELETE take query parameters; POST, PUT and PATCH take a JSON body (Content-Type: application/json). Ids in the path always win over the same name in the body.
• Responses: JSON. Creating something answers 201, starting an App publish answers 202, everything else 200.
• Who it acts as: you, in the key's workspace, with your role in each Wapp. Writes appear in each Wapp's history with "(API)" at the end, and can be undone there. An archived Wapp can be read but not changed.

Every operation here is also an MCP tool; its name is under each table.

Errors

Every error has the same shape:

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This key isn't allowed to add and change records. Create a key with the \"records:write\" scope.",
    "details": { "requiredScope": "records:write" }
  }
}

message is written to be shown to a person. details is null or an object with more to go on.

A 401 carries a WWW-Authenticate header, and a 403 INSUFFICIENT_SCOPE names the missing scope in it as well.

Paging

Lists that can be long page in one of two ways, and say so in their answer:

• Records and runs return nextCursor. Pass it back as cursor to get the next page; null means there are no more.
• Documents take page (from 1) and pageSize, and return total.

Rate-limit headers

Every answer after authentication carries:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997

See Rate limits.

You

MCP: cheqq_whoami.

Wapps

A Wapp is named everywhere by its install id, its Wapp id or its slug (such as content-studio). If two Wapps in the workspace share a slug, use the install id.

Deleting a Wapp. The first DELETE deletes nothing: it answers needsConfirmation: true with what goes with it (its records, collections and automations, and how many other people lose it). Check with the person, then send it again with { "confirmed": true }. The Wapp moves to Trash and can be restored for 30 days with its records, automations and inbox addresses; its Apps are deleted for good. If automations of yours outside the Wapp still use it, the answer is 409 WAPP_DELETE_BLOCKED naming them in details.workflows: send trashWorkflowIds with their ids to move them to Trash with it.

MCP: cheqq_list_wapps, cheqq_get_wapp, cheqq_create_wapp, cheqq_delete_wapp.

Collections and fields

Fields. A field's slug is its key: record values, filters and sorts use it, and renaming the field never changes it. Where a path takes {fieldKey}, the field's label works too if only one field has it.

Field types: text, long_text, number, duration, checkbox, date, url, email, select, multi-select, json, relation, file, user, lookup, rollup, formula. Select fields take options (labels); a relation takes targetCollectionSlug and mode (single or multiple); a lookup takes relationFieldSlug and targetFieldSlug; rollups and formulas take a formula.

Changes that lose data (retyping a field, making it required, removing it) answer 409 DESTRUCTIVE_SCHEMA_CHANGE until you send confirmDestructive: true. Every one can be undone from the Wapp's history.

curl -X POST https://cheqq.ai/api/platform/v1/collections/COLLECTION_ID/fields \
  -H "Authorization: Bearer $CHEQQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Channel", "type": "select", "options": ["Blog", "LinkedIn", "Newsletter"] }'

MCP: cheqq_list_collections, cheqq_create_collection, cheqq_get_collection, cheqq_update_collection, cheqq_delete_collection, cheqq_add_field, cheqq_update_field, cheqq_remove_field.

Views

config replaces the whole config, so read the view, change what you need and send it all back. A locked view refuses changes to its name, type and config unless you're an admin of the Wapp. MCP: cheqq_list_views, cheqq_create_view, cheqq_update_view, cheqq_delete_view.

Dashboards

Each tile has a uuid id, a grid layout (x, y, w, h) and content of kind chart, table or timeline. A tile's source is all of a collection's records ({ "mode": "all" }), a saved view's ({ "mode": "view", "viewId" }) or a filter's ({ "mode": "filter", "filter" }, in the filter language records use). Tiles are checked before they're saved: a tile over a collection of another Wapp, or a filter on a field the collection doesn't have, answers 422 naming the tile and the field keys there are. Read an existing dashboard to copy the shape. MCP: cheqq_list_dashboards, cheqq_create_dashboard, cheqq_update_dashboard, cheqq_update_dashboard_tiles, cheqq_delete_dashboard.

Records

Writing values. data names fields by key or by label. A select takes the option's label. A name no field answers to is refused with 400 INVALID_FIELD, listing the fields you could have meant. Automations that run on new or changed records run for API writes as they do for yours.

Reading values. data is keyed by field key. A select value reads as { "id": "…", "label": "Live" } and a multi-select as a list of them, so you can show the label and send either one back.

Filtering records

Listing, counting and dashboard tiles take one filter language, the one saved views use: a group of rules joined by and (the default) or or, where a rule can itself be a group.

{
  "glue": "and",
  "rules": [
    { "field": "status", "filter": "contains", "includes": ["Live"] },
    { "field": "amount", "filter": "greater", "value": 100 },
    { "glue": "or", "rules": [
      { "field": "title", "filter": "contains", "value": "launch" },
      { "field": "owner", "filter": "isEmpty" }
    ] }
  ]
}

Rules name fields by key. Text takes contains, notContains, equal, notEqual, beginsWith and endsWith; numbers and dates equal, notEqual, greater, greaterOrEqual, less and lessOrEqual; any field isEmpty and isNotEmpty. Select, relation and person fields use contains or notContains with includes: option labels or ids, record ids or member ids. A rule on a field the collection doesn't have answers 422 with the field keys it does have. On a GET, send the group as JSON in ?filter=. The older equality shorthand filter.<field key>=value still works, but not together with filter.

Summaries. Each widget is { "id": "<a uuid you choose>", "aggregation": { "type": "sum", "sourceFieldId": "amount" } }. Types: count, sum, avg, min, max, median, empty, unique, earliest, latest, option-counts, group-by. Results come back keyed by your widget id.

MCP: cheqq_list_records, cheqq_get_record, cheqq_count_records, cheqq_aggregate_records, cheqq_create_record, cheqq_update_record, cheqq_create_records, cheqq_update_records, cheqq_delete_record, cheqq_delete_records.

Automations

There's no endpoint to create an automation from scratch yet: build new ones over MCP, or in Cheqq. See Automations. MCP: cheqq_list_workflows, cheqq_get_workflow, cheqq_replace_workflow, cheqq_delete_workflow, cheqq_list_workflow_actions.

Runs

MCP: cheqq_run_workflow, cheqq_list_runs, cheqq_get_run, cheqq_stop_run, cheqq_respond_to_run.

Documents

See Documents and Apps for how versions keep two people's edits apart. MCP: cheqq_list_documents, cheqq_get_document, cheqq_read_document_file, cheqq_create_document, cheqq_update_document, cheqq_patch_document, cheqq_read_document_blocks, cheqq_edit_document_blocks, cheqq_export_document, cheqq_list_document_versions, cheqq_restore_document_version, cheqq_delete_document.

Apps

Source files you can write are under src/, public/ and index.html; the rest of the project is managed by Cheqq. See Documents and Apps. MCP: cheqq_list_apps, cheqq_get_app, cheqq_get_app_deployment, cheqq_list_app_files, cheqq_read_app_file, cheqq_write_app_files, cheqq_delete_app_file, cheqq_update_app_dependencies, cheqq_list_app_checkpoints, cheqq_restore_app_checkpoint, cheqq_check_app, cheqq_verify_app, cheqq_publish_app, cheqq_unpublish_app, cheqq_rollback_app.