API-määrittely

Täydellinen REST-päätepisteviittaus. Tutoriaaleja ja esimerkkejä varten katso API-opas.

Kaikki minkä projektin jäsen voi tehdä verkkokäyttöliittymässä on saatavilla täällä — SPA käyttää tätä samaa APIa. Operaatiot, jotka vaativat manager-roolin, on merkitty (manager); kaikki muu vaatii vain projektin jäsenyyttä (tai, lukuoperaatioille jotka on merkitty (viewer), minkä tahansa käyttöoikeustason). Alla olevat taulukot nimeävät jokaisen palvelimen tarjoaman reittiryhmän; yhdellä rivillä tiivistetyt on kuvattu kokonaisuudessaan live-openapi.json-tiedostossa.

Perusta

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

APIlla on oma isäntänsä: eastagiletracker.com tarjoaa verkkosovelluksen ja vastaa poluille /api/v1/… koodilla 404. Kaikki pyynnöt ja vastaukset ovat JSON-muotoa, lukuun ottamatta muutamia tiedostonlatauspäätepisteitä, jotka hyväksyvät multipartin.

Kaksi ryhmää sijaitsee tasoa ylempänä, polun /api alla eikä polun /api/v1 alla: tunnistautumispinta (/api/auth/*) ja julkinen yhteydenottolomake (/api/contact). Niiden /api/v1/…-muodot palauttavat 404.

Tunnistautuminen

Jokainen tunnistautunut pyyntö lähettää tunnisteen yhdellä seuraavista:

• X-TrackerToken: <key>
• Authorization: Bearer <key>

Käyttäjäavaimet alkavat ea_user_, agenttiavaimet ea_agent_ ja MCP-käyttöoikeustokenit ea_mcp_. Katso API-opas → Kolme tunnistetyyppiä.

Tunnistautumattomat päätepisteet: /openapi.json, /docs, /api/auth/*-päätepisteet ja viitedatahaut (/story_types, /story_states, /effort_scales, /priority_scales). /meta on tunnistautunut — mikä tahansa kelvollinen avain toimii, mutta se ei ole projektirajattu (projektiin sidottu agenttiavain tavoittaa sen myös).

Roolit

Neljä tasoa portittaa projektirajattuja päätepisteitä:

Taso	Kuka pääsee	Tyypilliset operaatiot
public viewer	kuka tahansa, projektissa jonka näkyvyys on julkinen	taulun luvut: tarinat, iteraatiot, haku, tarinoiden ja eeppien toiminta (toimijan tiedot peitettyinä)
viewer	viewer, member, manager	luvut (listaa/hae tarinoita, haku, mittarit, vientimuotojen lista)
member	member, manager	kaikki työkohteiden kirjoitukset (tarinat, tehtävät, kommentit, …), tapahtumavirta
manager	vain manager	projektin asetukset, jäsenyyden hallinta, agenttiavaimet, poisto, tuonti, vientien lataukset, varmuuskopiot, tarkastusloki

Agenteilla on samat roolit kuin jäsenillä — viewer, member tai manager — rajattuna avaimen luoneen jäsenen rooliin. Ei-jäsen saa yksityisten projektien poluilla 404 unfound_resource (ei 403), joten projektien ID:t eivät ole lueteltavissa.

Itseään kuvaavat päätepisteet

Metodi	Polku	Kuvaus
GET	/openapi.json	Live OpenAPI 3 -spesifikaatio pyyntörunkoineen. Tunnistautumaton.
GET	/docs	Swagger UI. Tunnistautumaton.
GET	/meta	Kutsujan identiteetti (auth.kind/key_id/agent_id/project_id) + tarinatyypin siirtymägraafi. Tunnistautunut (mikä tahansa kelvollinen avain; ei projektirajattu). Kutsu tätä ensin.
GET	/api/health · /api/config	Elossaolotarkistus sekä asennuksen julkinen konfiguraatio (yhden organisaation tila, käytössä olevat valinnaiset toiminnot, instanssin nimi). Tunnistautumaton, /v1:n ulkopuolella.

Auth (/api/auth/*, /v1:n ulkopuolella)

Istuntopäätepisteet, tunnistautumattomia ellei toisin mainita. SPA käyttää näitä; skriptit käyttävät tavallisesti API-avainta.

Metodi	Polku	Kuvaus
POST	/auth/register	Rekisteröi uusi tili — reCAPTCHA-suojattu; tili läpäisee sen jälkeen tekstiviestivahvistuksen
POST	/auth/sms/challenge · /auth/sms/status · /auth/sms/bypass	Lähetä / tarkista rekisteröitymisen tekstiviestikoodi (ohitus on operaattorin hallinnassa)
GET	/auth/config	Mitä sisäänkirjautumistapoja asennus tarjoaa
POST	/auth/login	Kirjaudu sisään sähköpostilla + salasanalla; palauttaa istunto-JWT:n tai TOTP-haasteen
POST	/auth/login/totp	Viimeistele sisäänkirjautuminen todennussovelluksen koodilla tai palautuskoodilla
POST	/auth/passkey/login/start · /auth/passkey/login/finish	Salasanaton WebAuthn-sisäänkirjautuminen
GET	/auth/oauth/github/start · /auth/oauth/github/callback · /auth/oauth/google/start · /auth/oauth/google/callback · POST /auth/oauth/exchange	OAuth-sisäänkirjautuminen GitHubilla tai Googlella
POST	/auth/refresh · /auth/refresh/revoke	Kierrätä refresh-token / mitätöi se
POST	/auth/logout	Kirjaudu ulos (vaatii tunnistautumisen; mitätöi tämän istunnon refresh-tokenin)
POST	/auth/forgot-password · /auth/reset-password	Pyydä palautussähköposti / käytä palautustunnusta
POST	/auth/accept-invite/lookup · /auth/accept-invite	Selvitä kutsutunnus → sähköposti / hyväksy projektikutsu (tunnistautumisen jälkeen)
POST	/auth/oauth/link/preview · …/link/confirm · /auth/oauth/merge/preview · …/merge/confirm	Yhdistä GitHub- tai Google-tili olemassa olevaan tiliin tai yhdistä kaksi tiliä
POST	/auth/email_addresses/primary/preview · …/primary/confirm	Viimeistele ensisijaisen sähköpostin vaihto sähköpostitse lähetetystä vahvistuslinkistä

Tili / identiteetti

Nämä kohdistuvat kutsujaan eivätkä tarvitse projektiroolia. Ne tarvitsevat jäsenidentiteetin — agenttiavain saa vastauksen 401 (agentit käyttävät polkua /agent/me). Tunnistetietoja muuttavat kutsut — salasana, TOTP, pääsyavaimet, tilin poisto, sähköpostin vaihto, tunnuksen uudelleenluonti — tarvitsevat selainistunnon; API-avain saa vastauksen 403.

Metodi	Polku	Kuvaus
GET	/me	Nykyisen käyttäjän profiili
PUT	/me	Päivitä profiili
DELETE	/me	Poista tili — evätään niin kauan kuin olet organisaation ainoa omistaja tai muita jäseniä sisältävän projektin ainoa omistaja
GET	/me/deletion-impact	Mitä tilin poistaminen poistaisi ja mikä estää sen
PUT	/me/password	Vaihda salasana
PUT	/me/settings	Päivitä asetukset (teema, ilmoitusasetukset)
POST / DELETE	/me/avatar	Lataa (multipart) / poista avatarisi
POST	/me/api-token/regenerate	Kirjaa ulos kaikki istunnot ja palauta uusi istuntotunnus; API-avaimiin tämä ei vaikuta
GET / POST	/me/email_addresses · GET …/email_addresses/offers · PUT …/email_addresses/primary	Sähköpostiosoitteesi; ota yhdistetyn palveluntarjoajan osoite vaihtoehtoiseksi; pyydä ensisijaisen vaihtoa (vahvistetaan sähköpostitse)
GET	/me/oauth_identities · DELETE …/oauth_identities/{provider} · POST …/oauth_identities/{provider}/link	Yhdistetyt kirjautumistilit (GitHub, Google): listaa, katkaise yhteys, aloita yhdistäminen
GET	/me/api_keys · POST /me/api_keys · DELETE /me/api_keys/{id}	Hallitse käyttäjän (ea_user_) API-avaimia
GET	/me/totp · POST /me/totp/setup · /me/totp/verify · /me/totp/disable	Kaksivaiheisen tunnistuksen (TOTP) käyttöönotto; verify palauttaa palautuskoodit kerran
GET	/me/passkeys · POST /me/passkeys/register/start · /me/passkeys/register/finish · DELETE /me/passkeys/{credential_id}	Pääsyavainten rekisteröinti ja poisto
GET	/me/oauth_grants · DELETE /me/oauth_grants/{grant_id}	Connected apps — MCP-asiakkaat ja OAuth-sovellukset, joille olet antanut valtuutuksen
GET	/me/activity	Toimintasi kaikkien projektien yli
GET	/me/stories	Tarinat, jotka omistat, joita olet pyytänyt tai joita seuraat kaikissa projekteissa, joihin token ulottuu — role=owned|requested|following, state=, cursor= / limit= (enintään 200)
GET	/me/mentions · POST /me/mentions/{mention_id}/ack	@-mainintojen saapuneet (unacked=true suodattaa) ja kuittaus — yhdistetty myös alla olevaan ilmoitussyötteeseen
GET	/me/data-export	GDPR-itsevienti tiedoistasi
GET	/me/consent · POST /me/consent	Lue / tallenna suostumus ({ consent_type, granted })
GET	/legal/pending · POST /legal/accept	Odottavat clickwrap-asiakirjat / tallenna hyväksyntä
GET / PUT	/agent/me	Agenttiavaimen oma identiteetti ja profiili, agentin luettavissa ja muokattavissa (/me:n agenttipuolen vastine)
POST	/api/contact · /api/v1/feedback · /api/v1/feedback/with-screenshot	Yhteydenotto + sovelluksen sisäinen palaute; IP-kohtainen nopeusrajoitus

Viitedata (tunnistautumaton)

Siemenhaut, joita käytetään tarinoita luotaessa/arvioitaessa. Vakaat ID:t.

Metodi	Polku	Kuvaus
GET	/story_types	feature, bug, chore, release (+ allow_points)
GET	/story_states	unstarted … accepted, rejected
GET	/effort_scales	käytettävissä olevat arviointiasteikot
GET	/effort_scales/{scale_id}/values	asteikon pistearvot
GET	/priority_scales · /priority_scales/{scale_id}/values	prioriteettiasteikot ja niiden arvot (tarinan priority_id ratkeaa täältä)

Organisaatiot

Vain hostattu palvelu — itsehostattu asennus toimii yhden organisaation tilassa eikä ota näitä käyttöön (organisaatiolistaa lukuun ottamatta). Roolit ovat organisaatiorooleja: owner, admin, member.

Metodi	Polku	Kuvaus
GET / POST	/organizations	Listaa organisaatiosi / luo uusi
GET / PUT / DELETE	/organizations/{oid}	Lue, nimeä uudelleen (nimi + slug; omistaja tai ylläpitäjä), poista
GET / POST	/organizations/{oid}/memberships · PUT / DELETE …/memberships/{member_id}	Jäsenet ja kutsut; kutsuilla on roolikatto (ei koskaan kutsujan omaa korkeampi; omistajaa ei koskaan kutsuta)
POST	/organizations/{oid}/memberships/bulk-role · …/memberships/bulk-remove	Vaihda enintään 200 jäsenen rooli tai poista heidät kerralla. Kaikki tai ei mitään: erä, joka poistaisi viimeisen ownerin tai jättäisi projektin ilman omistajaa, hylätään kokonaan; reassign_confirmed tekee sinusta näiden projektien omistajan
DELETE	/organizations/{oid}/invitations/{invitation_id}	Peruuta vahvistamaton kutsu
POST	/organizations/{oid}/transfer-ownership	Luovuta omistajan rooli toiselle jäsenelle
GET	/organization-invitations/{token} · POST …/{token}/accept	Selvitä / hyväksy sähköpostitse saatu organisaatiokutsu
GET	/organizations/{oid}/export · POST …/export/jobs · GET …/export/jobs/{job_id} · …/export/jobs/{job_id}/download	Vain omistajille: organisaation vienti — zip, jossa on SQL-vedos ja jokainen liite, ajetaan työnä

Projektit

Metodi	Polku	Kuvaus
GET	/projects	Listaa projektisi (limit ≤ 200)
POST	/projects	Luo projekti
GET	/projects/{id}	Hae projektin tiedot (viewer)
PUT	/projects/{id}	Päivitä projektin asetukset (manager)
DELETE	/projects/{id}	Poista projekti (manager)
POST / DELETE	/projects/{id}/pin	Kiinnitä projekti projektilistaasi / irrota se
POST	/projects/{id}/transfer-organization	Siirrä projekti toiseen organisaatioon — kutsujan on oltava projektin Vastuuhenkilö sekä kohdeorganisaation omistaja tai ylläpitäjä
POST	/projects/{id}/slack/test	Lähetä testiviesti projektin Slack-syötteeseen (manager)
GET / POST	/projects/{id}/showcase_claim_eligibility · /projects/{id}/showcase_claim · /projects/{id}/showcase_seed	Julkiset esittelyprojektit: tarkista, voitko ottaa sellaisen omaksesi, ota se omaksesi, täytä se esimerkkisisällöllä (täyttö on tuotteen ylläpitäjille; kaikki muut saavat vastauksen 404)
GET	/projects/{id}/audit-log	Tarkastuslokin luku — projektihistoria sekä tarina- / eeppikohtainen toiminta surface=-parametrilla; pääsy vaihtelee surfacen mukaan, katso alta
GET	/projects/{id}/events	Kursorisivutettu tapahtumavirta (member) — katso Tapahtumat

Tarkastuslokin kyselyparametrit: event_type= (yksi tyyppi tai pilkuin eroteltu lista), limit= (oletus 50, enintään 1000), before= (keyset-kursori <ISO-8601>|<audit_id> — välitä edellisen sivun next_cursor), surface= (project_history, story_activities, epic_activities), target_id= (tarinan/eepin id — pakollinen kun surface=story_activities tai epic_activities). Pääsy: suodattamaton loki on (manager); surface=project_history on (viewer), ja jäsenten sähköpostit peitetään, kun projekti piilottaa ne; story_activities / epic_activities ovat kaikkien projektin jäsenten luettavissa, ja julkisissa projekteissa myös anonyymisti toimijan henkilötiedot peitettyinä.

Jäsenet, agentit ja agenttiavaimet

Metodi	Polku	Kuvaus
GET	/projects/{id}/memberships	Listaa jäsenet (viewer)
POST	/projects/{id}/memberships	Kutsu jäsen sähköpostitse (manager)
PUT	/projects/{id}/memberships/{mid}	Päivitä rooli (manager)
DELETE	/projects/{id}/memberships/{mid}	Poista jäsen (manager)
POST	/projects/{id}/memberships/bulk-role · …/memberships/bulk-remove	Vaihda monen jäsenen rooli kerralla tai poista heidät (manager)
GET	/projects/{id}/addable-members · POST /projects/{id}/members/add-existing	Organisaation jäsenet, jotka eivät vielä ole projektissa / lisää yksi ilman sähköpostikutsua — (manager) sekä organisaation omistaja tai ylläpitäjä
POST	/projects/{id}/members/join	Organisaation omistaja tai ylläpitäjä liittyy organisaationsa projektiin managerina tai ylentää itsensä manageriksi (projektilistan Make me owner -toiminto)
GET / POST	/projects/{id}/agent_keys	Listaa (manager) / luo agenttiavaimia — henkilöt, joiden rooli on projektin creator-roles-käytännössä; agenttiavaimet eivät voi luoda avaimia
PUT / DELETE	/projects/{id}/agent_keys/{kid}	Muokkaa avaimen nimeä, roolia tai vastausvihjeitä / peruuta se (manager)
GET	/projects/{id}/agent_keys/onboarding	Onboarding-paketti: kehotteet ja konfiguraatiotiedostot yleisimmille agenttiasiakkaille
GET	/projects/{id}/agents · GET / PUT / DELETE /projects/{id}/agents/{aid}	Projektin agentit ja niiden profiilit (nimi, nimikirjaimet, kuvaus, väri); DELETE peruuttaa agentin ja kaikki sen avaimet — manageri tai agentin luoja
POST	/projects/{id}/agents/{aid}/rotate-key · /projects/{id}/agents/{aid}/avatar	Kierrätä agentin avain (identiteetti ja historia säilyvät) / lataa sen avatar

Tarinat

Kaikki tarinakirjoitukset vaativat member-roolin. Tarinan luominen taannehtivin päivämäärin, tuontialkuperällä (import_source / import_external_id) tai ulkoisilla omistajilla tai pyytäjällä vaatii roolin (manager).

Metodi	Polku	Kuvaus
GET	/projects/{id}/stories	Listaa tarinat (sivutettu, suodatettavissa) (viewer)
POST	/projects/{id}/stories	Luo tarina
GET	/projects/{id}/stories/{sid}	Hae yksi tarina (viewer)
PUT	/projects/{id}/stories/{sid}	Päivitä tarina
DELETE	/projects/{id}/stories/{sid}	Poista tarina
POST	/projects/{id}/stories/{sid}/transitions	Vaihda tilaa validoinnilla
POST	/projects/{id}/stories/{sid}/reject · /projects/{id}/stories/{sid}/restart	Hylkää toimitettu tarina / palauta hylätty tarina tilaan started (rejected on päätetila päätepisteelle /transitions)
POST	/projects/{id}/stories/{sid}/archive · /projects/{id}/stories/{sid}/unarchive	Arkistoi / palauta arkistosta yksi tarina
POST	/projects/{id}/stories/bulk-unarchive	Palauta monta tarinaa arkistosta
POST	/projects/{id}/stories/bulk_transition	Siirrä useita tarinoita (1–100) kerralla
POST	/projects/{id}/stories/bulk-archive · bulk-delete · bulk-duplicate · bulk-move	Arkistoi, poista, monista tai siirrä (paneeliin / kohtaan) useita tarinoita
POST	/projects/{id}/stories/{sid}/duplicate	Monista yksi tarina
POST / DELETE	/projects/{id}/stories/{sid}/epics · …/epics/{eid}	Tarinan eeppijäsenyys
GET	/short-links/{code} · /story-references	Ratkaise /s/<code>-lyhytlinkki sen tarinaksi / ratkaise enintään 100 viittausta — codes= (pilkuin erotellut lyhytlinkkikoodit) ja ids= (pilkuin erotellut project_id:story_id) — tarinoiksi, joita kutsuja voi lukea

Tarinalistojen kyselyparametrit: archived= (exclude oletus / include / only — kolmitilainen arkistointisuodatin; korvaa vanhentuneen include_archived=true-parametrin, joka on nyt archived=include-muodon alias), include_done=true (sallii Done-paneelin tarinat, jotka on jäädytetty menneisiin iteraatioihin; oletuksena pois jätetty). Sivutus (cursor= / limit= / offset=) ja suppeat kenttäjoukot (fields=) noudattavat osioita Sivutus ja Kenttäprojektio.

Luo (POST …/stories): { "name" (required), "story_type": "feature|bug|chore|release", "description"?, "estimate"?, "current_state"?, "icebox"?, "labels"? }. estimate on asteikon arvon nimike merkkijonona ("3", "13"); JSON-luku hylätään. labels hyväksyy ["auth"] tai [{ "name": "auth" }]; tuntemattomat tunnisteet luodaan. Oletukset: story_type=feature, current_state=unstarted.

Päivitä (PUT …/stories/{sid}): samat kentät, kaikki valinnaisia, lisäksi "position" (float), "force_state_change" (bool) ja "expected_version" (kokonaisluku, tarinan version — kuvauksen tallennus evätään virheellä 409 stale_write, jos kuvaus on muuttunut kyseisen version jälkeen). Vanhempi "expected_updated_at" (RFC 3339) on vanhentunut ja toimii vielä yhden julkaisun ajan: jos se lähetetään kuvauksen kanssa ilman expected_version-kenttää, tallennus evätään virheellä 409 stale_write, ellei se vastaa tarinan updated_at-arvoa. Tarinakirjoitukset noudattavat myös If-Match-otsaketta tarinan ETag-arvoa vasten; epäsuhta on 412 precondition_failed.

Siirtymä (POST …/transitions): { "to": "<state>" }. Kenttä on to. Palauttaa { story_id, state }. Laiton siirto → 422 invalid_transition, jossa details: { from, to, allowed }.

Massasiirtymä (POST …/bulk_transition): { "story_ids": [int,…] (1–100), "to": "<state>" }. Jokainen tarina arvioidaan itsenäisesti; palauttaa { results: [ { id, status: "ok" } | { id, status: "failed", error } ] }.

Tarinan aliresurssit

Kaikki member. Useimpien listaus/GET on (viewer). Liitteen tai linkkiliitteen poistaminen vaatii sen lataajan tai roolin (manager).

Metodi	Polku	Runko / huomiot
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) } tai { comment_emoji }. GET ottaa fields=-parametrin (sallitut: comment_id, story_comment_id, story_id, comment_text, comment_emoji, member, created) sekä 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}	Luonti: { url, link_type?, title? }; päivitys: { url, title? } — link_type ∈ relates_to, duplicates, blocks, is_blocked_by, pull_request, branch, other; GitHubin /pull/- ja /tree/-URL:t tyypitetään automaattisesti
GET / POST	/projects/{id}/stories/{sid}/reviews · PUT/DELETE …/reviews/{rid}	Luonti: { reviewer_id? / reviewer_agent_id?, comment? } — jätä molemmat pois määrittääksesi itsesi. Päivitys: { status, comment? }
GET / POST	/projects/{id}/stories/{sid}/owners · DELETE …/owners/{mid} · DELETE …/owners/agents/{aid}	{ member_id? / agent_id? } — jätä molemmat pois lisätäksesi kutsujan
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}	{ label_id } — olemassa oleva projektin tunniste; luo tunnisteita kutsulla POST /projects/{id}/labels tai lähetä labels tarinan PUT-kutsussa
GET / POST	/projects/{id}/stories/{sid}/attachments (+ /json) · DELETE …/attachments/{aid}	multipart-lataus — video ≤ 200 MB, PDF / Word / Excel ≤ 25 MB, kuvat / CSV / teksti ≤ 10 MB; listaus on (viewer)
GET / POST	/projects/{id}/stories/{sid}/link-attachments · DELETE …/link-attachments/{laid}	Linkkiliitteet — ulkoinen URL, joka säilytetään tiedostoliitteiden rinnalla koodilinkin sijaan
GET	/attachments/{token} · /api/v1/avatars/{token}	Tokenilla osoitetut liitteen tai avatarin luvut — APIn jakamat URL:t; X-TrackerToken-otsaketta ei tarvita

Eepit

Sama muoto kuin tarinoilla, ilman tilakonetta. member kirjoituksille sekä kommentti-, omistaja- ja seuraajalistoille; (viewer) eeposlistalle, yksittäiselle eepokselle ja liitelistoille.

Metodi	Polku	Kuvaus
GET / POST	/projects/{id}/epics · GET / PUT / DELETE …/epics/{eid}	Eepeillä on nimi, Markdown-kuvaus ja taustatunniste, joka yhdistää niiden tarinat
GET / POST / PUT / DELETE	…/epics/{eid}/comments · …/comments/{cid}	Eeppien kommentit
GET / POST / DELETE	…/epics/{eid}/owners · …/followers (+ /agents/{aid}-muunnelmat)	Omistajat ja seuraajat, jäseniä tai agentteja — eepin omistajat periytyvät sen tarinoille
GET / POST / DELETE	…/epics/{eid}/attachments (+ /json) · …/link-attachments	Liitteet, samat rajat kuin tarinoilla
GET	/projects/{id}/analytics/epics · …/analytics/epics/{eid}	Eeppikohtainen edistyminen: burnup, läpimeno, kunto, ennuste (viewer)

Tunnisteet

member kirjoituksille, (viewer) luvuille.

Metodi	Polku	Kuvaus
GET / POST	/projects/{id}/labels	Listaa / luo tunniste
GET / PUT / DELETE	/projects/{id}/labels/{lid}	Lue / päivitä / poista tunniste
POST	/projects/{id}/labels/{lid}/archive	Arkistoi (piilota pehmeästi) tunniste

Iteraatiot

Luvut ovat avoinna mille tahansa projektiroolille, ja julkisessa projektissa myös anonyymeille.

Metodi	Polku	Kuvaus
GET	/projects/{id}/iterations	Listaa iteraatiot (≤ 500 sivua kohti; sisältää ETag-otsakkeen ja X-Tracker-Pagination-*-jatko-otsakkeet, kun lista katkaistaan)
GET	/projects/{id}/iterations/{itid}	Yksi iteraatio
GET	/projects/{id}/iterations/first-preview	Aikaikkuna, ennustettu nopeus ja Backlog-täyttö iteraatiolle, jonka luova kirjoitus loisi, tai nykyiselle iteraatiolle, jos sellainen on (member)
POST	/projects/{id}/iterations	Luo manuaalinen iteraatio (manager)
DELETE	/projects/{id}/iterations/{itid}	Poista iteraatio (manager)
PUT	/projects/{id}/iterations/{itid}/velocity	Ohita yhden iteraation nopeus muuttamatta projektin strategiaa (manager)
GET	/projects/{id}/iterations/{itid}/done-stories	Suljetun iteraation hyväksytyt tarinat, sivutettuina

Haku, mittarit, asetukset

Metodi	Polku	Kuvaus
GET	/projects/{id}/search?q=…	Tehokas haku — kokoteksti + fasetti- / päivämääräväli- / henkilömääreet (GitHub-tyylinen DSL); palauttaa { results, total, limit, offset }. query on q:n alias; limit= (oletus 50, enintään 1000) / offset= sivuttavat; sort= järjestää arvoilla relevance (oletus), created, created_asc, state tai updated. (viewer) — katso Opas
GET	/projects/{id}/metrics/{velocity,burndown,story-types,contributors}	Metrics-sivun sarjat (viewer); eeppimittarit ovat yllä kohdassa /analytics/epics
GET	/projects/{id}/backlog/grouping	Backlogin ennustetut iteraatioryhmät (viewer)
GET / PUT	/projects/{id}/preferences	Taulusi asetukset tälle projektille — mikä tahansa projektirooli, vain oma rivisi

Tapahtumat

Metodi	Polku	Kuvaus
GET	/projects/{id}/events	Kursorisivutettu tapahtumavirta (member) — katsojat saavat 403

Kyselyparametrit: since_id=<event_id> (since on vanhempi alias; since_id voittaa, jos molemmat lähetetään), types=story.created,story.transitioned,comment.added,…, limit= (oletus 100, ≤ 500), cursor=. Vastaus on { items, next_since_id, next_cursor }: tallenna next_since_id ja välitä se takaisin arvona since_id jatkaaksesi; next_cursor on viimeisellä sivulla null.

Ilmoitukset

Sovelluksen yhtenäinen ilmoitussyöte: täysiveriset ilmoitusrivit (katselmointipyynnöt, tarinoiden tapahtumat, kutsut, …) yhdistettynä @-mainintojen saapuneisiin yhdeksi virraksi, uusin ensin. Syötteen id:issä on lähde-etuliite (nt-… / sc-… / ec-…). Jäsenistunnot ja ea_user_*-avaimet lukevat jäsenpuolen rivinsä; ea_agent_*-avaimet agenttipuolen rivinsä.

Metodi	Polku	Kuvaus
GET	/me/notifications	Ilmoitussyötteesi. Suodattimet: unread=true, since_id=, kind= (mentions / reviews / stories / invitations); sivutus cursor= / limit= -parametreilla
GET	/me/notifications/unread-count	Lukemattomien summat — { unread_count, by_category: { mentions, reviews, stories, invitations } }
POST	/me/notifications/read-all	Merkitse kaikki luetuiksi; palauttaa tuoreet laskurit
POST	/me/notifications/{id}/ack	Merkitse yksi kohde luetuksi (idempotentti)
POST	/me/notifications/{id}/accept	Hyväksy projekti-/organisaatiokutsu suoraan syötteestä (vain jäsentokenit)
POST	/me/notifications/{id}/decline	Hylkää projekti-/organisaatiokutsu (vain jäsentokenit)
GET	/me/notifications/resolve-invite?token=…	Yhdistä sähköpostitse saatu kutsutoken ilmoituksesi id:hen — { "id": "nt-…" } tai { "id": null }
GET	/me/notifications/stream	Live-push — Server-Sent Events (text/event-stream); katso alta

Stream-päätepiste ei ole JSON-päätepiste, joten se ei ole OpenAPI-määrittelyssä: se pitää yhteyden auki ja lähettää hyötykuormattoman kehyksen ({"type":"notification","kind":…}) aina kun jotakin uutta saapuu, kehottaen asiakasta noutamaan syötteen uudelleen. Palvelin katkaisee yhteydet 45 minuutin jälkeen — yhdistä ja todenna uudelleen. Vain jäsenistunnot ja ea_user_*-avaimet; ea_agent_*-avaimet saavat 403.

Tuonti (manager)

Metodi	Polku	Kuvaus
POST	/projects/{id}/import	Tiedostolähteet: source= ∈ pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json, eat. Multipart file=. Synkroninen — vastaa tuloslukemilla.
POST	/projects/{id}/import/json	JSON-runko; source=github ei tarvitse tiedostoa — owner, repo, valinnainen token ja valinnaiset liput include_pull_requests / include_milestones / include_releases / include_dependencies ja include_comments (oletus true); tiedostolähteet lähettävät file_base64. Asynkroninen: palauttaa 202 { import_id, status }. Palvelin hakee GitHubin GraphQL-rajapinnan kautta, joka hylkää anonyymit kutsujat, joten GitHubille menee aina token — omasi tai asennuksen jaettu. Katso Opas.
GET	/projects/{id}/imports/{import_id}	Kysele työn tilaa: status etenee pending → fetching → writing → done | failed; haun aikana mukana ovat progress_current / progress_total ja tilassa done tuloslukemat

Projektissa ajetaan yksi JSON-tuonti kerrallaan; toinen POST …/import/json, kun tuonti on jo käynnissä, palauttaa 409 import_already_running. Kun check_unpointed_estimates: true on käytössä (tiedostolähteet; github-lähteellä ohitetaan), tiedosto, jossa on bugien tai askareiden arvioita, joita projekti ei pisteytä, hylätään vastauksella 409 import_unpointed_estimates ja details.count ennen kuin mitään työtä aloitetaan; ilman lippua tuonti pudottaa nämä arviot ja raportoi tuloksen warnings-kentässä { code: "estimates_unpointed_dropped", count }. dry_run: true (JSON-runko tai dry_run=true multipart) esikatselee minkä tahansa lähteen: jäsentää, ratkaisee, poistaa duplikaatit, palauttaa samat { imported, skipped, errors, unmatched } -lukemat ja peruu sitten — mitään ei kirjoiteta. Rajat: 10 MiB tiedosto (400 import_too_large) ja 5 000 tarinaa tuontia kohti tiedostopohjaisille lähteille (400 import_too_many_records); mitään ei kirjoiteta. Yli 16 MiB:n pyyntörunko hylätään jo aiemmin vastauksella 413 request_too_large. GitHub-lähteellä ei ole kattoa — se kirjoittaa erissä yhden transaktion sijaan. Uudelleentuonti on idempotentti lähde-id:tä kohti — jo tuodut rivit ohitetaan, ei kahdenneta.

Vienti

Metodi	Polku	Kuvaus
GET	/projects/{id}/export/formats	Rekisteröidyt muodot: { id, name, content_type, drops, includes_archived }. Mikä tahansa projektirooli.
GET	/projects/{id}/export/{format}	Lataa yksi (manager). Vaihtomuodot: eat (täysi tarkkuus), jira, pivotal, shortcut, trello, asana, gitlab, linear, plane, plane_json; asiakirjat: pdf, docx.
GET	/projects/{id}/export/attachments	Jokainen liite yhtenä selattavana zip-tiedostona (tiedostot säilyttävät alkuperäiset nimet; JSON- + CSV-manifesti) (manager).

Dokumenttiviennit (pdf, docx) ottavat lisäkyselyparametreja: page_size= (letter oletus / a4 / legal / folio), from= / to= (tarinaikkunan rajat — RFC 3339 tai pelkkä YYYY-MM-DD; tarina on välillä, kun sen created tai completed_at osuu sen sisään), include_icebox= / include_backlog= (molempien oletus false, joten jaettava vienti näyttää vain aikataulutetun / käynnissä olevan työn). Vaihtomuotoiset CSV-formaatit ohittavat ne.

Varmuuskopiot ja palautukset (manager)

Metodi	Polku	Kuvaus
GET / POST	/projects/{id}/backups · GET …/backups/{snapshot_id} · …/backups/health	Listaa tilannevedokset, ota vedos nyt, lue yksi, sekä säilytyksen kuntoyhteenveto
POST	/projects/{id}/restores · POST …/restores/partial · GET …/restores/{restore_id}	Palauta koko tilannevedos tai siitä valitut taulut, ja kysele palautuksen tilaa

POST-kutsut kuuluvat alla kuvattuun arkaluonteiseen nopeusrajaportaaseen.

MCP- ja OAuth-palveluntarjoaja

East Agile Tracker on OAuth 2.1 -palveluntarjoaja MCP-asiakkaille. Asiakas löytää sen osoitteista /.well-known/oauth-authorization-server ja /.well-known/oauth-protected-resource/mcp, ohjaa sinut osoitteeseen /oauth/authorize (suostumussivu), vaihtaa koodin osoitteessa /oauth/token ja puhuu sitten MCP:tä osoitteessa /mcp saamallaan ea_mcp_*-tokenilla. Valtuutukset listataan ja peruutetaan osoitteessa /me/oauth_grants. Palveluntarjoajan päätepisteillä on oma nopeusrajaportaansa.

Idempotenssi

Kirjoituspäätepisteet (POST, PUT, DELETE) hyväksyvät Idempotency-Key-otsakkeen. Sama avain + sama runko toistaa välimuistitetun vastauksen (24 tunnin ikkuna); sama avain + eri runko palauttaa 409 idempotency_conflict. Avain on rajattu sen lähettäneeseen tunnisteeseen. Ei sovelleta metodeihin GET/HEAD/OPTIONS, polkuihin /openapi.json ja /docs, /api/auth/* tai /mcp, mihinkään polkuun, joka sisältää /attachments, eikä mihinkään multipart/*-pyyntöön; pyyntöä ilman tunnistetta ei koskaan välimuistiteta. Vastauksia, jotka päättyivät ennen toimialueen vastausta, ei koskaan välimuistiteta — 401, 403, 404, 429 ja jokainen 5xx — joten uudelleenyritys minkä tahansa niistä jälkeen tavoittaa käsittelijän; 400, 409, 412 ja 422 ovat toimialueen vastauksia ja toistuvat kuten onnistuminen.

Sivutus

Listapäätepisteet hyväksyvät cursor=<opaque> ja limit=<n>. Kun ne on asetettu, vastaus on { "items": [...], "next_cursor": "<str|null>" }; välitä next_cursor takaisin sivuttaaksesi. limit-katto on päätepistekohtainen: 200 tarinoille, kommenteille ja projekteille; 500 tapahtumille; 1000 tarkastuslokille. Haku sivuttaa parametreilla limit (≤ 1000) ja offset kursorin sijaan ja palauttaa { results, total, limit, offset }.

Tavallinen lista (ilman cursor/limit), jonka vastaus jouduttiin katkaisemaan, kertoo sen otsakkeissa — X-Tracker-Pagination-Truncated, X-Tracker-Pagination-Limit, X-Tracker-Pagination-Offset ja X-Tracker-Pagination-Next-Offset; välitä viimeinen takaisin muodossa offset= seuraavaa sivua varten. Kokonaismääräotsaketta ei ole.

Kenttäprojektio

Tarina-, kommentti- ja projektilistat hyväksyvät fields= (pilkuin erotettu) palauttaakseen vain tietyt kentät. Resurssin id sisältyy aina (story_id, story_comment_id ja comment_id, project_id); tuntematon kentän nimi palauttaa 400 validation_failed, jossa virheelliset nimet ovat kohdassa details.fields.

GET /projects/123/stories?fields=story_id,name,current_state,owners

Virhemuoto

Jokaisella JSON-virheellä on code ja error; jotkin lisäävät details:

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

Status	code	Milloin
400	invalid_parameter	virheellinen syöte; viesti kohdassa error. Kenttävalidointi (tyhjä/pituus/null-tavu/sähköposti) lisää details.fields- ja details.constraint-kentät; vain pelkkä bad request -virhe jättää details-kentän pois
400	validation_failed	jäsennelty syötevirhe; details.fields on taulukko virheellisten kenttien nimistä
400	toimialuekoodit	reittikohtainen hylkäys omalla koodillaan ilman details-kenttää — esim. unsupported_export_format, import_too_large, import_unknown_source
401	unauthenticated	puuttuva/virheellinen tunnus
403	unauthorized_operation	tunnistautunut mutta riittämätön rooli
404	unfound_resource	ei löytynyt — palautetaan myös ei-jäsenille
409	conflict	resurssikonflikti (esim. duplikaatti)
409	idempotency_conflict	Idempotency-Key uudelleenkäytetty eri rungolla
409	stale_write · import_already_running · import_unpointed_estimates	kuvaus on muuttunut expected_version-arvosi jälkeen (tai expected_updated_at ei enää täsmää) · tuonti on jo käynnissä · tiedostossa on bugien tai askareiden arvioita, joita projekti ei pisteytä (details.count)
412	precondition_failed	If-Match ei vastannut resurssin nykyistä ETag-arvoa; details sisältää expected ja current
413	request_too_large	runko ylittää reitin kokorajan
422	invalid_transition	laiton tilasiirto; details kantaa { from, to, allowed }
429	rate_limited	liian monta pyyntöä tästä IP:stä nopeusrajoitetulla reitillä; Retry-After-otsake
500	internal_error	palvelinvika — yleinen viesti; turvallista yrittää uudelleen
502	upstream_error	palvelu, josta reitti riippuu (esim. GitHub), epäonnistui
503	not_configured	asennuksesta puuttuu integraatio, jota tämä reitti tarvitsee (tekstiviestit, objektitallennus, …)

details.fields on JSON-taulukko kenttien nimistä (esim. ["to"]), joskus lisäavaimin kuten max. Kenttä→viesti-karttaa ei ole.

{ "code": "validation_failed", "error": "unknown field(s): foo", "details": { "fields": ["foo"] } }

Nopeusrajat

IP-kohtaisesti, muutamilla reiteillä; tunnistautunutta API-liikennettä muualla ei rajoiteta. Oletukset (kukin pari on jatkuva nopeus ja purske, operaattorin säädettävissä):

• Auth — /api/auth/*: 0,5 pyyntöä/s, purske 20.
• OAuth-palveluntarjoaja — /oauth/*: 1 pyyntö/s, purske 60.
• Julkinen — /api/contact: 0,2 pyyntöä/s, purske 10.
• Palaute — /api/v1/feedback ja /api/v1/feedback/with-screenshot: kolme päällekkäistä porrasta — yksi lähetys 15 sekunnissa, 10 tunnissa, 36 vuorokaudessa.
• Avatarit — tunnistautumaton avatar-uudelleenohjaus: 20 pyyntöä/s, purske 200.
• Arkaluonteinen — varmuuskopioinnin ja palautuksen POST-kutsut: ~0,002 pyyntöä/s, purske 5.

Ylitetty raja palauttaa 429, jossa on Retry-After-otsake ja tavallinen JSON-virhekuori, code: "rate_limited".