Skip to content

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.

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.

These examples use UTSUROI_API_URL for the backend origin, UTSUROI_TENANT_ID for the workspace ID and UTSUROI_API_TOKEN for the token.

Terminal window
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:

Terminal window
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.

  • Use PATCH /api/v1/tasks/{id} for base fields. Omitted fields remain unchanged; null clears nullable fields. Description edits preserve assignees, labels and comments.
  • PUT to /assignees or /labels replaces the complete respective set.
  • POST to /start, /complete or /reopen applies lifecycle transitions, including lane, timestamp and history changes.
  • /move-to-board copies the task to the destination with a new ID, then archives the original. It does not preserve the original ID.
  • Use /comments for comments and /comments/{commentId}/reactions for 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.

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 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.