Průvodce API

API East Agile Tracker je navrženo pro agenty stejně jako pro lidi. Vše, co můžete dělat v rozhraní, můžete dělat přes API — a pár věcí, které rozhraní neukazuje, je tu taky.

Tento průvodce vás dostane od nuly ke „skriptování vašeho backlogu” za méně než deset minut. Pro úplný referenční přehled endpointů viz Specifikace API.

Dva druhy klíčů

Autentizujete se pomocí API klíče v hlavičce X-TrackerToken. Existují dva druhy:

• Uživatelské klíče (ea_user_…) — Jednají jako vy. Vytvořte je v Account Settings → API Keys. Použijte je pro osobní skripty, CLI nástroje, integrace.
• Agentské klíče (ea_agent_…) — Jednají jako pojmenovaný agent v jednom projektu. Vytvořte je jako vlastník projektu v Project Settings → Agents. Použijte je pro AI agenty — Claude Code, Codex, vlastní — kteří by se měli účastnit projektu jako pojmenovaní členové týmu.

Rozdíly:

	Uživatelský klíč	Agentský klíč
Rozsah	Všechny vaše projekty	Jeden konkrétní projekt
Identita v auditním logu	Vaše jméno	Název agenta
Role	Vaše role v každém projektu	Nastavena při vytvoření klíče (viewer nebo member)
Odvolání	Odvolejte klíč; přístup si udržíte přes jiné klíče/relace	Odvolejte klíč; agent okamžitě ztratí přístup
Nejlépe pro	Osobní automatizaci, skripty	AI agenty, kteří by měli být v historii rozlišitelní od vás

Authorization: Bearer … funguje také, pokud preferujete tento styl hlavičky.

Ahoj, API

Získejte své projekty:

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

Nebo pro agentský klíč vypište projekt, na který je ohraničen:

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

API je JSON, REST-ovité, verzované na /api/v1/. Stejné tvary pro lidi i agenty.

Vytvoření 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
  }'

Odpověď zahrnuje project_id a jakékoli výchozí hodnoty, které server aplikoval (odhadovací škála, done state atd.).

Vytvoření story

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

Posun story životním cyklem

Endpoint pro přechod validuje požadovaný přesun a při chybě vrací povolené další stavy:

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 je to (ne to_state). Pokud je přesun nelegální — řekněme jste se pokusili přeskočit z unstarted rovnou na accepted — odpovědí je 422 invalid_transition se strukturovanými detaily chyby:

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

To je jedna z drobností, které dělají API přátelské k agentům: agent může přečíst details.allowed a zvolit správný další tah bez vytahování z prózy.

Komentář ke story

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

Komentář je připsán tomu, kdo vlastní API klíč — pokud je to agentský klíč, autorem komentáře je agent.

Idempotentní zápisy

Každý zápisový endpoint přijímá hlavičku Idempotency-Key. Opakujte stejný klíč se stejným tělem, dostanete zpět stejnou odpověď. Opakujte stejný klíč s jiným tělem, dostanete 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 je kritické pro agenty v opakovacích smyčkách — spadnete uprostřed zápisu, opakujte se stejným klíčem, žádné duplicitní stories.

Hromadné přechody

Přesuňte mnoho stories najednou. Každá story je posuzována nezávisle; jeden nelegální tah neselže ostatní.

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

Sledování proudu událostí

Pro agenty, kteří chtějí reagovat na to, co dělají lidé, dotazujte se na endpoint events:

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"

Odpovědí je kurzorem stránkovaný proud událostí s aktérem, zdrojem a změnou. Každá událost má ID; předejte poslední ID, které jste viděli, jako since, abyste pokračovali tam, kde jste skončili. Žádné webhooky, žádné scrapování, žádné zmeškané události.

Vyhledávání se syntaxí filtrů

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

Dostupné filtry:

Filtr	Příklad	Popis
type:	type:feature	Filtrovat podle typu story
state:	state:started	Filtrovat podle stavu
label:	label:"my label"	Filtrovat podle štítku
owner:	owner:claire	Filtrovat podle vlastníka
requester:	requester:tomas	Filtrovat podle zadavatele
has:	has:blocker	Stories s blokátory
is:	is:unestimated	Neodhadnuté features

Volný text odpovídá názvu a popisu. Filtry kombinujte oddělením mezerou — jsou spojeny pomocí AND.

Objevování API

Živá specifikace OpenAPI 3 je na:

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

Swagger UI je na:

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

/openapi.json a /docs jsou neautentizované — agent může přečíst kontrakt dříve, než má klíč. Jakmile drží klíč, /api/v1/meta (které vyžaduje platný klíč) vrací jeho identitu a graf přechodů pro každý typ story; vyhledávání referenčních dat (/story_types, /story_states, /effort_scales) jsou také neautentizovaná. Dohromady umožňují agentům odpovědět na otázku „co tady můžu dělat?” bez metody pokusu a omylu s chybami 403.

Poznámka: poskytovaný openapi.json vypisuje cesty, ale aktuálně dodává prázdná těla požadavků — pro zápisy použijte tvary polí v Specifikaci.

WebSocket control

Pro interaktivní automatizaci — řízení přihlášené relace prohlížeče ze skriptu, nebo vzdálené ovládání rozhraní pro tutoriály — existuje WebSocket kanál:

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

Většina uživatelů to nikdy nepotřebuje; je to tu pro případy, kdy REST nestačí.

Import z jiného trackeru

Pokud skriptujete hromadnou migraci:

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"

Podporované zdroje: pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json.

Formát chyb

Všechny chyby jsou JSON s minimálně:

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

Mnoho chybových odpovědí také zahrnuje objekt details — details.fields (pole názvů problematických polí) u validation_failed, a details.allowed (vedle from/to) u 422 invalid_transition. Použijte je.

Stránkování

List endpointy přijímají limit a cursor. Kurzor je neprůhledný; předejte next_cursor z předchozí odpovědi. Hlavičky odpovědi také zahrnují X-Tracker-Pagination-Total pro celkové počty tam, kde je výpočet levný.

Co dál

• Specifikace API — Každý endpoint, každé sloveso, každý tvar.
• Provozní pokyny → Agenti — Strana rozhraní: vytváření agentských klíčů, pojmenovávání agentů, odvolávání.
• Úvod — Koncepty za API: stories, stavy, iterace, rychlost, agenti.