API-guide

Kom igång med East Agile Trackers REST-API: användar- och agentnycklar, skapa och flytta stories, idempotenta skrivningar, sökning, händelser och paginering.

East Agile Tracker-API:et är utformat för agenter lika mycket som för människor. Allt du kan göra i gränssnittet kan du göra via API:et — och några saker som gränssnittet inte exponerar finns också där.

Den här guiden tar dig från noll till att “skripta din backlog” på under tio minuter. För den fullständiga endpoint-referensen, se API-specifikation.

Tre sorters inloggningsuppgifter

Du autentiserar med en nyckel i X-TrackerToken-headern. Det finns två sorters nyckel som du skapar själv, och en tredje som en MCP-klient hämtar åt dig:

Användarnycklar (ea_user_…) — Agerar som dig. Skapa dem under Account Settings → API Keys. Använd dem för personliga skript, CLI-verktyg, integrationer.
Agentnycklar (ea_agent_…) — Agerar som en namngiven agent i ett projekt. Skapa dem under Project Settings → Agent. Använd dem för AI-agenter — Claude Code, Codex, dina egna — som ska delta i projektet som namngivna lagkamrater.
MCP-tokens (ea_mcp_…) — OAuth 2.1-åtkomsttokens som utfärdas till en MCP-klient (Claude, en IDE) efter att du godkänt den på samtyckessidan. De agerar som du, och du kan återkalla dem under Account Settings → API Keys → Connected apps.

Engångsdialogen efter att en personlig API-nyckel skapats i Kontoinställningar; nyckeln är maskerad i den här bilden

Formuläret för ny nyckel på fliken Agent med ett namn och rollen member vald, under installationsanvisningarna

Skillnaderna mellan de två du skapar själv:

	Användarnyckel	Agentnyckel
Omfattning	Alla dina projekt	Ett specifikt projekt
Identitet i granskningsloggen	Ditt namn	Agentens namn
Roll	Din roll i varje projekt	Anges när nyckeln skapas (viewer, member eller manager — aldrig högre än rollen hos den medlem som skapar den)
Återkallande	Återkalla en nyckel; du behåller åtkomst via andra nycklar/sessioner	Återkalla eller rotera en nyckel; agenten förlorar åtkomst omedelbart
Bäst för	Personlig automatisering, skript	AI-agenter som ska gå att skilja från dig i historiken

Authorization: Bearer … fungerar också om du föredrar den header-stilen.

Hello, API

Hämta dina projekt:

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

Eller, för en agentnyckel, lista projektet den är knuten till:

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

API:et är JSON, REST-aktigt, versionerat på /api/v1/. Samma former för människor och agenter.

Skapa ett 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 innehåller project_id och de iterationsstandardvärden som servern tillämpade (iteration_start_day, initial_velocity, iteration_length_weeks); GET /projects/{id} returnerar alla inställningar.

Skapa 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 är skalvärdets etikett som en sträng — "3", eller "13" på Fibonacci-skalan — eftersom det måste motsvara en punkt på projektets skala. Ett JSON-tal avvisas.

Flytta en story genom livscykeln

Transition-endpointen validerar den begärda förflyttningen och returnerar de tillåtna nästa tillstånden vid fel:

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

Fältet är to (inte to_state). Om förflyttningen är otillåten — säg att du försökte hoppa från unstarted direkt till accepted — blir svaret 422 invalid_transition med strukturerade feldetaljer:

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

Det här är en av de små sakerna som gör API:et agentvänligt: en agent kan läsa details.allowed och välja rätt nästa förflyttning utan att skrapa prosa.

rejected är ett sluttillstånd för transition-endpointen, som också nekar to: "rejected". Avvisa en levererad story med POST …/stories/{sid}/reject; sätt en avvisad story i arbete igen med POST …/stories/{sid}/restart, som fungerar medan storyn ligger i den aktuella iterationen.

Kommentera 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 tillskrivs den som äger API-nyckeln — om det är en agentnyckel är kommentarens författare agenten.

Idempotenta skrivningar

Skriv-endpoints accepterar en Idempotency-Key-header (utom bilageuppladdningar). Gör om samma nyckel med samma body inom 24 timmar och få samma svar tillbaka. Gör om samma nyckel med en annan body och 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" }'

Det här är avgörande för agenter i omförsöksloopar — krasch mitt i en skrivning, gör om med samma nyckel, inga dubblerade stories. Ett 5xx-, 401-, 403-, 404- eller 429-svar cachas aldrig, så ett omförsök efter ett sådant kör requesten igen.

