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 owner, jsou označeny (owner); vše ostatní potřebuje pouze členství v projektu (nebo, pro čtení označená (viewer), jakoukoli úroveň přístupu).

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.

Autentizace

Každý autentizovaný požadavek posílá API klíč jedním z:

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

Uživatelské klíče začínají na ea_user_. Agentské klíče začínají na ea_agent_. Viz Průvodce API → Dva druhy klíčů.

Neautentizované endpointy: /openapi.json, /docs, endpointy /auth/* a vyhledávání referenčních dat (/story_types, /story_states, /effort_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

Tři úrovně ohraničují endpointy ohraničené projektem:

Úroveň	Kdo projde	Typické operace
viewer	viewer, member, owner	čtení (list/get stories, search, analytics)
member	member, owner	všechny zápisy pracovních položek (stories, tasks, comments, …)
owner	pouze owner	nastavení projektu, správa členství, agentské klíče, mazání, import, auditní log

Nečlen obdrží 404 unfound_resource (ne 403) na cestách projektu, takže ID projektů nejsou vyčíslitelná.

Sebepopisné endpointy

Metoda	Cesta	Popis
GET	/openapi.json	Živá specifikace OpenAPI 3. 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í.

Účet / identita

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

Metoda	Cesta	Popis
POST	/auth/register	Registrovat nový účet
POST	/auth/login	Přihlásit se, vrací token relace
POST	/auth/logout	Odhlásit se
POST	/auth/forgot-password	Požádat o e-mail pro reset hesla
POST	/auth/reset-password	Použít reset token k nastavení nového hesla
GET	/auth/verify-email	Ověřit e-mailovou adresu
POST	/auth/accept-invite/lookup	Přeložit pozvánkový token → e-mail (neautentizované)
POST	/auth/accept-invite	Přijmout pozvánku do projektu (po autentizaci)
GET	/me	Profil aktuálního uživatele
PUT	/me	Aktualizovat profil
DELETE	/me	Smazat účet
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/activity	Vaše aktivita napříč všemi projekty
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í
POST	/contact · POST /feedback · POST /feedback/with-screenshot	Kontakt + zpětná vazba v aplikaci

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

Projekty

Metoda	Cesta	Popis
GET	/projects	Vypsat vaše projekty
POST	/projects	Vytvořit projekt
GET	/projects/{id}	Získat detaily projektu (viewer)
PUT	/projects/{id}	Aktualizovat nastavení projektu (owner)
DELETE	/projects/{id}	Smazat projekt (owner)
GET	/projects/{id}/audit-log	Proud aktivity projektu (owner)
GET	/projects/{id}/events	Kurzorem stránkovaný proud událostí (viewer) — viz Events

Členové a agentské klíče

Metoda	Cesta	Popis
GET	/projects/{id}/memberships	Vypsat členy (viewer)
POST	/projects/{id}/memberships	Pozvat člena e-mailem (owner)
PUT	/projects/{id}/memberships/{mid}	Aktualizovat roli (owner)
DELETE	/projects/{id}/memberships/{mid}	Odebrat člena (owner)
GET / POST	/projects/{id}/agent_keys	Vypsat / vytvořit agentské klíče (owner)
DELETE	/projects/{id}/agent_keys/{kid}	Odvolat agentský klíč (owner)

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/bulk_transition	Přechod mnoha stories (1–100) najednou
POST	/projects/{id}/stories/bulk-delete	Smazat mnoho stories
POST	/projects/{id}/stories/bulk-duplicate	Duplikovat mnoho stories
POST	/projects/{id}/stories/{sid}/duplicate	Duplikovat jednu story

Create (POST …/stories): { "name" (required), "story_type": "feature|bug|chore|release", "description"?, "estimate"?, "current_state"?, "icebox"?, "labels"? }. 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) a "force_state_change" (bool).

Transition (POST …/transitions): { "to": "<state>", "reason"? }. 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>", "reason"? }. 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 / POST	/projects/{id}/stories/{sid}/blockers · PUT/DELETE …/blockers/{bid}	{ blocker_desc, resolved? }
GET / POST	/projects/{id}/stories/{sid}/links · DELETE …/links/{lid}	{ url, link_type?, title? }
GET / POST	/projects/{id}/stories/{sid}/reviews · PUT/DELETE …/reviews/{rid}	{ reviewer_id? / reviewer_agent_id?, 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 (≤ 2 GB každý); list je (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

Metoda	Cesta	Popis
GET	/projects/{id}/iterations	Vypsat iterace (member)
POST	/projects/{id}/iterations	Vytvořit manuální iteraci (owner)
DELETE	/projects/{id}/iterations/{itid}	Smazat iteraci (owner)

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

Metoda	Cesta	Popis
GET	/projects/{id}/search?query=…	Vyhledávání syntaxí filtrů (viewer) — viz Průvodce
GET	/projects/{id}/analytics/{overview,iteration,releases,activity,cycle-time,projections}	Analytika (viewer). Detailní rozbor iterace bere ?iteration_id=
GET	/projects/{id}/metrics/{velocity,burndown,story-types}	Metriky (viewer)
GET / PUT	/projects/{id}/preferences	Vaše předvolby tabule pro tento projekt (member)

Events

Metoda	Cesta	Popis
GET	/projects/{id}/events	Kurzorem stránkovaný proud událostí (viewer)

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

Import (owner)

Metoda	Cesta	Popis
POST	/projects/{id}/import (+ /json)	Multipart upload. source= ∈ pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json.

WebSocket

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

Pro interaktivní vzdálené ovládání rozhraní ({ "action": "get_state", "id": "req-1" }). 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. Neaplikuje se na cesty GET/HEAD/OPTIONS, /auth/* ani /attachments. Odpovědi 5xx se nikdy necachují — opakování dosáhne na handler.

Stránkování

List endpointy přijímají cursor=<opaque> a limit=<n≤200>. Když jsou nastaveny, odpověď je { "items": [...], "next_cursor": "<str|null>" }; předejte next_cursor zpět pro další stránku. Některé seznamy také vracejí hlavičku X-Tracker-Pagination-Total.

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
422	invalid_transition	nelegální přesun stavu; details nese { from, to, allowed }
500	internal_error	chyba serveru — generická zpráva; bezpečné opakovat

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

Per-klíč (per-IP pro neautentizované endpointy), GCRA token bucket:

• Auth — /auth/*: 0.5 req/s, burst 20.
• Public — /contact, /feedback: 0.2 req/s, burst 10.
• Sensitive — reset hesla: ~0.002 req/s, burst 5.

Překročený limit vrátí 429 Too Many Requests s hlavičkou Retry-After a tělem v prostém textu (ne JSON obálka chyby).