REST API Reference

Return today's date in ISO 8601 (YYYY-MM-DD) and the server's UTC timestamp. Call this before computing relative dates like 'tomorrow' or 'next Friday'.

Return basic info about the current workspace (organization): id, name, slug, and plan.

List organization members as a lightweight directory (user id, display name, username, role) for resolving an assignee or mention target. For emails, activity, and profile details use members_list (requires the 'Read members' scope).

Return the calling user's identity in this org: user id, display name, email, and system role (owner / admin / member). Always available.

Create a new board with a name and optional description/color.

name*:string, description:string, color:string

Permanently delete a board and all of its lists and tasks. No undo.

board_id*:string

Get a single board including its lists (in order) so you know which list_id to target when creating or moving tasks.

board_id*:string

List a board's statuses in order (the Status view groups tasks by these, distinct from lists/columns). Use a returned status id with task_update's status_id to set a task's exact status.

board_id*:string

Update a board's name, description, or color.

board_id*:string, name:string, description:any, color:string

List boards in the workspace the user can see (open boards, boards they created, or boards their role can access).

Create a new list (column) on a board. Pass is_done=true if completing this list should mark tasks as done.

board_id*:string, name*:string, is_done:boolean

Delete a list and every task in it. No undo.

list_id*:string

Update a list's name or done-state flag.

list_id*:string, name:string, is_done:boolean

List the custom field definitions on a board (name, type, options, required), ordered by position.

board_id*:string

List the labels defined on a board (name, color, description), ordered by name.

board_id*:string

Create a custom field on a board. field_type is one of: text, longtext, number, date, dropdown, multi, link, email, person, checkbox. options is optional JSON (e.g. dropdown choices).

board_id*:string, name*:string, field_type*:text | longtext | number | date | dropdown | multi | link | email | person | checkbox, options:any, is_required:boolean

Delete a custom field definition from a board. Cascades to all task values for that field. No undo.

field_id*:string

Update a custom field definition's name, options, position, or required flag.

field_id*:string, name:string, options:any, position:integer, is_required:boolean

Create a label on a board (unique name per board). color is a #rrggbb hex string.

board_id*:string, name*:string, color*:string, description:any

Delete a board label. No undo.

label_id*:string

Update a label's name, color, or description.

label_id*:string, name:string, color:string, description:any

List tasks assigned to the calling user. Filter by status (default: only 'open').

status:open | done, limit:integer

Get tasks past their due date and still open, limited to boards the user can see.

Search tasks, documents, and boards by keyword. Returns up to 10 of each, filtered to what the user can see.

query*:string

List the direct subtasks of a task (child cards whose parent is this task), in board order.

task_id*:string

Add an org member as an assignee on a task. No-op if already assigned.

task_id*:string, user_id*:string

Remove an assignee from a task.

task_id*:string, user_id*:string

List all assignees on a task with their profile info.

task_id*:string

Replace a task's assignees with the exact set of user_ids given (pass [] to clear all). All ids must be org members.

task_id*:string, user_ids*:array

Delete a task attachment record. The uploader may delete their own; otherwise board delete permission is required. No undo.

attachment_id*:string

Generate a short-lived (1 hour) signed URL to view or download a single task attachment. Set download=true to force a save dialog.

attachment_id*:string, download:boolean

List file attachments on a task (file name, size, type, uploader, storage path). Use task_attachment_url to fetch a viewable URL.

task_id*:string

Batched card detail for a task: recent comments, attachment file names, and blocked-by / blocks dependency titles.

task_id*:string

Add a comment to a task.

task_id*:string, content*:string

Soft-delete a task comment. The author may delete their own; otherwise board delete permission is required.

comment_id*:string

Edit a task comment. Only the comment's own author may edit it (author-only).

comment_id*:string, content*:string

List comments on a task in chronological order.

task_id*:string, limit:integer

Create a new task in a board and list. Resolve list_id via board_get first.

board_id*:string, list_id*:string, title*:string, description:string, priority:none | low | medium | high | urgent, due_date:string, start_date:string, assignee_id:string

