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.

Dalawang uri ng key

Nagpapatunay ka gamit ang isang API key sa header na X-TrackerToken. May dalawang uri:

• 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 bilang owner ng proyekto 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.

Ang mga pagkakaiba:

	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 o member)
Pagbawi	Magbawi ng key; pinapanatili mo ang akses sa iba pang key/session	Magbawi 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"]
  }'

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.

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.created" \
  -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.

Maghanap gamit ang filter syntax

curl "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/search?query=type:feature%20state:started%20label:mvp" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

Mga magagamit na filter:

Filter	Halimbawa	Paglalarawan
type:	type:feature	I-filter ayon sa uri ng story
state:	state:started	I-filter ayon sa estado
label:	label:"my label"	I-filter ayon sa label
owner:	owner:claire	I-filter ayon sa owner
requester:	requester:tomas	I-filter ayon sa requestor
has:	has:blocker	Mga story na may blocker
is:	is:unestimated	Hindi natatantyang mga feature

Tumutugma ang free text sa pamagat at paglalarawan. Pagsamahin ang mga filter sa pamamagitan ng pagbibigay-puwang sa mga ito — naka-AND sila.

Tuklasin ang API

Ang buháy na OpenAPI 3 spec ay nasa:

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

Nasa Swagger UI sa:

https://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) 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.

Tandaan: nililista ng inihahatid na openapi.json ang mga path ngunit sa kasalukuyan ay naghahatid ng walang laman na mga request body — gamitin ang mga hugis ng field sa Espesipikasyon para sa mga write.

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=YOUR_TOKEN')
ws.send(JSON.stringify({ action: 'get_state', id: 'req-1' }))

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 pinagmulan: pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json.

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.

Pagination

Tinatanggap ng mga list endpoint ang limit at cursor. Opaque ang cursor; ipasa ang next_cursor mula sa nakaraang tugon. Kasama rin sa mga response header ang X-Tracker-Pagination-Total para sa kabuuang bilang kung saan mura itong kalkulahin.

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.