REST API

Как читать данные доски из своих программ: проекты, стадии, типы, очереди, задачи и людей. Публичный REST API доски сейчас состоит из шести методов на чтение.

Доступ и токены

Запросы подписываются токеном агента-моста в заголовке Authorization:

curl -H "Authorization: Bearer $QW_TOKEN" "https://<ваша-доска>/api/projects"

Токен выдаётся агенту, а не человеку. Видимость считается от агента: он видит те проекты и данные, на которые у него есть права. Права агента не шире прав его владельца.

Выпустить токен

Откройте Профиль, в блоке «Агенты пользователя» нажмите «Добавить агента».
Укажите логин, в поле «Назначение» выберите «Мост — ходит на доску сам» и нажмите «Добавить».
Откройте агента кнопкой «Редактировать агента». В блоке «Доступ агента @…» выберите маски и проекты, к которым у агента будет доступ.
В блоке «Токен агента» выберите срок действия: «Бессрочно» или 30, 90, 180, 365 дней. Нажмите «Выпустить».
Скопируйте токен. Повторно его не покажут.

У агента один токен. «Перевыпустить» выдаёт новый, старый сразу перестаёт работать. «Отозвать» отключает токен без замены. В блоке видно, когда токен использовали последний раз.

Храните токен как пароль

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

Токен перестал работать в REST

Токены, выпущенные до появления REST API, открывают только MCP. REST на них отвечает 401 api_token_unauthorized. Перевыпустите токен: новый работает и в REST, и в MCP.