Permanently delete a task. No undo.

task_id*:string

List a task's dependencies: tasks that block it (blockedBy) and tasks it blocks (blocks).

task_id*:string

Add a dependency: blocking_task_id must be completed before blocked_task_id. Both tasks must be on boards you can edit.

blocking_task_id*:string, blocked_task_id*:string

Remove a task dependency by its id.

dependency_id*:string

Clear a single custom field value from a task (the field definition stays on the board).

task_id*:string, field_id*:string

Set (upsert) a custom field value on a task. value is JSON matching the field type (string, number, boolean, array, etc.).

task_id*:string, field_id*:string, value*:any

List the custom field values set on a task, each joined to its field name and type.

task_id*:string

Check whether the calling user is watching a task.

task_id*:string

Move a task to a different list on the same board.

task_id*:string, target_list_id*:string

Link a diagram (flowchart or chart) to a task. You must be able to view the referenced diagram.

task_id*:string, ref_type*:flowchart | chart, ref_id*:string

Remove a diagram reference from a task by its reference id. The reference's creator (or a board editor) may remove it.

reference_id*:string

List the diagrams (flowcharts / charts) linked to a task, hydrated with each target's title and type.

task_id*:string

Delete a time entry and decrement the task's timeSpent. The logger may delete their own; otherwise board delete permission is required. No undo.

entry_id*:string

List time entries logged against a task, newest first, with the logging user's profile info.

task_id*:string, limit:integer

Log time (in minutes) against a task as the calling user. Increments the task's running timeSpent. logged_at is an optional YYYY-MM-DD date.

task_id*:string, minutes*:integer, description:string, logged_at:string

Get a time-tracking summary for a task: total minutes logged, the task's running timeSpent, and the entry count.

task_id*:string

Remove the calling user from a task's watchers.

task_id*:string

Update a task's title, description, status, priority, dates, or assignee. Pass status_id to set the exact board status (discover ids via board_statuses_list); it takes precedence over the open/done `status` flag.

task_id*:string, title:string, description:any, status:open | done, status_id:any, priority:none | low | medium | high | urgent, due_date:any, start_date:any, assignee_id:any

Make the calling user a watcher of a task. No-op if already watching.

task_id*:string

List the users watching a task (subscribed to its updates).

task_id*:string

List tasks in the workspace, optionally filtered by board, status, priority, or assignee. Only returns tasks on boards the user can see.

board_id:string, status:open | done, priority:none | low | medium | high | urgent, assignee_id:string, limit:integer

Add a comment to a document.

document_id*:string, content*:string

Delete a document comment. Only the comment's author or an org admin/owner may delete it.

comment_id*:string

Mark a document comment as resolved.

comment_id*:string

Reopen a resolved document comment.

comment_id*:string

List comments on a document in chronological order. By default excludes resolved comments.

document_id*:string, include_resolved:boolean, limit:integer

Create a new document (or folder) with a title and optional plain-text body. The body is converted to a minimal TipTap doc — do not pass JSON.

title*:string, content:string, parent_id:string, is_folder:boolean

Toggle the calling user's favorite flag on a document. Returns the new favorited state.

document_id*:string

Create a new document from an existing template, optionally nested under a parent folder.

template_id*:string, parent_id:string

Get a single document including its TipTap content (as stored JSON). Excludes trashed documents.

document_id*:string

Permanently delete a trashed document and all its versions and descendants. No undo.

document_id*:string

Restore a trashed document (and its descendants) out of the trash. Restores to root if its parent is gone.

document_id*:string

Move a document (and, if it is a folder, its descendants) to the trash. Reversible via doc_restore.

document_id*:string

Permanently delete a document template. No undo.

template_id*:string

List the org's document templates with name, description, and category.

Update a document's title and/or body. Body is plain text — converted to a TipTap doc, replacing existing content. Do not pass JSON.

document_id*:string, title:string, content:string, icon:any

Restore a document to a saved version. The current content is snapshotted as a new version first.

version_id*:string

Snapshot a document's current content as a new version in its history.

document_id*:string

