API

API Quevell состоит из тех же методов, которыми пользуется интерфейс продукта, открытых для интеграций. Он принимает и отдает JSON и работает только от имени сервисного аккаунта: у людей личных токенов нет. Ниже описано, как к нему обращаться и что он возвращает, а в конце перечислены методы, которые можно вызывать.

Адрес#

https://<ключ>.quevell.com/api

<ключ> - это ключ вашей компании, тот же, что в адресной строке продукта. Обращайтесь к адресу своей компании: токен выдан одной компанией, и на адресе другой компании запрос отклоняется с кодом auth.tenant_mismatch (403). Номера версии в адресе нет.

Вход#

В каждом запросе передается токен сервисного аккаунта:

Authorization: Bearer qvl_...

Как выпустить токен, как сузить его права и как получить временный токен через OAuth-клиент, описано в статье Сервисные аккаунты. Запрос без токена, с неизвестным, истекшим или отозванным токеном отклоняется с ответом 401 auth.required. Если токену не хватает прав на действие, ответ будет 403 authorization.forbidden.

Ответы и ошибки#

Успешный ответ содержит сам объект, список или страницу, без обертки. Ошибка всегда приходит в одном и том же формате:

{
  "code": "concurrency.version_conflict",
  "message": "Issue was modified concurrently",
  "status": 409,
  "path": "/api/issues/6f1c.../transitions/...",
  "correlationId": "9b2e...",
  "timestamp": "2026-09-17T08:00:00Z",
  "details": {}
}

• code: неизменный код, по нему и выбирайте, как обработать ошибку.
• message: предложение для человека, по-английски. Оно может измениться в любой день, поэтому на message не опирайтесь.
• details: подробности, если они есть: ошибки полей в details.fieldErrors, время ожидания в details.retryAfterSeconds.
• correlationId: номер запроса. Он же приходит в заголовке X-Correlation-Id каждого ответа; укажите его, когда пишете в поддержку.

Частые коды:

Модули добавляют свои коды в своем пространстве имен: note.*, sprint.*, identity.* и другие. Незнакомый код обрабатывайте по статусу.

Даты и время#

Моменты времени приходят и принимаются в UTC, строкой ISO-8601 с Z на конце. Календарные дни, например срок задачи или день записи времени, передаются как год-месяц-день без времени. Часовой пояс сервера и человека на ответ не влияет: перевод в местное время остается за программой.

Страницы и курсор#

Длинные списки отдаются страницами. Ответ содержит items и nextCursor, у части методов еще total. Следующую страницу просят тем же запросом с cursor=<nextCursor>; когда nextCursor пуст, страниц больше нет. Размер страницы задает limit, у каждого метода свой предел, он указан в справочнике. Номеров страниц и смещений нет.

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

Поиск и QQL#

Задачи по всем доступным проектам ищет GET /api/issues/search. В text передается либо обычный текст, либо запрос на QQL:

curl -G https://<ключ>.quevell.com/api/issues/search \
  -H "Authorization: Bearer qvl_..." \
  --data-urlencode 'text=project = OFFICE and status != Done order by updated desc' \
  --data-urlencode 'mode=QUERY'

Без mode сервер сам решает, текст это или запрос, и сообщает решение в поле mode ответа; в интеграции лучше указывать mode=QUERY явно. Порядок задает ORDER BY внутри запроса, по умолчанию сначала недавно измененные. Сохраненный фильтр запускается параметром filterId.

Задачи, которые токен видеть не может, в ответ не попадают вовсе: их нет ни в items, ни в total.

Версии и конфликты#

У изменяемых объектов есть поле version. Изменяя объект, передайте версию, которую вы прочитали, в expectedVersion. Если кто-то успел изменить объект раньше, ответ будет 409 concurrency.version_conflict или доменный код с version_conflict в конце. Перечитайте объект и решите, применять ли изменение снова.

Повтор того же изменения задачи ничего не меняет и нового события не пишет. А вот создание не идемпотентно: повторенный POST создаст второй объект. Если запрос на создание оборвался, сначала проверьте, создался ли объект.

Лимиты#

Как считается:

• Минута: календарная минута по UTC, не скользящее окно. Считается каждый запрос с действующим токеном, в том числе отклоненный из-за прав.
• Сутки: календарные сутки по UTC. Запись означает каждое событие, которое аккаунт оставил в журнале: создание и изменение задачи, комментарий, запись времени, а также скачивание вложения и выгрузка CSV. Чтение без события запись не расходует.
• Все токены одного аккаунта, выпущенные вручную и выданные OAuth-клиентом, расходуют один общий лимит.

В каждом ответе 429 сказано, сколько ждать: в заголовке Retry-After и тем же числом в details.retryAfterSeconds. Для минутного лимита это секунды до новой минуты, для суточного время до полуночи по UTC.

HTTP/1.1 429 Too Many Requests
Retry-After: 17

{"code":"tenant.rate_limited","status":429,"details":{"retryAfterSeconds":17},...}

Подождите указанное время и повторите запрос. Повторять раньше бесполезно, такие запросы тоже считаются. При 409 files.storage_quota_exceeded в details приходят usedBytes и limitBytes.

Примеры#

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

curl -X POST https://<ключ>.quevell.com/api/projects/<projectId>/issues \
  -H "Authorization: Bearer qvl_..." \
  -H "Content-Type: application/json" \
  -d '{"summary": "Заменить картридж", "description": "Принтер на третьем этаже"}'

Перевести задачу по статусу: сначала узнать доступные переходы, затем выполнить нужный с версией задачи.

curl https://<ключ>.quevell.com/api/issues/<issueId>/transitions \
  -H "Authorization: Bearer qvl_..."

curl -X POST https://<ключ>.quevell.com/api/issues/<issueId>/transitions/<transitionId> \
  -H "Authorization: Bearer qvl_..." \
  -H "Content-Type: application/json" \
  -d '{"expectedVersion": 3}'

Добавить комментарий:

curl -X POST https://<ключ>.quevell.com/api/issues/<issueId>/comments \
  -H "Authorization: Bearer qvl_..." \
  -H "Content-Type: application/json" \
  -d '{"body": "Картридж заменен"}'

Справочник методов#

Список собран из кода продукта и сверяется с ним при каждой сборке, поэтому в нем нет методов, которых уже не существует. Методы входа, администрирования компании и вспомогательные методы экранов сюда не входят: их форма меняется вместе с интерфейсом. Право в описании требуется и от роли аккаунта, и от токена; просмотр проекта требуется везде и не указан.