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.

Tre slags legitimationsoplysninger

Du autentificerer med en nøgle i X-TrackerToken-headeren. Der er to slags nøgler, du selv udsteder, og en tredje, som en MCP-klient henter for dig:

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 i Project Settings → Agents. Brug disse til AI-agenter — Claude Code, Codex, din egen — der skal deltage i projektet som navngivne teammedlemmer.
MCP-tokens (ea_mcp_…) — OAuth 2.1-adgangstokens udstedt til en MCP-klient (Claude, en IDE), efter at du har godkendt den på samtykkesiden. De handler som dig, og du kan tilbagekalde dem under Account Settings → Connected apps.

Engangsdialogen efter oprettelse af en personlig API-nøgle i Kontoindstillinger, med nøglen skjult i dette billede

Fanen Agents formular til ny nøgle med et navn og rollen member valgt, under opsætningsvejledningen

Forskellene mellem de to, du selv udsteder:

	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, member eller manager — aldrig højere end den udstedende medlems egen rolle)
Tilbagekaldelse	Tilbagekald en nøgle; du beholder adgang via andre nøgler/sessioner	Tilbagekald eller rotér 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"]
  }'

estimate er skalaværdiens etiket som en streng — "3", eller "13" på Fibonacci-skalaen — fordi den skal svare til et punkt på projektets skala. Et JSON-tal afvises.

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.

rejected er terminal for transition-endpointet. For at sætte en afvist story i arbejde igen skal du bruge POST …/stories/{sid}/restart; POST …/stories/{sid}/reject er verbumsformen for at afvise en leveret story.

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.added" \
  -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. Strømmen kræver rollen member — en viewer får 403.

Søg

GET /projects/{id}/search?q=<query> kører en kraftfuld fritekst- og struktureret søgning over projektets stories. Forespørgselssproget er modelleret efter GitHubs kvalifikatorer til issue-søgning — så syntaks, du (eller en AI-agent) allerede kender fra GitHub, kan for det meste bruges her.

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'

Svaret er en JSON-konvolut med stories rangeret efter relevans:

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

total er det fulde antal træffere, ikke sidestørrelsen. Paginér med limit (standard 50, maks. 1000) og offset; sortér med sort=relevance (standard), created, created_asc, updated eller state.

Grammatik

Fritekst matcher en storys titel, reference og beskrivelse (fritekst, stammet og rangeret). Omslut en præcis frase med "anførselstegn".
Kvalifikatorer har formen field:value. Adskil alternativer med komma (OR inden for ét felt): type:bug,chore. Adskil kvalifikatorer med mellemrum (AND på tværs af dem).
Negér ethvert led eller enhver kvalifikator med et indledende -: -label:wontfix.
Intervaller for datoer og point: inklusivt a..b, eller åbent >x / <x.

Kvalifikatorer

Kvalifikator	Eksempel	Matcher
`type:`	`type:bug,chore`	story-type(r)
`state:`	`state:started,finished`	workflow-tilstand(e)
`label:`	`label:"my label"`	et label
`epic:`	`epic:"Checkout"`	stories i en epic
`priority:`	`priority:p1`	prioritet
`points:`	`points:3` · `points:1..5` · `points:>3`	estimatværdi eller interval
`iteration:`	`iteration:42`	iterations-id
`created:` `updated:` `started:` `completed:` `release:`	`created:2026-05-01..2026-06-01` · `updated:>2026-06-01`	en dato eller et interval (dags-granularitet); `release:` er storyens udgivelsesdato
`owner:` `requester:` `follower:` `reviewer:` `commenter:` `mention:`	`owner:claire` · `owner:@me`	en person via navn eller e-mail — medlemmer og agenter, `mention:` inklusive; `@me` er dig
`has:blocker`	`has:blocker`	har en åben blokker
`is:`	`is:unestimated` · `is:icebox` · `is:backlog` · `is:blocked`	et flag

mywork: er et alias for owner: — mywork:me er owner:@me. Den ældre kvalifikator scheduled: er udfaset og ignoreres stiltiende; brug release:.

Komma-OR (type:bug,chore) gælder facet-kvalifikatorerne; person-kvalifikatorerne (owner: requester: follower: reviewer: commenter: mention:) tager én enkelt værdi.

Eksempler

payment crash                              fritekst "payment" OG "crash"
"exact phrase"                             en frase
type:bug,chore state:started               bugs eller chores, der er startet
owner:@me -label:wontfix                   mine, uden labelet wontfix
points:3..8 created:2026-05-01..2026-06-01 estimeret 3-8, oprettet i maj
follower:tomas has:blocker                 tomas følger den, og den er blokeret
is:backlog updated:>2026-06-01             backlog-poster rørt siden 1. juni

