Посібник з API

API East Agile Tracker спроєктовано для агентів не менше, ніж для людей. Усе, що ви можете зробити в інтерфейсі, ви можете зробити через API — а ще там є кілька речей, яких інтерфейс не показує.

Цей посібник проведе вас від нуля до «скриптування свого беклогу» менш ніж за десять хвилин. Повну довідку по кінцевих точках дивіться в Специфікації API.

Три види облікових даних

Ви автентифікуєтеся за допомогою ключа в заголовку X-TrackerToken. Є два види ключів, які ви створюєте самі, і третій, який MCP-клієнт отримує за вас:

Користувацькі ключі (ea_user_…) — діють як ви. Створюйте їх в Account Settings → API Keys. Використовуйте їх для особистих скриптів, інструментів CLI, інтеграцій.
Ключі агентів (ea_agent_…) — діють як названий агент в одному проєкті. Створюйте їх в Project Settings → Agents. Використовуйте їх для AI-агентів — Claude Code, Codex, власних — які мають брати участь у проєкті як названі члени команди.
MCP-токени (ea_mcp_…) — access-токени OAuth 2.1, що видаються MCP-клієнту (Claude, IDE) після того, як ви схвалите його на сторінці згоди. Вони діють як ви, і ви можете відкликати їх в Account Settings → Connected apps.

Одноразове вікно після створення особистого API-ключа в налаштуваннях облікового запису; ключ на цьому знімку приховано

Форма створення ключа на вкладці Agent з іменем і вибраною роллю member під інструкціями з налаштування

Відмінності між двома видами, які ви створюєте самі:

	Користувацький ключ	Ключ агента
Область дії	Усі ваші проєкти	Один конкретний проєкт
Ідентичність у журналі аудиту	Ваше ім’я	Ім’я агента
Роль	Ваша роль у кожному проєкті	Задається при створенні ключа (viewer, member або manager — ніколи не вище за власну роль учасника, що створює ключ)
Відкликання	Відкличте ключ; ви зберігаєте доступ через інші ключі/сесії	Відкличте або ротуйте ключ; агент негайно втрачає доступ
Найкраще для	Особиста автоматизація, скрипти	AI-агенти, яких слід відрізняти від вас в історії

Authorization: Bearer … також працює, якщо ви віддаєте перевагу цьому стилю заголовка.

Привіт, API

Отримайте свої проєкти:

curl https://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: $TRACKER_TOKEN"

Або для ключа агента — перелічіть проєкт, до якого він прив’язаний:

curl https://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: ea_agent_xxxxx"

API — це JSON, у стилі REST, версіонований за /api/v1/. Однакові структури для людей і агентів.

Створення проєкту

curl -X POST https://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Onboarding redesign",
    "description": "Q3 redesign of new-user onboarding",
    "iteration_length_weeks": 1
  }'

Відповідь містить project_id та будь-які значення за замовчуванням, які застосував сервер (шкала оцінювання, завершений стан тощо).

Створення історії

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Add OAuth login for Google",
    "description": "## Acceptance\n- Google button on /login\n- Redirect back to original URL",
    "story_type": "feature",
    "estimate": "3",
    "labels": ["auth"]
  }'

estimate — це підпис значення шкали у вигляді рядка — "3" або "13" на шкалі Fibonacci, — бо він має збігатися з точкою на шкалі проєкту. JSON-число відхиляється.

Проведення історії через життєвий цикл

Кінцева точка переходу перевіряє запитаний рух і повертає дозволені наступні стани при помилці:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/$STORY_ID/transitions \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "to": "started" }'

Поле — це to (не to_state). Якщо рух неприпустимий — скажімо, ви спробували перескочити з unstarted прямо до accepted — відповідь буде 422 invalid_transition зі структурованими деталями помилки:

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

Це одна з дрібниць, що робить API дружнім до агентів: агент може прочитати details.allowed і обрати правильний наступний рух без вишкрібання прози.

rejected — кінцевий стан для кінцевої точки переходів. Щоб повернути відхилену історію в роботу, викличте POST …/stories/{sid}/restart; POST …/stories/{sid}/reject — дієслівна форма відхилення доставленої історії.

Коментування історії

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/$STORY_ID/comments \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Investigation done. Picking this up." }'

Коментар приписується тому, хто володіє ключем API — якщо це ключ агента, автором коментаря є агент.

Ідемпотентні записи

Кожна кінцева точка запису приймає заголовок Idempotency-Key. Повторіть той самий ключ із тим самим тілом — отримаєте ту саму відповідь назад. Повторіть той самий ключ з іншим тілом — отримаєте 409 idempotency_conflict:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Refactor auth middleware", "story_type": "chore" }'

Це критично для агентів у циклах повторних спроб — збій посеред запису, повтор із тим самим ключем, жодних дубльованих історій.

Масові переходи

