Посібник з API

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

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

Два види ключів

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

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

Відмінності:

	Користувацький ключ	Ключ агента
Область дії	Усі ваші проєкти	Один конкретний проєкт
Ідентичність у журналі аудиту	Ваше ім’я	Ім’я агента
Роль	Ваша роль у кожному проєкті	Задається при створенні ключа (viewer або member)
Відкликання	Відкличте ключ; ви зберігаєте доступ через інші ключі/сесії	Відкличте ключ; агент негайно втрачає доступ
Найкраще для	Особиста автоматизація, скрипти	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"]
  }'

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

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

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 і обрати правильний наступний рух без вишкрібання прози.

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

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.created" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

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

Пошук із синтаксисом фільтрів

curl "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/search?query=type:feature%20state:started%20label:mvp" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

Доступні фільтри:

Фільтр	Приклад	Опис
`type:`	`type:feature`	Фільтр за типом історії
`state:`	`state:started`	Фільтр за станом
`label:`	`label:"my label"`	Фільтр за міткою
`owner:`	`owner:claire`	Фільтр за власником
`requester:`	`requester:tomas`	Фільтр за замовником
`has:`	`has:blocker`	Історії з блокерами
`is:`	`is:unestimated`	Неоцінені функції

Вільний текст збігається із заголовком та описом. Комбінуйте фільтри, розділяючи їх пробілом — вони об’єднуються через AND.

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

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

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

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

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

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

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

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

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

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

Більшості користувачів це ніколи не знадобиться; воно існує для випадків, коли 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.

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

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

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

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

Пагінація

Кінцеві точки списків приймають limit та cursor. Курсор непрозорий; передайте next_cursor із попередньої відповіді. Заголовки відповіді також містять X-Tracker-Pagination-Total для загальної кількості там, де її дешево обчислити.

Що далі

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