Den samme forespørgselsstreng driver tavlens søgefelt (som åbner en levende resultatkolonne) og dette API — én grammatik for både mennesker og agenter. At søge i indholdet af kommentarer, tasks og blokkere står på roadmappet; i dag dækker fritekst storyens egen titel, reference og beskrivelse.

Opdag API’et

Den live OpenAPI 3-specifikation er på:

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

Swagger UI er på:

https://api.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, /priority_scales) er også uautentificerede. Tilsammen lader de agenter besvare “hvad kan jeg gøre her?” uden trial-and-error 403’er.

Den serverede openapi.json bærer request-body-skemaer for skrive-endpointene, inklusive hvert felts maxLength, så en klient kan validere, før den sender. Specifikationen opsummerer de samme former.

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

token er browsersessionens JWT, ikke en API-nøgle — en ea_user_*- eller ea_agent_*-nøgle afvises før opgraderingen. 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 filkilder: pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json, eat (East Agile Trackers egen eksport — round-trip-formatet). Multipart-endpointet kører synkront og svarer med resultattallene.

GitHub importerer fra API’et frem for fra en fil, via JSON-endpointet — ingen file, kun repository-koordinaterne:

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

JSON-endpointet er asynkront: det svarer 202 med { "import_id", "status" }, og du poller GET /projects/{id}/imports/{import_id}, indtil jobbet når done eller failed. Kun én import kører pr. projekt ad gangen — et andet kald, mens ét er undervejs, giver 409 import_already_running. Hele løkken, med jobbets fremdriftsfelter, står i Fyld et projekt fra et GitHub-repo.

token er valgfrit i kaldet, men selve hentningen autentificerer sig altid — den kører på GitHubs GraphQL-API, som ikke har noget anonymt niveau. Udelad token, og serveren indsætter sit platform-token: kun offentlige repositories, delt af hver eneste kalder og afvist med import_github_shared_quota_low, når dets GraphQL-budget falder under 500 point. Et privat repository, eller et deployment der ikke har konfigureret noget platform-token (import_github_no_token), kræver dit. Uanset hvilket token der kører, bruges det kun til de opstrøms GitHub-kald og gemmes eller ekkoes aldrig tilbage. Alle detaljer, inklusive GitHubs uautentificerede REST-loft på 60 forespørgsler, står i Fyld et projekt fra et GitHub-repo.

Dry-run-forhåndsvisning. Tilføj "dry_run": true (JSON) eller -F "dry_run=true" (multipart) til en hvilken som helst kilde. Importen parser, resolver og de-duplikerer nøjagtigt som en rigtig kørsel, giver de samme resultattal (imported, skipped, errors, unmatched) og ruller derefter alt tilbage — intet skrives. På JSON-endpointet kommer tallene på det pollede job, tørkørsel eller ej.

Grænser. En upload-body er begrænset til 10 MiB, og en enkelt import til 5.000 historier; at overskride en af dem er en 400 uden noget skrevet. At genimportere en fil er sikkert — rækker, der allerede er importeret (matchet på kilde-id), springes over frem for at blive duplikeret.

Eksportér et projekt

Enhver projektrolle kan liste formaterne; at downloade ét er kun for owners:

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

# Download ét format (eat er den fuldt-fidelitet round-trip-CSV)
curl https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/export/eat \
  -H "X-TrackerToken: $TRACKER_TOKEN" -o project-export.csv

Udvekslingsformat-id’er: eat, jira, pivotal, shortcut, trello, asana, gitlab, linear, plane, plane_json, plus dokumentformaterne pdf og docx. Hver vedhæftning kan downloades som én zip fra GET /projects/{id}/export/attachments.

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. En 429 rate_limited bærer en Retry-After-header i den samme JSON-konvolut.

Paginering

List-endpoints accepterer limit og cursor. Cursor er uigennemsigtig; angiv next_cursor fra det forrige svar. Loftet for limit er pr. endpoint — 200 på stories, kommentarer og projekter, 500 på events, 1000 på søgning og revisionsloggen. En almindelig liste (uden cursor), der har måttet afkorte sit svar, siger det i headers: X-Tracker-Pagination-Truncated, -Limit, -Offset og -Next-Offset, som du sender tilbage som offset= til næste side. Der findes ingen header med samlet antal.

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.