Переміщайте багато історій за раз. Кожна історія оцінюється незалежно; один неприпустимий рух не провалює інші.

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/bulk_transition \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "story_ids": [101, 102, 103],
    "to": "delivered"
  }'

Слідкування за потоком подій

Для агентів, які хочуть реагувати на те, що роблять люди, опитуйте кінцеву точку подій:

curl "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/events?since=$LAST_CURSOR&types=story.created,story.transitioned,comment.added" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

Відповідь — це потік подій з курсорною пагінацією, з актором, ресурсом і зміною. Кожна подія має ID; передайте останній ID, який ви бачили, як since, щоб відновитися там, де зупинилися. Жодних вебхуків, жодного вишкрібання, жодних пропущених подій. Потоку потрібна роль member — viewer отримує 403.

Пошук

GET /projects/{id}/search?q=<query> виконує потужний повнотекстовий + структурований пошук по історіях проєкту. Мову запитів побудовано за зразком кваліфікаторів пошуку issues у GitHub — тож синтаксис, який ви (або AI-агент) уже знаєте з GitHub, здебільшого переноситься.

curl -G "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/search" \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  --data-urlencode 'q=payment crash type:bug,chore owner:@me created:>2026-05-01'

Відповідь — JSON-конверт, історії ранжовано за релевантністю:

{ "results": [ /* canonical story objects */ ], "total": 42, "limit": 50, "offset": 0 }

total — це повна кількість збігів, а не розмір сторінки. Гортайте за допомогою limit (за замовчуванням 50, максимум 1000) та offset; упорядковуйте через sort=relevance (за замовчуванням), created, created_asc, updated або state.

Граматика

Вільний текст збігається із заголовком, референсом та описом історії (повнотекстовий, зі стемінгом і ранжуванням). Беріть точну фразу в "лапки".
Кваліфікатори мають вигляд field:value. Розділяйте альтернативи комою (АБО в межах поля): type:bug,chore. Розділяйте кваліфікатори пробілами (І між ними).
Заперечуйте будь-який термін чи кваліфікатор провідним -: -label:wontfix.
Діапазони для дат і балів: включний a..b або відкритий >x / <x.

Кваліфікатори

Кваліфікатор	Приклад	Збігається з
`type:`	`type:bug,chore`	тип(и) історії
`state:`	`state:started,finished`	стан(и) робочого процесу
`label:`	`label:"my label"`	мітка
`epic:`	`epic:"Checkout"`	історії в епіку
`priority:`	`priority:p1`	пріоритет
`points:`	`points:3` · `points:1..5` · `points:>3`	значення оцінки або діапазон
`iteration:`	`iteration:42`	id ітерації
`created:` `updated:` `started:` `completed:` `release:`	`created:2026-05-01..2026-06-01` · `updated:>2026-06-01`	дата або діапазон (з точністю до дня); `release:` — дата релізу історії
`owner:` `requester:` `follower:` `reviewer:` `commenter:` `mention:`	`owner:claire` · `owner:@me`	людина за іменем або email — учасники й агенти, зокрема для `mention:`; `@me` — це ви
`has:blocker`	`has:blocker`	має відкритий блокер
`is:`	`is:unestimated` · `is:icebox` · `is:backlog` · `is:blocked`	прапорець

mywork: — псевдонім для owner:: mywork:me — це owner:@me. Старий кваліфікатор scheduled: виведено з ужитку й мовчки ігнорується; використовуйте release:.

АБО через кому (type:bug,chore) застосовується до кваліфікаторів-аспектів; кваліфікатори людей (owner: requester: follower: reviewer: commenter: mention:) приймають одне значення.

Приклади

payment crash                              full text "payment" AND "crash"
"exact phrase"                             a phrase
type:bug,chore state:started               bugs or chores that are started
owner:@me -label:wontfix                   mine, excluding the wontfix label
points:3..8 created:2026-05-01..2026-06-01 estimated 3-8, created in May
follower:tomas has:blocker                 tomas follows it and it's blocked
is:backlog updated:>2026-06-01             backlog items touched since Jun 1

Той самий рядок запиту керує і полем пошуку на дошці (яке відкриває живу колонку результатів), і цим API — одна граматика і для людей, і для агентів. Пошук за вмістом коментарів, завдань і блокерів — у планах; сьогодні вільний текст охоплює заголовок, референс та опис самої історії.

Дослідження API

Актуальна специфікація OpenAPI 3 за адресою:

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

Swagger UI за адресою:

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

/openapi.json та /docs не вимагають автентифікації — агент може прочитати контракт ще до того, як матиме ключ. Щойно він отримає ключ, /api/v1/meta (яка вимагає дійсного ключа) повертає його ідентичність та граф переходів для кожного типу історій; пошуки довідкових даних (/story_types, /story_states, /effort_scales, /priority_scales) також не вимагають автентифікації. Разом вони дозволяють агентам відповісти на запитання «що я можу тут зробити?» без помилок 403 методом проб.

