API விவரக்குறிப்பு

முழுமையான REST endpoint குறிப்பு. பயிற்சிகள் மற்றும் எடுத்துக்காட்டுகளுக்கு, API வழிகாட்டியைப் பார்க்கவும்.

ஒரு திட்ட member வலை UI-இல் செய்யக்கூடிய அனைத்தும் இங்கே கிடைக்கின்றன — SPA இந்த அதே API-ஐ நுகர்கிறது. owner பாத்திரம் தேவைப்படும் செயல்பாடுகள் (owner) என குறிக்கப்பட்டுள்ளன; மற்ற அனைத்திற்கும் திட்ட உறுப்பினர் மட்டுமே தேவை (அல்லது, (viewer) என குறிக்கப்பட்ட reads-க்கு, எந்த அணுகல் மட்டமும்).

அடிப்படை

https://eastagiletracker.com/api/v1

https://api.eastagiletracker.com/api/v1 ஒத்த API-ஐ வழங்குகிறது. multipart-ஐ ஏற்றுக்கொள்ளும் சில file-upload endpoints தவிர, அனைத்து requests மற்றும் responses-ம் JSON.

அங்கீகாரம்

ஒவ்வொரு அங்கீகரிக்கப்பட்ட request-ம் இவற்றில் ஒன்றின் வழியாக ஒரு API விசையை அனுப்புகிறது:

• X-TrackerToken: <key>
• Authorization: Bearer <key>

User keys ea_user_ உடன் தொடங்குகின்றன. Agent keys ea_agent_ உடன் தொடங்குகின்றன. API வழிகாட்டி → இரண்டு வகை விசைகள் பார்க்கவும்.

