API-gids

Aan de slag met de REST API van East Agile Tracker: gebruikers- en agentsleutels, stories aanmaken en verplaatsen, idempotente writes, zoeken, events en paginering.

De East Agile Tracker API is net zozeer voor agents als voor mensen ontworpen. Alles wat je in de UI kunt doen, kun je via de API doen — en een paar dingen die de UI niet blootlegt zijn er ook.

Deze gids brengt je in minder dan tien minuten van nul naar “je backlog scripten”. Voor de volledige endpoint-referentie, zie API-specificatie.

Drie soorten inloggegevens

Je authenticeert met een sleutel in de X-TrackerToken-header. Er zijn twee soorten sleutels die je zelf aanmaakt, en een derde die een MCP-client voor je verkrijgt:

User-sleutels (ea_user_…) — Handelen als jou. Maak ze aan in Account Settings → API Keys. Gebruik deze voor persoonlijke scripts, CLI-tools, integraties.
Agent-sleutels (ea_agent_…) — Handelen als een benoemde agent in één project. Maak ze aan in Project Settings → Agent. Gebruik deze voor AI-agents — Claude Code, Codex, je eigen — die als benoemde teamgenoten aan het project moeten deelnemen.
MCP-tokens (ea_mcp_…) — OAuth 2.1-access-tokens die aan een MCP-client (Claude, een IDE) worden uitgegeven nadat je die op de toestemmingspagina hebt goedgekeurd. Ze handelen als jou, en je kunt ze intrekken onder Account Settings → API Keys → Connected apps.

Het eenmalige dialoogvenster na het aanmaken van een persoonlijke API-sleutel in Accountinstellingen; de sleutel is gemaskeerd

Het formulier voor een nieuwe sleutel op het tabblad Agent met een naam en de rol member gekozen, onder de installatie-instructies

De verschillen tussen de twee die je zelf aanmaakt:

	User-sleutel	Agent-sleutel
Scope	Al je projecten	Eén specifiek project
Identiteit in auditlog	Je naam	De naam van de agent
Rol	Je rol in elk project	Ingesteld bij aanmaken van de sleutel (viewer, member of manager — nooit hoger dan de eigen rol van het lid dat de sleutel aanmaakt)
Intrekking	Trek een sleutel in; je behoudt toegang via andere sleutels/sessies	Trek een sleutel in of roteer hem; de agent verliest onmiddellijk de toegang
Beste voor	Persoonlijke automatisering, scripts	AI-agents die in de historie van jou te onderscheiden moeten zijn

Authorization: Bearer … werkt ook als je die headerstijl verkiest.

Hallo, API

Haal je projecten op:

curl https://api.eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: $TRACKER_TOKEN"

Of voor een agent-sleutel, toon het project waaraan deze is gebonden:

curl https://api.eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: ea_agent_xxxxx"

De API is JSON, REST-achtig, geversioneerd op /api/v1/. Dezelfde vormen voor mensen en agents.

Een project aanmaken

curl -X POST https://api.eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Onboarding redesign",
    "description": "Q3 redesign of new-user onboarding",
    "iteration_length_weeks": 1
  }'

Het antwoord bevat het project_id en de iteratie-standaardwaarden die de server heeft toegepast (iteration_start_day, initial_velocity, iteration_length_weeks); GET /projects/{id} geeft de volledige instellingen terug.

Een story aanmaken

curl -X POST https://api.eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Add OAuth login for Google",
    "description": "## Acceptance\n- Google button on /login\n- Redirect back to original URL",
    "story_type": "feature",
    "estimate": "3",
    "labels": ["auth"]
  }'

estimate is het label van de schaalwaarde als string — "3", of "13" op de Fibonacci-schaal — omdat het moet overeenkomen met een punt op de schaal van het project. Een JSON-getal wordt geweigerd.

Een story door de levenscyclus bewegen

Het transition-endpoint valideert de gevraagde beweging en geeft bij een fout de toegestane volgende toestanden terug:

curl -X POST https://api.eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/$STORY_ID/transitions \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "to": "started" }'

