API මාර්ගෝපදේශය

East Agile Tracker API එක මානවයන් සඳහා මෙන්ම ඒජන්තයන් සඳහාද නිර්මාණය කර ඇත. UI එකේ ඔබට කළ හැකි සියල්ල, ඔබට API එක හරහා කළ හැකිය — සහ UI එක නොපෙන්වන දේවල් කිහිපයක්ද එහි ඇත.

මෙම මාර්ගෝපදේශය ඔබව ශුන්‍යයේ සිට “ඔබේ බැක්ලොග් එක scripting කිරීම” දක්වා මිනිත්තු දහයකට අඩු කාලයකින් ගෙන යයි. සම්පූර්ණ endpoint යොමුව සඳහා, API පිරිවිතර බලන්න.

යතුරු වර්ග දෙකක්

ඔබ X-TrackerToken header එකේ API key එකකින් සත්‍යාපනය වේ. වර්ග දෙකක් ඇත:

User keys (ea_user_…) — ඔබ ලෙස ක්‍රියා කරයි. ඒවා Account Settings → API Keys හි සාදන්න. පුද්ගලික scripts, CLI මෙවලම්, integrations සඳහා මේවා භාවිතා කරන්න.
Agent keys (ea_agent_…) — එක් ව්‍යාපෘතියක නම් කරන ලද ඒජන්තයෙකු ලෙස ක්‍රියා කරයි. ව්‍යාපෘති owner කෙනෙකු ලෙස Project Settings → Agents හි ඒවා සාදන්න. නම් කරන ලද කණ්ඩායම් සාමාජිකයන් ලෙස ව්‍යාපෘතියට සහභාගි විය යුතු AI ඒජන්තයන් සඳහා මේවා භාවිතා කරන්න — Claude Code, Codex, ඔබේම.

වෙනස්කම්:

	User key	Agent key
විෂය පථය	ඔබේ සියලුම ව්‍යාපෘති	එක් නිශ්චිත ව්‍යාපෘතියක්
විගණන ලොගයේ අනන්‍යතාව	ඔබේ නම	ඒජන්තයාගේ නම
භූමිකාව	එක් එක් ව්‍යාපෘතියේ ඔබේ භූමිකාව	යතුර සෑදීමේදී සකස් කරයි (viewer හෝ member)
අවලංගු කිරීම	යතුරක් අවලංගු කරන්න; ඔබ වෙනත් යතුරු/සැසි හරහා ප්‍රවේශය තබා ගනියි	යතුරක් අවලංගු කරන්න; ඒජන්තයා වහාම ප්‍රවේශය නැති කරයි
හොඳම	පුද්ගලික ස්වයංක්‍රීයකරණය, scripts	ඉතිහාසයේ ඔබෙන් වෙන් කර හඳුනාගත හැකි විය යුතු AI ඒජන්තයන්

ඔබ එම header විලාසයට කැමති නම් Authorization: Bearer … ද ක්‍රියා කරයි.

හෙලෝ, API

ඔබේ ව්‍යාපෘති ලබා ගන්න:

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

හෝ agent key එකක් සඳහා, එය පරිමාණය වී ඇති ව්‍යාපෘතිය ලැයිස්තුගත කරන්න:

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

API එක JSON, REST-ish, /api/v1/ හි අනුවාද කර ඇත. මානවයන්ට සහ ඒජන්තයන්ට එකම හැඩයන්.

ව්‍යාපෘතියක් සෑදීම

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
  }'

ප්‍රතිචාරයට project_id සහ සේවාදායකය යෙදූ ඕනෑම පෙරනිමි (estimate scale, done state, ආදිය) ඇතුළත් වේ.

ස්ටෝරියක් සෑදීම

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"]
  }'

ස්ටෝරියක් ජීවන චක්‍රය හරහා ගෙන යාම

transition endpoint එක ඉල්ලූ මාරුව වලංගු කර දෝෂයකදී අවසර ලත් ඊළඟ තත්ත්ව ආපසු දෙයි:

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" }'

ක්ෂේත්‍රය to වේ (to_state නොව). මාරුව නීති විරෝධී නම් — උදා. ඔබ unstarted සිට කෙලින්ම accepted වෙත පැනීමට උත්සාහ කළා නම් — ප්‍රතිචාරය ව්‍යුහගත දෝෂ විස්තර සමඟ 422 invalid_transition වේ:

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

මෙය API එක ඒජන්ට්-හිතකාමී කරන කුඩා දේවලින් එකකි: ඒජන්තයෙකුට details.allowed කියවා, prose scraping නොකර නිවැරදි ඊළඟ මාරුව තෝරාගත හැකිය.

ස්ටෝරියකට comment කිරීම

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." }'

comment එක API key එක හිමි කරගත් අයට ආරෝපණය වේ — එය agent key එකක් නම්, comment එකේ කර්තෘ ඒජන්තයාය.

Idempotent ලිවීම්

සෑම write endpoint එකක්ම Idempotency-Key header එකක් පිළිගනියි. එම යතුරම එම body එකම සමඟ නැවත උත්සාහ කරන්න, එම ප්‍රතිචාරයම ආපසු ලබා ගන්න. එම යතුරම වෙනස් body එකක් සමඟ නැවත උත්සාහ කරන්න, 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" }'

retry ලූප වල ඒජන්තයන් සඳහා මෙය තීරණාත්මකය — ලිවීම මැද crash වන්න, එම යතුරම සමඟ නැවත උත්සාහ කරන්න, අනුපිටපත් ස්ටෝරි නැත.

