Gabay sa API

Ang East Agile Tracker API ay dinisenyo para sa mga agent gaya rin para sa mga tao. Lahat ng kaya mong gawin sa UI, kaya mong gawin sa API — at ilang bagay na hindi inilalantad ng UI ay naroon din.

Inihahatid ka ng gabay na ito mula sa zero tungo sa “pag-script ng iyong backlog” sa loob ng wala pang sampung minuto. Para sa buong sanggunian ng endpoint, tingnan ang Espesipikasyon ng API.

Tatlong uri ng kredensyal

Nagpapatunay ka gamit ang isang key sa header na X-TrackerToken. May dalawang uri ng key na ikaw mismo ang nagmi-mint, at isang ikatlo na kinukuha para sa iyo ng isang MCP client:

Mga User key (ea_user_…) — Kumikilos bilang ikaw. Likhain ang mga ito sa Account Settings → API Keys. Gamitin ang mga ito para sa mga personal na script, CLI tool, integration.
Mga Agent key (ea_agent_…) — Kumikilos bilang isang pinangalanang agent sa isang proyekto. Likhain ang mga ito sa Project Settings → Agents. Gamitin ang mga ito para sa mga AI agent — Claude Code, Codex, ang sarili mo — na dapat makilahok sa proyekto bilang mga pinangalanang kasama sa team.
Mga MCP token (ea_mcp_…) — Mga OAuth 2.1 access token na ibinibigay sa isang MCP client (Claude, isang IDE) pagkatapos mo itong aprubahan sa consent page. Kumikilos sila bilang ikaw, at maaari mo silang bawiin sa ilalim ng Account Settings → Connected apps.

Ang isang beses na dialog matapos gumawa ng personal na API key sa Account Settings, na naka-mask ang key sa kuhang ito

Ang form sa paggawa ng key sa tab na Agent na may pangalan at napiling role na member, sa ilalim ng setup instructions

Ang mga pagkakaiba ng dalawang uri na ikaw ang nagmi-mint:

	User key	Agent key
Saklaw	Lahat ng iyong proyekto	Isang tiyak na proyekto
Identidad sa audit log	Ang pangalan mo	Ang pangalan ng agent
Tungkulin	Ang tungkulin mo sa bawat proyekto	Itinakda sa paglikha ng key (viewer, member, o manager — hindi kailanman lalampas sa sariling tungkulin ng miyembrong nag-mint)
Pagbawi	Magbawi ng key; pinapanatili mo ang akses sa iba pang key/session	Magbawi o mag-rotate ng key; agad na nawawalan ng akses ang agent
Pinakamainam para sa	Personal na automation, mga script	Mga AI agent na dapat makilala mula sa iyo sa kasaysayan

Gumagana rin ang Authorization: Bearer … kung mas gusto mo ang istilong iyon ng header.

Hello, API

Kunin ang iyong mga proyekto:

curl https://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: $TRACKER_TOKEN"

O para sa isang agent key, ilista ang proyektong saklaw nito:

curl https://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: ea_agent_xxxxx"

Ang API ay JSON, REST-ish, naka-version sa /api/v1/. Parehong mga hugis para sa mga tao at agent.

Gumawa ng proyekto

curl -X POST https://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Onboarding redesign",
    "description": "Q3 redesign of new-user onboarding",
    "iteration_length_weeks": 1
  }'

Kasama sa tugon ang project_id at anumang default na inilapat ng server (estimate scale, done state, atbp.).

Gumawa ng story

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Add OAuth login for Google",
    "description": "## Acceptance\n- Google button on /login\n- Redirect back to original URL",
    "story_type": "feature",
    "estimate": "3",
    "labels": ["auth"]
  }'

Ang estimate ay ang label ng halaga sa scale bilang isang string — "3", o "13" sa Fibonacci scale — dahil kailangan itong tumugma sa isang punto sa scale ng proyekto. Tinatanggihan ang isang JSON number.

Igalaw ang isang story sa lifecycle

Pinapatunayan ng transition endpoint ang hinihiling na galaw at ibinabalik ang mga pinapayagang susunod na estado kapag may error:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/$STORY_ID/transitions \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "to": "started" }'

Ang field ay to (hindi to_state). Kung ilegal ang galaw — sabihin nating sinubukan mong lumaktaw mula unstarted tuwiran tungo sa accepted — ang tugon ay 422 invalid_transition na may structured na detalye ng error:

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

