API Reference

Returns info about the workspace linked to your API key.

{
  "id": "ws_abc",
  "name": "Acme Corp",
  "urlId": "acme",
  "avatarUrl": null,
  "taskPrefix": "SCA"
}

Returns all workspace members. Use userId as assigneeId when creating or updating tasks.

[{
  "userId": "user_abc",
  "name": "Jane Smith",
  "email": "jane@acme.com",
  "role": "member",
  "avatarUrl": null
}]

role is "owner", "member", or "guest".

Returns all task statuses in the workspace, ordered by position.

[{
  "id": "status_abc",
  "name": "In Review",
  "color": "#FFFABB",
  "systemType": null,
  "order": 2
}]

systemType is "todo" for the default start status, "done" for the completion status, or null for custom statuses.

Returns all projects in the workspace.

[{ "id": "proj_abc", "name": "Website Redesign", "description": null, "taskPrefix": "SCA" }]

Creates a new project with a default "To Do" section. Returns 403 if the workspace is on the free plan and has reached the 3-project limit.

# Returns 201
{ "id": "proj_xyz", "defaultListId": "sec_abc" }

Updates a project's name or description. At least one field required.

{ "id": "proj_abc" }

Returns all sections in a project, ordered by position.

[{ "id": "sec_abc", "name": "To Do", "order": 0, "projectId": "proj_abc" }]

Creates a new section at the end of a project.

# Returns 201
{ "id": "sec_xyz" }

Renames a section.

Returns all tasks in a project.

[{
  "id": "task_abc",
  "number": 42,
  "name": "Design homepage hero",
  "isCompleted": false,
  "description": null,
  "listId": "sec_abc",
  "assigneeId": null,
  "statusId": null,
  "order": 3,
  "createdAt": "2026-06-01T10:00:00.000Z"
}]

order is the task's display position within its section (lower = higher in the list). description is null when empty, or a rich text node array when set.

Returns a single task with full details, including description, labels, and projectId.

{
  "id": "task_abc",
  "number": 42,
  "name": "Design homepage hero",
  "isCompleted": false,
  "description": null,
  "listId": "sec_abc",
  "projectId": "proj_abc",
  "assigneeId": null,
  "statusId": null,
  "labels": [],
  "createdAt": "2026-06-01T10:00:00.000Z"
}

description is null when empty, or a rich text node array when set. To extract plain text, concatenate the text fields from all leaf nodes. Labels are read-only via the API.

Creates a new task in a section. Returns 400 if listId does not belong to the specified projectId. Returns 403 if the workspace is on the free plan and has reached the 300-task limit. To set a description, call PATCH /v1/tasks/:id after creation.

# Returns 201
{ "id": "task_xyz", "number": 42 }

Updates a task. Only the fields you send are changed. At least one field is required (otherwise 400).

description format

Pass a markdown string (recommended) or a raw Plate.js node array.

Supported markdown syntax: # / ## / ### headings, - bullet lists, 1. numbered lists, **bold**, *italic*, ***bold italic***, ~~strikethrough~~, `inline code`, > blockquote.

# Markdown string (recommended)
{ "description": "## Steps to reproduce\n\n- Open settings\n- Click Profile\n\n**Expected:** profile page opens" }

# Raw Plate node array (advanced)
{ "description": [{ "type": "p", "children": [{ "text": "Your text here" }] }] }

# Clear the description
{ "description": null }

• description cannot be set in POST /v1/tasks — use PATCH after creation.
• Omitting description from PATCH leaves existing content unchanged.
• Sending [] (empty array) stores an empty node — use null to clear.

Deletes a task and all its comments. Returns 204 on success.

Adds a comment to a task. When using an API key the comment appears under the key name; when using a Bearer token it appears as the authenticated user. Returns 201 on success.

# Plain text
{ "text": "Fixed the issue in projectsSaga.ts:287." }

# With markdown formatting
{ "text": "## Root cause\n\nThe worker was missing an `await`.\n\n- Fixed in projectsSaga.ts:287\n- Added unit test" }

# Returns 201
{ "id": "comment_xyz" }

Deletes a comment. Returns 204 on success.

Returns a resumable upload URL for uploading a file directly to Firebase Storage (valid for 7 days). PUT the file to this URL with the exact Content-Type and Content-Length headers.

# Step 1: get upload URL
{ "uploadUrl": "https://storage.googleapis.com/...", "attachmentId": "att_abc" }

# Step 2: upload the file directly to GCS
curl -X PUT "<uploadUrl>" \
  -H "Content-Type: image/png" \
  -H "Content-Length: <size in bytes>" \
  --data-binary @file.png

Registers an already-uploaded file as an attachment on a task. Call this after a successful PUT to the signed URL. Returns the permanent download URL.

{ "id": "att_abc", "url": "https://firebasestorage.googleapis.com/..." }

Registers a new webhook endpoint. Plate will send a signed HTTP POST to url for each matching event. Returns 201 on success.

{ "id": "wh_abc", "url": "https://example.com/hooks/plate", "events": ["task.created", "task.updated", "task.completed"] }

Returns all registered webhook endpoints for the workspace. Secrets are never included in the response.

[
  {
    "id": "wh_abc",
    "url": "https://example.com/hooks/plate",
    "events": ["task.created", "task.updated", "task.completed"],
    "createdAt": "2024-01-15T10:00:00.000Z"
  }
]

Deletes a webhook endpoint. Returns 204 on success.