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

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

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

База

https://eastagiletracker.com/api/v1

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

Дві групи розташовані на рівень вище, під /api, а не /api/v1: поверхня автентифікації (/api/auth/*) та публічні форми (/api/contact, /api/feedback). Їхнє написання через /api/v1/… повертає 404.

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

Кожен автентифікований запит надсилає облікові дані одним із способів:

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

Користувацькі ключі починаються з ea_user_, ключі агентів — з ea_agent_, а access-токени MCP — з ea_mcp_. Дивіться Посібник з API → Три види облікових даних.

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

Ролі

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

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

Агенти мають ті самі ролі, що й учасники, — viewer, member або manager, — обмежені роллю учасника, який створив ключ. Не-учасник отримує 404 unfound_resource (а не 403) на шляхах приватного проєкту, тож ID проєктів не можна перелічити.

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

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

Auth (/api/auth/*, поза /v1)

Кінцеві точки сесій, без автентифікації, якщо не зазначено інше. Ними керує SPA; скрипти зазвичай використовують натомість ключ API.

Метод	Шлях	Опис
POST	/auth/register	Зареєструвати новий обліковий запис — захищено reCAPTCHA; далі обліковий запис проходить SMS-перевірку
POST	/auth/sms/challenge · /auth/sms/status · /auth/sms/bypass	Надіслати / перевірити SMS-код реєстрації (bypass доступний лише оператору)
GET	/auth/config	Які способи входу пропонує розгортання
POST	/auth/login	Вхід за email + паролем; повертає JWT сесії або TOTP-запит
POST	/auth/login/totp	Завершити вхід кодом із застосунку-автентифікатора або кодом відновлення
POST	/auth/passkey/login/start · /auth/passkey/login/finish	Безпарольний вхід через WebAuthn
GET	/auth/oauth/github/start · /auth/oauth/github/callback · /auth/oauth/google/start · /auth/oauth/google/callback · POST /auth/oauth/exchange	Вхід через OAuth з GitHub або Google
POST	/auth/refresh · /auth/refresh/revoke	Ротувати токен оновлення / відкликати його
POST	/auth/logout	Вийти (відкликає токен оновлення)
POST	/auth/forgot-password · /auth/reset-password	Запитати лист для скидання / використати токен скидання
POST	/auth/accept-invite/lookup · /auth/accept-invite	Розв’язати токен запрошення → електронна пошта / прийняти запрошення до проєкту (після автентифікації)

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

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

Метод	Шлях	Опис
GET	/me	Профіль поточного користувача
PUT	/me	Оновити профіль
DELETE	/me	Видалити обліковий запис — відхиляється, доки ви єдиний власник організації або проєкту, у якому є інші учасники
GET	/me/deletion-impact	Що видалить видалення облікового запису і що йому заважає
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/totp · POST /me/totp/setup · /me/totp/verify · /me/totp/disable	Підключення двофакторної автентифікації (TOTP); verify один раз повертає коди відновлення
GET	/me/passkeys · POST /me/passkeys/register/start · /me/passkeys/register/finish · DELETE /me/passkeys/{credential_id}	Реєстрація та видалення ключів доступу
GET	/me/oauth_grants · DELETE /me/oauth_grants/{grant_id}	Підключені застосунки — MCP-клієнти та OAuth-застосунки, яким ви надали доступ
GET	/me/activity	Ваша активність у всіх проєктах
GET	/me/stories	Історії, якими ви володієте, які запитали чи за якими стежите, в усіх проєктах, доступних токену — role=owned|requested|following, state=, cursor= / limit= (максимум 200)
GET	/me/mentions · POST /me/mentions/{mention_id}/ack	Вхідні @-згадки (unacked=true для фільтрації) та підтвердження — також зведені до стрічки сповіщень нижче
GET	/me/data-export	Самостійний експорт ваших даних за GDPR
GET	/me/consent · POST /me/consent	Прочитати / записати згоду ({ consent_type, granted })
GET	/legal/pending · POST /legal/accept	Очікувані документи clickwrap / запис прийняття
GET / PUT	/agent/me	Власна ідентичність і профіль ключа агента, доступні агенту для читання та редагування (аналог /me на боці агента)
POST	/api/contact · /api/feedback · /api/feedback/with-screenshot	Контакт + зворотний зв’язок у застосунку. Поза /v1; з обмеженням частоти за IP

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

Стартові пошуки, що використовуються при створенні/оцінюванні історій. Стабільні 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	/priority_scales · /priority_scales/{scale_id}/values	шкали пріоритетів та їхні значення (priority_id історії розв’язується тут)

Організації

Лише в хмарному сервісі — самостійно розміщена інсталяція працює в режимі однієї організації й не монтує ці кінцеві точки (крім списку організацій). Ролі тут організаційні: owner, admin, member.

Метод	Шлях	Опис
GET / POST	/organizations	Перелічити ваші організації / створити організацію
GET / PUT / DELETE	/organizations/{oid}	Прочитати, перейменувати (назва + slug; owner або admin), видалити
GET / POST	/organizations/{oid}/memberships · PUT / DELETE …/memberships/{member_id}	Учасники та запрошення; запрошення має стелю ролі (ніколи не вище за роль того, хто запрошує; роль owner ніколи не надається запрошенням)
POST	/organizations/{oid}/memberships/bulk-role · …/memberships/bulk-remove	Зміна ролі або видалення до 200 учасників за раз. Усе або нічого: пакет, який видалив би останнього owner або залишив проєкт без власника, відхиляється повністю; з reassign_confirmed власником цих проєктів стаєте ви
DELETE	/organizations/{oid}/invitations/{invitation_id}	Відкликати очікуване запрошення
POST	/organizations/{oid}/transfer-ownership	Передати роль owner іншому учаснику
PUT	/organizations/{oid}/memberships/{member_id}/anonymization	Приховати ім’я / email / аватар учасника в усій організації
GET	/organization-invitations/{token} · POST …/{token}/accept	Розв’язати / прийняти надіслане поштою запрошення до організації
POST	/organizations/{oid}/export · GET / POST …/export/jobs · GET …/export/jobs/{job_id} · …/export/jobs/{job_id}/download	Експорт організації, лише для власника: zip із SQL-дампом і кожним вкладенням, виконується як завдання

Проєкти

Метод	Шлях	Опис
GET	/projects	Перелічити ваші проєкти (limit ≤ 200)
POST	/projects	Створити проєкт
GET	/projects/{id}	Отримати деталі проєкту (viewer)
PUT	/projects/{id}	Оновити налаштування проєкту (manager)
DELETE	/projects/{id}	Видалити проєкт (manager)
POST	/projects/{id}/pin	Закріпити / відкріпити проєкт у вашому списку проєктів
POST	/projects/{id}/transfer-organization	Перенести проєкт до іншої організації (manager)
POST	/projects/{id}/slack/test	Надіслати тестове повідомлення до Slack-стрічки проєкту (manager)
GET / POST	/projects/{id}/showcase_claim_eligibility · /projects/{id}/showcase_claim · /projects/{id}/showcase_seed	Публічні вітринні проєкти: перевірити, чи можете ви забрати такий проєкт, забрати його, наповнити його даними
GET	/projects/{id}/audit-log	Читання audit log — історія проєкту плюс активність за історією / за епіком через surface=; доступ залежить від surface, див. нижче
GET	/projects/{id}/events	Потік подій із курсорною пагінацією (member) — дивіться Події

Query-параметри audit log: event_type= (один тип або список через кому), limit= (≤ 1000), before= (keyset-курсор, created_at в ISO-8601), surface= (project_history, story_activities, epic_activities), target_id= (id історії/епіка — обов’язковий, коли surface=story_activities або epic_activities). Доступ: нефільтрований лог і surface=project_history — (manager); story_activities / epic_activities може читати будь-який учасник проєкту, а в публічних проєктах — і анонімно, з прихованими персональними даними актора.

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

Метод	Шлях	Опис
GET	/projects/{id}/memberships	Перелічити учасників (viewer)
POST	/projects/{id}/memberships	Запросити учасника за електронною поштою (manager)
PUT	/projects/{id}/memberships/{mid}	Оновити роль (manager)
DELETE	/projects/{id}/memberships/{mid}	Видалити учасника (manager)
GET	/projects/{id}/addable-members · POST /projects/{id}/members/add-existing	Учасники організації, яких ще немає в проєкті / додати одного без запрошення поштою (manager)
POST	/projects/{id}/members/join	Owner або admin організації приєднується до проєкту своєї організації як manager або підвищує себе до цієї ролі (дія Make me owner у списку проєктів)
PUT	/projects/{id}/members/{mid}/anonymization	Приховати ім’я / email / аватар учасника в цьому проєкті (manager)
GET / POST	/projects/{id}/agent_keys	Перелічити / створити ключі агентів — менеджери або ролі, які допускає політика ролей-творців проєкту
DELETE	/projects/{id}/agent_keys/{kid}	Відкликати ключ агента
GET	/projects/{id}/agent_keys/onboarding	Стартовий набір: промпти та конфігураційні файли для поширених агентських клієнтів
GET	/projects/{id}/agents · GET / PUT /projects/{id}/agents/{aid}	Агенти проєкту та їхні профілі (ім’я, ініціали, опис, колір)
POST	/projects/{id}/agents/{aid}/rotate-key · /projects/{id}/agents/{aid}/avatar	Ротувати ключ агента (ідентичність та історія зберігаються) / завантажити його аватар

Історії

Усі записи історій потребують ролі 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/{sid}/reject · /projects/{id}/stories/{sid}/restart	Відхилити доставлену історію / повернути відхилену до started (rejected — кінцевий стан для /transitions)
POST	/projects/{id}/stories/{sid}/archive · /projects/{id}/stories/{sid}/unarchive	Архівувати / розархівувати одну історію
POST	/projects/{id}/stories/bulk_transition	Перевести багато історій (1–100) за раз
POST	/projects/{id}/stories/bulk-archive · bulk-delete · bulk-duplicate · bulk-move	Архівувати, видалити, дублювати або перемістити (до панелі / на позицію) багато історій
POST	/projects/{id}/stories/{sid}/duplicate	Дублювати одну історію
GET / POST / DELETE	/projects/{id}/stories/{sid}/epics · …/epics/{eid}	Належність історії до епіків
GET	/short-links/{code} · /story-references	Розв’язати коротке посилання /s/<code> до його історії / розв’язати до 100 посилань на історії (#id, URL) до історій, які може читати викликач

Параметри запиту списку історій: archived= (exclude за замовчуванням / include / only — тристановий фільтр архівованих; замінює застарілий include_archived=true, який тепер є псевдонімом archived=include), include_done=true (допускає історії панелі Done, заморожені на минулих ітераціях; за замовчуванням виключені). Пагінація (cursor= / limit= / offset=) та часткові набори полів (fields=) відповідають розділам Пагінація та Проєкція полів.

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

Update (PUT …/stories/{sid}): ті самі поля, усі необов’язкові, плюс "position" (float), "force_state_change" (bool) та "expected_updated_at" (RFC 3339 — збереження опису відхиляється з 409 stale_write, якщо історія змінилася відтоді, як ви її прочитали). Записи історій також враховують If-Match відносно ETag історії; розбіжність — це 412 precondition_failed.

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

Bulk transition (POST …/bulk_transition): { "story_ids": [int,…] (1–100), "to": "<state>" }. Кожна історія оцінюється незалежно; повертає { 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 приймає fields= (список дозволених: comment_id, story_comment_id, story_id, comment_text, comment_emoji, member, created) плюс cursor= / limit= (≤ 200) / order=asc|desc
GET / POST	/projects/{id}/stories/{sid}/blockers · PUT/DELETE …/blockers/{bid}	{ blocker_desc, resolved? }
GET / POST	/projects/{id}/stories/{sid}/links · PUT/DELETE …/links/{lid}	{ url, link_type?, title? } — link_type ∈ relates_to, duplicates, blocks, is_blocked_by, pull_request, branch, other; URL GitHub виду /pull/ та /tree/ отримують тип автоматично
GET / POST	/projects/{id}/stories/{sid}/reviews · PUT/DELETE …/reviews/{rid}	Створення: { reviewer_id? / reviewer_agent_id?, comment? } — пропустіть обидва, щоб призначити себе. Оновлення: { 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 — відео ≤ 200 МБ, PDF / Word / Excel ≤ 25 МБ, зображення / CSV / текст ≤ 10 МБ; перелік — (viewer)
GET / POST	/projects/{id}/stories/{sid}/link-attachments · DELETE …/link-attachments/{laid}	Вкладення-посилання — зовнішній URL, що зберігається поряд із файловими вкладеннями, а не як посилання на код
GET	/attachments/{token} · /api/avatars/{token}	Читання вкладення чи аватара за токеном — саме такі URL видає API; X-TrackerToken не потрібен

Епіки

Та сама структура, що й в історій, лише без машини станів. member для записів, (viewer) для читань.

Метод	Шлях	Опис
GET / POST	/projects/{id}/epics · GET / PUT / DELETE …/epics/{eid}	Епіки мають назву, опис у Markdown і пов’язану мітку, що об’єднує їхні історії
GET / POST / PUT / DELETE	…/epics/{eid}/comments · …/comments/{cid}	Коментарі до епіка
GET / POST / DELETE	…/epics/{eid}/owners · …/followers (+ варіанти /agents/{aid})	Власники та спостерігачі, учасники чи агенти — власники епіка поширюються на його історії
GET / POST / DELETE	…/epics/{eid}/attachments (+ /json) · …/link-attachments	Вкладення, ті самі обмеження, що й для історій
GET	/projects/{id}/analytics/epics · …/analytics/epics/{eid}	Прогрес кожного епіка: діаграма зростання, пропускна здатність, стан, прогноз (viewer)

Мітки

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

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

Ітерації

Читання відкрите для будь-якої ролі в проєкті, а в публічному проєкті — й анонімно.

Метод	Шлях	Опис
GET	/projects/{id}/iterations	Перелічити ітерації (≤ 500 на сторінку; містить ETag та заголовки продовження X-Tracker-Pagination-*, коли відповідь обрізано)
GET	/projects/{id}/iterations/{itid}	Одна ітерація
GET	/projects/{id}/iterations/first-preview	Дати, які отримає перша ітерація, — показуються в підтвердженні її створення
POST	/projects/{id}/iterations	Створити ручну ітерацію (member)
DELETE	/projects/{id}/iterations/{itid}	Видалити ітерацію (manager)
PUT	/projects/{id}/iterations/{itid}/velocity	Перевизначити швидкість однієї ітерації, не змінюючи стратегію проєкту (manager)
GET	/projects/{id}/iterations/{itid}/done-stories	Прийняті історії закритої ітерації, з пагінацією

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

Метод	Шлях	Опис
GET	/projects/{id}/search?q=…	Потужний пошук — повнотекстовий + кваліфікатори аспектів / діапазонів дат / людей (DSL у стилі GitHub); повертає { results, total, limit, offset }. query — псевдонім q; limit= (за замовчуванням 50, макс. 1000) / offset= для пагінації; sort= упорядковує за relevance (за замовчуванням), created, created_asc, state або updated. (viewer) — дивіться Посібник
GET	/projects/{id}/metrics/{velocity,burndown,story-types,contributors}	Ряди даних сторінки Metrics (viewer); метрики епіків — у /analytics/epics вище
GET	/projects/{id}/backlog/grouping	Спрогнозовані групи ітерацій Backlog (viewer)
GET / PUT	/projects/{id}/preferences	Ваші налаштування дошки для цього проєкту — будь-яка роль у проєкті, лише ваш власний рядок

Події

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

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

Сповіщення

Єдина стрічка сповіщень у застосунку: повноцінні рядки сповіщень (запити на рецензію, активність по історіях, запрошення, …), об’єднані зі вхідними @-згадками в один потік, спочатку нові. Id у стрічці мають префікс джерела (nt-… / sc-… / ec-…). Сесії учасників і ключі ea_user_* читають свої рядки учасника; ключі ea_agent_* — свої рядки агента.

Метод	Шлях	Опис
GET	/me/notifications	Ваша стрічка сповіщень. Фільтри: unread=true, since_id=, kind= (mentions / reviews / stories / invitations); пагінація через cursor= / limit=
GET	/me/notifications/unread-count	Лічильники непрочитаного — { unread_count, by_category: { mentions, reviews, stories, invitations } }
POST	/me/notifications/read-all	Позначити все прочитаним; повертає свіжі лічильники
POST	/me/notifications/{id}/ack	Позначити один елемент прочитаним (ідемпотентно)
POST	/me/notifications/{id}/accept	Прийняти запрошення до проєкту / організації просто зі стрічки (лише токени учасника)
POST	/me/notifications/{id}/decline	Відхилити запрошення до проєкту / організації (лише токени учасника)
GET	/me/notifications/resolve-invite?token=…	Зіставити надісланий поштою токен запрошення з id вашого сповіщення — { "id": "nt-…" } або { "id": null }
GET	/me/notifications/stream	Живий push — Server-Sent Events (text/event-stream); див. нижче

Stream-ендпоінт — не JSON-ендпоінт, тому його немає у специфікації OpenAPI: він тримає з’єднання відкритим і щоразу, коли надходить щось нове, надсилає кадр без корисного навантаження ({"type":"notification","kind":…}), сигналізуючи клієнту перезавантажити стрічку. З’єднання закриваються сервером через 45 хвилин — перепідключіться та автентифікуйтеся знову. Лише сесії учасників і ключі ea_user_*; ключі ea_agent_* отримують 403.

Імпорт (manager)

Метод	Шлях	Опис
POST	/projects/{id}/import	Файлові джерела: source= ∈ pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json, eat. Multipart file=. Синхронний — відповідає підрахунками результату.
POST	/projects/{id}/import/json	Тіло JSON; source=github не потребує файлу — owner, repo, необов’язковий token та опційні прапорці include_pull_requests / include_milestones / include_releases / include_dependencies; файлові джерела надсилають file_base64. Асинхронний: повертає 202 { import_id, status }. Сервер вибирає дані через GraphQL API GitHub, який відхиляє анонімні виклики, тож до GitHub завжди доходить токен — ваш або спільний токен розгортання. Див. Посібник.
GET	/projects/{id}/imports/{import_id}	Опитати завдання: status проходить pending → fetching → writing → done | failed, з progress_current / progress_total під час вибірки та підрахунками результату при done

У проєкті одночасно виконується один імпорт; другий POST, поки один триває, дає 409 import_already_running. dry_run: true (у тілі JSON або dry_run=true multipart) робить попередній перегляд будь-якого джерела: розбирає, розв’язує, усуває дублікати, повертає ті самі підрахунки { imported, skipped, errors, unmatched }, а потім відкочує — нічого не записується. Обмеження: тіло 10 МіБ та 5 000 історій на імпорт для файлових джерел (перевищення будь-якого → 400, без запису). Джерело GitHub стелі не має — воно фіксує зміни порціями, а не однією транзакцією. Повторний імпорт ідемпотентний за id у джерелі — уже імпортовані рядки пропускаються, а не дублюються.

Експорт

Метод	Шлях	Опис
GET	/projects/{id}/export/formats	Зареєстровані формати: { id, name, content_type, drops, includes_archived }. Будь-яка роль у проєкті.
GET	/projects/{id}/export/{format}	Завантажити один (manager). Обмін: eat (повна точність), jira, pivotal, shortcut, trello, asana, gitlab, linear, plane, plane_json; документи: pdf, docx.
GET	/projects/{id}/export/attachments	Кожне вкладення одним переглядуваним zip (файли зберігають оригінальні імена; маніфест JSON + CSV) (manager).

Експорти документів (pdf, docx) приймають додаткові параметри запиту: page_size= (letter за замовчуванням / a4 / legal / folio), from= / to= (межі вікна історій — RFC 3339 або просто YYYY-MM-DD; історія потрапляє в діапазон, коли її created або completed_at лежить усередині нього), include_icebox= / include_backlog= (обидва за замовчуванням false, тож експорт для поширення показує лише заплановану / поточну роботу). Формати обміну CSV їх ігнорують.

Резервні копії та відновлення (manager)

Метод	Шлях	Опис
GET / POST	/projects/{id}/backups · GET …/backups/{snapshot_id} · …/backups/health	Перелічити знімки, зробити знімок зараз, прочитати один, а також зведення про стан зберігання
GET / POST	/projects/{id}/restores · POST …/restores/partial · GET …/restores/{restore_id}	Відновити знімок цілком або вибрані таблиці з нього та опитувати хід відновлення

Ці POST належать до чутливого рівня обмеження частоти (див. нижче).

MCP та OAuth-провайдер

East Agile Tracker — це OAuth 2.1-провайдер для MCP-клієнтів. Клієнт знаходить його за /.well-known/oauth-authorization-server та /.well-known/oauth-protected-resource/mcp, спрямовує вас на /oauth/authorize (сторінка згоди), обмінює код на /oauth/token, а потім спілкується за MCP на /mcp з отриманим токеном ea_mcp_*. Надані дозволи перелічуються й відкликаються на /me/oauth_grants. Кінцеві точки провайдера мають власний рівень обмеження частоти.

WebSocket

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

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

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

Кінцеві точки запису (POST, PUT, DELETE) приймають заголовок Idempotency-Key. Той самий ключ + те саме тіло відтворює кешовану відповідь (24-годинне вікно); той самий ключ + інше тіло повертає 409 idempotency_conflict. Ключ обмежений обліковими даними, які його надіслали. Не застосовується до GET/HEAD/OPTIONS, /openapi.json та /docs, /api/auth/* чи multipart-завантажень на шляхах /attachments. Відповіді, що не дійшли до відповіді домену, ніколи не кешуються — 401, 403, 404, 429 і будь-який 5xx, — тож повторна спроба після будь-якої з них досягає обробника; 400, 409, 412 та 422 — це відповідь домену, і вони відтворюються так само, як успішні.

Пагінація

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

Звичайний список (без cursor/limit), якому довелося обрізати відповідь, повідомляє про це в заголовках — X-Tracker-Pagination-Truncated, X-Tracker-Pagination-Limit, X-Tracker-Pagination-Offset та X-Tracker-Pagination-Next-Offset; останній передайте назад як offset= для наступної сторінки. Заголовка із загальною кількістю немає.

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

Кінцеві точки списків приймають 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 повторно використано з іншим тілом
409	stale_write · import_already_running	історія змінилася після вашого expected_updated_at · імпорт уже виконується
412	precondition_failed	If-Match не збігся з поточним ETag ресурсу; details несе expected та current
413	request_too_large	тіло перевищує обмеження розміру для цього маршруту
422	invalid_transition	неприпустимий рух стану; details несе { from, to, allowed }
429	rate_limited	забагато запитів із цього IP на маршруті з обмеженням частоти; заголовок Retry-After
500	internal_error	помилка сервера — загальне повідомлення; безпечно повторювати
503	not_configured	у розгортанні немає інтеграції, потрібної цьому маршруту (SMS, об’єктне сховище, …)

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

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

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

За IP клієнта, на кількох маршрутах; решта автентифікованого трафіку API не обмежується за частотою. Значення за замовчуванням (кожна пара — стала частота та сплеск, налаштовуються оператором):

• Auth — /api/auth/*: 0.5 запит/с, сплеск 20.
• OAuth provider — /oauth/*: 1 запит/с, сплеск 60.
• Public — /api/contact: 0.2 запит/с, сплеск 10.
• Feedback — /api/feedback: три накладені рівні — одне надсилання на 15 с, 10 на годину, 36 на добу.
• Avatars — редирект аватара без автентифікації: 20 запит/с, сплеск 200.
• Sensitive — POST-запити резервного копіювання та відновлення: ~0.002 запит/с, сплеск 5.

Перевищення ліміту повертає 429 із заголовком Retry-After та стандартним конвертом помилки JSON, code: "rate_limited".