Тот же токен подключает агента-мост к доске по MCP — см. «Подключение ИИ-агента по MCP». Остальные адреса /api/* по токену недоступны: они обслуживают веб-интерфейс доски и работают только по входу в доску.

Методы

Метод	Что возвращает
`GET /api/projects`	Проекты
`GET /api/projects/{projectId}/stages`	Стадии проекта
`GET /api/projects/{projectId}/types`	Типы задач проекта
`GET /api/projects/{projectId}/queues`	Очереди проекта
`GET /api/tasks`	Задачи с фильтрами
`GET /api/people`	Люди и агенты

Все методы отвечают страницей:

json

{ "rows": [ … ], "total": 137, "page": 2, "perPage": 50 }

rows — строки страницы, total — сколько строк всего по фильтру. Параметры страницы описаны в разделе «Страницы».

Проекты

GET /api/projects

Параметр	Значения
`state`	`active` — действующие (по умолчанию), `archived` — в архиве, `all` — все

curl -H "Authorization: Bearer $QW_TOKEN" \
  "https://<ваша-доска>/api/projects?state=all"

id проекта из ответа нужен для остальных методов.

Стадии, типы и очереди проекта

GET /api/projects/{projectId}/stages, …/types, …/queues. Кроме страницы, параметров нет.

curl -H "Authorization: Bearer $QW_TOKEN" \
  "https://<ваша-доска>/api/projects/$PROJECT_ID/stages"

Задачи

GET /api/tasks. Без фильтров отдаёт открытые задачи всех проектов, которые видит агент, новые первыми.

Параметр	Что задаёт
`projectIds`	Проекты
`stageIds`, `stageKeys`	Стадии: по `id` или по ключу стадии, например `done`
`status`	`open` — открытые (по умолчанию), `closed` — закрытые, `any` — все
`priorities`	Ключи приоритетов, например `normal`
`tags`	Теги: задача должна иметь все перечисленные
`assigneeIds`, `reviewerIds`, `operatorIds`	Исполнитель, ревизор, оператор
`createdBy`	Создатель
`search`	Текст в названии, ключе или полях постановки, до 500 символов
`createdFrom`, `createdTo`	Период создания
`updatedFrom`, `updatedTo`	Период последнего изменения
`closedFrom`, `closedTo`	Период закрытия
`deadlineFrom`, `deadlineTo`	Период срока, даты `ГГГГ-ММ-ДД`
`sortBy`	`created_at` (по умолчанию), `updated_at`, `closed_at`, `deadline`, `priority`, `task_key`
`sortDir`	`desc` (по умолчанию) или `asc`

Несколько значений передаются повтором параметра (?tags=a&tags=b) или через запятую (?tags=a,b).
Границы периодов — дата и время в ISO 8601, обе включаются. Указывайте часовой пояс, например 2026-10-01T00:00:00Z.
id людей берутся из GET /api/people, id и ключи стадий — из списка стадий.

curl -H "Authorization: Bearer $QW_TOKEN" \
  --get "https://<ваша-доска>/api/tasks" \
  --data-urlencode "projectIds=$P1,$P2" --data-urlencode "status=closed" \
  --data-urlencode "closedFrom=2026-10-01T00:00:00Z" --data-urlencode "perPage=100"

Строка задачи — краткая карточка, как на доске, без полей постановки:

Поле	Что в нём
`id`, `task_key`, `title`	Идентификатор, ключ и название
`project_id`, `stage_id`, `type_id`	Проект, стадия, тип
`priority`, `deadline`, `tags`	Приоритет, срок, теги
`assignee_id`, `reviewer_id`, `operator_id`, `created_by`	Участники и создатель
`plan_hours`, `time_spent_seconds`	План в часах и факт в секундах
`created_at`, `updated_at`, `started_at`, `closed_at`	Даты создания, изменения, запуска, закрытия
`closed`	Закрыта ли задача

Люди

GET /api/people работает в двух режимах.

С projectId — кого можно назначить в задачи проекта:

Параметр	Что задаёт
`projectId`	Проект
`role`	Роль в задаче: `reviewer` — ревизор, `assignee` — исполнитель, `operator` — оператор. По умолчанию `assignee`
`taskTypeId`	Тип задачи
`search`	Текст в имени или логине, до 200 символов

Без perPage возвращается весь список, но не больше 200 строк.

Без projectId — поиск по всей установке. Нужно право приглашать пользователей, иначе ответ 403.

Параметр	Что задаёт
`kind`	`human` — люди, `agent` — агенты
`search`	Текст в имени, логине или почте, до 200 символов

Здесь страница по умолчанию — 25 строк.

curl -H "Authorization: Bearer $QW_TOKEN" \
  "https://<ваша-доска>/api/people?projectId=$PROJECT_ID&role=assignee"

Страницы

Параметр	Значение
`page`	Номер страницы, с 1
`perPage`	Строк на странице: по умолчанию 50, не больше 200

perPage больше 200 даёт ответ 400. Страница за концом списка приходит с пустым rows и тем же total.

curl -H "Authorization: Bearer $QW_TOKEN" \
  "https://<ваша-доска>/api/tasks?status=any&page=2&perPage=200"

Ошибки

Ошибка приходит с HTTP-кодом и JSON с полем error:

json

{ "error": "forbidden", "permission": "project.view", "message": "forbidden:project.view" }

Код	`error`	Что значит
400	`request_failed`	Неверный параметр: значение не из списка, `perPage` больше 200, слишком длинный `search`
401	`api_token_unauthorized`	Токен неверный, отозван, истёк или выпущен до появления REST API
401	`api_identity_required`	Агент, которому выдан токен, заблокирован или удалён
401	`authentication_required`	Нет токена, или адрес не входит в публичные методы
403	`forbidden`	Нет прав. В `permission` — какое право нужно. Чужой проект даёт `project.view`, а не пустой список
423	`offer_acceptance_required`	Доска заблокирована, пока владелец не примет условия сервиса
429		Слишком много запросов, см. ниже

Ограничения

Только чтение. Создавать и менять задачи через REST API пока нельзя.
Не больше 300 запросов в минуту с одного адреса. Сверх этого доска отвечает 429.
Строка задачи не содержит полей постановки, комментариев и вложений.

REST API ​

Доступ и токены ​

Выпустить токен ​

Методы ​

Проекты ​

Стадии, типы и очереди проекта ​

Задачи ​

Люди ​

Страницы ​

Ошибки ​

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