API-vejledning

East Agile Tracker-API’et er designet til agenter lige så meget som til mennesker. Alt, hvad du kan gøre i brugergrænsefladen, kan du gøre over API’et — og et par ting, som brugergrænsefladen ikke eksponerer, er der også.

Denne vejledning får dig fra nul til “scripting af din backlog” på under ti minutter. For den fulde endpoint-reference, se API-specifikation.

To slags nøgler

Du autentificerer med en API-nøgle i X-TrackerToken-headeren. Der er to slags:

• Brugernøgler (ea_user_…) — Handler som dig. Opret dem i Account Settings → API Keys. Brug disse til personlige scripts, CLI-værktøjer, integrationer.
• Agent-nøgler (ea_agent_…) — Handler som en navngiven agent i ét projekt. Opret dem som projektejer i Project Settings → Agents. Brug disse til AI-agenter — Claude Code, Codex, din egen — der skal deltage i projektet som navngivne teammedlemmer.

Forskellene:

	Brugernøgle	Agent-nøgle
Omfang	Alle dine projekter	Ét specifikt projekt
Identitet i revisionslog	Dit navn	Agentens navn
Rolle	Din rolle i hvert projekt	Sat ved nøgleoprettelse (viewer eller member)
Tilbagekaldelse	Tilbagekald en nøgle; du beholder adgang via andre nøgler/sessioner	Tilbagekald en nøgle; agenten mister adgang øjeblikkeligt
Bedst til	Personlig automatisering, scripts	AI-agenter, der skal kunne skelnes fra dig i historikken

Authorization: Bearer … virker også, hvis du foretrækker den header-stil.

Hej, API

Hent dine projekter:

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

Eller for en agent-nøgle, list det projekt, den er afgrænset til:

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

API’et er JSON, REST-agtigt, versioneret på /api/v1/. Samme former for mennesker og agenter.

Opret et projekt

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
  }'

Svaret inkluderer project_id og eventuelle standardværdier, serveren har anvendt (estimeringsskala, done state osv.).

Opret en story

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"]
  }'

Flyt en story gennem livscyklussen

Transition-endpointet validerer det ønskede træk og returnerer de tilladte næste tilstande ved fejl:

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" }'

Feltet er to (ikke to_state). Hvis trækket er ulovligt — sig du forsøgte at springe fra unstarted direkte til accepted — er svaret 422 invalid_transition med strukturerede fejldetaljer:

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

Dette er en af de små ting, der gør API’et agentvenligt: en agent kan læse details.allowed og vælge det rigtige næste træk uden at skrabe prosa.

Kommentér på en story

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." }'

Kommentaren tilskrives den, der ejer API-nøglen — hvis det er en agent-nøgle, er kommentarens forfatter agenten.

Idempotente skrivninger

Hvert skrive-endpoint accepterer en Idempotency-Key-header. Prøv den samme nøgle igen med den samme body, og få det samme svar tilbage. Prøv den samme nøgle igen med en anden body, og få en 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" }'

Dette er kritisk for agenter i retry-loops — gå ned midt i en skrivning, prøv igen med den samme nøgle, ingen dublerede stories.

Massetransitioner

Flyt mange stories på én gang. Hver story bedømmes uafhængigt; ét ulovligt træk lader ikke de andre fejle.

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"
  }'

Følg hændelsesstrømmen

For agenter, der vil reagere på, hvad mennesker gør, poll events-endpointet:

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"

Svaret er en cursor-pagineret strøm af hændelser med aktøren, ressourcen og ændringen. Hver hændelse har et ID; angiv det sidste ID, du så, som since for at genoptage, hvor du slap. Ingen webhooks, ingen scraping, ingen mistede hændelser.

Søg med filtersyntaksen

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

Tilgængelige filtre:

Filter	Eksempel	Beskrivelse
type:	type:feature	Filtrér efter story-type
state:	state:started	Filtrér efter tilstand
label:	label:"my label"	Filtrér efter label
owner:	owner:claire	Filtrér efter ejer
requester:	requester:tomas	Filtrér efter rekvirent
has:	has:blocker	Stories med blokkere
is:	is:unestimated	Uestimerede features

Fritekst matcher titlen og beskrivelsen. Kombiner filtre ved at adskille dem med mellemrum — de AND’es sammen.

Opdag API’et

Den live OpenAPI 3-specifikation er på:

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

Swagger UI er på:

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

/openapi.json og /docs er uautentificerede — en agent kan læse kontrakten, før den har en nøgle. Når den først holder en nøgle, returnerer /api/v1/meta (som kræver en gyldig nøgle) dens identitet og overgangsgrafen pr. story-type; opslag af referencedata (/story_types, /story_states, /effort_scales) er også uautentificerede. Tilsammen lader de agenter besvare “hvad kan jeg gøre her?” uden trial-and-error 403’er.

Bemærk: den serverede openapi.json oplister paths, men leverer i øjeblikket tomme request-bodies — brug feltformerne i Specifikationen til skrivninger.

WebSocket-kontrol

For interaktiv automatisering — at drive en logget-ind browser-session fra et script eller fjernstyre brugergrænsefladen til tutorials — er der en WebSocket-kanal:

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

De fleste brugere har aldrig brug for dette; det er der til de tilfælde, hvor REST ikke er nok.

Import fra en anden tracker

Hvis du scripter en massemigrering:

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"

Understøttede kilder: pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json.

Fejlformat

Alle fejl er JSON med som minimum:

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

Mange fejlsvar inkluderer også et details-objekt — details.fields (et array af krænkende feltnavne) på validation_failed, og details.allowed (ved siden af from/to) på 422 invalid_transition. Brug dem.

Paginering

List-endpoints accepterer limit og cursor. Cursor er uigennemsigtig; angiv next_cursor fra det forrige svar. Svar-headers inkluderer også X-Tracker-Pagination-Total for samlede tællinger, hvor det er billigt at beregne.

Hvad er det næste

• API-specifikation — Hvert endpoint, hvert verbum, hver form.
• Betjeningsvejledning → Agenter — UI-siden: udstedelse af agent-nøgler, navngivning af agenter, tilbagekaldelse.
• Introduktion — Begreberne bag API’et: stories, tilstande, iterationer, velocity, agenter.