API-gids

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 → Agents. 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 → 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://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: $TRACKER_TOKEN"

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

curl https://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://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 alle standaardwaarden die de server heeft toegepast (schattingsschaal, done state, enz.).

Een story aanmaken

curl -X POST https://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://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. Om een afgewezen story weer aan het werk te zetten, gebruik je POST …/stories/{sid}/restart; POST …/stories/{sid}/reject is de werkwoordsvorm om een opgeleverde story af te wijzen.

Op een story reageren

curl -X POST https://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

Elk write-endpoint accepteert een Idempotency-Key-header. Probeer dezelfde sleutel 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://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.

Bulk-overgangen

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

curl -X POST https://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://eastagiletracker.com/api/v1/projects/$PROJECT_ID/events?since=$LAST_CURSOR&types=story.created,story.transitioned,comment.added" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

Het antwoord is een cursor-gepagineerde stroom van events met de actor, de resource en de wijziging. Elk event heeft een ID; geef het laatste ID dat je zag door als since om verder te gaan waar je gebleven was. 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://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:

{ "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
`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-06-01 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.

WebSocket-besturing

Voor interactieve automatisering — het besturen van een ingelogde browsersessie vanuit een script, of het op afstand bedienen van de UI voor tutorials — is er een WebSocket-kanaal:

const ws = new WebSocket('wss://eastagiletracker.com/ws/control?token=SESSION_JWT')
ws.send(JSON.stringify({ action: 'get_state', id: 'req-1' }))

Het token is de JWT van de browsersessie, geen API-sleutel — een ea_user_*- of ea_agent_*-sleutel wordt vóór de upgrade geweigerd. De meeste gebruikers hebben dit nooit nodig; het is er voor de gevallen waarin REST niet genoeg is.

Importeren uit een andere tracker

Als je een bulkmigratie script:

curl -X POST https://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://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 upload-body is begrensd op 10 MiB, en een enkele import op 5.000 stories; overschrijding van één van beide is een 400 zonder dat er iets wordt weggeschreven. 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 is alleen voor owners:

# The registered export formats: { id, name, content_type, drops, includes_archived }
curl https://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://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 zoeken en het auditlog. 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.