Специфікація API

Повна довідка по кінцевих точках REST. Щодо туторіалів та прикладів дивіться Посібник з API.

Усе, що member проєкту може зробити у вебінтерфейсі, доступно тут — SPA споживає той самий API. Операції, що вимагають ролі owner, позначено (owner); усе інше потребує лише членства в проєкті (або, для читань, позначених (viewer), будь-якого рівня доступу).

База

https://eastagiletracker.com/api/v1

https://api.eastagiletracker.com/api/v1 обслуговує ідентичний API. Усі запити та відповіді — це JSON, окрім кількох кінцевих точок завантаження файлів, що приймають multipart.

Автентифікація

Кожен автентифікований запит надсилає ключ API через один із:

• X-TrackerToken: <key>
• Authorization: Bearer <key>

Користувацькі ключі починаються з ea_user_. Ключі агентів починаються з ea_agent_. Дивіться Посібник з API → Два види ключів.

Кінцеві точки без автентифікації: /openapi.json, /docs, кінцеві точки /auth/* та пошуки довідкових даних (/story_types, /story_states, /effort_scales, …). /meta є автентифікованою — будь-який дійсний ключ працює, але вона не обмежена проєктом (ключ агента, прив’язаний до проєкту, теж її досягає).

Ролі

Три рівні регулюють кінцеві точки, обмежені проєктом:

Рівень	Хто проходить	Типові операції
viewer	viewer, member, owner	читання (перелік/отримання історій, пошук, аналітика)
member	member, owner	усі записи робочих елементів (історії, завдання, коментарі, …)
owner	лише owner	налаштування проєкту, керування членством, ключі агентів, видалення, імпорт, журнал аудиту

Не-учасник отримує 404 unfound_resource (а не 403) на шляхах проєкту, тож ID проєктів не можна перелічити.

Самоописові кінцеві точки

Метод	Шлях	Опис
GET	/openapi.json	Актуальна специфікація OpenAPI 3. Без автентифікації.
GET	/docs	Swagger UI. Без автентифікації.
GET	/meta	Ідентичність викликача (auth.kind/key_id/agent_id/project_id) + граф переходів за типом історій. Автентифікована (будь-який дійсний ключ; не обмежена проєктом). Викликайте її першою.

Обліковий запис / ідентичність

Ці діють на викликача і потребують лише дійсного ключа (без ролі в проєкті).

Метод	Шлях	Опис
POST	/auth/register	Зареєструвати новий обліковий запис
POST	/auth/login	Увійти, повертає токен сесії
POST	/auth/logout	Вийти
POST	/auth/forgot-password	Запитати лист для скидання пароля
POST	/auth/reset-password	Використати токен скидання, щоб задати новий пароль
GET	/auth/verify-email	Підтвердити адресу електронної пошти
POST	/auth/accept-invite/lookup	Розв’язати токен запрошення → електронна пошта (без автентифікації)
POST	/auth/accept-invite	Прийняти запрошення до проєкту (після автентифікації)
GET	/me	Профіль поточного користувача
PUT	/me	Оновити профіль
DELETE	/me	Видалити обліковий запис
PUT	/me/password	Змінити пароль
PUT	/me/settings	Оновити налаштування (тема, налаштування сповіщень)
POST	/me/avatar	Завантажити аватар (multipart)
POST	/me/api-token/regenerate	Ротувати ваш токен API — інвалідує наявні сесії/ключі
GET	/me/api_keys · POST /me/api_keys · DELETE /me/api_keys/{id}	Керувати користувацькими (ea_user_) ключами API
GET	/me/activity	Ваша активність у всіх проєктах
GET	/me/data-export	Самостійний експорт ваших даних за GDPR
GET	/me/consent · POST /me/consent	Прочитати / записати згоду ({ consent_type, granted })
GET	/legal/pending · POST /legal/accept	Очікувані документи clickwrap / запис прийняття
POST	/contact · POST /feedback · POST /feedback/with-screenshot	Контакт + внутрішньозастосунковий зворотний зв’язок

Довідкові дані (без автентифікації)

Стартові пошуки, що використовуються при створенні/оцінюванні історій. Стабільні ID.

Метод	Шлях	Опис
GET	/story_types	feature, bug, chore, release (+ allow_points)
GET	/story_states	unstarted … accepted, rejected
GET	/effort_scales	доступні шкали оцінювання
GET	/effort_scales/{scale_id}/values	бальні значення у шкалі

Проєкти

Метод	Шлях	Опис
GET	/projects	Перелічити ваші проєкти
POST	/projects	Створити проєкт
GET	/projects/{id}	Отримати деталі проєкту (viewer)
PUT	/projects/{id}	Оновити налаштування проєкту (owner)
DELETE	/projects/{id}	Видалити проєкт (owner)
GET	/projects/{id}/audit-log	Потік активності проєкту (owner)
GET	/projects/{id}/events	Потік подій із курсорною пагінацією (viewer) — дивіться Події

Учасники та ключі агентів

Метод	Шлях	Опис
GET	/projects/{id}/memberships	Перелічити учасників (viewer)
POST	/projects/{id}/memberships	Запросити учасника за електронною поштою (owner)
PUT	/projects/{id}/memberships/{mid}	Оновити роль (owner)
DELETE	/projects/{id}/memberships/{mid}	Видалити учасника (owner)
GET / POST	/projects/{id}/agent_keys	Перелічити / створити ключі агентів (owner)
DELETE	/projects/{id}/agent_keys/{kid}	Відкликати ключ агента (owner)

Історії

Усі записи історій потребують ролі member.

Метод	Шлях	Опис
GET	/projects/{id}/stories	Перелічити історії (пагіновано, з фільтрацією) (viewer)
POST	/projects/{id}/stories	Створити історію
GET	/projects/{id}/stories/{sid}	Отримати одну історію (viewer)
PUT	/projects/{id}/stories/{sid}	Оновити історію
DELETE	/projects/{id}/stories/{sid}	Видалити історію
POST	/projects/{id}/stories/{sid}/transitions	Змінити стан із перевіркою
POST	/projects/{id}/stories/bulk_transition	Перевести багато історій (1–100) за раз
POST	/projects/{id}/stories/bulk-delete	Видалити багато історій
POST	/projects/{id}/stories/bulk-duplicate	Дублювати багато історій
POST	/projects/{id}/stories/{sid}/duplicate	Дублювати одну історію

Create (POST …/stories): { "name" (required), "story_type": "feature|bug|chore|release", "description"?, "estimate"?, "current_state"?, "icebox"?, "labels"? }. labels приймає ["auth"] або [{ "name": "auth" }]; невідомі мітки створюються. За замовчуванням: story_type=feature, current_state=unstarted.

Update (PUT …/stories/{sid}): ті самі поля, усі необов’язкові, плюс "position" (float) та "force_state_change" (bool).

Transition (POST …/transitions): { "to": "<state>", "reason"? }. Поле — це to. Повертає { story_id, state }. Неприпустимий рух → 422 invalid_transition з details: { from, to, allowed }.

Bulk transition (POST …/bulk_transition): { "story_ids": [int,…] (1–100), "to": "<state>", "reason"? }. Кожна історія оцінюється незалежно; повертає { results: [ { id, status: "ok" } | { id, status: "failed", error } ] }.

Підресурси історії

Усі member. Перелік/GET для більшості — (viewer).

Метод	Шлях	Тіло / примітки
GET / POST	/projects/{id}/stories/{sid}/tasks · PUT/DELETE …/tasks/{tid}	{ description (or task_desc), complete?, task_order? }
GET / POST	/projects/{id}/stories/{sid}/comments · PUT/DELETE …/comments/{cid}	{ text (or comment_text) } або { comment_emoji }
GET / POST	/projects/{id}/stories/{sid}/blockers · PUT/DELETE …/blockers/{bid}	{ blocker_desc, resolved? }
GET / POST	/projects/{id}/stories/{sid}/links · DELETE …/links/{lid}	{ url, link_type?, title? }
GET / POST	/projects/{id}/stories/{sid}/reviews · PUT/DELETE …/reviews/{rid}	{ reviewer_id? / reviewer_agent_id?, status, comment? }
GET / POST	/projects/{id}/stories/{sid}/owners · DELETE …/owners/{mid} · DELETE …/owners/agents/{aid}	{ member_id? / agent_id? } — пропустіть обидва, щоб додати викликача
GET / POST	/projects/{id}/stories/{sid}/followers · DELETE …/followers/{mid} · DELETE …/followers/agents/{aid}	{ member_id? / agent_id? }
GET / POST	/projects/{id}/stories/{sid}/labels · DELETE …/labels/{lid}	{ name }
GET / POST	/projects/{id}/stories/{sid}/attachments (+ /json) · DELETE …/attachments/{aid}	завантаження multipart (≤ 2 ГБ кожне); перелік — (viewer)

Мітки

member для записів, (viewer) для читань.

Метод	Шлях	Опис
GET / POST	/projects/{id}/labels	Перелічити / створити мітку
PUT / DELETE	/projects/{id}/labels/{lid}	Оновити / видалити мітку
POST	/projects/{id}/labels/{lid}/archive	Архівувати (м’яко приховати) мітку

Ітерації

Метод	Шлях	Опис
GET	/projects/{id}/iterations	Перелічити ітерації (member)
POST	/projects/{id}/iterations	Створити ручну ітерацію (owner)
DELETE	/projects/{id}/iterations/{itid}	Видалити ітерацію (owner)

Пошук, аналітика, метрики, налаштування

Метод	Шлях	Опис
GET	/projects/{id}/search?query=…	Пошук із синтаксисом фільтрів (viewer) — дивіться Посібник
GET	/projects/{id}/analytics/{overview,iteration,releases,activity,cycle-time,projections}	Аналітика (viewer). Деталізація ітерації приймає ?iteration_id=
GET	/projects/{id}/metrics/{velocity,burndown,story-types}	Метрики (viewer)
GET / PUT	/projects/{id}/preferences	Ваші налаштування дошки для цього проєкту (member)

Події

Метод	Шлях	Опис
GET	/projects/{id}/events	Потік подій із курсорною пагінацією (viewer)

Параметри запиту: since=<event_id>, types=story.created,story.transitioned,comment.created,…, limit=, cursor=. Відповідь містить next_cursor. Передайте останній event_id, який ви бачили, як since, щоб відновитися.

Імпорт (owner)

Метод	Шлях	Опис
POST	/projects/{id}/import (+ /json)	Завантаження multipart. source= ∈ pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json.

WebSocket

wss://eastagiletracker.com/ws/control?token=<key>

Для інтерактивного дистанційного керування інтерфейсом ({ "action": "get_state", "id": "req-1" }). Не канал даних — усі читання/записи йдуть через REST. Лише для одного екземпляра; не розподіляється між репліками.

Ідемпотентність

Кінцеві точки запису (POST, PUT, DELETE) приймають заголовок Idempotency-Key. Той самий ключ + те саме тіло відтворює кешовану відповідь (24-годинне вікно); той самий ключ + інше тіло повертає 409 idempotency_conflict. Не застосовується до GET/HEAD/OPTIONS, /auth/* чи шляхів /attachments. Відповіді 5xx ніколи не кешуються — повторна спроба досягає обробника.

Пагінація

Кінцеві точки списків приймають cursor=<opaque> та limit=<n≤200>. Коли задано, відповідь має вигляд { "items": [...], "next_cursor": "<str|null>" }; передайте next_cursor назад для переходу на сторінку. Деякі списки також повертають заголовок X-Tracker-Pagination-Total.

Проєкція полів

Кінцеві точки списків приймають fields= (розділені комами), щоб повертати лише конкретні поля. story_id завжди включається; невідоме ім’я поля повертає 400 validation_failed з порушуючими іменами в details.fields.

GET /projects/123/stories?fields=story_id,name,current_state,owners

Формат помилок

Кожна помилка JSON має code та error; деякі додають details:

{ "code": "invalid_transition",
  "error": "Cannot move story from `unstarted` to `accepted`",
  "details": { "from": "unstarted", "to": "accepted", "allowed": ["started"] } }

Статус	code	Коли
400	invalid_parameter	поганий ввід; повідомлення в error, без details (більшість перевірок: порожнє/довжина/null-байт/email)
400	validation_failed	структурована помилка вводу; details.fields — це масив імен полів, що порушують правило
401	unauthenticated	відсутній/недійсний токен
403	unauthorized_operation	автентифіковано, але недостатня роль
404	unfound_resource	не знайдено — також повертається не-учасникам
409	conflict	конфлікт ресурсу (наприклад, дублікат)
409	idempotency_conflict	Idempotency-Key повторно використано з іншим тілом
422	invalid_transition	неприпустимий рух стану; details несе { from, to, allowed }
500	internal_error	помилка сервера — загальне повідомлення; безпечно повторювати

details.fields — це JSON масив імен полів (наприклад, ["to"]), іноді з додатковими ключами на кшталт max. Немає відображення поле→повідомлення.

{ "code": "validation_failed", "error": "unknown field(s): foo", "details": { "fields": ["foo"] } }

Обмеження частоти

Для кожного ключа (для кожного IP для кінцевих точок без автентифікації), токен-бакет GCRA:

• Auth — /auth/*: 0.5 запит/с, сплеск 20.
• Public — /contact, /feedback: 0.2 запит/с, сплеск 10.
• Sensitive — скидання пароля: ~0.002 запит/с, сплеск 5.

Перевищення ліміту повертає 429 Too Many Requests із заголовком Retry-After та тілом у простому тексті (не конвертом помилки JSON).