API-specificatie

De volledige REST-endpoint-referentie. Voor tutorials en voorbeelden, zie de API-gids.

Alles wat een project-member in de web-UI kan doen is hier beschikbaar — de SPA verbruikt dezelfde API. Operaties die de rol owner vereisen zijn gemarkeerd met (owner); al het andere heeft alleen projectlidmaatschap nodig (of, voor reads gemarkeerd met (viewer), een willekeurig toegangsniveau).

Basis

https://eastagiletracker.com/api/v1

https://api.eastagiletracker.com/api/v1 serveert de identieke API. Alle verzoeken en antwoorden zijn JSON, behalve een paar bestandsupload-endpoints die multipart accepteren.

Authenticatie

Elk geauthenticeerd verzoek stuurt een API-sleutel via een van:

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

User-sleutels beginnen met ea_user_. Agent-sleutels beginnen met ea_agent_. Zie API-gids → Twee soorten sleutels.

Endpoints zonder authenticatie: /openapi.json, /docs, de /auth/*-endpoints, en de referentiegegevens-lookups (/story_types, /story_states, /effort_scales, …). /meta is geauthenticeerd — elke geldige sleutel werkt, maar het is niet projectgebonden (een aan een project gebonden agent-sleutel bereikt het ook).

Rollen

Drie niveaus reguleren projectgebonden endpoints:

Niveau	Wie passeert	Typische operaties
viewer	viewer, member, owner	reads (list/get stories, search, analytics)
member	member, owner	alle writes op werkitems (stories, tasks, comments, …)
owner	alleen owner	projectinstellingen, lidmaatschapsbeheer, agent-sleutels, verwijderen, import, auditlog

Een niet-member ontvangt 404 unfound_resource (niet 403) op projectpaden, zodat project-ID’s niet enumereerbaar zijn.

Zelfbeschrijvende endpoints

Methode	Pad	Beschrijving
GET	/openapi.json	De live OpenAPI 3-spec. Zonder authenticatie.
GET	/docs	Swagger UI. Zonder authenticatie.
GET	/meta	Identiteit van de aanroeper (auth.kind/key_id/agent_id/project_id) + de transitiegraaf per story-type. Geauthenticeerd (elke geldige sleutel; niet projectgebonden). Roep dit eerst aan.

Account / identiteit

Deze handelen op de aanroeper en hebben alleen een geldige sleutel nodig (geen projectrol).

Methode	Pad	Beschrijving
POST	/auth/register	Een nieuw account registreren
POST	/auth/login	Inloggen, geeft een sessietoken terug
POST	/auth/logout	Uitloggen
POST	/auth/forgot-password	Een wachtwoordreset-e-mail aanvragen
POST	/auth/reset-password	Een resettoken gebruiken om een nieuw wachtwoord in te stellen
GET	/auth/verify-email	Een e-mailadres verifiëren
POST	/auth/accept-invite/lookup	Een uitnodigingstoken oplossen → e-mail (zonder authenticatie)
POST	/auth/accept-invite	Een projectuitnodiging accepteren (na authenticatie)
GET	/me	Huidig gebruikersprofiel
PUT	/me	Profiel bijwerken
DELETE	/me	Account verwijderen
PUT	/me/password	Wachtwoord wijzigen
PUT	/me/settings	Instellingen bijwerken (thema, notificatievoorkeuren)
POST	/me/avatar	Avatar uploaden (multipart)
POST	/me/api-token/regenerate	Je API-token roteren — maakt bestaande sessies/sleutels ongeldig
GET	/me/api_keys · POST /me/api_keys · DELETE /me/api_keys/{id}	Beheer user- (ea_user_) API-sleutels
GET	/me/activity	Je activiteit over alle projecten
GET	/me/data-export	GDPR-zelfexport van je gegevens
GET	/me/consent · POST /me/consent	Toestemming lezen / registreren ({ consent_type, granted })
GET	/legal/pending · POST /legal/accept	Openstaande clickwrap-documenten / acceptatie registreren
POST	/contact · POST /feedback · POST /feedback/with-screenshot	Contact + in-app feedback

Referentiegegevens (zonder authenticatie)

Seed-lookups die worden gebruikt bij het aanmaken/schatten van stories. Stabiele ID’s.

Methode	Pad	Beschrijving
GET	/story_types	feature, bug, chore, release (+ allow_points)
GET	/story_states	unstarted … accepted, rejected
GET	/effort_scales	beschikbare schattingsschalen
GET	/effort_scales/{scale_id}/values	de puntwaarden in een schaal

Projecten

Methode	Pad	Beschrijving
GET	/projects	Je projecten tonen
POST	/projects	Een project aanmaken
GET	/projects/{id}	Projectdetails ophalen (viewer)
PUT	/projects/{id}	Projectinstellingen bijwerken (owner)
DELETE	/projects/{id}	Een project verwijderen (owner)
GET	/projects/{id}/audit-log	Projectactiviteitenstroom (owner)
GET	/projects/{id}/events	Cursor-gepagineerde eventstream (viewer) — zie Events

Members en agent-sleutels

Methode	Pad	Beschrijving
GET	/projects/{id}/memberships	Members tonen (viewer)
POST	/projects/{id}/memberships	Een member uitnodigen via e-mail (owner)
PUT	/projects/{id}/memberships/{mid}	Rol bijwerken (owner)
DELETE	/projects/{id}/memberships/{mid}	Een member verwijderen (owner)
GET / POST	/projects/{id}/agent_keys	Agent-sleutels tonen / aanmaken (owner)
DELETE	/projects/{id}/agent_keys/{kid}	Een agent-sleutel intrekken (owner)

Stories

Alle story-writes hebben de rol member nodig.

Methode	Pad	Beschrijving
GET	/projects/{id}/stories	Stories tonen (gepagineerd, filterbaar) (viewer)
POST	/projects/{id}/stories	Een story aanmaken
GET	/projects/{id}/stories/{sid}	Eén story ophalen (viewer)
PUT	/projects/{id}/stories/{sid}	Een story bijwerken
DELETE	/projects/{id}/stories/{sid}	Een story verwijderen
POST	/projects/{id}/stories/{sid}/transitions	Toestand wijzigen met validatie
POST	/projects/{id}/stories/bulk_transition	Veel stories (1–100) tegelijk laten overgaan
POST	/projects/{id}/stories/bulk-delete	Veel stories verwijderen
POST	/projects/{id}/stories/bulk-duplicate	Veel stories dupliceren
POST	/projects/{id}/stories/{sid}/duplicate	Eén story dupliceren

Aanmaken (POST …/stories): { "name" (verplicht), "story_type": "feature|bug|chore|release", "description"?, "estimate"?, "current_state"?, "icebox"?, "labels"? }. labels accepteert ["auth"] of [{ "name": "auth" }]; onbekende labels worden aangemaakt. Standaardwaarden: story_type=feature, current_state=unstarted.

Bijwerken (PUT …/stories/{sid}): dezelfde velden, allemaal optioneel, plus "position" (float) en "force_state_change" (bool).

Transition (POST …/transitions): { "to": "<state>", "reason"? }. Het veld is to. Geeft { story_id, state } terug. Ongeldige beweging → 422 invalid_transition met details: { from, to, allowed }.

Bulk transition (POST …/bulk_transition): { "story_ids": [int,…] (1–100), "to": "<state>", "reason"? }. Elke story wordt onafhankelijk beoordeeld; geeft { results: [ { id, status: "ok" } | { id, status: "failed", error } ] } terug.

Story-subresources

Alle member. List/GET op de meeste is (viewer).

Methode	Pad	Body / notities
GET / POST	/projects/{id}/stories/{sid}/tasks · PUT/DELETE …/tasks/{tid}	{ description (of task_desc), complete?, task_order? }
GET / POST	/projects/{id}/stories/{sid}/comments · PUT/DELETE …/comments/{cid}	{ text (of comment_text) } of { 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? } — laat beide weg om de aanroeper toe te voegen
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 per stuk); list is (viewer)

Labels

member voor writes, (viewer) voor reads.

Methode	Pad	Beschrijving
GET / POST	/projects/{id}/labels	Een label tonen / aanmaken
PUT / DELETE	/projects/{id}/labels/{lid}	Een label bijwerken / verwijderen
POST	/projects/{id}/labels/{lid}/archive	Een label archiveren (zacht verbergen)

Iteraties

Methode	Pad	Beschrijving
GET	/projects/{id}/iterations	Iteraties tonen (member)
POST	/projects/{id}/iterations	Een handmatige iteratie aanmaken (owner)
DELETE	/projects/{id}/iterations/{itid}	Een iteratie verwijderen (owner)

Zoeken, analytics, metrics, voorkeuren

Methode	Pad	Beschrijving
GET	/projects/{id}/search?query=…	Zoeken met filtersyntaxis (viewer) — zie Gids
GET	/projects/{id}/analytics/{overview,iteration,releases,activity,cycle-time,projections}	Analytics (viewer). Inzoomen op iteratie neemt ?iteration_id=
GET	/projects/{id}/metrics/{velocity,burndown,story-types}	Metrics (viewer)
GET / PUT	/projects/{id}/preferences	Je bordvoorkeuren voor dit project (member)

Events

Methode	Pad	Beschrijving
GET	/projects/{id}/events	Cursor-gepagineerde eventstream (viewer)

Query-parameters: since=<event_id>, types=story.created,story.transitioned,comment.created,…, limit=, cursor=. Het antwoord bevat next_cursor. Geef het laatste event_id dat je zag door als since om verder te gaan.

Import (owner)

Methode	Pad	Beschrijving
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>

Voor interactieve UI-afstandsbediening ({ "action": "get_state", "id": "req-1" }). Geen datakanaal — alle reads/writes gaan via REST. Alleen single-instance; niet uitgewaaierd over replica’s.

Idempotentie

Write-endpoints (POST, PUT, DELETE) accepteren een Idempotency-Key-header. Dezelfde sleutel + dezelfde body speelt het gecachte antwoord opnieuw af (venster van 24 uur); dezelfde sleutel + een andere body geeft 409 idempotency_conflict terug. Niet toegepast op GET/HEAD/OPTIONS, /auth/* of /attachments-paden. 5xx-antwoorden worden nooit gecacht — een retry bereikt de handler.

Paginering

List-endpoints accepteren cursor=<opaque> en limit=<n≤200>. Indien ingesteld is het antwoord { "items": [...], "next_cursor": "<str|null>" }; geef next_cursor terug om te pagineren. Sommige lijsten geven ook een X-Tracker-Pagination-Total-header terug.

Veldprojectie

List-endpoints accepteren fields= (komma-gescheiden) om alleen specifieke velden terug te geven. story_id wordt altijd opgenomen; een onbekende veldnaam geeft 400 validation_failed terug met de schendende namen in details.fields.

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

Foutformaat

Elke JSON-fout heeft code en error; sommige voegen details toe:

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

Status	code	Wanneer
400	invalid_parameter	foute invoer; bericht in error, geen details (meeste validatie: blank/lengte/null-byte/e-mail)
400	validation_failed	gestructureerde invoerfout; details.fields is een array van schendende veldnamen
401	unauthenticated	ontbrekend/ongeldig token
403	unauthorized_operation	geauthenticeerd maar onvoldoende rol
404	unfound_resource	niet gevonden — ook teruggegeven aan niet-members
409	conflict	resourceconflict (bijv. duplicaat)
409	idempotency_conflict	Idempotency-Key hergebruikt met een andere body
422	invalid_transition	ongeldige toestandsbeweging; details draagt { from, to, allowed }
500	internal_error	serverfout — generiek bericht; veilig om opnieuw te proberen

details.fields is een JSON-array van veldnamen (bijv. ["to"]), soms met extra sleutels zoals max. Er is geen veld→bericht-map.

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

Rate limits

Per sleutel (per IP voor endpoints zonder authenticatie), GCRA token bucket:

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

Een overschreden limiet geeft 429 Too Many Requests terug met een Retry-After-header en een plat-tekst-body (niet de JSON-foutenvelop).