Skip to content

API

A public API for integrating third-party services with UTasks.


https://app.utasks.io/utb

All endpoints start with the /pub/v1/ prefix.

The API uses a Bearer token. To get a key, send the command /apikey new to @UTasksBot.

Pass the key in the header of every request:

Authorization: Bearer utb_xxxxxxxxxxxxxxxx

Make sure the key works – request your profile:

GET /utb/pub/v1/profile
Authorization: Bearer utb_...

Returns the profile of the API key owner. Handy as a connection check.

Response 200 – a PubProfileModel object

{
"userId": "abc123",
"userName": "ivan",
"title": "Ivan Petrov",
"role": "PRO",
"roleExpireDate": "2025-12-31T00:00:00Z",
"locale": "ru",
"timeZone": "Europe/Moscow",
"timeZoneId": 3
}

Projects the current user is a member of.

Response 200 – an array of PubProjectModel


Get a project by ID. Available only for projects the user is a member of.

Path parameters

Parameter Type Required Description
id string ✓ Project ID

Response 200 – a PubProjectModel object


Project members with their statuses. Available only for projects the user is a member of.

Path parameters

Parameter Type Required Description
id string ✓ Project ID

Response 200 – an array of PubProjectUserModel


The current user’s tasks – by scope or by project.

Query parameters

Parameter Type Description
scope PubTaskScope Task scope (All by default). Ignored if projectId is set
projectId string Project ID; requires active membership
completed boolean true – return completed tasks instead of open ones
q string Search query (searches titles)

Response 200 – an array of PubTaskModel

Example

GET /utb/pub/v1/tasks?scope=Today
Authorization: Bearer utb_...
GET /utb/pub/v1/tasks?projectId=abc123&completed=false
Authorization: Bearer utb_...

Create a task in a project or in the personal inbox. Sends the same messenger notifications as tasks created in the app.

Request body – PubCreateTaskRequest

Response 200 – a PubTaskModel object

Example

{
"title": "Prepare a report",
"description": "Quarterly metrics report",
"projectId": "abc123",
"planDate": "2025-08-01T09:00:00Z",
"dueDate": "2025-08-05T18:00:00Z",
"priority": "High",
"assigneeIds": ["user1", "user2"]
}

Get a task by ID.

Path parameters

Parameter Type Required Description
id string ✓ Task ID

Response 200 – a PubTaskModel object


Partial task update. Only the fields you pass (not null) are updated. An empty assigneeIds list removes all assignees.

Path parameters

Parameter Type Required Description
id string ✓ Task ID

Request body – PubUpdateTaskRequest

Response 200 – a PubTaskModel object

Example – change the status and priority

{
"status": "InProgress",
"priority": "Highest"
}

Example – clear the planned date

{
"clearPlanDate": true
}

Delete a task. Allowed for the task author and project administrators.

Path parameters

Parameter Type Required Description
id string ✓ Task ID

Mark a task as completed. The author closes the whole task; an assignee marks only their own part – the task is closed globally once all assignees have completed their parts. Available to the author and assignees.

Path parameters

Parameter Type Required Description
id string ✓ Task ID

Reopen a completed task for all participants; the status is reset to New. Available to the author and assignees.

Path parameters

Parameter Type Required Description
id string ✓ Task ID

Task change history and comments, from oldest to newest by default.

Path parameters

Parameter Type Required Description
id string ✓ Task ID

Query parameters

Parameter Type Description
filter string History entry filter
sort string Entry sort order

Response 200 – an array of PubTaskHistoryItemModel


Add the current user (the API key owner) as a task assignee.

Path parameters

Parameter Type Required Description
id string ✓ Task ID

Publish the task card as a message to the project chat (for public projects) or to the author’s personal chat.

Path parameters

Parameter Type Required Description
id string ✓ Task ID

Add a text comment to a task.

Path parameters

Parameter Type Required Description
id string ✓ Task ID

Request body – PubCommentRequest

{
"text": "Done, please check"
}

Profile of the user who owns the API key.

Field Type Description
userId string User ID
userName string Username
title string Display name
role string Plan / role
roleExpireDate string (ISO 8601) Plan expiry date
locale string Interface language
timeZone string Time zone (IANA)
timeZoneId number Time zone ID

Field Type Description
id string Project ID
name string Project name
description string Description
type UTProjectType Project type

