API गाइड

East Agile Tracker API मनुष्यों जितना ही एजेंट के लिए डिज़ाइन किया गया है। जो कुछ भी आप UI में कर सकते हैं, वह आप API पर कर सकते हैं — और कुछ चीज़ें जो UI उजागर नहीं करता वे भी वहाँ हैं।

यह गाइड आपको दस मिनट से कम में शून्य से “अपने बैकलॉग की स्क्रिप्टिंग” तक ले जाती है। पूर्ण एंडपॉइंट संदर्भ के लिए, API विनिर्देश देखें।

दो तरह की कुंजियाँ

आप X-TrackerToken हेडर में एक API कुंजी के साथ प्रमाणित होते हैं। दो तरह की हैं:

• यूज़र कुंजियाँ (ea_user_…) — आप के रूप में कार्य करती हैं। उन्हें Account Settings → API Keys में बनाएँ। इनका उपयोग व्यक्तिगत स्क्रिप्ट, CLI टूल, इंटीग्रेशन के लिए करें।
• एजेंट कुंजियाँ (ea_agent_…) — एक प्रोजेक्ट में एक नामित एजेंट के रूप में कार्य करती हैं। उन्हें एक प्रोजेक्ट ओनर के रूप में Project Settings → Agents में बनाएँ। इनका उपयोग AI एजेंट के लिए करें — Claude Code, Codex, अपना — जिन्हें नामित साथियों के रूप में प्रोजेक्ट में भाग लेना चाहिए।

अंतर:

	यूज़र कुंजी	एजेंट कुंजी
दायरा	आपके सभी प्रोजेक्ट	एक विशिष्ट प्रोजेक्ट
ऑडिट लॉग में पहचान	आपका नाम	एजेंट का नाम
भूमिका	प्रत्येक प्रोजेक्ट में आपकी भूमिका	कुंजी निर्माण पर सेट (viewer या member)
निरस्तीकरण	एक कुंजी निरस्त करें; आप अन्य कुंजियों/सत्रों से पहुँच रखते हैं	एक कुंजी निरस्त करें; एजेंट तुरंत पहुँच खो देता है
सबसे अच्छा इसके लिए	व्यक्तिगत स्वचालन, स्क्रिप्ट	AI एजेंट जिन्हें इतिहास में आपसे अलग पहचाना जाना चाहिए

यदि आप उस हेडर शैली को पसंद करते हैं तो Authorization: Bearer … भी काम करता है।

हैलो, API

अपने प्रोजेक्ट प्राप्त करें:

curl https://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: $TRACKER_TOKEN"

या किसी एजेंट कुंजी के लिए, उस प्रोजेक्ट को सूचीबद्ध करें जिस तक यह सीमित है:

curl https://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: ea_agent_xxxxx"

API JSON है, REST-जैसा, /api/v1/ पर संस्करणित। मनुष्यों और एजेंट के लिए समान आकार।

एक प्रोजेक्ट बनाएँ

curl -X POST https://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Onboarding redesign",
    "description": "Q3 redesign of new-user onboarding",
    "iteration_length_weeks": 1
  }'

प्रतिक्रिया में project_id और सर्वर द्वारा लागू किए गए कोई भी डिफ़ॉल्ट शामिल हैं (अनुमान स्केल, done state, आदि)।

एक स्टोरी बनाएँ

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Add OAuth login for Google",
    "description": "## Acceptance\n- Google button on /login\n- Redirect back to original URL",
    "story_type": "feature",
    "estimate": 3,
    "labels": ["auth"]
  }'

किसी स्टोरी को जीवनचक्र के माध्यम से ले जाएँ

ट्रांज़िशन एंडपॉइंट अनुरोधित मूव को सत्यापित करता है और त्रुटि पर अनुमत अगले स्टेट लौटाता है:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/$STORY_ID/transitions \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "to": "started" }'

फ़ील्ड to है (न कि to_state)। यदि मूव अवैध है — मान लीजिए आपने unstarted से सीधे accepted पर छलाँग लगाने की कोशिश की — तो प्रतिक्रिया संरचित त्रुटि विवरण के साथ 422 invalid_transition होती है:

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

यह उन छोटी चीज़ों में से एक है जो API को एजेंट-अनुकूल बनाती हैं: एक एजेंट details.allowed पढ़ सकता है और गद्य को स्क्रैप किए बिना सही अगला मूव चुन सकता है।

किसी स्टोरी पर टिप्पणी करें

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/$STORY_ID/comments \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Investigation done. Picking this up." }'

टिप्पणी उसे श्रेय दी जाती है जिसके पास API कुंजी है — यदि यह एक एजेंट कुंजी है, तो टिप्पणी का लेखक एजेंट है।

आइडेम्पोटेंट राइट

हर राइट एंडपॉइंट एक Idempotency-Key हेडर स्वीकार करता है। समान बॉडी के साथ वही कुंजी फिर से आज़माएँ, वही प्रतिक्रिया वापस पाएँ। अलग बॉडी के साथ वही कुंजी फिर से आज़माएँ, एक 409 idempotency_conflict पाएँ:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Refactor auth middleware", "story_type": "chore" }'

यह रिट्राई लूप में एजेंट के लिए महत्वपूर्ण है — राइट के बीच में क्रैश, उसी कुंजी के साथ फिर से आज़माएँ, कोई डुप्लिकेट स्टोरी नहीं।

थोक ट्रांज़िशन

