API-vejledning

Kom i gang med East Agile Trackers REST API: bruger- og agentnøgler, oprette og flytte stories, idempotente skrivninger, søgning, hændelser og paginering.

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 → Agent. 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 → API Keys → 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://api.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://api.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://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
  }'

Svaret inkluderer project_id og de iterationsstandarder, serveren har anvendt (iteration_start_day, initial_velocity, iteration_length_weeks); GET /projects/{id} returnerer de fulde indstillinger.

Opret en story

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

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, som også afviser to: "rejected". Afvis en leveret story med POST …/stories/{sid}/reject; sæt en afvist story i arbejde igen med POST …/stories/{sid}/restart, som virker, mens storyen er i den aktuelle iteration.

Kommentér på en story

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

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

Idempotente skrivninger

Skrive-endpoints accepterer en Idempotency-Key-header (undtagen upload af vedhæftninger). Prøv den samme nøgle igen med den samme body inden for 24 timer, 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://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" }'

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. Et 5xx-, 401-, 403-, 404- eller 429-svar caches aldrig, så et nyt forsøg efter et af dem kører requesten igen.

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

Følg hændelsesstrømmen

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

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"

Svaret er { items, next_since_id, next_cursor }: hver hændelse bærer aktøren, ressourcen og ændringen. Gem next_since_id og angiv det tilbage som since_id ved næste poll for at genoptage, hvor du slap (since accepteres som et ældre alias). 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://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'

Svaret er en JSON-konvolut med stories rangeret efter relevans, når forespørgslen har fritekst, og ellers i board-rækkefølge:

{ "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 (med en agent-nøgle det medlem, der oprettede nøglen)
`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-05-31 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.

Import fra en anden tracker

Hvis du scripter en massemigrering:

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"

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

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 importfil er begrænset til 10 MiB og 5.000 historier (400 import_too_large / import_too_many_records, intet skrevet); en GitHub-import har ingen grænse for antal historier. 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 kræver rollen manager:

# De registrerede eksportformater: { 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 ét format (eat er den fuldt-fidelitet round-trip-CSV)
curl https://api.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å revisionsloggen; søgning paginerer med limit (≤ 1000) og offset. 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.