Руководство по API

API East Agile Tracker спроектирован для агентов в той же мере, что и для людей. Всё, что вы можете делать в интерфейсе, вы можете делать через API — и несколько вещей, которые интерфейс не предоставляет, тоже здесь есть.

Это руководство проведёт вас от нуля до «скриптинга своего бэклога» менее чем за десять минут. Полный справочник по эндпоинтам см. в Спецификации API.

Два вида ключей

Вы аутентифицируетесь с помощью API-ключа в заголовке X-TrackerToken. Есть два вида:

• Пользовательские ключи (ea_user_…) — Действуют от вашего имени. Создавайте их в Account Settings → API Keys. Используйте их для персональных скриптов, CLI-инструментов, интеграций.
• Ключи агента (ea_agent_…) — Действуют как именованный агент в одном проекте. Создавайте их как владелец проекта в Project Settings → Agents. Используйте их для ИИ-агентов — Claude Code, Codex, своих собственных — которые должны участвовать в проекте как именованные члены команды.

Различия:

	Пользовательский ключ	Ключ агента
Область	Все ваши проекты	Один конкретный проект
Идентичность в журнале аудита	Ваше имя	Имя агента
Роль	Ваша роль в каждом проекте	Задаётся при создании ключа (viewer или member)
Отзыв	Отзовите ключ; вы сохраняете доступ через другие ключи/сессии	Отзовите ключ; агент теряет доступ немедленно
Лучше всего для	Персональной автоматизации, скриптов	ИИ-агентов, которые должны отличаться от вас в истории

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	Неоценённые фичи

Свободный текст совпадает с заголовком и описанием. Комбинируйте фильтры, разделяя их пробелами — они объединяются по И.

Изучение 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: истории, состояния, итерации, velocity, агенты.