Espesipikasyon ng API

Ang kumpletong sanggunian ng REST endpoint. Para sa mga tutorial at halimbawa, tingnan ang Gabay sa API.

Lahat ng kayang gawin ng isang miyembro ng proyekto sa web UI ay magagamit dito — ang SPA ay kumukonsumo ng parehong API na ito. Ang mga operasyong nangangailangan ng tungkuling manager ay minamarkahang (manager); lahat ng iba ay nangangailangan lamang ng membership sa proyekto (o, para sa mga read na minarkahang (viewer), anumang antas ng akses). Pinapangalanan ng mga talahanayan sa ibaba ang bawat grupo ng route na ini-mount ng server; ang mga ibinubuod sa iisang linya ay buong inilalarawan sa live na openapi.json.

Base

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

May sariling host ang API: ang eastagiletracker.com ang naghahatid ng web app at sumasagot ng 404 sa /api/v1/…. Lahat ng request at response ay JSON, maliban sa ilang file-upload endpoint na tumatanggap ng multipart.

Dalawang grupo ang nasa isang antas na mas mataas, sa ilalim ng /api sa halip na /api/v1: ang authentication surface (/api/auth/*) at ang pampublikong contact form (/api/contact). Nagbabalik ng 404 ang kanilang mga anyong /api/v1/….

Pagpapatunay

Bawat na-authenticate na request ay nagpapadala ng kredensyal sa pamamagitan ng isa sa:

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

Nagsisimula ang mga user key sa ea_user_, ang mga agent key sa ea_agent_, at ang mga MCP access token sa ea_mcp_. Tingnan ang Gabay sa API → Tatlong uri ng kredensyal.

Mga endpoint na walang authentication: /openapi.json, /docs, ang mga endpoint na /api/auth/*, at ang mga reference-data na lookup (/story_types, /story_states, /effort_scales, /priority_scales). Ang /meta ay authenticated — gumagana ang anumang wastong key, ngunit hindi ito scoped-sa-proyekto (naaabot din ito ng project-bound na agent key).

Mga tungkulin

Apat na antas ang nagkokontrol sa mga endpoint na scoped-sa-proyekto:

Antas	Sino ang pumapasa	Karaniwang mga operasyon
public viewer	sinuman, sa isang proyektong pampubliko ang visibility	mga read ng board: stories, iterations, search, aktibidad ng story at epic (na naka-redact ang mga detalye ng aktor)
viewer	viewer, member, manager	mga read (list/get stories, search, metrics, listahan ng export format)
member	member, manager	lahat ng write ng work-item (stories, tasks, comments, …), ang event stream
manager	manager lamang	mga setting ng proyekto, pamamahala ng membership, agent keys, delete, import, pag-download ng export, backups, audit log

Hawak ng mga agent ang parehong mga tungkulin gaya ng mga miyembro — viewer, member, o manager — na nililimitahan sa tungkulin ng miyembrong nag-mint ng key. Ang isang hindi-miyembro ay tumatanggap ng 404 unfound_resource (hindi 403) sa mga path ng pribadong proyekto, kaya hindi maiisa-isa ang mga project ID.

Mga endpoint na naglalarawan sa sarili

Method	Path	Paglalarawan
GET	/openapi.json	Ang buháy na OpenAPI 3 spec, kasama ang mga request body. Walang authentication.
GET	/docs	Swagger UI. Walang authentication.
GET	/meta	Identidad ng caller (auth.kind/key_id/agent_id/project_id) + ang story-type transition graph. Authenticated (anumang wastong key; hindi scoped-sa-proyekto). Tawagin ito muna.
GET	/api/health · /api/config	Liveness, at ang pampublikong configuration ng deployment (single-org mode, kung aling mga opsyonal na feature ang naka-on, pangalan ng instance). Walang authentication, nasa labas ng /v1.

Auth (/api/auth/*, sa labas ng /v1)

Mga session endpoint, walang authentication maliban kung nakasaad. Ang SPA ang nagpapatakbo ng mga ito; karaniwang API key ang ginagamit ng mga script sa halip.

Method	Path	Paglalarawan
POST	/auth/register	Magrehistro ng bagong account — binabantayan ng reCAPTCHA; pagkatapos ay dumadaan ang account sa SMS challenge
POST	/auth/sms/challenge · /auth/sms/status · /auth/sms/bypass	Ipadala / suriin ang SMS code ng sign-up (kontrolado ng operator ang bypass)
GET	/auth/config	Kung aling mga paraan ng pag-sign in ang inaalok ng deployment
POST	/auth/login	Mag-sign in gamit ang email + password; nagbabalik ng session JWT, o isang TOTP challenge
POST	/auth/login/totp	Tapusin ang pag-sign in gamit ang authenticator code o recovery code
POST	/auth/passkey/login/start · /auth/passkey/login/finish	Passwordless na WebAuthn sign-in
GET	/auth/oauth/github/start · /auth/oauth/github/callback · /auth/oauth/google/start · /auth/oauth/google/callback · POST /auth/oauth/exchange	OAuth sign-in gamit ang GitHub o Google
POST	/auth/refresh · /auth/refresh/revoke	I-rotate ang refresh token / bawiin ito
POST	/auth/logout	Mag-sign out (naka-authenticate; binabawi ang refresh token ng session na ito)
POST	/auth/forgot-password · /auth/reset-password	Humiling ng reset na email / gamitin ang reset token
POST	/auth/accept-invite/lookup · /auth/accept-invite	Lutasin ang invitation token → email / tanggapin ang imbitasyon sa proyekto (pagkatapos mag-authenticate)
POST	/auth/oauth/link/preview · …/link/confirm · /auth/oauth/merge/preview · …/merge/confirm	Ikonekta ang isang GitHub o Google account sa isang umiiral na account, o pagsamahin ang dalawang account
POST	/auth/email_addresses/primary/preview · …/primary/confirm	Tapusin ang pagpapalit ng pangunahing email mula sa confirmation link na ipinadala sa email

Account / identidad

Ang mga ito ay kumikilos sa caller at hindi nangangailangan ng tungkulin sa proyekto. Kailangan nila ng pagkakakilanlan ng miyembro — nakakakuha ng 401 ang isang agent key (ginagamit ng mga agent ang /agent/me). Ang mga tawag na nagbabago ng kredensyal — password, TOTP, passkey, pag-delete ng account, pagpapalit ng email, muling pagbuo ng token — ay nangangailangan ng browser session; nakakakuha ng 403 ang isang API key.

Method	Path	Paglalarawan
GET	/me	Profile ng kasalukuyang user
PUT	/me	I-update ang profile
DELETE	/me	I-delete ang account — tinatanggihan habang ikaw ang nag-iisang owner ng isang org o ng isang proyektong may iba pang miyembro
GET	/me/deletion-impact	Ano ang aalisin ng pag-delete ng account at ano ang humaharang dito
PUT	/me/password	Baguhin ang password
PUT	/me/settings	I-update ang mga setting (theme, mga kagustuhan sa abiso)
POST / DELETE	/me/avatar	Mag-upload (multipart) / mag-alis ng iyong avatar
POST	/me/api-token/regenerate	I-sign out ang bawat session at magbalik ng bagong session token; hindi apektado ang mga API key
GET / POST	/me/email_addresses · GET …/email_addresses/offers · PUT …/email_addresses/primary	Ang iyong mga email address; gamitin ang address ng isang konektadong provider bilang alternate; humiling ng pagpapalit ng pangunahin (kinukumpirma sa email)
GET	/me/oauth_identities · DELETE …/oauth_identities/{provider} · POST …/oauth_identities/{provider}/link	Mga konektadong sign-in account (GitHub, Google): ilista, idiskonekta, simulan ang pag-link
GET	/me/api_keys · POST /me/api_keys · DELETE /me/api_keys/{id}	Pamahalaan ang user (ea_user_) na mga API key
GET	/me/totp · POST /me/totp/setup · /me/totp/verify · /me/totp/disable	Enrollment sa two-factor (TOTP); ibinabalik ng verify ang mga recovery code nang isang beses
GET	/me/passkeys · POST /me/passkeys/register/start · /me/passkeys/register/finish · DELETE /me/passkeys/{credential_id}	Enrollment at pag-alis ng passkey
GET	/me/oauth_grants · DELETE /me/oauth_grants/{grant_id}	Mga connected app — ang mga MCP client at OAuth app na pinahintulutan mo
GET	/me/activity	Ang iyong aktibidad sa lahat ng proyekto
GET	/me/stories	Mga story na pag-aari mo, hiniling mo, o sinusundan mo sa bawat proyektong naaabot ng token — role=owned|requested|following, state=, cursor= / limit= (max 200)
GET	/me/mentions · POST /me/mentions/{mention_id}/ack	Ang inbox ng @-banggit (unacked=true para mag-filter) at ang pag-acknowledge — kasama rin sa feed ng notipikasyon sa ibaba
GET	/me/data-export	GDPR na self-export ng iyong datos
GET	/me/consent · POST /me/consent	Basahin / itala ang consent ({ consent_type, granted })
GET	/legal/pending · POST /legal/accept	Mga nakabinbing clickwrap na dokumento / itala ang pagtanggap
GET / PUT	/agent/me	Ang sariling identidad at profile ng isang agent key, nababasa at nae-edit ng agent (ang katapat sa panig-agent ng /me)
POST	/api/contact · /api/v1/feedback · /api/v1/feedback/with-screenshot	Contact + in-app na feedback; may rate limit kada IP

Reference data (walang authentication)

Mga seed na lookup na ginagamit kapag lumilikha/nagtatantiya ng mga story. Mga stable na ID.

Method	Path	Paglalarawan
GET	/story_types	feature, bug, chore, release (+ allow_points)
GET	/story_states	unstarted … accepted, rejected
GET	/effort_scales	mga magagamit na estimate scale
GET	/effort_scales/{scale_id}/values	ang mga point value sa isang scale
GET	/priority_scales · /priority_scales/{scale_id}/values	ang mga priority scale at ang mga halaga nito (dito nireresolba ang priority_id ng isang story)

Mga Organisasyon

Sa hosted na serbisyo lamang — tumatakbo sa single-organization mode ang isang self-hosted na install at hindi nito ini-mount ang mga ito (maliban sa listahan ng org). Mga tungkulin sa org ang mga tungkulin: owner, admin, member.

Method	Path	Paglalarawan
GET / POST	/organizations	Ilista ang iyong mga organisasyon / gumawa ng isa
GET / PUT / DELETE	/organizations/{oid}	Basahin, palitan ang pangalan (pangalan + slug; owner o admin), i-delete
GET / POST	/organizations/{oid}/memberships · PUT / DELETE …/memberships/{member_id}	Mga miyembro at imbitasyon; may role ceiling ang mga imbitasyon (hindi kailanman lampas sa caller; hindi kailanman iniimbitahan ang owner)
POST	/organizations/{oid}/memberships/bulk-role · …/memberships/bulk-remove	Baguhin ang role ng hanggang 200 miyembro o alisin sila nang sabay-sabay. Lahat o wala: tinatanggihan ang buong batch kung aalisin nito ang huling owner o iiwan ang isang project nang walang may-ari; sa reassign_confirmed ay ikaw ang magiging may-ari ng mga project na iyon
DELETE	/organizations/{oid}/invitations/{invitation_id}	Bawiin ang isang nakabinbing imbitasyon
POST	/organizations/{oid}/transfer-ownership	Ipasa ang tungkuling owner sa ibang miyembro
GET	/organization-invitations/{token} · POST …/{token}/accept	Lutasin / tanggapin ang isang imbitasyon sa org na ipinadala sa email
GET	/organizations/{oid}/export · POST …/export/jobs · GET …/export/jobs/{job_id} · …/export/jobs/{job_id}/download	Owner-only na export ng org: isang zip na may SQL dump at bawat attachment, pinapatakbo bilang isang job

Mga Proyekto

Method	Path	Paglalarawan
GET	/projects	Ilista ang iyong mga proyekto (limit ≤ 200)
POST	/projects	Gumawa ng proyekto
GET	/projects/{id}	Kunin ang mga detalye ng proyekto (viewer)
PUT	/projects/{id}	I-update ang mga setting ng proyekto (manager)
DELETE	/projects/{id}	Mag-delete ng proyekto (manager)
POST / DELETE	/projects/{id}/pin	I-pin / i-unpin ang proyekto sa iyong listahan ng proyekto
POST	/projects/{id}/transfer-organization	Ilipat ang proyekto sa ibang organisasyon — dapat ay Manager ng proyekto ang caller at owner o admin ng target na organisasyon
POST	/projects/{id}/slack/test	Magpadala ng test message sa Slack feed ng proyekto (manager)
GET / POST	/projects/{id}/showcase_claim_eligibility · /projects/{id}/showcase_claim · /projects/{id}/showcase_seed	Mga pampublikong showcase project: suriin kung maaari mong i-claim ang isa, i-claim ito, i-seed ito (para sa mga product admin ang pag-seed; 404 ang nakukuha ng iba)
GET	/projects/{id}/audit-log	Pagbasa ng audit log — project history kasama ang per-story / per-epic na aktibidad sa pamamagitan ng surface=; nag-iiba ang access ayon sa surface, tingnan sa ibaba
GET	/projects/{id}/events	Cursor-paginated na event stream (member) — tingnan ang Events

Mga query parameter ng audit log: event_type= (isang uri o comma-separated na listahan), limit= (default na 50, hanggang 1000), before= (keyset cursor na <ISO-8601>|<audit_id> — ipasa ang next_cursor ng nakaraang pahina), surface= (project_history, story_activities, epic_activities), target_id= (ang id ng story/epic — kailangan kapag surface=story_activities o epic_activities). Access: ang hindi na-filter na log ay (manager); ang surface=project_history ay (viewer), na naka-redact ang email ng mga miyembro kapag itinatago ito ng proyekto; ang story_activities / epic_activities ay mababasa ng sinumang miyembro ng proyekto, at anonymous sa mga pampublikong proyekto na may na-redact na PII ng actor.

Mga miyembro, agent, at agent key

Method	Path	Paglalarawan
GET	/projects/{id}/memberships	Ilista ang mga miyembro (viewer)
POST	/projects/{id}/memberships	Mag-imbita ng miyembro sa pamamagitan ng email (manager)
PUT	/projects/{id}/memberships/{mid}	I-update ang tungkulin (manager)
DELETE	/projects/{id}/memberships/{mid}	Mag-alis ng miyembro (manager)
POST	/projects/{id}/memberships/bulk-role · …/memberships/bulk-remove	Palitan ang tungkulin ng, o alisin, ang maraming miyembro nang sabay-sabay (manager)
GET	/projects/{id}/addable-members · POST /projects/{id}/members/add-existing	Mga miyembro ng org na wala pa sa proyekto / magdagdag ng isa nang walang email na imbitasyon — (manager) at owner o admin ng org
POST	/projects/{id}/members/join	Sumasali ang isang owner o admin ng org sa isang proyekto sa kanilang org bilang manager, o ipino-promote ang sarili bilang isa (ang aksyong Make me owner sa listahan ng proyekto)
GET / POST	/projects/{id}/agent_keys	Ilista (manager) / mag-mint ng mga agent key — mga taong nasa creator-roles policy ng proyekto ang tungkulin; hindi makakapag-mint ang mga agent key
PUT / DELETE	/projects/{id}/agent_keys/{kid}	I-edit ang pangalan, tungkulin, o mga response hint ng key / bawiin ito (manager)
GET	/projects/{id}/agent_keys/onboarding	Ang onboarding bundle: mga prompt at config file para sa mga karaniwang agent client
GET	/projects/{id}/agents · GET / PUT / DELETE /projects/{id}/agents/{aid}	Ang mga agent ng proyekto at ang kanilang mga profile (pangalan, initial, paglalarawan, kulay); binabawi ng DELETE ang agent at lahat ng key nito — isang manager o ang gumawa ng agent
POST	/projects/{id}/agents/{aid}/rotate-key · /projects/{id}/agents/{aid}/avatar	I-rotate ang key ng isang agent (pinananatili ang identidad at kasaysayan) / i-upload ang avatar nito

Mga Story

Lahat ng story write ay nangangailangan ng tungkuling member. Ang paggawa ng story na may mga petsang nakaraan, import provenance (import_source / import_external_id), o mga panlabas na owner o requester ay nangangailangan ng (manager).

Method	Path	Paglalarawan
GET	/projects/{id}/stories	Ilista ang mga story (paginated, mafi-filter) (viewer)
POST	/projects/{id}/stories	Gumawa ng story
GET	/projects/{id}/stories/{sid}	Kunin ang isang story (viewer)
PUT	/projects/{id}/stories/{sid}	I-update ang isang story
DELETE	/projects/{id}/stories/{sid}	Mag-delete ng story
POST	/projects/{id}/stories/{sid}/transitions	Baguhin ang estado nang may validation
POST	/projects/{id}/stories/{sid}/reject · /projects/{id}/stories/{sid}/restart	Tanggihan ang isang delivered na story / ibalik sa started ang isang tinanggihan (terminal ang rejected para sa /transitions)
POST	/projects/{id}/stories/{sid}/archive · /projects/{id}/stories/{sid}/unarchive	I-archive / i-unarchive ang isang story
POST	/projects/{id}/stories/bulk-unarchive	I-unarchive ang maraming story
POST	/projects/{id}/stories/bulk_transition	I-transition ang maraming story (1–100) nang sabay-sabay
POST	/projects/{id}/stories/bulk-archive · bulk-delete · bulk-duplicate · bulk-move	I-archive, i-delete, i-duplicate, o ilipat (sa isang panel / posisyon) ang maraming story
POST	/projects/{id}/stories/{sid}/duplicate	I-duplicate ang isang story
POST / DELETE	/projects/{id}/stories/{sid}/epics · …/epics/{eid}	Ang pagiging kasapi ng story sa mga epic
GET	/short-links/{code} · /story-references	I-resolve ang isang /s/<code> short link sa story nito / i-resolve ang hanggang 100 reference — codes= (comma-separated na mga short-link code) at ids= (comma-separated na project_id:story_id) — sa mga story na mababasa ng caller

Mga query parameter ng listahan ng story: archived= (exclude bilang default / include / only — ang tatlong-estadong filter ng naka-archive; pumapalit sa deprecated na include_archived=true, na alias na ngayon ng archived=include), include_done=true (isinasama ang mga story ng Done panel na naka-freeze sa mga nakaraang iteration, hindi kasama bilang default). Sumusunod ang pagination (cursor= / limit= / offset=) at ang mga sparse fieldset (fields=) sa Pagination at Field projection.

Create (POST …/stories): { "name" (required), "story_type": "feature|bug|chore|release", "description"?, "estimate"?, "current_state"?, "icebox"?, "labels"? }. Ang estimate ay ang label ng halaga sa scale bilang isang string ("3", "13"); tinatanggihan ang isang JSON number. Tinatanggap ng labels ang ["auth"] o [{ "name": "auth" }]; nililikha ang hindi kilalang mga label. Mga default: story_type=feature, current_state=unstarted.

Update (PUT …/stories/{sid}): parehong mga field, lahat opsyonal, kasama ang "position" (float), "force_state_change" (bool), at "expected_version" (integer, ang version ng story — tinatanggihan ang pag-save ng paglalarawan nang may 409 stale_write kung nagbago ang paglalarawan pagkatapos ng bersyong iyon). Ang mas lumang "expected_updated_at" (RFC 3339) ay deprecated at gagana pa sa isang release: kapag ipinadala kasama ng paglalarawan at walang expected_version, tinatanggihan ang pag-save nang may 409 stale_write maliban kung katumbas ito ng updated_at ng story. Iginagalang din ng mga story write ang If-Match laban sa ETag ng story; ang hindi pagtugma ay 412 precondition_failed.

Transition (POST …/transitions): { "to": "<state>" }. Ang field ay to. Nagbabalik ng { story_id, state }. Ilegal na galaw → 422 invalid_transition na may details: { from, to, allowed }.

Bulk transition (POST …/bulk_transition): { "story_ids": [int,…] (1–100), "to": "<state>" }. Bawat story ay hinuhusgahan nang nag-iisa; nagbabalik ng { results: [ { id, status: "ok" } | { id, status: "failed", error } ] }.

Mga sub-resource ng story

Lahat ay member. Ang List/GET sa karamihan ay (viewer). Ang pag-delete ng attachment o link attachment ay nangangailangan ng nag-upload nito o ng (manager).

Method	Path	Body / mga tala
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) } o { comment_emoji }. Tumatanggap ang GET ng fields= (allowlist: comment_id, story_comment_id, story_id, comment_text, comment_emoji, member, created) pati ng 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}	Paglikha: { url, link_type?, title? }; pag-update: { url, title? } — ang link_type ∈ relates_to, duplicates, blocks, is_blocked_by, pull_request, branch, other; awtomatikong nabibigyan ng uri ang mga GitHub /pull/ at /tree/ na URL
GET / POST	/projects/{id}/stories/{sid}/reviews · PUT/DELETE …/reviews/{rid}	Create: { reviewer_id? / reviewer_agent_id?, comment? } — alisin pareho upang italaga ang sarili mo. Update: { status, comment? }
GET / POST	/projects/{id}/stories/{sid}/owners · DELETE …/owners/{mid} · DELETE …/owners/agents/{aid}	{ member_id? / agent_id? } — alisin pareho upang idagdag ang caller
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 } — isang umiiral na label ng proyekto; gumawa ng mga label gamit ang POST /projects/{id}/labels, o ipadala ang labels sa PUT ng story
GET / POST	/projects/{id}/stories/{sid}/attachments (+ /json) · DELETE …/attachments/{aid}	multipart upload — video ≤ 200 MB, PDF / Word / Excel ≤ 25 MB, mga larawan / CSV / teksto ≤ 10 MB; ang list ay (viewer)
GET / POST	/projects/{id}/stories/{sid}/link-attachments · DELETE …/link-attachments/{laid}	Mga link attachment — isang panlabas na URL na itinatago kasama ng mga file attachment sa halip na bilang code link
GET	/attachments/{token} · /api/v1/avatars/{token}	Mga token-addressed na read ng isang attachment o avatar — ang mga URL na ibinibigay ng API; hindi kailangan ng X-TrackerToken

Mga Epic

Parehong hugis gaya ng mga story, bawas ang state machine. member para sa mga write at para sa mga listahan ng comment, owner, at follower; (viewer) para sa listahan ng epic, sa isang epic, at sa mga listahan ng attachment.

Method	Path	Paglalarawan
GET / POST	/projects/{id}/epics · GET / PUT / DELETE …/epics/{eid}	May dalang pangalan, Markdown na paglalarawan, at isang backing label na nag-uugnay sa kanilang mga story ang mga epic
GET / POST / PUT / DELETE	…/epics/{eid}/comments · …/comments/{cid}	Mga comment ng epic
GET / POST / DELETE	…/epics/{eid}/owners · …/followers (+ mga variant na /agents/{aid})	Mga owner at follower, miyembro man o agent — naipapasa sa mga story nito ang mga owner ng isang epic
GET / POST / DELETE	…/epics/{eid}/attachments (+ /json) · …/link-attachments	Mga attachment, parehong mga limitasyon gaya ng mga story
GET	/projects/{id}/analytics/epics · …/analytics/epics/{eid}	Progreso kada epic: burnup, throughput, kalusugan, forecast (viewer)

Mga Label

member para sa mga write, (viewer) para sa mga read.

Method	Path	Paglalarawan
GET / POST	/projects/{id}/labels	Ilista / lumikha ng label
GET / PUT / DELETE	/projects/{id}/labels/{lid}	Basahin / i-update / i-delete ang label
POST	/projects/{id}/labels/{lid}/archive	I-archive (soft-hide) ang label

Mga Iteration

Bukas ang mga read sa anumang tungkulin sa proyekto, at anonymous sa isang pampublikong proyekto.

Method	Path	Paglalarawan
GET	/projects/{id}/iterations	Ilista ang mga iteration (≤ 500 kada pahina; may dalang ETag at ang mga continuation header na X-Tracker-Pagination-* kapag naputol)
GET	/projects/{id}/iterations/{itid}	Isang iteration
GET	/projects/{id}/iterations/first-preview	Ang saklaw ng petsa, inaasahang velocity at dami ng pupunuin mula sa Backlog ng iteration na lilikhain ng pagsulat na nagsisimula nito, o ng kasalukuyang iteration kapag mayroon na (member)
POST	/projects/{id}/iterations	Gumawa ng manu-manong iteration (manager)
DELETE	/projects/{id}/iterations/{itid}	Mag-delete ng iteration (manager)
PUT	/projects/{id}/iterations/{itid}/velocity	I-override ang velocity ng isang iteration nang hindi binabago ang strategy ng proyekto (manager)
GET	/projects/{id}/iterations/{itid}/done-stories	Ang mga tinanggap na story ng isang saradong iteration, paginated

Search, metrics, preferences

Method	Path	Paglalarawan
GET	/projects/{id}/search?q=…	Makapangyarihang paghahanap — full-text + mga facet / date-range / people qualifier (DSL na istilong GitHub); nagbabalik ng { results, total, limit, offset }. Alias ng q ang query; nagpa-paginate ang limit= (default 50, max 1000) / offset=; nag-aayos ang sort= ayon sa relevance (default), created, created_asc, state, o updated. (viewer) — tingnan ang Gabay
GET	/projects/{id}/metrics/{velocity,burndown,story-types,contributors}	Ang mga serye ng Metrics page (viewer); nasa ilalim ng /analytics/epics sa itaas ang mga metric ng epic
GET	/projects/{id}/backlog/grouping	Ang mga ipinoproyektong grupo ng iteration ng Backlog (viewer)
GET / PUT	/projects/{id}/preferences	Ang iyong mga kagustuhan sa board para sa proyektong ito — anumang tungkulin sa proyekto, sarili mong hilera lamang

Events

Method	Path	Paglalarawan
GET	/projects/{id}/events	Cursor-paginated na event stream (member) — nakakakuha ng 403 ang mga viewer

Mga query parameter: since_id=<event_id> (ang since ang mas lumang alias; nananaig ang since_id kapag parehong ipinadala), types=story.created,story.transitioned,comment.added,…, limit= (default na 100, ≤ 500), cursor=. Ang tugon ay { items, next_since_id, next_cursor }: itago ang next_since_id at ipasa ito pabalik bilang since_id upang magpatuloy; null ang next_cursor sa huling pahina.

Mga Notipikasyon

Ang pinag-isang in-app na feed ng notipikasyon: mga first-class na hilera ng notipikasyon (mga hiling ng review, aktibidad ng story, mga imbitasyon, …) na pinagsama sa inbox ng @-banggit sa iisang stream, pinakabago muna. May prefix ng pinagmulan ang mga id ng feed (nt-… / sc-… / ec-…). Binabasa ng mga session ng miyembro at ng mga key na ea_user_* ang kanilang mga hilerang panig-miyembro; ng mga key na ea_agent_* ang kanilang mga hilerang panig-agent.

Method	Path	Paglalarawan
GET	/me/notifications	Ang iyong feed ng notipikasyon. Mga filter: unread=true, since_id=, kind= (mentions / reviews / stories / invitations); mag-page gamit ang cursor= / limit=
GET	/me/notifications/unread-count	Kabuuang hindi pa nababasa — { unread_count, by_category: { mentions, reviews, stories, invitations } }
POST	/me/notifications/read-all	Markahan lahat bilang nabasa; ibinabalik ang mga sariwang bilang
POST	/me/notifications/{id}/ack	Markahan ang isang item bilang nabasa (idempotent)
POST	/me/notifications/{id}/accept	Tanggapin ang imbitasyon sa proyekto / organisasyon mula mismo sa feed (mga token ng miyembro lamang)
POST	/me/notifications/{id}/decline	Tanggihan ang imbitasyon sa proyekto / organisasyon (mga token ng miyembro lamang)
GET	/me/notifications/resolve-invite?token=…	Itugma ang token ng imbitasyong ipinadala sa email sa id ng iyong notipikasyon — { "id": "nt-…" } o { "id": null }
GET	/me/notifications/stream	Live na push — Server-Sent Events (text/event-stream); tingnan sa ibaba

Ang stream endpoint ay hindi JSON endpoint kaya wala ito sa OpenAPI spec: pinananatili nitong bukas ang koneksyon at naglalabas ng frame na walang payload ({"type":"notification","kind":…}) tuwing may bagong dumarating, bilang hudyat sa client na kunin muli ang feed. Pinuputol ang mga koneksyon sa panig ng server pagkatapos ng 45 minuto — muling kumonekta at muling mag-authenticate. Mga session ng miyembro at mga key na ea_user_* lamang; tumatanggap ng 403 ang mga key na ea_agent_*.

Import (manager)

Method	Path	Paglalarawan
POST	/projects/{id}/import	Mga file na pinagmulan: source= ∈ pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json, eat. Multipart file=. Synchronous — sumasagot gamit ang mga bilang ng resulta.
POST	/projects/{id}/import/json	JSON body; hindi kailangan ng file ng source=github — owner, repo, opsyonal na token, at ang mga opt-in na flag na include_pull_requests / include_milestones / include_releases / include_dependencies, at include_comments (default true); nagpapadala ng file_base64 ang mga file na pinagmulan. Asynchronous: nagbabalik ng 202 { import_id, status }. Kumukuha ang server sa pamamagitan ng GraphQL API ng GitHub, na tumatanggi sa mga anonymous na tumatawag, kaya laging may token na nakakarating sa GitHub — ang sa iyo, o ang shared na token ng deployment. Tingnan ang Gabay.
GET	/projects/{id}/imports/{import_id}	I-poll ang isang job: dumadaan ang status sa pending → fetching → writing → done | failed, na may progress_current / progress_total habang kumukuha at ang mga bilang ng resulta sa done

Iisang JSON import ang tumatakbo kada proyekto sa isang pagkakataon; ang ikalawang POST …/import/json habang may tumatakbo pa ay 409 import_already_running. Kapag may check_unpointed_estimates: true (mga file source; hindi pinapansin sa github), ang file na may mga estimate ng bug o chore na hindi pinupuntusan ng proyekto ay tinatanggihan ng 409 import_unpointed_estimates at details.count bago magsimula ang anumang job; kung walang flag, itatapon ng import ang mga estimate na iyon at mag-uulat ng { code: "estimates_unpointed_dropped", count } sa warnings ng resulta. Ini-preview ng dry_run: true (JSON body o dry_run=true multipart) ang anumang pinagmulan: ipina-parse, nireresolba, ide-de-dupe, naglalabas ng parehong mga bilang na { imported, skipped, errors, unmatched }, pagkatapos ay ibinabalik sa dati — walang isinusulat. Mga hangganan: isang 10 MiB na file (400 import_too_large) at 5,000 story kada import para sa mga pinagmulang nakabatay sa file (400 import_too_many_records); walang isinusulat. Ang request body na lampas sa 16 MiB ay tinatanggihan nang mas maaga ng 413 request_too_large. Walang hangganan ang pinagmulang GitHub — nagko-commit ito nang tipak-tipak sa halip na sa iisang transaksyon. Idempotent ang muling pag-import kada source id — ang mga hilerang na-import na ay nilalaktawan, hindi ni-doble.

Export

Method	Path	Paglalarawan
GET	/projects/{id}/export/formats	Mga nakarehistrong format: { id, name, content_type, drops, includes_archived }. Anumang tungkulin sa proyekto.
GET	/projects/{id}/export/{format}	Mag-download ng isa (manager). Interchange: eat (buong katapatan), jira, pivotal, shortcut, trello, asana, gitlab, linear, plane, plane_json; mga dokumento: pdf, docx.
GET	/projects/{id}/export/attachments	Bawat attachment bilang isang browsable na zip (pinapanatili ng mga file ang orihinal na pangalan; JSON + CSV na manifest) (manager).

Ang mga document export (pdf, docx) ay tumatanggap ng karagdagang query parameter: page_size= (letter bilang default / a4 / legal / folio), from= / to= (mga hangganan ng story window — RFC 3339 o payak na YYYY-MM-DD; nasa saklaw ang story kapag pumapasok dito ang created o completed_at nito), include_icebox= / include_backlog= (parehong false bilang default, kaya ipinapakita lang ng naibabahaging export ang naka-iskedyul / kasalukuyang ginagawang trabaho). Binabalewala ang mga ito ng mga interchange na CSV format.

Mga backup at restore (manager)

Method	Path	Paglalarawan
GET / POST	/projects/{id}/backups · GET …/backups/{snapshot_id} · …/backups/health	Ilista ang mga snapshot, kumuha ng isa ngayon, basahin ang isa, at ang buod ng kalusugan ng retention
POST	/projects/{id}/restores · POST …/restores/partial · GET …/restores/{restore_id}	I-restore ang isang buong snapshot, o mga piling table mula rito, at i-poll ang restore

Nasa sensitive na rate-limit tier (sa ibaba) ang mga POST.

MCP at OAuth provider

Ang East Agile Tracker ay isang OAuth 2.1 provider para sa mga MCP client. Natutuklasan ito ng isang client sa /.well-known/oauth-authorization-server at /.well-known/oauth-protected-resource/mcp, ipinapadala ka sa /oauth/authorize (ang consent page), ipinapalit ang code sa /oauth/token, at pagkatapos ay nagsasalita ng MCP sa /mcp gamit ang nakuhang ea_mcp_* token. Inililista at binabawi ang mga grant sa /me/oauth_grants. May sariling rate-limit tier ang mga provider endpoint.

Idempotency

Tinatanggap ng mga write endpoint (POST, PUT, DELETE) ang header na Idempotency-Key. Parehong key + parehong body ay nag-rereplay ng naka-cache na tugon (24-oras na window); parehong key + isang kaibang body ay nagbabalik ng 409 idempotency_conflict. Saklaw ang key ng kredensyal na nagpadala nito. Hindi inilalapat sa GET/HEAD/OPTIONS, /openapi.json at /docs, /api/auth/*, /mcp, anumang path na naglalaman ng /attachments, o anumang multipart/* na request; hindi kailanman naka-cache ang request na walang kredensyal. Hindi kailanman naka-cache ang mga tugong huminto bago ang sagot ng domain — 401, 403, 404, 429, at bawat 5xx — kaya naaabot ng isang retry pagkatapos ng alinman sa mga ito ang handler; ang 400, 409, 412, at 422 ay sagot ng domain at nire-replay gaya ng isang tagumpay.

Pagination

Tinatanggap ng mga list endpoint ang cursor=<opaque> at limit=<n>. Kapag itinakda, ang tugon ay { "items": [...], "next_cursor": "<str|null>" }; ipasa pabalik ang next_cursor upang mag-page. Nag-iiba kada endpoint ang hangganan ng limit: 200 sa mga story, comment, at proyekto; 500 sa mga event; 1000 sa audit log. Nagpa-page ang search gamit ang limit (≤ 1000) at offset sa halip na cursor at nagbabalik ng { results, total, limit, offset }.

Ang isang karaniwang listahan (walang cursor/limit) na kinailangang putulin ang tugon nito ay nagsasabi nito sa mga header — X-Tracker-Pagination-Truncated, X-Tracker-Pagination-Limit, X-Tracker-Pagination-Offset, at X-Tracker-Pagination-Next-Offset; ipasa pabalik ang huli bilang offset= para sa susunod na pahina. Walang header ng kabuuang bilang.

Field projection

Tinatanggap ng mga listahan ng story, comment, at proyekto ang fields= (comma-separated) upang magbalik lamang ng mga tiyak na field. Palaging kasama ang id ng rekurso (story_id, story_comment_id at comment_id, project_id); ang hindi kilalang pangalan ng field ay nagbabalik ng 400 validation_failed na may mga nagkakasalang pangalan sa details.fields.

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

Format ng error

Bawat JSON na error ay may code at error; ang ilan ay nagdaragdag ng details:

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

Status	code	Kailan
400	invalid_parameter	masamang input; mensahe sa error. Nagdaragdag ang field validation (blank/length/null-byte/email) ng details.fields at details.constraint; tanging payak na bad-request error ang walang details
400	validation_failed	structured na input error; ang details.fields ay isang array ng mga nagkakasalang pangalan ng field
400	mga domain code	isang pagtangging partikular sa route na may sariling code at walang details — hal. unsupported_export_format, import_too_large, import_unknown_source
401	unauthenticated	nawawala/imbalidong token
403	unauthorized_operation	na-authenticate ngunit hindi sapat na tungkulin
404	unfound_resource	hindi nahanap — ibinabalik din sa mga hindi-miyembro
409	conflict	salungatan sa rekurso (hal. duplicate)
409	idempotency_conflict	Idempotency-Key na muling ginamit na may kaibang body
409	stale_write · import_already_running · import_unpointed_estimates	nagbago ang paglalarawan pagkatapos ng iyong expected_version (o hindi na tugma ang expected_updated_at) · may import nang tumatakbo · may mga estimate ng bug o chore ang file na hindi pinupuntusan ng proyekto (details.count)
412	precondition_failed	hindi tumugma ang If-Match sa kasalukuyang ETag ng rekurso; dala ng details ang expected at current
413	request_too_large	lumampas ang body sa size limit ng route
422	invalid_transition	ilegal na galaw ng estado; dala ng details ang { from, to, allowed }
429	rate_limited	masyadong maraming request mula sa IP na ito sa isang route na may rate limit; header na Retry-After
500	internal_error	pagkakamali ng server — generic na mensahe; ligtas ulitin
502	upstream_error	pumalya ang isang serbisyong inaasahan ng route (hal. GitHub)
503	not_configured	wala sa deployment ang integration na kailangan ng route na ito (SMS, object storage, …)

Ang details.fields ay isang JSON na array ng mga pangalan ng field (hal. ["to"]), kung minsan ay may dagdag na mga key tulad ng max. Walang field→message na mapa.

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

Mga rate limit

Kada client IP, sa ilang route lamang; walang rate limit ang authenticated na API traffic sa ibang lugar. Mga default (bawat pares ay sustained rate at burst, naaayos ng operator):

• Auth — /api/auth/*: 0.5 req/s, burst 20.
• OAuth provider — /oauth/*: 1 req/s, burst 60.
• Public — /api/contact: 0.2 req/s, burst 10.
• Feedback — /api/v1/feedback at /api/v1/feedback/with-screenshot: tatlong magkapatong na tier — isang submit kada 15 s, 10 kada oras, 36 kada araw.
• Avatars — ang unauthenticated na avatar redirect: 20 req/s, burst 200.
• Sensitive — ang mga backup at restore na POST: ~0.002 req/s, burst 5.

Ang isang nalampasang limit ay nagbabalik ng 429 na may header na Retry-After at ang karaniwang JSON na error envelope, code: "rate_limited".