API и интеграции: справочник

Справочник написан для разработчика интеграции. Пошаговая инструкция для пользователя находится в процессе «Интеграции».

Способы доступа

Способ	Для чего	Аутентификация
REST API	Чтение и изменение данных из скриптов и сервисов	API-ключ в заголовке `Authorization: Bearer thor_sk_…`
MCP	Чтение данных ИИ-ассистентами (только чтение)	API-ключ
Webhook	Получение событий в вашу систему	Подпись `X-Assist-Signature`

Адреса

REST API: https://<адрес кабинета>/api.
MCP: https://<адрес кабинета>/api/mcp (Streamable HTTP, без сессий).
Проверка работоспособности: GET /health и GET /ready без аутентификации.

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

Создайте API-ключ на странице «API-ключи». Выберите роль: ключ получит права именно этой роли.
Сохраните токен вида thor_sk_<идентификатор>.<секрет>: он показывается один раз.
Передавайте токен в каждом запросе: Authorization: Bearer thor_sk_….

Для запросов с ключом заголовок X-Requested-With не нужен. Управление самими ключами через ключ невозможно: ответ 403.

Общие заголовки

Заголовок	Когда	Значение
`Authorization`	Всегда	`Bearer thor_sk_<id>.<secret>`
`Content-Type`	Для POST и PATCH с телом	`application/json`
`Accept-Language`	По желанию	`ru` или `en`: язык сообщений
`Idempotency-Key`	Рекомендуется для POST, PUT, PATCH, DELETE	Уникальная строка до 255 символов

Идемпотентность. Повтор запроса с тем же ключом и телом возвращает сохранённый ответ. Тот же ключ с другим телом: ошибка 409 IDEMPOTENCY_MISMATCH. Для загрузки файлов (multipart/form-data) не работает.

Формат данных

Идентификаторы: UUID в нижнем регистре.
Даты и время: ISO 8601 с часовым поясом, например 2026-10-28T12:00:00.000Z.
Календарные дни (начало и конец задач и релизов): YYYY-MM-DD.
Описание: документ BlockNote (JSON) или null.
Оценка и длительности: минуты (целое число).

Пагинация. Списки отвечают объектом { items, pagination: { limit, offset, total, hasMore } }. Параметры limit и offset. Деревья задач используют курсор: nextCursor.

Права

Каждый метод проверяет права роли ключа и охват записей. Права текущего ключа возвращает GET /api/me в поле permissions. Ошибка 403 означает недостаточные права, а не проблему аутентификации. Ошибка 404 может означать, что запись вне охвата роли.

Лимиты

Зона	Лимит
`/api/auth/*`	40 запросов в минуту с адреса
Остальной `/api/*`	180 запросов в минуту с адреса

При превышении ответ 429 RATE_LIMITED с заголовками x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, retry-after.

Формат ошибок

{ "error": { "code": "VALIDATION_ERROR", "message": "Invalid request body", "details": {} } }

HTTP	Код	Когда
400	`VALIDATION_ERROR`	Неверное тело или параметры запроса
401	`UNAUTHORIZED`	Нет или недействителен ключ или сессия
403	`FORBIDDEN`	Нет права
404	`NOT_FOUND`	Запись не найдена или вне охвата
409	`CONFLICT`, `IDEMPOTENCY_MISMATCH`	Конфликт данных, повтор с другим телом
429	`RATE_LIMITED`	Превышен лимит
500	`INTERNAL`	Необработанная ошибка

Переход по стадии, который не прошёл гейт, возвращает ошибку с details.failures и подсказкой hint.

Основные методы

Нужное право указано для роли ключа.

Профиль

Метод	Путь	Описание
GET	`/api/me`	Профиль, роль и права ключа
GET	`/api/me/my-work`	Задачи «Моей работы»

Проекты, релизы, задачи

Метод	Путь	Описание	Право
GET	`/api/projects`	Список проектов. Параметры `q`, `kind`, `stageKey`, `limit`, `offset`	Проекты: просмотр
POST	`/api/projects`	Создать проект	Проекты: создание
GET	`/api/projects/:id/releases`	Релизы проекта	Релизы: просмотр
POST	`/api/projects/:id/releases`	Создать релиз	Релизы: создание
PATCH	`/api/releases/:id`	Изменить релиз	Релизы: изменение
POST	`/api/releases/:id/move-stage`	Перевести релиз	Релизы: изменение
GET	`/api/projects/:id/tasks`	Дерево задач проекта	Задачи: просмотр
POST	`/api/projects/:id/tasks`	Создать задачу	Задачи: создание
POST	`/api/releases/:id/tasks`	Создать задачу в релизе	Задачи: создание
GET	`/api/tasks/:id`	Получить задачу	Задачи: просмотр
PATCH	`/api/tasks/:id`	Изменить задачу	Задачи: изменение
POST	`/api/tasks/:id/move-stage`	Перевести задачу: тело `{"stageKey":"in_progress","confirmed":true}`	Задачи: изменение
GET	`/api/tasks/:id/allowed-transitions`	Допустимые переходы	Задачи: просмотр
DELETE	`/api/tasks/:id`	Удалить задачу	Задачи: удаление
GET	`/api/search?q=…`	Глобальный поиск	Права просмотра

