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 owner ay minamarkahang (owner); lahat ng iba ay nangangailangan lamang ng membership sa proyekto (o, para sa mga read na minarkahang (viewer), anumang antas ng akses).
https://eastagiletracker.com/api/v1Naghahatid ang https://api.eastagiletracker.com/api/v1 ng magkaparehong API. Lahat ng request at response ay JSON, maliban sa ilang file-upload endpoint na tumatanggap ng multipart.
Pagpapatunay
Section titled “Pagpapatunay”Bawat na-authenticate na request ay nagpapadala ng API key sa pamamagitan ng isa sa:
X-TrackerToken: <key>Authorization: Bearer <key>
Nagsisimula ang mga user key sa ea_user_. Nagsisimula ang mga agent key sa ea_agent_. Tingnan ang Gabay sa API → Dalawang uri ng key.
Mga endpoint na walang authentication: /openapi.json, /docs, ang mga endpoint na /auth/*, at ang mga reference-data na lookup (/story_types, /story_states, /effort_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
Section titled “Mga tungkulin”Tatlong antas ang nagkokontrol sa mga endpoint na scoped-sa-proyekto:
| Antas | Sino ang pumapasa | Karaniwang mga operasyon |
|---|---|---|
| viewer | viewer, member, owner | mga read (list/get stories, search, analytics) |
| member | member, owner | lahat ng write ng work-item (stories, tasks, comments, …) |
| owner | owner lamang | mga setting ng proyekto, pamamahala ng membership, agent keys, delete, import, audit log |
Ang isang hindi-miyembro ay tumatanggap ng 404 unfound_resource (hindi 403) sa mga path ng proyekto, kaya hindi maaabakada ang mga project ID.
Mga endpoint na naglalarawan sa sarili
Section titled “Mga endpoint na naglalarawan sa sarili”| Method | Path | Paglalarawan |
|---|---|---|
| GET | /openapi.json | Ang buháy na OpenAPI 3 spec. 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. |
Account / identidad
Section titled “Account / identidad”Ang mga ito ay kumikilos sa caller at nangangailangan lamang ng wastong key (walang tungkulin sa proyekto).
| Method | Path | Paglalarawan |
|---|---|---|
| POST | /auth/register | Magrehistro ng bagong account |
| POST | /auth/login | Mag-sign in, nagbabalik ng session token |
| POST | /auth/logout | Mag-sign out |
| POST | /auth/forgot-password | Humiling ng password-reset na email |
| POST | /auth/reset-password | Gumamit ng reset token upang magtakda ng bagong password |
| GET | /auth/verify-email | I-verify ang isang email address |
| POST | /auth/accept-invite/lookup | Lutasin ang invitation token → email (walang authentication) |
| POST | /auth/accept-invite | Tanggapin ang imbitasyon sa proyekto (pagkatapos mag-authenticate) |
| GET | /me | Profile ng kasalukuyang user |
| PUT | /me | I-update ang profile |
| DELETE | /me | I-delete ang account |
| PUT | /me/password | Baguhin ang password |
| PUT | /me/settings | I-update ang mga setting (theme, mga kagustuhan sa abiso) |
| POST | /me/avatar | Mag-upload ng avatar (multipart) |
| POST | /me/api-token/regenerate | Iikutin ang iyong API token — pinapawalang-bisa ang umiiral na mga session/key |
| GET | /me/api_keys · POST /me/api_keys · DELETE /me/api_keys/{id} | Pamahalaan ang user (ea_user_) na mga API key |
| GET | /me/activity | Ang iyong aktibidad sa lahat ng proyekto |
| 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 |
| POST | /contact · POST /feedback · POST /feedback/with-screenshot | Contact + in-app na feedback |
Reference data (walang authentication)
Section titled “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 |
Mga Proyekto
Section titled “Mga Proyekto”| Method | Path | Paglalarawan |
|---|---|---|
| GET | /projects | Ilista ang iyong mga proyekto |
| 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 (owner) |
| DELETE | /projects/{id} | Mag-delete ng proyekto (owner) |
| GET | /projects/{id}/audit-log | Stream ng aktibidad ng proyekto (owner) |
| GET | /projects/{id}/events | Cursor-paginated na event stream (viewer) — tingnan ang Events |
Mga miyembro at agent key
Section titled “Mga miyembro 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 (owner) |
| PUT | /projects/{id}/memberships/{mid} | I-update ang tungkulin (owner) |
| DELETE | /projects/{id}/memberships/{mid} | Mag-alis ng miyembro (owner) |
| GET / POST | /projects/{id}/agent_keys | Ilista / mag-mint ng mga agent key (owner) |
| DELETE | /projects/{id}/agent_keys/{kid} | Magbawi ng agent key (owner) |
Mga Story
Section titled “Mga Story”Lahat ng story write ay nangangailangan ng tungkuling member.
| 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/bulk_transition | I-transition ang maraming story (1–100) nang sabay-sabay |
| POST | /projects/{id}/stories/bulk-delete | Mag-delete ng maraming story |
| POST | /projects/{id}/stories/bulk-duplicate | I-duplicate ang maraming story |
| POST | /projects/{id}/stories/{sid}/duplicate | I-duplicate ang isang story |
Create (POST …/stories): { "name" (kinakailangan), "story_type": "feature|bug|chore|release", "description"?, "estimate"?, "current_state"?, "icebox"?, "labels"? }. 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) at "force_state_change" (bool).
Transition (POST …/transitions): { "to": "<state>", "reason"? }. 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>", "reason"? }. Bawat story ay hinuhusgahan nang nag-iisa; nagbabalik ng { results: [ { id, status: "ok" } | { id, status: "failed", error } ] }.
Mga sub-resource ng story
Section titled “Mga sub-resource ng story”Lahat ay member. Ang List/GET sa karamihan ay (viewer).
| 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 } |
| GET / POST | /projects/{id}/stories/{sid}/blockers · PUT/DELETE …/blockers/{bid} | { blocker_desc, resolved? } |
| GET / POST | /projects/{id}/stories/{sid}/links · DELETE …/links/{lid} | { url, link_type?, title? } |
| GET / POST | /projects/{id}/stories/{sid}/reviews · PUT/DELETE …/reviews/{rid} | { reviewer_id? / reviewer_agent_id?, 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} | { name } |
| GET / POST | /projects/{id}/stories/{sid}/attachments (+ /json) · DELETE …/attachments/{aid} | multipart upload (≤ 2 GB bawat isa); ang list ay (viewer) |
Mga Label
Section titled “Mga Label”member para sa mga write, (viewer) para sa mga read.
| Method | Path | Paglalarawan |
|---|---|---|
| GET / POST | /projects/{id}/labels | Ilista / lumikha ng label |
| PUT / DELETE | /projects/{id}/labels/{lid} | I-update / i-delete ang label |
| POST | /projects/{id}/labels/{lid}/archive | I-archive (soft-hide) ang label |
Mga Iteration
Section titled “Mga Iteration”| Method | Path | Paglalarawan |
|---|---|---|
| GET | /projects/{id}/iterations | Ilista ang mga iteration (member) |
| POST | /projects/{id}/iterations | Gumawa ng manu-manong iteration (owner) |
| DELETE | /projects/{id}/iterations/{itid} | Mag-delete ng iteration (owner) |
Search, analytics, metrics, preferences
Section titled “Search, analytics, metrics, preferences”| Method | Path | Paglalarawan |
|---|---|---|
| GET | /projects/{id}/search?query=… | Paghahanap sa filter syntax (viewer) — tingnan ang Gabay |
| GET | /projects/{id}/analytics/{overview,iteration,releases,activity,cycle-time,projections} | Analytics (viewer). Kinukuha ng iteration drilldown ang ?iteration_id= |
| GET | /projects/{id}/metrics/{velocity,burndown,story-types} | Metrics (viewer) |
| GET / PUT | /projects/{id}/preferences | Ang iyong mga kagustuhan sa board para sa proyektong ito (member) |
Events
Section titled “Events”| Method | Path | Paglalarawan |
|---|---|---|
| GET | /projects/{id}/events | Cursor-paginated na event stream (viewer) |
Mga query parameter: since=<event_id>, types=story.created,story.transitioned,comment.created,…, limit=, cursor=. Kasama sa tugon ang next_cursor. Ipasa ang huling event_id na nakita mo bilang since upang magpatuloy.
Import (owner)
Section titled “Import (owner)”| Method | Path | Paglalarawan |
|---|---|---|
| POST | /projects/{id}/import (+ /json) | Multipart upload. source= ∈ pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json. |
WebSocket
Section titled “WebSocket”wss://eastagiletracker.com/ws/control?token=<key>Para sa interaktibong UI remote-control ({ "action": "get_state", "id": "req-1" }). Hindi isang data channel — lahat ng read/write ay dumadaan sa REST. Single-instance lamang; hindi naka-fan-out sa mga replica.
Idempotency
Section titled “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. Hindi inilalapat sa GET/HEAD/OPTIONS, /auth/*, o /attachments na mga path. Hindi kailanman naka-cache ang mga 5xx na tugon — naaabot ng retry ang handler.
Pagination
Section titled “Pagination”Tinatanggap ng mga list endpoint ang cursor=<opaque> at limit=<n≤200>. Kapag itinakda, ang tugon ay { "items": [...], "next_cursor": "<str|null>" }; ipasa pabalik ang next_cursor upang mag-page. Ang ilang listahan ay nagbabalik din ng header na X-Tracker-Pagination-Total.
Field projection
Section titled “Field projection”Tinatanggap ng mga list endpoint ang fields= (comma-separated) upang magbalik lamang ng mga tiyak na field. Palaging kasama ang story_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,ownersFormat ng error
Section titled “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, walang details (karamihan sa validation: blank/length/null-byte/email) |
| 400 | validation_failed | structured na input error; ang details.fields ay isang array ng mga nagkakasalang pangalan ng field |
| 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 |
| 422 | invalid_transition | ilegal na galaw ng estado; dala ng details ang { from, to, allowed } |
| 500 | internal_error | pagkakamali ng server — generic na mensahe; ligtas ulitin |
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
Section titled “Mga rate limit”Per-key (per-IP para sa mga endpoint na walang authentication), GCRA token bucket:
- Auth —
/auth/*: 0.5 req/s, burst 20. - Public —
/contact,/feedback: 0.2 req/s, burst 10. - Sensitive — password-reset: ~0.002 req/s, burst 5.
Ang isang lumampas na limit ay nagbabalik ng 429 Too Many Requests na may header na Retry-After at isang plain-text na body (hindi ang JSON na error envelope).