API පිරිවිතර

සම්පූර්ණ REST endpoint යොමුව. tutorials සහ උදාහරණ සඳහා, API මාර්ගෝපදේශය බලන්න.

ව්‍යාපෘති member කෙනෙකුට web UI එකේ කළ හැකි සියල්ල මෙහි ලබා ගත හැකිය — SPA එක මෙම එකම API එකම පරිභෝජනය කරයි. owner භූමිකාව අවශ්‍ය ක්‍රියා (owner) ලෙස සලකුණු කර ඇත; අනෙක් සියල්ලට අවශ්‍ය වන්නේ ව්‍යාපෘති සාමාජිකත්වය පමණි (හෝ, (viewer) ලෙස සලකුණු කළ reads සඳහා, ඕනෑම ප්‍රවේශ මට්ටමක්).

මූලය

https://eastagiletracker.com/api/v1

https://api.eastagiletracker.com/api/v1 සමාන API එක සේවය කරයි. multipart පිළිගන්නා ගොනු-උඩුගත endpoints කිහිපයක් හැර, සියලුම requests සහ responses JSON වේ.

සත්‍යාපනය

සෑම සත්‍යාපිත request එකක්ම පහත එකකින් API key එකක් යවයි:

• 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 (ස්ටෝරි list/get, search, analytics)
member	member, owner	සියලුම work-item writes (stories, tasks, comments, …)
owner	owner පමණි	ව්‍යාපෘති සැකසුම්, සාමාජිකත්ව කළමනාකරණය, agent keys, delete, import, audit log

සාමාජිකයෙකු නොවන අයෙකුට ව්‍යාපෘති මාර්ග මත 404 unfound_resource (403 නොව) ලැබේ, ඒ නිසා ව්‍යාපෘති 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) + story-type transition graph එක. සත්‍යාපිතය (ඕනෑම වලංගු යතුරක්; ව්‍යාපෘති-පරිමාණ නොව). මෙය මුලින්ම ඇමතන්න.

ගිණුම / අනන්‍යතාව

මේවා caller මත ක්‍රියා කරන අතර වලංගු යතුරක් පමණක් අවශ්‍ය වේ (ව්‍යාපෘති භූමිකාවක් නැත).

Method	Path	විස්තරය
POST	/auth/register	නව ගිණුමක් ලියාපදිංචි කරන්න
POST	/auth/login	පුරනය වන්න, session token එකක් ආපසු දෙයි
POST	/auth/logout	පිටවන්න
POST	/auth/forgot-password	මුරපද-නැවත සැකසීමේ ඊමේල් එකක් ඉල්ලන්න
POST	/auth/reset-password	නව මුරපදයක් සැකසීමට reset token එකක් භාවිතා කරන්න
GET	/auth/verify-email	ඊමේල් ලිපිනයක් සත්‍යාපනය කරන්න
POST	/auth/accept-invite/lookup	invitation token එකක් → ඊමේල් වෙත විසඳන්න (සත්‍යාපනය නොකළ)
POST	/auth/accept-invite	ව්‍යාපෘති ආරාධනාවක් accept කරන්න (සත්‍යාපනයෙන් පසු)
GET	/me	වත්මන් පරිශීලක profile
PUT	/me	Profile යාවත්කාලීන කරන්න
DELETE	/me	ගිණුම මකන්න
PUT	/me/password	මුරපදය වෙනස් කරන්න
PUT	/me/settings	සැකසුම් යාවත්කාලීන කරන්න (theme, notification preferences)
POST	/me/avatar	Avatar උඩුගත කරන්න (multipart)
POST	/me/api-token/regenerate	ඔබේ API token භ්‍රමණය කරන්න — පවතින sessions/keys අවලංගු කරයි
GET	/me/api_keys · POST /me/api_keys · DELETE /me/api_keys/{id}	User (ea_user_) API keys කළමනාකරණය කරන්න
GET	/me/activity	සියලුම ව්‍යාපෘති හරහා ඔබේ ක්‍රියාකාරකම්
GET	/me/data-export	ඔබේ දත්ත වල GDPR ස්ව-export
GET	/me/consent · POST /me/consent	Consent කියවන්න / පටිගත කරන්න ({ consent_type, granted })
GET	/legal/pending · POST /legal/accept	පොරොත්තු clickwrap docs / පිළිගැනීම පටිගත කරන්න
POST	/contact · POST /feedback · POST /feedback/with-screenshot	Contact + යෙදුම් ඇතුළත 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	ලබා ගත හැකි estimate scales
GET	/effort_scales/{scale_id}/values	පරිමාණයක ඇති point values

ව්‍යාපෘති

