API

UTasks Developer API

Публичный API для интеграции сторонних сервисов с UTasks.

Начало работы

Базовый URL

https://app.utasks.io/utb

Все эндпоинты начинаются с префикса/pub/v1/.

Аутентификация

API использует Bearer-токен. Чтобы получить ключ, отправьте команду/apikey new в @UTasksBot.

Передавайте ключ в заголовке каждого запроса:

Authorization: Bearer utb_xxxxxxxxxxxxxxxx

Проверка подключения

Убедитесь, что ключ работает — запросите профиль:

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

Эндпоинты

Профиль

GET /pub/v1/profile

Возвращает профиль владельца API-ключа. Удобно использовать как проверку соединения.

Ответ200— объект PubProfileModel

{
  "userId": "abc123",
  "userName": "ivan",
  "title": "Иван Петров",
  "role": "PRO",
  "roleExpireDate": "2025-12-31T00:00:00Z",
  "locale": "ru",
  "timeZone": "Europe/Moscow",
  "timeZoneId": 3
}

Проекты

GET /pub/v1/projects

Список проектов, в которых состоит текущий пользователь.

Ответ200— массив PubProjectModel

GET /pub/v1/projects/{id}

Получить проект по идентификатору. Доступно только для проектов, в которых пользователь является участником.

Параметры пути

Ответ200— объект PubProjectModel

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

Список участников проекта с их статусами. Доступно только для проектов, в которых пользователь состоит.

Параметры пути

Ответ200— массив PubProjectUserModel

Задачи

GET /pub/v1/tasks

Список задач текущего пользователя — по области или по проекту.

Параметры запроса

Ответ200— массив PubTaskModel

Пример

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

Создать задачу в проекте или в личном инбоксе. Отправляет те же уведомления в мессенджер, что и задачи из приложения.

Тело запроса—PubCreateTaskRequest

Ответ200— объект PubTaskModel

Пример

{
  "title": "Подготовить отчёт",
  "description": "Квартальный отчёт по метрикам",
  "projectId": "abc123",
  "planDate": "2025-08-01T09:00:00Z",
  "dueDate": "2025-08-05T18:00:00Z",
  "priority": "High",
  "assigneeIds": ["user1", "user2"]
}

GET /pub/v1/tasks/{id}

Получить задачу по идентификатору.

Параметры пути

Ответ200— объект PubTaskModel

PATCH /pub/v1/tasks/{id}

Частичное обновление задачи. Обновляются только переданные (неnull) поля. Пустой список assigneeIds удаляет всех исполнителей.

Параметры пути

Тело запроса — PubUpdateTaskRequest

Ответ200— объект PubTaskModel

Пример — изменить статус и приоритет

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

Пример — очистить плановую дату

{
  "clearPlanDate": true
}

DELETE /pub/v1/tasks/{id}

Удалить задачу. Разрешено автору задачи и администраторам проекта.

Параметры пути

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

Отметить задачу как выполненную. Автор закрывает задачу целиком; исполнитель отмечает только свою часть — задача закрывается глобально, когда все исполнители выполнили свою часть. Доступно автору и исполнителям.

Параметры пути

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

Переоткрыть выполненную задачу для всех участников; статус сбрасывается вNew. Доступно автору и исполнителям.

Параметры пути

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

История изменений задачи и комментарии, по умолчанию от старых к новым.

Параметры пути

Параметры запроса

Ответ200— массив PubTaskHistoryItemModel

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

Добавить текущего пользователя (владельца API-ключа) как исполнителя задачи.

Параметры пути

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

Опубликовать карточку задачи как сообщение в чат проекта (для публичных проектов) или в личный чат автора.

Параметры пути

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

Добавить текстовый комментарий к задаче.

Параметры пути

Тело запроса—PubCommentRequest

{
  "text": "Готово, проверьте пожалуйста"
}

Объекты данных

PubProfileModel

Профиль пользователя — владельца API-ключа.

PubProjectModel

PubProjectUserModel

PubUserModel

Краткая информация о пользователе (используется внутри задач).

PubTaskModel

PubCreateTaskRequest

PubUpdateTaskRequest

Все поля опциональны. Передавайте только те, которые нужно изменить.

PubCommentRequest

PubCommentModel

PubTaskHistoryItemModel

Запись истории изменений задачи.

PubTaskHistoryChangeModel

Перечисления

UTTaskStatus

Статус задачи.

UTTaskPriority

Приоритет задачи.

UTProjectType

Тип проекта.

UTUserStatus

Роль участника в проекте.

PubTaskScope

Область фильтрации задач.

Примеры сценариев

Получить задачи на сегодня

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

Создать задачу в личном инбоксе

POST /utb/pub/v1/tasks
Authorization: Bearer utb_...
Content-Type: application/json

{
  "title": "Позвонить клиенту",
  "planDate": "2025-08-01T10:00:00Z",
  "priority": "High"
}

Создать задачу в проекте с исполнителями

POST /utb/pub/v1/tasks
Authorization: Bearer utb_...
Content-Type: application/json

{
  "title": "Ревью 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": "Готово, жду вашего ревью"
}

Коды ошибок

Тело ошибки возвращается в формате ProblemDetails:

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