एक साथ कई स्टोरी को मूव करें। प्रत्येक स्टोरी का स्वतंत्र रूप से न्याय किया जाता है; एक अवैध मूव दूसरों को विफल नहीं करता।

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/bulk_transition \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "story_ids": [101, 102, 103],
    "to": "delivered"
  }'

इवेंट स्ट्रीम फ़ॉलो करें

उन एजेंट के लिए जो मनुष्यों के किए पर प्रतिक्रिया देना चाहते हैं, events एंडपॉइंट को पोल करें:

curl "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/events?since=$LAST_CURSOR&types=story.created,story.transitioned,comment.created" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

प्रतिक्रिया एक्टर, संसाधन, और परिवर्तन के साथ इवेंट की एक कर्सर-पेजिनेटेड स्ट्रीम है। हर इवेंट का एक ID होता है; जहाँ आपने छोड़ा था वहाँ से फिर शुरू करने के लिए आपके द्वारा देखे गए अंतिम ID को since के रूप में पास करें। कोई वेबहुक नहीं, कोई स्क्रैपिंग नहीं, कोई छूटे हुए इवेंट नहीं।

फ़िल्टर सिंटैक्स के साथ खोजें

curl "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/search?query=type:feature%20state:started%20label:mvp" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

उपलब्ध फ़िल्टर:

फ़िल्टर	उदाहरण	विवरण
type:	type:feature	स्टोरी प्रकार के अनुसार फ़िल्टर
state:	state:started	स्टेट के अनुसार फ़िल्टर
label:	label:"my label"	लेबल के अनुसार फ़िल्टर
owner:	owner:claire	ओनर के अनुसार फ़िल्टर
requester:	requester:tomas	अनुरोधकर्ता के अनुसार फ़िल्टर
has:	has:blocker	ब्लॉकर वाली स्टोरी
is:	is:unestimated	बिना अनुमान वाले फ़ीचर

मुक्त पाठ शीर्षक और विवरण से मेल खाता है। उन्हें स्पेस-पृथक करके फ़िल्टर संयोजित करें — वे AND किए जाते हैं।

API की खोज करें

लाइव OpenAPI 3 स्पेक यहाँ है:

https://eastagiletracker.com/api/v1/openapi.json

Swagger UI यहाँ है:

https://eastagiletracker.com/api/v1/docs

/openapi.json और /docs अप्रमाणित हैं — एक एजेंट कुंजी होने से पहले अनुबंध पढ़ सकता है। एक बार जब इसके पास कुंजी हो, तो /api/v1/meta (जिसके लिए एक वैध कुंजी की आवश्यकता होती है) इसकी पहचान और प्रति-स्टोरी-प्रकार ट्रांज़िशन ग्राफ़ लौटाता है; संदर्भ-डेटा लुकअप (/story_types, /story_states, /effort_scales) भी अप्रमाणित हैं। साथ में वे एजेंट को बिना ट्रायल-एंड-एरर 403 के “मैं यहाँ क्या कर सकता हूँ?” का उत्तर देने देते हैं।

नोट: परोसा गया openapi.json पथ सूचीबद्ध करता है लेकिन वर्तमान में खाली अनुरोध बॉडी शिप करता है — राइट के लिए विनिर्देश में फ़ील्ड आकार का उपयोग करें।

WebSocket नियंत्रण

इंटरैक्टिव स्वचालन के लिए — एक स्क्रिप्ट से लॉग-इन ब्राउज़र सत्र चलाना, या ट्यूटोरियल के लिए UI को दूरस्थ रूप से नियंत्रित करना — एक WebSocket चैनल है:

const ws = new WebSocket('wss://eastagiletracker.com/ws/control?token=YOUR_TOKEN')
ws.send(JSON.stringify({ action: 'get_state', id: 'req-1' }))

अधिकांश उपयोगकर्ताओं को इसकी कभी ज़रूरत नहीं होती; यह उन मामलों के लिए है जहाँ REST पर्याप्त नहीं है।

किसी अन्य ट्रैकर से इम्पोर्ट करें

यदि आप एक थोक माइग्रेशन की स्क्रिप्टिंग कर रहे हैं:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/import \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -F "source=pivotal" \
  -F "file=@pivotal_export.csv"

समर्थित स्रोत: pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json।

त्रुटि प्रारूप

सभी त्रुटियाँ JSON हैं जिनमें कम से कम:

{
  "code": "invalid_transition",
  "error": "Cannot move story from `unstarted` to `accepted`"
}

कई त्रुटि प्रतिक्रियाओं में एक details ऑब्जेक्ट भी शामिल होता है — validation_failed पर details.fields (आपत्तिजनक फ़ील्ड नामों की एक array), और 422 invalid_transition पर details.allowed (from/to के साथ)। उनका उपयोग करें।

पेजिनेशन

लिस्ट एंडपॉइंट limit और cursor स्वीकार करते हैं। कर्सर अपारदर्शी है; पिछली प्रतिक्रिया से next_cursor पास करें। प्रतिक्रिया हेडर में कुल गिनती के लिए X-Tracker-Pagination-Total भी शामिल है जहाँ गणना करना सस्ता हो।

आगे क्या है

• API विनिर्देश — हर एंडपॉइंट, हर वर्ब, हर आकार।
• संचालन निर्देश → एजेंट — UI-पक्ष: एजेंट कुंजियाँ जारी करना, एजेंट का नामकरण, निरस्त करना।
• परिचय — API के पीछे की अवधारणाएँ: स्टोरी, स्टेट, इटरेशन, वेलोसिटी, एजेंट।