Field Type Description
id string User ID
userName string Username
title string Display name
status UTUserStatus Member status in the project

Brief user information (used inside tasks).

Field Type Description
id string User ID
userName string Username
title string Display name

Field Type Description
id string Task ID
number string Human-readable task number, e.g. UT-12
title string Task title
description string Description
status UTTaskStatus Status
priority UTTaskPriority Priority
projectId string | null Project ID; null for personal inbox tasks
projectName string | null Project name; null for the personal inbox
planDate string | null Planned date (ISO 8601)
planCron string | null Recurrence rule for the planned date
dueDate string | null Deadline (ISO 8601)
isCompleted boolean The task is completed globally. For tasks with several assignees, it becomes true only after each of them has marked their part
completedDate string | null Completion date
completedUserIds string[] IDs of the assignees who have marked their part as completed
personalCompleted boolean The task is completed for the current user: either completed globally, or the user has marked their part
author PubUserModel Task author
assignees PubUserModel[] Assignees

Field Type Required Description
title string ✓ Task title, up to 5000 characters
description string | null Description, up to 5000 characters
projectId string | null Project ID; omit it for the personal inbox
planDate string | null Planned date (ISO 8601)
dueDate string | null Deadline; cannot be earlier than the planned date
planCron string | null Recurrence rule for the planned date
priority UTTaskPriority Priority
assigneeIds string[] | null Assignee IDs. They must be project members

All fields are optional. Pass only the ones you want to change.

Field Type Description
title string | null New title, up to 5000 characters
description string | null New description, up to 5000 characters
planDate string | null New planned date
dueDate string | null New deadline; cannot be earlier than the planned date
clearPlanDate boolean Clear the planned date (takes precedence over planDate)
clearDueDate boolean Clear the deadline (takes precedence over dueDate)
planCron string | null New recurrence rule
priority UTTaskPriority New priority
status UTTaskStatus New status
assigneeIds string[] | null New full list of assignees (an empty array removes everyone)

Field Type Required Description
text string ✓ Comment text

Field Type Description
text string Comment text
createDate string (ISO 8601) Creation date

A task change history entry.

Field Type Description
date string (ISO 8601) Event date
author PubUserModel Author of the change
comment string Comment text (if this is a comment)
change PubTaskHistoryChangeModel Field change details

Field Type Description
field string Name of the changed field
oldValue string Old value
newValue string New value

Task status.

Value Description
New New
ToDo To Do
InProgress In Progress
Resolved Resolved
Review In Review
Approved Approved
Closed Closed

Task priority.

Value Description
None Not set
Lowest Lowest
Low Low
Medium Medium
High High
Highest Highest

Project type.

Value Description
Private Private
Public Public
Dynamic Dynamic

Member role in the project.

Value Description
None No role
Creator Creator
Administrator Administrator
Member Member

Task filter scope.

Value Description
All All tasks
Inbox Inbox
Today Due today
Tomorrow Due tomorrow
Week Due this week
Completed Completed

GET /utb/pub/v1/tasks?scope=Today
Authorization: Bearer utb_...
POST /utb/pub/v1/tasks
Authorization: Bearer utb_...
Content-Type: application/json
{
"title": "Call the client",
"planDate": "2025-08-01T10:00:00Z",
"priority": "High"
}
POST /utb/pub/v1/tasks
Authorization: Bearer utb_...
Content-Type: application/json
{
"title": "Review PR #42",
"projectId": "proj_abc",
"assigneeIds": ["user_1", "user_2"],
"dueDate": "2025-08-03T18:00:00Z",
"priority": "Medium"
}
PATCH /utb/pub/v1/tasks/task_xyz
Authorization: Bearer utb_...
Content-Type: application/json
{
"status": "InProgress"
}
POST /utb/pub/v1/tasks/task_xyz/complete
Authorization: Bearer utb_...
POST /utb/pub/v1/tasks/task_xyz/comments
Authorization: Bearer utb_...
Content-Type: application/json
{
"text": "Done, waiting for your review"
}

Code Description
400 Bad request – check the request body
401 Unauthorized – check your API key
403 Forbidden – insufficient permissions for this action
404 Object not found
500 Internal server error

The error body is returned in the ProblemDetails format:

{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "Bad Request",
"status": 400,
"detail": "Title is required"
}