Часы и комментарии

Метод	Путь	Описание
GET	`/api/tracks`	Список треков
POST	`/api/tracks`	Создать трек: `taskId`, `workTypeId`, `description`, `durationMinutes`, `startedAt`, `endedAt`, при праве — `userId`
GET	`/api/work-types`	Типы работ
POST	`/api/entity-comments`	Комментарий: `entityType` (`task`, `release`, `project`), `entityId`, `body`

Уведомления и отчёты

Метод	Путь	Описание
GET	`/api/notifications`	Лента уведомлений
POST	`/api/notifications/:id/read`	Отметить прочитанным
GET	`/api/reports/tracks/duration-matrix`	Отчёт «Часы по трекам» (есть `.csv` и `.xlsx`)
GET	`/api/reports/tracks/time-allocation`	Отчёт «Распределение времени»
GET	`/api/resources/plan-fact?yearMonth=YYYY-MM`	План-факт

Примеры

Создать задачу:

curl -X POST "https://<адрес>/api/projects/<ID_ПРОЕКТА>/tasks" \
  -H "Authorization: Bearer thor_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-import-001" \
  -d '{"title": "Задача из CRM", "estimateMinutes": 120}'

Записать время:

curl -X POST "https://<адрес>/api/tracks" \
  -H "Authorization: Bearer thor_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"taskId": "<ID_ЗАДАЧИ>", "workTypeId": "<ID_ТИПА_РАБОТ>", "description": "Работа по интеграции", "durationMinutes": 60, "startedAt": "2026-10-28T09:00:00.000Z", "endedAt": "2026-10-28T10:00:00.000Z"}'

Перевести задачу на стадию:

curl -X POST "https://<адрес>/api/tasks/<ID_ЗАДАЧИ>/move-stage" \
  -H "Authorization: Bearer thor_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"stageKey": "in_progress", "confirmed": true}'

Правила записи времени те же, что в интерфейсе: «Правила и ограничения».

MCP для ИИ-ассистентов

MCP-сервер работает только на чтение. Авторизация только по API-ключу. Запросы GET и DELETE возвращают 405.

Инструмент	Что возвращает
`whoami`	Пользователь ключа, роль, коллекции с охватом
`list_fields`	Поля задач и проектов
`list_projects`, `get_project`	Проекты; карточка проекта с командой и зонами ответственности (по `projectId` или префиксу)
`list_tasks`, `get_task`	Задачи по всем проектам с фильтрами; карточка задачи (по `taskId` или ключу вида `RGM-30`)
`list_users`	Пользователи; с `projectId` — команда проекта
`list_time_tracks`	Треки времени и итог в минутах
`list_field_tracks`	История значений полей

Списки принимают limit (1–100, по умолчанию 50) и offset. Даты в ответах: ISO 8601.

Webhook

Webhook настраивается пользователем на вкладке «Каналы уведомлений» профиля: «Свои настройки уведомлений».

Assist отправляет один HTTPS POST на каждое событие.
Адрес должен быть публично доступным. Частные и локальные адреса отклоняются.
Секрет показывается один раз при создании.
Подпись: заголовок X-Assist-Signature содержит sha256= и шестнадцатеричный HMAC-SHA256 точного тела запроса, посчитанный с секретом webhook.

Пример проверки подписи (Python):

import hmac, hashlib

def is_valid(body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

Ограничения

Ключи создаются и отзываются только в интерфейсе.
Удаление задач, проектов, релизов и треков мягкое: записи помечаются удалёнными.
Переходы по стадиям могут быть заблокированы гейтом. Передайте confirmed: true после выполнения условий.
Дополнительные поля из конструктора передаются как поля верхнего уровня тела запроса и проверяются по каталогу и правам на поля.
Полный перечень методов и схем тел запросов ведёт команда разработки Assist. Запросите документ «REST API (интеграция)» у администратора.

Способы доступа​

Адреса​

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

Общие заголовки​

Формат данных​

Права​

Лимиты​

Формат ошибок​

Основные методы​

Профиль​

Проекты, релизы, задачи​

Часы и комментарии​

Уведомления и отчёты​

Примеры​

MCP для ИИ-ассистентов​

Webhook​

Ограничения​