In Development — Targeting Q3 2026

API Reference

KnotDo REST API

The KnotDo API lets you programmatically read and write tasks, lists, and webhooks. Available on Braid and Rope plans at general release.

Base URL

https://api.knotdo.app/v1

Authentication

Authorization: Bearer YOUR_API_KEY

Generate keys in Workspace Settings → API Keys.

Webhook Events

task.createdtask.updatedtask.completedtask.deletedlist.createdlist.updated

Each webhook payload includes a X-KnotDo-Signature header. Verify it using your webhook secret to confirm authenticity.

Authentication

GET/users/me

Returns the authenticated user's profile.

Example Response

{ "id": "usr_...", "email": "[email protected]", "name": "Your Name", "plan": "strand", "createdAt": "2026-01-01T00:00:00Z" }

Task Lists

GET/lists

Returns all task lists in the authenticated workspace.

Query Parameters

workspace_idstringFilter by workspace ID. Defaults to primary workspace.

Example Response

{ "data": [{ "id": "lst_...", "name": "Work", "color": "blue", "taskCount": 12, "createdAt": "..." }] }

POST/lists

Creates a new task list.

Request Body (JSON)

namestring *List name (max 100 chars)

colorstringColor: slate, blue, green, red, amber, violet, rose, etc.

defaultViewstringlist | kanban | gantt | calendar

Example Response

{ "id": "lst_...", "name": "New List", "color": "blue", "createdAt": "..." }

PATCH/lists/:id

Updates a task list.

Request Body (JSON)

namestringNew list name

colorstringNew color

Example Response

{ "id": "lst_...", "name": "Updated Name", "updatedAt": "..." }

DELETE/lists/:id

Deletes a list and all its tasks. Irreversible.

Example Response

{ "ok": true }

Tasks

GET/tasks

Returns tasks in the workspace. Filter by list, status, assignee, or due date.

Query Parameters

list_idstringFilter by list

statusstringtodo | in_progress | done | archived

assignee_idstringFilter by assignee user ID

due_beforeISO 8601Tasks due before this date

due_afterISO 8601Tasks due after this date

limitnumberMax results (default 50, max 200)

offsetnumberPagination offset

Example Response

{ "data": [{ "id": "tsk_...", "title": "...", "status": "todo", "priority": "high", "dueDate": null, "assigneeId": null }], "total": 42 }

POST/tasks

Creates a new task.

Request Body (JSON)

listIdstring *ID of the list to create the task in

titlestring *Task title (max 500 chars)

notesstringTask notes/description (markdown supported)

statusstringtodo (default) | in_progress | done

prioritystringnone (default) | low | medium | high | urgent

dueDateISO 8601Due date

assigneeIdstringUser ID to assign the task to

parentIdstringParent task ID (creates a subtask)

Example Response

{ "id": "tsk_...", "title": "...", "status": "todo", "createdAt": "..." }

PATCH/tasks/:id

Updates a task. Only include fields you want to change.

Request Body (JSON)

titlestringNew title

notesstringNew notes

statusstringtodo | in_progress | done | archived

prioritystringnone | low | medium | high | urgent

dueDateISO 8601 | nullSet or clear due date

assigneeIdstring | nullSet or clear assignee

Example Response

{ "id": "tsk_...", "title": "...", "status": "done", "updatedAt": "..." }

DELETE/tasks/:id

Deletes a task and all its subtasks. Irreversible.

Example Response

{ "ok": true }

Webhooks

GET/webhooks

Lists all configured webhooks for the workspace.

Example Response

{ "data": [{ "id": "whk_...", "url": "https://your-app.com/hook", "events": ["task.created", "task.completed"], "isActive": true }] }

POST/webhooks

Creates a webhook endpoint.

Request Body (JSON)

urlstring *HTTPS URL to receive webhook events

namestring *Friendly name for this webhook

eventsstring[] *Events to subscribe to (see event list below)

Example Response

{ "id": "whk_...", "url": "...", "secret": "whsec_...", "events": [...] }

Rate Limits

Braid plan

600 requests / 10 min

Rope plan

3,000 requests / 10 min

Rate limit headers

X-RateLimit-Remaining
X-RateLimit-Reset

Questions about the API?