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.

Twee soorten sleutels

Je authenticeert met een API-sleutel in de X-TrackerToken-header. Er zijn twee soorten:

• 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 als project-owner in Project Settings → Agents. Gebruik deze voor AI-agents — Claude Code, Codex, je eigen — die als benoemde teamgenoten aan het project moeten deelnemen.

De verschillen:

	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 of member)
Intrekking	Trek een sleutel in; je behoudt toegang via andere sleutels/sessies	Trek een sleutel in; 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"]
  }'

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.

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.created" \
  -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.

Zoeken met de filtersyntaxis

curl "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/search?query=type:feature%20state:started%20label:mvp" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

Beschikbare filters:

Filter	Voorbeeld	Beschrijving
type:	type:feature	Filter op story-type
state:	state:started	Filter op toestand
label:	label:"my label"	Filter op label
owner:	owner:claire	Filter op owner
requester:	requester:tomas	Filter op aanvrager
has:	has:blocker	Stories met blockers
is:	is:unestimated	Niet-geschatte features

Vrije tekst matcht de titel en beschrijving. Combineer filters door ze met spaties te scheiden — ze worden ge-AND’d.

De API ontdekken

De live OpenAPI 3-spec staat op:

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

Swagger UI staat op:

https://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) zijn eveneens zonder authenticatie. Samen laten ze agents de vraag “wat kan ik hier doen?” beantwoorden zonder trial-and-error-403’s.

Let op: de geserveerde openapi.json somt paden op, maar levert momenteel lege request-bodies — gebruik de veldvormen in de Specificatie voor writes.

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=YOUR_TOKEN')
ws.send(JSON.stringify({ action: 'get_state', id: 'req-1' }))

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 scripten:

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 bronnen: pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json.

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.

Paginering

List-endpoints accepteren limit en cursor. De cursor is ondoorzichtig; geef de next_cursor van het vorige antwoord door. Antwoordheaders bevatten ook X-Tracker-Pagination-Total voor totaaltellingen waar dat goedkoop te berekenen is.

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.