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.

Två sorters nycklar

Du autentiserar med en API-nyckel i X-TrackerToken-headern. Det finns två sorter:

• 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 som projektägare under Project Settings → Agents. Använd dem för AI-agenter — Claude Code, Codex, dina egna — som ska delta i projektet som namngivna lagkamrater.

Skillnaderna:

	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 eller member)
Återkallande	Återkalla en nyckel; du behåller åtkomst via andra nycklar/sessioner	Återkalla 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"]
  }'

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.

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.created" \
  -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.

Sök med filtersyntaxen

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

Tillgängliga filter:

Filter	Exempel	Beskrivning
type:	type:feature	Filtrera på story-typ
state:	state:started	Filtrera på tillstånd
label:	label:"my label"	Filtrera på etikett
owner:	owner:claire	Filtrera på ägare
requester:	requester:tomas	Filtrera på beställare
has:	has:blocker	Stories med blockerare
is:	is:unestimated	Oestimerade features

Fritext matchar titeln och beskrivningen. Kombinera filter genom att separera dem med blanksteg — de AND:as ihop.

Utforska API:et

Den live OpenAPI 3-specifikationen finns på:

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

Swagger UI finns på:

https://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) ä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.

Obs: den serverade openapi.json listar sökvägar men levererar för närvarande tomma request-bodies — använd fältformerna i Specifikationen för skrivningar.

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

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"

Källor som stöds: pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json.

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.

Paginering

List-endpoints accepterar limit och cursor. Cursor är ogenomskinlig; skicka next_cursor från föregående svar. Svarsheaders inkluderar även X-Tracker-Pagination-Total för totalantal där det är billigt att beräkna.

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.