API-specifikation

Den komplette REST-endpoint-reference. For tutorials og eksempler, se API-guiden.

Alt, hvad et projekt-member kan gøre i webgrænsefladen, er tilgængeligt her — SPA’en forbruger dette samme API. Operationer, der kræver owner-rollen, er markeret (owner); alt andet kræver kun projektmedlemskab (eller, for læsninger markeret (viewer), ethvert adgangsniveau).

Base

https://eastagiletracker.com/api/v1

https://api.eastagiletracker.com/api/v1 serverer det identiske API. Alle requests og responses er JSON, undtagen et par filupload-endpoints, der accepterer multipart.

Autentificering

Hver autentificeret request sender en API-nøgle via en af:

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

Brugernøgler starter med ea_user_. Agent-nøgler starter med ea_agent_. Se API-guide → To slags nøgler.

Uautentificerede endpoints: /openapi.json, /docs, /auth/*-endpoints og opslag af referencedata (/story_types, /story_states, /effort_scales, …). /meta er autentificeret — enhver gyldig nøgle virker, men det er ikke projektafgrænset (en projektbundet agent-nøgle når det også).

Roller

Tre niveauer afgrænser projektafgrænsede endpoints:

Niveau	Hvem passerer	Typiske operationer
viewer	viewer, member, owner	læsninger (list/get stories, søgning, analyser)
member	member, owner	alle skrivninger af arbejdsenheder (stories, tasks, kommentarer, …)
owner	kun owner	projektindstillinger, medlemskabsadministration, agent-nøgler, sletning, import, revisionslog

Et ikke-medlem modtager 404 unfound_resource (ikke 403) på projekt-paths, så projekt-ID’er ikke kan opregnes.

Selvbeskrivende endpoints

Metode	Path	Beskrivelse
GET	/openapi.json	Den live OpenAPI 3-specifikation. Uautentificeret.
GET	/docs	Swagger UI. Uautentificeret.
GET	/meta	Kalderidentitet (auth.kind/key_id/agent_id/project_id) + overgangsgrafen pr. story-type. Autentificeret (enhver gyldig nøgle; ikke projektafgrænset). Kald dette først.

Konto / identitet

Disse handler på kalderen og kræver kun en gyldig nøgle (ingen projektrolle).

Metode	Path	Beskrivelse
POST	/auth/register	Registrer en ny konto
POST	/auth/login	Log ind, returnerer et session-token
POST	/auth/logout	Log ud
POST	/auth/forgot-password	Anmod om en e-mail til nulstilling af adgangskode
POST	/auth/reset-password	Brug et nulstillings-token til at sætte en ny adgangskode
GET	/auth/verify-email	Bekræft en e-mailadresse
POST	/auth/accept-invite/lookup	Slå et invitations-token op → e-mail (uautentificeret)
POST	/auth/accept-invite	Accepter en projektinvitation (efter autentificering)
GET	/me	Den aktuelle brugers profil
PUT	/me	Opdater profil
DELETE	/me	Slet konto
PUT	/me/password	Skift adgangskode
PUT	/me/settings	Opdater indstillinger (tema, notifikationspræferencer)
POST	/me/avatar	Upload avatar (multipart)
POST	/me/api-token/regenerate	Rotér dit API-token — ugyldiggør eksisterende sessioner/nøgler
GET	/me/api_keys · POST /me/api_keys · DELETE /me/api_keys/{id}	Administrér bruger-API-nøgler (ea_user_)
GET	/me/activity	Din aktivitet på tværs af alle projekter
GET	/me/data-export	GDPR-selveksport af dine data
GET	/me/consent · POST /me/consent	Læs / registrer samtykke ({ consent_type, granted })
GET	/legal/pending · POST /legal/accept	Ventende clickwrap-dokumenter / registrer accept
POST	/contact · POST /feedback · POST /feedback/with-screenshot	Kontakt + in-app-feedback

Referencedata (uautentificeret)

Seed-opslag brugt ved oprettelse/estimering af stories. Stabile ID’er.

Metode	Path	Beskrivelse
GET	/story_types	feature, bug, chore, release (+ allow_points)
GET	/story_states	unstarted … accepted, rejected
GET	/effort_scales	tilgængelige estimeringsskalaer
GET	/effort_scales/{scale_id}/values	point-værdierne i en skala

Projekter

Metode	Path	Beskrivelse
GET	/projects	List dine projekter
POST	/projects	Opret et projekt
GET	/projects/{id}	Hent projektdetaljer (viewer)
PUT	/projects/{id}	Opdater projektindstillinger (owner)
DELETE	/projects/{id}	Slet et projekt (owner)
GET	/projects/{id}/audit-log	Projektaktivitetsstrøm (owner)
GET	/projects/{id}/events	Cursor-pagineret hændelsesstrøm (viewer) — se Events

Medlemmer og agent-nøgler

Metode	Path	Beskrivelse
GET	/projects/{id}/memberships	List medlemmer (viewer)
POST	/projects/{id}/memberships	Inviter et medlem via e-mail (owner)
PUT	/projects/{id}/memberships/{mid}	Opdater rolle (owner)
DELETE	/projects/{id}/memberships/{mid}	Fjern et medlem (owner)
GET / POST	/projects/{id}/agent_keys	List / udsted agent-nøgler (owner)
DELETE	/projects/{id}/agent_keys/{kid}	Tilbagekald en agent-nøgle (owner)

Stories

Alle story-skrivninger kræver member-rollen.

Metode	Path	Beskrivelse
GET	/projects/{id}/stories	List stories (pagineret, filtrerbar) (viewer)
POST	/projects/{id}/stories	Opret en story
GET	/projects/{id}/stories/{sid}	Hent én story (viewer)
PUT	/projects/{id}/stories/{sid}	Opdater en story
DELETE	/projects/{id}/stories/{sid}	Slet en story
POST	/projects/{id}/stories/{sid}/transitions	Skift tilstand med validering
POST	/projects/{id}/stories/bulk_transition	Skift tilstand på mange stories (1–100) på én gang
POST	/projects/{id}/stories/bulk-delete	Slet mange stories
POST	/projects/{id}/stories/bulk-duplicate	Dublér mange stories
POST	/projects/{id}/stories/{sid}/duplicate	Dublér én story

Create (POST …/stories): { "name" (required), "story_type": "feature|bug|chore|release", "description"?, "estimate"?, "current_state"?, "icebox"?, "labels"? }. labels accepterer ["auth"] eller [{ "name": "auth" }]; ukendte labels oprettes. Standardværdier: story_type=feature, current_state=unstarted.

Update (PUT …/stories/{sid}): samme felter, alle valgfri, plus "position" (float) og "force_state_change" (bool).

Transition (POST …/transitions): { "to": "<state>", "reason"? }. Feltet er to. Returnerer { story_id, state }. Ulovligt træk → 422 invalid_transition med details: { from, to, allowed }.

Bulk transition (POST …/bulk_transition): { "story_ids": [int,…] (1–100), "to": "<state>", "reason"? }. Hver story bedømmes uafhængigt; returnerer { results: [ { id, status: "ok" } | { id, status: "failed", error } ] }.

Story-underressourcer

Alle member. List/GET på de fleste er (viewer).

Metode	Path	Body / noter
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? } — udelad begge for at tilføje kalderen
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 hver); list er (viewer)

Labels

member for skrivninger, (viewer) for læsninger.

Metode	Path	Beskrivelse
GET / POST	/projects/{id}/labels	List / opret en label
PUT / DELETE	/projects/{id}/labels/{lid}	Opdater / slet en label
POST	/projects/{id}/labels/{lid}/archive	Arkivér (skjul blødt) en label

Iterationer

Metode	Path	Beskrivelse
GET	/projects/{id}/iterations	List iterationer (member)
POST	/projects/{id}/iterations	Opret en manuel iteration (owner)
DELETE	/projects/{id}/iterations/{itid}	Slet en iteration (owner)

Søgning, analyser, metrikker, præferencer

Metode	Path	Beskrivelse
GET	/projects/{id}/search?query=…	Søgning med filtersyntaks (viewer) — se Guide
GET	/projects/{id}/analytics/{overview,iteration,releases,activity,cycle-time,projections}	Analyser (viewer). Iterationsdetaljer tager ?iteration_id=
GET	/projects/{id}/metrics/{velocity,burndown,story-types}	Metrikker (viewer)
GET / PUT	/projects/{id}/preferences	Dine board-præferencer for dette projekt (member)

Events

Metode	Path	Beskrivelse
GET	/projects/{id}/events	Cursor-pagineret hændelsesstrøm (viewer)

Query-parametre: since=<event_id>, types=story.created,story.transitioned,comment.created,…, limit=, cursor=. Svaret inkluderer next_cursor. Angiv det sidste event_id, du så, som since for at genoptage.

Import (owner)

Metode	Path	Beskrivelse
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>

Til interaktiv fjernstyring af UI ({ "action": "get_state", "id": "req-1" }). Ikke en datakanal — alle læsninger/skrivninger går gennem REST. Kun enkelt-instans; fanes ikke ud på tværs af replikaer.

Idempotens

Skrive-endpoints (POST, PUT, DELETE) accepterer en Idempotency-Key-header. Samme nøgle + samme body genafspiller det cachede svar (24-timers vindue); samme nøgle + en anden body returnerer 409 idempotency_conflict. Anvendes ikke på GET/HEAD/OPTIONS, /auth/* eller /attachments-paths. 5xx-svar caches aldrig — et nyt forsøg når handleren.

Paginering

List-endpoints accepterer cursor=<opaque> og limit=<n≤200>. Når sat, er svaret { "items": [...], "next_cursor": "<str|null>" }; angiv next_cursor tilbage for at bladre. Nogle lister returnerer også en X-Tracker-Pagination-Total-header.

Feltprojektion

List-endpoints accepterer fields= (kommasepareret) for kun at returnere bestemte felter. story_id inkluderes altid; et ukendt feltnavn returnerer 400 validation_failed med de krænkende navne i details.fields.

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

Fejlformat

Hver JSON-fejl har code og error; nogle tilføjer details:

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

Status	code	Hvornår
400	invalid_parameter	dårligt input; besked i error, ingen details (de fleste valideringer: blank/længde/null-byte/e-mail)
400	validation_failed	struktureret input-fejl; details.fields er et array af krænkende feltnavne
401	unauthenticated	manglende/ugyldigt token
403	unauthorized_operation	autentificeret, men utilstrækkelig rolle
404	unfound_resource	ikke fundet — returneres også til ikke-medlemmer
409	conflict	ressourcekonflikt (f.eks. dublet)
409	idempotency_conflict	Idempotency-Key genbrugt med en anden body
422	invalid_transition	ulovligt tilstandsskifte; details bærer { from, to, allowed }
500	internal_error	serverfejl — generisk besked; sikker at prøve igen

details.fields er et JSON-array af feltnavne (f.eks. ["to"]), nogle gange med ekstra nøgler som max. Der er ingen felt→besked-afbildning.

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

Rate limits

Pr. nøgle (pr. IP for uautentificerede endpoints), GCRA token bucket:

• Auth — /auth/*: 0,5 req/s, burst 20.
• Public — /contact, /feedback: 0,2 req/s, burst 10.
• Sensitive — nulstilling af adgangskode: ~0,002 req/s, burst 5.

En overskredet grænse returnerer 429 Too Many Requests med en Retry-After-header og en ren tekst-body (ikke JSON-fejlomslaget).