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://eastagiletracker.com/api/v1

https://api.eastagiletracker.com/api/v1 tarjoaa identtisen APIn. 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 julkiset lomakkeet (/api/contact, /api/feedback). 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 (mitätöi 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)

Tili / identiteetti

Nämä kohdistuvat kutsujaan ja tarvitsevat vain kelvollisen avaimen (ei projektiroolia).

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	/me/avatar	Lataa avatar (multipart)
POST	/me/api-token/regenerate	Kierrätä API-tunnuksesi — mitätöi olemassa olevat istunnot/avaimet
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/feedback · /api/feedback/with-screenshot	Yhteydenotto + sovelluksen sisäinen palaute. /v1:n ulkopuolella; 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
PUT	/organizations/{oid}/memberships/{member_id}/anonymization	Peitä jäsenen nimi / sähköposti / avatar koko organisaatiossa
GET	/organization-invitations/{token} · POST …/{token}/accept	Selvitä / hyväksy sähköpostitse saatu organisaatiokutsu
POST	/organizations/{oid}/export · GET / 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	/projects/{id}/pin	Kiinnitä projekti projektilistaasi / irrota se
POST	/projects/{id}/transfer-organization	Siirrä projekti toiseen organisaatioon (manager)
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ä
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= (≤ 1000), before= (keyset-kursori, ISO-8601 created_at), surface= (project_history, story_activities, epic_activities), target_id= (tarinan/eepin id — pakollinen kun surface=story_activities tai epic_activities). Pääsy: suodattamaton loki ja surface=project_history ovat (manager); 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)
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)
POST	/projects/{id}/members/join	Organisaation omistaja tai ylläpitäjä liittyy organisaationsa projektiin managerina tai ylentää itsensä manageriksi (projektilistan Make me owner -toiminto)
PUT	/projects/{id}/members/{mid}/anonymization	Peitä jäsenen nimi / sähköposti / avatar tässä projektissa (manager)
GET / POST	/projects/{id}/agent_keys	Listaa / luo agenttiavaimia — managerit tai roolit, jotka projektin creator-roles-käytäntö sallii
DELETE	/projects/{id}/agent_keys/{kid}	Peruuta agenttiavain
GET	/projects/{id}/agent_keys/onboarding	Onboarding-paketti: kehotteet ja konfiguraatiotiedostot yleisimmille agenttiasiakkaille
GET	/projects/{id}/agents · GET / PUT /projects/{id}/agents/{aid}	Projektin agentit ja niiden profiilit (nimi, nimikirjaimet, kuvaus, väri)
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.

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_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
GET / POST / DELETE	/projects/{id}/stories/{sid}/epics · …/epics/{eid}	Tarinan eeppijäsenyys
GET	/short-links/{code} · /story-references	Selvitä /s/<code>-lyhytlinkin tarina / selvitä enintään 100 tarinaviitettä (#id, URL:t) 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_updated_at" (RFC 3339 — kuvauksen tallennus evätään virheellä 409 stale_write, jos tarina on muuttunut lukemisesi jälkeen). 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).

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}	{ url, link_type?, 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}	{ name }
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/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, (viewer) luvuille.

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
PUT / DELETE	/projects/{id}/labels/{lid}	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	Päivämäärät, jotka ensimmäinen iteraatio saisi, näytetään luontivahvistuksessa
POST	/projects/{id}/iterations	Luo manuaalinen iteraatio (member)
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=<event_id>, types=story.created,story.transitioned,comment.added,…, limit= (≤ 500), cursor=. Vastaus sisältää next_cursor. Välitä viimeisin näkemäsi event_id arvona since jatkaaksesi.

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; 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 tuonti kerrallaan; toinen POST, kun tuonti on jo käynnissä, palauttaa 409 import_already_running. 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 runko ja 5 000 tarinaa tuontia kohti tiedostopohjaisille lähteille (kumman tahansa yli → 400, mitään ei kirjoiteta). 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
GET / 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.

WebSocket

wss://eastagiletracker.com/ws/control?token=<session JWT>

Interaktiiviseen käyttöliittymän etäohjaukseen ({ "action": "get_state", "id": "req-1" }). Token on selainistunnon JWT — API-avain hylätään virheellä 401 ennen yhteyden päivitystä. Ei datakanava — kaikki luvut/kirjoitukset kulkevat RESTin kautta. Vain yksi instanssi; ei jaeta replikoiden kesken.

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 tai /api/auth/* eikä multipart-latauksiin /attachments-poluilla. 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 haulle ja tarkastuslokille.

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

Listapäätepisteet hyväksyvät fields= (pilkuin erotettu) palauttaakseen vain tietyt kentät. story_id sisältyy aina; 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, ei details (useimmat validoinnit: tyhjä/pituus/null-tavu/sähköposti)
400	validation_failed	jäsennelty syötevirhe; details.fields on taulukko virheellisten kenttien nimistä
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	tarina on muuttunut expected_updated_at-arvosi jälkeen · tuonti on jo käynnissä
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
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/feedback: 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".