Bulk transitions

ස්ටෝරි බොහෝමයක් එකවර ගෙන යන්න. එක් එක් ස්ටෝරිය ස්වාධීනව විනිශ්චය කරයි; එක් නීති විරෝධී මාරුවක් අනෙක් ඒවා අසාර්ථක නොකරයි.

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"
  }'

Event stream අනුගමනය කිරීම

මානවයන් කරන දේට ප්‍රතික්‍රියා කිරීමට අවශ්‍ය ඒජන්තයන් සඳහා, events endpoint එක poll කරන්න:

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"

ප්‍රතිචාරය actor, resource, සහ වෙනස සමඟ cursor-paginated events stream එකකි. සෑම event එකකටම ID එකක් ඇත; ඔබ නැවැත්වූ තැනින් නැවත ආරම්භ කිරීමට ඔබ දුටු අවසන් ID එක since ලෙස ලබා දෙන්න. webhooks නැත, scraping නැත, මග හැරුණු events නැත.

පෙරහන් වාක්‍ය ඛණ්ඩය සමඟ සෙවීම

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

ලබා ගත හැකි පෙරහන්:

පෙරහන	උදාහරණය	විස්තරය
`type:`	`type:feature`	ස්ටෝරි වර්ගය අනුව පෙරන්න
`state:`	`state:started`	තත්ත්වය අනුව පෙරන්න
`label:`	`label:"my label"`	label අනුව පෙරන්න
`owner:`	`owner:claire`	owner අනුව පෙරන්න
`requester:`	`requester:tomas`	requestor අනුව පෙරන්න
`has:`	`has:blocker`	blockers සහිත ස්ටෝරි
`is:`	`is:unestimated`	තක්සේරු නොකළ features

නිදහස් පෙළ මාතෘකාවට සහ විස්තරයට ගැළපේ. පෙරහන් අතරට හිස්තැන් යොදා ඒවා සංයෝජනය කරන්න — ඒවා AND කරයි.

API එක සොයා ගැනීම

සජීවී OpenAPI 3 spec එක මෙහි ඇත:

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

Swagger UI එක මෙහි ඇත:

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

/openapi.json සහ /docs සත්‍යාපනය නොකළ ඒවා — ඒජන්තයෙකුට යතුරක් ලැබීමට පෙර ගිවිසුම කියවිය හැකිය. එය යතුරක් රඳවාගත් පසු, /api/v1/meta (එයට වලංගු යතුරක් අවශ්‍ය වේ) එහි අනන්‍යතාව සහ එක් එක් ස්ටෝරි-වර්ග transition graph එක ආපසු දෙයි; reference-data lookups (/story_types, /story_states, /effort_scales) ද සත්‍යාපනය නොකළ ඒවාය. එක්ව ඒවා ඒජන්තයන්ට අත්හදා බැලීමේ-දෝෂ 403s නොමැතිව “මට මෙහි කළ හැක්කේ කුමක්ද?” යන්නට පිළිතුරු දීමට ඉඩ සලසයි.

සටහන: සේවය කරන ලද openapi.json මාර්ග ලැයිස්තුගත කරයි නමුත් දැනට හිස් request bodies සමඟ එයි — ලිවීම් සඳහා පිරිවිතර හි ඇති ක්ෂේත්‍ර හැඩයන් භාවිතා කරන්න.

WebSocket control

අන්තර්ක්‍රියාකාරී ස්වයංක්‍රීයකරණය සඳහා — script එකකින් පුරනය වූ browser session එකක් ධාවනය කිරීම, හෝ tutorials සඳහා UI එක දුරස්ථව පාලනය කිරීම — WebSocket channel එකක් ඇත:

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

බොහෝ පරිශීලකයන්ට මෙය කිසි විටෙක අවශ්‍ය නැත; REST ප්‍රමාණවත් නොවන අවස්ථා සඳහා එය එහි ඇත.

වෙනත් tracker එකකින් ආයාත කිරීම

ඔබ bulk migration එකක් scripting කරන්නේ නම්:

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"

සහාය දක්වන මූලාශ්‍ර: pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json.

දෝෂ ආකෘතිය

සියලුම දෝෂ අවම වශයෙන් මෙය සහිත JSON වේ:

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

බොහෝ දෝෂ ප්‍රතිචාර details වස්තුවක්ද ඇතුළත් කරයි — validation_failed හි details.fields (වැරදිකරු ක්ෂේත්‍ර නම් වල array එකක්), සහ 422 invalid_transition හි details.allowed (from/to සමඟ). ඒවා භාවිතා කරන්න.

Pagination

List endpoints limit සහ cursor පිළිගනියි. Cursor අපාරදෘශ්‍යය; පෙර ප්‍රතිචාරයෙන් next_cursor ලබා දෙන්න. ලාභදායී ලෙස ගණනය කළ හැකි තැන්වල මුළු ගණන් සඳහා ප්‍රතිචාර headers X-Tracker-Pagination-Total ද ඇතුළත් කරයි.

ඊළඟට කුමක්ද

API පිරිවිතර — සෑම endpoint එකක්ම, සෑම verb එකක්ම, සෑම හැඩයක්ම.
ක්‍රියාකරණ උපදෙස් → Agents — UI-පැත්ත: agent keys mint කිරීම, ඒජන්තයන් නම් කිරීම, අවලංගු කිරීම.
හැඳින්වීම — API එක පිටුපස සංකල්ප: stories, states, iterations, velocity, agents.