Правила API

Общие правила для запросов к /api/public/v1.

Пагинация и фильтры

Коллекции возвращают {items, total, limit, offset}. По умолчанию limit=50, допустимо 1–100; offset — 0–100000. Порядок устойчивый, но изменения между запросами страниц могут сдвигать выдачу.

Поиск задач q находит отображаемый ID или вхождение в название без учёта регистра. Явно переданный пустой q возвращает пустую выдачу. Разные поля фильтра объединяются AND, значения одного поля — OR. Для нескольких значений повторяйте query-параметр. projectId, assigneeId и cycleId принимают none, чтобы выбрать задачи без связи.

Пример запроса

curl "$PMLY_API/workspaces/$WORKSPACE_ID/issues?limit=20&offset=0&priority=1&priority=2&assigneeId=none" \
  --header "Authorization: Bearer $PMLY_API_TOKEN"

Версии и PATCH

PATCH меняет только переданные поля и требует текущую version. Пропущенное поле сохраняется. Для снятия проекта, исполнителя или цикла передайте null; описание очищается пустой строкой. Неизвестные поля отклоняются.

Актуальная запись без изменений не увеличивает версию. Устаревшая версия всегда даёт 409. После конфликта выполните GET и явно выберите изменения. Настройки представления при передаче заменяются целиком. Удаление комментария и представления требует версии в query-параметре.

Повторы создания

Каждый POST создания требует Idempotency-Key длиной 1–128 символов. В течение 24 часов повтор одинакового нормализованного запроса возвращает первоначальный успешный ответ. Другой payload с тем же ключом даёт 409.

Область ключа — пользователь, пространство и операция; для комментариев также задача. Ключ не зависит от конкретного токена: ротация не создаёт дублей. После 24 часов ключ может создать новый ресурс. После повтора выполните GET для получения актуального состояния, поскольку первоначальный ответ может содержать старую версию.

Ошибки

Пример ответа об ошибке

{"code":"version_conflict","message":"Задача изменена. Обновите данные","requestId":"00000000-0000-4000-8000-000000000001"}

HTTP	Причина и действие
`400`	Неверный ввод. Проверьте поля, типы и обязательные параметры.
`401`	Токен отсутствует, истёк или отозван. Проверьте Authorization; ответ содержит Bearer challenge.
`403`	Недостаточно scopes или бизнес-прав. Проверьте разрешения и права пользователя.
`404`	Ресурс не найден или недоступен в этом пространстве.
`409`	Конфликт версии или ключа повтора. Прочитайте ресурс или проверьте payload.
`413`	Тело запроса превышает допустимый размер.
`429`	Лимит запросов. Подождите Retry-After секунд.

Заголовок X-Request-Id и поле requestId помогают найти запрос при обращении за поддержкой.

Лимиты и совместимость

По умолчанию 120 запросов в минуту на токен, включая не более 30 записей; тело до 128 КиБ. Повторы и запросы, отклонённые после аутентификации, учитываются. Окно — календарная минута; счётчики общие для процессов приложения. При 429 сервер возвращает Retry-After в секундах.

Совместимые изменения могут добавлять поля ответа. Клиент должен допускать неизвестные поля ответа. Несовместимые изменения требуют новой major-версии API.