Bulk-transitioner

Flytta många stories på en gång. Varje story bedöms oberoende; en otillåten förflyttning gör inte att de andra misslyckas.

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ölj händelseströmmen

För agenter som vill reagera på vad människor gör, pollar du events-endpointen:

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 är { items, next_since_id, next_cursor }: varje händelse bär aktören, resursen och ändringen. Spara next_since_id och skicka tillbaka det som since_id vid nästa poll för att återuppta där du slutade (since accepteras som ett äldre alias). Inga webhooks, ingen skrapning, inga missade händelser. Strömmen kräver rollen member — en viewer får 403.

Sök

GET /projects/{id}/search?q=<query> kör en kraftfull fritext- och strukturerad sökning över projektets stories. Frågespråket är modellerat efter GitHubs kvalificerare för issue-sökning — så syntax som du (eller en AI-agent) redan kan från GitHub fungerar för det mesta här också.

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 är ett JSON-kuvert med stories rangordnade efter relevans när frågan innehåller fritext, och annars i tavlans ordning:

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

total är hela antalet träffar, inte sidstorleken. Paginera med limit (standard 50, max 1000) och offset; sortera med sort=relevance (standard), created, created_asc, updated eller state.

Grammatik

Fritext matchar en storys titel, referens och beskrivning (fritext, stamformad och rangordnad). Omslut en exakt fras med "citattecken".
Kvalificerare har formen field:value. Separera alternativ med komma (OR inom ett fält): type:bug,chore. Separera kvalificerare med blanksteg (AND mellan dem).
Negera valfri term eller kvalificerare med ett inledande -: -label:wontfix.
Intervall för datum och poäng: inklusivt a..b, eller öppet >x / <x.

Kvalificerare

Kvalificerare	Exempel	Matchar
`type:`	`type:bug,chore`	story-typ(er)
`state:`	`state:started,finished`	arbetsflödestillstånd
`label:`	`label:"my label"`	en etikett
`epic:`	`epic:"Checkout"`	stories i en epic
`priority:`	`priority:p1`	prioritet
`points:`	`points:3` · `points:1..5` · `points:>3`	estimatvärde eller intervall
`iteration:`	`iteration:42`	iterations-id
`created:` `updated:` `started:` `completed:` `release:`	`created:2026-05-01..2026-06-01` · `updated:>2026-06-01`	ett datum eller intervall (dagsgranularitet); `release:` är storyns släppdatum
`owner:` `requester:` `follower:` `reviewer:` `commenter:` `mention:`	`owner:claire` · `owner:@me`	en person via namn eller e-post — medlemmar och agenter, `mention:` inräknad; `@me` är du (med en agentnyckel, den medlem som skapade nyckeln)
`has:blocker`	`has:blocker`	har en öppen blockerare
`is:`	`is:unestimated` · `is:icebox` · `is:backlog` · `is:blocked`	en flagga

mywork: är ett alias för owner: — mywork:me är owner:@me. Den äldre kvalificeraren scheduled: är utfasad och ignoreras tyst; använd release:.

Komma-OR (type:bug,chore) gäller facettkvalificerarna; personkvalificerarna (owner: requester: follower: reviewer: commenter: mention:) tar ett enda värde.

Exempel

payment crash                              fritext "payment" OCH "crash"
"exact phrase"                             en fras
type:bug,chore state:started               buggar eller chores som är startade
owner:@me -label:wontfix                   mina, exklusive etiketten wontfix
points:3..8 created:2026-05-01..2026-05-31 estimerade 3-8, skapade i maj
follower:tomas has:blocker                 tomas följer den och den är blockerad
is:backlog updated:>2026-06-01             backlog-poster rörda sedan 1 juni

Samma frågesträng driver tavlans sökruta (som öppnar en levande resultatkolumn) och det här API:et — en grammatik för människor och agenter. Att söka i innehållet i kommentarer, tasks och blockerare finns på färdplanen; idag täcker fritext storyns egen titel, referens och beskrivning.

Utforska API:et

Den live OpenAPI 3-specifikationen finns på:

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

Swagger UI finns på:

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

/openapi.json och /docs är oautentiserade — en agent kan läsa kontraktet innan den har en nyckel. När den väl har en nyckel returnerar /api/v1/meta (som kräver en giltig nyckel) dess identitet och övergångsgrafen per story-typ; uppslagen av referensdata (/story_types, /story_states, /effort_scales, /priority_scales) är också oautentiserade. Tillsammans låter de agenter svara på “vad kan jag göra här?” utan att råka ut för 403:or genom trial-and-error.

