API-guide

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 → Agents. 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 → 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://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: $TRACKER_TOKEN"

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

curl https://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://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 eventuella standardvärden som servern tillämpade (estimeringsskala, klart-tillstånd osv.).

Skapa 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 ä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://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. För att sätta en avvisad story i arbete igen, POST …/stories/{sid}/restart; POST …/stories/{sid}/reject är verbformen för att avvisa en levererad story.

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

Idempotenta skrivningar

Varje skriv-endpoint accepterar en Idempotency-Key-header. Gör om samma nyckel med samma body och få samma svar tillbaka. Gör om samma nyckel med en annan body och 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" }'

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.

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://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://eastagiletracker.com/api/v1/projects/$PROJECT_ID/events?since=$LAST_CURSOR&types=story.created,story.transitioned,comment.added" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

Svaret är en cursor-paginerad ström av händelser med aktören, resursen och ändringen. Varje händelse har ett ID; skicka det senaste ID:t du sett som since för att återuppta där du slutade. 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://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:

{ "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
`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-06-01 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.

WebSocket-styrning

För interaktiv automatisering — att driva en inloggad webbläsarsession från ett skript, eller fjärrstyra gränssnittet för handledningar — finns det 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 är webbläsarsessionens JWT, inte en API-nyckel — en ea_user_*- eller ea_agent_*-nyckel avvisas före uppgraderingen. De flesta användare behöver aldrig detta; det finns för de fall där REST inte räcker.

Importera från en annan tracker

Om du skriptar en bulkmigrering:

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"

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://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 uppladdnings-body är begränsad till 10 MiB, och en enskild import till 5 000 stories; att överskrida någondera ger en 400 utan att något skrivs. 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 är endast för owners:

# The registered export formats: { id, name, content_type, drops, includes_archived }
curl https://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://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 sök och granskningsloggen. 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.