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.

Tři druhy přihlašovacích údajů

Autentizujete se klíčem v hlavičce X-TrackerToken. Existují dva druhy klíčů, které si vystavíte sami, a třetí, který za vás získá MCP klient:

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 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.
MCP tokeny (ea_mcp_…) — Přístupové tokeny OAuth 2.1 vydané MCP klientovi (Claude, IDE) poté, co ho schválíte na stránce souhlasu. Jednají jako vy a můžete je odvolat v Account Settings → Connected apps.

Jednorázový dialog po vytvoření osobního klíče API v Nastavení účtu, klíč je na tomto snímku zakrytý

Formulář pro vytvoření klíče na kartě Agent se jménem a vybranou rolí member, pod pokyny k nastavení

Rozdíly mezi dvěma druhy, které vystavujete sami:

	Uživatelský klíč	Agentský klíč
Rozsah	Všechny vaše projekty	Jeden konkrétní projekt
Identita v auditním logu	Vaše jméno	Jméno agenta
Role	Vaše role v každém projektu	Nastavena při vytvoření klíče (viewer, member nebo manager — nikdy nad vlastní rolí člena, který klíč vystavil)
Odvolání	Odvolejte klíč; přístup si udržíte přes jiné klíče/relace	Odvolejte nebo rotujte 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"]
  }'

estimate je popisek hodnoty škály jako řetězec — "3", nebo "13" na škále Fibonacci — protože musí odpovídat bodu na škále projektu. Číslo v JSON se odmítne.

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.

rejected je pro endpoint přechodů koncový stav. Chcete-li odmítnutou story vrátit do práce, použijte POST …/stories/{sid}/restart; POST …/stories/{sid}/reject je slovesná podoba odmítnutí dodané story.

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 neshodí 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.added" \
  -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. Proud vyžaduje roli member — viewer dostane 403.

Vyhledávání

GET /projects/{id}/search?q=<query> spouští výkonné fulltextové + strukturované vyhledávání ve stories projektu. Jazyk dotazů je inspirován kvalifikátory vyhledávání issues na GitHubu — syntaxe, kterou vy (nebo AI agent) už znáte z GitHubu, se tak z velké části přenáší.

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'

Odpovědí je JSON obálka se stories seřazenými podle relevance:

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

total je celkový počet shod, ne velikost stránky. Stránkujte pomocí limit (výchozí 50, max 1000) a offset; řaďte pomocí sort=relevance (výchozí), created, created_asc, updated nebo state.

Gramatika

Volný text odpovídá názvu, referenci a popisu story (fulltextově, se stemmingem a řazením podle relevance). Přesnou frázi uzavřete do "uvozovek".
Kvalifikátory mají tvar field:value. Alternativy oddělte čárkou (OR v rámci jednoho pole): type:bug,chore. Kvalifikátory oddělte mezerou (AND mezi nimi).
Negujte jakýkoli výraz nebo kvalifikátor úvodním -: -label:wontfix.
Rozsahy pro data a body: včetně mezí a..b, nebo otevřené >x / <x.

Kvalifikátory

Kvalifikátor	Příklad	Shoduje se s
`type:`	`type:bug,chore`	typ(y) story
`state:`	`state:started,finished`	stav(y) workflow
`label:`	`label:"my label"`	štítkem
`epic:`	`epic:"Checkout"`	stories v epicu
`priority:`	`priority:p1`	prioritou
`points:`	`points:3` · `points:1..5` · `points:>3`	hodnotou nebo rozsahem odhadu
`iteration:`	`iteration:42`	id iterace
`created:` `updated:` `started:` `completed:` `release:`	`created:2026-05-01..2026-06-01` · `updated:>2026-06-01`	datem nebo rozsahem (s přesností na den); `release:` je datum vydání story
`owner:` `requester:` `follower:` `reviewer:` `commenter:` `mention:`	`owner:claire` · `owner:@me`	osobou podle jména nebo e-mailu — členové i agenti, včetně `mention:`; `@me` jste vy
`has:blocker`	`has:blocker`	má otevřený blokátor
`is:`	`is:unestimated` · `is:icebox` · `is:backlog` · `is:blocked`	příznakem

mywork: je alias pro owner: — mywork:me je owner:@me. Starší kvalifikátor scheduled: je vyřazen a tiše ignorován; použijte release:.

Čárkové OR (type:bug,chore) platí pro fasetové kvalifikátory; kvalifikátory osob (owner: requester: follower: reviewer: commenter: mention:) přijímají jedinou hodnotu.

Příklady

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