Method	Path	විස්තරය
GET	/projects	ඔබේ ව්‍යාපෘති ලැයිස්තුගත කරන්න
POST	/projects	ව්‍යාපෘතියක් සාදන්න
GET	/projects/{id}	ව්‍යාපෘති විස්තර ලබා ගන්න (viewer)
PUT	/projects/{id}	ව්‍යාපෘති සැකසුම් යාවත්කාලීන කරන්න (owner)
DELETE	/projects/{id}	ව්‍යාපෘතියක් මකන්න (owner)
GET	/projects/{id}/audit-log	ව්‍යාපෘති ක්‍රියාකාරකම් stream (owner)
GET	/projects/{id}/events	Cursor-paginated event stream (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 ලැයිස්තුගත / mint කරන්න (owner)
DELETE	/projects/{id}/agent_keys/{kid}	Agent key එකක් අවලංගු කරන්න (owner)

ස්ටෝරි

සියලුම story writes වලට member භූමිකාව අවශ්‍ය වේ.

Method	Path	විස්තරය
GET	/projects/{id}/stories	ස්ටෝරි ලැයිස්තුගත කරන්න (paginated, filterable) (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" (අවශ්‍යයි), "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 } ] } ආපසු දෙයි.

ස්ටෝරි උප-resources

සියල්ල 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 upload (එකකට ≤ 2 GB); list (viewer) වේ

Labels

writes සඳහා 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) කරන්න

Iterations

Method	Path	විස්තරය
GET	/projects/{id}/iterations	Iterations ලැයිස්තුගත කරන්න (member)
POST	/projects/{id}/iterations	manual iteration එකක් සාදන්න (owner)
DELETE	/projects/{id}/iterations/{itid}	iteration එකක් මකන්න (owner)

Search, analytics, metrics, preferences

Method	Path	විස්තරය
GET	/projects/{id}/search?query=…	පෙරහන් වාක්‍ය ඛණ්ඩ සෙවුම (viewer) — මාර්ගෝපදේශය බලන්න
GET	/projects/{id}/analytics/{overview,iteration,releases,activity,cycle-time,projections}	Analytics (viewer). Iteration drilldown ?iteration_id= ගනියි
GET	/projects/{id}/metrics/{velocity,burndown,story-types}	Metrics (viewer)
GET / PUT	/projects/{id}/preferences	මෙම ව්‍යාපෘතිය සඳහා ඔබේ board preferences (member)

Events

Method	Path	විස්තරය
GET	/projects/{id}/events	Cursor-paginated event stream (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 upload. 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" }). දත්ත channel එකක් නොවේ — සියලුම reads/writes REST හරහා යයි. තනි-instance පමණි; replicas හරහා fan out නොකරයි.

Idempotency

Write endpoints (POST, PUT, DELETE) Idempotency-Key header එකක් පිළිගනියි. එම යතුර + එම body එක cached ප්‍රතිචාරය නැවත ධාවනය කරයි (පැය 24 කවුළුවක්); එම යතුර + වෙනස් body එකක් 409 idempotency_conflict ආපසු දෙයි. GET/HEAD/OPTIONS, /auth/*, හෝ /attachments මාර්ග වලට යොදන්නේ නැත. 5xx ප්‍රතිචාර කිසි විටෙක cache නොකරයි — retry එකක් handler වෙත ළඟා වේ.

Pagination

List endpoints cursor=<opaque> සහ limit=<n≤200> පිළිගනියි. සකසා ඇති විට, ප්‍රතිචාරය { "items": [...], "next_cursor": "<str|null>" } වේ; page කිරීමට next_cursor ආපසු ලබා දෙන්න. සමහර lists X-Tracker-Pagination-Total header එකක්ද ආපසු දෙයි.

ක්ෂේත්‍ර ප්‍රක්ෂේපනය

List endpoints නිශ්චිත ක්ෂේත්‍ර පමණක් ආපසු දීමට fields= (කොමාවෙන් වෙන් කළ) පිළිගනියි. story_id සැමවිටම ඇතුළත් වේ; නොදන්නා ක්ෂේත්‍ර නමක් 400 validation_failed ආපසු දෙයි, details.fields හි වැරදිකරු නම් සමඟ.

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	නරක input; පණිවිඩය error හි, details නැත (බොහෝ වලංගුකරණ: blank/length/null-byte/email)
400	validation_failed	ව්‍යුහගත input දෝෂය; details.fields යනු වැරදිකරු ක්ෂේත්‍ර නම් වල array එකකි
401	unauthenticated	token නැති/අවලංගු
403	unauthorized_operation	සත්‍යාපිත නමුත් ප්‍රමාණවත් නොවන භූමිකාව
404	unfound_resource	නොමැත — සාමාජිකයන් නොවන අයටද ආපසු දෙයි
409	conflict	resource ගැටුම (උදා. අනුපිටපත)
409	idempotency_conflict	Idempotency-Key වෙනස් body එකක් සමඟ නැවත භාවිතා කර ඇත
422	invalid_transition	නීති විරෝධී තත්ත්ව මාරුව; details { from, to, allowed } දරයි
500	internal_error	සේවාදායක දෝෂය — සාමාන්‍ය පණිවිඩය; retry කිරීම ආරක්ෂිතය

details.fields යනු ක්ෂේත්‍ර නම් වල JSON array එකකි (උදා. ["to"]), සමහර විට max වැනි අමතර යතුරු සමඟ. ක්ෂේත්‍ර→පණිවිඩ සිතියමක් නැත.

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

Rate limits

Per-key (සත්‍යාපනය නොකළ endpoints සඳහා per-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.

ඉක්මවූ සීමාවක් 429 Too Many Requests ආපසු දෙයි, Retry-After header එකක් සහ plain-text body එකක් සමඟ (JSON දෝෂ ආවරණය නොවේ).