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 ägarrollen är markerade (owner); allt annat kräver enbart projektmedlemskap (eller, för läsningar markerade (viewer), vilken åtkomstnivå som helst).

Bas

https://eastagiletracker.com/api/v1

https://api.eastagiletracker.com/api/v1 betjänar det identiska API:et. Alla requests och svar är JSON, förutom några fil-uppladdnings-endpoints som accepterar multipart.

Autentisering

Varje autentiserad request skickar en API-nyckel via något av:

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

Användarnycklar börjar med ea_user_. Agentnycklar börjar med ea_agent_. Se API-guide → Två sorters nycklar.

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

Roller

Tre nivåer styr projektavgränsade endpoints:

Nivå	Vem passerar	Typiska operationer
viewer	viewer, member, owner	läsningar (lista/hämta stories, sökning, analys)
member	member, owner	alla skrivningar av arbetsposter (stories, tasks, kommentarer, …)
owner	endast owner	projektinställningar, medlemshantering, agentnycklar, radering, import, granskningslogg

En icke-medlem får 404 unfound_resource (inte 403) på 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. 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.

Konto / identitet

Dessa agerar på anroparen och kräver enbart en giltig nyckel (ingen projektroll).

Method	Path	Beskrivning
POST	/auth/register	Registrera ett nytt konto
POST	/auth/login	Logga in, returnerar en sessions-token
POST	/auth/logout	Logga ut
POST	/auth/forgot-password	Begär ett e-postmeddelande för återställning av lösenord
POST	/auth/reset-password	Använd en återställnings-token för att sätta ett nytt lösenord
GET	/auth/verify-email	Verifiera en e-postadress
POST	/auth/accept-invite/lookup	Slå upp en inbjudnings-token → e-post (oautentiserad)
POST	/auth/accept-invite	Acceptera en projektinbjudan (efter autentisering)
GET	/me	Aktuell användarprofil
PUT	/me	Uppdatera profil
DELETE	/me	Radera konto
PUT	/me/password	Byt lösenord
PUT	/me/settings	Uppdatera inställningar (tema, notisinställningar)
POST	/me/avatar	Ladda upp avatar (multipart)
POST	/me/api-token/regenerate	Rotera din API-token — ogiltigförklarar befintliga sessioner/nycklar
GET	/me/api_keys · POST /me/api_keys · DELETE /me/api_keys/{id}	Hantera användar-API-nycklar (ea_user_)
GET	/me/activity	Din aktivitet över alla projekt
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
POST	/contact · POST /feedback · POST /feedback/with-screenshot	Kontakt + feedback i appen

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

Projekt

Method	Path	Beskrivning
GET	/projects	Lista dina projekt
POST	/projects	Skapa ett projekt
GET	/projects/{id}	Hämta projektdetaljer (viewer)
PUT	/projects/{id}	Uppdatera projektinställningar (owner)
DELETE	/projects/{id}	Radera ett projekt (owner)
GET	/projects/{id}/audit-log	Projektets aktivitetsström (owner)
GET	/projects/{id}/events	Cursor-paginerad händelseström (viewer) — se Händelser

Medlemmar och agentnycklar

Method	Path	Beskrivning
GET	/projects/{id}/memberships	Lista medlemmar (viewer)
POST	/projects/{id}/memberships	Bjud in en medlem via e-post (owner)
PUT	/projects/{id}/memberships/{mid}	Uppdatera roll (owner)
DELETE	/projects/{id}/memberships/{mid}	Ta bort en medlem (owner)
GET / POST	/projects/{id}/agent_keys	Lista / skapa agentnycklar (owner)
DELETE	/projects/{id}/agent_keys/{kid}	Återkalla en agentnyckel (owner)

Stories

Alla story-skrivningar kräver member-rollen.

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/bulk_transition	Transitionera många stories (1–100) på en gång
POST	/projects/{id}/stories/bulk-delete	Radera många stories
POST	/projects/{id}/stories/bulk-duplicate	Duplicera många stories
POST	/projects/{id}/stories/{sid}/duplicate	Duplicera en story

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

Transition (POST …/transitions): { "to": "<state>", "reason"? }. 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>", "reason"? }. 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).

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) } or { 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? } — 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}	{ name }
GET / POST	/projects/{id}/stories/{sid}/attachments (+ /json) · DELETE …/attachments/{aid}	multipart-uppladdning (≤ 2 GB vardera); listning är (viewer)

Etiketter

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

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

Iterationer

Method	Path	Beskrivning
GET	/projects/{id}/iterations	Lista iterationer (member)
POST	/projects/{id}/iterations	Skapa en manuell iteration (owner)
DELETE	/projects/{id}/iterations/{itid}	Radera en iteration (owner)

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

Method	Path	Beskrivning
GET	/projects/{id}/search?query=…	Sökning med filtersyntax (viewer) — se Guiden
GET	/projects/{id}/analytics/{overview,iteration,releases,activity,cycle-time,projections}	Analys (viewer). Iterations-fördjupning tar ?iteration_id=
GET	/projects/{id}/metrics/{velocity,burndown,story-types}	Mätvärden (viewer)
GET / PUT	/projects/{id}/preferences	Dina board-inställningar för detta projekt (member)

Händelser

Method	Path	Beskrivning
GET	/projects/{id}/events	Cursor-paginerad händelseström (viewer)

Query-parametrar: since=<event_id>, types=story.created,story.transitioned,comment.created,…, limit=, cursor=. Svaret inkluderar next_cursor. Skicka det senaste event_id du sett som since för att återuppta.

Import (owner)

Method	Path	Beskrivning
POST	/projects/{id}/import (+ /json)	Multipart-uppladdning. source= ∈ pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json.

WebSocket

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

För interaktiv fjärrstyrning av gränssnittet ({ "action": "get_state", "id": "req-1" }). Inte en datakanal — alla läsningar/skrivningar går via REST. Endast en instans; inte utfläkt över repliker.

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. Tillämpas inte på GET/HEAD/OPTIONS, /auth/* eller /attachments-sökvägar. 5xx-svar cachas aldrig — ett omförsök når hanteraren.

Paginering

List-endpoints accepterar cursor=<opaque> och limit=<n≤200>. När de är satta är svaret { "items": [...], "next_cursor": "<str|null>" }; skicka tillbaka next_cursor för att bläddra. Vissa listor returnerar också en X-Tracker-Pagination-Total-header.

Fältprojektion

List-endpoints accepterar fields= (kommaseparerad) för att returnera enbart specifika fält. story_id inkluderas alltid; 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, inga details (de flesta valideringar: blank/längd/null-byte/e-post)
400	validation_failed	strukturerat indatafel; details.fields är en array av felande fältnamn
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
422	invalid_transition	otillåten tillståndsförflyttning; details bär { from, to, allowed }
500	internal_error	serverfel — generiskt meddelande; säkert att försöka igen

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 nyckel (per IP för oautentiserade endpoints), GCRA token-bucket:

• Auth — /auth/*: 0.5 req/s, burst 20.
• Public — /contact, /feedback: 0.2 req/s, burst 10.
• Sensitive — återställning av lösenord: ~0.002 req/s, burst 5.

En överskriden gräns returnerar 429 Too Many Requests med en Retry-After-header och en body i klartext (inte JSON-felkuvertet).