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 manager vereisen zijn gemarkeerd met (manager); al het andere heeft alleen projectlidmaatschap nodig (of, voor reads gemarkeerd met (viewer), een willekeurig toegangsniveau). De tabellen hieronder noemen elke routegroep die de server aanbiedt; de groepen die in één regel zijn samengevat, worden volledig beschreven in de live openapi.json.

Basis

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

De API heeft een eigen host: eastagiletracker.com serveert de webapp en beantwoordt /api/v1/… met 404. Alle verzoeken en antwoorden zijn JSON, behalve een paar bestandsupload-endpoints die multipart accepteren.

Twee groepen staan één niveau hoger, onder /api in plaats van /api/v1: het authenticatiegedeelte (/api/auth/*) en het openbare contactformulier (/api/contact). Hun /api/v1/…-varianten geven 404 terug.

Authenticatie

Elk geauthenticeerd verzoek stuurt inloggegevens via een van:

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

User-sleutels beginnen met ea_user_, agent-sleutels met ea_agent_, en MCP-access-tokens met ea_mcp_. Zie API-gids → Drie soorten inloggegevens.

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

Rollen

Vier niveaus reguleren projectgebonden endpoints:

Niveau	Wie passeert	Typische operaties
public viewer	iedereen, op een project met openbare zichtbaarheid	reads van het bord: stories, iteraties, zoeken, story- en epic-activiteit (met actorgegevens weggelakt)
viewer	viewer, member, manager	reads (stories tonen/ophalen, zoeken, metrics, lijst met exportformaten)
member	member, manager	alle writes op werkitems (stories, taken, reacties, …), de eventstream
manager	alleen manager	projectinstellingen, lidmaatschapsbeheer, agent-sleutels, verwijderen, import, exportdownloads, back-ups, auditlog

Agents hebben dezelfde rollen als members — viewer, member of manager — begrensd op de rol van het lid dat de sleutel heeft aangemaakt. Een niet-member ontvangt 404 unfound_resource (niet 403) op paden van privéprojecten, zodat project-ID’s niet enumereerbaar zijn.

Zelfbeschrijvende endpoints

Methode	Pad	Beschrijving
GET	/openapi.json	De live OpenAPI 3-spec, inclusief request-bodies. 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.
GET	/api/health · /api/config	Liveness, en de openbare configuratie van de deployment (single-org-modus, ingeschakelde optionele functies, naam van de instantie). Zonder authenticatie, buiten /v1.

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

Sessie-endpoints, zonder authenticatie tenzij anders vermeld. De SPA gebruikt deze; scripts gebruiken normaal gesproken een API-sleutel.

Methode	Pad	Beschrijving
POST	/auth/register	Een nieuw account registreren — beschermd door reCAPTCHA; het account doorloopt daarna de sms-controle
POST	/auth/sms/challenge · /auth/sms/status · /auth/sms/bypass	De sms-code voor registratie versturen / controleren (bypass is afgeschermd door de beheerder)
GET	/auth/config	Welke inlogmethoden de deployment aanbiedt
POST	/auth/login	Inloggen met e-mail + wachtwoord; geeft een sessie-JWT of een TOTP-uitdaging terug
POST	/auth/login/totp	Een aanmelding afronden met een authenticatorcode of een herstelcode
POST	/auth/passkey/login/start · /auth/passkey/login/finish	Wachtwoordloos inloggen met WebAuthn
GET	/auth/oauth/github/start · /auth/oauth/github/callback · /auth/oauth/google/start · /auth/oauth/google/callback · POST /auth/oauth/exchange	OAuth-aanmelding met GitHub of Google
POST	/auth/refresh · /auth/refresh/revoke	Het refresh-token roteren / intrekken
POST	/auth/logout	Uitloggen (geauthenticeerd; trekt het refresh-token van deze sessie in)
POST	/auth/forgot-password · /auth/reset-password	Een reset-e-mail aanvragen / het resettoken gebruiken
POST	/auth/accept-invite/lookup · /auth/accept-invite	Een uitnodigingstoken herleiden → e-mail / de projectuitnodiging accepteren (na authenticatie)
POST	/auth/oauth/link/preview · …/link/confirm · /auth/oauth/merge/preview · …/merge/confirm	Een GitHub- of Google-account aan een bestaand account koppelen, of twee accounts samenvoegen
POST	/auth/email_addresses/primary/preview · …/primary/confirm	Een wijziging van het primaire e-mailadres afronden via de bevestigingslink uit de e-mail

Account / identiteit

Deze handelen op de aanroeper en hebben geen projectrol nodig. Ze vereisen een lid-identiteit — een agent-sleutel krijgt 401 (agents gebruiken /agent/me). Aanroepen die inloggegevens wijzigen — wachtwoord, TOTP, passkeys, account verwijderen, een e-mailwijziging, token opnieuw genereren — vereisen een browsersessie; een API-sleutel krijgt 403.

Methode	Pad	Beschrijving
GET	/me	Huidig gebruikersprofiel
PUT	/me	Profiel bijwerken
DELETE	/me	Account verwijderen — geweigerd zolang je de enige owner bent van een organisatie of van een project met andere leden
GET	/me/deletion-impact	Wat het verwijderen van het account zou weghalen en wat het blokkeert
PUT	/me/password	Wachtwoord wijzigen
PUT	/me/settings	Instellingen bijwerken (thema, notificatievoorkeuren)
POST / DELETE	/me/avatar	Je avatar uploaden (multipart) / verwijderen
POST	/me/api-token/regenerate	Elke sessie uitloggen en een nieuw sessietoken teruggeven; API-sleutels blijven ongemoeid
GET / POST	/me/email_addresses · GET …/email_addresses/offers · PUT …/email_addresses/primary	Je e-mailadressen; het adres van een gekoppelde provider als alternatief adres overnemen; een wijziging van het primaire adres aanvragen (bevestigd per e-mail)
GET	/me/oauth_identities · DELETE …/oauth_identities/{provider} · POST …/oauth_identities/{provider}/link	Gekoppelde inlogaccounts (GitHub, Google): tonen, ontkoppelen, een koppeling starten
GET	/me/api_keys · POST /me/api_keys · DELETE /me/api_keys/{id}	Beheer user- (ea_user_) API-sleutels
GET	/me/totp · POST /me/totp/setup · /me/totp/verify · /me/totp/disable	Inschrijving voor tweestapsverificatie (TOTP); verify geeft de herstelcodes eenmalig terug
GET	/me/passkeys · POST /me/passkeys/register/start · /me/passkeys/register/finish · DELETE /me/passkeys/{credential_id}	Passkeys registreren en verwijderen
GET	/me/oauth_grants · DELETE /me/oauth_grants/{grant_id}	Connected apps — de MCP-clients en OAuth-apps die je hebt geautoriseerd
GET	/me/activity	Je activiteit over alle projecten
GET	/me/stories	Stories waarvan je owner of aanvrager bent, of die je volgt, over elk project dat het token kan bereiken — role=owned|requested|following, state=, cursor= / limit= (max 200)
GET	/me/mentions · POST /me/mentions/{mention_id}/ack	De inbox met @-vermeldingen (unacked=true om te filteren) en bevestiging — ook opgenomen in de meldingenfeed hieronder
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
GET / PUT	/agent/me	De eigen identiteit en het profiel van een agent-sleutel, leesbaar en bewerkbaar door de agent (de tegenhanger van /me aan agentzijde)
POST	/api/contact · /api/v1/feedback · /api/v1/feedback/with-screenshot	Contact + in-app-feedback; rate-limited per IP-adres

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
GET	/priority_scales · /priority_scales/{scale_id}/values	de prioriteitsschalen en hun waarden (priority_id op een story verwijst hiernaar)

Organisaties

Alleen op de gehoste dienst — een self-hosted installatie draait in single-organization-modus en biedt deze niet aan (behalve de lijst met organisaties). Rollen zijn organisatierollen: owner, admin, member.

Methode	Pad	Beschrijving
GET / POST	/organizations	Je organisaties tonen / er een aanmaken
GET / PUT / DELETE	/organizations/{oid}	Lezen, hernoemen (naam + slug; owner of admin), verwijderen
GET / POST	/organizations/{oid}/memberships · PUT / DELETE …/memberships/{member_id}	Leden en uitnodigingen; uitnodigingen hebben een rolplafond (nooit hoger dan dat van de aanroeper; owner wordt nooit uitgenodigd)
POST	/organizations/{oid}/memberships/bulk-role · …/memberships/bulk-remove	Wijzig de rol van maximaal 200 leden tegelijk of verwijder ze. Alles of niets: een batch die de laatste owner zou verwijderen of een project zonder eigenaar zou achterlaten, wordt in zijn geheel geweigerd; met reassign_confirmed word je in plaats daarvan eigenaar van die projecten
DELETE	/organizations/{oid}/invitations/{invitation_id}	Een openstaande uitnodiging intrekken
POST	/organizations/{oid}/transfer-ownership	De rol owner overdragen aan een ander lid
GET	/organization-invitations/{token} · POST …/{token}/accept	Een per e-mail ontvangen organisatie-uitnodiging herleiden / accepteren
GET	/organizations/{oid}/export · POST …/export/jobs · GET …/export/jobs/{job_id} · …/export/jobs/{job_id}/download	Organisatie-export, alleen voor owners: een zip met een SQL-dump en elke bijlage, uitgevoerd als job

Projecten

Methode	Pad	Beschrijving
GET	/projects	Je projecten tonen (limit ≤ 200)
POST	/projects	Een project aanmaken
GET	/projects/{id}	Projectdetails ophalen (viewer)
PUT	/projects/{id}	Projectinstellingen bijwerken (manager)
DELETE	/projects/{id}	Een project verwijderen (manager)
POST / DELETE	/projects/{id}/pin	Het project vastzetten / losmaken in je projectlijst
POST	/projects/{id}/transfer-organization	Het project naar een andere organisatie verplaatsen — de aanroeper moet Beheerder van het project zijn en org-owner of -admin van de doelorganisatie
POST	/projects/{id}/slack/test	Een testbericht naar de Slack-feed van het project sturen (manager)
GET / POST	/projects/{id}/showcase_claim_eligibility · /projects/{id}/showcase_claim · /projects/{id}/showcase_seed	Openbare showcaseprojecten: controleren of je er een kunt claimen, het claimen, het vullen (vullen is voor productbeheerders; ieder ander krijgt 404)
GET	/projects/{id}/audit-log	Audit-log lezen — projecthistorie plus activiteit per story / per epic via surface=; toegang verschilt per surface, zie hieronder
GET	/projects/{id}/events	Cursor-gepagineerde eventstream (member) — zie Events

Query-parameters van de audit-log: event_type= (één type of kommagescheiden lijst), limit= (standaard 50, begrensd op 1000), before= (keyset-cursor <ISO-8601>|<audit_id> — geef de next_cursor van de vorige pagina door), surface= (project_history, story_activities, epic_activities), target_id= (het story-/epic-id — verplicht wanneer surface=story_activities of epic_activities). Toegang: de ongefilterde log is (manager); surface=project_history is (viewer), met de e-mailadressen van leden weggelakt wanneer het project die verbergt; story_activities / epic_activities zijn leesbaar voor elk projectlid, en anoniem op publieke projecten met de PII van de actor weggelakt.

Members, agents en agent-sleutels

Methode	Pad	Beschrijving
GET	/projects/{id}/memberships	Members tonen (viewer)
POST	/projects/{id}/memberships	Een member uitnodigen via e-mail (manager)
PUT	/projects/{id}/memberships/{mid}	Rol bijwerken (manager)
DELETE	/projects/{id}/memberships/{mid}	Een member verwijderen (manager)
POST	/projects/{id}/memberships/bulk-role · …/memberships/bulk-remove	De rol van veel leden tegelijk wijzigen, of ze verwijderen (manager)
GET	/projects/{id}/addable-members · POST /projects/{id}/members/add-existing	Leden van de organisatie die nog niet in het project zitten / er een toevoegen zonder uitnodiging per e-mail — (manager) en een org-owner of -admin
POST	/projects/{id}/members/join	Een owner of admin van de organisatie treedt als manager toe tot een project in zijn organisatie, of promoveert zichzelf tot manager (de actie Make me owner in de projectlijst)
GET / POST	/projects/{id}/agent_keys	Agent-sleutels tonen (manager) / aanmaken — mensen wier rol in het creator-roles-beleid van het project staat; agent-sleutels kunnen geen sleutels aanmaken
PUT / DELETE	/projects/{id}/agent_keys/{kid}	De naam, rol of response hints van een sleutel bewerken / hem intrekken (manager)
GET	/projects/{id}/agent_keys/onboarding	De onboarding-bundel: prompts en configuratiebestanden voor de gangbare agent-clients
GET	/projects/{id}/agents · GET / PUT / DELETE /projects/{id}/agents/{aid}	De agents van het project en hun profielen (naam, initialen, beschrijving, kleur); DELETE trekt de agent en al zijn sleutels in — een manager of de maker van de agent
POST	/projects/{id}/agents/{aid}/rotate-key · /projects/{id}/agents/{aid}/avatar	De sleutel van een agent roteren (identiteit en historie blijven behouden) / de avatar uploaden

Stories

Alle story-writes hebben de rol member nodig. Een story aanmaken met teruggedateerde datums, importherkomst (import_source / import_external_id) of externe owners of requester vereist (manager).

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/{sid}/reject · /projects/{id}/stories/{sid}/restart	Een opgeleverde story afwijzen / een afgewezen story terugzetten op started (rejected is een eindtoestand voor /transitions)
POST	/projects/{id}/stories/{sid}/archive · /projects/{id}/stories/{sid}/unarchive	Eén story archiveren / dearchiveren
POST	/projects/{id}/stories/bulk-unarchive	Veel stories dearchiveren
POST	/projects/{id}/stories/bulk_transition	Veel stories (1–100) tegelijk laten overgaan
POST	/projects/{id}/stories/bulk-archive · bulk-delete · bulk-duplicate · bulk-move	Veel stories archiveren, verwijderen, dupliceren of verplaatsen (naar een paneel / positie)
POST	/projects/{id}/stories/{sid}/duplicate	Eén story dupliceren
POST / DELETE	/projects/{id}/stories/{sid}/epics · …/epics/{eid}	Het epic-lidmaatschap van de story
GET	/short-links/{code} · /story-references	Een /s/<code>-short-link herleiden tot zijn story / tot 100 referenties — codes= (kommagescheiden short-link-codes) en ids= (kommagescheiden project_id:story_id) — herleiden tot de stories die de aanroeper kan lezen

Queryparameters voor de story-lijst: archived= (exclude standaard / include / only — het archieffilter met drie standen; vervangt het verouderde include_archived=true, nu een alias voor archived=include), include_done=true (laat Done-panelstories toe die op eerdere iteraties zijn bevroren, standaard uitgesloten). Paginering (cursor= / limit= / offset=) en spaarzame veldensets (fields=) volgen Paginering en Veldprojectie.

Aanmaken (POST …/stories): { "name" (required), "story_type": "feature|bug|chore|release", "description"?, "estimate"?, "current_state"?, "icebox"?, "labels"? }. estimate is het label van de schaalwaarde als string ("3", "13"); een JSON-getal wordt geweigerd. 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), "force_state_change" (bool) en "expected_version" (geheel getal, de version van de story — het opslaan van een beschrijving wordt geweigerd met 409 stale_write als de beschrijving na die versie is gewijzigd). Het oudere "expected_updated_at" (RFC 3339) is verouderd en werkt nog één release: verstuurd met een beschrijving en zonder expected_version wordt het opslaan geweigerd met 409 stale_write, tenzij het gelijk is aan de updated_at van de story. Story-writes respecteren ook If-Match tegen de ETag van de story; bij een mismatch volgt 412 precondition_failed.

Transition (POST …/transitions): { "to": "<state>" }. 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>" }. 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). Een bijlage of linkbijlage verwijderen vereist de uploader ervan of (manager).

Methode	Pad	Body / notities
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) } of { comment_emoji }. GET neemt fields= (toegestane lijst: 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}	Aanmaken: { url, link_type?, title? }; bijwerken: { url, title? } — link_type ∈ relates_to, duplicates, blocks, is_blocked_by, pull_request, branch, other; GitHub-URL’s met /pull/ en /tree/ krijgen automatisch een type
GET / POST	/projects/{id}/stories/{sid}/reviews · PUT/DELETE …/reviews/{rid}	Aanmaken: { reviewer_id? / reviewer_agent_id?, comment? } — laat beide weg om jezelf toe te wijzen. Bijwerken: { 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}	{ label_id } — een bestaand projectlabel; maak labels aan met POST /projects/{id}/labels, of stuur labels mee in de PUT van de story
GET / POST	/projects/{id}/stories/{sid}/attachments (+ /json) · DELETE …/attachments/{aid}	multipart-upload — video ≤ 200 MB, PDF / Word / Excel ≤ 25 MB, afbeeldingen / CSV / tekst ≤ 10 MB; list is (viewer)
GET / POST	/projects/{id}/stories/{sid}/link-attachments · DELETE …/link-attachments/{laid}	Linkbijlagen — een externe URL die naast de bestandsbijlagen wordt bewaard in plaats van als codelink
GET	/attachments/{token} · /api/v1/avatars/{token}	Reads van een bijlage of een avatar, geadresseerd via een token — de URL’s die de API uitdeelt; geen X-TrackerToken nodig

Epics

Dezelfde vorm als stories, zonder de toestandsmachine. member voor writes en voor de lijsten van reacties, owners en volgers; (viewer) voor de epic-lijst, één epic en de bijlagelijsten.

Methode	Pad	Beschrijving
GET / POST	/projects/{id}/epics · GET / PUT / DELETE …/epics/{eid}	Epics hebben een naam, een Markdown-beschrijving en een onderliggend label dat hun stories verbindt
GET / POST / PUT / DELETE	…/epics/{eid}/comments · …/comments/{cid}	Reacties op epics
GET / POST / DELETE	…/epics/{eid}/owners · …/followers (+ /agents/{aid}-varianten)	Owners en volgers, leden of agents — de owners van een epic worden doorgegeven aan zijn stories
GET / POST / DELETE	…/epics/{eid}/attachments (+ /json) · …/link-attachments	Bijlagen, met dezelfde limieten als bij stories
GET	/projects/{id}/analytics/epics · …/analytics/epics/{eid}	Voortgang per epic: burnup, doorvoer, gezondheid, voorspelling (viewer)

Labels

member voor writes, (viewer) voor reads.

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

Iteraties

Reads staan open voor elke projectrol, en anoniem op een openbaar project.

Methode	Pad	Beschrijving
GET	/projects/{id}/iterations	Iteraties tonen (≤ 500 per pagina; heeft een ETag en de vervolgheaders X-Tracker-Pagination-* wanneer afgekapt)
GET	/projects/{id}/iterations/{itid}	Eén iteratie
GET	/projects/{id}/iterations/first-preview	Het venster, de geprojecteerde velocity en de Backlog-vulling van de iteratie die een startende schrijfactie zou aanmaken, of van de huidige iteratie als die bestaat (member)
POST	/projects/{id}/iterations	Een handmatige iteratie aanmaken (manager)
DELETE	/projects/{id}/iterations/{itid}	Een iteratie verwijderen (manager)
PUT	/projects/{id}/iterations/{itid}/velocity	De velocity van één iteratie overschrijven zonder de projectstrategie te wijzigen (manager)
GET	/projects/{id}/iterations/{itid}/done-stories	De geaccepteerde stories van een gesloten iteratie, gepagineerd

Zoeken, metrics, voorkeuren

Methode	Pad	Beschrijving
GET	/projects/{id}/search?q=…	Krachtig zoeken — volledige tekst + kwalificatoren voor facetten / datumbereiken / personen (DSL in GitHub-stijl); geeft { results, total, limit, offset } terug. query is een alias voor q; limit= (standaard 50, max 1000) / offset= pagineren; sort= sorteert op relevance (standaard), created, created_asc, state of updated. (viewer) — zie de Gids
GET	/projects/{id}/metrics/{velocity,burndown,story-types,contributors}	De reeksen van de Metrics-pagina (viewer); epic-metrics staan onder /analytics/epics hierboven
GET	/projects/{id}/backlog/grouping	De geprojecteerde iteratiegroepen van de Backlog (viewer)
GET / PUT	/projects/{id}/preferences	Je bordvoorkeuren voor dit project — elke projectrol, alleen je eigen rij

Events

Methode	Pad	Beschrijving
GET	/projects/{id}/events	Cursor-gepagineerde eventstream (member) — viewers krijgen 403

Query-parameters: since_id=<event_id> (since is de oudere alias; since_id wint als beide worden meegestuurd), types=story.created,story.transitioned,comment.added,…, limit= (standaard 100, ≤ 500), cursor=. Het antwoord is { items, next_since_id, next_cursor }: bewaar next_since_id en geef het terug als since_id om verder te gaan; next_cursor is null op de laatste pagina.

Meldingen

De geünificeerde in-app meldingenfeed: volwaardige meldingsregels (reviewverzoeken, story-activiteit, uitnodigingen, …) samengevoegd met de @-vermeldingen-inbox tot één stream, nieuwste eerst. Feed-ids dragen een bronprefix (nt-… / sc-… / ec-…). Ledensessies en ea_user_*-sleutels lezen hun ledenregels; ea_agent_*-sleutels hun agentregels.

Methode	Pad	Beschrijving
GET	/me/notifications	Je meldingenfeed. Filters: unread=true, since_id=, kind= (mentions / reviews / stories / invitations); pagineer met cursor= / limit=
GET	/me/notifications/unread-count	Ongelezen totalen — { unread_count, by_category: { mentions, reviews, stories, invitations } }
POST	/me/notifications/read-all	Alles als gelezen markeren; geeft de verse tellers terug
POST	/me/notifications/{id}/ack	Eén item als gelezen markeren (idempotent)
POST	/me/notifications/{id}/accept	Een project-/organisatie-uitnodiging accepteren vanuit de feed (alleen leden-tokens)
POST	/me/notifications/{id}/decline	Een project-/organisatie-uitnodiging afwijzen (alleen leden-tokens)
GET	/me/notifications/resolve-invite?token=…	Een per e-mail ontvangen uitnodigingstoken herleiden tot je meldings-id — { "id": "nt-…" } of { "id": null }
GET	/me/notifications/stream	Live push — Server-Sent Events (text/event-stream); zie hieronder

Het stream-endpoint is geen JSON-endpoint en staat daarom niet in de OpenAPI-specificatie: het houdt de verbinding open en stuurt een frame zonder payload ({"type":"notification","kind":…}) zodra er iets nieuws binnenkomt, als signaal aan de client om de feed opnieuw op te halen. Verbindingen worden serverzijdig na 45 minuten beëindigd — opnieuw verbinden en opnieuw authenticeren. Alleen ledensessies en ea_user_*-sleutels; ea_agent_*-sleutels krijgen 403.

Import (manager)

Methode	Pad	Beschrijving
POST	/projects/{id}/import	Bestandsbronnen: source= ∈ pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json, eat. Multipart file=. Synchroon — antwoordt met de resultaattellingen.
POST	/projects/{id}/import/json	JSON-body; source=github heeft geen bestand nodig — owner, repo, optioneel token, en de opt-in-vlaggen include_pull_requests / include_milestones / include_releases / include_dependencies, en include_comments (standaard true); de bestandsbronnen sturen file_base64. Asynchroon: geeft 202 { import_id, status } terug. De server haalt op via GitHubs GraphQL-API, die anonieme aanroepers weigert, dus er bereikt altijd een token GitHub — het jouwe, of het gedeelde van de deployment. Zie de Gids.
GET	/projects/{id}/imports/{import_id}	Een job pollen: status loopt pending → fetching → writing → done | failed, met progress_current / progress_total tijdens het ophalen en de resultaattellingen bij done

Er draait per project maar één JSON-import tegelijk; een tweede POST …/import/json terwijl er een loopt, geeft 409 import_already_running. Met check_unpointed_estimates: true (bestandsbronnen; genegeerd voor github) wordt een bestand met schattingen van bugs of klusjes die het project niet van punten voorziet geweigerd met 409 import_unpointed_estimates en details.count, voordat een job start; zonder de vlag laat de import die schattingen vallen en meldt { code: "estimates_unpointed_dropped", count } in de warnings van het resultaat. dry_run: true (JSON-body of dry_run=true multipart) toont een voorbeeld van elke bron: parseert, herleidt, ontdubbelt, geeft dezelfde { imported, skipped, errors, unmatched }-tellingen terug en draait daarna terug — er wordt niets weggeschreven. Limieten: een bestand van 10 MiB (400 import_too_large) en 5.000 stories per import voor de bestandsbronnen (400 import_too_many_records); er wordt niets weggeschreven. Een request-body boven 16 MiB wordt eerder geweigerd met 413 request_too_large. De GitHub-bron kent geen plafond — die schrijft in blokken in plaats van één transactie. Herimporteren is idempotent per bron-id — reeds geïmporteerde regels worden overgeslagen, niet gedupliceerd.

Export

Methode	Pad	Beschrijving
GET	/projects/{id}/export/formats	Geregistreerde formaten: { id, name, content_type, drops, includes_archived }. Elke projectrol.
GET	/projects/{id}/export/{format}	Download er één (manager). Uitwisseling: eat (volledige getrouwheid), jira, pivotal, shortcut, trello, asana, gitlab, linear, plane, plane_json; documenten: pdf, docx.
GET	/projects/{id}/export/attachments	Elke bijlage als één doorbladerbare zip (bestanden behouden hun oorspronkelijke namen; JSON- + CSV-manifest) (manager).

Documentexports (pdf, docx) nemen extra queryparameters: page_size= (letter standaard / a4 / legal / folio), from= / to= (grenzen van het story-venster — RFC 3339 of kaal YYYY-MM-DD; een story valt binnen het bereik wanneer zijn created of completed_at erin ligt), include_icebox= / include_backlog= (beide standaard false, zodat een deelbare export alleen gepland / lopend werk toont). De uitwisselings-CSV-formaten negeren ze.

Back-ups en herstel (manager)

Methode	Pad	Beschrijving
GET / POST	/projects/{id}/backups · GET …/backups/{snapshot_id} · …/backups/health	Snapshots tonen, er nu een maken, er een lezen, en de gezondheidssamenvatting van de bewaring
POST	/projects/{id}/restores · POST …/restores/partial · GET …/restores/{restore_id}	Een hele snapshot herstellen, of geselecteerde tabellen eruit, en het herstel pollen

De POSTs vallen onder de rate-limit-laag sensitive (hieronder).

MCP- en OAuth-provider

East Agile Tracker is een OAuth 2.1-provider voor MCP-clients. Een client ontdekt hem via /.well-known/oauth-authorization-server en /.well-known/oauth-protected-resource/mcp, stuurt je naar /oauth/authorize (de toestemmingspagina), wisselt de code in bij /oauth/token, en spreekt daarna MCP op /mcp met het resulterende ea_mcp_*-token. Autorisaties worden getoond en ingetrokken via /me/oauth_grants. De provider-endpoints hebben een eigen rate-limit-laag.

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. De sleutel is gebonden aan de inloggegevens die hem hebben verstuurd. Niet toegepast op GET/HEAD/OPTIONS, /openapi.json en /docs, /api/auth/*, /mcp, elk pad dat /attachments bevat, of elk multipart/*-verzoek; een verzoek zonder inloggegevens wordt nooit gecacht. Antwoorden die geen domeinantwoord hebben bereikt, worden nooit gecacht — 401, 403, 404, 429 en elke 5xx — dus een retry na een van deze bereikt de handler; 400, 409, 412 en 422 zijn het antwoord van het domein en worden net als een succes opnieuw afgespeeld.

Paginering

List-endpoints accepteren cursor=<opaque> en limit=<n>. Indien ingesteld is het antwoord { "items": [...], "next_cursor": "<str|null>" }; geef next_cursor terug om te pagineren. Het plafond voor limit verschilt per endpoint: 200 voor stories, reacties en projecten; 500 voor events; 1000 voor het auditlog. Zoeken pagineert met limit (≤ 1000) en offset in plaats van een cursor en geeft { results, total, limit, offset } terug.

Een gewone lijst (zonder cursor/limit) die zijn antwoord moest afkappen, meldt dat in headers — X-Tracker-Pagination-Truncated, X-Tracker-Pagination-Limit, X-Tracker-Pagination-Offset en X-Tracker-Pagination-Next-Offset; stuur de laatste terug als offset= voor de volgende pagina. Er is geen header met het totale aantal.

Veldprojectie

De lijsten van stories, reacties en projecten accepteren fields= (komma-gescheiden) om alleen specifieke velden terug te geven. Het id van de resource wordt altijd opgenomen (story_id, story_comment_id en comment_id, project_id); 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. Veldvalidatie (blank/lengte/null-byte/e-mail) voegt details.fields en details.constraint toe; alleen een kale bad-request-fout laat details weg
400	validation_failed	gestructureerde invoerfout; details.fields is een array van schendende veldnamen
400	domeincodes	een route-specifieke weigering met een eigen code en zonder details — bijv. unsupported_export_format, import_too_large, import_unknown_source
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
409	stale_write · import_already_running · import_unpointed_estimates	de beschrijving is gewijzigd na je expected_version (of expected_updated_at komt niet meer overeen) · er loopt al een import · het bestand bevat schattingen van bugs of klusjes die het project niet van punten voorziet (details.count)
412	precondition_failed	If-Match kwam niet overeen met de huidige ETag van de resource; details bevat expected en current
413	request_too_large	de body overschrijdt de groottelimiet van de route
422	invalid_transition	ongeldige toestandsbeweging; details draagt { from, to, allowed }
429	rate_limited	te veel verzoeken vanaf dit IP op een route met rate limit; Retry-After-header
500	internal_error	serverfout — generiek bericht; veilig om opnieuw te proberen
502	upstream_error	een dienst waar de route van afhangt (bijv. GitHub) faalde
503	not_configured	de deployment mist de integratie die deze route nodig heeft (sms, objectopslag, …)

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 client-IP, op een handvol routes; geauthenticeerd API-verkeer elders kent geen rate limit. Standaardwaarden (elk paar is het aanhoudende tempo en de burst, instelbaar door de beheerder):

• Auth — /api/auth/*: 0,5 req/s, burst 20.
• OAuth provider — /oauth/*: 1 req/s, burst 60.
• Public — /api/contact: 0,2 req/s, burst 10.
• Feedback — /api/v1/feedback en /api/v1/feedback/with-screenshot: drie gestapelde lagen — één inzending per 15 s, 10 per uur, 36 per dag.
• Avatars — de avatar-redirect zonder authenticatie: 20 req/s, burst 200.
• Sensitive — de POSTs voor back-up en herstel: ~0,002 req/s, burst 5.

Een overschreden limiet geeft 429 terug met een Retry-After-header en de standaard JSON-foutenvelop, code: "rate_limited".