List saved version snapshots of a document, newest first, with version number, title, and timestamp.

document_id*:string, limit:integer

List documents the calling user has favorited. Excludes trashed documents.

List documents and folders the user can see (open docs, docs they created, or docs their role can access). Excludes trashed documents.

parent_id:string, limit:integer

List the most recently updated documents the user can see. Excludes trashed documents.

limit:integer

Search documents by title and body text. Returns up to 20 matches the user can see, newest-updated first. Excludes trashed documents.

query*:string

List soft-deleted documents in the trash (org-wide). Requires view-documents permission.

limit:integer

Create a channel. Pass is_private=true for an invite-only channel; you are auto-joined as the creator.

name*:string, description:string, is_private:boolean

Permanently delete a channel and all of its messages. No undo. Requires the delete-channels permission.

channel_id*:string

Get a single channel and its members. Private channels require membership.

channel_id*:string

Join a public channel. Private channels can't be joined without an invite. Requires the join-channels permission.

channel_id*:string

Leave a channel you're a member of.

channel_id*:string

Mark a channel as read up to now for the calling user.

channel_id*:string

List recent top-level messages in a channel, newest first. Requires view-messages permission and, for private channels, membership.

channel_id*:string, limit:integer

Update a channel's name, description, or topic.

channel_id*:string, name:string, description:any, topic:any

List channels in the workspace. Private channels the user isn't a member of are omitted; channels the user's roles can't view are omitted.

Start a direct-message thread with one or more org members, or return the existing 1:1 thread. Requires send-messages permission.

member_ids*:array

List recent top-level messages in a DM thread, newest first. The caller must be a participant.

thread_id*:string, limit:integer

List the direct-message threads the calling user participates in, with the other members and last message.

Delete a message. You may delete your own (needs delete-messages) or, with delete_others-messages, anyone's. Soft delete.

message_id*:string

Edit one of YOUR OWN messages. Requires edit-messages permission. To edit someone else's message use message_edit_others.

message_id*:string, content*:string

Edit another member's message. Requires the edit_others-messages permission.

message_id*:string, content*:string

Send a message to a channel OR a DM thread (exactly one of channel_id / thread_id). Optionally reply under a parent message. Requires send-messages permission and channel/DM access.

channel_id:string, thread_id:string, content*:string, parent_message_id:string

List replies under a parent message in chronological order. The caller must be able to see the parent (channel membership / DM participation).

parent_message_id*:string, limit:integer

Generate a shareable 30-day invite link that anyone can use to join this workspace. Generating an admin-role link requires you to be an owner or admin. Respects the free-tier seat cap.

role:admin | member, custom_role_id:string

Re-send a still-pending invitation: rotates its token, resets the 7-day expiry, and emails it again.

invite_id*:string

Revoke a pending invitation so its link can no longer be used.

invite_id*:string

List invitations for this workspace (pending, accepted, expired, revoked) newest first.

status:pending | accepted | expired | revoked

Get a member's recent board activity (their actions across boards in this workspace), newest first.

user_id*:string, limit:integer

Invite multiple people at once by passing a list of email addresses. Inviting at the admin role requires you to be an owner or admin. Each invite is checked against the free-tier seat cap; returns per-email results.

emails*:array, role:admin | member

Deactivate a member: they remain in the workspace but lose all access until reactivated. The primary owner cannot be deactivated (co-owners can, by an owner), and you cannot deactivate yourself.

member_id*:string

Get a single workspace member (by org member id) with profile, system role, and assigned custom roles. Email is null for members who hide it unless you are owner/admin.

member_id*:string

Invite a person by email to this workspace. Inviting at the admin role requires you to be an owner or admin. Respects the free-tier seat cap.

email*:string, role:admin | member, custom_role_id:string

Set or clear a member's per-org job title. Pass an empty string to clear it (the display then falls back to a role's preset title, if any). Editing your own title requires the members edit_own_job_title permission; editing others requires edit_job_title (owner/admin always may).

member_id*:string, job_title*:any

Reactivate a previously deactivated member, restoring their access.

member_id*:string

