# Жирус — подробно для языковых моделей и агентов

> Свободный трекер задач: проекты, доски Scrum и Kanban, спринты, бэклог, JQL,
> дизайнер процессов, отчёты. REST API совместим с Jira Cloud: клиенты Jira
> работают без правок, меняется только базовый адрес и учётные данные.

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

- Токен API выпускается на https://jirus.ru/settings/tokens и показывается один раз.
- Заголовок: `Authorization: Bearer <токен>` или Basic с почтой и токеном.
- Пароль в Basic по умолчанию не принимается: только токен.
- У пользователя не больше десяти действующих токенов.
- Неверные учётные данные после серии попыток получают 429 с Retry-After.

## Основные операции

- Поиск: `POST https://jirus.ru/rest/api/3/search/jql` с телом
  `{ "jql": "project = DEMO AND status != Done", "maxResults": 50, "fields": ["summary", "status"] }`.
  Страницы — через `nextPageToken`; глубина выдачи ограничена 10 000.
- Задача: `GET https://jirus.ru/rest/api/3/issue/DEMO-1`, создание —
  `POST https://jirus.ru/rest/api/3/issue`, переход — `POST …/issue/{key}/transitions`.
- Комментарии: `POST https://jirus.ru/rest/api/3/issue/{key}/comment`, тело в ADF v1.
- Доски и спринты: `https://jirus.ru/rest/agile/1.0/board`, `…/sprint/{id}/issue`.
- Алиас `/rest/api/2` отдаёт описания и комментарии обычным текстом.

## JQL

Поддерживается язык целиком: `=`, `!=`, `IN`, `~` с морфологией русского и
английского, `WAS`, `CHANGED` с `BY/BEFORE/AFTER/DURING`, функции
`currentUser()`, `openSprints()`, `startOfDay()` и другие. Спринт задаётся
именем или числовым id: `sprint = 123`.

Пределы запроса: не длиннее 10 000 символов, вложенность скобок до 50,
не больше 500 условий. Запрос дольше 15 секунд прерывается.

## Пределы и лимиты

- Тело JSON-запроса — до 1 МБ, вложение — до 10 МБ.
- Массовое создание — до 50 задач за вызов, массовое чтение — до 1000.
- Частотные лимиты отдают заголовки `X-RateLimit-Limit` и `X-RateLimit-Remaining`;
  при превышении — 429 с `Retry-After`.
- Пишущий запрос по сессионной куке требует своего Origin или заголовка
  `X-Atlassian-Token: no-check`, как в Jira.

## Вебхуки

- Регистрирует администратор пространства: `POST https://jirus.ru/rest/api/3/webhook`.
- Только https и публичный адрес; редиректы не выполняются.
- Событие доставляется, только если владелец вебхука видит задачу; `jqlFilter`
  применяется. Подпись — `X-Hub-Signature-256` (HMAC-SHA256).
- Не больше 20 вебхуков на пространство, срок жизни — 30 дней без продления.

## Чего нет

Atlassian Connect, Forge, Marketplace, Advanced Roadmaps и DevOps-интеграции
отвечают 501. Схемы разрешений, уведомлений и экранов читаются как одна
системная схема; их изменение отвечает 400. Почта участников видна только
им самим и администраторам пространства.

## Ошибки

Формат Jira: `{ "errorMessages": [], "errors": {}, "status": 0 }`.
Нет объекта и нет прав неразличимы: оба — 404.