API
UTasks Developer API
Section titled “UTasks Developer API”A public API for integrating third-party services with UTasks.
Getting started
Section titled “Getting started”Base URL
Section titled “Base URL”https://app.utasks.io/utbAll endpoints start with the /pub/v1/ prefix.
Authentication
Section titled “Authentication”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_xxxxxxxxxxxxxxxxChecking the connection
Section titled “Checking the connection”Make sure the key works – request your profile:
GET /utb/pub/v1/profileAuthorization: Bearer utb_...Endpoints
Section titled “Endpoints”Profile
Section titled “Profile”GET /pub/v1/profile
Section titled “GET /pub/v1/profile”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
Section titled “Projects”GET /pub/v1/projects
Section titled “GET /pub/v1/projects”Projects the current user is a member of.
Response 200 – an array of PubProjectModel
GET /pub/v1/projects/{id}
Section titled “GET /pub/v1/projects/{id}”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
GET /pub/v1/projects/{id}/users
Section titled “GET /pub/v1/projects/{id}/users”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
GET /pub/v1/tasks
Section titled “GET /pub/v1/tasks”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=TodayAuthorization: Bearer utb_...GET /utb/pub/v1/tasks?projectId=abc123&completed=falseAuthorization: Bearer utb_...POST /pub/v1/tasks
Section titled “POST /pub/v1/tasks”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 /pub/v1/tasks/{id}
Section titled “GET /pub/v1/tasks/{id}”Get a task by ID.
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id |
string | ✓ | Task ID |
Response 200 – a PubTaskModel object
PATCH /pub/v1/tasks/{id}
Section titled “PATCH /pub/v1/tasks/{id}”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 /pub/v1/tasks/{id}
Section titled “DELETE /pub/v1/tasks/{id}”Delete a task. Allowed for the task author and project administrators.
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id |
string | ✓ | Task ID |
POST /pub/v1/tasks/{id}/complete
Section titled “POST /pub/v1/tasks/{id}/complete”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 |
POST /pub/v1/tasks/{id}/uncomplete
Section titled “POST /pub/v1/tasks/{id}/uncomplete”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 |
GET /pub/v1/tasks/{id}/history
Section titled “GET /pub/v1/tasks/{id}/history”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
POST /pub/v1/tasks/{id}/attachassignee
Section titled “POST /pub/v1/tasks/{id}/attachassignee”Add the current user (the API key owner) as a task assignee.
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id |
string | ✓ | Task ID |
POST /pub/v1/tasks/{id}/publish
Section titled “POST /pub/v1/tasks/{id}/publish”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 |
POST /pub/v1/tasks/{id}/comments
Section titled “POST /pub/v1/tasks/{id}/comments”Add a text comment to a task.
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id |
string | ✓ | Task ID |
Request body – PubCommentRequest
{ "text": "Done, please check"}Data models
Section titled “Data models”PubProfileModel
Section titled “PubProfileModel”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 |
PubProjectModel
Section titled “PubProjectModel”| Field | Type | Description |
|---|---|---|
id |
string | Project ID |
name |
string | Project name |
description |
string | Description |
type |
UTProjectType |
Project type |
PubProjectUserModel
Section titled “PubProjectUserModel”| Field | Type | Description |
|---|---|---|
id |
string | User ID |
userName |
string | Username |
title |
string | Display name |
status |
UTUserStatus |
Member status in the project |
PubUserModel
Section titled “PubUserModel”Brief user information (used inside tasks).
| Field | Type | Description |
|---|---|---|
id |
string | User ID |
userName |
string | Username |
title |
string | Display name |
PubTaskModel
Section titled “PubTaskModel”| 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 |
PubCreateTaskRequest
Section titled “PubCreateTaskRequest”| 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 |
PubUpdateTaskRequest
Section titled “PubUpdateTaskRequest”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) |
PubCommentRequest
Section titled “PubCommentRequest”| Field | Type | Required | Description |
|---|---|---|---|
text |
string | ✓ | Comment text |
PubCommentModel
Section titled “PubCommentModel”| Field | Type | Description |
|---|---|---|
text |
string | Comment text |
createDate |
string (ISO 8601) | Creation date |
PubTaskHistoryItemModel
Section titled “PubTaskHistoryItemModel”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 |
PubTaskHistoryChangeModel
Section titled “PubTaskHistoryChangeModel”| Field | Type | Description |
|---|---|---|
field |
string | Name of the changed field |
oldValue |
string | Old value |
newValue |
string | New value |
Enumerations
Section titled “Enumerations”UTTaskStatus
Section titled “UTTaskStatus”Task status.
| Value | Description |
|---|---|
New |
New |
ToDo |
To Do |
InProgress |
In Progress |
Resolved |
Resolved |
Review |
In Review |
Approved |
Approved |
Closed |
Closed |
UTTaskPriority
Section titled “UTTaskPriority”Task priority.
| Value | Description |
|---|---|
None |
Not set |
Lowest |
Lowest |
Low |
Low |
Medium |
Medium |
High |
High |
Highest |
Highest |
UTProjectType
Section titled “UTProjectType”Project type.
| Value | Description |
|---|---|
Private |
Private |
Public |
Public |
Dynamic |
Dynamic |
UTUserStatus
Section titled “UTUserStatus”Member role in the project.
| Value | Description |
|---|---|
None |
No role |
Creator |
Creator |
Administrator |
Administrator |
Member |
Member |
PubTaskScope
Section titled “PubTaskScope”Task filter scope.
| Value | Description |
|---|---|
All |
All tasks |
Inbox |
Inbox |
Today |
Due today |
Tomorrow |
Due tomorrow |
Week |
Due this week |
Completed |
Completed |
Usage examples
Section titled “Usage examples”Get today’s tasks
Section titled “Get today’s tasks”GET /utb/pub/v1/tasks?scope=TodayAuthorization: Bearer utb_...Create a task in the personal inbox
Section titled “Create a task in the personal inbox”POST /utb/pub/v1/tasksAuthorization: Bearer utb_...Content-Type: application/json
{ "title": "Call the client", "planDate": "2025-08-01T10:00:00Z", "priority": "High"}Create a task in a project with assignees
Section titled “Create a task in a project with assignees”POST /utb/pub/v1/tasksAuthorization: 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"}Move a task to “In Progress”
Section titled “Move a task to “In Progress””PATCH /utb/pub/v1/tasks/task_xyzAuthorization: Bearer utb_...Content-Type: application/json
{ "status": "InProgress"}Complete a task
Section titled “Complete a task”POST /utb/pub/v1/tasks/task_xyz/completeAuthorization: Bearer utb_...Add a comment
Section titled “Add a comment”POST /utb/pub/v1/tasks/task_xyz/commentsAuthorization: Bearer utb_...Content-Type: application/json
{ "text": "Done, waiting for your review"}Error codes
Section titled “Error codes”| 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"}