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

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

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

База

https://api.eastagiletracker.com/api/v1

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

Дві групи розташовані на рівень вище, під /api, а не /api/v1: поверхня автентифікації (/api/auth/*) та публічна контактна форма (/api/contact). Їхнє написання через /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	Розв’язати токен запрошення → електронна пошта / прийняти запрошення до проєкту (після автентифікації)
POST	/auth/oauth/link/preview · …/link/confirm · /auth/oauth/merge/preview · …/merge/confirm	Під’єднати обліковий запис GitHub або Google до наявного або об’єднати два облікові записи
POST	/auth/email_addresses/primary/preview · …/primary/confirm	Завершити зміну основної адреси email за посиланням підтвердження з листа

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

Ці діють на викликача і не потребують ролі в проєкті. Вони потребують ідентичності учасника — ключ агента отримує 401 (агенти використовують /agent/me). Виклики, що змінюють облікові дані — пароль, TOTP, ключі доступу, видалення облікового запису, зміна email, перегенерація токена, — потребують сесії браузера; ключ API отримує 403.

Метод	Шлях	Опис
GET	/me	Профіль поточного користувача
PUT	/me	Оновити профіль
DELETE	/me	Видалити обліковий запис — відхиляється, доки ви єдиний власник організації або проєкту, у якому є інші учасники
GET	/me/deletion-impact	Що видалить видалення облікового запису і що йому заважає
PUT	/me/password	Змінити пароль
PUT	/me/settings	Оновити налаштування (тема, налаштування сповіщень)
POST / DELETE	/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 / POST	/me/email_addresses · GET …/email_addresses/offers · PUT …/email_addresses/primary	Ваші адреси email; прийняти адресу підключеного провайдера як додаткову; запитати зміну основної адреси (підтверджується листом)
GET	/me/oauth_identities · DELETE …/oauth_identities/{provider} · POST …/oauth_identities/{provider}/link	Підключені облікові записи для входу (GitHub, Google): перелік, відключення, початок під’єднання
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/v1/feedback · /api/v1/feedback/with-screenshot	Контакт + зворотний зв’язок у застосунку; з обмеженням частоти за 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 іншому учаснику
GET	/organization-invitations/{token} · POST …/{token}/accept	Розв’язати / прийняти надіслане поштою запрошення до організації
GET	/organizations/{oid}/export · 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 / DELETE	/projects/{id}/pin	Закріпити / відкріпити проєкт у вашому списку проєктів
POST	/projects/{id}/transfer-organization	Перенести проєкт до іншої організації — викликач має бути Менеджером проєкту та owner або admin цільової організації
POST	/projects/{id}/slack/test	Надіслати тестове повідомлення до Slack-стрічки проєкту (manager)
GET / POST	/projects/{id}/showcase_claim_eligibility · /projects/{id}/showcase_claim · /projects/{id}/showcase_seed	Публічні вітринні проєкти: перевірити, чи можете ви забрати такий проєкт, забрати його, наповнити його даними (наповнення — для адміністраторів продукту; усі інші отримують 404)
GET	/projects/{id}/audit-log	Читання audit log — історія проєкту плюс активність за історією / за епіком через surface=; доступ залежить від surface, див. нижче
GET	/projects/{id}/events	Потік подій із курсорною пагінацією (member) — дивіться Події

Query-параметри audit log: event_type= (один тип або список через кому), limit= (за замовчуванням 50, обмежується до 1000), before= (keyset-курсор <ISO-8601>|<audit_id> — передайте next_cursor попередньої сторінки), surface= (project_history, story_activities, epic_activities), target_id= (id історії/епіка — обов’язковий, коли surface=story_activities або epic_activities). Доступ: нефільтрований лог — (manager); surface=project_history — (viewer), з прихованими email учасників, коли проєкт їх приховує; 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)
POST	/projects/{id}/memberships/bulk-role · …/memberships/bulk-remove	Змінити роль або видалити багатьох учасників за раз (manager)
GET	/projects/{id}/addable-members · POST /projects/{id}/members/add-existing	Учасники організації, яких ще немає в проєкті / додати одного без запрошення поштою — (manager) і owner або admin організації
POST	/projects/{id}/members/join	Owner або admin організації приєднується до проєкту своєї організації як manager або підвищує себе до цієї ролі (дія Make me owner у списку проєктів)
GET / POST	/projects/{id}/agent_keys	Перелічити (manager) / створити ключі агентів — люди, чия роль входить до політики ролей-творців проєкту; ключі агентів створювати ключі не можуть
PUT / DELETE	/projects/{id}/agent_keys/{kid}	Змінити назву, роль або підказки відповідей ключа / відкликати його (manager)
GET	/projects/{id}/agent_keys/onboarding	Стартовий набір: промпти та конфігураційні файли для поширених агентських клієнтів
GET	/projects/{id}/agents · GET / PUT / DELETE /projects/{id}/agents/{aid}	Агенти проєкту та їхні профілі (ім’я, ініціали, опис, колір); DELETE відкликає агента й усі його ключі — manager або творець агента
POST	/projects/{id}/agents/{aid}/rotate-key · /projects/{id}/agents/{aid}/avatar	Ротувати ключ агента (ідентичність та історія зберігаються) / завантажити його аватар

Історії

Усі записи історій потребують ролі member. Створення історії із заднім числом дат, походженням імпорту (import_source / import_external_id) або зовнішніми власниками чи запитувачем потребує (manager).

Метод	Шлях	Опис
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/bulk-unarchive	Розархівувати багато історій
POST	/projects/{id}/stories/{sid}/duplicate	Дублювати одну історію
POST / DELETE	/projects/{id}/stories/{sid}/epics · …/epics/{eid}	Належність історії до епіків
GET	/short-links/{code} · /story-references	Розв’язати коротке посилання /s/<code> до його історії / розв’язати до 100 посилань — codes= (коди коротких посилань через кому) та ids= (project_id:story_id через кому) — до історій, які може читати викликач

Параметри запиту списку історій: 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_version" (ціле число, version історії — збереження опису відхиляється з 409 stale_write, якщо опис змінився після цієї версії). Старе поле "expected_updated_at" (RFC 3339) застаріле й працює ще один реліз: якщо його надіслано з описом і без expected_version, збереження відхиляється з 409 stale_write, коли воно не дорівнює updated_at історії. Записи історій також враховують 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). Видалення вкладення чи вкладення-посилання потребує того, хто його завантажив, або (manager).

Метод	Шлях	Тіло / примітки
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? }; оновлення: { url, 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}	{ label_id } — наявна мітка проєкту; створюйте мітки через POST /projects/{id}/labels або надсилайте labels у PUT історії
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/v1/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	Перелічити / створити мітку
GET / 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	Вікно, прогнозована швидкість і заповнення з Backlog для ітерації, яку створив би початковий запис, або для поточної ітерації, якщо вона є (member)
POST	/projects/{id}/iterations	Створити ручну ітерацію (manager)
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_id=<event_id> (since — старіший псевдонім; якщо надіслано обидва, перевагу має since_id), types=story.created,story.transitioned,comment.added,…, limit= (за замовчуванням 100, ≤ 500), cursor=. Відповідь має вигляд { items, next_since_id, next_cursor }: збережіть next_since_id і передайте його назад як since_id, щоб відновитися; на останній сторінці next_cursor дорівнює null.

Сповіщення

Єдина стрічка сповіщень у застосунку: повноцінні рядки сповіщень (запити на рецензію, активність по історіях, запрошення, …), об’єднані зі вхідними @-згадками в один потік, спочатку нові. 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, а також include_comments (типово true); файлові джерела надсилають 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

У проєкті одночасно виконується один JSON-імпорт; другий POST …/import/json, поки один триває, дає 409 import_already_running. З check_unpointed_estimates: true (файлові джерела; для github ігнорується) файл з оцінками багів чи рутинних задач, які проєкт не оцінює очками, відхиляється з 409 import_unpointed_estimates і details.count до запуску будь-якого завдання; без прапорця імпорт відкидає ці оцінки та повідомляє { code: "estimates_unpointed_dropped", count } у warnings результату. dry_run: true (у тілі JSON або dry_run=true multipart) робить попередній перегляд будь-якого джерела: розбирає, розв’язує, усуває дублікати, повертає ті самі підрахунки { imported, skipped, errors, unmatched }, а потім відкочує — нічого не записується. Обмеження: файл 10 МіБ (400 import_too_large) та 5 000 історій на імпорт для файлових джерел (400 import_too_many_records); нічого не записується. Тіло запиту понад 16 МіБ відхиляється раніше з 413 request_too_large. Джерело 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	Перелічити знімки, зробити знімок зараз, прочитати один, а також зведення про стан зберігання
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. Кінцеві точки провайдера мають власний рівень обмеження частоти.

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

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

Пагінація

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

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

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

Списки історій, коментарів і проєктів приймають fields= (розділені комами), щоб повертати лише конкретні поля. Id ресурсу завжди включається (story_id, story_comment_id та comment_id, project_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. Перевірка полів (порожнє/довжина/null-байт/email) додає details.fields і details.constraint; details бракує лише у простої помилки некоректного запиту
400	validation_failed	структурована помилка вводу; details.fields — це масив імен полів, що порушують правило
400	доменні коди	відмова, специфічна для маршруту, з власним кодом і без details — наприклад, unsupported_export_format, import_too_large, import_unknown_source
401	unauthenticated	відсутній/недійсний токен
403	unauthorized_operation	автентифіковано, але недостатня роль
404	unfound_resource	не знайдено — також повертається не-учасникам
409	conflict	конфлікт ресурсу (наприклад, дублікат)
409	idempotency_conflict	Idempotency-Key повторно використано з іншим тілом
409	stale_write · import_already_running · import_unpointed_estimates	опис змінився після вашого expected_version (або expected_updated_at більше не збігається) · імпорт уже виконується · у файлі є оцінки багів чи рутинних задач, які проєкт не оцінює очками (details.count)
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	помилка сервера — загальне повідомлення; безпечно повторювати
502	upstream_error	збій сервісу, від якого залежить маршрут (наприклад, GitHub)
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/v1/feedback та /api/v1/feedback/with-screenshot: три накладені рівні — одне надсилання на 15 с, 10 на годину, 36 на добу.
• Avatars — редирект аватара без автентифікації: 20 запит/с, сплеск 200.
• Sensitive — POST-запити резервного копіювання та відновлення: ~0.002 запит/с, сплеск 5.

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