Обслуговуваний openapi.json містить схеми тіл запитів для кінцевих точок запису, зокрема maxLength кожного поля, тож клієнт може перевірити дані перед надсиланням. Специфікація підсумовує ті самі структури.

Керування через WebSocket

Для інтерактивної автоматизації — керування сесією залогіненого браузера зі скрипта чи дистанційне керування інтерфейсом для туторіалів — є канал WebSocket:

const ws = new WebSocket('wss://eastagiletracker.com/ws/control?token=SESSION_JWT')
ws.send(JSON.stringify({ action: 'get_state', id: 'req-1' }))

token — це JWT сесії браузера, а не ключ API: ключ ea_user_* чи ea_agent_* відхиляється ще до апгрейду з’єднання. Більшості користувачів це ніколи не знадобиться; воно існує для випадків, коли REST недостатньо.

Імпорт з іншого трекера

Якщо ви скриптуєте масову міграцію:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/import \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -F "source=pivotal" \
  -F "file=@pivotal_export.csv"

Підтримувані файлові джерела: pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json, eat (власний експорт East Agile Tracker — формат для повного циклу). Multipart-ендпоінт працює синхронно й відповідає підрахунками результату.

GitHub імпортує з API, а не з файлу, через JSON-ендпоінт — без file, лише координати репозиторію:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/import/json \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "source": "github",
        "owner": "octocat",
        "repo": "hello-world",
        "token": "ghp_…",
        "include_pull_requests": false,
        "include_milestones": false,
        "include_releases": false,
        "include_dependencies": false
      }'

JSON-ендпоінт асинхронний: він відповідає 202 з { "import_id", "status" }, а ви опитуєте GET /projects/{id}/imports/{import_id}, доки завдання не досягне done або failed. У проєкті одночасно виконується лише один імпорт — другий виклик, поки один триває, дає 409 import_already_running. Увесь цикл, з полями прогресу завдання, описано в Наповненні проєкту з репозиторію GitHub.

token необов’язковий у запиті, але сама вибірка завжди проходить автентифікацію — вона йде через GraphQL API GitHub, де анонімного рівня немає. Пропустіть token, і сервер підставить платформний токен: лише публічні репозиторії, спільний для всіх викликів, і відхилений з import_github_shared_quota_low, щойно його бюджет GraphQL падає нижче 500 очок. Приватний репозиторій або розгортання, де платформний токен не налаштовано (import_github_no_token), потребує вашого. Хоч би який токен спрацював, він використовується лише для вихідних викликів до GitHub і ніколи не зберігається та не повертається у відповіді. Повні подробиці, включно з неавтентифікованою REST-стелею GitHub у 60 запитів, — у Наповнення проєкту з репозиторію GitHub.

Попередній перегляд у режимі dry-run. Додайте "dry_run": true (JSON) або -F "dry_run=true" (multipart) до будь-якого джерела. Імпорт розбирає, розв’язує та усуває дублікати точно так само, як справжній запуск, повертає ті самі підрахунки результату (imported, skipped, errors, unmatched), а потім відкочує все — нічого не записується. На JSON-ендпоінті підрахунки надходять в опитуване завдання, хоч це dry-run, хоч ні.

Обмеження. Тіло завантаження обмежене 10 МіБ, а один імпорт — 5 000 історій; перевищення будь-якого — це 400 без запису. Повторний імпорт файлу безпечний — рядки, які вже імпортовано (зіставлені за id у джерелі), пропускаються, а не дублюються.

Експорт проєкту

Перелічити формати може будь-яка роль у проєкті; завантаження — лише для власника:

# The registered export formats: { id, name, content_type, drops, includes_archived }
curl https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/export/formats \
  -H "X-TrackerToken: $TRACKER_TOKEN"

# Download one format (eat is the full-fidelity round-trip CSV)
curl https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/export/eat \
  -H "X-TrackerToken: $TRACKER_TOKEN" -o project-export.csv

Id форматів обміну: eat, jira, pivotal, shortcut, trello, asana, gitlab, linear, plane, plane_json, а також формати документів pdf і docx. Кожне вкладення можна завантажити одним zip з GET /projects/{id}/export/attachments.

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

Усі помилки — це JSON, що містить щонайменше:

{
  "code": "invalid_transition",
  "error": "Cannot move story from `unstarted` to `accepted`"
}

Багато відповідей про помилку також містять об’єкт details — details.fields (масив імен полів, що порушують правило) при validation_failed та details.allowed (поряд із from/to) при 422 invalid_transition. Використовуйте їх. 429 rate_limited несе заголовок Retry-After у тому самому JSON-конверті.

Пагінація

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

Що далі

Специфікація API — кожна кінцева точка, кожен метод, кожна структура.
Інструкція з експлуатації → Агенти — з боку інтерфейсу: створення ключів агентів, найменування агентів, відкликання.
Вступ — концепції за API: історії, стани, ітерації, швидкість, агенти.