Permanently remove a member from this workspace. The primary owner cannot be removed (co-owners can, by an owner), and you cannot remove yourself. No undo.

member_id*:string

Change a member's system role (admin or member). Promoting/demoting admins or owners is reserved to owners. Co-owners can be demoted here, but the primary owner's role can't be changed (use Transfer ownership).

member_id*:string, role*:admin | member

Replace the full set of custom roles assigned to a member. Pass an empty list to clear all of their custom roles. All roles must belong to this workspace.

member_id*:string, role_ids*:array

List the members of this workspace with display name, username, email, system role, and per-org job title. Emails of members who hide their email are returned as null unless you are an owner/admin.

include_deactivated:boolean

Create a new custom role with a name, hex color, optional description, and optional preset job title (shown to every member holding the role).

name*:string, color:string, description:any, job_title:any

Delete a custom role. Members holding it lose it. System roles cannot be deleted. No undo.

role_id*:string

List the (resource_type, action) permission grants attached to a role.

role_id*:string

Replace the full permission set of a custom role with the given (resource_type, action) grants. Pass an empty list to clear all grants. System roles cannot be modified.

role_id*:string, permissions*:array

Update a custom role's name, color, description, or preset job title. Pass job_title as an empty string or null to clear the preset. System roles cannot be modified.

role_id*:string, name:string, color:string, description:any, job_title:any

List the custom and system roles in this workspace, ordered by position.

Get recent board activity for a team. Requires that the user can see the team AND holds the view_activity grant (owner/admin bypass).

team_id*:string, limit:integer

List the boards belonging to a team, with list and task counts. Requires that the user can see the team.

team_id*:string

List the channels belonging to a team. Requires that the user can see the team.

team_id*:string

Create a new team with a name, optional description, and color.

name*:string, description:any, color:string

Permanently delete a team. Its boards/channels/documents are detached (team_id set null), not deleted. No undo.

team_id*:string

List the documents belonging to a team (excluding trashed). Requires that the user can see the team.

team_id*:string

Get a single team with its members (display name, username, email). Requires that the user can see the team.

team_id*:string

Add an existing org member to a team. The target must already be an active org member.

team_id*:string, user_id*:string

Remove a member from a team. Removing yourself (self-leave) is always allowed; removing others requires manage_members on the team. The team owner cannot be removed until ownership is transferred.

team_id*:string, user_id*:string

Transfer team ownership to another current team member. Allowed for the current team owner or an org owner/admin. The new owner must already be a member of the team.

team_id*:string, new_owner_id*:string

Get aggregated counts for a team (tasks, open/completed/overdue, members, boards, channels). Requires that the user can see the team.

team_id*:string

Update a team's name, description, or color.

team_id*:string, name:string, description:any, color:string

List the teams the user can see in this workspace. Owner/admin see every team; everyone else sees only teams they belong to. Includes member counts.

List boards available as timeline filters (id, name, color). Returns nothing if the user can't view timelines.

Set or clear a task's start date and/or due date on the timeline. Pass null for either to clear it. Dates are 'YYYY-MM-DD'.

task_id*:string, start_date*:any, due_date*:any

List tasks that have a start date and/or due date so they can be plotted on the timeline. Only returns tasks on boards the user can see. Optionally filter by board, assignee, priority, or status.

board_id:string, assignee_id:string, priority:none | low | medium | high | urgent, status:open | done

Create a new goal/OKR with a target value and unit (percent | number | currency | tasks).

name*:string, description:string, target_value:integer, unit:percent | number | currency | tasks, due_date:string

Permanently delete a goal. No undo. The goal creator, an admin, or a role with goals:delete may delete.

goal_id*:string

Get a single goal by id with its full detail.

goal_id*:string

Update a goal's name, description, target value, unit, due date, current value, or status. The goal creator, an admin, or a role with the goals:edit permission may update.

goal_id*:string, name:string, description:any, target_value:integer, current_value:integer, unit:percent | number | currency | tasks, due_date:any, status:on_track | at_risk | behind | completed

Update a goal's current value and/or status (on_track | at_risk | behind | completed). The goal creator, an admin, or a role with goals:edit may update.

