Przewodnik po API

API East Agile Tracker jest zaprojektowane dla agentów w równym stopniu co dla ludzi. Wszystko, co możesz zrobić w interfejsie, możesz zrobić przez API — a kilka rzeczy, których interfejs nie udostępnia, też tu jest.

Ten przewodnik przeprowadza Cię od zera do „skryptowania backlogu” w mniej niż dziesięć minut. Pełną referencję endpointów znajdziesz w Specyfikacji API.

Dwa rodzaje kluczy

Uwierzytelniasz się za pomocą klucza API w nagłówku X-TrackerToken. Są dwa rodzaje:

• Klucze użytkownika (ea_user_…) — Działają jako Ty. Twórz je w Account Settings → API Keys. Używaj ich do osobistych skryptów, narzędzi CLI, integracji.
• Klucze agentów (ea_agent_…) — Działają jako nazwany agent w jednym projekcie. Twórz je jako właściciel projektu w Project Settings → Agents. Używaj ich dla agentów AI — Claude Code, Codex, własnych — którzy powinni uczestniczyć w projekcie jako wymienieni z imienia członkowie zespołu.

Różnice:

	Klucz użytkownika	Klucz agenta
Zasięg	Wszystkie Twoje projekty	Jeden konkretny projekt
Tożsamość w dzienniku audytu	Twoje imię	Imię agenta
Rola	Twoja rola w każdym projekcie	Ustawiana przy tworzeniu klucza (viewer lub member)
Odbieranie	Odbierz klucz; zachowujesz dostęp przez inne klucze/sesje	Odbierz klucz; agent natychmiast traci dostęp
Najlepszy do	Osobistej automatyzacji, skryptów	Agentów AI, którzy powinni być odróżnialni od Ciebie w historii

Authorization: Bearer … również działa, jeśli wolisz ten styl nagłówka.

Witaj, API

Pobierz swoje projekty:

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

Albo, dla klucza agenta, wylistuj projekt, do którego jest przypisany:

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

API jest w JSON, w stylu REST, wersjonowane pod /api/v1/. Te same kształty dla ludzi i agentów.

Tworzenie projektu

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
  }'

Odpowiedź zawiera project_id oraz wszelkie wartości domyślne zastosowane przez serwer (skala estymacji, stan ukończenia itd.).

Tworzenie historii

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"]
  }'

Przesuwanie historii przez cykl życia

Endpoint przejścia waliduje żądany ruch i zwraca dozwolone następne stany w przypadku błędu:

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" }'

Pole to to (a nie to_state). Jeśli ruch jest niedozwolony — powiedzmy, że spróbowałeś przeskoczyć z unstarted prosto do accepted — odpowiedzią jest 422 invalid_transition ze strukturyzowanymi szczegółami błędu:

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

To jedna z drobnych rzeczy, które czynią API przyjaznym dla agentów: agent może odczytać details.allowed i wybrać właściwy następny ruch bez zeskrobywania prozy.

Komentowanie historii

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." }'

Komentarz jest przypisywany temu, kto jest właścicielem klucza API — jeśli to klucz agenta, autorem komentarza jest agent.

Idempotentne zapisy

Każdy endpoint zapisu akceptuje nagłówek Idempotency-Key. Ponów ten sam klucz z tym samym ciałem, a otrzymasz tę samą odpowiedź. Ponów ten sam klucz z innym ciałem, a otrzymasz 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" }'

To krytyczne dla agentów w pętlach ponawiania — awaria w połowie zapisu, ponowienie z tym samym kluczem, brak zduplikowanych historii.

Przejścia zbiorcze

Przesuwaj wiele historii naraz. Każda historia jest oceniana niezależnie; jeden niedozwolony ruch nie powoduje porażki pozostałych.

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"
  }'

Śledzenie strumienia zdarzeń

Dla agentów, którzy chcą reagować na to, co robią ludzie, odpytuj endpoint zdarzeń:

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"

Odpowiedzią jest strumień zdarzeń stronicowany kursorem, z wykonawcą, zasobem i zmianą. Każde zdarzenie ma identyfikator; przekaż ostatni widziany identyfikator jako since, aby wznowić tam, gdzie skończyłeś. Bez webhooków, bez zeskrobywania, bez pominiętych zdarzeń.

Wyszukiwanie składnią filtrów

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

Dostępne filtry:

Filtr	Przykład	Opis
type:	type:feature	Filtruj według typu historii
state:	state:started	Filtruj według stanu
label:	label:"my label"	Filtruj według etykiety
owner:	owner:claire	Filtruj według właściciela
requester:	requester:tomas	Filtruj według zgłaszającego
has:	has:blocker	Historie z blokerami
is:	is:unestimated	Nieestymowane features

Tekst swobodny dopasowuje tytuł i opis. Łącz filtry, oddzielając je spacją — są łączone operatorem AND.

Odkrywanie API

Żywa specyfikacja OpenAPI 3 znajduje się pod:

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

Swagger UI znajduje się pod:

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

/openapi.json i /docs są nieuwierzytelnione — agent może odczytać kontrakt, zanim będzie miał klucz. Gdy już ma klucz, /api/v1/meta (które wymaga prawidłowego klucza) zwraca jego tożsamość oraz graf przejść per typ historii; lookupy danych referencyjnych (/story_types, /story_states, /effort_scales) są również nieuwierzytelnione. Razem pozwalają agentom odpowiedzieć na pytanie „co mogę tu zrobić?” bez błędów 403 metodą prób i błędów.

Uwaga: serwowany openapi.json wymienia ścieżki, ale obecnie dostarcza puste ciała żądań — użyj kształtów pól ze Specyfikacji dla zapisów.

Sterowanie przez WebSocket

Do interaktywnej automatyzacji — sterowania zalogowaną sesją przeglądarki ze skryptu lub zdalnego sterowania interfejsem na potrzeby samouczków — istnieje kanał WebSocket:

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

Większość użytkowników nigdy tego nie potrzebuje; jest tu dla przypadków, w których REST nie wystarcza.

Import z innego trackera

Jeśli skryptujesz masową migrację:

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"

Obsługiwane źródła: pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json.

Format błędów

Wszystkie błędy są w JSON, z co najmniej:

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

Wiele odpowiedzi błędów zawiera również obiekt details — details.fields (tablica nazw wadliwych pól) przy validation_failed oraz details.allowed (obok from/to) przy 422 invalid_transition. Korzystaj z nich.

Stronicowanie

Endpointy listujące akceptują limit i cursor. Kursor jest nieprzezroczysty; przekaż next_cursor z poprzedniej odpowiedzi. Nagłówki odpowiedzi zawierają również X-Tracker-Pagination-Total dla łącznych liczników, gdy ich obliczenie jest tanie.

Co dalej

• Specyfikacja API — Każdy endpoint, każda metoda, każdy kształt.
• Instrukcja obsługi → Agenci — Strona interfejsu: wybijanie kluczy agentów, nazywanie agentów, odbieranie dostępu.
• Wprowadzenie — Pojęcia stojące za API: historie, stany, iteracje, prędkość, agenci.