Den kompletta REST-endpoint-referensen. För handledningar och exempel, se API-guiden.
Allt en projektmedlem kan göra i webbgränssnittet finns tillgängligt här — SPA:n använder samma API. Operationer som kräver manager-rollen är markerade (manager); allt annat kräver enbart projektmedlemskap (eller, för läsningar markerade (viewer), vilken åtkomstnivå som helst). Tabellerna nedan namnger varje ruttgrupp som servern monterar; de som sammanfattas på en enda rad beskrivs fullständigt i den live openapi.json.
https://eastagiletracker.com/api/v1https://api.eastagiletracker.com/api/v1 betjänar det identiska API:et. Alla requests och svar är JSON, förutom några fil-uppladdnings-endpoints som accepterar multipart.
Två grupper ligger en nivå upp, under /api i stället för /api/v1: autentiseringsytan (/api/auth/*) och de publika formulären (/api/contact, /api/feedback). Deras /api/v1/…-varianter returnerar 404.
Autentisering
Section titled “Autentisering”Varje autentiserad request skickar en inloggningsuppgift via något av:
X-TrackerToken: <key>Authorization: Bearer <key>
Användarnycklar börjar med ea_user_, agentnycklar med ea_agent_ och MCP-åtkomsttokens med ea_mcp_. Se API-guide → Tre sorters inloggningsuppgifter.
Oautentiserade endpoints: /openapi.json, /docs, /api/auth/*-endpointerna och uppslagen av referensdata (/story_types, /story_states, /effort_scales, /priority_scales). /meta är autentiserad — vilken giltig nyckel som helst fungerar, men den är inte projektavgränsad (en projektbunden agentnyckel når den också).
Roller
Section titled “Roller”Fyra nivåer styr projektavgränsade endpoints:
| Nivå | Vem passerar | Typiska operationer |
|---|---|---|
| public viewer | vem som helst, på ett projekt vars synlighet är publik | läsningar av boarden: stories, iterationer, sökning, story- och epic-aktivitet (med aktörsuppgifterna maskerade) |
| viewer | viewer, member, manager | läsningar (lista/hämta stories, sökning, mätvärden, listan över exportformat) |
| member | member, manager | alla skrivningar av arbetsposter (stories, tasks, kommentarer, …), händelseströmmen |
| manager | endast manager | projektinställningar, medlemshantering, agentnycklar, radering, import, exportnedladdningar, säkerhetskopior, granskningslogg |
Agenter har samma roller som medlemmar — viewer, member eller manager — med den medlem som präglade nyckeln som tak. En icke-medlem får 404 unfound_resource (inte 403) på privata projektsökvägar, så projekt-ID:n går inte att räkna upp.
Självbeskrivande endpoints
Section titled “Självbeskrivande endpoints”| Method | Path | Beskrivning |
|---|---|---|
| GET | /openapi.json | Den live OpenAPI 3-specifikationen, inklusive request-bodies. Oautentiserad. |
| GET | /docs | Swagger UI. Oautentiserad. |
| GET | /meta | Anroparens identitet (auth.kind/key_id/agent_id/project_id) + övergångsgrafen per story-typ. Autentiserad (vilken giltig nyckel som helst; inte projektavgränsad). Anropa detta först. |
| GET | /api/health · /api/config | Liveness, och driftsättningens publika konfiguration (enkelorganisationsläge, vilka valfria funktioner som är på, instansens namn). Oautentiserad, utanför /v1. |
Auth (/api/auth/*, utanför /v1)
Section titled “Auth (/api/auth/*, utanför /v1)”Sessions-endpoints, oautentiserade om inget annat anges. SPA:n driver dessa; skript använder normalt en API-nyckel i stället.
| Method | Path | Beskrivning |
|---|---|---|
| POST | /auth/register | Registrera ett nytt konto — skyddat av reCAPTCHA; kontot passerar sedan SMS-utmaningen |
| POST | /auth/sms/challenge · /auth/sms/status · /auth/sms/bypass | Skicka / kontrollera SMS-koden vid registrering (bypass styrs av operatören) |
| GET | /auth/config | Vilka inloggningsmetoder driftsättningen erbjuder |
| POST | /auth/login | Logga in med e-post + lösenord; returnerar en sessions-JWT, eller en TOTP-utmaning |
| POST | /auth/login/totp | Slutför en inloggning med en kod från autentiseringsappen eller en recovery code |
| POST | /auth/passkey/login/start · /auth/passkey/login/finish | Lösenordsfri WebAuthn-inloggning |
| GET | /auth/oauth/github/start · /auth/oauth/github/callback · /auth/oauth/google/start · /auth/oauth/google/callback · POST /auth/oauth/exchange | OAuth-inloggning med GitHub eller Google |
| POST | /auth/refresh · /auth/refresh/revoke | Rotera refresh-token / återkalla den |
| POST | /auth/logout | Logga ut (återkallar refresh-token) |
| POST | /auth/forgot-password · /auth/reset-password | Begär ett återställningsmejl / använd återställnings-token |
| POST | /auth/accept-invite/lookup · /auth/accept-invite | Slå upp en inbjudnings-token → e-post / acceptera projektinbjudan (efter autentisering) |
Konto / identitet
Section titled “Konto / identitet”Dessa agerar på anroparen och kräver enbart en giltig nyckel (ingen projektroll).
| Method | Path | Beskrivning |
|---|---|---|
| GET | /me | Aktuell användarprofil |
| PUT | /me | Uppdatera profil |
| DELETE | /me | Radera konto — nekas medan du är ensam owner för en organisation eller för ett projekt med andra medlemmar |
| GET | /me/deletion-impact | Vad en radering av kontot skulle ta bort och vad som blockerar den |
| PUT | /me/password | Byt lösenord |
| PUT | /me/settings | Uppdatera inställningar (tema, notisinställningar) |
| POST | /me/avatar | Ladda upp avatar (multipart) |
| POST | /me/api-token/regenerate | Rotera din API-token — ogiltigförklarar befintliga sessioner/nycklar |
| GET | /me/api_keys · POST /me/api_keys · DELETE /me/api_keys/{id} | Hantera användar-API-nycklar (ea_user_) |
| GET | /me/totp · POST /me/totp/setup · /me/totp/verify · /me/totp/disable | Registrering av tvåfaktor (TOTP); verify returnerar recovery codes en gång |
| GET | /me/passkeys · POST /me/passkeys/register/start · /me/passkeys/register/finish · DELETE /me/passkeys/{credential_id} | Registrering och borttagning av passkeys |
| GET | /me/oauth_grants · DELETE /me/oauth_grants/{grant_id} | Anslutna appar — de MCP-klienter och OAuth-appar du har auktoriserat |
| GET | /me/activity | Din aktivitet över alla projekt |
| GET | /me/stories | Stories du äger, har beställt eller följer i alla projekt som token når — role=owned|requested|following, state=, cursor= / limit= (max 200) |
| GET | /me/mentions · POST /me/mentions/{mention_id}/ack | @-omnämnande-inkorgen (unacked=true för att filtrera) och kvittering — ingår också i notisflödet nedan |
| GET | /me/data-export | GDPR-självexport av dina data |
| GET | /me/consent · POST /me/consent | Läs / registrera samtycke ({ consent_type, granted }) |
| GET | /legal/pending · POST /legal/accept | Väntande clickwrap-dokument / registrera godkännande |
| GET / PUT | /agent/me | En agentnyckels egen identitet och profil, läsbar och redigerbar av agenten (agentsidans motsvarighet till /me) |
| POST | /api/contact · /api/feedback · /api/feedback/with-screenshot | Kontakt + feedback i appen. Utanför /v1; hastighetsbegränsat per IP |
Referensdata (oautentiserad)
Section titled “Referensdata (oautentiserad)”Seed-uppslag som används när stories skapas/estimeras. Stabila ID:n.
| Method | Path | Beskrivning |
|---|---|---|
| GET | /story_types | feature, bug, chore, release (+ allow_points) |
| GET | /story_states | unstarted … accepted, rejected |
| GET | /effort_scales | tillgängliga estimeringsskalor |
| GET | /effort_scales/{scale_id}/values | poängvärdena i en skala |
| GET | /priority_scales · /priority_scales/{scale_id}/values | prioritetsskalorna och deras värden (priority_id på en story slås upp här) |
Organisationer
Section titled “Organisationer”Endast den hostade tjänsten — en self-hostad installation körs i enkelorganisationsläge och monterar inte dessa (utom organisationslistan). Rollerna är organisationsroller: owner, admin, member.
| Method | Path | Beskrivning |
|---|---|---|
| GET / POST | /organizations | Lista dina organisationer / skapa en |
| GET / PUT / DELETE | /organizations/{oid} | Läs, byt namn (namn + slug; owner eller admin), radera |
| GET / POST | /organizations/{oid}/memberships · PUT / DELETE …/memberships/{member_id} | Medlemmar och inbjudningar; inbjudningar har ett rolltak (aldrig över anroparens; owner bjuds aldrig in) |
| POST | /organizations/{oid}/memberships/bulk-role · …/memberships/bulk-remove | Ändra roll för eller ta bort upp till 200 medlemmar på en gång. Allt eller inget: en batch som skulle ta bort den sista ownern eller lämna ett projekt utan ägare avvisas helt; med reassign_confirmed blir du i stället ägare till de projekten |
| DELETE | /organizations/{oid}/invitations/{invitation_id} | Återkalla en väntande inbjudan |
| POST | /organizations/{oid}/transfer-ownership | Lämna över owner-rollen till en annan medlem |
| PUT | /organizations/{oid}/memberships/{member_id}/anonymization | Maskera en medlems namn / e-post / avatar i hela organisationen |
| GET | /organization-invitations/{token} · POST …/{token}/accept | Slå upp / acceptera en e-postad organisationsinbjudan |
| POST | /organizations/{oid}/export · GET / POST …/export/jobs · GET …/export/jobs/{job_id} · …/export/jobs/{job_id}/download | Organisationsexport endast för owners: en zip med en SQL-dump och varje bilaga, körd som ett jobb |
Projekt
Section titled “Projekt”| Method | Path | Beskrivning |
|---|---|---|
| GET | /projects | Lista dina projekt (limit ≤ 200) |
| POST | /projects | Skapa ett projekt |
| GET | /projects/{id} | Hämta projektdetaljer (viewer) |
| PUT | /projects/{id} | Uppdatera projektinställningar (manager) |
| DELETE | /projects/{id} | Radera ett projekt (manager) |
| POST | /projects/{id}/pin | Fäst / lossa projektet i din projektlista |
| POST | /projects/{id}/transfer-organization | Flytta projektet till en annan organisation (manager) |
| POST | /projects/{id}/slack/test | Skicka ett testmeddelande till projektets Slack-flöde (manager) |
| GET / POST | /projects/{id}/showcase_claim_eligibility · /projects/{id}/showcase_claim · /projects/{id}/showcase_seed | Publika showcase-projekt: kontrollera om du kan göra anspråk på ett, gör anspråk på det, seeda det |
| GET | /projects/{id}/audit-log | Läsning av audit-loggen — projekthistorik plus aktivitet per story / per epic via surface=; åtkomsten varierar per surface, se nedan |
| GET | /projects/{id}/events | Cursor-paginerad händelseström (member) — se Händelser |
Query-parametrar för audit-loggen: event_type= (en typ eller kommaseparerad lista), limit= (≤ 1000), before= (keyset-cursor, ISO-8601 created_at), surface= (project_history, story_activities, epic_activities), target_id= (story-/epic-id — krävs när surface=story_activities eller epic_activities). Åtkomst: den ofiltrerade loggen och surface=project_history är (manager); story_activities / epic_activities kan läsas av alla projektmedlemmar, och anonymt på publika projekt med aktörens PII maskerad.
Medlemmar, agenter och agentnycklar
Section titled “Medlemmar, agenter och agentnycklar”| Method | Path | Beskrivning |
|---|---|---|
| GET | /projects/{id}/memberships | Lista medlemmar (viewer) |
| POST | /projects/{id}/memberships | Bjud in en medlem via e-post (manager) |
| PUT | /projects/{id}/memberships/{mid} | Uppdatera roll (manager) |
| DELETE | /projects/{id}/memberships/{mid} | Ta bort en medlem (manager) |
| GET | /projects/{id}/addable-members · POST /projects/{id}/members/add-existing | Organisationsmedlemmar som ännu inte är med i projektet / lägg till en utan e-postinbjudan (manager) |
| POST | /projects/{id}/members/join | En owner eller admin i organisationen går med i ett projekt i sin organisation som manager, eller befordrar sig själv till det (åtgärden Make me owner i projektlistan) |
| PUT | /projects/{id}/members/{mid}/anonymization | Maskera en medlems namn / e-post / avatar i det här projektet (manager) |
| GET / POST | /projects/{id}/agent_keys | Lista / prägla agentnycklar — managers, eller de roller som projektets creator-roles policy släpper in |
| DELETE | /projects/{id}/agent_keys/{kid} | Återkalla en agentnyckel |
| GET | /projects/{id}/agent_keys/onboarding | Onboarding-paketet: prompter och konfigurationsfiler för de vanliga agentklienterna |
| GET | /projects/{id}/agents · GET / PUT /projects/{id}/agents/{aid} | Projektets agenter och deras profiler (namn, initialer, beskrivning, färg) |
| POST | /projects/{id}/agents/{aid}/rotate-key · /projects/{id}/agents/{aid}/avatar | Rotera en agents nyckel (identitet och historik behålls) / ladda upp dess avatar |
Stories
Section titled “Stories”Alla story-skrivningar kräver member-rollen.
| Method | Path | Beskrivning |
|---|---|---|
| GET | /projects/{id}/stories | Lista stories (paginerade, filtrerbara) (viewer) |
| POST | /projects/{id}/stories | Skapa en story |
| GET | /projects/{id}/stories/{sid} | Hämta en story (viewer) |
| PUT | /projects/{id}/stories/{sid} | Uppdatera en story |
| DELETE | /projects/{id}/stories/{sid} | Radera en story |
| POST | /projects/{id}/stories/{sid}/transitions | Ändra tillstånd med validering |
| POST | /projects/{id}/stories/{sid}/reject · /projects/{id}/stories/{sid}/restart | Avvisa en levererad story / sätt tillbaka en avvisad till started (rejected är ett sluttillstånd för /transitions) |
| POST | /projects/{id}/stories/{sid}/archive · /projects/{id}/stories/{sid}/unarchive | Arkivera / avarkivera en story |
| POST | /projects/{id}/stories/bulk_transition | Transitionera många stories (1–100) på en gång |
| POST | /projects/{id}/stories/bulk-archive · bulk-delete · bulk-duplicate · bulk-move | Arkivera, radera, duplicera eller flytta (till en panel / position) många stories |
| POST | /projects/{id}/stories/{sid}/duplicate | Duplicera en story |
| GET / POST / DELETE | /projects/{id}/stories/{sid}/epics · …/epics/{eid} | Storyns epic-medlemskap |
| GET | /short-links/{code} · /story-references | Slå upp en /s/<code>-kortlänk till dess story / slå upp upp till 100 story-referenser (#id, URL:er) till de stories anroparen kan läsa |
Frågeparametrar för story-listan: archived= (exclude som standard / include / only — det trelägiga arkivfiltret; ersätter det utfasade include_archived=true, som nu är ett alias för archived=include), include_done=true (tar med stories från Done-panelen frysta på tidigare iterationer, exkluderade som standard). Paginering (cursor= / limit= / offset=) och glesa fältmängder (fields=) följer Paginering och Fältprojektion.
Skapa (POST …/stories): { "name" (required), "story_type": "feature|bug|chore|release", "description"?, "estimate"?, "current_state"?, "icebox"?, "labels"? }. estimate är skalvärdets etikett som en sträng ("3", "13"); ett JSON-nummer avvisas. labels accepterar ["auth"] eller [{ "name": "auth" }]; okända etiketter skapas. Standardvärden: story_type=feature, current_state=unstarted.
Uppdatera (PUT …/stories/{sid}): samma fält, alla valfria, plus "position" (float), "force_state_change" (bool) och "expected_updated_at" (RFC 3339 — en sparning av beskrivningen nekas med 409 stale_write om storyn har ändrats sedan du läste den). Story-skrivningar respekterar också If-Match mot storyns ETag; en avvikelse ger 412 precondition_failed.
Transition (POST …/transitions): { "to": "<state>" }. Fältet är to. Returnerar { story_id, state }. Otillåten förflyttning → 422 invalid_transition med details: { from, to, allowed }.
Bulk-transition (POST …/bulk_transition): { "story_ids": [int,…] (1–100), "to": "<state>" }. Varje story bedöms oberoende; returnerar { results: [ { id, status: "ok" } | { id, status: "failed", error } ] }.
Underresurser till story
Section titled “Underresurser till story”Alla member. List/GET på de flesta är (viewer).
| Method | Path | Body / anmärkningar |
|---|---|---|
| GET / POST | /projects/{id}/stories/{sid}/tasks · PUT/DELETE …/tasks/{tid} | { description (or task_desc), complete?, task_order? } |
| GET / POST | /projects/{id}/stories/{sid}/comments · PUT/DELETE …/comments/{cid} | { text (or comment_text) } eller { comment_emoji }. GET tar fields= (tillåtelselista: comment_id, story_comment_id, story_id, comment_text, comment_emoji, member, created) plus cursor= / limit= (≤ 200) / order=asc|desc |
| GET / POST | /projects/{id}/stories/{sid}/blockers · PUT/DELETE …/blockers/{bid} | { blocker_desc, resolved? } |
| GET / POST | /projects/{id}/stories/{sid}/links · PUT/DELETE …/links/{lid} | { url, link_type?, title? } — link_type ∈ relates_to, duplicates, blocks, is_blocked_by, pull_request, branch, other; GitHub-URL:er med /pull/ och /tree/ typas automatiskt |
| GET / POST | /projects/{id}/stories/{sid}/reviews · PUT/DELETE …/reviews/{rid} | Skapa: { reviewer_id? / reviewer_agent_id?, comment? } — utelämna båda för att tilldela dig själv. Uppdatera: { status, comment? } |
| GET / POST | /projects/{id}/stories/{sid}/owners · DELETE …/owners/{mid} · DELETE …/owners/agents/{aid} | { member_id? / agent_id? } — utelämna båda för att lägga till anroparen |
| GET / POST | /projects/{id}/stories/{sid}/followers · DELETE …/followers/{mid} · DELETE …/followers/agents/{aid} | { member_id? / agent_id? } |
| GET / POST | /projects/{id}/stories/{sid}/labels · DELETE …/labels/{lid} | { name } |
| GET / POST | /projects/{id}/stories/{sid}/attachments (+ /json) · DELETE …/attachments/{aid} | multipart-uppladdning — video ≤ 200 MB, PDF / Word / Excel ≤ 25 MB, bilder / CSV / text ≤ 10 MB; listning är (viewer) |
| GET / POST | /projects/{id}/stories/{sid}/link-attachments · DELETE …/link-attachments/{laid} | Länkbilagor — en extern URL som förvaras bredvid filbilagorna i stället för som en kodlänk |
| GET | /attachments/{token} · /api/avatars/{token} | Token-adresserade läsningar av en bilaga eller en avatar — de URL:er som API:et delar ut; ingen X-TrackerToken behövs |
Samma form som stories, minus tillståndsmaskinen. member för skrivningar, (viewer) för läsningar.
| Method | Path | Beskrivning |
|---|---|---|
| GET / POST | /projects/{id}/epics · GET / PUT / DELETE …/epics/{eid} | Epics har ett namn, en Markdown-beskrivning och en underliggande etikett som knyter ihop deras stories |
| GET / POST / PUT / DELETE | …/epics/{eid}/comments · …/comments/{cid} | Epic-kommentarer |
| GET / POST / DELETE | …/epics/{eid}/owners · …/followers (+ /agents/{aid}-varianter) | Ägare och följare, medlemmar eller agenter — en epics ägare förs vidare till dess stories |
| GET / POST / DELETE | …/epics/{eid}/attachments (+ /json) · …/link-attachments | Bilagor, samma gränser som för stories |
| GET | /projects/{id}/analytics/epics · …/analytics/epics/{eid} | Framsteg per epic: burnup, genomströmning, hälsa, prognos (viewer) |
Etiketter
Section titled “Etiketter”member för skrivningar, (viewer) för läsningar.
| Method | Path | Beskrivning |
|---|---|---|
| GET / POST | /projects/{id}/labels | Lista / skapa en etikett |
| PUT / DELETE | /projects/{id}/labels/{lid} | Uppdatera / radera en etikett |
| POST | /projects/{id}/labels/{lid}/archive | Arkivera (mjukt dölja) en etikett |
Iterationer
Section titled “Iterationer”Läsningar är öppna för alla projektroller, och anonyma på ett publikt projekt.
| Method | Path | Beskrivning |
|---|---|---|
| GET | /projects/{id}/iterations | Lista iterationer (≤ 500 per sida; bär en ETag och X-Tracker-Pagination-*-fortsättningsheadrarna vid trunkering) |
| GET | /projects/{id}/iterations/{itid} | En iteration |
| GET | /projects/{id}/iterations/first-preview | De datum som den första iterationen skulle få, visade i seed-bekräftelsen |
| POST | /projects/{id}/iterations | Skapa en manuell iteration (member) |
| DELETE | /projects/{id}/iterations/{itid} | Radera en iteration (manager) |
| PUT | /projects/{id}/iterations/{itid}/velocity | Åsidosätt en iterations velocity utan att ändra projektets strategi (manager) |
| GET | /projects/{id}/iterations/{itid}/done-stories | De accepterade stories i en stängd iteration, paginerade |
Sökning, mätvärden, inställningar
Section titled “Sökning, mätvärden, inställningar”| Method | Path | Beskrivning |
|---|---|---|
| GET | /projects/{id}/search?q=… | Kraftfull sökning — fulltext + kvalificerare för facetter / datumintervall / personer (GitHub-liknande DSL); returnerar { results, total, limit, offset }. query är ett alias för q; limit= (standard 50, max 1000) / offset= paginerar; sort= sorterar efter relevance (standard), created, created_asc, state eller updated. (viewer) — se Guiden |
| GET | /projects/{id}/metrics/{velocity,burndown,story-types,contributors} | Metrics-sidans dataserier (viewer); epic-mätvärden finns under /analytics/epics ovan |
| GET | /projects/{id}/backlog/grouping | Backlogens projicerade iterationsgrupper (viewer) |
| GET / PUT | /projects/{id}/preferences | Dina board-inställningar för detta projekt — alla projektroller, bara din egen rad |
Händelser
Section titled “Händelser”| Method | Path | Beskrivning |
|---|---|---|
| GET | /projects/{id}/events | Cursor-paginerad händelseström (member) — viewers får 403 |
Query-parametrar: since=<event_id>, types=story.created,story.transitioned,comment.added,…, limit= (≤ 500), cursor=. Svaret inkluderar next_cursor. Skicka det senaste event_id du sett som since för att återuppta.
Notiser
Section titled “Notiser”Det samlade notisflödet i appen: fullvärdiga notisrader (granskningsförfrågningar, story-aktivitet, inbjudningar, …) sammanslagna med @-omnämnande-inkorgen till en enda ström, nyast först. Flödes-id:n har källprefix (nt-… / sc-… / ec-…). Medlemssessioner och ea_user_*-nycklar läser sina medlemsrader; ea_agent_*-nycklar sina agentrader.
| Method | Path | Beskrivning |
|---|---|---|
| GET | /me/notifications | Ditt notisflöde. Filter: unread=true, since_id=, kind= (mentions / reviews / stories / invitations); paginera med cursor= / limit= |
| GET | /me/notifications/unread-count | Olästa totaler — { unread_count, by_category: { mentions, reviews, stories, invitations } } |
| POST | /me/notifications/read-all | Markera allt som läst; returnerar de färska räknarna |
| POST | /me/notifications/{id}/ack | Markera ett objekt som läst (idempotent) |
| POST | /me/notifications/{id}/accept | Acceptera en projekt-/organisationsinbjudan från flödet (endast medlemstoken) |
| POST | /me/notifications/{id}/decline | Avböj en projekt-/organisationsinbjudan (endast medlemstoken) |
| GET | /me/notifications/resolve-invite?token=… | Slå upp ett e-postat inbjudningstoken till ditt notis-id — { "id": "nt-…" } eller { "id": null } |
| GET | /me/notifications/stream | Live-push — Server-Sent Events (text/event-stream); se nedan |
Stream-endpointen är ingen JSON-endpoint och finns därför inte i OpenAPI-specifikationen: den håller anslutningen öppen och skickar en ram utan payload ({"type":"notification","kind":…}) så fort något nytt landar, som en signal till klienten att hämta om flödet. Anslutningar avslutas på serversidan efter 45 minuter — återanslut och autentisera igen. Endast medlemssessioner och ea_user_*-nycklar; ea_agent_*-nycklar får 403.
Import (manager)
Section titled “Import (manager)”| Method | Path | Beskrivning |
|---|---|---|
| POST | /projects/{id}/import | Filkällor: source= ∈ pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json, eat. Multipart file=. Synkron — svarar med resultaträknarna. |
| POST | /projects/{id}/import/json | JSON-body; source=github behöver ingen fil — owner, repo, valfri token och opt-in-flaggorna include_pull_requests / include_milestones / include_releases / include_dependencies; filkällorna skickar file_base64. Asynkron: returnerar 202 { import_id, status }. Servern hämtar via GitHubs GraphQL-API, som avvisar anonyma anropare, så en token når alltid GitHub — din, eller driftsättningens delade. Se Guiden. |
| GET | /projects/{id}/imports/{import_id} | Polla ett jobb: status går pending → fetching → writing → done | failed, med progress_current / progress_total under hämtningen och resultaträknarna vid done |
En import körs per projekt åt gången; en andra POST medan en pågår ger 409 import_already_running. dry_run: true (JSON-body eller dry_run=true multipart) förhandsvisar valfri källa: tolkar, resolvar, av-dubblerar, returnerar samma { imported, skipped, errors, unmatched }-räknare och rullar sedan tillbaka — ingenting skrivs. Gränser: 10 MiB body och 5 000 stories per import för de filbaserade källorna (över någondera → 400, ingenting skrivs). GitHub-källan har inget tak — den skriver i block i stället för i en enda transaktion. Återimport är idempotent per käll-id — redan importerade rader hoppas över, inte dubbleras.
Export
Section titled “Export”| Method | Path | Beskrivning |
|---|---|---|
| GET | /projects/{id}/export/formats | Registrerade format: { id, name, content_type, drops, includes_archived }. Alla projektroller. |
| GET | /projects/{id}/export/{format} | Ladda ner ett (manager). Utbyte: eat (full trohet), jira, pivotal, shortcut, trello, asana, gitlab, linear, plane, plane_json; dokument: pdf, docx. |
| GET | /projects/{id}/export/attachments | Varje bilaga som en bläddringsbar zip (filer behåller originalnamn; JSON- + CSV-manifest) (manager). |
Dokumentexporter (pdf, docx) tar extra frågeparametrar: page_size= (letter som standard / a4 / legal / folio), from= / to= (story-fönstrets gränser — RFC 3339 eller bara YYYY-MM-DD; en story är i intervallet när dess created eller completed_at faller inom det), include_icebox= / include_backlog= (båda false som standard, så en delbar export visar bara schemalagt / pågående arbete). CSV-utbytesformaten ignorerar dem.
Säkerhetskopior och återställningar (manager)
Section titled “Säkerhetskopior och återställningar (manager)”| Method | Path | Beskrivning |
|---|---|---|
| GET / POST | /projects/{id}/backups · GET …/backups/{snapshot_id} · …/backups/health | Lista snapshots, ta en nu, läs en, och sammanfattningen av lagringshälsan |
| GET / POST | /projects/{id}/restores · POST …/restores/partial · GET …/restores/{restore_id} | Återställ en hel snapshot, eller valda tabeller från en, och polla återställningen |
POST-anropen ligger på den känsliga hastighetsgränsnivån (nedan).
MCP och OAuth-leverantör
Section titled “MCP och OAuth-leverantör”East Agile Tracker är en OAuth 2.1-leverantör för MCP-klienter. En klient hittar den via /.well-known/oauth-authorization-server och /.well-known/oauth-protected-resource/mcp, skickar dig till /oauth/authorize (samtyckessidan), växlar in koden på /oauth/token och talar sedan MCP på /mcp med den resulterande ea_mcp_*-token. Behörigheter listas och återkallas på /me/oauth_grants. Leverantörens endpoints har en egen hastighetsgränsnivå.
WebSocket
Section titled “WebSocket”wss://eastagiletracker.com/ws/control?token=<session JWT>För interaktiv fjärrstyrning av gränssnittet ({ "action": "get_state", "id": "req-1" }). Token är en sessions-JWT från webbläsaren — en API-nyckel avvisas med 401 före uppgraderingen. Inte en datakanal — alla läsningar/skrivningar går via REST. Endast en instans; inte utspridd över repliker.
Idempotens
Section titled “Idempotens”Skriv-endpoints (POST, PUT, DELETE) accepterar en Idempotency-Key-header. Samma nyckel + samma body spelar upp det cachade svaret (24-timmarsfönster); samma nyckel + en annan body returnerar 409 idempotency_conflict. Nyckeln är avgränsad till den inloggningsuppgift som skickade den. Tillämpas inte på GET/HEAD/OPTIONS, /openapi.json och /docs, /api/auth/* eller multipart-uppladdningar på /attachments-sökvägar. Svar som stannade innan domänen hann svara cachas aldrig — 401, 403, 404, 429 och varje 5xx — så ett omförsök efter något av dem når hanteraren; 400, 409, 412 och 422 är domänens svar och spelas upp som en framgång.
Paginering
Section titled “Paginering”List-endpoints accepterar cursor=<opaque> och limit=<n>. När de är satta är svaret { "items": [...], "next_cursor": "<str|null>" }; skicka tillbaka next_cursor för att bläddra. Taket för limit gäller per endpoint: 200 för stories, kommentarer och projekt; 500 för händelser; 1000 för sökning och granskningsloggen.
En vanlig lista (utan cursor/limit) som var tvungen att trunkera sitt svar anger det i headrar — X-Tracker-Pagination-Truncated, X-Tracker-Pagination-Limit, X-Tracker-Pagination-Offset och X-Tracker-Pagination-Next-Offset; skicka tillbaka den sista som offset= för nästa sida. Det finns ingen header med totalantal.
Fältprojektion
Section titled “Fältprojektion”List-endpoints accepterar fields= (kommaseparerad) för att returnera enbart specifika fält. story_id inkluderas alltid; ett okänt fältnamn returnerar 400 validation_failed med de felande namnen i details.fields.
GET /projects/123/stories?fields=story_id,name,current_state,ownersFelformat
Section titled “Felformat”Varje JSON-fel har code och error; vissa lägger till details:
{ "code": "invalid_transition", "error": "Cannot move story from `unstarted` to `accepted`", "details": { "from": "unstarted", "to": "accepted", "allowed": ["started"] } }| Status | code | När |
|---|---|---|
| 400 | invalid_parameter | felaktig indata; meddelande i error, inga details (de flesta valideringar: blank/längd/null-byte/e-post) |
| 400 | validation_failed | strukturerat indatafel; details.fields är en array av felande fältnamn |
| 401 | unauthenticated | saknad/ogiltig token |
| 403 | unauthorized_operation | autentiserad men otillräcklig roll |
| 404 | unfound_resource | hittades inte — returneras även till icke-medlemmar |
| 409 | conflict | resurskonflikt (t.ex. dubblett) |
| 409 | idempotency_conflict | Idempotency-Key återanvänd med en annan body |
| 409 | stale_write · import_already_running | storyn har ändrats sedan ditt expected_updated_at · en import pågår redan |
| 412 | precondition_failed | If-Match matchade inte resursens aktuella ETag; details bär expected och current |
| 413 | request_too_large | bodyn överskrider ruttens storleksgräns |
| 422 | invalid_transition | otillåten tillståndsförflyttning; details bär { from, to, allowed } |
| 429 | rate_limited | för många requests från denna IP på en hastighetsbegränsad rutt; Retry-After-header |
| 500 | internal_error | serverfel — generiskt meddelande; säkert att försöka igen |
| 503 | not_configured | driftsättningen saknar den integration som rutten behöver (SMS, objektlagring, …) |
details.fields är en JSON-array av fältnamn (t.ex. ["to"]), ibland med extra nycklar som max. Det finns ingen mappning fält→meddelande.
{ "code": "validation_failed", "error": "unknown field(s): foo", "details": { "fields": ["foo"] } }Hastighetsgränser
Section titled “Hastighetsgränser”Per klient-IP, på ett fåtal rutter; autentiserad API-trafik i övrigt är inte hastighetsbegränsad. Standardvärden (varje par är varaktig takt och burst, justerbara av operatören):
- Auth —
/api/auth/*: 0.5 req/s, burst 20. - OAuth-leverantör —
/oauth/*: 1 req/s, burst 60. - Public —
/api/contact: 0.2 req/s, burst 10. - Feedback —
/api/feedback: tre staplade nivåer — en inskickning per 15 s, 10 per timme, 36 per dygn. - Avatarer — den oautentiserade avatar-omdirigeringen: 20 req/s, burst 200.
- Sensitive —
POST-anropen för säkerhetskopiering och återställning: ~0.002 req/s, burst 5.
En överskriden gräns returnerar 429 med en Retry-After-header och det vanliga JSON-felkuvertet, code: "rate_limited".