Tasks

Record-scoped tasks can be created, listed, updated, marked done, and commented on via the public API. Standalone tasks (not attached to a record) remain session-only — API keys trying to reach them get Task is not on a record.

All endpoints require an API key with read access to the task's workspace. Write operations additionally require the key to not be read-only.

Create a task on a record

POST /api/tasks/onRecord/<table_id>/<record_id>/create

Request body

{
  "title": "Send proposal",
  "details": "Draft is attached to the record",
  "assignee_email": "sam@example.com",
  "due_date": "2026-05-01",
  "due_time": "09:00",
  "reminder_offset_mins": 30
}

Field	Type	Notes
`title`	string	Required.
`details`	string	Optional long text.
`assignee_user_id`	int	Takes precedence if both id and email are given.
`assignee_email`	string	Must be a current space member.
`due_date`	`YYYY-MM-DD`	Optional.
`due_time`	`HH:MM`	Optional, only valid alongside `due_date`.
`reminder_offset_mins`	int	Minutes before the due datetime. Requires `due_time`.
`reminder_time`	`HH:MM`	Time of day on `due_date` (date-only tasks). Mutually exclusive with `reminder_offset_mins`.

Response

{
  "id": 19,
  "creator_user_id": 4,
  "assignee_user_id": 9,
  "account_id": 1,
  "space_id": 2,
  "table_id": 101,
  "record_id": 42,
  "title": "Send proposal",
  "details": "Draft is attached to the record",
  "due_date": "2026-05-01",
  "due_time": "09:00:00",
  "reminder_offset_mins": 30,
  "reminder_time": null,
  "reminder_at": "2026-05-01 08:30:00",
  "reminder_sent_at": null,
  "status": "open",
  "completed_at": null,
  "completed_by_user_id": null,
  "created_at": "2026-04-15 14:32:01",
  "updated_at": "2026-04-15 14:32:01"
}

List tasks on a record

GET /api/tasks/onRecord/<table_id>/<record_id>/list

Query parameters

status — open or done. Omit for all.
limit (default 50, max 200)
offset (default 0)

Get a single task

GET /api/task/<task_id>/get

Returns the task row plus comment_count, subscribers (user ids), subscribed (boolean for the calling key's owning user), table_name, record_title, and a recent_comments array with the latest 20 comments.

Update a task

POST /api/task/<task_id>/update

Any of title, details, due_date, due_time, reminder_offset_mins, reminder_time, assignee_user_id, assignee_email. Reassignment fires a single TASK_ASSIGNED notification to the new assignee.

Delete a task

POST /api/task/<task_id>/delete

Mark done / undone

POST /api/task/<task_id>/markDone
POST /api/task/<task_id>/markUndone

Both return {"ok": true|false, "status": "done"|"open"}. ok is false when the call is idempotent (e.g. marking an already-done task done again).

Subscribe / unsubscribe

POST /api/task/<task_id>/subscribe
POST /api/task/<task_id>/unsubscribe

Comments

GET  /api/task/<task_id>/comments/get        (limit, offset)
POST /api/task/<task_id>/comments/create     {content}
POST /api/task/<task_id>/comment/<comment_id>/update   {content}
POST /api/task/<task_id>/comment/<comment_id>/delete

Comments created via an API key have user_id = 0, user_name = "API: <key name>", and api_key_id set — same convention as record comments. Authors can edit their own comments for 15 minutes after creation.

Permission errors

Error	Meaning
`Task is not on a record`	API key tried to reach a standalone task.
`API key not authorized for this workspace`	Key's space whitelist excludes this task's space.
`API key is read-only`	Read-only key attempted a write operation.
`Not authorized`	Record-linked task whose space the key cannot read, or non-creator/non-assignee trying to edit.