Specifikace API

Kompletní referenční přehled REST endpointů. Pro tutoriály a příklady viz Průvodce API.

Vše, co může member projektu dělat ve webovém rozhraní, je dostupné zde — SPA spotřebovává totéž API. Operace, které vyžadují roli manager, jsou označeny (manager); vše ostatní potřebuje pouze členství v projektu (nebo, pro čtení označená (viewer), jakoukoli úroveň přístupu). Tabulky níže uvádějí každou skupinu cest, kterou server připojuje; ty, které jsou shrnuty jediným řádkem, jsou úplně popsány v živém openapi.json.

Base

https://eastagiletracker.com/api/v1

https://api.eastagiletracker.com/api/v1 poskytuje identické API. Všechny požadavky a odpovědi jsou JSON, kromě několika endpointů pro nahrávání souborů, které přijímají multipart.

Dvě skupiny leží o úroveň výš, pod /api místo /api/v1: autentizační rozhraní (/api/auth/*) a veřejné formuláře (/api/contact, /api/feedback). Jejich varianty /api/v1/… vracejí 404.

Autentizace

Každý autentizovaný požadavek posílá přihlašovací údaj jedním z:

• X-TrackerToken: <key>
• Authorization: Bearer <key>

Uživatelské klíče začínají na ea_user_, agentské klíče na ea_agent_ a přístupové tokeny MCP na ea_mcp_. Viz Průvodce API → Tři druhy přihlašovacích údajů.

Neautentizované endpointy: /openapi.json, /docs, endpointy /api/auth/* a vyhledávání referenčních dat (/story_types, /story_states, /effort_scales, /priority_scales). /meta je autentizované — funguje jakýkoli platný klíč, ale není ohraničeno projektem (dosáhne na něj i agentský klíč vázaný na projekt).

Role

Čtyři úrovně ohraničují endpointy vázané na projekt:

Úroveň	Kdo projde	Typické operace
public viewer	kdokoli, u projektu s veřejnou viditelností	čtení nástěnky: stories, iterace, vyhledávání, aktivita stories a epiců (s redigovanými údaji o aktérovi)
viewer	viewer, member, manager	čtení (list/get stories, vyhledávání, metriky, seznam exportních formátů)
member	member, manager	všechny zápisy pracovních položek (stories, tasks, comments, …), proud událostí
manager	pouze manager	nastavení projektu, správa členství, agentské klíče, mazání, import, stahování exportů, zálohy, auditní log

Agenti mají stejné role jako členové — viewer, member nebo manager — omezené rolí člena, který klíč vystavil. Nečlen obdrží 404 unfound_resource (ne 403) na cestách soukromých projektů, takže ID projektů nejsou vyčíslitelná.

Sebepopisné endpointy

Metoda	Cesta	Popis
GET	/openapi.json	Živá specifikace OpenAPI 3 včetně těl požadavků. Neautentizované.
GET	/docs	Swagger UI. Neautentizované.
GET	/meta	Identita volajícího (auth.kind/key_id/agent_id/project_id) + graf přechodů typů story. Autentizované (jakýkoli platný klíč; není ohraničeno projektem). Volejte toto jako první.
GET	/api/health · /api/config	Stav živosti a veřejná konfigurace instalace (režim jedné organizace, zapnuté volitelné funkce, název instance). Neautentizované, mimo /v1.

Auth (/api/auth/*, mimo /v1)

Endpointy relací, neautentizované, pokud není uvedeno jinak. Používá je SPA; skripty obvykle místo nich používají API klíč.

Metoda	Cesta	Popis
POST	/auth/register	Registrovat nový účet — chráněno reCAPTCHA; účet pak projde SMS výzvou
POST	/auth/sms/challenge · /auth/sms/status · /auth/sms/bypass	Odeslat / zkontrolovat registrační SMS kód (bypass povoluje provozovatel)
GET	/auth/config	Které metody přihlášení instalace nabízí
POST	/auth/login	Přihlášení e-mailem + heslem; vrací JWT relace, nebo výzvu TOTP
POST	/auth/login/totp	Dokončit přihlášení kódem z autentizační aplikace nebo obnovovacím kódem
POST	/auth/passkey/login/start · /auth/passkey/login/finish	Přihlášení bez hesla přes WebAuthn
GET	/auth/oauth/github/start · /auth/oauth/github/callback · /auth/oauth/google/start · /auth/oauth/google/callback · POST /auth/oauth/exchange	Přihlášení přes OAuth s GitHubem nebo Googlem
POST	/auth/refresh · /auth/refresh/revoke	Rotovat obnovovací token / zrušit ho
POST	/auth/logout	Odhlásit se (zruší obnovovací token)
POST	/auth/forgot-password · /auth/reset-password	Požádat o e-mail pro obnovení hesla / použít token pro obnovení
POST	/auth/accept-invite/lookup · /auth/accept-invite	Přeložit token pozvánky → e-mail / přijmout pozvánku do projektu (po autentizaci)

Účet / identita

Tyto jednají na volajícím a potřebují pouze platný klíč (žádnou roli v projektu).

Metoda	Cesta	Popis
GET	/me	Profil aktuálního uživatele
PUT	/me	Aktualizovat profil
DELETE	/me	Smazat účet — odmítnuto, dokud jste jediným vlastníkem organizace nebo projektu s dalšími členy
GET	/me/deletion-impact	Co by smazání účtu odstranilo a co mu brání
PUT	/me/password	Změnit heslo
PUT	/me/settings	Aktualizovat nastavení (motiv, předvolby oznámení)
POST	/me/avatar	Nahrát avatar (multipart)
POST	/me/api-token/regenerate	Rotovat váš API token — zneplatní stávající relace/klíče
GET	/me/api_keys · POST /me/api_keys · DELETE /me/api_keys/{id}	Spravovat uživatelské (ea_user_) API klíče
GET	/me/totp · POST /me/totp/setup · /me/totp/verify · /me/totp/disable	Registrace dvoufázového ověření (TOTP); verify jednou vrátí obnovovací kódy
GET	/me/passkeys · POST /me/passkeys/register/start · /me/passkeys/register/finish · DELETE /me/passkeys/{credential_id}	Registrace a odebrání passkeys
GET	/me/oauth_grants · DELETE /me/oauth_grants/{grant_id}	Připojené aplikace — MCP klienti a OAuth aplikace, které jste autorizovali
GET	/me/activity	Vaše aktivita napříč všemi projekty
GET	/me/stories	Stories, které vlastníte, o které jste požádali nebo které sledujete, napříč všemi projekty, na které token dosáhne — role=owned|requested|following, state=, cursor= / limit= (max 200)
GET	/me/mentions · POST /me/mentions/{mention_id}/ack	Schránka @-zmínek (unacked=true pro filtrování) a jejich potvrzení — zahrnuto také ve feedu oznámení níže
GET	/me/data-export	GDPR sebeexport vašich dat
GET	/me/consent · POST /me/consent	Číst / zaznamenat souhlas ({ consent_type, granted })
GET	/legal/pending · POST /legal/accept	Čekající clickwrap dokumenty / zaznamenat přijetí
GET / PUT	/agent/me	Vlastní identita a profil agentského klíče, které agent může číst i upravovat (agentní protějšek /me)
POST	/api/contact · /api/feedback · /api/feedback/with-screenshot	Kontakt + zpětná vazba v aplikaci. Mimo /v1; limitováno podle IP

Referenční data (neautentizované)

Vyhledávání počátečních dat používaná při vytváření/odhadování stories. Stabilní ID.

Metoda	Cesta	Popis
GET	/story_types	feature, bug, chore, release (+ allow_points)
GET	/story_states	unstarted … accepted, rejected
GET	/effort_scales	dostupné odhadovací škály
GET	/effort_scales/{scale_id}/values	bodové hodnoty ve škále
GET	/priority_scales · /priority_scales/{scale_id}/values	škály priorit a jejich hodnoty (sem se překládá priority_id na story)

Organizace

Pouze hostovaná služba — instalace na vlastní infrastruktuře běží v režimu jedné organizace a tyto cesty nepřipojuje (kromě seznamu organizací). Role jsou role v organizaci: owner, admin, member.

Metoda	Cesta	Popis
GET / POST	/organizations	Vypsat vaše organizace / vytvořit novou
GET / PUT / DELETE	/organizations/{oid}	Číst, přejmenovat (název + slug; owner nebo admin), smazat
GET / POST	/organizations/{oid}/memberships · PUT / DELETE …/memberships/{member_id}	Členové a pozvánky; pozvánky nesou strop role (nikdy nad rolí volajícího; owner se nikdy nezve)
POST	/organizations/{oid}/memberships/bulk-role · …/memberships/bulk-remove	Změna role nebo odebrání až 200 členů najednou. Vše, nebo nic: dávka, která by odebrala posledního ownera nebo nechala projekt bez vlastníka, je odmítnuta celá; s reassign_confirmed se místo toho stanete vlastníkem těchto projektů
DELETE	/organizations/{oid}/invitations/{invitation_id}	Zrušit čekající pozvánku
POST	/organizations/{oid}/transfer-ownership	Předat roli owner jinému členovi
PUT	/organizations/{oid}/memberships/{member_id}/anonymization	Zamaskovat jméno / e-mail / avatar člena v celé organizaci
GET	/organization-invitations/{token} · POST …/{token}/accept	Přeložit / přijmout pozvánku do organizace zaslanou e-mailem
POST	/organizations/{oid}/export · GET / POST …/export/jobs · GET …/export/jobs/{job_id} · …/export/jobs/{job_id}/download	Export organizace pouze pro vlastníka: zip s SQL dumpem a všemi přílohami, spouštěný jako úloha

Projekty

Metoda	Cesta	Popis
GET	/projects	Vypsat vaše projekty (limit ≤ 200)
POST	/projects	Vytvořit projekt
GET	/projects/{id}	Získat detaily projektu (viewer)
PUT	/projects/{id}	Aktualizovat nastavení projektu (manager)
DELETE	/projects/{id}	Smazat projekt (manager)
POST	/projects/{id}/pin	Připnout / odepnout projekt ve vašem seznamu projektů
POST	/projects/{id}/transfer-organization	Přesunout projekt do jiné organizace (manager)
POST	/projects/{id}/slack/test	Odeslat testovací zprávu do feedu projektu ve Slacku (manager)
GET / POST	/projects/{id}/showcase_claim_eligibility · /projects/{id}/showcase_claim · /projects/{id}/showcase_seed	Veřejné ukázkové projekty: ověřit, zda si ho můžete převzít, převzít ho, naplnit ho
GET	/projects/{id}/audit-log	Čtení auditního logu — historie projektu plus aktivita per-story / per-epic přes surface=; přístup se liší podle surface, viz níže
GET	/projects/{id}/events	Kurzorem stránkovaný proud událostí (member) — viz Events

Query parametry auditního logu: event_type= (jeden typ nebo čárkami oddělený seznam), limit= (≤ 1000), before= (keyset kurzor, ISO-8601 created_at), surface= (project_history, story_activities, epic_activities), target_id= (id story/epicu — povinné, když surface=story_activities nebo epic_activities). Přístup: nefiltrovaný log a surface=project_history jsou (manager); story_activities / epic_activities může číst kterýkoli člen projektu a u veřejných projektů i anonymně s redigovanými osobními údaji aktéra.

Členové, agenti a agentské klíče

Metoda	Cesta	Popis
GET	/projects/{id}/memberships	Vypsat členy (viewer)
POST	/projects/{id}/memberships	Pozvat člena e-mailem (manager)
PUT	/projects/{id}/memberships/{mid}	Aktualizovat roli (manager)
DELETE	/projects/{id}/memberships/{mid}	Odebrat člena (manager)
GET	/projects/{id}/addable-members · POST /projects/{id}/members/add-existing	Členové organizace, kteří ještě nejsou v projektu / přidat jednoho bez e-mailové pozvánky (manager)
POST	/projects/{id}/members/join	Owner nebo admin organizace se připojí k projektu ve své organizaci jako manager, nebo se na managera povýší (akce Make me owner v seznamu projektů)
PUT	/projects/{id}/members/{mid}/anonymization	Zamaskovat jméno / e-mail / avatar člena v tomto projektu (manager)
GET / POST	/projects/{id}/agent_keys	Vypsat / vystavit agentské klíče — managers, nebo role, které připouští creator-roles policy projektu
DELETE	/projects/{id}/agent_keys/{kid}	Odvolat agentský klíč
GET	/projects/{id}/agent_keys/onboarding	Onboarding bundle: prompty a konfigurační soubory pro běžné agentní klienty
GET	/projects/{id}/agents · GET / PUT /projects/{id}/agents/{aid}	Agenti projektu a jejich profily (jméno, iniciály, popis, barva)
POST	/projects/{id}/agents/{aid}/rotate-key · /projects/{id}/agents/{aid}/avatar	Rotovat klíč agenta (identita a historie zůstávají) / nahrát jeho avatar

Stories

Všechny zápisy stories potřebují roli member.

Metoda	Cesta	Popis
GET	/projects/{id}/stories	Vypsat stories (stránkované, filtrovatelné) (viewer)
POST	/projects/{id}/stories	Vytvořit story
GET	/projects/{id}/stories/{sid}	Získat jednu story (viewer)
PUT	/projects/{id}/stories/{sid}	Aktualizovat story
DELETE	/projects/{id}/stories/{sid}	Smazat story
POST	/projects/{id}/stories/{sid}/transitions	Změnit stav s validací
POST	/projects/{id}/stories/{sid}/reject · /projects/{id}/stories/{sid}/restart	Odmítnout dodanou story / vrátit odmítnutou zpět do started (rejected je pro /transitions koncový stav)
POST	/projects/{id}/stories/{sid}/archive · /projects/{id}/stories/{sid}/unarchive	Archivovat / obnovit z archivu jednu story
POST	/projects/{id}/stories/bulk_transition	Přechod mnoha stories (1–100) najednou
POST	/projects/{id}/stories/bulk-archive · bulk-delete · bulk-duplicate · bulk-move	Archivovat, smazat, duplikovat nebo přesunout (na panel / pozici) mnoho stories
POST	/projects/{id}/stories/{sid}/duplicate	Duplikovat jednu story
GET / POST / DELETE	/projects/{id}/stories/{sid}/epics · …/epics/{eid}	Příslušnost story k epicům
GET	/short-links/{code} · /story-references	Přeložit krátký odkaz /s/<code> na jeho story / přeložit až 100 referencí na stories (#id, URL) na stories, které volající smí číst

Query parametry seznamu stories: archived= (exclude výchozí / include / only — třístavový filtr archivace; nahrazuje zastaralé include_archived=true, které je nyní aliasem archived=include), include_done=true (připustí stories z panelu Done zmrazené na minulých iteracích, standardně vyloučené). Stránkování (cursor= / limit= / offset=) a řídké sady polí (fields=) se řídí sekcemi Stránkování a Projekce polí.

Create (POST …/stories): { "name" (required), "story_type": "feature|bug|chore|release", "description"?, "estimate"?, "current_state"?, "icebox"?, "labels"? }. estimate je popisek hodnoty škály jako řetězec ("3", "13"); číslo v JSON se odmítne. labels přijímá ["auth"] nebo [{ "name": "auth" }]; neznámé štítky se vytvoří. Výchozí: story_type=feature, current_state=unstarted.

Update (PUT …/stories/{sid}): stejná pole, všechna volitelná, plus "position" (float), "force_state_change" (bool) a "expected_updated_at" (RFC 3339 — uložení popisu se odmítne s 409 stale_write, pokud se story od vašeho čtení změnila). Zápisy stories také respektují If-Match vůči ETag story; nesoulad vede na 412 precondition_failed.

Transition (POST …/transitions): { "to": "<state>" }. Pole je to. Vrací { story_id, state }. Nelegální tah → 422 invalid_transition s details: { from, to, allowed }.

Bulk transition (POST …/bulk_transition): { "story_ids": [int,…] (1–100), "to": "<state>" }. Každá story je posuzována nezávisle; vrací { results: [ { id, status: "ok" } | { id, status: "failed", error } ] }.

Pod-zdroje story

Všechny member. List/GET na většině je (viewer).

Metoda	Cesta	Tělo / poznámky
GET / POST	/projects/{id}/stories/{sid}/tasks · PUT/DELETE …/tasks/{tid}	{ description (or task_desc), complete?, task_order? }
GET / POST	/projects/{id}/stories/{sid}/comments · PUT/DELETE …/comments/{cid}	{ text (or comment_text) } nebo { comment_emoji }. GET přijímá fields= (povolený seznam: comment_id, story_comment_id, story_id, comment_text, comment_emoji, member, created) a navíc cursor= / limit= (≤ 200) / order=asc|desc
GET / POST	/projects/{id}/stories/{sid}/blockers · PUT/DELETE …/blockers/{bid}	{ blocker_desc, resolved? }
GET / POST	/projects/{id}/stories/{sid}/links · PUT/DELETE …/links/{lid}	{ url, link_type?, title? } — link_type ∈ relates_to, duplicates, blocks, is_blocked_by, pull_request, branch, other; GitHub URL s /pull/ a /tree/ dostanou typ automaticky
GET / POST	/projects/{id}/stories/{sid}/reviews · PUT/DELETE …/reviews/{rid}	Vytvoření: { reviewer_id? / reviewer_agent_id?, comment? } — vynechte obojí a přiřadíte sami sebe. Aktualizace: { status, comment? }
GET / POST	/projects/{id}/stories/{sid}/owners · DELETE …/owners/{mid} · DELETE …/owners/agents/{aid}	{ member_id? / agent_id? } — vynechte obojí pro přidání volajícího
GET / POST	/projects/{id}/stories/{sid}/followers · DELETE …/followers/{mid} · DELETE …/followers/agents/{aid}	{ member_id? / agent_id? }
GET / POST	/projects/{id}/stories/{sid}/labels · DELETE …/labels/{lid}	{ name }
GET / POST	/projects/{id}/stories/{sid}/attachments (+ /json) · DELETE …/attachments/{aid}	multipart upload — video ≤ 200 MB, PDF / Word / Excel ≤ 25 MB, obrázky / CSV / text ≤ 10 MB; list je (viewer)
GET / POST	/projects/{id}/stories/{sid}/link-attachments · DELETE …/link-attachments/{laid}	Odkazové přílohy — externí URL vedená vedle souborových příloh, nikoli jako odkaz na kód
GET	/attachments/{token} · /api/avatars/{token}	Čtení přílohy nebo avataru adresované tokenem — URL, které API vydává; X-TrackerToken není potřeba

Epiky

Stejný tvar jako stories, jen bez stavového automatu. member pro zápisy, (viewer) pro čtení.

Metoda	Cesta	Popis
GET / POST	/projects/{id}/epics · GET / PUT / DELETE …/epics/{eid}	Epiky nesou název, popis v Markdownu a podkladový štítek, který spojuje jejich stories
GET / POST / PUT / DELETE	…/epics/{eid}/comments · …/comments/{cid}	Komentáře k epicům
GET / POST / DELETE	…/epics/{eid}/owners · …/followers (+ varianty /agents/{aid})	Vlastníci a sledující, členové nebo agenti — vlastníci epicu se propisují do jeho stories
GET / POST / DELETE	…/epics/{eid}/attachments (+ /json) · …/link-attachments	Přílohy, stejné limity jako u stories
GET	/projects/{id}/analytics/epics · …/analytics/epics/{eid}	Postup po epicích: burnup, propustnost, stav, předpověď (viewer)

Štítky

member pro zápisy, (viewer) pro čtení.

Metoda	Cesta	Popis
GET / POST	/projects/{id}/labels	Vypsat / vytvořit štítek
PUT / DELETE	/projects/{id}/labels/{lid}	Aktualizovat / smazat štítek
POST	/projects/{id}/labels/{lid}/archive	Archivovat (měkce skrýt) štítek

Iterace

Čtení je otevřené pro jakoukoli roli v projektu a u veřejného projektu i anonymně.

Metoda	Cesta	Popis
GET	/projects/{id}/iterations	Vypsat iterace (≤ 500 na stránku; nese ETag a při zkrácení pokračovací hlavičky X-Tracker-Pagination-*)
GET	/projects/{id}/iterations/{itid}	Jedna iterace
GET	/projects/{id}/iterations/first-preview	Data, která by dostala první iterace, zobrazená v potvrzení při jejím založení
POST	/projects/{id}/iterations	Vytvořit manuální iteraci (member)
DELETE	/projects/{id}/iterations/{itid}	Smazat iteraci (manager)
PUT	/projects/{id}/iterations/{itid}/velocity	Přepsat rychlost jedné iterace bez změny strategie projektu (manager)
GET	/projects/{id}/iterations/{itid}/done-stories	Přijaté stories uzavřené iterace, stránkované

Vyhledávání, metriky, předvolby

Metoda	Cesta	Popis
GET	/projects/{id}/search?q=…	Výkonné vyhledávání — fulltext + kvalifikátory faset / datových rozsahů / osob (DSL ve stylu GitHubu); vrací { results, total, limit, offset }. query je alias pro q; limit= (výchozí 50, max 1000) / offset= stránkují; sort= řadí podle relevance (výchozí), created, created_asc, state nebo updated. (viewer) — viz Průvodce
GET	/projects/{id}/metrics/{velocity,burndown,story-types,contributors}	Řady pro stránku Metrics (viewer); metriky epiců jsou výše pod /analytics/epics
GET	/projects/{id}/backlog/grouping	Promítnuté skupiny iterací v Backlogu (viewer)
GET / PUT	/projects/{id}/preferences	Vaše předvolby nástěnky pro tento projekt — jakákoli role v projektu, pouze váš vlastní řádek

Events

Metoda	Cesta	Popis
GET	/projects/{id}/events	Kurzorem stránkovaný proud událostí (member) — viewers dostanou 403

Parametry dotazu: since=<event_id>, types=story.created,story.transitioned,comment.added,…, limit= (≤ 500), cursor=. Odpověď zahrnuje next_cursor. Předejte poslední event_id, které jste viděli, jako since, abyste pokračovali.

Oznámení

Sjednocený feed oznámení v aplikaci: plnohodnotné řádky oznámení (žádosti o review, aktivita na story, pozvánky, …) sloučené se schránkou @-zmínek do jednoho proudu, od nejnovějších. Id ve feedu nesou prefix zdroje (nt-… / sc-… / ec-…). Členské relace a klíče ea_user_* čtou své členské řádky; klíče ea_agent_* své agentní řádky.

Metoda	Cesta	Popis
GET	/me/notifications	Váš feed oznámení. Filtry: unread=true, since_id=, kind= (mentions / reviews / stories / invitations); stránkujte přes cursor= / limit=
GET	/me/notifications/unread-count	Souhrny nepřečtených — { unread_count, by_category: { mentions, reviews, stories, invitations } }
POST	/me/notifications/read-all	Označit vše jako přečtené; vrací čerstvé počty
POST	/me/notifications/{id}/ack	Označit jednu položku jako přečtenou (idempotentní)
POST	/me/notifications/{id}/accept	Přijmout pozvánku do projektu / organizace přímo z feedu (pouze členské tokeny)
POST	/me/notifications/{id}/decline	Odmítnout pozvánku do projektu / organizace (pouze členské tokeny)
GET	/me/notifications/resolve-invite?token=…	Převést e-mailový token pozvánky na id vašeho oznámení — { "id": "nt-…" } nebo { "id": null }
GET	/me/notifications/stream	Živý push — Server-Sent Events (text/event-stream); viz níže

Stream endpoint není JSON endpoint, a proto není v OpenAPI specifikaci: drží spojení otevřené a při každé nové události vyšle rámec bez payloadu ({"type":"notification","kind":…}), kterým klientovi říká, ať feed načte znovu. Spojení server ukončí po 45 minutách — znovu se připojte a autentizujte. Pouze členské relace a klíče ea_user_*; klíče ea_agent_* dostanou 403.

Import (manager)

Metoda	Cesta	Popis
POST	/projects/{id}/import	Souborové zdroje: source= ∈ pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json, eat. Multipart file=. Synchronní — odpoví počty výsledků.
POST	/projects/{id}/import/json	Tělo v JSON; source=github nepotřebuje soubor — owner, repo, volitelný token a opt-in přepínače include_pull_requests / include_milestones / include_releases / include_dependencies; souborové zdroje posílají file_base64. Asynchronní: vrací 202 { import_id, status }. Server načítá přes GraphQL API GitHubu, které odmítá anonymní volající, takže na GitHub vždy dorazí token — váš, nebo sdílený token instalace. Viz Průvodce.
GET	/projects/{id}/imports/{import_id}	Dotazování na úlohu: status prochází pending → fetching → writing → done | failed, během načítání s progress_current / progress_total a při done s počty výsledků

V jednom projektu běží vždy jen jeden import; druhý POST, zatímco jiný probíhá, skončí 409 import_already_running. dry_run: true (JSON tělo nebo dry_run=true multipart) zobrazí náhled libovolného zdroje: zpracuje, přeloží, odstraní duplicity, vrátí stejné počty { imported, skipped, errors, unmatched } a pak vše vrátí zpět — nic se nezapíše. Limity: 10 MiB tělo a 5 000 stories na import u souborových zdrojů (přes kterýkoli z nich → 400, nic se nezapíše). Zdroj GitHub limit nemá — zapisuje po dávkách místo jedné transakce. Opakovaný import je idempotentní podle source id — již naimportované řádky se přeskočí, nikoli duplikují.

Export

Metoda	Cesta	Popis
GET	/projects/{id}/export/formats	Registrované formáty: { id, name, content_type, drops, includes_archived }. Jakákoli role v projektu.
GET	/projects/{id}/export/{format}	Stáhnout jeden (manager). Výměnné: eat (plná věrnost), jira, pivotal, shortcut, trello, asana, gitlab, linear, plane, plane_json; dokumenty: pdf, docx.
GET	/projects/{id}/export/attachments	Každá příloha jako jeden procházecí zip (soubory si ponechávají původní názvy; manifest v JSON + CSV) (manager).

Exporty dokumentů (pdf, docx) berou další query parametry: page_size= (letter výchozí / a4 / legal / folio), from= / to= (meze okna stories — RFC 3339 nebo holé YYYY-MM-DD; story je v rozsahu, když do něj spadá její created nebo completed_at), include_icebox= / include_backlog= (obojí výchozí false, takže sdílitelný export ukazuje jen naplánovanou / rozpracovanou práci). Výměnné formáty CSV je ignorují.

Zálohy a obnovy (manager)

Metoda	Cesta	Popis
GET / POST	/projects/{id}/backups · GET …/backups/{snapshot_id} · …/backups/health	Vypsat snímky, pořídit snímek hned, přečíst jeden snímek a souhrn stavu uchovávání
GET / POST	/projects/{id}/restores · POST …/restores/partial · GET …/restores/{restore_id}	Obnovit celý snímek nebo vybrané tabulky z něj a dotazovat se na průběh obnovy

Požadavky POST spadají do citlivé úrovně limitů rychlosti (níže).

MCP a poskytovatel OAuth

East Agile Tracker je poskytovatel OAuth 2.1 pro MCP klienty. Klient ho objeví na /.well-known/oauth-authorization-server a /.well-known/oauth-protected-resource/mcp, pošle vás na /oauth/authorize (stránka souhlasu), vymění kód na /oauth/token a pak s výsledným tokenem ea_mcp_* komunikuje přes MCP na /mcp. Udělená oprávnění se vypisují a odvolávají na /me/oauth_grants. Endpointy poskytovatele mají vlastní úroveň limitů rychlosti.

WebSocket

wss://eastagiletracker.com/ws/control?token=<session JWT>

Pro interaktivní vzdálené ovládání rozhraní ({ "action": "get_state", "id": "req-1" }). Token je JWT relace prohlížeče — API klíč se odmítne s 401 ještě před upgradem spojení. Není to datový kanál — všechna čtení/zápisy jdou přes REST. Pouze jedna instance; nešíří se napříč replikami.

Idempotence

Zápisové endpointy (POST, PUT, DELETE) přijímají hlavičku Idempotency-Key. Stejný klíč + stejné tělo přehraje cachovanou odpověď (24hodinové okno); stejný klíč + jiné tělo vrátí 409 idempotency_conflict. Klíč je vázán na přihlašovací údaj, který ho odeslal. Neaplikuje se na GET/HEAD/OPTIONS, /openapi.json a /docs, /api/auth/* ani na multipart nahrávání na cestách /attachments. Odpovědi, které skončily dřív, než doménová logika odpověděla, se nikdy necachují — 401, 403, 404, 429 a každé 5xx — takže opakování po kterékoli z nich dosáhne na handler; 400, 409, 412 a 422 jsou odpovědí domény a přehrávají se stejně jako úspěch.

Stránkování

List endpointy přijímají cursor=<opaque> a limit=<n>. Když jsou nastaveny, odpověď je { "items": [...], "next_cursor": "<str|null>" }; předejte next_cursor zpět pro další stránku. 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ý seznam (bez cursor/limit), který musel svou odpověď zkrátit, to oznámí v hlavičkách — X-Tracker-Pagination-Truncated, X-Tracker-Pagination-Limit, X-Tracker-Pagination-Offset a X-Tracker-Pagination-Next-Offset; poslední z nich předejte zpět jako offset= pro další stránku. Hlavička s celkovým počtem neexistuje.

Projekce polí

List endpointy přijímají fields= (oddělené čárkami) pro vrácení pouze konkrétních polí. story_id je vždy zahrnuto; neznámý název pole vrátí 400 validation_failed s problematickými názvy v details.fields.

GET /projects/123/stories?fields=story_id,name,current_state,owners

Formát chyb

Každá JSON chyba má code a error; některé přidávají details:

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

Status	code	Kdy
400	invalid_parameter	špatný vstup; zpráva v error, žádné details (většina validace: prázdné/délka/null-byte/email)
400	validation_failed	strukturovaná chyba vstupu; details.fields je pole názvů problematických polí
401	unauthenticated	chybějící/neplatný token
403	unauthorized_operation	autentizovaný, ale nedostatečná role
404	unfound_resource	nenalezeno — vraceno také nečlenům
409	conflict	konflikt zdroje (např. duplikát)
409	idempotency_conflict	Idempotency-Key znovupoužitý s jiným tělem
409	stale_write · import_already_running	story se změnila od vašeho expected_updated_at · import už probíhá
412	precondition_failed	If-Match neodpovídá aktuálnímu ETag zdroje; details nese expected a current
413	request_too_large	tělo překračuje limit velikosti dané cesty
422	invalid_transition	nelegální přesun stavu; details nese { from, to, allowed }
429	rate_limited	příliš mnoho požadavků z této IP na cestě s limitem rychlosti; hlavička Retry-After
500	internal_error	chyba serveru — generická zpráva; bezpečné opakovat
503	not_configured	instalaci chybí integrace, kterou tato cesta potřebuje (SMS, objektové úložiště, …)

details.fields je JSON pole názvů polí (např. ["to"]), někdy s extra klíči jako max. Neexistuje mapa pole→zpráva.

{ "code": "validation_failed", "error": "unknown field(s): foo", "details": { "fields": ["foo"] } }

Limity rychlosti

Podle IP klienta, na několika málo cestách; autentizovaný provoz API jinde limitován není. Výchozí hodnoty (každá dvojice je trvalá rychlost a burst, laditelné provozovatelem):

• Auth — /api/auth/*: 0.5 req/s, burst 20.
• OAuth provider — /oauth/*: 1 req/s, burst 60.
• Public — /api/contact: 0.2 req/s, burst 10.
• Feedback — /api/feedback: tři vrstvené úrovně — jedno odeslání za 15 s, 10 za hodinu, 36 za den.
• Avatars — neautentizované přesměrování na avatar: 20 req/s, burst 200.
• Sensitive — požadavky POST pro zálohy a obnovy: ~0.002 req/s, burst 5.

Překročený limit vrátí 429 s hlavičkou Retry-After a standardní JSON obálkou chyby, code: "rate_limited".