Ito ang isa sa maliliit na bagay na nagpapagawa sa API na agent-friendly: mababasa ng isang agent ang details.allowed at mapipili ang tamang susunod na galaw nang hindi nag-iiscrape ng prosa.

Terminal ang rejected para sa transition endpoint. Upang ibalik sa trabaho ang isang tinanggihang story, gamitin ang POST …/stories/{sid}/restart; ang POST …/stories/{sid}/reject ang anyong pandiwa ng pagtanggi sa isang story na delivered na.

Mag-comment sa isang story

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/$STORY_ID/comments \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Investigation done. Picking this up." }'

Ang comment ay iniaatribute sa kung sino man ang may-ari ng API key — kung agent key ito, ang may-akda ng comment ay ang agent.

Mga idempotent na write

Tinatanggap ng bawat write endpoint ang header na Idempotency-Key. Ulitin ang parehong key na may parehong body, makuha ang parehong tugon pabalik. Ulitin ang parehong key na may kaibang body, makuha ang 409 idempotency_conflict:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Refactor auth middleware", "story_type": "chore" }'

Kritikal ito para sa mga agent sa mga retry loop — mag-crash sa kalagitnaan ng write, ulitin gamit ang parehong key, walang dobleng story.

Mga bulk transition

Igalaw ang maraming story nang sabay-sabay. Bawat story ay hinuhusgahan nang nag-iisa; ang isang ilegal na galaw ay hindi nagpapabigo sa iba.

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/bulk_transition \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "story_ids": [101, 102, 103],
    "to": "delivered"
  }'

Sundan ang event stream

Para sa mga agent na gustong tumugon sa kung ano ang ginagawa ng mga tao, i-poll ang events endpoint:

curl "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/events?since=$LAST_CURSOR&types=story.created,story.transitioned,comment.added" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

Ang tugon ay isang cursor-paginated na stream ng mga event na may aktor, ang rekurso, at ang pagbabago. Bawat event ay may ID; ipasa ang huling ID na nakita mo bilang since upang magpatuloy mula sa kung saan ka tumigil. Walang webhook, walang scraping, walang nawawalang event. Kailangan ng stream ang tungkuling member — nakakakuha ng 403 ang isang viewer.

Paghahanap

Ang GET /projects/{id}/search?q=<query> ay nagpapatakbo ng isang makapangyarihang full-text + structured na paghahanap sa mga story ng proyekto. Ang query language ay hinango sa mga qualifier ng issue search ng GitHub — kaya karamihan sa syntax na alam mo na (o ng isang AI agent) mula sa GitHub ay magagamit din dito.

curl -G "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/search" \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  --data-urlencode 'q=payment crash type:bug,chore owner:@me created:>2026-05-01'

Ang tugon ay isang JSON envelope, na nakaranggo ang mga story ayon sa relevance:

{ "results": [ /* canonical story objects */ ], "total": 42, "limit": 50, "offset": 0 }

Ang total ay ang buong bilang ng tugma, hindi ang laki ng pahina. Mag-page gamit ang limit (default 50, max 1000) at offset; ayusin gamit ang sort=relevance (default), created, created_asc, updated, o state.

Gramatika

Free text ay tumutugma sa pamagat, reference, at paglalarawan ng isang story (full-text, may stemming at ranggo). Ibalot ang eksaktong parirala sa "panipi".
Mga qualifier ay nasa anyong field:value. Paghiwalayin ng kuwit ang mga alternatibo (OR sa loob ng isang field): type:bug,chore. Paghiwalayin ng puwang ang mga qualifier (AND sa kanilang lahat).
I-negate ang anumang termino o qualifier gamit ang paunang -: -label:wontfix.
Mga saklaw para sa mga petsa at puntos: inclusive na a..b, o bukas na >x / <x.

Mga qualifier

Qualifier	Halimbawa	Tumutugma sa
`type:`	`type:bug,chore`	(mga) uri ng story
`state:`	`state:started,finished`	(mga) estado ng workflow
`label:`	`label:"my label"`	isang label
`epic:`	`epic:"Checkout"`	mga story sa isang epic
`priority:`	`priority:p1`	priority
`points:`	`points:3` · `points:1..5` · `points:>3`	halaga o saklaw ng tantiya
`iteration:`	`iteration:42`	id ng iteration
`created:` `updated:` `started:` `completed:` `release:`	`created:2026-05-01..2026-06-01` · `updated:>2026-06-01`	isang petsa o saklaw (kada araw); ang `release:` ay ang petsa ng release ng story
`owner:` `requester:` `follower:` `reviewer:` `commenter:` `mention:`	`owner:claire` · `owner:@me`	isang tao ayon sa pangalan o email — mga miyembro at agent, kasama ang `mention:`; ikaw ang `@me`
`has:blocker`	`has:blocker`	may bukás na blocker
`is:`	`is:unestimated` · `is:icebox` · `is:backlog` · `is:blocked`	isang flag

