සම්පූර්ණ REST endpoint යොමුව. tutorials සහ උදාහරණ සඳහා, API මාර්ගෝපදේශය බලන්න.
ව්යාපෘති member කෙනෙකුට web UI එකේ කළ හැකි සියල්ල මෙහි ලබා ගත හැකිය — SPA එක මෙම එකම API එක පරිභෝජනය කරයි. manager භූමිකාව අවශ්ය ක්රියා (manager) ලෙස සලකුණු කර ඇත; අනෙක් සියල්ලට අවශ්ය වන්නේ ව්යාපෘති සාමාජිකත්වය පමණි (හෝ, (viewer) ලෙස සලකුණු කළ reads සඳහා, ඕනෑම ප්රවේශ මට්ටමක්). පහත වගු සේවාදායකය mount කරන සෑම route කණ්ඩායමක්ම නම් කරයි; තනි පේළියකින් සාරාංශ කළ ඒවා සජීවී openapi.json හි සම්පූර්ණයෙන් විස්තර කර ඇත.
https://eastagiletracker.com/api/v1https://api.eastagiletracker.com/api/v1 සමාන API එකම සේවය කරයි. multipart පිළිගන්නා ගොනු-උඩුගත endpoints කිහිපයක් හැර, සියලුම requests සහ responses JSON වේ.
කණ්ඩායම් දෙකක් /api/v1 වෙනුවට /api යටතේ, එක් මට්ටමක් ඉහළින් පිහිටයි: සත්යාපන මතුපිට (/api/auth/*) සහ පොදු පෝරම (/api/contact, /api/feedback). ඒවායේ /api/v1/… ආකාරයන් 404 ආපසු දෙයි.
සත්යාපනය
Section titled “සත්යාපනය”සෑම සත්යාපිත request එකක්ම පහත එකකින් අක්තපත්රයක් යවයි:
X-TrackerToken: <key>Authorization: Bearer <key>
User keys ea_user_ වලින්, agent keys ea_agent_ වලින්, සහ MCP access tokens ea_mcp_ වලින් ආරම්භ වේ. API මාර්ගෝපදේශය → අක්තපත්ර වර්ග තුනක් බලන්න.
සත්යාපනය නොකළ endpoints: /openapi.json, /docs, /api/auth/* endpoints, සහ reference-data lookups (/story_types, /story_states, /effort_scales, /priority_scales). /meta සත්යාපිතය — ඕනෑම වලංගු යතුරක් ක්රියා කරයි, නමුත් එය ව්යාපෘති-පරිමාණ නොවේ (ව්යාපෘතියට බැඳුණු agent key එකක්ද එයට ළඟා වේ).
භූමිකාවන්
Section titled “භූමිකාවන්”ව්යාපෘති-පරිමාණ endpoints මට්ටම් හතරක් ගේට්ටු කරයි:
| මට්ටම | සමත් වන්නේ කවුද | සාමාන්ය ක්රියා |
|---|---|---|
| public viewer | ඕනෑම අයෙක්, දෘශ්යතාව පොදු වූ ව්යාපෘතියක | බෝඩ් එකේ reads: ස්ටෝරි, ඉටරේෂන්, search, ස්ටෝරි සහ epic ක්රියාකාරකම් (actor විස්තර සඟවා) |
| viewer | viewer, member, manager | reads (ස්ටෝරි list/get, search, metrics, export ආකෘති ලැයිස්තුව) |
| member | member, manager | සියලුම work-item writes (stories, tasks, comments, …), event stream එක |
| manager | manager පමණි | ව්යාපෘති සැකසුම්, සාමාජිකත්ව කළමනාකරණය, agent keys, delete, import, export බාගැනීම්, backups, audit log |
ඒජන්තයන් සාමාජිකයන්ට සමාන භූමිකාවන් දරයි — viewer, member, හෝ manager — යතුර mint කළ සාමාජිකයාගේ භූමිකාවෙන් සීමා වේ. සාමාජිකයෙකු නොවන අයෙකුට පෞද්ගලික ව්යාපෘති මාර්ග මත 404 unfound_resource (403 නොව) ලැබේ, ඒ නිසා ව්යාපෘති IDs ගණනය කළ නොහැකිය.
ස්ව-විස්තර endpoints
Section titled “ස්ව-විස්තර endpoints”| Method | Path | විස්තරය |
|---|---|---|
| GET | /openapi.json | සජීවී OpenAPI 3 spec එක, request bodies ඇතුළුව. සත්යාපනය නොකළ. |
| GET | /docs | Swagger UI. සත්යාපනය නොකළ. |
| GET | /meta | Caller අනන්යතාව (auth.kind/key_id/agent_id/project_id) + story-type transition graph එක. සත්යාපිතය (ඕනෑම වලංගු යතුරක්; ව්යාපෘති-පරිමාණ නොව). මෙය මුලින්ම ඇමතන්න. |
| GET | /api/health · /api/config | ජීවමානතාව, සහ deployment එකේ පොදු වින්යාසය (තනි-ආයතන ප්රකාරය, සක්රිය විකල්ප විශේෂාංග, instance එකේ නම). සත්යාපනය නොකළ, /v1 වලින් පිටත. |
Auth (/api/auth/*, /v1 වලින් පිටත)
Section titled “Auth (/api/auth/*, /v1 වලින් පිටත)”සැසි endpoints, සඳහන් කර නොමැති නම් සත්යාපනය නොකළ. SPA එක මේවා ධාවනය කරයි; scripts සාමාන්යයෙන් ඒ වෙනුවට API key එකක් භාවිතා කරයි.
| Method | Path | විස්තරය |
|---|---|---|
| POST | /auth/register | නව ගිණුමක් ලියාපදිංචි කරන්න — reCAPTCHA-ආරක්ෂිත; ඉන්පසු ගිණුම SMS අභියෝගය පසු කරයි |
| POST | /auth/sms/challenge · /auth/sms/status · /auth/sms/bypass | ලියාපදිංචි SMS කේතය යවන්න / පරීක්ෂා කරන්න (bypass ක්රියාකරු විසින් ගේට්ටු කර ඇත) |
| GET | /auth/config | deployment එක ලබා දෙන පුරනය වීමේ ක්රම මොනවාද |
| POST | /auth/login | ඊමේල් + මුරපදය සමඟ පුරනය වන්න; සැසි JWT එකක්, හෝ TOTP අභියෝගයක් ආපසු දෙයි |
| POST | /auth/login/totp | authenticator කේතයකින් හෝ ප්රතිසාධන කේතයකින් පුරනය වීමක් අවසන් කරන්න |
| POST | /auth/passkey/login/start · /auth/passkey/login/finish | මුරපද රහිත WebAuthn පුරනය |
| GET | /auth/oauth/github/start · /auth/oauth/github/callback · /auth/oauth/google/start · /auth/oauth/google/callback · POST /auth/oauth/exchange | GitHub හෝ Google සමඟ OAuth පුරනය |
| POST | /auth/refresh · /auth/refresh/revoke | refresh token එක භ්රමණය කරන්න / අවලංගු කරන්න |
| POST | /auth/logout | පිටවන්න (refresh token එක අවලංගු කරයි) |
| POST | /auth/forgot-password · /auth/reset-password | නැවත සැකසීමේ ඊමේල් එකක් ඉල්ලන්න / reset token එක භාවිතා කරන්න |
| POST | /auth/accept-invite/lookup · /auth/accept-invite | invitation token එකක් → ඊමේල් වෙත විසඳන්න / ව්යාපෘති ආරාධනාව accept කරන්න (සත්යාපනයෙන් පසු) |
ගිණුම / අනන්යතාව
Section titled “ගිණුම / අනන්යතාව”මේවා caller මත ක්රියා කරන අතර වලංගු යතුරක් පමණක් අවශ්ය වේ (ව්යාපෘති භූමිකාවක් නැත).
| Method | Path | විස්තරය |
|---|---|---|
| GET | /me | වත්මන් පරිශීලක profile |
| PUT | /me | Profile යාවත්කාලීන කරන්න |
| DELETE | /me | ගිණුම මකන්න — ඔබ ආයතනයක හෝ වෙනත් සාමාජිකයන් සිටින ව්යාපෘතියක එකම owner වන තාක් ප්රතික්ෂේප කෙරේ |
| GET | /me/deletion-impact | ගිණුම මකා දැමීමෙන් ඉවත් වන්නේ කුමක්ද සහ එය අවහිර කරන්නේ කුමක්ද |
| 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/totp · POST /me/totp/setup · /me/totp/verify · /me/totp/disable | දෙ-සාධක (TOTP) ලියාපදිංචිය; verify ප්රතිසාධන කේත එක් වරක් ආපසු දෙයි |
| GET | /me/passkeys · POST /me/passkeys/register/start · /me/passkeys/register/finish · DELETE /me/passkeys/{credential_id} | Passkey ලියාපදිංචිය සහ ඉවත් කිරීම |
| GET | /me/oauth_grants · DELETE /me/oauth_grants/{grant_id} | Connected apps — ඔබ අවසර දී ඇති MCP clients සහ OAuth යෙදුම් |
| GET | /me/activity | සියලුම ව්යාපෘති හරහා ඔබේ ක්රියාකාරකම් |
| GET | /me/stories | token එකට ළඟා විය හැකි සෑම ව්යාපෘතියක් පුරාම ඔබ අයිති, ඉල්ලූ, හෝ follow කරන ස්ටෝරි — role=owned|requested|following, state=, cursor= / limit= (උපරිමය 200) |
| GET | /me/mentions · POST /me/mentions/{mention_id}/ack | @-සඳහන් එන ලිපි පෙට්ටිය (පෙරීමට unacked=true) සහ පිළිගැනීම — පහත දැනුම්දීම් සංග්රහයටද ඒකාබද්ධ කර ඇත |
| GET | /me/data-export | ඔබේ දත්ත වල GDPR ස්ව-export |
| GET | /me/consent · POST /me/consent | Consent කියවන්න / පටිගත කරන්න ({ consent_type, granted }) |
| GET | /legal/pending · POST /legal/accept | පොරොත්තු clickwrap docs / පිළිගැනීම පටිගත කරන්න |
| GET / PUT | /agent/me | agent key එකක තමන්ගේම අනන්යතාව සහ profile, ඒජන්තයාට කියවිය හැකි සහ සංස්කරණය කළ හැකි (/me හි agent-පාර්ශ්ව සමානය) |
| POST | /api/contact · /api/feedback · /api/feedback/with-screenshot | Contact + යෙදුම් ඇතුළත feedback. /v1 වලින් පිටත; IP අනුව rate-limited |
Reference data (සත්යාපනය නොකළ)
Section titled “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 |
| GET | /priority_scales · /priority_scales/{scale_id}/values | ප්රමුඛතා පරිමාණ සහ ඒවායේ අගයන් (ස්ටෝරියක priority_id මෙහි විසඳේ) |
සත්කාරක සේවාවේ පමණි — ස්වයං-සත්කාරක ස්ථාපනයක් තනි-ආයතන ප්රකාරයේ ධාවනය වන අතර මේවා mount නොකරයි (ආයතන ලැයිස්තුව හැර). භූමිකාවන් ආයතන භූමිකාවන් වේ: owner, admin, member.
| Method | Path | විස්තරය |
|---|---|---|
| GET / POST | /organizations | ඔබේ ආයතන ලැයිස්තුගත කරන්න / එකක් සාදන්න |
| GET / PUT / DELETE | /organizations/{oid} | කියවන්න, නැවත නම් කරන්න (නම + slug; owner හෝ admin), මකන්න |
| GET / POST | /organizations/{oid}/memberships · PUT / DELETE …/memberships/{member_id} | සාමාජිකයන් සහ ආරාධනා; ආරාධනා භූමිකා සීමාවක් දරයි (කිසිවිටෙක ඇමතුම්කරුගේ භූමිකාවට ඉහළින් නොවේ; owner කිසිවිටෙක ආරාධනා නොකෙරේ) |
| POST | /organizations/{oid}/memberships/bulk-role · …/memberships/bulk-remove | එකවර සාමාජිකයින් 200 දක්වා භූමිකාව වෙනස් කරන්න හෝ ඉවත් කරන්න. සියල්ල හෝ කිසිවක් නැත: අවසාන owner ඉවත් කරන හෝ ව්යාපෘතියක් හිමිකරුවෙකු නොමැතිව තබන කණ්ඩායමක් සම්පූර්ණයෙන් ප්රතික්ෂේප වේ; reassign_confirmed සමඟ ඔබ එම ව්යාපෘතිවල හිමිකරු වේ |
| DELETE | /organizations/{oid}/invitations/{invitation_id} | පොරොත්තු ආරාධනාවක් අවලංගු කරන්න |
| POST | /organizations/{oid}/transfer-ownership | owner භූමිකාව වෙනත් සාමාජිකයෙකුට භාර දෙන්න |
| PUT | /organizations/{oid}/memberships/{member_id}/anonymization | සාමාජිකයෙකුගේ නම / ඊමේල් / avatar ආයතනය පුරා වසන් කරන්න |
| GET | /organization-invitations/{token} · POST …/{token}/accept | ඊමේල් කළ ආයතන ආරාධනාවක් විසඳන්න / accept කරන්න |
| POST | /organizations/{oid}/export · GET / POST …/export/jobs · GET …/export/jobs/{job_id} · …/export/jobs/{job_id}/download | Owner-පමණක් ආයතන export: SQL dump එකක් සහ සෑම attachment එකක්ම සහිත zip එකක්, job එකක් ලෙස ධාවනය වේ |
ව්යාපෘති
Section titled “ව්යාපෘති”| Method | Path | විස්තරය |
|---|---|---|
| GET | /projects | ඔබේ ව්යාපෘති ලැයිස්තුගත කරන්න (limit ≤ 200) |
| POST | /projects | ව්යාපෘතියක් සාදන්න |
| GET | /projects/{id} | ව්යාපෘති විස්තර ලබා ගන්න (viewer) |
| PUT | /projects/{id} | ව්යාපෘති සැකසුම් යාවත්කාලීන කරන්න (manager) |
| DELETE | /projects/{id} | ව්යාපෘතියක් මකන්න (manager) |
| POST | /projects/{id}/pin | ඔබේ ව්යාපෘති ලැයිස්තුවේ ව්යාපෘතිය pin / unpin කරන්න |
| POST | /projects/{id}/transfer-organization | ව්යාපෘතිය වෙනත් ආයතනයකට ගෙන යන්න (manager) |
| POST | /projects/{id}/slack/test | ව්යාපෘතියේ Slack feed එකට පරීක්ෂණ පණිවිඩයක් යවන්න (manager) |
| GET / POST | /projects/{id}/showcase_claim_eligibility · /projects/{id}/showcase_claim · /projects/{id}/showcase_seed | පොදු showcase ව්යාපෘති: ඔබට එකක් හිමිකර ගත හැකිද යන්න පරීක්ෂා කරන්න, එය හිමිකර ගන්න, එය බීජ කරන්න |
| GET | /projects/{id}/audit-log | Audit log කියවීම — ව්යාපෘති ඉතිහාසය සහ surface= හරහා ස්ටෝරිය අනුව / epic අනුව ක්රියාකාරකම්; ප්රවේශය surface අනුව වෙනස් වේ, පහත බලන්න |
| GET | /projects/{id}/events | Cursor-paginated event stream (member) — Events බලන්න |
Audit log query පරාමිතීන්: event_type= (එක් වර්ගයක් හෝ කොමාවෙන් වෙන් කළ ලැයිස්තුවක්), limit= (≤ 1000), before= (keyset cursor, ISO-8601 created_at), surface= (project_history, story_activities, epic_activities), target_id= (ස්ටෝරියේ/epic එකේ id — surface=story_activities හෝ epic_activities විට අවශ්යයි). ප්රවේශය: පෙරහන් නොකළ ලොගය සහ surface=project_history (manager) වේ; story_activities / epic_activities ව්යාපෘතියේ ඕනෑම සාමාජිකයෙකුට කියවිය හැකි අතර, පොදු ව්යාපෘතිවල නිර්නාමිකවද — ක්රියාකරුගේ PII සඟවා ඇත.
සාමාජිකයන්, ඒජන්තයන්, සහ agent keys
Section titled “සාමාජිකයන්, ඒජන්තයන්, සහ agent keys”| Method | Path | විස්තරය |
|---|---|---|
| GET | /projects/{id}/memberships | සාමාජිකයන් ලැයිස්තුගත කරන්න (viewer) |
| POST | /projects/{id}/memberships | ඊමේල් මගින් සාමාජිකයෙකුට ආරාධනා කරන්න (manager) |
| PUT | /projects/{id}/memberships/{mid} | භූමිකාව යාවත්කාලීන කරන්න (manager) |
| DELETE | /projects/{id}/memberships/{mid} | සාමාජිකයෙකු ඉවත් කරන්න (manager) |
| GET | /projects/{id}/addable-members · POST /projects/{id}/members/add-existing | තවමත් ව්යාපෘතියේ නැති ආයතන සාමාජිකයන් / ඊමේල් ආරාධනාවකින් තොරව එකක් එක් කරන්න (manager) |
| POST | /projects/{id}/members/join | ආයතන owner හෝ admin කෙනෙකු තමන්ගේ ආයතනයේ ව්යාපෘතියකට manager කෙනෙකු ලෙස එක් වේ, හෝ තමන්වම එකෙකු ලෙස උසස් කරයි (ව්යාපෘති ලැයිස්තුවේ Make me owner ක්රියාව) |
| PUT | /projects/{id}/members/{mid}/anonymization | මෙම ව්යාපෘතියේ සාමාජිකයෙකුගේ නම / ඊමේල් / avatar වසන් කරන්න (manager) |
| GET / POST | /projects/{id}/agent_keys | Agent keys ලැයිස්තුගත / mint කරන්න — managers, හෝ ව්යාපෘතියේ creator-roles policy එක ඇතුළත් කරන භූමිකාවන් |
| DELETE | /projects/{id}/agent_keys/{kid} | Agent key එකක් අවලංගු කරන්න |
| GET | /projects/{id}/agent_keys/onboarding | onboarding bundle එක: පොදු agent clients සඳහා prompts සහ config ගොනු |
| GET | /projects/{id}/agents · GET / PUT /projects/{id}/agents/{aid} | ව්යාපෘතියේ ඒජන්තයන් සහ ඔවුන්ගේ profiles (නම, මුලකුරු, විස්තරය, වර්ණය) |
| POST | /projects/{id}/agents/{aid}/rotate-key · /projects/{id}/agents/{aid}/avatar | ඒජන්තයෙකුගේ යතුර භ්රමණය කරන්න (අනන්යතාව සහ ඉතිහාසය තබා ගනී) / එහි avatar එක උඩුගත කරන්න |
ස්ටෝරි
Section titled “ස්ටෝරි”සියලුම 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/{sid}/reject · /projects/{id}/stories/{sid}/restart | delivered ස්ටෝරියක් reject කරන්න / reject කළ එකක් නැවත started වෙත පත් කරන්න (/transitions සඳහා rejected අවසාන තත්ත්වයකි) |
| POST | /projects/{id}/stories/{sid}/archive · /projects/{id}/stories/{sid}/unarchive | එක් ස්ටෝරියක් archive / unarchive කරන්න |
| POST | /projects/{id}/stories/bulk_transition | ස්ටෝරි බොහෝමයක් (1–100) එකවර මාරු කරන්න |
| POST | /projects/{id}/stories/bulk-archive · bulk-delete · bulk-duplicate · bulk-move | ස්ටෝරි බොහෝමයක් archive, delete, duplicate, හෝ (පැනලයකට / ස්ථානයකට) move කරන්න |
| POST | /projects/{id}/stories/{sid}/duplicate | එක් ස්ටෝරියක් අනුපිටපත් කරන්න |
| GET / POST / DELETE | /projects/{id}/stories/{sid}/epics · …/epics/{eid} | ස්ටෝරියේ epic සාමාජිකත්වය |
| GET | /short-links/{code} · /story-references | /s/<code> කෙටි සබැඳියක් එහි ස්ටෝරියට විසඳන්න / ස්ටෝරි references 100ක් දක්වා (#id, URLs) ඇමතුම්කරුට කියවිය හැකි ස්ටෝරි වලට විසඳන්න |
ස්ටෝරි-ලැයිස්තු query parameters: archived= (exclude පෙරනිමිය / include / only — ත්රි-අවස්ථා archived පෙරහන; අත්හළ include_archived=true වෙනුවට යෙදේ, එය දැන් archived=include සඳහා alias එකකි), include_done=true (පසුගිය iterations මත ශීත කළ Done පැනලයේ ස්ටෝරි ඇතුළත් කරයි; පෙරනිමියෙන් බැහැර වේ). Pagination (cursor= / limit= / offset=) සහ sparse fieldsets (fields=) Pagination සහ ක්ෂේත්ර ප්රක්ෂේපනය අනුගමනය කරයි.
Create (POST …/stories): { "name" (required), "story_type": "feature|bug|chore|release", "description"?, "estimate"?, "current_state"?, "icebox"?, "labels"? }. estimate යනු පරිමාණ අගයේ label එක string එකක් ලෙසයි ("3", "13"); JSON අංකයක් ප්රතික්ෂේප කෙරේ. labels ["auth"] හෝ [{ "name": "auth" }] පිළිගනියි; නොදන්නා labels සාදනු ලැබේ. පෙරනිමි: story_type=feature, current_state=unstarted.
Update (PUT …/stories/{sid}): එම ක්ෂේත්ර, සියල්ල විකල්ප, ඊට අමතරව "position" (float), "force_state_change" (bool), සහ "expected_updated_at" (RFC 3339 — ඔබ කියවූ පසු ස්ටෝරිය වෙනස් වී ඇත්නම් විස්තර සුරැකීමක් 409 stale_write සමඟ ප්රතික්ෂේප කෙරේ). Story writes ස්ටෝරියේ ETag එකට එරෙහිව If-Match ද ගරු කරයි; නොගැළපීමක් 412 precondition_failed වේ.
Transition (POST …/transitions): { "to": "<state>" }. ක්ෂේත්රය to වේ. { story_id, state } ආපසු දෙයි. නීති විරෝධී මාරුව → 422 invalid_transition, details: { from, to, allowed } සමඟ.
Bulk transition (POST …/bulk_transition): { "story_ids": [int,…] (1–100), "to": "<state>" }. එක් එක් ස්ටෝරිය ස්වාධීනව විනිශ්චය කරයි; { results: [ { id, status: "ok" } | { id, status: "failed", error } ] } ආපසු දෙයි.
ස්ටෝරි උප-resources
Section titled “ස්ටෝරි උප-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 මගින් fields= (allowlist: comment_id, story_comment_id, story_id, comment_text, comment_emoji, member, created) සහ cursor= / limit= (≤ 200) / order=asc|desc ද පිළිගනියි |
| GET / POST | /projects/{id}/stories/{sid}/blockers · PUT/DELETE …/blockers/{bid} | { blocker_desc, resolved? } |
| GET / POST | /projects/{id}/stories/{sid}/links · PUT/DELETE …/links/{lid} | { url, link_type?, title? } — link_type ∈ relates_to, duplicates, blocks, is_blocked_by, pull_request, branch, other; GitHub /pull/ සහ /tree/ URLs ස්වයංක්රීයව වර්ගීකරණය කෙරේ |
| GET / POST | /projects/{id}/stories/{sid}/reviews · PUT/DELETE …/reviews/{rid} | Create: { reviewer_id? / reviewer_agent_id?, comment? } — ඔබවම පැවරීමට දෙකම අත්හරින්න. Update: { 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 — වීඩියෝ ≤ 200 MB, PDF / Word / Excel ≤ 25 MB, රූප / CSV / පෙළ ≤ 10 MB; list (viewer) වේ |
| GET / POST | /projects/{id}/stories/{sid}/link-attachments · DELETE …/link-attachments/{laid} | Link attachments — code link එකක් ලෙස නොව ගොනු attachments සමඟ තබා ඇති බාහිර URL එකක් |
| GET | /attachments/{token} · /api/avatars/{token} | attachment එකක හෝ avatar එකක token-ලිපිනගත reads — API එක ලබා දෙන URLs; X-TrackerToken අවශ්ය නැත |
ස්ටෝරි වලට සමාන හැඩය, තත්ත්ව යන්ත්රය හැර. writes සඳහා member, reads සඳහා (viewer).
| Method | Path | විස්තරය |
|---|---|---|
| GET / POST | /projects/{id}/epics · GET / PUT / DELETE …/epics/{eid} | Epics නමක්, Markdown විස්තරයක්, සහ ඒවායේ ස්ටෝරි එකට බැඳෙන පසුබිම් label එකක් දරයි |
| GET / POST / PUT / DELETE | …/epics/{eid}/comments · …/comments/{cid} | Epic comments |
| GET / POST / DELETE | …/epics/{eid}/owners · …/followers (+ /agents/{aid} variants) | Owners සහ followers, සාමාජිකයන් හෝ ඒජන්තයන් — epic එකක owners එහි ස්ටෝරි වෙත ප්රචාරණය වේ |
| GET / POST / DELETE | …/epics/{eid}/attachments (+ /json) · …/link-attachments | Attachments, ස්ටෝරි වලට සමාන සීමා |
| GET | /projects/{id}/analytics/epics · …/analytics/epics/{eid} | එක් එක් epic අනුව ප්රගතිය: burnup, throughput, සෞඛ්යය, පුරෝකථනය (viewer) |
Labels
Section titled “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
Section titled “Iterations”Reads ඕනෑම ව්යාපෘති භූමිකාවකට විවෘත වන අතර, පොදු ව්යාපෘතියක නිර්නාමික වේ.
| Method | Path | විස්තරය |
|---|---|---|
| GET | /projects/{id}/iterations | ඉටරේෂන් ලැයිස්තුගත කරන්න (පිටුවකට ≤ 500; කපා හැරි විට ETag එකක් සහ X-Tracker-Pagination-* අඛණ්ඩ headers දරයි) |
| GET | /projects/{id}/iterations/{itid} | එක් ඉටරේෂන් එකක් |
| GET | /projects/{id}/iterations/first-preview | පළමු ඉටරේෂන් එකට ලැබෙන දින, බීජ කිරීමේ තහවුරු කිරීමේ පෙන්වයි |
| POST | /projects/{id}/iterations | manual ඉටරේෂන් එකක් සාදන්න (member) |
| DELETE | /projects/{id}/iterations/{itid} | ඉටරේෂන් එකක් මකන්න (manager) |
| PUT | /projects/{id}/iterations/{itid}/velocity | ව්යාපෘති strategy එක වෙනස් නොකර එක් ඉටරේෂන් එකක වෙලොසිටිය ඉක්මවා යන්න (manager) |
| GET | /projects/{id}/iterations/{itid}/done-stories | වසා දැමූ ඉටරේෂන් එකක accepted ස්ටෝරි, paginated |
Search, metrics, preferences
Section titled “Search, metrics, preferences”| Method | Path | විස්තරය |
|---|---|---|
| GET | /projects/{id}/search?q=… | ප්රබල සෙවුම — සම්පූර්ණ-පෙළ + facet / date-range / people qualifiers (GitHub-විලාසයේ DSL); { results, total, limit, offset } ආපසු දෙයි. query යනු q සඳහා alias එකකි; limit= (පෙරනිමිය 50, උපරිමය 1000) / offset= පිටු කරයි; sort= relevance (පෙරනිමිය), created, created_asc, state, හෝ updated අනුව අනුපිළිවෙළ කරයි. (viewer) — මාර්ගෝපදේශය බලන්න |
| GET | /projects/{id}/metrics/{velocity,burndown,story-types,contributors} | Metrics පිටුවේ series (viewer); epic metrics ඉහත /analytics/epics යටතේ ඇත |
| GET | /projects/{id}/backlog/grouping | Backlog හි ප්රක්ෂේපිත ඉටරේෂන් කණ්ඩායම් (viewer) |
| GET / PUT | /projects/{id}/preferences | මෙම ව්යාපෘතිය සඳහා ඔබේ board preferences — ඕනෑම ව්යාපෘති භූමිකාවක්, ඔබේම පේළිය පමණි |
Events
Section titled “Events”| Method | Path | විස්තරය |
|---|---|---|
| GET | /projects/{id}/events | Cursor-paginated event stream (member) — viewers ට 403 ලැබේ |
Query parameters: since=<event_id>, types=story.created,story.transitioned,comment.added,…, limit= (≤ 500), cursor=. ප්රතිචාරයට next_cursor ඇතුළත් වේ. නැවත ආරම්භ කිරීමට ඔබ දුටු අවසන් event_id එක since ලෙස ලබා දෙන්න.
දැනුම්දීම්
Section titled “දැනුම්දීම්”යෙදුම තුළ ඒකාබද්ධ දැනුම්දීම් සංග්රහය: ප්රථම-පන්තියේ දැනුම්දීම් පේළි (සමාලෝචන ඉල්ලීම්, story ක්රියාකාරකම්, ආරාධනා, …) @-සඳහන් එන ලිපි සමඟ ඒකාබද්ධ කර අලුත්ම පළමුව අනුපිළිවෙළින් එක් ප්රවාහයක් ලෙස. සංග්රහ id වලට මූලාශ්ර උපසර්ගයක් ඇත (nt-… / sc-… / ec-…). සාමාජික සැසි සහ ea_user_* යතුරු ඔවුන්ගේ සාමාජික-පාර්ශ්ව පේළි කියවයි; ea_agent_* යතුරු ඔවුන්ගේ agent-පාර්ශ්ව පේළි.
| Method | Path | විස්තරය |
|---|---|---|
| GET | /me/notifications | ඔබේ දැනුම්දීම් සංග්රහය. පෙරහන්: unread=true, since_id=, kind= (mentions / reviews / stories / invitations); පිටු කිරීම cursor= / limit= මගින් |
| GET | /me/notifications/unread-count | නොකියවූ එකතු — { unread_count, by_category: { mentions, reviews, stories, invitations } } |
| POST | /me/notifications/read-all | සියල්ල කියවූ ලෙස සලකුණු කරන්න; නැවුම් ගණන් ලබා දෙයි |
| POST | /me/notifications/{id}/ack | එක් අයිතමයක් කියවූ ලෙස සලකුණු කරන්න (idempotent) |
| POST | /me/notifications/{id}/accept | සංග්රහයෙන්ම ව්යාපෘති / සංවිධාන ආරාධනාවක් පිළිගන්න (සාමාජික ටෝකන පමණි) |
| POST | /me/notifications/{id}/decline | ව්යාපෘති / සංවිධාන ආරාධනාවක් ප්රතික්ෂේප කරන්න (සාමාජික ටෝකන පමණි) |
| GET | /me/notifications/resolve-invite?token=… | ඊමේල් මගින් ලැබුණු ආරාධනා ටෝකනය ඔබේ දැනුම්දීම් id වෙත ගැළපීම — { "id": "nt-…" } හෝ { "id": null } |
| GET | /me/notifications/stream | සජීවී push — Server-Sent Events (text/event-stream); පහත බලන්න |
stream endpoint එක JSON endpoint එකක් නොවන නිසා එය OpenAPI පිරිවිතරයේ නැත: එය සම්බන්ධතාව විවෘතව තබාගෙන අලුත් දෙයක් පැමිණෙන සෑම විටම payload රහිත රාමුවක් ({"type":"notification","kind":…}) නිකුත් කරයි, සංග්රහය නැවත ලබාගන්නා ලෙස client ට දන්වයි. සම්බන්ධතා සේවාදායක පාර්ශ්වයෙන් මිනිත්තු 45 කට පසු අවසන් වේ — නැවත සම්බන්ධ වී නැවත සත්යාපනය කරන්න. සාමාජික සැසි සහ ea_user_* යතුරු පමණි; ea_agent_* යතුරුවලට 403 ලැබේ.
Import (manager)
Section titled “Import (manager)”| Method | Path | විස්තරය |
|---|---|---|
| POST | /projects/{id}/import | ගොනු මූලාශ්ර: source= ∈ pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json, eat. Multipart file=. සමමුහුර්ත — ප්රතිඵල ගණන් සමඟ පිළිතුරු දෙයි. |
| POST | /projects/{id}/import/json | JSON body; source=github හට ගොනුවක් අවශ්ය නැත — owner, repo, විකල්ප token, සහ opt-in flags include_pull_requests / include_milestones / include_releases / include_dependencies; ගොනු මූලාශ්ර file_base64 යවයි. අසමමුහුර්ත: 202 { import_id, status } ආපසු දෙයි. සේවාදායකය GitHub හි GraphQL API හරහා ලබා ගනී, එය නිර්නාමික ඇමතුම්කරුවන් ප්රතික්ෂේප කරයි, ඒ නිසා GitHub වෙත සැමවිටම token එකක් ළඟා වේ — ඔබේම එක, හෝ deployment එකේ බෙදාගත් එක. මාර්ගෝපදේශය බලන්න. |
| GET | /projects/{id}/imports/{import_id} | job එකක් poll කරන්න: status pending → fetching → writing → done | failed ලෙස ධාවනය වේ, fetching අතරතුර progress_current / progress_total සහ done මත ප්රතිඵල ගණන් සමඟ |
ව්යාපෘතියකට වරකට ධාවනය වන්නේ එක් import එකක් පමණි; එකක් ක්රියාත්මක වෙමින් තිබියදී දෙවන POST එකක් 409 import_already_running වේ. dry_run: true (JSON body හෝ dry_run=true multipart) ඕනෑම මූලාශ්රයක් පෙරදසුන් කරයි: parse, resolve, de-dupe කර, එම { imported, skipped, errors, unmatched } counts ම ආපසු දී, පසුව rollback කරයි — කිසිවක් නොලියයි. සීමා: 10 MiB body, සහ ගොනු-පාදක මූලාශ්ර සඳහා per import ස්ටෝරි 5,000 (එකක් ඉක්මවීම → 400, කිසිවක් නොලියයි). GitHub මූලාශ්රයට සීමාවක් නැත — එය තනි ගනුදෙනුවක් වෙනුවට කොටස් වශයෙන් commit කරයි. නැවත-import එක source id අනුව idempotent — දැනටමත් import කළ පේළි අනුපිටපත් නොකර මඟ හැරේ.
Export
Section titled “Export”| Method | Path | විස්තරය |
|---|---|---|
| GET | /projects/{id}/export/formats | ලියාපදිංචි ආකෘති: { id, name, content_type, drops, includes_archived }. ඕනෑම ව්යාපෘති භූමිකාවක්. |
| GET | /projects/{id}/export/{format} | එකක් බාගන්න (manager). Interchange: eat (සම්පූර්ණ නිරවද්යතාව), jira, pivotal, shortcut, trello, asana, gitlab, linear, plane, plane_json; documents: pdf, docx. |
| GET | /projects/{id}/export/attachments | සෑම attachment එකක්ම browse කළ හැකි එක් zip එකක් ලෙස (ගොනු මුල් නම් තබා ගනී; JSON + CSV manifest) (manager). |
Document exports (pdf, docx) අමතර query parameters පිළිගනියි: page_size= (letter පෙරනිමිය / a4 / legal / folio), from= / to= (ස්ටෝරි කවුළු සීමා — RFC 3339 හෝ සරල YYYY-MM-DD; ස්ටෝරියක created හෝ completed_at ඒ තුළට වැටෙන විට එය පරාසයේ ඇත), include_icebox= / include_backlog= (දෙකම පෙරනිමියෙන් false, එබැවින් බෙදාගත හැකි export එකක පෙන්වන්නේ කාලසටහන්ගත / ක්රියාත්මක වෙමින් පවතින වැඩ පමණි). Interchange CSV formats ඒවා නොසලකා හරියි.
Backups සහ restores (manager)
Section titled “Backups සහ restores (manager)”| Method | Path | විස්තරය |
|---|---|---|
| GET / POST | /projects/{id}/backups · GET …/backups/{snapshot_id} · …/backups/health | snapshots ලැයිස්තුගත කරන්න, දැන් එකක් ගන්න, එකක් කියවන්න, සහ රඳවා තබා ගැනීමේ සෞඛ්ය සාරාංශය |
| GET / POST | /projects/{id}/restores · POST …/restores/partial · GET …/restores/{restore_id} | මුළු snapshot එකක්ම, හෝ එකකින් තෝරාගත් වගු, restore කර restore එක poll කරන්න |
POSTs sensitive rate-limit ස්තරයේ පිහිටයි (පහත).
MCP සහ OAuth provider
Section titled “MCP සහ OAuth provider”East Agile Tracker යනු MCP clients සඳහා OAuth 2.1 සපයන්නෙකි. client එකක් එය /.well-known/oauth-authorization-server සහ /.well-known/oauth-protected-resource/mcp හි සොයා ගනී, ඔබව /oauth/authorize (කැමැත්ත පිටුව) වෙත යවයි, /oauth/token හි කේතය හුවමාරු කරයි, ඉන්පසු ලැබෙන ea_mcp_* token එක සමඟ /mcp හි MCP කථා කරයි. Grants /me/oauth_grants හි ලැයිස්තුගත කර අවලංගු කෙරේ. සපයන්නාගේ endpoints වලට තමන්ගේම rate-limit ස්තරයක් ඇත.
WebSocket
Section titled “WebSocket”wss://eastagiletracker.com/ws/control?token=<session JWT>අන්තර්ක්රියාකාරී UI දුරස්ථ-පාලනය සඳහා ({ "action": "get_state", "id": "req-1" }). token එක browser සැසි JWT එකකි — API key එකක් upgrade එකට පෙර 401 සමඟ ප්රතික්ෂේප කෙරේ. දත්ත channel එකක් නොවේ — සියලුම reads/writes REST හරහා යයි. තනි-instance පමණි; replicas හරහා fan out නොකරයි.
Idempotency
Section titled “Idempotency”Write endpoints (POST, PUT, DELETE) Idempotency-Key header එකක් පිළිගනියි. එම යතුර + එම body එක cached ප්රතිචාරය නැවත ධාවනය කරයි (පැය 24 කවුළුවක්); එම යතුර + වෙනස් body එකක් 409 idempotency_conflict ආපසු දෙයි. යතුර එය යැවූ අක්තපත්රයට පරිමාණය කර ඇත. GET/HEAD/OPTIONS, /openapi.json සහ /docs, /api/auth/*, හෝ /attachments මාර්ග මත multipart උඩුගත කිරීම් වලට යොදන්නේ නැත. domain පිළිතුරකට පෙර නැවතුණු ප්රතිචාර කිසිවිටෙක cache නොකෙරේ — 401, 403, 404, 429, සහ සෑම 5xx එකක්ම — ඒ නිසා ඒවායින් ඕනෑම එකකට පසු retry එකක් handler වෙත ළඟා වේ; 400, 409, 412, සහ 422 domain එකේ පිළිතුර වන අතර සාර්ථකත්වයක් මෙන් නැවත ධාවනය වේ.
Pagination
Section titled “Pagination”List endpoints cursor=<opaque> සහ limit=<n> පිළිගනියි. සකසා ඇති විට, ප්රතිචාරය { "items": [...], "next_cursor": "<str|null>" } වේ; page කිරීමට next_cursor ආපසු ලබා දෙන්න. limit සීමාව endpoint අනුව වේ: ස්ටෝරි, comments, සහ ව්යාපෘති මත 200; events මත 500; search සහ audit log මත 1000.
එහි ප්රතිචාරය කපා හැරීමට සිදු වූ සරල ලැයිස්තුවක් (cursor/limit නැති) එය headers වල පවසයි — X-Tracker-Pagination-Truncated, X-Tracker-Pagination-Limit, X-Tracker-Pagination-Offset, සහ X-Tracker-Pagination-Next-Offset; ඊළඟ පිටුව සඳහා අවසාන එක offset= ලෙස ආපසු ලබා දෙන්න. සම්පූර්ණ-ගණන් header එකක් නැත.
ක්ෂේත්ර ප්රක්ෂේපනය
Section titled “ක්ෂේත්ර ප්රක්ෂේපනය”List endpoints නිශ්චිත ක්ෂේත්ර පමණක් ආපසු දීමට fields= (කොමාවෙන් වෙන් කළ) පිළිගනියි. story_id සැමවිටම ඇතුළත් වේ; නොදන්නා ක්ෂේත්ර නමක් 400 validation_failed ආපසු දෙයි, details.fields හි වැරදිකරු නම් සමඟ.
GET /projects/123/stories?fields=story_id,name,current_state,ownersදෝෂ ආකෘතිය
Section titled “දෝෂ ආකෘතිය”සෑම 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 එකක් සමඟ නැවත භාවිතා කර ඇත |
| 409 | stale_write · import_already_running | ඔබේ expected_updated_at සිට ස්ටෝරිය වෙනස් වී ඇත · import එකක් දැනටමත් ක්රියාත්මක වෙමින් පවතී |
| 412 | precondition_failed | If-Match සම්පතේ වත්මන් ETag එකට නොගැළපුණි; details expected සහ current දරයි |
| 413 | request_too_large | body එක route එකේ ප්රමාණ සීමාව ඉක්මවයි |
| 422 | invalid_transition | නීති විරෝධී තත්ත්ව මාරුව; details { from, to, allowed } දරයි |
| 429 | rate_limited | rate-limited route එකක මෙම IP එකෙන් ඉල්ලීම් වැඩිය; Retry-After header |
| 500 | internal_error | සේවාදායක දෝෂය — සාමාන්ය පණිවිඩය; retry කිරීම ආරක්ෂිතය |
| 503 | not_configured | මෙම route එකට අවශ්ය integration එක deployment එකේ නැත (SMS, object storage, …) |
details.fields යනු ක්ෂේත්ර නම් වල JSON array එකකි (උදා. ["to"]), සමහර විට max වැනි අමතර යතුරු සමඟ. ක්ෂේත්ර→පණිවිඩ සිතියමක් නැත.
{ "code": "validation_failed", "error": "unknown field(s): foo", "details": { "fields": ["foo"] } }Rate limits
Section titled “Rate limits”සේවාදායක IP අනුව, routes අතලොස්සක් මත; වෙනත් තැන්වල සත්යාපිත API ගමනාගමනය rate-limited නොවේ. පෙරනිමි (සෑම යුගලයක්ම තිරසාර අනුපාතය සහ burst, ක්රියාකරුට සුසර කළ හැකි):
- Auth —
/api/auth/*: 0.5 req/s, burst 20. - OAuth provider —
/oauth/*: 1 req/s, burst 60. - Public —
/api/contact: 0.2 req/s, burst 10. - Feedback —
/api/feedback: ගොඩගැසූ ස්තර තුනක් — තත්පර 15කට එක් ඉදිරිපත් කිරීමක්, පැයකට 10, දිනකට 36. - Avatars — සත්යාපනය නොකළ avatar redirect: 20 req/s, burst 200.
- Sensitive — backup සහ restore
POSTs: ~0.002 req/s, burst 5.
ඉක්මවූ සීමාවක් Retry-After header එකක් සහ සම්මත JSON දෝෂ envelope එක, code: "rate_limited" සමඟ 429 ආපසු දෙයි.