API வழிகாட்டி

East Agile Tracker API மனிதர்களுக்கு எவ்வளவோ அவ்வளவு ஏஜெண்ட்களுக்காகவும் வடிவமைக்கப்பட்டுள்ளது. UI-இல் நீங்கள் செய்யக்கூடிய அனைத்தையும், API மீது செய்ய முடியும் — மேலும் UI வெளிப்படுத்தாத சில விஷயங்களும் அங்கே உள்ளன.

இந்த வழிகாட்டி உங்களை பத்து நிமிடங்களுக்குள் பூஜ்ஜியத்திலிருந்து “உங்கள் backlog-ஐ ஸ்கிரிப்ட் செய்தல்” வரை கொண்டுசெல்கிறது. முழு endpoint குறிப்புக்கு, API விவரக்குறிப்பைப் பார்க்கவும்.

இரண்டு வகை விசைகள்

நீங்கள் X-TrackerToken header-இல் ஒரு API விசையுடன் அங்கீகரிக்கிறீர்கள். இரண்டு வகைகள் உள்ளன:

• User keys (ea_user_…) — உங்களாக செயல்படுகின்றன. Account Settings → API Keys இல் அவற்றை உருவாக்கவும். தனிப்பட்ட ஸ்கிரிப்ட்கள், CLI கருவிகள், ஒருங்கிணைப்புகளுக்கு இவற்றைப் பயன்படுத்தவும்.
• Agent keys (ea_agent_…) — ஒரு திட்டத்தில் பெயரிடப்பட்ட ஒரு ஏஜெண்டாக செயல்படுகின்றன. ஒரு திட்ட owner-ஆக Project Settings → Agents இல் அவற்றை உருவாக்கவும். பெயரிடப்பட்ட அணி உறுப்பினர்களாக திட்டத்தில் பங்கேற்க வேண்டிய AI ஏஜெண்ட்களுக்கு — Claude Code, Codex, உங்களுடையது — இவற்றைப் பயன்படுத்தவும்.

வேறுபாடுகள்:

	User key	Agent key
நோக்கம்	உங்கள் அனைத்துத் திட்டங்களும்	ஒரு குறிப்பிட்ட திட்டம்
தணிக்கைப் பதிவில் அடையாளம்	உங்கள் பெயர்	ஏஜெண்டின் பெயர்
பாத்திரம்	ஒவ்வொரு திட்டத்திலும் உங்கள் பாத்திரம்	விசை உருவாக்கத்தில் அமைக்கப்படுகிறது (viewer அல்லது member)
ரத்துசெய்தல்	ஒரு விசையை ரத்து செய்யுங்கள்; மற்ற விசைகள்/அமர்வுகள் வழியாக அணுகலை வைத்திருக்கிறீர்கள்	ஒரு விசையை ரத்து செய்யுங்கள்; ஏஜெண்ட் உடனடியாக அணுகலை இழக்கிறது
சிறந்தது	தனிப்பட்ட தானியங்கி, ஸ்கிரிப்ட்கள்	வரலாற்றில் உங்களிடமிருந்து வேறுபடுத்தக்கூடிய 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-ஆன, /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 மற்றும் சர்வர் பயன்படுத்திய எந்த இயல்புநிலைகளையும் (மதிப்பீட்டு அளவீடு, 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-ஐப் படித்து, உரையை அரித்தெடுக்காமல் சரியான அடுத்த நகர்வைத் தேர்ந்தெடுக்க முடியும்.

ஒரு ஸ்டோரியில் கருத்துத் தெரிவியுங்கள்

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

API விசையை யார் சொந்தமாக்குகிறார்களோ அவருக்குக் கருத்து காரணப்படுத்தப்படுகிறது — அது ஒரு agent key எனில், கருத்தின் ஆசிரியர் ஏஜெண்ட்.

Idempotent எழுத்துகள்

ஒவ்வொரு எழுதும் 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" }'

மீண்டும் முயற்சி loops-இல் உள்ள ஏஜெண்ட்களுக்கு இது முக்கியமானது — எழுதும் நடுவில் crash, அதே விசையுடன் மீண்டும் முயற்சி, நகல் ஸ்டோரிகள் இல்லை.

மொத்த மாற்றங்கள்

ஒரே நேரத்தில் பல ஸ்டோரிகளை நகர்த்தவும். ஒவ்வொரு ஸ்டோரியும் சுயாதீனமாக மதிப்பிடப்படுகிறது; ஒரு சட்டவிரோத நகர்வு மற்றவற்றைத் தோல்வியடையச் செய்யாது.

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

நிகழ்வு ஓடையைப் பின்தொடரவும்

மனிதர்கள் என்ன செய்கிறார்கள் என்பதற்குப் பதிலளிக்க விரும்பும் ஏஜெண்ட்களுக்கு, 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"

பதில் என்பது செயல்படுத்துபவர், ஆதாரம், மற்றும் மாற்றத்துடன் நிகழ்வுகளின் ஒரு cursor-paginated ஓடை. ஒவ்வொரு நிகழ்வுக்கும் ஒரு ID உள்ளது; நீங்கள் கடைசியாகப் பார்த்த ID-ஐ since-ஆக அனுப்பி நீங்கள் விட்ட இடத்தில் தொடரவும். Webhooks இல்லை, அரித்தெடுத்தல் இல்லை, தவறவிட்ட நிகழ்வுகள் இல்லை.

வடிகட்டி தொடரியலுடன் தேடவும்

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"	லேபிளின்படி வடிகட்டவும்
owner:	owner:claire	உரிமையாளரின்படி வடிகட்டவும்
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) உம் அங்கீகரிக்கப்படாதவை. ஒன்றாக அவை ஏஜெண்ட்கள் சோதனை-மற்றும்-பிழை 403-கள் இல்லாமல் “இங்கே நான் என்ன செய்ய முடியும்?” என்பதற்குப் பதிலளிக்க அனுமதிக்கின்றன.

குறிப்பு: வழங்கப்பட்ட openapi.json பாதைகளை பட்டியலிடுகிறது ஆனால் தற்போது வெற்று request bodies-ஐ வழங்குகிறது — எழுத்துகளுக்கு விவரக்குறிப்பில் உள்ள புல வடிவங்களைப் பயன்படுத்தவும்.

WebSocket கட்டுப்பாடு

ஊடாடும் தானியங்கிக்கு — ஒரு ஸ்கிரிப்டிலிருந்து உள்நுழைந்த உலாவி அமர்வை இயக்குதல், அல்லது tutorials-க்காக UI-ஐ தொலைதூரக் கட்டுப்படுத்துதல் — ஒரு WebSocket சேனல் உள்ளது:

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

பெரும்பாலான பயனர்களுக்கு இது ஒருபோதும் தேவையில்லை; REST போதாத நிகழ்வுகளுக்கு அது இருக்கிறது.

மற்றொரு tracker-இலிருந்து இறக்குமதி

நீங்கள் ஒரு மொத்த இடம்பெயர்வை ஸ்கிரிப்ட் செய்கிறீர்கள் என்றால்:

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, ஒவ்வொரு வடிவம்.
• இயக்க வழிமுறைகள் → ஏஜெண்ட்கள் — UI-பக்கம்: ஏஜெண்ட் விசைகளை உருவாக்குதல், ஏஜெண்ட்களைப் பெயரிடுதல், ரத்து செய்தல்.
• அறிமுகம் — API-க்குப் பின்னால் உள்ள கருத்துக்கள்: ஸ்டோரிகள், நிலைகள், மறுசுழற்சிகள், வேகம், ஏஜெண்ட்கள்.