Ang mywork: ay alias ng owner: — ang mywork:me ay owner:@me. Retirado na ang lumang qualifier na scheduled: at tahimik na binabalewala; gamitin ang release:.

Nalalapat ang comma-OR (type:bug,chore) sa mga facet qualifier; iisang halaga lang ang tinatanggap ng mga qualifier ng tao (owner: requester: follower: reviewer: commenter: mention:).

Mga halimbawa

payment crash                              full text "payment" AND "crash"
"exact phrase"                             a phrase
type:bug,chore state:started               bugs or chores that are started
owner:@me -label:wontfix                   mine, excluding the wontfix label
points:3..8 created:2026-05-01..2026-06-01 estimated 3-8, created in May
follower:tomas has:blocker                 tomas follows it and it's blocked
is:backlog updated:>2026-06-01             backlog items touched since Jun 1

Ang parehong query string ang nagpapatakbo sa search box ng board (na nagbubukas ng isang live na column ng resulta) at sa API na ito — iisang gramatika para sa mga tao at agent. Nasa roadmap ang paghahanap sa nilalaman ng mga comment, task, at blocker; sa ngayon, sinasaklaw ng free text ang sariling pamagat, reference, at paglalarawan ng story.

Tuklasin ang API

Ang buháy na OpenAPI 3 spec ay nasa:

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

Nasa Swagger UI sa:

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

Ang /openapi.json at /docs ay walang authentication — maaaring basahin ng isang agent ang kontrata bago ito magkaroon ng key. Kapag may hawak na itong key, ibinabalik ng /api/v1/meta (na nangangailangan ng wastong key) ang identidad nito at ang per-story-type na transition graph; ang mga reference-data na lookup (/story_types, /story_states, /effort_scales, /priority_scales) ay walang authentication din. Magkasama, hinahayaan nila ang mga agent na sagutin ang “ano ang kaya kong gawin dito?” nang walang trial-and-error na mga 403.

May dalang mga request-body schema para sa mga write endpoint ang inihahatid na openapi.json, kasama ang maxLength ng bawat field, kaya makakapag-validate ang isang client bago ito magpadala. Binubuod ng Espesipikasyon ang parehong mga hugis.

WebSocket control

Para sa interaktibong automation — pagmamaneho ng isang naka-log-in na browser session mula sa isang script, o remote-controlling ng UI para sa mga tutorial — may isang WebSocket channel:

const ws = new WebSocket('wss://eastagiletracker.com/ws/control?token=SESSION_JWT')
ws.send(JSON.stringify({ action: 'get_state', id: 'req-1' }))

Ang token ay ang JWT ng browser session, hindi isang API key — tinatanggihan ang isang ea_user_* o ea_agent_* key bago ang upgrade. Karamihan sa mga user ay hindi kailanman nangangailangan nito; naroon ito para sa mga kaso kung saan hindi sapat ang REST.

Mag-import mula sa ibang tracker

Kung nag-i-script ka ng isang bulk migration:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/import \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -F "source=pivotal" \
  -F "file=@pivotal_export.csv"

Mga sinusuportahang file na pinagmulan: pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json, eat (ang sariling export ng East Agile Tracker — ang round-trip na format). Synchronous na tumatakbo ang multipart endpoint at sumasagot gamit ang mga bilang ng resulta.

Nag-i-import ang GitHub mula sa API sa halip na mula sa isang file, sa pamamagitan ng JSON endpoint — walang file, ang mga coordinate lang ng repository:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/import/json \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "source": "github",
        "owner": "octocat",
        "repo": "hello-world",
        "token": "ghp_…",
        "include_pull_requests": false,
        "include_milestones": false,
        "include_releases": false,
        "include_dependencies": false
      }'