Het veld is to (niet to_state). Als de beweging ongeldig is — zeg, je probeerde van unstarted rechtstreeks naar accepted te springen — is het antwoord 422 invalid_transition met gestructureerde foutdetails:

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

Dit is een van de kleine dingen die de API agent-vriendelijk maakt: een agent kan details.allowed lezen en de juiste volgende beweging kiezen zonder proza te scrapen.

rejected is een eindtoestand voor het transition-endpoint, dat ook to: "rejected" weigert. Wijs een opgeleverde story af met POST …/stories/{sid}/reject; zet een afgewezen story weer aan het werk met POST …/stories/{sid}/restart, wat werkt zolang de story in de huidige iteratie zit.

Op een story reageren

curl -X POST https://api.eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/$STORY_ID/comments \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Investigation done. Picking this up." }'

De reactie wordt toegeschreven aan wie de API-sleutel bezit — als het een agent-sleutel is, is de auteur van de reactie de agent.

Idempotente writes

Write-endpoints accepteren een Idempotency-Key-header (uploads van bijlagen uitgezonderd). Probeer dezelfde sleutel binnen 24 uur opnieuw met dezelfde body en je krijgt hetzelfde antwoord terug. Probeer dezelfde sleutel opnieuw met een andere body en je krijgt een 409 idempotency_conflict:

curl -X POST https://api.eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Refactor auth middleware", "story_type": "chore" }'

Dit is cruciaal voor agents in retry-lussen — crash halverwege een write, probeer opnieuw met dezelfde sleutel, geen dubbele stories. Een 5xx-, 401-, 403-, 404- of 429-antwoord wordt nooit gecacht, dus een retry daarna voert het verzoek opnieuw uit.

Bulk-overgangen

Beweeg veel stories tegelijk. Elke story wordt onafhankelijk beoordeeld; één ongeldige beweging laat de andere niet falen.

curl -X POST https://api.eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/bulk_transition \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "story_ids": [101, 102, 103],
    "to": "delivered"
  }'

De eventstream volgen

Voor agents die willen reageren op wat mensen doen, poll je het events-endpoint:

curl "https://api.eastagiletracker.com/api/v1/projects/$PROJECT_ID/events?since_id=$LAST_EVENT_ID&types=story.created,story.transitioned,comment.added" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

Het antwoord is { items, next_since_id, next_cursor }: elk event bevat de actor, de resource en de wijziging. Bewaar next_since_id en geef het bij de volgende poll terug als since_id om verder te gaan waar je gebleven was (since wordt als oudere alias geaccepteerd). Geen webhooks, geen scrapen, geen gemiste events. De stream vereist de rol member — een viewer krijgt 403.

Zoeken

GET /projects/{id}/search?q=<query> voert een krachtige zoekopdracht uit over de stories van het project, met volledige tekst en gestructureerde filters. De querytaal is gemodelleerd naar de issue-zoekkwalificatoren van GitHub — dus syntaxis die jij (of een AI-agent) al van GitHub kent, werkt grotendeels ook hier.

curl -G "https://api.eastagiletracker.com/api/v1/projects/$PROJECT_ID/search" \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  --data-urlencode 'q=payment crash type:bug,chore owner:@me created:>2026-05-01'

Het antwoord is een JSON-envelop, met de stories gerangschikt op relevantie wanneer de query vrije tekst bevat, en anders in bordvolgorde:

{ "results": [ /* canonical story objects */ ], "total": 42, "limit": 50, "offset": 0 }

total is het volledige aantal treffers, niet de paginagrootte. Pagineer met limit (standaard 50, max 1000) en offset; sorteer met sort=relevance (standaard), created, created_asc, updated of state.

Grammatica

Vrije tekst matcht de titel, referentie en beschrijving van een story (volledige tekst, gestemd en gerangschikt). Zet een exacte zin tussen "quotes".
Kwalificatoren hebben de vorm field:value. Scheid alternatieven met komma’s (OF binnen een veld): type:bug,chore. Scheid kwalificatoren met spaties (EN tussen kwalificatoren).
Ontken elke term of kwalificator met een voorafgaand -: -label:wontfix.
Bereiken voor datums en punten: inclusief a..b, of open >x / <x.