Stejný řetězec dotazu pohání vyhledávací pole na nástěnce (které otevírá živý sloupec výsledků) i toto API — jedna gramatika pro lidi i agenty. Vyhledávání v obsahu komentářů, úkolů a blokátorů je v plánu; dnes volný text pokrývá vlastní název, referenci a popis story.

Objevování API

Živá specifikace OpenAPI 3 je na:

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

Swagger UI je na:

https://api.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, /priority_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.

Poskytovaný openapi.json nese schémata těl požadavků pro zápisové endpointy, včetně maxLength každého pole, takže klient může validovat ještě před odesláním. Specifikace shrnuje tytéž tvary.

Ovládání přes WebSocket

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=SESSION_JWT')
ws.send(JSON.stringify({ action: 'get_state', id: 'req-1' }))

token je JWT relace prohlížeče, ne API klíč — klíč ea_user_* nebo ea_agent_* se odmítne ještě před upgradem spojení. 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é souborové zdroje: pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json, eat (vlastní export East Agile Tracker — formát pro obousměrný přenos). Multipart endpoint běží synchronně a odpoví počty výsledků.

GitHub importuje z API místo ze souboru, přes JSON endpoint — žádný file, jen souřadnice repozitáře:

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 endpoint je asynchronní: odpoví 202 s { "import_id", "status" } a vy se dotazujete na GET /projects/{id}/imports/{import_id}, dokud úloha nedosáhne stavu done nebo failed. V jednom projektu běží vždy jen jeden import — druhé volání, zatímco jiný probíhá, skončí 409 import_already_running. Celá smyčka včetně polí s průběhem úlohy je popsána v Naplnění projektu z GitHub repozitáře.

Token token je v požadavku volitelný, ale samotné načítání se vždy autentizuje — běží přes GraphQL API GitHubu, které nemá anonymní úroveň. Vynechte token a server dosadí svůj platformový token: pouze veřejné repozitáře, sdílený všemi volajícími a odmítnutý s import_github_shared_quota_low, jakmile jeho rozpočet GraphQL klesne pod 500 bodů. Soukromý repozitář nebo instalace, která žádný platformový token nenastavila (import_github_no_token), vyžaduje ten váš. Ať běží kterýkoli token, používá se pouze pro upstream volání GitHubu a nikdy se neukládá ani nevrací zpět. Úplné podrobnosti včetně nepřihlášeného REST stropu 60 požadavků GitHubu najdete v Naplnění projektu z GitHub repozitáře.

Náhled dry-run. Přidejte "dry_run": true (JSON) nebo -F "dry_run=true" (multipart) k libovolnému zdroji. Import zpracuje, přeloží a odstraní duplicity přesně jako skutečné spuštění, vrátí stejné počty výsledků (imported, skipped, errors, unmatched) a pak vše vrátí zpět — nic se nezapíše. U JSON endpointu počty dorazí na dotazované úloze, ať jde o dry run, nebo ne.

Limity. Tělo nahrávání je omezeno na 10 MiB a jediný import na 5 000 stories; překročení kteréhokoli z nich je 400 bez zápisu. Opakovaný import souboru je bezpečný — řádky již naimportované (spárované podle source id) se přeskočí, nikoli duplikují.

Export projektu

Formáty může vypsat jakákoli role v projektu; stažení jednoho z nich je vyhrazeno vlastníkovi:

# 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 výměnných formátů: eat, jira, pivotal, shortcut, trello, asana, gitlab, linear, plane, plane_json, plus dokumentové formáty pdf a docx. Každou přílohu lze stáhnout jako jeden zip z GET /projects/{id}/export/attachments.

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. 429 rate_limited nese hlavičku Retry-After ve stejné JSON obálce.

Stránkování

List endpointy přijímají limit a cursor. Kurzor je neprůhledný; předejte next_cursor z předchozí odpovědi. Strop limit se liší podle endpointu — 200 u stories, komentářů a projektů, 500 u událostí, 1000 u vyhledávání a auditního logu. Prostý (nekurzorový) seznam, který musel svou odpověď zkrátit, to oznámí v hlavičkách: X-Tracker-Pagination-Truncated, -Limit, -Offset a -Next-Offset, kterou předáte zpět jako offset= pro další stránku. Hlavička s celkovým počtem neexistuje.

Co dál

Specifikace API — Každý endpoint, každé sloveso, každý tvar.
Návod k použití → Agenti — Strana rozhraní: vystavování agentských klíčů, pojmenovávání agentů, odvolávání.
Úvod — Koncepty za API: stories, stavy, iterace, rychlost, agenti.