API

UTasks Developer API

Public API for integrating third-party services with UTasks.

Getting Started

Base URL

https://app.utasks.io/utb

All endpoints are prefixed with/pub/v1/.

Authentication

The API uses Bearer token authentication.

To get a new key, send the/apikey new command to the @UTasksBot.

Pass the key in every request header:

Authorization: Bearer utb_xxxxxxxxxxxxxxxx

Verify the Connection

Confirm your key is working by requesting your profile:

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

Endpoints

Profile

GET /pub/v1/profile

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

Response 200—PubProfileModel

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

Projects

GET /pub/v1/projects

Returns a list of projects the current user is a member of.

Response 200— array ofPubProjectModel

GET /pub/v1/projects/{id}

Get a project by ID. Only available for projects the user is a member of.

Path parameters

Parameter

Type

Required

Description

id

string

✓

Project ID

Response 200—PubProjectModel

GET /pub/v1/projects/{id}/users

List project members with their statuses. Only available for projects the user belongs to.

Path parameters

Parameter

Type

Required

Description

id

string

✓

Project ID

Response 200— array ofPubProjectUserModel

Tasks

GET /pub/v1/tasks

Returns the current user's tasks — filtered by scope or project.

Query parameters

Parameter

Type

Description

scope

PubTaskScope

Task scope (default:All). Ignored ifprojectIdis set

projectId

string

Project ID; requires active membership

completed

boolean

true— return completed tasks instead of open ones

q

string

Search query (searches by title)

Response 200— array ofPubTaskModel

Examples

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

POST /pub/v1/tasks

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

Request body—PubCreateTaskRequest

Response 200—PubTaskModel

Example

{
  "title": "Prepare the 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}

Get a task by ID.

Path parameters

Parameter

Type

Required

Description

id

string

✓

Task ID

Response 200—PubTaskModel

PATCH /pub/v1/tasks/{id}

Partially update a task. Only fields that are passed (non-null) are updated. An emptyassigneeIdslist removes all assignees.

Path parameters

Parameter

Type

Required

Description

id

string

✓

Task ID

Request body—PubUpdateTaskRequest

Response 200—PubTaskModel

Example — update status and priority

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

Example — clear the planned date

{
  "clearPlanDate": true
}

DELETE /pub/v1/tasks/{id}

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

Path parameters

Parameter

Type

Required

Description

id

string

✓

Task ID

POST /pub/v1/tasks/{id}/complete

Mark a task as complete. The author closes the task for everyone; an assignee marks only their own part — the task closes globally once all assignees have marked their part done. Available to the author and assignees.

Path parameters

Parameter

Type

Required

Description

id

string

✓

Task ID

POST /pub/v1/tasks/{id}/uncomplete

Reopen a completed task for all participants; status resets toNew. Available to the author and assignees.

Path parameters

Parameter

Type

Required

Description

id

string

✓

Task ID

GET /pub/v1/tasks/{id}/history

Task change history and comments, sorted oldest-first by default.

Path parameters

Parameter

Type

Required

Description

id

string

✓

Task ID

Query parameters

Parameter

Type

Description

filter

string

History record filter

sort

string

Sort order

Response 200— array ofPubTaskHistoryItemModel

POST /pub/v1/tasks/{id}/attachassignee

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

Path parameters

Parameter

Type

Required

Description

id

string

✓

Task ID

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

Add a text comment to a task.

Path parameters

Parameter

Type

Required

Description

id

string

✓

Task ID

Request body—PubCommentRequest

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

Data Models

PubProfileModel

Profile of the API key owner.

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

Field

Type

Description

id

string

Project ID

name

string

Project name

description

string

Description

type

UTProjectType

Project type

PubProjectUserModel

Field

Type

Description

id

string

User ID

userName

string

Username

title

string

Display name

status

UTUserStatus

Member status in the project

PubUserModel

Abbreviated user info used inside tasks.

Field

Type

Description

id

string

User ID

userName

string

Username

title

string

Display name

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;nullfor personal inbox tasks

projectName

string | null

Project name;nullfor personal inbox

planDate

string | null

Planned date (ISO 8601)

planCron

string | null

Planned date recurrence rule

dueDate

string | null

Deadline (ISO 8601)

isCompleted

boolean

Task is globally complete. For multi-assignee tasks, becomestrueonly after every assignee has marked their part done

completedDate

string | null

Completion date

completedUserIds

string[]

IDs of assignees who have marked their part done

personalCompleted

boolean

Task is complete for the current user: either globally closed, or the user has marked their own part done

author

PubUserModel

Task author

assignees

PubUserModel[]

Assignees

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 for personal inbox

planDate

string | null

Planned date (ISO 8601)

dueDate

string | null

Deadline; cannot be earlier than the planned date

planCron

string | null

Planned date recurrence rule

priority

UTTaskPriority

Priority

assigneeIds

string[] | null

Assignee IDs; must be project members

PubUpdateTaskRequest

All fields are optional. Pass only the fields 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 overplanDate)

clearDueDate

boolean

Clear the deadline (takes precedence overdueDate)

planCron

string | null

New recurrence rule

priority

UTTaskPriority

New priority

status

UTTaskStatus

New status

assigneeIds

string[] | null

Full updated assignee list (empty array removes all assignees)

PubCommentRequest

Field

Type

Required

Description

text

string

✓

Comment text

PubCommentModel

Field

Type

Description

text

string

Comment text

createDate

string (ISO 8601)

Creation date

PubTaskHistoryItemModel

A task change history record.

Field

Type

Description

date

string (ISO 8601)

Event date

author

PubUserModel

Author of the change

comment

string

Comment text (if this record is a comment)

change

PubTaskHistoryChangeModel

Field change data

PubTaskHistoryChangeModel

Field

Type

Description

field

string

Name of the changed field

oldValue

string

Previous value

newValue

string

New value

Enumerations

UTTaskStatus

Value

Description

New

New

ToDo

To Do

InProgress

In Progress

Resolved

Resolved

Review

In Review

Approved

Approved

Closed

Closed

UTTaskPriority

Value

Description

None

Not set

Lowest

Lowest

Low

Low

Medium

Medium

High

High

Highest

Highest

UTProjectType

Value

Description

Private

Private

Public

Public

Dynamic

Dynamic

UTUserStatus

Value

Description

None

No role

Creator

Creator

Administrator

Administrator

Member

Member

PubTaskScope

Value

Description

All

All tasks

Inbox

Inbox

Today

Due today

Tomorrow

Due tomorrow

Week

Due this week

Completed

Completed

Usage Examples

Get today's tasks

GET /utb/pub/v1/tasks?scope=Today
Authorization: Bearer utb_...

Create a task in the personal inbox

POST /utb/pub/v1/tasks
Authorization: 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

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"
}

Move a task to In Progress

PATCH /utb/pub/v1/tasks/task_xyz
Authorization: Bearer utb_...
Content-Type: application/json
{
  "status": "InProgress"
}

Complete a task

POST /utb/pub/v1/tasks/task_xyz/complete
Authorization: Bearer utb_...

Add a comment

POST /utb/pub/v1/tasks/task_xyz/comments
Authorization: Bearer utb_...
Content-Type: application/json
{
  "text": "Done — waiting for your review"
}

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

Error responses follow theProblemDetailsformat:

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