அங்கீகரிக்கப்படாத endpoints: /openapi.json, /docs, /auth/* endpoints, மற்றும் reference-data lookups (/story_types, /story_states, /effort_scales, …). /meta அங்கீகரிக்கப்பட்டது — எந்த செல்லுபடியாகும் விசையும் வேலை செய்கிறது, ஆனால் அது திட்டம்-வரம்பிடப்படாதது (ஒரு திட்டம்-பிணைக்கப்பட்ட agent key உம் அதை அடைகிறது).

பாத்திரங்கள்

மூன்று மட்டங்கள் திட்டம்-வரம்பிடப்பட்ட endpoints-ஐ வாயிலிடுகின்றன:

மட்டம்	யார் கடக்கிறார்கள்	வழக்கமான செயல்பாடுகள்
viewer	viewer, member, owner	reads (ஸ்டோரிகளை பட்டியலிடு/பெறு, தேடல், பகுப்பாய்வுகள்)
member	member, owner	அனைத்து work-item எழுத்துகள் (stories, tasks, comments, …)
owner	owner மட்டுமே	திட்ட அமைப்புகள், உறுப்பினர் மேலாண்மை, agent keys, delete, import, audit log

ஒரு non-member திட்டப் பாதைகளில் 404 unfound_resource (403 அல்ல) பெறுகிறார், எனவே project IDs எண்ணிக்கையிடக்கூடியவை அல்ல.

சுய-விவரிக்கும் endpoints

Method	Path	விளக்கம்
GET	/openapi.json	நேரடி OpenAPI 3 spec. அங்கீகரிக்கப்படாதது.
GET	/docs	Swagger UI. அங்கீகரிக்கப்படாதது.
GET	/meta	Caller அடையாளம் (auth.kind/key_id/agent_id/project_id) + ஸ்டோரி-வகை transition graph. அங்கீகரிக்கப்பட்டது (எந்த செல்லுபடியாகும் விசையும்; திட்டம்-வரம்பிடப்படாதது). இதை முதலில் அழைக்கவும்.

கணக்கு / அடையாளம்

இவை caller மீது செயல்படுகின்றன, மேலும் ஒரு செல்லுபடியாகும் விசை மட்டுமே தேவை (திட்ட பாத்திரம் இல்லை).

Method	Path	விளக்கம்
POST	/auth/register	ஒரு புதிய கணக்கைப் பதிவு செய்யவும்
POST	/auth/login	உள்நுழையவும், ஒரு session token-ஐத் திருப்பித் தருகிறது
POST	/auth/logout	வெளியேறவும்
POST	/auth/forgot-password	ஒரு password-reset மின்னஞ்சலைக் கோரவும்
POST	/auth/reset-password	ஒரு புதிய கடவுச்சொல்லை அமைக்க ஒரு reset token-ஐப் பயன்படுத்தவும்
GET	/auth/verify-email	ஒரு மின்னஞ்சல் முகவரியைச் சரிபார்க்கவும்
POST	/auth/accept-invite/lookup	ஒரு invitation token → email-ஐத் தீர்க்கவும் (அங்கீகரிக்கப்படாதது)
POST	/auth/accept-invite	ஒரு திட்ட அழைப்பை ஏற்றுக்கொள்ளவும் (அங்கீகரித்த பிறகு)
GET	/me	தற்போதைய பயனர் சுயவிவரம்
PUT	/me	சுயவிவரத்தைப் புதுப்பிக்கவும்
DELETE	/me	கணக்கை நீக்கவும்
PUT	/me/password	கடவுச்சொல்லை மாற்றவும்
PUT	/me/settings	அமைப்புகளைப் புதுப்பிக்கவும் (theme, அறிவிப்பு விருப்பத்தேர்வுகள்)
POST	/me/avatar	Avatar-ஐப் பதிவேற்றவும் (multipart)
POST	/me/api-token/regenerate	உங்கள் API token-ஐச் சுழற்றவும் — இருக்கும் அமர்வுகள்/விசைகளை செல்லாததாக்குகிறது
GET	/me/api_keys · POST /me/api_keys · DELETE /me/api_keys/{id}	User (ea_user_) API விசைகளை நிர்வகிக்கவும்
GET	/me/activity	அனைத்துத் திட்டங்கள் முழுவதும் உங்கள் செயல்பாடு
GET	/me/data-export	உங்கள் தரவின் GDPR சுய-ஏற்றுமதி
GET	/me/consent · POST /me/consent	ஒப்புதலைப் படிக்க / பதிவு செய்ய ({ consent_type, granted })
GET	/legal/pending · POST /legal/accept	நிலுவையில் உள்ள clickwrap ஆவணங்கள் / ஏற்பைப் பதிவு செய்தல்
POST	/contact · POST /feedback · POST /feedback/with-screenshot	தொடர்பு + பயன்பாட்டுள் feedback

Reference data (அங்கீகரிக்கப்படாதது)

ஸ்டோரிகளை உருவாக்கும்போது/மதிப்பிடும்போது பயன்படுத்தப்படும் Seed lookups. நிலையான IDs.

Method	Path	விளக்கம்
GET	/story_types	feature, bug, chore, release (+ allow_points)
GET	/story_states	unstarted … accepted, rejected
GET	/effort_scales	கிடைக்கும் மதிப்பீட்டு அளவீடுகள்
GET	/effort_scales/{scale_id}/values	ஒரு அளவீட்டில் உள்ள புள்ளி மதிப்புகள்

திட்டங்கள்

Method	Path	விளக்கம்
GET	/projects	உங்கள் திட்டங்களைப் பட்டியலிடவும்
POST	/projects	ஒரு திட்டத்தை உருவாக்கவும்
GET	/projects/{id}	திட்ட விவரங்களைப் பெறவும் (viewer)
PUT	/projects/{id}	திட்ட அமைப்புகளைப் புதுப்பிக்கவும் (owner)
DELETE	/projects/{id}	ஒரு திட்டத்தை நீக்கவும் (owner)
GET	/projects/{id}/audit-log	திட்ட செயல்பாட்டு ஓடை (owner)
GET	/projects/{id}/events	Cursor-paginated நிகழ்வு ஓடை (viewer) — Events பார்க்கவும்

உறுப்பினர்களும் agent keys-ம்

Method	Path	விளக்கம்
GET	/projects/{id}/memberships	உறுப்பினர்களைப் பட்டியலிடவும் (viewer)
POST	/projects/{id}/memberships	மின்னஞ்சல் மூலம் ஒரு உறுப்பினரை அழைக்கவும் (owner)
PUT	/projects/{id}/memberships/{mid}	பாத்திரத்தைப் புதுப்பிக்கவும் (owner)
DELETE	/projects/{id}/memberships/{mid}	ஒரு உறுப்பினரை அகற்றவும் (owner)
GET / POST	/projects/{id}/agent_keys	agent keys-ஐ பட்டியலிடு / உருவாக்கு (owner)
DELETE	/projects/{id}/agent_keys/{kid}	ஒரு agent key-ஐ ரத்து செய்யவும் (owner)

ஸ்டோரிகள்

அனைத்து ஸ்டோரி எழுத்துகளுக்கும் member பாத்திரம் தேவை.

Method	Path	விளக்கம்
GET	/projects/{id}/stories	ஸ்டோரிகளைப் பட்டியலிடவும் (paginated, வடிகட்டக்கூடியது) (viewer)
POST	/projects/{id}/stories	ஒரு ஸ்டோரியை உருவாக்கவும்
GET	/projects/{id}/stories/{sid}	ஒரு ஸ்டோரியைப் பெறவும் (viewer)
PUT	/projects/{id}/stories/{sid}	ஒரு ஸ்டோரியைப் புதுப்பிக்கவும்
DELETE	/projects/{id}/stories/{sid}	ஒரு ஸ்டோரியை நீக்கவும்
POST	/projects/{id}/stories/{sid}/transitions	சரிபார்ப்புடன் நிலையை மாற்றவும்
POST	/projects/{id}/stories/bulk_transition	ஒரே நேரத்தில் பல ஸ்டோரிகளை மாற்றவும் (1–100)
POST	/projects/{id}/stories/bulk-delete	பல ஸ்டோரிகளை நீக்கவும்
POST	/projects/{id}/stories/bulk-duplicate	பல ஸ்டோரிகளை நகலெடுக்கவும்
POST	/projects/{id}/stories/{sid}/duplicate	ஒரு ஸ்டோரியை நகலெடுக்கவும்

Create (POST …/stories): { "name" (required), "story_type": "feature|bug|chore|release", "description"?, "estimate"?, "current_state"?, "icebox"?, "labels"? }. labels ["auth"] அல்லது [{ "name": "auth" }]-ஐ ஏற்றுக்கொள்கிறது; தெரியாத labels உருவாக்கப்படுகின்றன. இயல்புநிலைகள்: story_type=feature, current_state=unstarted.

Update (PUT …/stories/{sid}): அதே புலங்கள், அனைத்தும் விருப்பம், மேலும் "position" (float) மற்றும் "force_state_change" (bool).

Transition (POST …/transitions): { "to": "<state>", "reason"? }. புலம் to. { story_id, state }-ஐத் திருப்பித் தருகிறது. சட்டவிரோத நகர்வு → 422 invalid_transition உடன் details: { from, to, allowed }.

Bulk transition (POST …/bulk_transition): { "story_ids": [int,…] (1–100), "to": "<state>", "reason"? }. ஒவ்வொரு ஸ்டோரியும் சுயாதீனமாக மதிப்பிடப்படுகிறது; { results: [ { id, status: "ok" } | { id, status: "failed", error } ] }-ஐத் திருப்பித் தருகிறது.

ஸ்டோரி துணை-ஆதாரங்கள்

அனைத்தும் member. பெரும்பாலானவற்றில் List/GET (viewer).

Method	Path	Body / குறிப்புகள்
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) } அல்லது { 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? } — 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 பதிவேற்றம் (ஒவ்வொன்றும் ≤ 2 GB); list (viewer)

Labels

எழுத்துகளுக்கு member, reads-க்கு (viewer).

Method	Path	விளக்கம்
GET / POST	/projects/{id}/labels	ஒரு label-ஐ பட்டியலிடு / உருவாக்கு
PUT / DELETE	/projects/{id}/labels/{lid}	ஒரு label-ஐ புதுப்பிக்க / நீக்க
POST	/projects/{id}/labels/{lid}/archive	ஒரு label-ஐ archive (soft-hide) செய்யவும்

மறுசுழற்சிகள்

Method	Path	விளக்கம்
GET	/projects/{id}/iterations	மறுசுழற்சிகளைப் பட்டியலிடவும் (member)
POST	/projects/{id}/iterations	ஒரு கைமுறை மறுசுழற்சியை உருவாக்கவும் (owner)
DELETE	/projects/{id}/iterations/{itid}	ஒரு மறுசுழற்சியை நீக்கவும் (owner)

தேடல், பகுப்பாய்வுகள், metrics, விருப்பத்தேர்வுகள்

Method	Path	விளக்கம்
GET	/projects/{id}/search?query=…	வடிகட்டி தொடரியல் தேடல் (viewer) — வழிகாட்டியைப் பார்க்கவும்
GET	/projects/{id}/analytics/{overview,iteration,releases,activity,cycle-time,projections}	பகுப்பாய்வுகள் (viewer). Iteration drilldown ?iteration_id=-ஐ எடுக்கிறது
GET	/projects/{id}/metrics/{velocity,burndown,story-types}	Metrics (viewer)
GET / PUT	/projects/{id}/preferences	இந்தத் திட்டத்திற்கான உங்கள் போர்டு விருப்பத்தேர்வுகள் (member)

Events

Method	Path	விளக்கம்
GET	/projects/{id}/events	Cursor-paginated நிகழ்வு ஓடை (viewer)

Query parameters: since=<event_id>, types=story.created,story.transitioned,comment.created,…, limit=, cursor=. பதில் next_cursor-ஐ உள்ளடக்குகிறது. நீங்கள் கடைசியாகப் பார்த்த event_id-ஐ since-ஆக அனுப்பி தொடரவும்.

Import (owner)

Method	Path	விளக்கம்
POST	/projects/{id}/import (+ /json)	Multipart பதிவேற்றம். source= ∈ pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json.

WebSocket

wss://eastagiletracker.com/ws/control?token=<key>

ஊடாடும் UI தொலைதூரக்-கட்டுப்பாட்டிற்கு ({ "action": "get_state", "id": "req-1" }). ஒரு தரவு சேனல் அல்ல — அனைத்து reads/writes-ம் REST வழியாகச் செல்கின்றன. ஒற்றை-நிகழ்வு மட்டுமே; replicas முழுவதும் விரிக்கப்படவில்லை.

Idempotency

எழுதும் endpoints (POST, PUT, DELETE) ஒரு Idempotency-Key header-ஐ ஏற்றுக்கொள்கின்றன. அதே விசை + அதே body cached பதிலை மீண்டும் இயக்குகிறது (24-மணிநேர சாளரம்); அதே விசை + ஒரு வேறு body 409 idempotency_conflict-ஐத் திருப்பித் தருகிறது. GET/HEAD/OPTIONS, /auth/*, அல்லது /attachments பாதைகளுக்குப் பயன்படுத்தப்படவில்லை. 5xx பதில்கள் ஒருபோதும் cache செய்யப்படுவதில்லை — ஒரு மறுமுயற்சி handler-ஐ அடைகிறது.

Pagination

List endpoints cursor=<opaque> மற்றும் limit=<n≤200>-ஐ ஏற்றுக்கொள்கின்றன. அமைக்கப்பட்டால், பதில் { "items": [...], "next_cursor": "<str|null>" }; page செய்ய next_cursor-ஐ மீண்டும் அனுப்பவும். சில lists ஒரு X-Tracker-Pagination-Total header-ஐயும் திருப்பித் தருகின்றன.

புல projection

List endpoints குறிப்பிட்ட புலங்களை மட்டுமே திருப்பித் தர fields= (கமாவால் பிரிக்கப்பட்டது)-ஐ ஏற்றுக்கொள்கின்றன. story_id எப்போதும் சேர்க்கப்படுகிறது; ஒரு தெரியாத புல பெயர் details.fields-இல் குற்றவாளி பெயர்களுடன் 400 validation_failed-ஐத் திருப்பித் தருகிறது.

GET /projects/123/stories?fields=story_id,name,current_state,owners

பிழை வடிவம்

ஒவ்வொரு JSON பிழைக்கும் code மற்றும் error உள்ளது; சில details-ஐச் சேர்க்கின்றன:

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

Status	code	எப்போது
400	invalid_parameter	மோசமான உள்ளீடு; செய்தி error-இல், details இல்லை (பெரும்பாலான சரிபார்ப்பு: blank/length/null-byte/email)
400	validation_failed	கட்டமைக்கப்பட்ட உள்ளீட்டுப் பிழை; details.fields குற்றவாளி புல பெயர்களின் ஒரு array
401	unauthenticated	விடுபட்ட/தவறான token
403	unauthorized_operation	அங்கீகரிக்கப்பட்டது ஆனால் போதிய பாத்திரம் இல்லை
404	unfound_resource	கிடைக்கவில்லை — non-members-க்கும் திருப்பித் தரப்படுகிறது
409	conflict	ஆதார மோதல் (எ.கா. நகல்)
409	idempotency_conflict	Idempotency-Key வேறு body-உடன் மீண்டும் பயன்படுத்தப்பட்டது
422	invalid_transition	சட்டவிரோத நிலை நகர்வு; details { from, to, allowed }-ஐச் சுமக்கிறது
500	internal_error	சர்வர் தவறு — பொதுவான செய்தி; மீண்டும் முயற்சிக்க பாதுகாப்பானது

details.fields என்பது புல பெயர்களின் ஒரு JSON array (எ.கா. ["to"]), சில நேரங்களில் max போன்ற கூடுதல் விசைகளுடன். field→message வரைபடம் எதுவும் இல்லை.

{ "code": "validation_failed", "error": "unknown field(s): foo", "details": { "fields": ["foo"] } }

வரம்புகள்

ஒவ்வொரு-விசைக்கு (அங்கீகரிக்கப்படாத endpoints-க்கு ஒவ்வொரு-IP-க்கு), 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.

மீறப்பட்ட வரம்பு ஒரு Retry-After header மற்றும் ஒரு plain-text body உடன் 429 Too Many Requests-ஐத் திருப்பித் தருகிறது (JSON பிழை உறை அல்ல).