Tasks

Tasks can be created, listed, updated, marked done, and commented on via the API.

Account API keys (il_live_) can only access record-scoped tasks. Standalone tasks return Task is not on a record.

Personal API keys (il_user_) can access all tasks you have permission for, including standalone tasks. They also have access to additional endpoints for listing and creating standalone tasks (see Standalone tasks below).

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
}

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

Returns {"ok": true, "subscribed": true} or {"ok": true, "subscribed": false}.

Without force, subscribing when already subscribed (or unsubscribing when not) returns an error.

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.

Task comments support the same mention token format as record comments: @{<user_id>:<display_name>}. Only current workspace members are valid. When a valid token is created, the mentioned user gets a task.comment.mention notification and is auto-subscribed to the task.

Task comments support the same mention token format as record comments: @{<user_id>:<display_name>}. Only current workspace members are valid. When a valid token is created, the mentioned user gets a task.comment.mention notification and is auto-subscribed to the task.

Task comments support the same mention token format as record comments: @{<user_id>:<display_name>}. Only current workspace members are valid. When a valid token is created, the mentioned user gets a task.comment.mention notification and is auto-subscribed to the task.

Standalone tasks (personal keys only)

These endpoints are only available with personal API keys (il_user_).

List your tasks

POST /api/tasks/list

Create a standalone task

POST /api/tasks/create

Badge count

POST /api/tasks/badgeCount

Returns {"count": <n>} — open tasks assigned to you that are due today or overdue.

File attachments

Task and task-comment endpoints accept an attachments array shaped like record file fields: [{path,name,size,type,host},...]. Session-only — attachments cannot be set or uploaded with API keys. Attempting to include attachments in a public-API call returns Attachments cannot be set via the public API.

The browser-only upload endpoints (no API key access) are:

POST /api/tasks/upload                                       (new standalone)
POST /api/tasks/onRecord/<table_id>/<record_id>/upload       (new record-linked)
POST /api/task/<task_id>/upload                              (existing task)
POST /api/task/<task_id>/comments/upload                     (existing task's comment)

Each takes {name, type, data} (data = base64-encoded bytes, max 50 MB). Existing-task uploads return {name,path,size,type,host}. New-task uploads return staged metadata with a staged_token. Pass the metadata through to the task/comment create or update payload as attachments: [...].

For new tasks, the file stays in local session staging until Task::create() assigns the task id, then uploads once to final task-{id}-... storage and returns the final path on the created task.

Removing an attachment via /task/<id>/update (by passing an attachments array that omits an entry the task previously had) queues the dropped path for delayed S3 cleanup. Task comment attachments are frozen at post — to remove a comment's attachment, delete the comment.

Permission errors