Kwalificatoren

Kwalificator	Voorbeeld	Matcht
`type:`	`type:bug,chore`	storytype(s)
`state:`	`state:started,finished`	workflowtoestand(en)
`label:`	`label:"my label"`	een label
`epic:`	`epic:"Checkout"`	stories in een epic
`priority:`	`priority:p1`	prioriteit
`points:`	`points:3` · `points:1..5` · `points:>3`	schattingswaarde of bereik
`iteration:`	`iteration:42`	iteratie-id
`created:` `updated:` `started:` `completed:` `release:`	`created:2026-05-01..2026-06-01` · `updated:>2026-06-01`	een datum of bereik (per dag); `release:` is de releasedatum van de story
`owner:` `requester:` `follower:` `reviewer:` `commenter:` `mention:`	`owner:claire` · `owner:@me`	een persoon op naam of e-mailadres — members en agents, `mention:` inbegrepen; `@me` ben jij (met een agent-sleutel: het lid dat de sleutel heeft aangemaakt)
`has:blocker`	`has:blocker`	heeft een open blocker
`is:`	`is:unestimated` · `is:icebox` · `is:backlog` · `is:blocked`	een vlag

mywork: is een alias voor owner: — mywork:me is owner:@me. De oudere kwalificator scheduled: is uitgefaseerd en wordt stilzwijgend genegeerd; gebruik release:.

Komma-OF (type:bug,chore) geldt voor de facetkwalificatoren; de personenkwalificatoren (owner: requester: follower: reviewer: commenter: mention:) nemen één waarde.

Voorbeelden

payment crash                              full text "payment" AND "crash"
"exact phrase"                             a phrase
type:bug,chore state:started               bugs or chores that are started
owner:@me -label:wontfix                   mine, excluding the wontfix label
points:3..8 created:2026-05-01..2026-05-31 estimated 3-8, created in May
follower:tomas has:blocker                 tomas follows it and it's blocked
is:backlog updated:>2026-06-01             backlog items touched since Jun 1

Dezelfde querystring stuurt het zoekvak van het bord aan (dat een live resultatenkolom opent) en deze API — één grammatica voor mensen en agents. Zoeken in de inhoud van reacties, taken en blockers staat op de roadmap; vandaag dekt vrije tekst de eigen titel, referentie en beschrijving van de story.

De API ontdekken

De live OpenAPI 3-spec staat op:

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

Swagger UI staat op:

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

/openapi.json en /docs zijn zonder authenticatie — een agent kan het contract lezen voordat het een sleutel heeft. Zodra het een sleutel bezit, geeft /api/v1/meta (dat een geldige sleutel vereist) zijn identiteit en de transitiegraaf per story-type terug; de referentiegegevens-lookups (/story_types, /story_states, /effort_scales, /priority_scales) zijn eveneens zonder authenticatie. Samen laten ze agents de vraag “wat kan ik hier doen?” beantwoorden zonder trial-and-error-403’s.

De geserveerde openapi.json bevat request-body-schema’s voor de write-endpoints, inclusief de maxLength van elk veld, zodat een client kan valideren voordat hij verstuurt. De Specificatie vat dezelfde vormen samen.

Importeren uit een andere tracker

Als je een bulkmigratie script:

curl -X POST https://api.eastagiletracker.com/api/v1/projects/$PROJECT_ID/import \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -F "source=pivotal" \
  -F "file=@pivotal_export.csv"

Ondersteunde bestandsbronnen: pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json, eat (East Agile Trackers eigen export — het round-trip-formaat). Het multipart-endpoint draait synchroon en antwoordt met de resultaattellingen.

GitHub importeert uit de API in plaats van uit een bestand, via het JSON-endpoint — geen file, alleen de repository-coördinaten:

curl -X POST https://api.eastagiletracker.com/api/v1/projects/$PROJECT_ID/import/json \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "source": "github",
        "owner": "octocat",
        "repo": "hello-world",
        "token": "ghp_…",
        "include_pull_requests": false,
        "include_milestones": false,
        "include_releases": false,
        "include_dependencies": false
      }'

