Specyfikacja API

Kompletna referencja endpointów REST. Samouczki i przykłady znajdziesz w Przewodniku po API.

Wszystko, co member projektu może zrobić w interfejsie webowym, jest dostępne tutaj — SPA korzysta z tego samego API. Operacje wymagające roli manager są oznaczone (manager); wszystko inne wymaga jedynie członkostwa w projekcie (lub, dla odczytów oznaczonych (viewer), dowolnego poziomu dostępu). Poniższe tabele wymieniają każdą grupę tras montowaną przez serwer; te streszczone w jednym wierszu są w pełni opisane w żywym openapi.json.

Baza

https://eastagiletracker.com/api/v1

https://api.eastagiletracker.com/api/v1 serwuje identyczne API. Wszystkie żądania i odpowiedzi są w JSON, z wyjątkiem kilku endpointów przesyłania plików, które akceptują multipart.

Dwie grupy znajdują się poziom wyżej, pod /api zamiast /api/v1: powierzchnia uwierzytelniania (/api/auth/*) oraz formularze publiczne (/api/contact, /api/feedback). Ich warianty /api/v1/… zwracają 404.

Uwierzytelnianie

Każde uwierzytelnione żądanie wysyła poświadczenie za pomocą jednego z:

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

Klucze użytkownika zaczynają się od ea_user_, klucze agentów od ea_agent_, a tokeny dostępu MCP od ea_mcp_. Zobacz Przewodnik po API → Trzy rodzaje poświadczeń.

Endpointy nieuwierzytelnione: /openapi.json, /docs, endpointy /api/auth/* oraz lookupy danych referencyjnych (/story_types, /story_states, /effort_scales, /priority_scales). /meta jest uwierzytelnione — działa każdy prawidłowy klucz, ale nie jest przypisane do projektu (klucz agenta związany z projektem również do niego dociera).

Role

Cztery poziomy bramkują endpointy o zasięgu projektu:

Poziom	Kto przechodzi	Typowe operacje
public viewer	każdy, w projekcie o widoczności publicznej	odczyty tablicy: historie, iteracje, wyszukiwanie, aktywność historii i epików (z utajnionymi danymi wykonawcy)
viewer	viewer, member, manager	odczyty (listowanie/pobieranie historii, wyszukiwanie, metryki, lista formatów eksportu)
member	member, manager	wszystkie zapisy elementów pracy (historie, zadania, komentarze, …), strumień zdarzeń
manager	tylko manager	ustawienia projektu, zarządzanie członkostwem, klucze agentów, usuwanie, import, pobieranie eksportów, kopie zapasowe, dziennik audytu

Agenci mają te same role co członkowie — viewer, member lub manager — ograniczone rolą członka, który wybił klucz. Osoba niebędąca członkiem otrzymuje 404 unfound_resource (a nie 403) na ścieżkach prywatnych projektów, więc identyfikatory projektów nie są wyliczalne.

Endpointy samoopisujące

Metoda	Ścieżka	Opis
GET	/openapi.json	Żywa specyfikacja OpenAPI 3, łącznie z ciałami żądań. Nieuwierzytelniona.
GET	/docs	Swagger UI. Nieuwierzytelniona.
GET	/meta	Tożsamość wywołującego (auth.kind/key_id/agent_id/project_id) + graf przejść per typ historii. Uwierzytelnione (dowolny prawidłowy klucz; nieprzypisane do projektu). Wywołaj to jako pierwsze.
GET	/api/health · /api/config	Stan działania oraz publiczna konfiguracja wdrożenia (tryb jednej organizacji, włączone funkcje opcjonalne, nazwa instancji). Nieuwierzytelnione, poza /v1.

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

Endpointy sesji, nieuwierzytelnione, o ile nie zaznaczono inaczej. Korzysta z nich SPA; skrypty zwykle używają zamiast tego klucza API.

Metoda	Ścieżka	Opis
POST	/auth/register	Zarejestruj nowe konto — chronione przez reCAPTCHA; konto przechodzi następnie wyzwanie SMS
POST	/auth/sms/challenge · /auth/sms/status · /auth/sms/bypass	Wyślij / sprawdź kod SMS przy rejestracji (bypass kontroluje operator)
GET	/auth/config	Jakie metody logowania oferuje wdrożenie
POST	/auth/login	Zaloguj się e-mailem + hasłem; zwraca JWT sesji albo wyzwanie TOTP
POST	/auth/login/totp	Dokończ logowanie kodem z aplikacji uwierzytelniającej lub kodem odzyskiwania
POST	/auth/passkey/login/start · /auth/passkey/login/finish	Logowanie WebAuthn bez hasła
GET	/auth/oauth/github/start · /auth/oauth/github/callback · /auth/oauth/google/start · /auth/oauth/google/callback · POST /auth/oauth/exchange	Logowanie OAuth przez GitHub lub Google
POST	/auth/refresh · /auth/refresh/revoke	Zrotuj token odświeżający / unieważnij go
POST	/auth/logout	Wyloguj się (unieważnia token odświeżający)
POST	/auth/forgot-password · /auth/reset-password	Poproś o e-mail resetujący / użyj tokenu resetującego
POST	/auth/accept-invite/lookup · /auth/accept-invite	Rozwiąż token zaproszenia → e-mail / zaakceptuj zaproszenie do projektu (po uwierzytelnieniu)

Konto / tożsamość

Te operują na wywołującym i wymagają jedynie prawidłowego klucza (bez roli projektowej).

Metoda	Ścieżka	Opis
GET	/me	Profil bieżącego użytkownika
PUT	/me	Zaktualizuj profil
DELETE	/me	Usuń konto — odrzucane, dopóki jesteś jedynym właścicielem organizacji lub projektu z innymi członkami
GET	/me/deletion-impact	Co usunięcie konta by usunęło i co je blokuje
PUT	/me/password	Zmień hasło
PUT	/me/settings	Zaktualizuj ustawienia (motyw, preferencje powiadomień)
POST	/me/avatar	Prześlij awatar (multipart)
POST	/me/api-token/regenerate	Zrotuj swój token API — unieważnia istniejące sesje/klucze
GET	/me/api_keys · POST /me/api_keys · DELETE /me/api_keys/{id}	Zarządzaj kluczami API użytkownika (ea_user_)
GET	/me/totp · POST /me/totp/setup · /me/totp/verify · /me/totp/disable	Konfiguracja uwierzytelniania dwuskładnikowego (TOTP); verify zwraca kody odzyskiwania jednorazowo
GET	/me/passkeys · POST /me/passkeys/register/start · /me/passkeys/register/finish · DELETE /me/passkeys/{credential_id}	Rejestracja i usuwanie passkeyów
GET	/me/oauth_grants · DELETE /me/oauth_grants/{grant_id}	Połączone aplikacje — klienci MCP i aplikacje OAuth, które autoryzowałeś
GET	/me/activity	Twoja aktywność we wszystkich projektach
GET	/me/stories	Historie, których jesteś właścicielem, zgłaszającym lub obserwującym, we wszystkich projektach dostępnych dla tokenu — role=owned|requested|following, state=, cursor= / limit= (maks. 200)
GET	/me/mentions · POST /me/mentions/{mention_id}/ack	Skrzynka @-wzmianek (unacked=true, aby filtrować) i potwierdzanie — wzmianki trafiają też do feedu powiadomień poniżej
GET	/me/data-export	Samodzielny eksport Twoich danych zgodny z RODO
GET	/me/consent · POST /me/consent	Odczyt / zapis zgody ({ consent_type, granted })
GET	/legal/pending · POST /legal/accept	Oczekujące dokumenty clickwrap / zapis akceptacji
GET / PUT	/agent/me	Własna tożsamość i profil klucza agenta, do odczytu i edycji przez agenta (agentowy odpowiednik /me)
POST	/api/contact · /api/feedback · /api/feedback/with-screenshot	Kontakt + opinia w aplikacji. Poza /v1; limit szybkości per IP

Dane referencyjne (nieuwierzytelnione)

Lookupy zasiewane używane przy tworzeniu/estymowaniu historii. Stabilne identyfikatory.

Metoda	Ścieżka	Opis
GET	/story_types	feature, bug, chore, release (+ allow_points)
GET	/story_states	unstarted … accepted, rejected
GET	/effort_scales	dostępne skale estymacji
GET	/effort_scales/{scale_id}/values	wartości punktowe w skali
GET	/priority_scales · /priority_scales/{scale_id}/values	skale priorytetów i ich wartości (tu rozwiązuje się priority_id historii)

Organizacje

Tylko usługa hostowana — instalacja samodzielnie hostowana działa w trybie jednej organizacji i nie montuje tych endpointów (poza listą organizacji). Role są rolami organizacyjnymi: owner, admin, member.

Metoda	Ścieżka	Opis
GET / POST	/organizations	Wylistuj swoje organizacje / utwórz nową
GET / PUT / DELETE	/organizations/{oid}	Odczytaj, zmień nazwę (nazwa + slug; owner lub admin), usuń
GET / POST	/organizations/{oid}/memberships · PUT / DELETE …/memberships/{member_id}	Członkowie i zaproszenia; zaproszenia mają sufit roli (nigdy powyżej roli wywołującego; do roli owner nikogo się nie zaprasza)
POST	/organizations/{oid}/memberships/bulk-role · …/memberships/bulk-remove	Zmiana roli lub usunięcie do 200 członków naraz. Wszystko albo nic: partia, która usunęłaby ostatniego ownera lub zostawiła projekt bez właściciela, jest odrzucana w całości; z reassign_confirmed zamiast tego stajesz się właścicielem tych projektów
DELETE	/organizations/{oid}/invitations/{invitation_id}	Cofnij oczekujące zaproszenie
POST	/organizations/{oid}/transfer-ownership	Przekaż rolę owner innemu członkowi
PUT	/organizations/{oid}/memberships/{member_id}/anonymization	Zamaskuj imię / e-mail / awatar członka w całej organizacji
GET	/organization-invitations/{token} · POST …/{token}/accept	Rozwiąż / zaakceptuj zaproszenie do organizacji wysłane e-mailem
POST	/organizations/{oid}/export · GET / POST …/export/jobs · GET …/export/jobs/{job_id} · …/export/jobs/{job_id}/download	Eksport organizacji tylko dla właściciela: zip ze zrzutem SQL i każdym załącznikiem, uruchamiany jako zadanie

Projekty

Metoda	Ścieżka	Opis
GET	/projects	Wylistuj swoje projekty (limit ≤ 200)
POST	/projects	Utwórz projekt
GET	/projects/{id}	Pobierz szczegóły projektu (viewer)
PUT	/projects/{id}	Zaktualizuj ustawienia projektu (manager)
DELETE	/projects/{id}	Usuń projekt (manager)
POST	/projects/{id}/pin	Przypnij / odepnij projekt na swojej liście projektów
POST	/projects/{id}/transfer-organization	Przenieś projekt do innej organizacji (manager)
POST	/projects/{id}/slack/test	Wyślij wiadomość testową do kanału Slack projektu (manager)
GET / POST	/projects/{id}/showcase_claim_eligibility · /projects/{id}/showcase_claim · /projects/{id}/showcase_seed	Publiczne projekty pokazowe: sprawdź, czy możesz przejąć projekt, przejmij go, zasiej go danymi
GET	/projects/{id}/audit-log	Odczyt audit logu — historia projektu plus aktywność per historia / per epic przez surface=; dostęp zależy od surface, zobacz poniżej
GET	/projects/{id}/events	Strumień zdarzeń stronicowany kursorem (member) — zobacz Zdarzenia

Parametry zapytania audit logu: event_type= (jeden typ lub lista rozdzielona przecinkami), limit= (≤ 1000), before= (kursor keyset, created_at w ISO-8601), surface= (project_history, story_activities, epic_activities), target_id= (id historii/epica — wymagane, gdy surface=story_activities lub epic_activities). Dostęp: niefiltrowany log i surface=project_history to (manager); story_activities / epic_activities może czytać każdy członek projektu, a w projektach publicznych także anonimowo, z usuniętymi danymi osobowymi aktora.

Członkowie, agenci i klucze agentów

Metoda	Ścieżka	Opis
GET	/projects/{id}/memberships	Wylistuj członków (viewer)
POST	/projects/{id}/memberships	Zaproś członka przez e-mail (manager)
PUT	/projects/{id}/memberships/{mid}	Zaktualizuj rolę (manager)
DELETE	/projects/{id}/memberships/{mid}	Usuń członka (manager)
GET	/projects/{id}/addable-members · POST /projects/{id}/members/add-existing	Członkowie organizacji, których jeszcze nie ma w projekcie / dodaj jednego bez zaproszenia e-mailem (manager)
POST	/projects/{id}/members/join	Owner lub admin organizacji dołącza do projektu w swojej organizacji jako manager albo awansuje się do tej roli (akcja Make me owner na liście projektów)
PUT	/projects/{id}/members/{mid}/anonymization	Zamaskuj imię / e-mail / awatar członka w tym projekcie (manager)
GET / POST	/projects/{id}/agent_keys	Wylistuj / wybij klucze agentów — menedżerowie albo role dopuszczone przez creator-roles policy projektu
DELETE	/projects/{id}/agent_keys/{kid}	Odbierz klucz agenta
GET	/projects/{id}/agent_keys/onboarding	Pakiet onboardingowy: prompty i pliki konfiguracyjne dla popularnych klientów agentowych
GET	/projects/{id}/agents · GET / PUT /projects/{id}/agents/{aid}	Agenci projektu i ich profile (nazwa, inicjały, opis, kolor)
POST	/projects/{id}/agents/{aid}/rotate-key · /projects/{id}/agents/{aid}/avatar	Zrotuj klucz agenta (tożsamość i historia zostają) / prześlij jego awatar

Historie

Wszystkie zapisy historii wymagają roli member.

Metoda	Ścieżka	Opis
GET	/projects/{id}/stories	Wylistuj historie (stronicowane, filtrowalne) (viewer)
POST	/projects/{id}/stories	Utwórz historię
GET	/projects/{id}/stories/{sid}	Pobierz jedną historię (viewer)
PUT	/projects/{id}/stories/{sid}	Zaktualizuj historię
DELETE	/projects/{id}/stories/{sid}	Usuń historię
POST	/projects/{id}/stories/{sid}/transitions	Zmień stan z walidacją
POST	/projects/{id}/stories/{sid}/reject · /projects/{id}/stories/{sid}/restart	Odrzuć dostarczoną historię / przywróć odrzuconą do started (rejected jest stanem końcowym dla /transitions)
POST	/projects/{id}/stories/{sid}/archive · /projects/{id}/stories/{sid}/unarchive	Zarchiwizuj / przywróć z archiwum jedną historię
POST	/projects/{id}/stories/bulk_transition	Przejdź wieloma historiami (1–100) naraz
POST	/projects/{id}/stories/bulk-archive · bulk-delete · bulk-duplicate · bulk-move	Zarchiwizuj, usuń, zduplikuj lub przenieś (do panelu / na pozycję) wiele historii
POST	/projects/{id}/stories/{sid}/duplicate	Zduplikuj jedną historię
GET / POST / DELETE	/projects/{id}/stories/{sid}/epics · …/epics/{eid}	Przynależność historii do epików
GET	/short-links/{code} · /story-references	Rozwiąż krótki link /s/<code> do jego historii / rozwiąż do 100 odwołań do historii (#id, adresy URL) na historie, które wywołujący może odczytać

Parametry zapytania listy historii: archived= (exclude domyślnie / include / only — trójstanowy filtr archiwum; zastępuje przestarzałe include_archived=true, będące teraz aliasem archived=include), include_done=true (dopuszcza historie panelu Done zamrożone na minionych iteracjach, domyślnie wykluczone). Stronicowanie (cursor= / limit= / offset=) i rzadkie zestawy pól (fields=) działają zgodnie z sekcjami Stronicowanie i Projekcja pól.

Tworzenie (POST …/stories): { "name" (required), "story_type": "feature|bug|chore|release", "description"?, "estimate"?, "current_state"?, "icebox"?, "labels"? }. estimate to etykieta wartości skali jako ciąg znaków ("3", "13"); liczba JSON jest odrzucana. labels akceptuje ["auth"] lub [{ "name": "auth" }]; nieznane etykiety są tworzone. Wartości domyślne: story_type=feature, current_state=unstarted.

Aktualizacja (PUT …/stories/{sid}): te same pola, wszystkie opcjonalne, plus "position" (float), "force_state_change" (bool) i "expected_updated_at" (RFC 3339 — zapis opisu jest odrzucany z 409 stale_write, jeśli historia zmieniła się od chwili, gdy ją odczytałeś). Zapisy historii respektują też If-Match względem ETag historii; niezgodność daje 412 precondition_failed.

Przejście (POST …/transitions): { "to": "<state>" }. Pole to to. Zwraca { story_id, state }. Niedozwolony ruch → 422 invalid_transition z details: { from, to, allowed }.

Przejście zbiorcze (POST …/bulk_transition): { "story_ids": [int,…] (1–100), "to": "<state>" }. Każda historia jest oceniana niezależnie; zwraca { results: [ { id, status: "ok" } | { id, status: "failed", error } ] }.

Podzasoby historii

Wszystkie member. Listowanie/GET dla większości to (viewer).

Metoda	Ścieżka	Ciało / uwagi
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) } lub { comment_emoji }. GET przyjmuje fields= (lista dozwolonych: comment_id, story_comment_id, story_id, comment_text, comment_emoji, member, created) oraz 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; adresy URL GitHuba z /pull/ i /tree/ są typowane automatycznie
GET / POST	/projects/{id}/stories/{sid}/reviews · PUT/DELETE …/reviews/{rid}	Tworzenie: { reviewer_id? / reviewer_agent_id?, comment? } — pomiń oba, aby przypisać siebie. Aktualizacja: { status, comment? }
GET / POST	/projects/{id}/stories/{sid}/owners · DELETE …/owners/{mid} · DELETE …/owners/agents/{aid}	{ member_id? / agent_id? } — pomiń oba, aby dodać wywołującego
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}	przesyłanie multipart — wideo ≤ 200 MB, PDF / Word / Excel ≤ 25 MB, obrazy / CSV / tekst ≤ 10 MB; listowanie to (viewer)
GET / POST	/projects/{id}/stories/{sid}/link-attachments · DELETE …/link-attachments/{laid}	Załączniki-linki — zewnętrzny adres URL przechowywany obok załączników plikowych, a nie jako powiązanie z kodem
GET	/attachments/{token} · /api/avatars/{token}	Odczyty załącznika lub awatara adresowane tokenem — adresy URL, które wydaje API; X-TrackerToken nie jest potrzebny

Epiki

Ten sam kształt co historie, bez maszyny stanów. member dla zapisów, (viewer) dla odczytów.

Metoda	Ścieżka	Opis
GET / POST	/projects/{id}/epics · GET / PUT / DELETE …/epics/{eid}	Epiki mają nazwę, opis w Markdown i powiązaną etykietę, która łączy ich historie
GET / POST / PUT / DELETE	…/epics/{eid}/comments · …/comments/{cid}	Komentarze epików
GET / POST / DELETE	…/epics/{eid}/owners · …/followers (+ warianty /agents/{aid})	Właściciele i obserwujący, członkowie lub agenci — właściciele epiku przechodzą na jego historie
GET / POST / DELETE	…/epics/{eid}/attachments (+ /json) · …/link-attachments	Załączniki, te same limity co w historiach
GET	/projects/{id}/analytics/epics · …/analytics/epics/{eid}	Postęp per epik: burnup, przepustowość, kondycja, prognoza (viewer)

Etykiety

member dla zapisów, (viewer) dla odczytów.

Metoda	Ścieżka	Opis
GET / POST	/projects/{id}/labels	Wylistuj / utwórz etykietę
PUT / DELETE	/projects/{id}/labels/{lid}	Zaktualizuj / usuń etykietę
POST	/projects/{id}/labels/{lid}/archive	Zarchiwizuj (miękko ukryj) etykietę

Iteracje

Odczyty są otwarte dla każdej roli w projekcie, a w projekcie publicznym także anonimowo.

Metoda	Ścieżka	Opis
GET	/projects/{id}/iterations	Wylistuj iteracje (≤ 500 na stronę; przy obcięciu niesie ETag i nagłówki kontynuacji X-Tracker-Pagination-*)
GET	/projects/{id}/iterations/{itid}	Jedna iteracja
GET	/projects/{id}/iterations/first-preview	Daty, które otrzymałaby pierwsza iteracja, pokazywane w potwierdzeniu jej założenia
POST	/projects/{id}/iterations	Utwórz ręczną iterację (member)
DELETE	/projects/{id}/iterations/{itid}	Usuń iterację (manager)
PUT	/projects/{id}/iterations/{itid}/velocity	Nadpisz prędkość jednej iteracji bez zmiany strategii projektu (manager)
GET	/projects/{id}/iterations/{itid}/done-stories	Zaakceptowane historie zamkniętej iteracji, stronicowane

Wyszukiwanie, metryki, preferencje

Metoda	Ścieżka	Opis
GET	/projects/{id}/search?q=…	Potężne wyszukiwanie — pełnotekstowe + kwalifikatory aspektów / zakresów dat / osób (DSL w stylu GitHuba); zwraca { results, total, limit, offset }. query to alias q; limit= (domyślnie 50, maks. 1000) / offset= stronicują; sort= porządkuje według relevance (domyślnie), created, created_asc, state lub updated. (viewer) — zobacz Przewodnik
GET	/projects/{id}/metrics/{velocity,burndown,story-types,contributors}	Serie danych strony Metrics (viewer); metryki epików są pod /analytics/epics powyżej
GET	/projects/{id}/backlog/grouping	Prognozowane grupy iteracji Backlogu (viewer)
GET / PUT	/projects/{id}/preferences	Twoje preferencje tablicy dla tego projektu — dowolna rola w projekcie, tylko Twój własny wiersz

Zdarzenia

Metoda	Ścieżka	Opis
GET	/projects/{id}/events	Strumień zdarzeń stronicowany kursorem (member) — viewerzy dostają 403

Parametry zapytania: since=<event_id>, types=story.created,story.transitioned,comment.added,…, limit= (≤ 500), cursor=. Odpowiedź zawiera next_cursor. Przekaż ostatni widziany event_id jako since, aby wznowić.

Powiadomienia

Ujednolicony feed powiadomień w aplikacji: pełnoprawne wiersze powiadomień (prośby o review, aktywność na story, zaproszenia, …) połączone ze skrzynką @-wzmianek w jeden strumień, od najnowszych. Id w feedzie mają prefiks źródła (nt-… / sc-… / ec-…). Sesje członków i klucze ea_user_* czytają swoje wiersze członkowskie; klucze ea_agent_* swoje wiersze agentowe.

Metoda	Ścieżka	Opis
GET	/me/notifications	Twój feed powiadomień. Filtry: unread=true, since_id=, kind= (mentions / reviews / stories / invitations); stronicuj przez cursor= / limit=
GET	/me/notifications/unread-count	Sumy nieprzeczytanych — { unread_count, by_category: { mentions, reviews, stories, invitations } }
POST	/me/notifications/read-all	Oznacz wszystko jako przeczytane; zwraca świeże liczniki
POST	/me/notifications/{id}/ack	Oznacz jeden element jako przeczytany (idempotentne)
POST	/me/notifications/{id}/accept	Zaakceptuj zaproszenie do projektu / organizacji z poziomu feedu (tylko tokeny członkowskie)
POST	/me/notifications/{id}/decline	Odrzuć zaproszenie do projektu / organizacji (tylko tokeny członkowskie)
GET	/me/notifications/resolve-invite?token=…	Zamień e-mailowy token zaproszenia na id Twojego powiadomienia — { "id": "nt-…" } albo { "id": null }
GET	/me/notifications/stream	Push na żywo — Server-Sent Events (text/event-stream); patrz niżej

Endpoint stream nie jest endpointem JSON i dlatego nie ma go w specyfikacji OpenAPI: utrzymuje otwarte połączenie i przy każdym nowym zdarzeniu wysyła ramkę bez payloadu ({"type":"notification","kind":…}), sygnalizując klientowi, by pobrał feed ponownie. Połączenia są zamykane po stronie serwera po 45 minutach — połącz się i uwierzytelnij ponownie. Tylko sesje członków i klucze ea_user_*; klucze ea_agent_* dostają 403.

Import (manager)

Metoda	Ścieżka	Opis
POST	/projects/{id}/import	Źródła plikowe: source= ∈ pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json, eat. Multipart file=. Synchroniczny — odpowiada liczbami wyników.
POST	/projects/{id}/import/json	Ciało JSON; source=github nie potrzebuje pliku — owner, repo, opcjonalnie token oraz opt-in flagi include_pull_requests / include_milestones / include_releases / include_dependencies; źródła plikowe wysyłają file_base64. Asynchroniczny: zwraca 202 { import_id, status }. Serwer pobiera przez API GraphQL GitHuba, które odrzuca anonimowych wywołujących, więc do GitHuba zawsze trafia token — twój albo współdzielony token wdrożenia. Zobacz Przewodnik.
GET	/projects/{id}/imports/{import_id}	Odpytuj zadanie: status przechodzi pending → fetching → writing → done | failed, z progress_current / progress_total podczas pobierania i liczbami wyników przy done

W projekcie działa naraz jeden import; drugi POST, gdy jeden trwa, daje 409 import_already_running. dry_run: true (ciało JSON lub dry_run=true w multipart) podglądowo uruchamia dowolne źródło: parsuje, rozwiązuje, deduplikuje, zwraca te same liczby { imported, skipped, errors, unmatched }, po czym cofa zmiany — nic nie jest zapisywane. Limity: 10 MiB ciała i 5000 historii na import dla źródeł plikowych (przekroczenie któregokolwiek → 400, bez żadnego zapisu). Źródło GitHub nie ma limitu — zapisuje partiami zamiast w jednej transakcji. Ponowny import jest idempotentny per identyfikator źródłowy — już zaimportowane wiersze są pomijane, a nie duplikowane.

Eksport

Metoda	Ścieżka	Opis
GET	/projects/{id}/export/formats	Zarejestrowane formaty: { id, name, content_type, drops, includes_archived }. Dowolna rola w projekcie.
GET	/projects/{id}/export/{format}	Pobierz jeden (manager). Wymiana: eat (pełna wierność), jira, pivotal, shortcut, trello, asana, gitlab, linear, plane, plane_json; dokumenty: pdf, docx.
GET	/projects/{id}/export/attachments	Każdy załącznik jako jeden przeglądalny zip (pliki zachowują oryginalne nazwy; manifest JSON + CSV) (manager).

Eksporty dokumentów (pdf, docx) przyjmują dodatkowe parametry zapytania: page_size= (letter domyślnie / a4 / legal / folio), from= / to= (granice okna historii — RFC 3339 lub samo YYYY-MM-DD; historia mieści się w zakresie, gdy jej created lub completed_at w niego wpada), include_icebox= / include_backlog= (oba domyślnie false, więc eksport do udostępnienia pokazuje tylko pracę zaplanowaną / w toku). Formaty wymiany CSV je ignorują.

Kopie zapasowe i przywracanie (manager)

Metoda	Ścieżka	Opis
GET / POST	/projects/{id}/backups · GET …/backups/{snapshot_id} · …/backups/health	Wylistuj migawki, wykonaj jedną teraz, odczytaj jedną oraz podsumowanie kondycji retencji
GET / POST	/projects/{id}/restores · POST …/restores/partial · GET …/restores/{restore_id}	Przywróć całą migawkę albo wybrane tabele z jednej i odpytuj przebieg przywracania

Te POST podlegają wrażliwemu poziomowi limitu szybkości (poniżej).

MCP i dostawca OAuth

East Agile Tracker jest dostawcą OAuth 2.1 dla klientów MCP. Klient odkrywa go pod /.well-known/oauth-authorization-server i /.well-known/oauth-protected-resource/mcp, kieruje Cię do /oauth/authorize (strona zgody), wymienia kod pod /oauth/token, a następnie komunikuje się przez MCP pod /mcp z uzyskanym tokenem ea_mcp_*. Uprawnienia są listowane i odbierane pod /me/oauth_grants. Endpointy dostawcy mają własny poziom limitu szybkości.

WebSocket

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

Do interaktywnego zdalnego sterowania interfejsem ({ "action": "get_state", "id": "req-1" }). Token to JWT sesji przeglądarki — klucz API jest odrzucany z 401 przed uaktualnieniem połączenia. Nie jest kanałem danych — wszystkie odczyty/zapisy idą przez REST. Tylko pojedyncza instancja; nierozprowadzane między replikami.

Idempotencja

Endpointy zapisu (POST, PUT, DELETE) akceptują nagłówek Idempotency-Key. Ten sam klucz + to samo ciało odtwarza zbuforowaną odpowiedź (okno 24-godzinne); ten sam klucz + inne ciało zwraca 409 idempotency_conflict. Klucz jest przypisany do poświadczenia, które go wysłało. Nie stosowane do GET/HEAD/OPTIONS, /openapi.json i /docs, /api/auth/* ani przesyłania multipart na ścieżkach /attachments. Odpowiedzi, które zakończyły się przed odpowiedzią domeny, nigdy nie są buforowane — 401, 403, 404, 429 i każde 5xx — więc ponowienie po którejkolwiek z nich dociera do handlera; 400, 409, 412 i 422 są odpowiedzią domeny i są odtwarzane jak sukces.

Stronicowanie

Endpointy listujące akceptują cursor=<opaque> i limit=<n>. Gdy ustawione, odpowiedź to { "items": [...], "next_cursor": "<str|null>" }; przekaż next_cursor z powrotem, aby stronicować. Limit limit zależy od endpointu: 200 dla historii, komentarzy i projektów; 500 dla zdarzeń; 1000 dla wyszukiwania i dziennika audytu.

Zwykła lista (bez cursor/limit), która musiała obciąć odpowiedź, sygnalizuje to w nagłówkach — X-Tracker-Pagination-Truncated, X-Tracker-Pagination-Limit, X-Tracker-Pagination-Offset i X-Tracker-Pagination-Next-Offset; przekaż ostatni z nich jako offset=, aby pobrać następną stronę. Nie ma nagłówka z łączną liczbą.

Projekcja pól

Endpointy listujące akceptują fields= (rozdzielone przecinkami), aby zwrócić tylko określone pola. story_id jest zawsze dołączane; nieznana nazwa pola zwraca 400 validation_failed z wadliwymi nazwami w details.fields.

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

Format błędów

Każdy błąd JSON ma code i error; niektóre dodają details:

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

Status	code	Kiedy
400	invalid_parameter	błędne wejście; komunikat w error, bez details (większość walidacji: puste/długość/bajt null/e-mail)
400	validation_failed	strukturyzowany błąd wejścia; details.fields to tablica nazw wadliwych pól
401	unauthenticated	brakujący/nieprawidłowy token
403	unauthorized_operation	uwierzytelniony, ale niewystarczająca rola
404	unfound_resource	nie znaleziono — zwracane również osobom niebędącym członkami
409	conflict	konflikt zasobu (np. duplikat)
409	idempotency_conflict	Idempotency-Key użyty ponownie z innym ciałem
409	stale_write · import_already_running	historia zmieniła się od Twojego expected_updated_at · import już trwa
412	precondition_failed	If-Match nie pasował do bieżącego ETag zasobu; details niesie expected i current
413	request_too_large	ciało przekracza limit rozmiaru trasy
422	invalid_transition	niedozwolony ruch stanu; details niesie { from, to, allowed }
429	rate_limited	zbyt wiele żądań z tego IP na trasie z limitem szybkości; nagłówek Retry-After
500	internal_error	usterka serwera — komunikat ogólny; bezpieczne do ponowienia
503	not_configured	wdrożeniu brakuje integracji, której ta trasa potrzebuje (SMS, magazyn obiektów, …)

details.fields to tablica JSON nazw pól (np. ["to"]), czasem z dodatkowymi kluczami jak max. Nie ma mapy pole→komunikat.

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

Limity szybkości

Per IP klienta, na kilku trasach; uwierzytelniony ruch API poza nimi nie ma limitu szybkości. Wartości domyślne (każda para to stała szybkość i burst, regulowane przez operatora):

• Auth — /api/auth/*: 0.5 req/s, burst 20.
• Dostawca OAuth — /oauth/*: 1 req/s, burst 60.
• Public — /api/contact: 0.2 req/s, burst 10.
• Feedback — /api/feedback: trzy nałożone poziomy — jedno zgłoszenie na 15 s, 10 na godzinę, 36 na dobę.
• Awatary — nieuwierzytelnione przekierowanie awatara: 20 req/s, burst 200.
• Sensitive — POST kopii zapasowych i przywracania: ~0.002 req/s, burst 5.

Przekroczony limit zwraca 429 z nagłówkiem Retry-After i standardową kopertą błędu JSON, code: "rate_limited".