API-specifikation

Den kompletta REST-endpoint-referensen. För handledningar och exempel, se API-guiden.

Allt en projektmedlem kan göra i webbgränssnittet finns tillgängligt här — SPA:n använder samma API. Operationer som kräver manager-rollen är markerade (manager); allt annat kräver enbart projektmedlemskap (eller, för läsningar markerade (viewer), vilken åtkomstnivå som helst). Tabellerna nedan namnger varje ruttgrupp som servern monterar; de som sammanfattas på en enda rad beskrivs fullständigt i den live openapi.json.

Bas

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

API:et har en egen värd: eastagiletracker.com betjänar webbappen och svarar på /api/v1/… med 404. Alla requests och svar är JSON, förutom några fil-uppladdnings-endpoints som accepterar multipart.

Två grupper ligger en nivå upp, under /api i stället för /api/v1: autentiseringsytan (/api/auth/*) och det publika kontaktformuläret (/api/contact). Deras /api/v1/…-varianter returnerar 404.

Autentisering

Varje autentiserad request skickar en inloggningsuppgift via något av:

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

Användarnycklar börjar med ea_user_, agentnycklar med ea_agent_ och MCP-åtkomsttokens med ea_mcp_. Se API-guide → Tre sorters inloggningsuppgifter.

Oautentiserade endpoints: /openapi.json, /docs, /api/auth/*-endpointerna och uppslagen av referensdata (/story_types, /story_states, /effort_scales, /priority_scales). /meta är autentiserad — vilken giltig nyckel som helst fungerar, men den är inte projektavgränsad (en projektbunden agentnyckel når den också).

Roller

Fyra nivåer styr projektavgränsade endpoints:

Nivå	Vem passerar	Typiska operationer
public viewer	vem som helst, på ett projekt vars synlighet är publik	läsningar av boarden: stories, iterationer, sökning, story- och epic-aktivitet (med aktörsuppgifterna maskerade)
viewer	viewer, member, manager	läsningar (lista/hämta stories, sökning, mätvärden, listan över exportformat)
member	member, manager	alla skrivningar av arbetsposter (stories, tasks, kommentarer, …), händelseströmmen
manager	endast manager	projektinställningar, medlemshantering, agentnycklar, radering, import, exportnedladdningar, säkerhetskopior, granskningslogg

Agenter har samma roller som medlemmar — viewer, member eller manager — med den medlem som präglade nyckeln som tak. En icke-medlem får 404 unfound_resource (inte 403) på privata projektsökvägar, så projekt-ID:n går inte att räkna upp.

Självbeskrivande endpoints

Method	Path	Beskrivning
GET	/openapi.json	Den live OpenAPI 3-specifikationen, inklusive request-bodies. Oautentiserad.
GET	/docs	Swagger UI. Oautentiserad.
GET	/meta	Anroparens identitet (auth.kind/key_id/agent_id/project_id) + övergångsgrafen per story-typ. Autentiserad (vilken giltig nyckel som helst; inte projektavgränsad). Anropa detta först.
GET	/api/health · /api/config	Liveness, och driftsättningens publika konfiguration (enkelorganisationsläge, vilka valfria funktioner som är på, instansens namn). Oautentiserad, utanför /v1.

Auth (/api/auth/*, utanför /v1)

Sessions-endpoints, oautentiserade om inget annat anges. SPA:n driver dessa; skript använder normalt en API-nyckel i stället.

Method	Path	Beskrivning
POST	/auth/register	Registrera ett nytt konto — skyddat av reCAPTCHA; kontot passerar sedan SMS-utmaningen
POST	/auth/sms/challenge · /auth/sms/status · /auth/sms/bypass	Skicka / kontrollera SMS-koden vid registrering (bypass styrs av operatören)
GET	/auth/config	Vilka inloggningsmetoder driftsättningen erbjuder
POST	/auth/login	Logga in med e-post + lösenord; returnerar en sessions-JWT, eller en TOTP-utmaning
POST	/auth/login/totp	Slutför en inloggning med en kod från autentiseringsappen eller en recovery code
POST	/auth/passkey/login/start · /auth/passkey/login/finish	Lösenordsfri WebAuthn-inloggning
GET	/auth/oauth/github/start · /auth/oauth/github/callback · /auth/oauth/google/start · /auth/oauth/google/callback · POST /auth/oauth/exchange	OAuth-inloggning med GitHub eller Google
POST	/auth/refresh · /auth/refresh/revoke	Rotera refresh-token / återkalla den
POST	/auth/logout	Logga ut (autentiserad; återkallar den här sessionens refresh-token)
POST	/auth/oauth/link/preview · …/link/confirm · /auth/oauth/merge/preview · …/merge/confirm	Koppla ett GitHub- eller Google-konto till ett befintligt konto, eller slå ihop två konton
POST	/auth/email_addresses/primary/preview · …/primary/confirm	Slutför ett byte av primär e-postadress via den e-postade bekräftelselänken
POST	/auth/forgot-password · /auth/reset-password	Begär ett återställningsmejl / använd återställnings-token
POST	/auth/accept-invite/lookup · /auth/accept-invite	Slå upp en inbjudnings-token → e-post / acceptera projektinbjudan (efter autentisering)

Konto / identitet

Dessa agerar på anroparen och kräver ingen projektroll. De kräver en medlemsidentitet — en agentnyckel får 401 (agenter använder /agent/me). Anrop som ändrar inloggningsuppgifter — lösenord, TOTP, passkeys, radering av kontot, byte av e-postadress, förnyelse av token — kräver en webbläsarsession; en API-nyckel får 403.

Method	Path	Beskrivning
GET	/me	Aktuell användarprofil
PUT	/me	Uppdatera profil
DELETE	/me	Radera konto — nekas medan du är ensam owner för en organisation eller för ett projekt med andra medlemmar
GET	/me/deletion-impact	Vad en radering av kontot skulle ta bort och vad som blockerar den
PUT	/me/password	Byt lösenord
PUT	/me/settings	Uppdatera inställningar (tema, notisinställningar)
POST / DELETE	/me/avatar	Ladda upp (multipart) / ta bort din avatar
POST	/me/api-token/regenerate	Logga ut varje session och returnera en ny sessions-token; API-nycklar påverkas inte
GET	/me/api_keys · POST /me/api_keys · DELETE /me/api_keys/{id}	Hantera användar-API-nycklar (ea_user_)
GET	/me/totp · POST /me/totp/setup · /me/totp/verify · /me/totp/disable	Registrering av tvåfaktor (TOTP); verify returnerar recovery codes en gång
GET	/me/passkeys · POST /me/passkeys/register/start · /me/passkeys/register/finish · DELETE /me/passkeys/{credential_id}	Registrering och borttagning av passkeys
GET / POST	/me/email_addresses · GET …/email_addresses/offers · PUT …/email_addresses/primary	Dina e-postadresser; anta en ansluten leverantörs adress som alternativ adress; begär byte av primär adress (bekräftas via e-post)
GET	/me/oauth_identities · DELETE …/oauth_identities/{provider} · POST …/oauth_identities/{provider}/link	Anslutna inloggningskonton (GitHub, Google): lista, koppla från, starta en koppling
GET	/me/oauth_grants · DELETE /me/oauth_grants/{grant_id}	Anslutna appar — de MCP-klienter och OAuth-appar du har auktoriserat
GET	/me/activity	Din aktivitet över alla projekt
GET	/me/stories	Stories du äger, har beställt eller följer i alla projekt som token når — role=owned|requested|following, state=, cursor= / limit= (max 200)
GET	/me/mentions · POST /me/mentions/{mention_id}/ack	@-omnämnande-inkorgen (unacked=true för att filtrera) och kvittering — ingår också i notisflödet nedan
GET	/me/data-export	GDPR-självexport av dina data
GET	/me/consent · POST /me/consent	Läs / registrera samtycke ({ consent_type, granted })
GET	/legal/pending · POST /legal/accept	Väntande clickwrap-dokument / registrera godkännande
GET / PUT	/agent/me	En agentnyckels egen identitet och profil, läsbar och redigerbar av agenten (agentsidans motsvarighet till /me)
POST	/api/contact · /api/v1/feedback · /api/v1/feedback/with-screenshot	Kontakt + feedback i appen; hastighetsbegränsat per IP

Referensdata (oautentiserad)

Seed-uppslag som används när stories skapas/estimeras. Stabila ID:n.

Method	Path	Beskrivning
GET	/story_types	feature, bug, chore, release (+ allow_points)
GET	/story_states	unstarted … accepted, rejected
GET	/effort_scales	tillgängliga estimeringsskalor
GET	/effort_scales/{scale_id}/values	poängvärdena i en skala
GET	/priority_scales · /priority_scales/{scale_id}/values	prioritetsskalorna och deras värden (priority_id på en story slås upp här)

Organisationer

Endast den hostade tjänsten — en self-hostad installation körs i enkelorganisationsläge och monterar inte dessa (utom organisationslistan). Rollerna är organisationsroller: owner, admin, member.

Method	Path	Beskrivning
GET / POST	/organizations	Lista dina organisationer / skapa en
GET / PUT / DELETE	/organizations/{oid}	Läs, byt namn (namn + slug; owner eller admin), radera
GET / POST	/organizations/{oid}/memberships · PUT / DELETE …/memberships/{member_id}	Medlemmar och inbjudningar; inbjudningar har ett rolltak (aldrig över anroparens; owner bjuds aldrig in)
POST	/organizations/{oid}/memberships/bulk-role · …/memberships/bulk-remove	Ändra roll för eller ta bort upp till 200 medlemmar på en gång. Allt eller inget: en batch som skulle ta bort den sista ownern eller lämna ett projekt utan ägare avvisas helt; med reassign_confirmed blir du i stället ägare till de projekten
DELETE	/organizations/{oid}/invitations/{invitation_id}	Återkalla en väntande inbjudan
POST	/organizations/{oid}/transfer-ownership	Lämna över owner-rollen till en annan medlem
GET	/organization-invitations/{token} · POST …/{token}/accept	Slå upp / acceptera en e-postad organisationsinbjudan
GET	/organizations/{oid}/export · POST …/export/jobs · GET …/export/jobs/{job_id} · …/export/jobs/{job_id}/download	Organisationsexport endast för owners: en zip med en SQL-dump och varje bilaga, körd som ett jobb

Projekt

Method	Path	Beskrivning
GET	/projects	Lista dina projekt (limit ≤ 200)
POST	/projects	Skapa ett projekt
GET	/projects/{id}	Hämta projektdetaljer (viewer)
PUT	/projects/{id}	Uppdatera projektinställningar (manager)
DELETE	/projects/{id}	Radera ett projekt (manager)
POST / DELETE	/projects/{id}/pin	Fäst / lossa projektet i din projektlista
POST	/projects/{id}/transfer-organization	Flytta projektet till en annan organisation — anroparen måste vara Ansvarig för projektet och owner eller admin i målorganisationen
POST	/projects/{id}/slack/test	Skicka ett testmeddelande till projektets Slack-flöde (manager)
GET / POST	/projects/{id}/showcase_claim_eligibility · /projects/{id}/showcase_claim · /projects/{id}/showcase_seed	Publika showcase-projekt: kontrollera om du kan göra anspråk på ett, gör anspråk på det, seeda det (seedning är för produktadministratörer; alla andra får 404)
GET	/projects/{id}/audit-log	Läsning av audit-loggen — projekthistorik plus aktivitet per story / per epic via surface=; åtkomsten varierar per surface, se nedan
GET	/projects/{id}/events	Cursor-paginerad händelseström (member) — se Händelser

Query-parametrar för audit-loggen: event_type= (en typ eller kommaseparerad lista), limit= (standard 50, begränsas till 1000), before= (keyset-cursor <ISO-8601>|<audit_id> — skicka föregående sidas next_cursor), surface= (project_history, story_activities, epic_activities), target_id= (story-/epic-id — krävs när surface=story_activities eller epic_activities). Åtkomst: den ofiltrerade loggen är (manager); surface=project_history är (viewer), med medlemmarnas e-postadresser maskerade när projektet döljer dem; story_activities / epic_activities kan läsas av alla projektmedlemmar, och anonymt på publika projekt med aktörens PII maskerad.

Medlemmar, agenter och agentnycklar

Method	Path	Beskrivning
GET	/projects/{id}/memberships	Lista medlemmar (viewer)
POST	/projects/{id}/memberships	Bjud in en medlem via e-post (manager)
PUT	/projects/{id}/memberships/{mid}	Uppdatera roll (manager)
DELETE	/projects/{id}/memberships/{mid}	Ta bort en medlem (manager)
POST	/projects/{id}/memberships/bulk-role · …/memberships/bulk-remove	Ändra roll för, eller ta bort, många medlemmar på en gång (manager)
GET	/projects/{id}/addable-members · POST /projects/{id}/members/add-existing	Organisationsmedlemmar som ännu inte är med i projektet / lägg till en utan e-postinbjudan — (manager) och owner eller admin i organisationen
POST	/projects/{id}/members/join	En owner eller admin i organisationen går med i ett projekt i sin organisation som manager, eller befordrar sig själv till det (åtgärden Make me owner i projektlistan)
GET / POST	/projects/{id}/agent_keys	Lista (manager) / prägla agentnycklar — personer vars roll finns i projektets creator-roles policy; agentnycklar kan inte prägla
PUT / DELETE	/projects/{id}/agent_keys/{kid}	Redigera en nyckels namn, roll eller svarstips / återkalla den (manager)
GET	/projects/{id}/agent_keys/onboarding	Onboarding-paketet: prompter och konfigurationsfiler för de vanliga agentklienterna
GET	/projects/{id}/agents · GET / PUT / DELETE /projects/{id}/agents/{aid}	Projektets agenter och deras profiler (namn, initialer, beskrivning, färg); DELETE återkallar agenten och alla dess nycklar — en manager eller den som skapade agenten
POST	/projects/{id}/agents/{aid}/rotate-key · /projects/{id}/agents/{aid}/avatar	Rotera en agents nyckel (identitet och historik behålls) / ladda upp dess avatar

Stories

Alla story-skrivningar kräver member-rollen. Att skapa en story med bakåtdaterade datum, importursprung (import_source / import_external_id) eller externa ägare eller beställare kräver (manager).

Method	Path	Beskrivning
GET	/projects/{id}/stories	Lista stories (paginerade, filtrerbara) (viewer)
POST	/projects/{id}/stories	Skapa en story
GET	/projects/{id}/stories/{sid}	Hämta en story (viewer)
PUT	/projects/{id}/stories/{sid}	Uppdatera en story
DELETE	/projects/{id}/stories/{sid}	Radera en story
POST	/projects/{id}/stories/{sid}/transitions	Ändra tillstånd med validering
POST	/projects/{id}/stories/{sid}/reject · /projects/{id}/stories/{sid}/restart	Avvisa en levererad story / sätt tillbaka en avvisad till started (rejected är ett sluttillstånd för /transitions)
POST	/projects/{id}/stories/{sid}/archive · /projects/{id}/stories/{sid}/unarchive	Arkivera / avarkivera en story
POST	/projects/{id}/stories/bulk_transition	Transitionera många stories (1–100) på en gång
POST	/projects/{id}/stories/bulk-archive · bulk-delete · bulk-duplicate · bulk-move	Arkivera, radera, duplicera eller flytta (till en panel / position) många stories
POST	/projects/{id}/stories/bulk-unarchive	Avarkivera många stories
POST	/projects/{id}/stories/{sid}/duplicate	Duplicera en story
POST / DELETE	/projects/{id}/stories/{sid}/epics · …/epics/{eid}	Storyns epic-medlemskap
GET	/short-links/{code} · /story-references	Slå upp en /s/<code>-kortlänk till dess story / slå upp upp till 100 referenser — codes= (kommaseparerade kortlänkskoder) och ids= (kommaseparerade project_id:story_id) — till de stories anroparen kan läsa

Frågeparametrar för story-listan: archived= (exclude som standard / include / only — det trelägiga arkivfiltret; ersätter det utfasade include_archived=true, som nu är ett alias för archived=include), include_done=true (tar med stories från Done-panelen frysta på tidigare iterationer, exkluderade som standard). Paginering (cursor= / limit= / offset=) och glesa fältmängder (fields=) följer Paginering och Fältprojektion.

Skapa (POST …/stories): { "name" (required), "story_type": "feature|bug|chore|release", "description"?, "estimate"?, "current_state"?, "icebox"?, "labels"? }. estimate är skalvärdets etikett som en sträng ("3", "13"); ett JSON-nummer avvisas. labels accepterar ["auth"] eller [{ "name": "auth" }]; okända etiketter skapas. Standardvärden: story_type=feature, current_state=unstarted.

Uppdatera (PUT …/stories/{sid}): samma fält, alla valfria, plus "position" (float), "force_state_change" (bool) och "expected_version" (heltal, storyns version — en sparning av beskrivningen nekas med 409 stale_write om beskrivningen har ändrats efter den versionen). Det äldre "expected_updated_at" (RFC 3339) är föråldrat och fungerar en release till: skickat med en beskrivning och utan expected_version nekas sparningen med 409 stale_write om det inte är lika med storyns updated_at. Story-skrivningar respekterar också If-Match mot storyns ETag; en avvikelse ger 412 precondition_failed.

Transition (POST …/transitions): { "to": "<state>" }. Fältet är to. Returnerar { story_id, state }. Otillåten förflyttning → 422 invalid_transition med details: { from, to, allowed }.

Bulk-transition (POST …/bulk_transition): { "story_ids": [int,…] (1–100), "to": "<state>" }. Varje story bedöms oberoende; returnerar { results: [ { id, status: "ok" } | { id, status: "failed", error } ] }.

Underresurser till story

Alla member. List/GET på de flesta är (viewer). Att radera en bilaga eller länkbilaga kräver den som laddade upp den eller (manager).

Method	Path	Body / anmärkningar
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) } eller { comment_emoji }. GET tar fields= (tillåtelselista: comment_id, story_comment_id, story_id, comment_text, comment_emoji, member, created) plus 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}	Skapa: { url, link_type?, title? }; uppdatera: { url, title? } — link_type ∈ relates_to, duplicates, blocks, is_blocked_by, pull_request, branch, other; GitHub-URL:er med /pull/ och /tree/ typas automatiskt
GET / POST	/projects/{id}/stories/{sid}/reviews · PUT/DELETE …/reviews/{rid}	Skapa: { reviewer_id? / reviewer_agent_id?, comment? } — utelämna båda för att tilldela dig själv. Uppdatera: { status, comment? }
GET / POST	/projects/{id}/stories/{sid}/owners · DELETE …/owners/{mid} · DELETE …/owners/agents/{aid}	{ member_id? / agent_id? } — utelämna båda för att lägga till anroparen
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}	{ label_id } — en befintlig projektetikett; skapa etiketter med POST /projects/{id}/labels, eller skicka labels i storyns PUT
GET / POST	/projects/{id}/stories/{sid}/attachments (+ /json) · DELETE …/attachments/{aid}	multipart-uppladdning — video ≤ 200 MB, PDF / Word / Excel ≤ 25 MB, bilder / CSV / text ≤ 10 MB; listning är (viewer)
GET / POST	/projects/{id}/stories/{sid}/link-attachments · DELETE …/link-attachments/{laid}	Länkbilagor — en extern URL som förvaras bredvid filbilagorna i stället för som en kodlänk
GET	/attachments/{token} · /api/v1/avatars/{token}	Token-adresserade läsningar av en bilaga eller en avatar — de URL:er som API:et delar ut; ingen X-TrackerToken behövs

Epics

Samma form som stories, minus tillståndsmaskinen. member för skrivningar och för kommentars-, ägar- och följarlistorna; (viewer) för epic-listan, en enskild epic och bilagelistorna.

Method	Path	Beskrivning
GET / POST	/projects/{id}/epics · GET / PUT / DELETE …/epics/{eid}	Epics har ett namn, en Markdown-beskrivning och en underliggande etikett som knyter ihop deras stories
GET / POST / PUT / DELETE	…/epics/{eid}/comments · …/comments/{cid}	Epic-kommentarer
GET / POST / DELETE	…/epics/{eid}/owners · …/followers (+ /agents/{aid}-varianter)	Ägare och följare, medlemmar eller agenter — en epics ägare förs vidare till dess stories
GET / POST / DELETE	…/epics/{eid}/attachments (+ /json) · …/link-attachments	Bilagor, samma gränser som för stories
GET	/projects/{id}/analytics/epics · …/analytics/epics/{eid}	Framsteg per epic: burnup, genomströmning, hälsa, prognos (viewer)

Etiketter

member för skrivningar, (viewer) för läsningar.

Method	Path	Beskrivning
GET / POST	/projects/{id}/labels	Lista / skapa en etikett
GET / PUT / DELETE	/projects/{id}/labels/{lid}	Läs / uppdatera / radera en etikett
POST	/projects/{id}/labels/{lid}/archive	Arkivera (mjukt dölja) en etikett

Iterationer

Läsningar är öppna för alla projektroller, och anonyma på ett publikt projekt.

Method	Path	Beskrivning
GET	/projects/{id}/iterations	Lista iterationer (≤ 500 per sida; bär en ETag och X-Tracker-Pagination-*-fortsättningsheadrarna vid trunkering)
GET	/projects/{id}/iterations/{itid}	En iteration
GET	/projects/{id}/iterations/first-preview	Fönstret, den prognostiserade velocityn och Backlog-fyllnaden för den iteration som en startande skrivning skulle skapa, eller för den aktuella iterationen när den finns (member)
POST	/projects/{id}/iterations	Skapa en manuell iteration (manager)
DELETE	/projects/{id}/iterations/{itid}	Radera en iteration (manager)
PUT	/projects/{id}/iterations/{itid}/velocity	Åsidosätt en iterations velocity utan att ändra projektets strategi (manager)
GET	/projects/{id}/iterations/{itid}/done-stories	De accepterade stories i en stängd iteration, paginerade

Sökning, mätvärden, inställningar

Method	Path	Beskrivning
GET	/projects/{id}/search?q=…	Kraftfull sökning — fulltext + kvalificerare för facetter / datumintervall / personer (GitHub-liknande DSL); returnerar { results, total, limit, offset }. query är ett alias för q; limit= (standard 50, max 1000) / offset= paginerar; sort= sorterar efter relevance (standard), created, created_asc, state eller updated. (viewer) — se Guiden
GET	/projects/{id}/metrics/{velocity,burndown,story-types,contributors}	Metrics-sidans dataserier (viewer); epic-mätvärden finns under /analytics/epics ovan
GET	/projects/{id}/backlog/grouping	Backlogens projicerade iterationsgrupper (viewer)
GET / PUT	/projects/{id}/preferences	Dina board-inställningar för detta projekt — alla projektroller, bara din egen rad

Händelser

Method	Path	Beskrivning
GET	/projects/{id}/events	Cursor-paginerad händelseström (member) — viewers får 403

Query-parametrar: since_id=<event_id> (since är det äldre aliaset; since_id vinner när båda skickas), types=story.created,story.transitioned,comment.added,…, limit= (standard 100, ≤ 500), cursor=. Svaret är { items, next_since_id, next_cursor }: spara next_since_id och skicka tillbaka det som since_id för att återuppta; next_cursor är null på sista sidan.

Notiser

Det samlade notisflödet i appen: fullvärdiga notisrader (granskningsförfrågningar, story-aktivitet, inbjudningar, …) sammanslagna med @-omnämnande-inkorgen till en enda ström, nyast först. Flödes-id:n har källprefix (nt-… / sc-… / ec-…). Medlemssessioner och ea_user_*-nycklar läser sina medlemsrader; ea_agent_*-nycklar sina agentrader.

Method	Path	Beskrivning
GET	/me/notifications	Ditt notisflöde. Filter: unread=true, since_id=, kind= (mentions / reviews / stories / invitations); paginera med cursor= / limit=
GET	/me/notifications/unread-count	Olästa totaler — { unread_count, by_category: { mentions, reviews, stories, invitations } }
POST	/me/notifications/read-all	Markera allt som läst; returnerar de färska räknarna
POST	/me/notifications/{id}/ack	Markera ett objekt som läst (idempotent)
POST	/me/notifications/{id}/accept	Acceptera en projekt-/organisationsinbjudan från flödet (endast medlemstoken)
POST	/me/notifications/{id}/decline	Avböj en projekt-/organisationsinbjudan (endast medlemstoken)
GET	/me/notifications/resolve-invite?token=…	Slå upp ett e-postat inbjudningstoken till ditt notis-id — { "id": "nt-…" } eller { "id": null }
GET	/me/notifications/stream	Live-push — Server-Sent Events (text/event-stream); se nedan

Stream-endpointen är ingen JSON-endpoint och finns därför inte i OpenAPI-specifikationen: den håller anslutningen öppen och skickar en ram utan payload ({"type":"notification","kind":…}) så fort något nytt landar, som en signal till klienten att hämta om flödet. Anslutningar avslutas på serversidan efter 45 minuter — återanslut och autentisera igen. Endast medlemssessioner och ea_user_*-nycklar; ea_agent_*-nycklar får 403.

Import (manager)

Method	Path	Beskrivning
POST	/projects/{id}/import	Filkällor: source= ∈ pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json, eat. Multipart file=. Synkron — svarar med resultaträknarna.
POST	/projects/{id}/import/json	JSON-body; source=github behöver ingen fil — owner, repo, valfri token och opt-in-flaggorna include_pull_requests / include_milestones / include_releases / include_dependencies, och include_comments (standard true); filkällorna skickar file_base64. Asynkron: returnerar 202 { import_id, status }. Servern hämtar via GitHubs GraphQL-API, som avvisar anonyma anropare, så en token når alltid GitHub — din, eller driftsättningens delade. Se Guiden.
GET	/projects/{id}/imports/{import_id}	Polla ett jobb: status går pending → fetching → writing → done | failed, med progress_current / progress_total under hämtningen och resultaträknarna vid done

En JSON-import körs per projekt åt gången; en andra POST …/import/json medan en pågår ger 409 import_already_running. Med check_unpointed_estimates: true (filkällor; ignoreras för github) avvisas en fil med uppskattningar på buggar eller sysslor som projektet inte poängsätter med 409 import_unpointed_estimates och details.count innan något jobb startar; utan flaggan släpper importen dessa uppskattningar och rapporterar { code: "estimates_unpointed_dropped", count } i resultatets warnings. dry_run: true (JSON-body eller dry_run=true multipart) förhandsvisar valfri källa: tolkar, resolvar, av-dubblerar, returnerar samma { imported, skipped, errors, unmatched }-räknare och rullar sedan tillbaka — ingenting skrivs. Gränser: en fil på 10 MiB (400 import_too_large) och 5 000 stories per import för de filbaserade källorna (400 import_too_many_records); ingenting skrivs. En request-body över 16 MiB nekas tidigare med 413 request_too_large. GitHub-källan har inget tak — den skriver i block i stället för i en enda transaktion. Återimport är idempotent per käll-id — redan importerade rader hoppas över, inte dubbleras.

Export

Method	Path	Beskrivning
GET	/projects/{id}/export/formats	Registrerade format: { id, name, content_type, drops, includes_archived }. Alla projektroller.
GET	/projects/{id}/export/{format}	Ladda ner ett (manager). Utbyte: eat (full trohet), jira, pivotal, shortcut, trello, asana, gitlab, linear, plane, plane_json; dokument: pdf, docx.
GET	/projects/{id}/export/attachments	Varje bilaga som en bläddringsbar zip (filer behåller originalnamn; JSON- + CSV-manifest) (manager).

Dokumentexporter (pdf, docx) tar extra frågeparametrar: page_size= (letter som standard / a4 / legal / folio), from= / to= (story-fönstrets gränser — RFC 3339 eller bara YYYY-MM-DD; en story är i intervallet när dess created eller completed_at faller inom det), include_icebox= / include_backlog= (båda false som standard, så en delbar export visar bara schemalagt / pågående arbete). CSV-utbytesformaten ignorerar dem.

Säkerhetskopior och återställningar (manager)

Method	Path	Beskrivning
GET / POST	/projects/{id}/backups · GET …/backups/{snapshot_id} · …/backups/health	Lista snapshots, ta en nu, läs en, och sammanfattningen av lagringshälsan
POST	/projects/{id}/restores · POST …/restores/partial · GET …/restores/{restore_id}	Återställ en hel snapshot, eller valda tabeller från en, och polla återställningen

POST-anropen ligger på den känsliga hastighetsgränsnivån (nedan).

MCP och OAuth-leverantör

East Agile Tracker är en OAuth 2.1-leverantör för MCP-klienter. En klient hittar den via /.well-known/oauth-authorization-server och /.well-known/oauth-protected-resource/mcp, skickar dig till /oauth/authorize (samtyckessidan), växlar in koden på /oauth/token och talar sedan MCP på /mcp med den resulterande ea_mcp_*-token. Behörigheter listas och återkallas på /me/oauth_grants. Leverantörens endpoints har en egen hastighetsgränsnivå.

Idempotens

Skriv-endpoints (POST, PUT, DELETE) accepterar en Idempotency-Key-header. Samma nyckel + samma body spelar upp det cachade svaret (24-timmarsfönster); samma nyckel + en annan body returnerar 409 idempotency_conflict. Nyckeln är avgränsad till den inloggningsuppgift som skickade den. Tillämpas inte på GET/HEAD/OPTIONS, /openapi.json och /docs, /api/auth/*, /mcp, någon sökväg som innehåller /attachments eller någon multipart/*-request; en request utan inloggningsuppgift cachas aldrig. Svar som stannade innan domänen hann svara cachas aldrig — 401, 403, 404, 429 och varje 5xx — så ett omförsök efter något av dem når hanteraren; 400, 409, 412 och 422 är domänens svar och spelas upp som en framgång.

Paginering

List-endpoints accepterar cursor=<opaque> och limit=<n>. När de är satta är svaret { "items": [...], "next_cursor": "<str|null>" }; skicka tillbaka next_cursor för att bläddra. Taket för limit gäller per endpoint: 200 för stories, kommentarer och projekt; 500 för händelser; 1000 för granskningsloggen. Sökning paginerar med limit (≤ 1000) och offset i stället för en cursor och returnerar { results, total, limit, offset }.

En vanlig lista (utan cursor/limit) som var tvungen att trunkera sitt svar anger det i headrar — X-Tracker-Pagination-Truncated, X-Tracker-Pagination-Limit, X-Tracker-Pagination-Offset och X-Tracker-Pagination-Next-Offset; skicka tillbaka den sista som offset= för nästa sida. Det finns ingen header med totalantal.

Fältprojektion

Listorna för stories, kommentarer och projekt accepterar fields= (kommaseparerad) för att returnera enbart specifika fält. Resursens id inkluderas alltid (story_id, story_comment_id och comment_id, project_id); ett okänt fältnamn returnerar 400 validation_failed med de felande namnen i details.fields.

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

Felformat

Varje JSON-fel har code och error; vissa lägger till details:

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

Status	code	När
400	invalid_parameter	felaktig indata; meddelande i error. Fältvalidering (blank/längd/null-byte/e-post) lägger till details.fields och details.constraint; bara ett rent bad request-fel utelämnar details
400	validation_failed	strukturerat indatafel; details.fields är en array av felande fältnamn
400	domänkoder	ett ruttspecifikt avslag med en egen kod och utan details — t.ex. unsupported_export_format, import_too_large, import_unknown_source
401	unauthenticated	saknad/ogiltig token
403	unauthorized_operation	autentiserad men otillräcklig roll
404	unfound_resource	hittades inte — returneras även till icke-medlemmar
409	conflict	resurskonflikt (t.ex. dubblett)
409	idempotency_conflict	Idempotency-Key återanvänd med en annan body
409	stale_write · import_already_running · import_unpointed_estimates	beskrivningen har ändrats efter din expected_version (eller expected_updated_at stämmer inte längre) · en import pågår redan · filen har uppskattningar på buggar eller sysslor som projektet inte poängsätter (details.count)
412	precondition_failed	If-Match matchade inte resursens aktuella ETag; details bär expected och current
413	request_too_large	bodyn överskrider ruttens storleksgräns
422	invalid_transition	otillåten tillståndsförflyttning; details bär { from, to, allowed }
429	rate_limited	för många requests från denna IP på en hastighetsbegränsad rutt; Retry-After-header
500	internal_error	serverfel — generiskt meddelande; säkert att försöka igen
502	upstream_error	en tjänst som rutten är beroende av (t.ex. GitHub) misslyckades
503	not_configured	driftsättningen saknar den integration som rutten behöver (SMS, objektlagring, …)

details.fields är en JSON-array av fältnamn (t.ex. ["to"]), ibland med extra nycklar som max. Det finns ingen mappning fält→meddelande.

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

Hastighetsgränser

Per klient-IP, på ett fåtal rutter; autentiserad API-trafik i övrigt är inte hastighetsbegränsad. Standardvärden (varje par är varaktig takt och burst, justerbara av operatören):

• Auth — /api/auth/*: 0.5 req/s, burst 20.
• OAuth-leverantör — /oauth/*: 1 req/s, burst 60.
• Public — /api/contact: 0.2 req/s, burst 10.
• Feedback — /api/v1/feedback och /api/v1/feedback/with-screenshot: tre staplade nivåer — en inskickning per 15 s, 10 per timme, 36 per dygn.
• Avatarer — den oautentiserade avatar-omdirigeringen: 20 req/s, burst 200.
• Sensitive — POST-anropen för säkerhetskopiering och återställning: ~0.002 req/s, burst 5.

En överskriden gräns returnerar 429 med en Retry-After-header och det vanliga JSON-felkuvertet, code: "rate_limited".