Het JSON-endpoint is asynchroon: het antwoordt met 202 en { "import_id", "status" }, en je pollt GET /projects/{id}/imports/{import_id} tot de job done of failed bereikt. Er draait per project maar één import tegelijk — een tweede aanroep terwijl er een loopt, geeft 409 import_already_running. De hele lus, met de voortgangsvelden van de job, staat in Een project vullen vanuit een GitHub-repo.

Het token is optioneel op de lijn, maar het ophalen zelf authenticeert altijd — het loopt via GitHubs GraphQL-API, die geen anonieme laag kent. Laat token weg en de server zet zijn platformtoken in: alleen publieke repositories, gedeeld door elke aanroeper, en geweigerd met import_github_shared_quota_low zodra het GraphQL-budget onder 500 punten zakt. Een private repository, of een deployment die geen platformtoken heeft ingesteld (import_github_no_token), vereist het jouwe. Welk token er ook loopt, het wordt uitsluitend gebruikt voor de bovenstroomse GitHub-aanroepen en wordt nooit opgeslagen of teruggegeven. De volledige uitleg, inclusief GitHubs niet-geauthenticeerde REST-plafond van 60 verzoeken, staat in Een project vullen vanuit een GitHub-repo.

Dry-run-voorbeeld. Voeg "dry_run": true (JSON) of -F "dry_run=true" (multipart) toe aan een willekeurige bron. De import parseert, herleidt en ontdubbelt precies zoals een echte run, geeft dezelfde resultaattellingen terug (imported, skipped, errors, unmatched), en draait daarna alles terug — er wordt niets weggeschreven. Bij het JSON-endpoint komen de tellingen binnen op de gepollde job, of het nu een dry run is of niet.

Limieten. Een importbestand is begrensd op 10 MiB en 5.000 stories (400 import_too_large / import_too_many_records, er wordt niets weggeschreven); een GitHub-import heeft geen storylimiet. Een bestand opnieuw importeren is veilig — reeds geïmporteerde regels (gematcht op bron-id) worden overgeslagen, niet gedupliceerd.

Een project exporteren

Elke projectrol kan de formaten opvragen; er een downloaden vereist de rol manager:

# The registered export formats: { id, name, content_type, drops, includes_archived }
curl https://api.eastagiletracker.com/api/v1/projects/$PROJECT_ID/export/formats \
  -H "X-TrackerToken: $TRACKER_TOKEN"

# Download one format (eat is the full-fidelity round-trip CSV)
curl https://api.eastagiletracker.com/api/v1/projects/$PROJECT_ID/export/eat \
  -H "X-TrackerToken: $TRACKER_TOKEN" -o project-export.csv

Uitwisselingsformaat-ids: eat, jira, pivotal, shortcut, trello, asana, gitlab, linear, plane, plane_json, plus de documentformaten pdf en docx. Elke bijlage is als één zip te downloaden via GET /projects/{id}/export/attachments.

Foutformaat

Alle fouten zijn JSON met ten minste:

{
  "code": "invalid_transition",
  "error": "Cannot move story from `unstarted` to `accepted`"
}

Veel foutantwoorden bevatten ook een details-object — details.fields (een array van schendende veldnamen) bij validation_failed, en details.allowed (naast from/to) bij 422 invalid_transition. Gebruik ze. Een 429 rate_limited heeft een Retry-After-header, in dezelfde JSON-envelop.

Paginering

List-endpoints accepteren limit en cursor. De cursor is ondoorzichtig; geef de next_cursor van het vorige antwoord door. 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. Een gewone lijst (zonder cursor) die zijn antwoord moest afkappen, meldt dat in headers: X-Tracker-Pagination-Truncated, -Limit, -Offset en -Next-Offset, die je als offset= terugstuurt voor de volgende pagina. Er is geen header met het totale aantal.

Wat is het volgende

API-specificatie — Elk endpoint, elke verb, elke vorm.
Gebruiksinstructies → Agents — UI-kant: agent-sleutels aanmaken, agents benoemen, intrekken.
Introductie — Concepten achter de API: stories, toestanden, iteraties, velocity, agents.