goal_id*:string, current_value:integer, status:on_track | at_risk | behind | completed

List all goals/OKRs in the workspace with their target value, stored current value, unit, status, and due date.

Create a new intake form on a board and target list. At least one field must map to 'title'. Resolve board_id/list_id via board_get first.

board_id*:string, list_id*:string, name*:string, description:any, fields*:array, is_public:boolean, requires_approval:boolean, approver_role_id:any, team_id:any

Permanently delete a form. No undo. Does not delete tasks already created from its submissions.

form_id*:string

Get a single form by id including its field definitions, board, and target list.

form_id*:string

Approve a pending form submission. Creates the deferred task in the form's target list, links it on the submission, marks the submission approved, and increments the form's submit count.

submission_id*:string

Reject a pending form submission with an optional reason. Never creates a task and never increments the form's submit count.

submission_id*:string, reason:any

List submissions for a form, most recent first, with their status (pending | approved | rejected), submitter email, linked task id, and any rejection reason.

form_id*:string, limit:integer

Update a form's name, description, fields, active/public state, target list, or approval settings. If fields are provided, at least one must map to 'title'.

form_id*:string, name:string, description:any, fields:array, is_active:boolean, is_public:boolean, list_id:string, requires_approval:boolean, approver_role_id:any

List all intake forms in the workspace with their board, target list, active/public state, submit count, and approval settings.

Create a new chart with a title, optional description, and chart type (defaults to bar). Set data/config afterward with chart_update.

title:string, description:string, chart_type:bar | line | pie | donut | area | scatter | radar | heatmap | treemap | sankey

Move a chart to the trash (soft delete, recoverable).

chart_id*:string

Get a single chart including its type, data rows, and rendering config.

chart_id*:string

Update a chart's title, description, type, data rows, or rendering config. Pass data as an array of row objects and config as a settings object.

chart_id*:string, title:string, description:any, chart_type:bar | line | pie | donut | area | scatter | radar | heatmap | treemap | sankey, data:any, config:any

List charts in the workspace the user can see (open ones, ones they created, or ones their role/team can access). Excludes trashed charts. Returns metadata only, not the chart data/config.

limit:integer

Create a new flowchart with a title and optional description. The diagram starts empty.

title:string, description:string

Move a flowchart to the trash (soft delete, recoverable).

flowchart_id*:string

Get a single flowchart's title, description, and metadata. Does not return the raw Yjs/binary diagram state.

flowchart_id*:string

Update a flowchart's title or description.

flowchart_id*:string, title:string, description:any

List flowcharts in the workspace the user can see (open ones, ones they created, or ones their role/team can access). Excludes trashed flowcharts. Returns metadata only, not the diagram contents.

limit:integer

Activity-log analytics for a period: total actions, distinct active categories, and a breakdown of action counts by category.

period:24h | 7d | 30d | all

Workspace overview KPIs for a period (24h/7d/30d/all): active members, tasks completed, messages sent, and documents created.

period:24h | 7d | 30d | all

Per-category storage usage for the workspace in bytes: task attachments, message attachments, other, and the canonical total.

Task analytics: open count, completed-in-period count, overdue count, plus a breakdown by status and by priority. Optionally scope to a single team.

period:24h | 7d | 30d | all, team_id:string

Read the workspace audit log, newest first. Optionally filter by category, acting user, period (24h/7d/30d/all), or a text search over entity name and action.

category:string, user_id:string, period:24h | 7d | 30d | all, search:string, limit:integer

Export the workspace document/folder tree metadata (title, type, created/updated). Excludes trashed documents. Owner/admin only.

Export a full structured snapshot of the workspace: organization, members, boards, tasks, documents, teams, and labels. Owner/admin only.

Export the member roster (name, email, system role, joined date, team memberships). Owner/admin only.

Export every task in the workspace as a structured list (title, status, priority, dates, board, list, assignee, labels). Owner/admin only.

Read the workspace plan, subscription state, and usage (storage bytes, member count, AI request usage). Read-only — does not start checkout.