Public API

The public API is the same surface our own integrations are built on. Use it to read and write your workspace’s data — boards, tasks, subtasks, notes and more — from your own code.

Base URL: https://app.coalfacetasks.com/api/public/v1 Format: JSON in, JSON out, UTF-8. All times are ISO-8601 UTC. Versioning: the major version is in the path (/v1). Additive changes (new fields, new endpoints) won’t break you; breaking changes ship under a new version.

Authentication

Every request carries an API key as a bearer token:

Authorization: Bearer ctk_a1b2c3d4_<48-hex-secret>

Create keys in Settings → API. A key:

• belongs to one workspace — it can only ever touch that workspace’s data;
• carries a set of scopes — see below;
• is shown once, at creation. We store only a hash of it. Lose it and you revoke and mint a new one.

The workspace is resolved from the key, so it’s never in the URL. Revoked keys stop working immediately.

Scopes

Scopes are <resource>:<read|write>. write covers create, update and delete — it does not imply read. Grant a key the least it needs.

Resource	Scopes
Boards	boards:read, boards:write
Columns	columns:read, columns:write
Tasks	tasks:read, tasks:write
Subtasks	subtasks:read, subtasks:write
Notes	notes:read, notes:write
Members	members:read, members:write
Labels	labels:read, labels:write
Webhooks	webhooks:read, webhooks:write

Responses

Success returns { "data": ... }. List endpoints add a pagination block.

{ "data": { "id": "…", "title": "Ship v1" } }

Errors return { "error": { "code": "…", "message": "…" } } with a stable code:

Status	code	Meaning
400	validation_error	Malformed body or an invalid field
401	unauthorized	Missing, malformed, unknown or revoked key
403	forbidden	Valid key, but missing the required scope

A first request

List your tasks:

curl https://app.coalfacetasks.com/api/public/v1/tasks \
  -H "Authorization: Bearer ctk_a1b2c3d4_<secret>"

Create one:

curl -X POST https://app.coalfacetasks.com/api/public/v1/tasks \
  -H "Authorization: Bearer ctk_a1b2c3d4_<secret>" \
  -H "Content-Type: application/json" \
  -d '{ "board_id": "…", "title": "Written from the API" }'

Webhooks

Rather than poll, subscribe to webhooks and we’ll push events to your endpoint: task.created, task.updated, task.completed, task.deleted, task.assigned and note.added.

Each delivery is signed — an X-CFT-Signature header over the payload and a timestamp — so you can verify it came from us. Manage subscriptions in Settings → API.

Connecting Zapier

Zapier is just a consumer of this API. Use a key with the scopes your Zap needs, and subscribe to webhooks for the events you want to trigger on — there’s a Set up for Zapier preset in the API settings that pre-fills the common events.

Using AI clients (MCP)

If you want your own AI client — Claude, Cursor and others — to read and update tasks, the MCP server runs on top of this same API and uses these same keys and scopes.

The short version: mint a scoped key in Settings → API, send it as a bearer token, and read or write your workspace’s data. Subscribe to signed webhooks for push updates.