API विनिर्देश

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

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

आधार

https://eastagiletracker.com/api/v1

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

प्रमाणीकरण

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

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

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

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

भूमिकाएँ

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

स्तर	कौन पास करता है	विशिष्ट ऑपरेशन
viewer	viewer, member, owner	रीड (स्टोरी लिस्ट/गेट, खोज, एनालिटिक्स)
member	member, owner	सभी कार्य-आइटम राइट (स्टोरी, टास्क, टिप्पणियाँ, …)
owner	केवल owner	प्रोजेक्ट सेटिंग्स, सदस्यता प्रबंधन, एजेंट कुंजियाँ, डिलीट, इम्पोर्ट, ऑडिट लॉग

एक गैर-सदस्य प्रोजेक्ट पथ पर 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) + स्टोरी-प्रकार ट्रांज़िशन ग्राफ़। प्रमाणित (कोई भी वैध कुंजी; प्रोजेक्ट-सीमित नहीं)। इसे पहले कॉल करें।

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

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

Method	Path	विवरण
POST	/auth/register	एक नया अकाउंट रजिस्टर करें
POST	/auth/login	साइन इन करें, एक सत्र टोकन लौटाता है
POST	/auth/logout	साइन आउट करें
POST	/auth/forgot-password	पासवर्ड-रीसेट ईमेल का अनुरोध करें
POST	/auth/reset-password	नया पासवर्ड सेट करने के लिए रीसेट टोकन का उपयोग करें
GET	/auth/verify-email	एक ईमेल पता सत्यापित करें
POST	/auth/accept-invite/lookup	एक आमंत्रण टोकन को हल करें → ईमेल (अप्रमाणित)
POST	/auth/accept-invite	एक प्रोजेक्ट आमंत्रण स्वीकार करें (प्रमाणित होने के बाद)
GET	/me	वर्तमान उपयोगकर्ता प्रोफ़ाइल
PUT	/me	प्रोफ़ाइल अपडेट करें
DELETE	/me	अकाउंट हटाएँ
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/activity	सभी प्रोजेक्ट में आपकी गतिविधि
GET	/me/data-export	आपके डेटा का GDPR स्व-एक्सपोर्ट
GET	/me/consent · POST /me/consent	सहमति पढ़ें / रिकॉर्ड करें ({ consent_type, granted })
GET	/legal/pending · POST /legal/accept	लंबित क्लिकरैप दस्तावेज़ / स्वीकृति रिकॉर्ड करें
POST	/contact · POST /feedback · POST /feedback/with-screenshot	संपर्क + इन-ऐप प्रतिक्रिया

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

स्टोरी बनाते/अनुमान लगाते समय उपयोग किए जाने वाले सीड लुकअप। स्थिर 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	किसी स्केल में पॉइंट मान

प्रोजेक्ट

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	कर्सर-पेजिनेटेड इवेंट स्ट्रीम (viewer) — Events देखें

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

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	एजेंट कुंजियाँ सूचीबद्ध / जारी करें (owner)
DELETE	/projects/{id}/agent_keys/{kid}	एक एजेंट कुंजी निरस्त करें (owner)

स्टोरी

सभी स्टोरी राइट को 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/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" }] स्वीकार करता है; अज्ञात लेबल बनाए जाते हैं। डिफ़ॉल्ट: 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 } लौटाता है। अवैध मूव → details: { from, to, allowed } के साथ 422 invalid_transition.

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	बॉडी / नोट्स
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? } — कॉलर जोड़ने के लिए दोनों को छोड़ दें
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) है

लेबल

राइट के लिए 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	इटरेशन सूचीबद्ध करें (member)
POST	/projects/{id}/iterations	एक मैन्युअल इटरेशन बनाएँ (owner)
DELETE	/projects/{id}/iterations/{itid}	एक इटरेशन हटाएँ (owner)

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

Method	Path	विवरण
GET	/projects/{id}/search?query=…	फ़िल्टर सिंटैक्स खोज (viewer) — गाइड देखें
GET	/projects/{id}/analytics/{overview,iteration,releases,activity,cycle-time,projections}	एनालिटिक्स (viewer). इटरेशन विस्तृत विश्लेषण ?iteration_id= लेता है
GET	/projects/{id}/metrics/{velocity,burndown,story-types}	मेट्रिक्स (viewer)
GET / PUT	/projects/{id}/preferences	इस प्रोजेक्ट के लिए आपकी बोर्ड प्राथमिकताएँ (member)

इवेंट

Method	Path	विवरण
GET	/projects/{id}/events	कर्सर-पेजिनेटेड इवेंट स्ट्रीम (viewer)

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

इम्पोर्ट (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" })। कोई डेटा चैनल नहीं — सभी रीड/राइट REST के माध्यम से जाते हैं। केवल एकल-इंस्टेंस; प्रतिकृतियों में फ़ैन आउट नहीं।

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

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

पेजिनेशन

लिस्ट एंडपॉइंट cursor=<opaque> और limit=<n≤200> स्वीकार करते हैं। सेट होने पर, प्रतिक्रिया { "items": [...], "next_cursor": "<str|null>" } होती है; पेज करने के लिए next_cursor वापस पास करें। कुछ लिस्ट एक X-Tracker-Pagination-Total हेडर भी लौटाती हैं।

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

लिस्ट एंडपॉइंट केवल विशिष्ट फ़ील्ड लौटाने के लिए 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 एक अलग बॉडी के साथ फिर से उपयोग किया गया
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"] } }

दर सीमाएँ

प्रति-कुंजी (अप्रमाणित एंडपॉइंट के लिए प्रति-IP), GCRA टोकन बकेट:

• Auth — /auth/*: 0.5 req/s, burst 20.
• Public — /contact, /feedback: 0.2 req/s, burst 10.
• Sensitive — पासवर्ड-रीसेट: ~0.002 req/s, burst 5.

एक पार की गई सीमा एक Retry-After हेडर और एक plain-text बॉडी (न कि JSON त्रुटि लिफ़ाफ़ा) के साथ 429 Too Many Requests लौटाती है।