Asynchronous ang JSON endpoint: sumasagot ito ng 202 na may { "import_id", "status" } at ipo-poll mo ang GET /projects/{id}/imports/{import_id} hanggang umabot ang job sa done o failed. Iisang import lang ang tumatakbo kada proyekto sa isang pagkakataon — ang ikalawang tawag habang may tumatakbo pa ay 409 import_already_running. Ang buong loop, kasama ang mga progress field ng job, ay nasa Punuin ang isang proyekto mula sa isang GitHub repo.

Opsyonal ang token sa kahilingan, ngunit laging nagpapatotoo ang pagkuha mismo — tumatakbo ito sa GraphQL API ng GitHub, na walang anonymous na antas. Alisin ang token at ipapalit ng server ang platform token nito: pampublikong repository lang, ibinabahagi ng bawat tumatawag, at tinatanggihan nang may import_github_shared_quota_low kapag bumaba sa 500 puntos ang badyet nitong GraphQL. Ang isang pribadong repository, o isang deployment na walang naka-configure na platform token (import_github_no_token), ay humihingi ng sa iyo. Anuman ang token na tumakbo, ginagamit lamang ito para sa mga upstream na tawag sa GitHub at hindi kailanman iniimbak o ina-echo pabalik. Ang buong detalye, kasama ang 60-kahilingang REST ceiling ng GitHub na walang patotoo, ay nasa Punuin ang isang proyekto mula sa isang GitHub repo.

Dry-run na preview. Idagdag ang "dry_run": true (JSON) o -F "dry_run=true" (multipart) sa anumang pinagmulan. Ipina-parse, nireresolba, at ide-de-duplicate ng import nang eksakto gaya ng isang tunay na pagpapatakbo, naglalabas ng parehong mga bilang ng resulta (imported, skipped, errors, unmatched), pagkatapos ay ibinabalik lahat sa dati — walang isinusulat. Sa JSON endpoint, dumarating ang mga bilang sa pino-poll na job, dry run man o hindi.

Mga limitasyon. Ang isang upload body ay may hangganang 10 MiB, at ang isang import sa 5,000 story; ang paglampas sa alinman ay isang 400 na walang isinusulat. Ligtas ang muling pag-import ng isang file — ang mga hilerang na-import na (itinugma sa pamamagitan ng source id) ay nilalaktawan, hindi ni-doble.

Mag-export ng proyekto

Maaaring ilista ng anumang tungkulin sa proyekto ang mga format; owner-only ang pag-download ng isa:

# The registered export formats: { id, name, content_type, drops, includes_archived }
curl https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/export/formats \
  -H "X-TrackerToken: $TRACKER_TOKEN"

# Download one format (eat is the full-fidelity round-trip CSV)
curl https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/export/eat \
  -H "X-TrackerToken: $TRACKER_TOKEN" -o project-export.csv

Mga id ng interchange format: eat, jira, pivotal, shortcut, trello, asana, gitlab, linear, plane, plane_json, kasama ang mga document format na pdf at docx. Nada-download ang bawat attachment bilang isang zip mula sa GET /projects/{id}/export/attachments.

Format ng error

Lahat ng error ay JSON na may pinakamababa:

{
  "code": "invalid_transition",
  "error": "Cannot move story from `unstarted` to `accepted`"
}

Maraming tugon ng error ang nagsasama rin ng isang details na bagay — details.fields (isang array ng mga nagkakasalang pangalan ng field) sa validation_failed, at details.allowed (kasama ang from/to) sa 422 invalid_transition. Gamitin ang mga ito. May dalang header na Retry-After ang isang 429 rate_limited sa parehong JSON envelope.

Pagination

Tinatanggap ng mga list endpoint ang limit at cursor. Opaque ang cursor; ipasa ang next_cursor mula sa nakaraang tugon. Nag-iiba kada endpoint ang hangganan ng limit — 200 sa mga story, comment, at proyekto, 500 sa mga event, 1000 sa search at sa audit log. Ang isang karaniwang (hindi cursor) na listahan na kinailangang putulin ang tugon nito ay nagsasabi nito sa mga header: X-Tracker-Pagination-Truncated, -Limit, -Offset, at -Next-Offset, na ipapasa mo pabalik bilang offset= para sa susunod na pahina. Walang header ng kabuuang bilang.

Ano ang susunod

Espesipikasyon ng API — Bawat endpoint, bawat verb, bawat hugis.
Mga Tagubilin sa Paggamit → Mga Agent — Panig-UI: pag-mint ng mga agent key, pagpapangalan sa mga agent, pagbawi.
Panimula — Mga konsepto sa likod ng API: mga story, estado, iteration, velocity, agent.