API विनिर्देश

संपूर्ण REST एंडपॉइंट संदर्भ। ट्यूटोरियल और उदाहरणों के लिए, API गाइड देखें।

जो कुछ भी एक प्रोजेक्ट सदस्य वेब UI में कर सकता है वह यहाँ उपलब्ध है — SPA इसी समान API का उपभोग करता है। जिन ऑपरेशन के लिए manager भूमिका की आवश्यकता होती है उन्हें (manager) से चिह्नित किया गया है; बाकी सब को केवल प्रोजेक्ट सदस्यता की आवश्यकता होती है (या, (viewer) से चिह्नित रीड के लिए, कोई भी एक्सेस स्तर)। नीचे की तालिकाएँ सर्वर द्वारा माउंट किए गए हर रूट समूह का नाम देती हैं; जिनका सारांश एक ही पंक्ति में दिया गया है, उनका पूरा वर्णन लाइव openapi.json में है।

आधार

https://eastagiletracker.com/api/v1

https://api.eastagiletracker.com/api/v1 समान API परोसता है। सभी अनुरोध और प्रतिक्रियाएँ JSON हैं, सिवाय कुछ फ़ाइल-अपलोड एंडपॉइंट के जो multipart स्वीकार करते हैं।

दो समूह एक स्तर ऊपर, /api/v1 के बजाय /api के अंतर्गत रहते हैं: प्रमाणीकरण सतह (/api/auth/*) और सार्वजनिक फ़ॉर्म (/api/contact, /api/feedback)। इनकी /api/v1/… वर्तनी 404 लौटाती है।

प्रमाणीकरण

हर प्रमाणित अनुरोध इनमें से किसी एक के माध्यम से एक क्रेडेंशियल भेजता है:

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

यूज़र कुंजियाँ ea_user_ से, एजेंट कुंजियाँ ea_agent_ से, और MCP एक्सेस टोकन ea_mcp_ से शुरू होते हैं। API गाइड → तीन तरह के क्रेडेंशियल देखें।

अप्रमाणित एंडपॉइंट: /openapi.json, /docs, /api/auth/* एंडपॉइंट, और संदर्भ-डेटा लुकअप (/story_types, /story_states, /effort_scales, /priority_scales)। /meta प्रमाणित है — कोई भी वैध कुंजी काम करती है, लेकिन यह प्रोजेक्ट-सीमित नहीं है (एक प्रोजेक्ट-बाउंड एजेंट कुंजी भी इस तक पहुँचती है)।

भूमिकाएँ

चार स्तर प्रोजेक्ट-सीमित एंडपॉइंट को नियंत्रित करते हैं:

स्तर	कौन पास करता है	विशिष्ट ऑपरेशन
public viewer	कोई भी, ऐसे प्रोजेक्ट पर जिसकी दृश्यता सार्वजनिक है	बोर्ड के रीड: स्टोरी, इटरेशन, खोज, स्टोरी और एपिक गतिविधि (कर्ता का विवरण छिपाकर)
viewer	viewer, member, manager	रीड (स्टोरी लिस्ट/गेट, खोज, मेट्रिक्स, एक्सपोर्ट प्रारूप सूची)
member	member, manager	सभी कार्य-आइटम राइट (स्टोरी, टास्क, टिप्पणियाँ, …), इवेंट स्ट्रीम
manager	केवल manager	प्रोजेक्ट सेटिंग्स, सदस्यता प्रबंधन, एजेंट कुंजियाँ, डिलीट, इम्पोर्ट, एक्सपोर्ट डाउनलोड, बैकअप, ऑडिट लॉग

एजेंट सदस्यों जैसी ही भूमिकाएँ रखते हैं — viewer, member, या manager — जिनकी सीमा कुंजी जारी करने वाले सदस्य की भूमिका होती है। एक गैर-सदस्य निजी प्रोजेक्ट पथ पर 404 unfound_resource प्राप्त करता है (न कि 403), इसलिए प्रोजेक्ट ID गणना योग्य नहीं हैं।

स्व-वर्णन करने वाले एंडपॉइंट

Method	Path	विवरण
GET	/openapi.json	लाइव OpenAPI 3 स्पेक, अनुरोध बॉडी सहित। अप्रमाणित।
GET	/docs	Swagger UI। अप्रमाणित।
GET	/meta	कॉलर पहचान (auth.kind/key_id/agent_id/project_id) + स्टोरी-प्रकार ट्रांज़िशन ग्राफ़। प्रमाणित (कोई भी वैध कुंजी; प्रोजेक्ट-सीमित नहीं)। इसे पहले कॉल करें।
GET	/api/health · /api/config	जीवंतता जाँच, और तैनाती का सार्वजनिक कॉन्फ़िगरेशन (एकल-संगठन मोड, कौन-सी वैकल्पिक सुविधाएँ चालू हैं, इंस्टेंस का नाम)। अप्रमाणित, /v1 के बाहर।

Auth (/api/auth/*, /v1 के बाहर)

सत्र एंडपॉइंट, अप्रमाणित जब तक अन्यथा न लिखा हो। SPA इन्हें चलाता है; स्क्रिप्ट सामान्यतः इनके बजाय API कुंजी का उपयोग करती हैं।

Method	Path	विवरण
POST	/auth/register	एक नया अकाउंट रजिस्टर करें — reCAPTCHA से सुरक्षित; फिर अकाउंट SMS चुनौती पार करता है
POST	/auth/sms/challenge · /auth/sms/status · /auth/sms/bypass	साइन-अप SMS कोड भेजें / जाँचें (bypass केवल ऑपरेटर के लिए खुला है)
GET	/auth/config	तैनाती कौन-से साइन-इन तरीके प्रदान करती है
POST	/auth/login	ईमेल + पासवर्ड से साइन इन करें; एक सत्र JWT, या एक TOTP चुनौती लौटाता है
POST	/auth/login/totp	ऑथेंटिकेटर कोड या रिकवरी कोड से साइन-इन पूरा करें
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	रिफ़्रेश टोकन रोटेट करें / उसे निरस्त करें
POST	/auth/logout	साइन आउट करें (रिफ़्रेश टोकन निरस्त करता है)
POST	/auth/forgot-password · /auth/reset-password	रीसेट ईमेल का अनुरोध करें / रीसेट टोकन का उपयोग करें
POST	/auth/accept-invite/lookup · /auth/accept-invite	एक आमंत्रण टोकन को हल करें → ईमेल / प्रोजेक्ट आमंत्रण स्वीकार करें (प्रमाणित होने के बाद)

अकाउंट / पहचान

ये कॉलर पर कार्य करते हैं और केवल एक वैध कुंजी की आवश्यकता होती है (कोई प्रोजेक्ट भूमिका नहीं)।

Method	Path	विवरण
GET	/me	वर्तमान उपयोगकर्ता प्रोफ़ाइल
PUT	/me	प्रोफ़ाइल अपडेट करें
DELETE	/me	अकाउंट हटाएँ — जब तक आप किसी संगठन के, या अन्य सदस्यों वाले किसी प्रोजेक्ट के एकमात्र ओनर हैं, तब तक अस्वीकृत
GET	/me/deletion-impact	अकाउंट हटाने से क्या हटेगा और क्या इसे रोकता है
PUT	/me/password	पासवर्ड बदलें
PUT	/me/settings	सेटिंग्स अपडेट करें (थीम, सूचना प्राथमिकताएँ)
POST	/me/avatar	अवतार अपलोड करें (multipart)
POST	/me/api-token/regenerate	अपना API टोकन रोटेट करें — मौजूदा सत्रों/कुंजियों को अमान्य करता है
GET	/me/api_keys · POST /me/api_keys · DELETE /me/api_keys/{id}	यूज़र (ea_user_) API कुंजियाँ प्रबंधित करें
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}	पासकी नामांकन और हटाना
GET	/me/oauth_grants · DELETE /me/oauth_grants/{grant_id}	कनेक्टेड ऐप — वे MCP क्लाइंट और OAuth ऐप जिन्हें आपने अधिकृत किया है
GET	/me/activity	सभी प्रोजेक्ट में आपकी गतिविधि
GET	/me/stories	टोकन की पहुँच वाले हर प्रोजेक्ट में वे स्टोरी जिनके आप ओनर हैं, जिनका आपने अनुरोध किया, या जिन्हें आप फ़ॉलो करते हैं — role=owned|requested|following, state=, cursor= / limit= (अधिकतम 200)
GET	/me/mentions · POST /me/mentions/{mention_id}/ack	@-उल्लेख इनबॉक्स (फ़िल्टर के लिए unacked=true) और पावती — नीचे की सूचना फ़ीड में भी शामिल
GET	/me/data-export	आपके डेटा का GDPR स्व-एक्सपोर्ट
GET	/me/consent · POST /me/consent	सहमति पढ़ें / रिकॉर्ड करें ({ consent_type, granted })
GET	/legal/pending · POST /legal/accept	लंबित क्लिकरैप दस्तावेज़ / स्वीकृति रिकॉर्ड करें
GET / PUT	/agent/me	एजेंट कुंजी की अपनी पहचान और प्रोफ़ाइल, जिसे एजेंट पढ़ और संपादित कर सकता है (/me का एजेंट-पक्षीय समकक्ष)
POST	/api/contact · /api/feedback · /api/feedback/with-screenshot	संपर्क + इन-ऐप प्रतिक्रिया। /v1 के बाहर; प्रति IP दर-सीमित

संदर्भ डेटा (अप्रमाणित)

स्टोरी बनाते/अनुमान लगाते समय उपयोग किए जाने वाले सीड लुकअप। स्थिर ID।

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	किसी स्केल में पॉइंट मान
GET	/priority_scales · /priority_scales/{scale_id}/values	प्राथमिकता स्केल और उनके मान (स्टोरी का priority_id यहीं हल होता है)

संगठन

केवल होस्टेड सेवा — एक सेल्फ़-होस्टेड इंस्टॉल एकल-संगठन मोड में चलता है और इन्हें माउंट नहीं करता (संगठन सूची को छोड़कर)। यहाँ भूमिकाएँ संगठन भूमिकाएँ हैं: owner, admin, member।

Method	Path	विवरण
GET / POST	/organizations	अपने संगठन सूचीबद्ध करें / एक बनाएँ
GET / PUT / DELETE	/organizations/{oid}	पढ़ें, नाम बदलें (नाम + स्लग; 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	पूरे संगठन में किसी सदस्य का नाम / ईमेल / अवतार छिपाएँ
GET	/organization-invitations/{token} · POST …/{token}/accept	ईमेल से भेजे गए संगठन आमंत्रण को हल करें / स्वीकार करें
POST	/organizations/{oid}/export · GET / POST …/export/jobs · GET …/export/jobs/{job_id} · …/export/jobs/{job_id}/download	केवल-ओनर संगठन एक्सपोर्ट: एक SQL डंप और हर अटैचमेंट वाला zip, एक जॉब के रूप में चलता है

प्रोजेक्ट

Method	Path	विवरण
GET	/projects	अपने प्रोजेक्ट सूचीबद्ध करें (limit ≤ 200)
POST	/projects	एक प्रोजेक्ट बनाएँ
GET	/projects/{id}	प्रोजेक्ट विवरण प्राप्त करें (viewer)
PUT	/projects/{id}	प्रोजेक्ट सेटिंग्स अपडेट करें (manager)
DELETE	/projects/{id}	एक प्रोजेक्ट हटाएँ (manager)
POST	/projects/{id}/pin	अपनी प्रोजेक्ट सूची पर प्रोजेक्ट को पिन / अनपिन करें
POST	/projects/{id}/transfer-organization	प्रोजेक्ट को किसी अन्य संगठन में ले जाएँ (manager)
POST	/projects/{id}/slack/test	प्रोजेक्ट की Slack फ़ीड पर एक परीक्षण संदेश भेजें (manager)
GET / POST	/projects/{id}/showcase_claim_eligibility · /projects/{id}/showcase_claim · /projects/{id}/showcase_seed	सार्वजनिक शोकेस प्रोजेक्ट: जाँचें कि क्या आप किसी पर दावा कर सकते हैं, उस पर दावा करें, उसमें डेटा भरें
GET	/projects/{id}/audit-log	ऑडिट लॉग पढ़ना — प्रोजेक्ट इतिहास और surface= के ज़रिए प्रति-स्टोरी / प्रति-एपिक गतिविधि; एक्सेस surface के अनुसार बदलता है, नीचे देखें
GET	/projects/{id}/events	कर्सर-पेजिनेटेड इवेंट स्ट्रीम (member) — इवेंट देखें

ऑडिट लॉग के क्वेरी पैरामीटर: event_type= (एक प्रकार या कॉमा-सेपरेटेड सूची), limit= (≤ 1000), before= (keyset कर्सर, ISO-8601 created_at), surface= (project_history, story_activities, epic_activities), target_id= (स्टोरी/एपिक का id — surface=story_activities या epic_activities होने पर आवश्यक)। एक्सेस: बिना फ़िल्टर किया लॉग और surface=project_history (manager) हैं; story_activities / epic_activities को प्रोजेक्ट का कोई भी सदस्य पढ़ सकता है, और सार्वजनिक प्रोजेक्ट पर अनाम रूप से भी, जिसमें कर्ता की PII हटा दी जाती है।

सदस्य, एजेंट, और एजेंट कुंजियाँ

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	इस प्रोजेक्ट पर किसी सदस्य का नाम / ईमेल / अवतार छिपाएँ (manager)
GET / POST	/projects/{id}/agent_keys	एजेंट कुंजियाँ सूचीबद्ध / जारी करें — मैनेजर, या वे भूमिकाएँ जिन्हें प्रोजेक्ट की निर्माता-भूमिका नीति अनुमति देती है
DELETE	/projects/{id}/agent_keys/{kid}	एक एजेंट कुंजी निरस्त करें
GET	/projects/{id}/agent_keys/onboarding	ऑनबोर्डिंग बंडल: आम एजेंट क्लाइंट के लिए प्रॉम्प्ट और कॉन्फ़िग फ़ाइलें
GET	/projects/{id}/agents · GET / PUT /projects/{id}/agents/{aid}	प्रोजेक्ट के एजेंट और उनकी प्रोफ़ाइल (नाम, इनिशियल्स, विवरण, रंग)
POST	/projects/{id}/agents/{aid}/rotate-key · /projects/{id}/agents/{aid}/avatar	किसी एजेंट की कुंजी रोटेट करें (पहचान और इतिहास बने रहते हैं) / उसका अवतार अपलोड करें

स्टोरी

सभी स्टोरी राइट को member भूमिका की आवश्यकता होती है।

Method	Path	विवरण
GET	/projects/{id}/stories	स्टोरी सूचीबद्ध करें (पेजिनेटेड, फ़िल्टर योग्य) (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	डिलीवर की गई स्टोरी अस्वीकार करें / अस्वीकृत स्टोरी को वापस started पर रखें (/transitions के लिए rejected अंतिम है)
POST	/projects/{id}/stories/{sid}/archive · /projects/{id}/stories/{sid}/unarchive	एक स्टोरी संग्रहित / असंग्रहित करें
POST	/projects/{id}/stories/bulk_transition	एक साथ कई स्टोरी (1–100) ट्रांज़िशन करें
POST	/projects/{id}/stories/bulk-archive · bulk-delete · bulk-duplicate · bulk-move	कई स्टोरी को संग्रहित, हटाएँ, डुप्लिकेट, या (किसी पैनल / स्थिति पर) मूव करें
POST	/projects/{id}/stories/{sid}/duplicate	एक स्टोरी डुप्लिकेट करें
GET / POST / DELETE	/projects/{id}/stories/{sid}/epics · …/epics/{eid}	स्टोरी की एपिक सदस्यता
GET	/short-links/{code} · /story-references	किसी /s/<code> शॉर्ट लिंक को उसकी स्टोरी तक हल करें / 100 तक स्टोरी संदर्भों (#id, URL) को उन स्टोरी तक हल करें जिन्हें कॉलर पढ़ सकता है

स्टोरी-लिस्ट क्वेरी पैरामीटर: archived= (exclude डिफ़ॉल्ट / include / only — त्रि-स्थिति संग्रहित फ़िल्टर; बहिष्कृत include_archived=true की जगह लेता है, जो अब archived=include का उपनाम है), include_done=true (बीती इटरेशन पर स्थिर Done-पैनल की स्टोरी शामिल करता है, जो डिफ़ॉल्ट रूप से बाहर रहती हैं)। पेजिनेशन (cursor= / limit= / offset=) और आंशिक फ़ील्ड सेट (fields=) पेजिनेशन और फ़ील्ड प्रोजेक्शन का पालन करते हैं।

Create (POST …/stories): { "name" (required), "story_type": "feature|bug|chore|release", "description"?, "estimate"?, "current_state"?, "icebox"?, "labels"? }। estimate स्केल मान का लेबल है, एक स्ट्रिंग के रूप में ("3", "13"); JSON संख्या अस्वीकार कर दी जाती है। labels ["auth"] या [{ "name": "auth" }] स्वीकार करता है; अज्ञात लेबल बनाए जाते हैं। डिफ़ॉल्ट: story_type=feature, current_state=unstarted।

Update (PUT …/stories/{sid}): समान फ़ील्ड, सभी वैकल्पिक, साथ ही "position" (float), "force_state_change" (bool), और "expected_updated_at" (RFC 3339 — यदि आपके पढ़ने के बाद स्टोरी बदल गई है तो विवरण सहेजना 409 stale_write के साथ अस्वीकृत होता है)। स्टोरी राइट स्टोरी के ETag के विरुद्ध If-Match का भी सम्मान करते हैं; मेल न होने पर 412 precondition_failed।

Transition (POST …/transitions): { "to": "<state>" }। फ़ील्ड to है। { story_id, state } लौटाता है। अवैध मूव → details: { from, to, allowed } के साथ 422 invalid_transition।

Bulk transition (POST …/bulk_transition): { "story_ids": [int,…] (1–100), "to": "<state>" }। प्रत्येक स्टोरी का स्वतंत्र रूप से न्याय किया जाता है; { results: [ { id, status: "ok" } | { id, status: "failed", error } ] } लौटाता है।

स्टोरी उप-संसाधन

सभी member। अधिकांश पर List/GET (viewer) है।

Method	Path	बॉडी / नोट्स
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= (अनुमत सूची: 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/ URL का प्रकार स्वतः तय होता है
GET / POST	/projects/{id}/stories/{sid}/reviews · PUT/DELETE …/reviews/{rid}	बनाएँ: { reviewer_id? / reviewer_agent_id?, comment? } — ख़ुद को असाइन करने के लिए दोनों को छोड़ दें। अपडेट: { status, comment? }
GET / POST	/projects/{id}/stories/{sid}/owners · DELETE …/owners/{mid} · DELETE …/owners/agents/{aid}	{ member_id? / agent_id? } — कॉलर जोड़ने के लिए दोनों को छोड़ दें
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 अपलोड — वीडियो ≤ 200 MB, PDF / Word / Excel ≤ 25 MB, चित्र / CSV / टेक्स्ट ≤ 10 MB; list (viewer) है
GET / POST	/projects/{id}/stories/{sid}/link-attachments · DELETE …/link-attachments/{laid}	लिंक अटैचमेंट — एक बाहरी URL जो कोड लिंक के बजाय फ़ाइल अटैचमेंट के साथ रखा जाता है
GET	/attachments/{token} · /api/avatars/{token}	टोकन-आधारित पते से किसी अटैचमेंट या अवतार को पढ़ना — वही URL जो API देता है; X-TrackerToken की आवश्यकता नहीं

एपिक

स्टोरी जैसा ही आकार, बस स्टेट मशीन के बिना। राइट के लिए member, रीड के लिए (viewer)।

Method	Path	विवरण
GET / POST	/projects/{id}/epics · GET / PUT / DELETE …/epics/{eid}	एपिक में एक नाम, एक Markdown विवरण, और एक आधार लेबल होता है जो उनकी स्टोरी को जोड़ता है
GET / POST / PUT / DELETE	…/epics/{eid}/comments · …/comments/{cid}	एपिक टिप्पणियाँ
GET / POST / DELETE	…/epics/{eid}/owners · …/followers (+ /agents/{aid} रूप)	ओनर और फ़ॉलोअर, सदस्य या एजेंट — एपिक के ओनर उसकी स्टोरी तक फैलते हैं
GET / POST / DELETE	…/epics/{eid}/attachments (+ /json) · …/link-attachments	अटैचमेंट, स्टोरी जैसी ही सीमाएँ
GET	/projects/{id}/analytics/epics · …/analytics/epics/{eid}	प्रति-एपिक प्रगति: बर्नअप, थ्रूपुट, स्वास्थ्य, पूर्वानुमान (viewer)

लेबल

राइट के लिए member, रीड के लिए (viewer)।

Method	Path	विवरण
GET / POST	/projects/{id}/labels	एक लेबल सूचीबद्ध / बनाएँ
PUT / DELETE	/projects/{id}/labels/{lid}	एक लेबल अपडेट / हटाएँ
POST	/projects/{id}/labels/{lid}/archive	एक लेबल संग्रहित (सॉफ़्ट-छिपाएँ) करें

इटरेशन

रीड किसी भी प्रोजेक्ट भूमिका के लिए खुले हैं, और सार्वजनिक प्रोजेक्ट पर अनाम रूप से भी।

Method	Path	विवरण
GET	/projects/{id}/iterations	इटरेशन सूचीबद्ध करें (प्रति पेज ≤ 500; एक ETag रखता है, और छोटा किए जाने पर X-Tracker-Pagination-* निरंतरता हेडर)
GET	/projects/{id}/iterations/{itid}	एक इटरेशन
GET	/projects/{id}/iterations/first-preview	पहले इटरेशन को मिलने वाली तारीख़ें, जो उसे शुरू करने की पुष्टि में दिखाई जाती हैं
POST	/projects/{id}/iterations	एक मैन्युअल इटरेशन बनाएँ (member)
DELETE	/projects/{id}/iterations/{itid}	एक इटरेशन हटाएँ (manager)
PUT	/projects/{id}/iterations/{itid}/velocity	प्रोजेक्ट की रणनीति बदले बिना एक इटरेशन की वेलोसिटी ओवरराइड करें (manager)
GET	/projects/{id}/iterations/{itid}/done-stories	किसी बंद इटरेशन की स्वीकृत स्टोरी, पेजिनेटेड

खोज, मेट्रिक्स, प्राथमिकताएँ

Method	Path	विवरण
GET	/projects/{id}/search?q=…	शक्तिशाली खोज — फ़ुल-टेक्स्ट + फ़ेसेट / तारीख़-रेंज / लोगों वाले क्वालिफ़ायर (GitHub-शैली DSL); { results, total, limit, offset } लौटाता है। query q का उपनाम है; limit= (डिफ़ॉल्ट 50, अधिकतम 1000) / offset= पेजिनेट करते हैं; sort= relevance (डिफ़ॉल्ट), created, created_asc, state, या updated से क्रमबद्ध करता है। (viewer) — गाइड देखें
GET	/projects/{id}/metrics/{velocity,burndown,story-types,contributors}	Metrics पेज की शृंखलाएँ (viewer); एपिक मेट्रिक्स ऊपर /analytics/epics के अंतर्गत हैं
GET	/projects/{id}/backlog/grouping	Backlog के प्रक्षेपित इटरेशन समूह (viewer)
GET / PUT	/projects/{id}/preferences	इस प्रोजेक्ट के लिए आपकी बोर्ड प्राथमिकताएँ — कोई भी प्रोजेक्ट भूमिका, केवल आपकी अपनी पंक्ति

इवेंट

Method	Path	विवरण
GET	/projects/{id}/events	कर्सर-पेजिनेटेड इवेंट स्ट्रीम (member) — viewer को 403 मिलता है

क्वेरी पैरामीटर: since=<event_id>, types=story.created,story.transitioned,comment.added,…, limit= (≤ 500), cursor=। प्रतिक्रिया में next_cursor शामिल है। फिर शुरू करने के लिए आपके द्वारा देखे गए अंतिम event_id को since के रूप में पास करें।

सूचनाएँ

ऐप के भीतर एकीकृत सूचना फ़ीड: प्रथम-श्रेणी की सूचना पंक्तियाँ (रिव्यू अनुरोध, स्टोरी गतिविधि, आमंत्रण, …) @-उल्लेख इनबॉक्स के साथ मिलाकर एक ही स्ट्रीम, नवीनतम पहले। फ़ीड id पर स्रोत-उपसर्ग होता है (nt-… / sc-… / ec-…)। सदस्य सत्र और ea_user_* कुंजियाँ अपनी सदस्य-पक्ष पंक्तियाँ पढ़ती हैं; ea_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	लाइव पुश — Server-Sent Events (text/event-stream); नीचे देखें

stream एंडपॉइंट JSON एंडपॉइंट नहीं है, इसलिए यह OpenAPI विनिर्देश में नहीं है: यह कनेक्शन खुला रखता है और हर नई चीज़ आने पर बिना payload वाला फ़्रेम ({"type":"notification","kind":…}) भेजता है, ताकि क्लाइंट फ़ीड दोबारा ले आए। कनेक्शन सर्वर की ओर से 45 मिनट बाद बंद हो जाते हैं — फिर से जुड़ें और दोबारा प्रमाणीकरण करें। केवल सदस्य सत्र और ea_user_* कुंजियाँ; ea_agent_* कुंजियों को 403 मिलता है।

इम्पोर्ट (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 बॉडी; source=github को किसी फ़ाइल की ज़रूरत नहीं — owner, repo, वैकल्पिक token, और ऑप्ट-इन फ़्लैग include_pull_requests / include_milestones / include_releases / include_dependencies; फ़ाइल स्रोत file_base64 भेजते हैं। असमकालिक: 202 { import_id, status } लौटाता है। सर्वर GitHub के GraphQL API से फ़ेच करता है, जो अनाम कॉलर को अस्वीकार करता है, इसलिए GitHub तक हमेशा कोई न कोई टोकन पहुँचता है — आपका, या तैनाती का साझा टोकन। देखें गाइड।
GET	/projects/{id}/imports/{import_id}	किसी जॉब को पोल करें: status pending → fetching → writing → done | failed क्रम में चलता है, फ़ेच के दौरान progress_current / progress_total और done पर परिणाम गिनतियों के साथ

प्रति प्रोजेक्ट एक समय में एक इम्पोर्ट चलता है; एक के चलते रहने के दौरान दूसरा POST 409 import_already_running होता है। dry_run: true (JSON बॉडी या dry_run=true multipart) किसी भी स्रोत का पूर्वावलोकन करता है: पार्स, हल, डी-डुप करता है, वही { imported, skipped, errors, unmatched } गिनतियाँ बनाता है, फिर रोलबैक करता है — कुछ भी नहीं लिखा जाता। सीमाएँ: 10 MiB बॉडी, और फ़ाइल-आधारित स्रोतों के लिए प्रति इम्पोर्ट 5,000 स्टोरी (किसी एक से अधिक → 400, कुछ भी नहीं लिखा जाता)। GitHub स्रोत पर कोई सीमा नहीं है — वह एक ही लेन-देन के बजाय टुकड़ों में कमिट करता है। स्रोत id के अनुसार फिर से इम्पोर्ट आइडेम्पोटेंट है — पहले से इम्पोर्ट की गई पंक्तियाँ डुप्लिकेट नहीं, बल्कि छोड़ दी जाती हैं।

एक्सपोर्ट

Method	Path	विवरण
GET	/projects/{id}/export/formats	पंजीकृत प्रारूप: { id, name, content_type, drops, includes_archived }। कोई भी प्रोजेक्ट भूमिका।
GET	/projects/{id}/export/{format}	एक डाउनलोड करें (manager)। इंटरचेंज: eat (पूर्ण निष्ठा), jira, pivotal, shortcut, trello, asana, gitlab, linear, plane, plane_json; दस्तावेज़: pdf, docx।
GET	/projects/{id}/export/attachments	हर अटैचमेंट एक ब्राउज़ करने योग्य zip के रूप में (फ़ाइलें मूल नाम रखती हैं; JSON + CSV मैनिफ़ेस्ट) (manager)।

दस्तावेज़ एक्सपोर्ट (pdf, docx) अतिरिक्त क्वेरी पैरामीटर लेते हैं: page_size= (letter डिफ़ॉल्ट / a4 / legal / folio), from= / to= (स्टोरी-विंडो सीमाएँ — RFC 3339 या सादा YYYY-MM-DD; एक स्टोरी सीमा में तब होती है जब उसका created या completed_at उसके भीतर आता है), include_icebox= / include_backlog= (दोनों डिफ़ॉल्ट रूप से false, इसलिए साझा करने योग्य एक्सपोर्ट केवल नियोजित / चालू कार्य दिखाता है)। इंटरचेंज CSV प्रारूप इन्हें अनदेखा करते हैं।

बैकअप और रिस्टोर (manager)

Method	Path	विवरण
GET / POST	/projects/{id}/backups · GET …/backups/{snapshot_id} · …/backups/health	स्नैपशॉट सूचीबद्ध करें, अभी एक लें, एक पढ़ें, और प्रतिधारण स्वास्थ्य सारांश
GET / POST	/projects/{id}/restores · POST …/restores/partial · GET …/restores/{restore_id}	पूरा स्नैपशॉट, या उसमें से चुनी गई तालिकाएँ रिस्टोर करें, और रिस्टोर को पोल करें

ये POST संवेदनशील दर-सीमा स्तर पर हैं (नीचे देखें)।

MCP और OAuth प्रदाता

East Agile Tracker MCP क्लाइंट के लिए एक OAuth 2.1 प्रदाता है। कोई क्लाइंट इसे /.well-known/oauth-authorization-server और /.well-known/oauth-protected-resource/mcp पर खोजता है, आपको /oauth/authorize (सहमति पेज) पर भेजता है, /oauth/token पर कोड का आदान-प्रदान करता है, और फिर परिणामी ea_mcp_* टोकन के साथ /mcp पर MCP बोलता है। अनुदान /me/oauth_grants पर सूचीबद्ध और निरस्त किए जाते हैं। प्रदाता एंडपॉइंट का अपना दर-सीमा स्तर है।

WebSocket

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

इंटरैक्टिव UI दूरस्थ-नियंत्रण के लिए ({ "action": "get_state", "id": "req-1" })। टोकन एक ब्राउज़र सत्र JWT है — API कुंजी अपग्रेड से पहले ही 401 के साथ अस्वीकार कर दी जाती है। कोई डेटा चैनल नहीं — सभी रीड/राइट REST के माध्यम से जाते हैं। केवल एकल-इंस्टेंस; प्रतिकृतियों में फ़ैन आउट नहीं।

आइडेम्पोटेंसी

राइट एंडपॉइंट (POST, PUT, DELETE) एक Idempotency-Key हेडर स्वीकार करते हैं। समान कुंजी + समान बॉडी कैश्ड प्रतिक्रिया फिर से चलाती है (24-घंटे की खिड़की); समान कुंजी + एक अलग बॉडी 409 idempotency_conflict लौटाती है। कुंजी उसे भेजने वाले क्रेडेंशियल तक सीमित है। GET/HEAD/OPTIONS, /openapi.json और /docs, /api/auth/*, या /attachments पथ पर multipart अपलोड पर लागू नहीं। जो प्रतिक्रियाएँ डोमेन उत्तर तक नहीं पहुँचीं वे कभी कैश नहीं होतीं — 401, 403, 404, 429, और हर 5xx — इसलिए उनमें से किसी के बाद रिट्राई हैंडलर तक पहुँचती है; 400, 409, 412, और 422 डोमेन का उत्तर हैं और सफलता की तरह फिर से चलते हैं।

पेजिनेशन

लिस्ट एंडपॉइंट cursor=<opaque> और limit=<n> स्वीकार करते हैं। सेट होने पर, प्रतिक्रिया { "items": [...], "next_cursor": "<str|null>" } होती है; पेज करने के लिए next_cursor वापस पास करें। limit की सीमा प्रति एंडपॉइंट है: स्टोरी, टिप्पणियों, और प्रोजेक्ट पर 200; इवेंट पर 500; खोज और ऑडिट लॉग पर 1000।

एक सादी लिस्ट (बिना cursor/limit) जिसे अपनी प्रतिक्रिया छोटी करनी पड़ी, यह हेडर में बताती है — X-Tracker-Pagination-Truncated, X-Tracker-Pagination-Limit, X-Tracker-Pagination-Offset, और X-Tracker-Pagination-Next-Offset; अगले पेज के लिए अंतिम वाले को offset= के रूप में वापस पास करें। कोई कुल-गिनती हेडर नहीं है।

फ़ील्ड प्रोजेक्शन

लिस्ट एंडपॉइंट केवल विशिष्ट फ़ील्ड लौटाने के लिए 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 नहीं (अधिकांश सत्यापन: रिक्त/लंबाई/नल-बाइट/ईमेल)
400	validation_failed	संरचित इनपुट त्रुटि; details.fields आपत्तिजनक फ़ील्ड नामों की एक array है
401	unauthenticated	अनुपस्थित/अमान्य टोकन
403	unauthorized_operation	प्रमाणित लेकिन अपर्याप्त भूमिका
404	unfound_resource	नहीं मिला — गैर-सदस्यों को भी लौटाया जाता है
409	conflict	संसाधन संघर्ष (जैसे, डुप्लिकेट)
409	idempotency_conflict	Idempotency-Key एक अलग बॉडी के साथ फिर से उपयोग किया गया
409	stale_write · import_already_running	आपके expected_updated_at के बाद स्टोरी बदल गई · एक इम्पोर्ट पहले से चल रहा है
412	precondition_failed	If-Match संसाधन के वर्तमान ETag से मेल नहीं खाया; details में expected और current होते हैं
413	request_too_large	बॉडी रूट की आकार सीमा से अधिक है
422	invalid_transition	अवैध स्टेट मूव; details में { from, to, allowed } होता है
429	rate_limited	किसी दर-सीमित रूट पर इस IP से बहुत अधिक अनुरोध; Retry-After हेडर
500	internal_error	सर्वर दोष — सामान्य संदेश; फिर से आज़माना सुरक्षित
503	not_configured	तैनाती में वह इंटीग्रेशन नहीं है जिसकी इस रूट को ज़रूरत है (SMS, ऑब्जेक्ट स्टोरेज, …)

details.fields फ़ील्ड नामों की एक JSON array है (जैसे, ["to"]), कभी-कभी max जैसी अतिरिक्त कुंजियों के साथ। कोई field→message मैप नहीं है।

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

दर सीमाएँ

प्रति क्लाइंट IP, कुछ ही रूट पर; बाकी जगह प्रमाणित API ट्रैफ़िक दर-सीमित नहीं है। डिफ़ॉल्ट (हर जोड़ी स्थायी दर और 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 s में एक सबमिट, प्रति घंटे 10, प्रति दिन 36।
• Avatars — अप्रमाणित अवतार रीडायरेक्ट: 20 req/s, burst 200।
• Sensitive — बैकअप और रिस्टोर POST: ~0.002 req/s, burst 5।

पार की गई सीमा एक Retry-After हेडर और मानक JSON त्रुटि लिफ़ाफ़े के साथ 429 लौटाती है, code: "rate_limited"।