API

UTasks Developer API

Үшінші тарап сервистерін UTasks-пен біріктіруге арналған ашық API.

Жұмысты бастау

Негізгі URL

https://app.utasks.io/utb

Барлық эндпоинт /pub/v1/ префиксінен басталады.

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

API Bearer токенін пайдаланады. Кілт алу үшін @UTasksBot ботына /apikey new командасын жіберіңіз.

Кілтті әр сұраудың тақырыбында жіберіңіз:

Authorization: Bearer utb_xxxxxxxxxxxxxxxx

Қосылымды тексеру

Кілттің жұмыс істейтініне көз жеткізіңіз – профиліңізді сұраңыз:

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

Эндпоинттер

Профиль

`GET /pub/v1/profile`

API кілті иесінің профилін қайтарады. Қосылымды тексеру үшін ыңғайлы.

Жауап 200 – PubProfileModel нысаны

{
  "userId": "abc123",
  "userName": "ivan",
  "title": "Ivan Petrov",
  "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}`

Жобаны ID бойынша алу. Тек пайдаланушы мүшесі болып табылатын жобалар үшін қолжетімді.

Жол параметрлері

Параметр	Түрі	Міндетті	Сипаттамасы
`id`	string	✓	Жоба ID-і

Жауап 200 – PubProjectModel нысаны

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

Жоба мүшелері және олардың мәртебелері. Тек пайдаланушы мүшесі болып табылатын жобалар үшін қолжетімді.

Жол параметрлері

Параметр	Түрі	Міндетті	Сипаттамасы
`id`	string	✓	Жоба ID-і

Жауап 200 – PubProjectUserModel массиві

Тапсырмалар

`GET /pub/v1/tasks`

Ағымдағы пайдаланушының тапсырмалары – аумақ немесе жоба бойынша.

Сұрау параметрлері

Параметр	Түрі	Сипаттамасы
`scope`	`PubTaskScope`	Тапсырмалар аумағы (әдепкі бойынша `All`). `projectId` берілсе, ескерілмейді
`projectId`	string	Жоба ID-і; белсенді мүшелікті талап етеді
`completed`	boolean	`true` – ашықтардың орнына орындалған тапсырмаларды қайтару
`q`	string	Іздеу сұрауы (атаулар бойынша іздейді)

Жауап 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}`

Тапсырманы ID бойынша алу.

Жол параметрлері

Параметр	Түрі	Міндетті	Сипаттамасы
`id`	string	✓	Тапсырма ID-і

Жауап 200 – PubTaskModel нысаны

`PATCH /pub/v1/tasks/{id}`

Тапсырманы ішінара жаңарту. Тек жіберілген (null емес) өрістер жаңартылады. Бос assigneeIds тізімі барлық орындаушыны алып тастайды.

Жол параметрлері

Параметр	Түрі	Міндетті	Сипаттамасы
`id`	string	✓	Тапсырма ID-і

Сұрау мазмұны – PubUpdateTaskRequest

Жауап 200 – PubTaskModel нысаны

Мысал – күй мен басымдықты өзгерту

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

Мысал – жоспарланған күнді тазалау

{
  "clearPlanDate": true
}

`DELETE /pub/v1/tasks/{id}`

Тапсырманы жою. Тапсырма авторына және жоба әкімшілеріне рұқсат етілген.

Жол параметрлері

Параметр	Түрі	Міндетті	Сипаттамасы
`id`	string	✓	Тапсырма ID-і

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

Тапсырманы орындалды деп белгілеу. Автор бүкіл тапсырманы жабады; орындаушы тек өз бөлігін белгілейді – барлық орындаушы өз бөлігін орындағанда тапсырма толығымен жабылады. Автор мен орындаушыларға қолжетімді.

Жол параметрлері

Параметр	Түрі	Міндетті	Сипаттамасы
`id`	string	✓	Тапсырма ID-і

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

Орындалған тапсырманы барлық қатысушы үшін қайта ашу; күй New мәніне қайтарылады. Автор мен орындаушыларға қолжетімді.

Жол параметрлері

Параметр	Түрі	Міндетті	Сипаттамасы
`id`	string	✓	Тапсырма ID-і

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

Тапсырма өзгерістерінің тарихы мен пікірлер, әдепкі бойынша ескісінен жаңасына қарай.

Жол параметрлері

Параметр	Түрі	Міндетті	Сипаттамасы
`id`	string	✓	Тапсырма ID-і

Сұрау параметрлері

Параметр	Түрі	Сипаттамасы
`filter`	string	Тарих жазбаларының сүзгісі
`sort`	string	Жазбаларды сұрыптау тәртібі

Жауап 200 – PubTaskHistoryItemModel массиві

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

Ағымдағы пайдаланушыны (API кілтінің иесін) тапсырманың орындаушысы ретінде қосу.

Жол параметрлері

Параметр	Түрі	Міндетті	Сипаттамасы
`id`	string	✓	Тапсырма ID-і

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

Тапсырма картасын жоба чатына (ашық жобалар үшін) немесе автордың жеке чатына хабарлама ретінде жариялау.

Жол параметрлері

Параметр	Түрі	Міндетті	Сипаттамасы
`id`	string	✓	Тапсырма ID-і

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

Тапсырмаға мәтіндік пікір қосу.

Жол параметрлері

Параметр	Түрі	Міндетті	Сипаттамасы
`id`	string	✓	Тапсырма ID-і

Сұрау мазмұны – PubCommentRequest

{
  "text": "Дайын, тексеріп көріңіз"
}

Деректер модельдері

PubProfileModel

API кілті иесінің профилі.

Өріс	Түрі	Сипаттамасы
`userId`	string	Пайдаланушы ID-і
`userName`	string	Пайдаланушы аты
`title`	string	Көрсетілетін аты
`role`	string	Тариф / рөл
`roleExpireDate`	string (ISO 8601)	Тарифтің аяқталу күні
`locale`	string	Интерфейс тілі
`timeZone`	string	Уақыт белдеуі (IANA)
`timeZoneId`	number	Уақыт белдеуінің ID-і

PubProjectModel

Өріс	Түрі	Сипаттамасы
`id`	string	Жоба ID-і
`name`	string	Жоба атауы
`description`	string	Сипаттама
`type`	`UTProjectType`	Жоба түрі

PubProjectUserModel

Өріс	Түрі	Сипаттамасы
`id`	string	Пайдаланушы ID-і
`userName`	string	Пайдаланушы аты
`title`	string	Көрсетілетін аты
`status`	`UTUserStatus`	Мүшенің жобадағы мәртебесі

PubUserModel

Пайдаланушы туралы қысқаша ақпарат (тапсырмалардың ішінде пайдаланылады).

Өріс	Түрі	Сипаттамасы
`id`	string	Пайдаланушы ID-і
`userName`	string	Пайдаланушы аты
`title`	string	Көрсетілетін аты

PubTaskModel

Өріс	Түрі	Сипаттамасы
`id`	string	Тапсырма ID-і
`number`	string	Тапсырманың оқуға ыңғайлы нөмірі, мысалы `UT-12`
`title`	string	Тапсырма атауы
`description`	string	Сипаттама
`status`	`UTTaskStatus`	Күй
`priority`	`UTTaskPriority`	Басымдық
`projectId`	string \| null	Жоба ID-і; жеке «Кіріс» тапсырмалары үшін `null`
`projectName`	string \| null	Жоба атауы; жеке «Кіріс» үшін `null`
`planDate`	string \| null	Жоспарланған күн (ISO 8601)
`planCron`	string \| null	Жоспарланған күннің қайталану ережесі
`dueDate`	string \| null	Мерзім (ISO 8601)
`isCompleted`	boolean	Тапсырма толығымен орындалды. Бірнеше орындаушысы бар тапсырмаларда әрқайсысы өз бөлігін белгілегеннен кейін ғана `true` болады
`completedDate`	string \| null	Орындалған күні
`completedUserIds`	string[]	Өз бөлігін орындалды деп белгілеген орындаушылардың ID-лері
`personalCompleted`	boolean	Тапсырма ағымдағы пайдаланушы үшін орындалды: не толығымен орындалды, не пайдаланушы өз бөлігін белгіледі
`author`	`PubUserModel`	Тапсырма авторы
`assignees`	`PubUserModel[]`	Орындаушылар

PubCreateTaskRequest

Өріс	Түрі	Міндетті	Сипаттамасы
`title`	string	✓	Тапсырма атауы, 5000 таңбаға дейін
`description`	string \| null		Сипаттама, 5000 таңбаға дейін
`projectId`	string \| null		Жоба ID-і; жеке «Кіріс» үшін көрсетпеңіз
`planDate`	string \| null		Жоспарланған күн (ISO 8601)
`dueDate`	string \| null		Мерзім; жоспарланған күннен ерте болмауы керек
`planCron`	string \| null		Жоспарланған күннің қайталану ережесі
`priority`	`UTTaskPriority`		Басымдық
`assigneeIds`	string[] \| null		Орындаушылардың ID-лері. Олар жоба мүшелері болуы керек

PubUpdateTaskRequest

Барлық өріс міндетті емес. Тек өзгерткіңіз келетіндерін жіберіңіз.

Өріс	Түрі	Сипаттамасы
`title`	string \| null	Жаңа атауы, 5000 таңбаға дейін
`description`	string \| null	Жаңа сипаттама, 5000 таңбаға дейін
`planDate`	string \| null	Жаңа жоспарланған күн
`dueDate`	string \| null	Жаңа мерзім; жоспарланған күннен ерте болмауы керек
`clearPlanDate`	boolean	Жоспарланған күнді тазалау (`planDate`-тен басым)
`clearDueDate`	boolean	Мерзімді тазалау (`dueDate`-тен басым)
`planCron`	string \| null	Жаңа қайталану ережесі
`priority`	`UTTaskPriority`	Жаңа басымдық
`status`	`UTTaskStatus`	Жаңа күй
`assigneeIds`	string[] \| null	Орындаушылардың жаңа толық тізімі (бос массив барлығын алып тастайды)

PubCommentRequest

Өріс	Түрі	Міндетті	Сипаттамасы
`text`	string	✓	Пікір мәтіні

PubCommentModel

Өріс	Түрі	Сипаттамасы
`text`	string	Пікір мәтіні
`createDate`	string (ISO 8601)	Жасалған күні

PubTaskHistoryItemModel

Тапсырма өзгерістері тарихының жазбасы.

Өріс	Түрі	Сипаттамасы
`date`	string (ISO 8601)	Оқиға күні
`author`	`PubUserModel`	Өзгеріс авторы
`comment`	string	Пікір мәтіні (бұл пікір болса)
`change`	`PubTaskHistoryChangeModel`	Өрістің өзгерісі туралы мәліметтер

PubTaskHistoryChangeModel

Өріс	Түрі	Сипаттамасы
`field`	string	Өзгерген өрістің атауы
`oldValue`	string	Ескі мәні
`newValue`	string	Жаңа мәні

Тізбелер

UTTaskStatus

Тапсырманың күйі.

Мәні	Сипаттамасы
`New`	Жаңа
`ToDo`	Жоспарланған
`InProgress`	Орындалуда
`Resolved`	Шешілді
`Review`	Тексеруде
`Approved`	Мақұлданды
`Closed`	Жабық

UTTaskPriority

Тапсырманың басымдығы.

Мәні	Сипаттамасы
`None`	Белгіленбеген
`Lowest`	Ең төмен
`Low`	Төмен
`Medium`	Орташа
`High`	Жоғары
`Highest`	Ең жоғары

UTProjectType

Жоба түрі.

Мәні	Сипаттамасы
`Private`	Жеке
`Public`	Ашық
`Dynamic`	Динамикалық

UTUserStatus

Мүшенің жобадағы рөлі.

Мәні	Сипаттамасы
`None`	Рөлі жоқ
`Creator`	Жасаушы
`Administrator`	Әкімші
`Member`	Мүше

PubTaskScope

Тапсырмаларды сүзу аумағы.

Мәні	Сипаттамасы
`All`	Барлық тапсырма
`Inbox`	«Кіріс»
`Today`	Бүгінге
`Tomorrow`	Ертеңге
`Week`	Осы аптаға
`Completed`	Орындалғандар

Пайдалану мысалдары

Бүгінгі тапсырмаларды алу

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": "Дайын, тексеруіңізді күтемін"
}

Қате кодтары

Код	Сипаттамасы
`400`	Қате сұрау – сұраудың мазмұнын тексеріңіз
`401`	Авторизацияланбаған – API кілтін тексеріңіз
`403`	Тыйым салынған – бұл әрекетке құқық жеткіліксіз
`404`	Нысан табылмады
`500`	Сервердің ішкі қатесі

Қатенің мазмұны ProblemDetails пішімінде қайтарылады:

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

MCP-серверді қосу