Skip to content
Knobs Docs

Tasks

Tasks are workspace to-dos with status, priority, due/do dates, and labels. A task can also be source-linked — created from a mail thread or chat message with a server-verified reference back to its source.

All routes are workspace-scoped and accept a session JWT or API key.

Endpoints

Section titled “Endpoints”
Endpoint Description
GET /v1/workspaces/{wid}/tasks List; ?view= (e.g. my-day/upcoming), ?tz=, ?limit= — or ?from=&to= (RFC 3339) for the date-range mode that feeds calendar overlays
POST /v1/workspaces/{wid}/tasks Create a task
GET /v1/workspaces/{wid}/tasks/{tid} One task
PATCH /v1/workspaces/{wid}/tasks/{tid} Partial update
DELETE /v1/workspaces/{wid}/tasks/{tid} Delete
POST /v1/workspaces/{wid}/tasks/{tid}/complete Mark complete → the updated task
POST /v1/workspaces/{wid}/tasks/{tid}/reopen Reopen → the updated task

Create a task

Section titled “Create a task”
Terminal window
curl -X POST https://api.knobs.io/v1/workspaces/{wid}/tasks \
  -H "Authorization: Bearer knak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Send Q3 budget draft",
    "notes": "Use the numbers from the finance sheet.",
    "priority": 2,
    "dueAt": "2026-07-20T17:00:00Z",
    "labels": ["finance"]
  }'

Returns 201 with the task. Fields: title (required), notes, priority (int), status, dueAt/doAt (RFC 3339), labels, listId.

Update a task

Section titled “Update a task”

PATCH takes any subset of the create fields (all optional). To unset a date, send the explicit clear flag rather than omitting the field:

Terminal window
curl -X PATCH https://api.knobs.io/v1/workspaces/{wid}/tasks/{tid} \
  -H "Authorization: Bearer knak_..." \
  -H "Content-Type: application/json" \
  -d '{"title": "Send Q3 budget draft v2", "clearDueAt": true}'

Source-linked creation

Section titled “Source-linked creation”

These RPCs create a task pointing at a source object. You pass only the source’s id — the server validates you can actually see it and derives the title/snippet itself, so a task can never leak content you can’t read.

Endpoint Source
POST /v1/workspaces/{wid}/tasks:create-from-mail a mail thread (objectId = thread id)
POST /v1/workspaces/{wid}/tasks:create-from-chat a chat message (objectId = message id)
POST /v1/workspaces/{wid}/tasks:create-from-doc a doc (reserved — returns 501 until the backend lands)
POST /v1/workspaces/{wid}/tasks:create-from-sheet a sheet (reserved, 501)
POST /v1/workspaces/{wid}/tasks:create-from-drive a drive file (reserved, 501)
POST /v1/workspaces/{wid}/tasks:create-from-web-run an @Web run (reserved, 501)
Terminal window
curl -X POST https://api.knobs.io/v1/workspaces/{wid}/tasks:create-from-mail \
  -H "Authorization: Bearer knak_..." \
  -H "Content-Type: application/json" \
  -d '{"objectId": "t_8c1f…", "title": "Reply to Sam re: Q3 planning"}'

title is optional — it defaults from the source (the thread subject, for mail). A source you can’t read returns 404 source_not_found.

Section titled “Related”
  • Calendar — the mirror-image events:create-from-mail / events:create-from-chat RPCs.
  • Search — tasks are searchable via type=task.