Integrate tasks with the public API
The public REST API is available under /api/v1. It supports reading board configuration and members, and operating on tasks and comments. See the API reference for request and response schemas.
Authentication
Section titled “Authentication”Create a token for the selected workspace under Account settings → API tokens. The secret is shown only once. Store it in your integration’s secret configuration.
Send both headers on every request:
Authorization: Bearer <API token>X-Tenant-Id: <workspace ID>
Read tokens allow reads; read/write tokens also allow mutations. The owner’s current workspace and board permissions still apply. Revoked or expired tokens, and tokens belonging to a removed member, cannot be used.
Create your first task
Section titled “Create your first task”These examples use UTSUROI_API_URL for the backend origin, UTSUROI_TENANT_ID for the workspace ID and UTSUROI_API_TOKEN for the token.
curl "$UTSUROI_API_URL/api/v1/boards" \ -H "Authorization: Bearer $UTSUROI_API_TOKEN" \ -H "X-Tenant-Id: $UTSUROI_TENANT_ID"Call GET /api/v1/boards/{id} to read that board’s lanes, labels and projects. Use the board and lane IDs when creating a task:
curl "$UTSUROI_API_URL/api/v1/tasks" \ -H "Authorization: Bearer $UTSUROI_API_TOKEN" \ -H "X-Tenant-Id: $UTSUROI_TENANT_ID" \ -H 'Content-Type: application/json' \ --data '{"id":"your-unique-id","boardId":"your-board-id","laneId":"your-lane-id","title":"Created using the API"}'Omit id to generate one on the server. Creating with an existing ID returns 409 and never overwrites the task. Supplying your own unique ID lets you retrieve that ID to check the outcome after an ambiguous network failure.
Update and retrieve
Section titled “Update and retrieve”- Use
PATCH /api/v1/tasks/{id}for base fields. Omitted fields remain unchanged;nullclears nullable fields. Description edits preserve assignees, labels and comments. - PUT to
/assigneesor/labelsreplaces the complete respective set. - POST to
/start,/completeor/reopenapplies lifecycle transitions, including lane, timestamp and history changes. /move-to-boardcopies the task to the destination with a new ID, then archives the original. It does not preserve the original ID.- Use
/commentsfor comments and/comments/{commentId}/reactionsfor reactions. Only the author may edit or delete a comment.
Calendar dates use YYYY-MM-DD. Creation, update, start and completion timestamps use Unix epoch milliseconds. Unset task fields are returned as null. Task lists and details use the same task representation, including timestamps, parent and assignee fields. Retrieve comments separately.
Pagination and search
Section titled “Pagination and search”Task, board, member and comment lists default to 50 items and allow at most 100. Set limit, then pass the returned nextCursor as cursor for the next page. nextCursor: null marks the last page.
Lists sort by creation time ascending, then by ID for ties; comments use their posting time. Search task titles and descriptions using q, and filter by boardId, laneId, parentId, assigneeId, labelId or projectId. Set archived to exclude (default), include or only.
Keep the same filters on subsequent pages. Cursors are bound to the workspace, caller, list and filters, and cannot be reused for a different query. Only matching tasks are included; parents and children are not automatically added. Concurrent additions, deletions and changes to matching fields can affect subsequent pages. Pagination does not provide a database snapshot.
Errors and compatibility
Section titled “Errors and compatibility”Errors use { "error": { "code": "…", "message": "…" } }. Branch on the HTTP status and code.
- 400: invalid input or cursor.
- 401: invalid token. 402: workspace plan restrictions block the operation.
- 403: insufficient token or user permissions.
- 404: resource not found. 409: conflicting ID or state. 422: invalid reference or operation.
- 429: rate limit exceeded. Wait the number of seconds in
Retry-After. Read and write allowances are separate; a user’s tokens share the allowance within the workspace.
The limit is per minute and depends on the plan.
| Plan | Reads | Writes |
|---|---|---|
| Free | 60 | 30 |
| Pro | 600 | 300 |
Existing inputs, outputs and operation semantics remain compatible within v1. Optional response fields and new operations may be added; ignore unknown response fields. Incompatible changes require a new major version with an announced migration period.
Board, lane, label and project configuration changes, attachment operations, administration, billing and Slack settings are outside this REST API. See agent integrations for MCP.