Den serverade openapi.json bär request-body-scheman för skriv-endpointerna, inklusive varje fälts maxLength, så att en klient kan validera innan den skickar. Specifikationen sammanfattar samma former.

Importera från en annan tracker

Om du skriptar en bulkmigrering:

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"

Filkällor som stöds: pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json, eat (East Agile Trackers egen export — formatet för fram-och-tillbaka). Multipart-endpointen körs synkront och svarar med resultaträknarna.

GitHub importerar från API:et istället för en fil, via JSON-endpointen — ingen file, bara repository-koordinaterna:

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-endpointen är asynkron: den svarar 202 med { "import_id", "status" } och du pollar GET /projects/{id}/imports/{import_id} tills jobbet når done eller failed. Bara en import körs per projekt åt gången — ett andra anrop medan en pågår ger 409 import_already_running. Hela loopen, med jobbets förloppsfält, finns i Fyll ett projekt från ett GitHub-repo.

token är valfri i anropet, men själva hämtningen autentiserar sig alltid — den går via GitHubs GraphQL-API, som saknar anonym nivå. Utelämna token så sätter servern in sin plattforms-token: endast publika repositoryn, delad av varje anropare och avvisad med import_github_shared_quota_low när dess GraphQL-budget sjunker under 500 poäng. Ett privat repository, eller en driftsättning som inte konfigurerat någon plattforms-token (import_github_no_token), kräver din. Vilken token som än används går den bara till de utgående GitHub-anropen och lagras eller ekas aldrig tillbaka. Alla detaljer, inklusive GitHubs oautentiserade REST-tak på 60 förfrågningar, finns i Fyll ett projekt från ett GitHub-repo.

Dry-run-förhandsvisning. Lägg till "dry_run": true (JSON) eller -F "dry_run=true" (multipart) till valfri källa. Importen tolkar, resolvar och av-dubblerar precis som en verklig körning, ger samma resultaträknare (imported, skipped, errors, unmatched) och rullar sedan tillbaka allt — ingenting skrivs. På JSON-endpointen kommer räknarna på det pollade jobbet, torrkörning eller inte.

Gränser. En importfil är begränsad till 10 MiB och 5 000 stories (400 import_too_large / import_too_many_records, ingenting skrivs); en GitHub-import har inget tak för antalet stories. Att importera om en fil är säkert — rader som redan importerats (matchade på käll-id) hoppas över, inte dubbleras.

Exportera ett projekt

Vilken projektroll som helst kan lista formaten; att ladda ner ett kräver rollen manager:

# The registered export formats: { 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 one format (eat is the full-fidelity round-trip CSV)
curl https://api.eastagiletracker.com/api/v1/projects/$PROJECT_ID/export/eat \
  -H "X-TrackerToken: $TRACKER_TOKEN" -o project-export.csv

Id:n för utbytesformat: eat, jira, pivotal, shortcut, trello, asana, gitlab, linear, plane, plane_json, plus dokumentformaten pdf och docx. Varje bilaga går att ladda ner som en zip från GET /projects/{id}/export/attachments.

Felformat

Alla fel är JSON med minst:

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

Många felsvar innehåller också ett details-objekt — details.fields (en array av felande fältnamn) vid validation_failed, och details.allowed (tillsammans med from/to) vid 422 invalid_transition. Använd dem. En 429 rate_limited bär en Retry-After-header i samma JSON-kuvert.

Paginering

List-endpoints accepterar limit och cursor. Cursor är ogenomskinlig; skicka next_cursor från föregående svar. Taket för limit är per endpoint — 200 för stories, kommentarer och projekt, 500 för events, 1000 för granskningsloggen; sök paginerar med limit (≤ 1000) och offset. En vanlig lista (utan cursor) som var tvungen att kapa sitt svar säger det i headers: X-Tracker-Pagination-Truncated, -Limit, -Offset och -Next-Offset, som du skickar tillbaka som offset= för nästa sida. Det finns ingen header med totalantal.

Vad händer härnäst

API-specifikation — Varje endpoint, varje verb, varje form.
Bruksanvisning → Agenter — På gränssnittssidan: skapa agentnycklar, namnge agenter, återkalla.
Introduktion — Koncepten bakom API:et: stories, tillstånd, iterationer, velocity, agenter.