API गाइड

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

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

तीन तरह के क्रेडेंशियल

आप X-TrackerToken हेडर में एक कुंजी के साथ प्रमाणित होते हैं। दो तरह की कुंजियाँ आप ख़ुद जारी करते हैं, और एक तीसरी जिसे कोई MCP क्लाइंट आपके लिए प्राप्त करता है:

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

Account Settings में निजी API कुंजी बनाने के बाद एक बार दिखने वाला डायलॉग, इस स्क्रीनशॉट में कुंजी छिपाई गई है

Agent टैब का कुंजी बनाने वाला फ़ॉर्म, जिसमें नाम और member भूमिका चुनी गई है, सेटअप निर्देशों के नीचे

आपके द्वारा जारी की जाने वाली दो कुंजियों के बीच अंतर:

	यूज़र कुंजी	एजेंट कुंजी
दायरा	आपके सभी प्रोजेक्ट	एक विशिष्ट प्रोजेक्ट
ऑडिट लॉग में पहचान	आपका नाम	एजेंट का नाम
भूमिका	प्रत्येक प्रोजेक्ट में आपकी भूमिका	कुंजी निर्माण पर सेट (viewer, member, या manager — जारी करने वाले सदस्य की अपनी भूमिका से कभी ऊपर नहीं)
निरस्तीकरण	एक कुंजी निरस्त करें; आप अन्य कुंजियों/सत्रों से पहुँच रखते हैं	एक कुंजी निरस्त या रोटेट करें; एजेंट तुरंत पहुँच खो देता है
सबसे अच्छा इसके लिए	व्यक्तिगत स्वचालन, स्क्रिप्ट	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"]
  }'

estimate स्केल मान का लेबल है, एक स्ट्रिंग के रूप में — "3", या Fibonacci स्केल पर "13" — क्योंकि इसे प्रोजेक्ट के स्केल के किसी बिंदु से मेल खाना होता है। JSON संख्या अस्वीकार कर दी जाती है।

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

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

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 पढ़ सकता है और गद्य को स्क्रैप किए बिना सही अगला मूव चुन सकता है।

ट्रांज़िशन एंडपॉइंट के लिए rejected अंतिम है। किसी अस्वीकृत स्टोरी को फिर से काम में लाने के लिए POST …/stories/{sid}/restart कॉल करें; POST …/stories/{sid}/reject किसी डिलीवर की गई स्टोरी को अस्वीकार करने का क्रिया-रूप है।

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

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.added" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

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

खोज

GET /projects/{id}/search?q=<query> प्रोजेक्ट की स्टोरी पर एक शक्तिशाली फ़ुल-टेक्स्ट + संरचित खोज चलाता है। क्वेरी भाषा GitHub के issue-खोज क्वालिफ़ायर पर आधारित है — इसलिए जो सिंटैक्स आप (या कोई AI एजेंट) GitHub से पहले से जानते हैं, वह ज़्यादातर यहाँ भी चलता है।

curl -G "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/search" \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  --data-urlencode 'q=payment crash type:bug,chore owner:@me created:>2026-05-01'

प्रतिक्रिया एक JSON लिफ़ाफ़ा है, जिसमें स्टोरी प्रासंगिकता के अनुसार रैंक की गई हैं:

{ "results": [ /* canonical story objects */ ], "total": 42, "limit": 50, "offset": 0 }

total मिलानों की पूरी गिनती है, पेज का आकार नहीं। limit (डिफ़ॉल्ट 50, अधिकतम 1000) और offset से पेज करें; sort=relevance (डिफ़ॉल्ट), created, created_asc, updated, या state से क्रमबद्ध करें।

व्याकरण

मुक्त पाठ स्टोरी के शीर्षक, संदर्भ, और विवरण से मेल खाता है (फ़ुल-टेक्स्ट, स्टेमिंग और रैंकिंग के साथ)। किसी सटीक वाक्यांश को "उद्धरण चिह्नों" में लपेटें।
क्वालिफ़ायर field:value होते हैं। विकल्पों को कॉमा से अलग करें (एक फ़ील्ड के भीतर OR): type:bug,chore। क्वालिफ़ायर को स्पेस से अलग करें (उनके बीच AND)।
किसी भी पद या क्वालिफ़ायर को आगे - लगाकर नकारें: -label:wontfix।
तारीख़ों और पॉइंट के लिए रेंज: समावेशी a..b, या खुले सिरे वाली >x / <x।

क्वालिफ़ायर

क्वालिफ़ायर	उदाहरण	किससे मेल खाता है
`type:`	`type:bug,chore`	स्टोरी प्रकार
`state:`	`state:started,finished`	वर्कफ़्लो स्टेट
`label:`	`label:"my label"`	एक लेबल
`epic:`	`epic:"Checkout"`	किसी एपिक की स्टोरी
`priority:`	`priority:p1`	प्राथमिकता
`points:`	`points:3` · `points:1..5` · `points:>3`	अनुमान मान या रेंज
`iteration:`	`iteration:42`	इटरेशन id
`created:` `updated:` `started:` `completed:` `release:`	`created:2026-05-01..2026-06-01` · `updated:>2026-06-01`	एक तारीख़ या रेंज (दिन-स्तर); `release:` स्टोरी की रिलीज़ तारीख़ है
`owner:` `requester:` `follower:` `reviewer:` `commenter:` `mention:`	`owner:claire` · `owner:@me`	नाम या ईमेल से कोई व्यक्ति — सदस्य और एजेंट, `mention:` सहित; `@me` आप हैं
`has:blocker`	`has:blocker`	कोई खुला ब्लॉकर है
`is:`	`is:unestimated` · `is:icebox` · `is:backlog` · `is:blocked`	एक फ़्लैग

mywork: owner: का उपनाम है — mywork:me का अर्थ owner:@me है। पुराना scheduled: क्वालिफ़ायर हटा दिया गया है और चुपचाप अनदेखा किया जाता है; release: का उपयोग करें।

कॉमा-OR (type:bug,chore) फ़ेसेट क्वालिफ़ायर पर लागू होता है; लोगों वाले क्वालिफ़ायर (owner: requester: follower: reviewer: commenter: mention:) एक ही मान लेते हैं।

उदाहरण

payment crash                              full text "payment" AND "crash"
"exact phrase"                             a phrase
type:bug,chore state:started               bugs or chores that are started
owner:@me -label:wontfix                   mine, excluding the wontfix label
points:3..8 created:2026-05-01..2026-06-01 estimated 3-8, created in May
follower:tomas has:blocker                 tomas follows it and it's blocked
is:backlog updated:>2026-06-01             backlog items touched since Jun 1

वही क्वेरी स्ट्रिंग बोर्ड के खोज बॉक्स (जो एक लाइव परिणाम कॉलम खोलता है) और इस API दोनों को चलाती है — मनुष्यों और एजेंट दोनों के लिए एक ही व्याकरण। टिप्पणियों, टास्क, और ब्लॉकर की सामग्री में खोज रोडमैप पर है; आज मुक्त पाठ स्टोरी के अपने शीर्षक, संदर्भ, और विवरण को ही कवर करता है।

API की खोज करें

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

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

Swagger UI यहाँ है:

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

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

परोसा गया openapi.json राइट एंडपॉइंट के लिए अनुरोध-बॉडी स्कीमा रखता है, जिसमें हर फ़ील्ड का maxLength शामिल है, ताकि कोई क्लाइंट भेजने से पहले सत्यापन कर सके। विनिर्देश इन्हीं आकारों का सारांश देता है।

WebSocket नियंत्रण

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

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

token ब्राउज़र सत्र का JWT है, API कुंजी नहीं — ea_user_* या ea_agent_* कुंजी अपग्रेड से पहले ही अस्वीकार कर दी जाती है। अधिकांश उपयोगकर्ताओं को इसकी कभी ज़रूरत नहीं होती; यह उन मामलों के लिए है जहाँ 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, eat (East Agile Tracker का अपना एक्सपोर्ट — राउंड-ट्रिप प्रारूप)। multipart एंडपॉइंट समकालिक रूप से चलता है और परिणाम गिनतियों के साथ उत्तर देता है।

GitHub किसी फ़ाइल के बजाय API से इम्पोर्ट करता है, JSON एंडपॉइंट के माध्यम से — कोई file नहीं, बस रिपॉज़िटरी निर्देशांक:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/import/json \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "source": "github",
        "owner": "octocat",
        "repo": "hello-world",
        "token": "ghp_…",
        "include_pull_requests": false,
        "include_milestones": false,
        "include_releases": false,
        "include_dependencies": false
      }'

JSON एंडपॉइंट असमकालिक है: यह { "import_id", "status" } के साथ 202 उत्तर देता है और आप GET /projects/{id}/imports/{import_id} को तब तक पोल करते हैं जब तक जॉब done या failed तक न पहुँच जाए। प्रति प्रोजेक्ट एक समय में केवल एक इम्पोर्ट चलता है — जब एक चल रहा हो तब दूसरी कॉल 409 import_already_running होती है। जॉब के प्रगति फ़ील्ड सहित पूरा लूप GitHub रिपॉज़िटरी से प्रोजेक्ट भरें में है।

token अनुरोध में वैकल्पिक है, पर फ़ेच स्वयं हमेशा प्रमाणित होता है — यह GitHub के GraphQL API पर चलता है, जिसमें कोई अनाम स्तर है ही नहीं। token छोड़ दें तो सर्वर अपना प्लेटफ़ॉर्म टोकन लगा देता है: केवल सार्वजनिक रिपॉज़िटरी, हर कॉलर द्वारा साझा, और जब उसका GraphQL बजट 500 अंकों से नीचे गिरता है तो import_github_shared_quota_low के साथ अस्वीकृत। निजी रिपॉज़िटरी, या ऐसी तैनाती जिसने कोई प्लेटफ़ॉर्म टोकन कॉन्फ़िगर नहीं किया (import_github_no_token), के लिए आपका अपना टोकन चाहिए। जो भी टोकन चले, उसका उपयोग केवल अपस्ट्रीम GitHub कॉल के लिए किया जाता है और वह कभी संग्रहीत या वापस प्रतिध्वनित नहीं किया जाता। पूरा विवरण, GitHub की बिना प्रमाणीकरण वाली 60 अनुरोध की REST सीमा सहित, GitHub रिपॉज़िटरी से प्रोजेक्ट भरें में है।

ड्राई-रन पूर्वावलोकन। किसी भी स्रोत में "dry_run": true (JSON) या -F "dry_run=true" (multipart) जोड़ें। इम्पोर्ट ठीक वैसे ही पार्स, हल, और डी-डुप्लिकेट करता है जैसे एक असली रन, वही परिणाम गिनतियाँ (imported, skipped, errors, unmatched) बनाता है, फिर सब कुछ रोलबैक कर देता है — कुछ भी नहीं लिखा जाता। JSON एंडपॉइंट पर गिनतियाँ पोल किए गए जॉब पर आती हैं, ड्राई रन हो या न हो।

सीमाएँ। एक अपलोड बॉडी 10 MiB पर सीमित है, और एक अकेला इम्पोर्ट 5,000 स्टोरी पर; किसी एक को पार करना एक 400 है जिसमें कुछ भी नहीं लिखा जाता। किसी फ़ाइल को फिर से इम्पोर्ट करना सुरक्षित है — पहले से इम्पोर्ट की गई पंक्तियाँ (स्रोत id द्वारा मिलान की गई) डुप्लिकेट नहीं, बल्कि छोड़ दी जाती हैं।

एक प्रोजेक्ट एक्सपोर्ट करें

कोई भी प्रोजेक्ट भूमिका प्रारूप सूचीबद्ध कर सकती है; किसी एक को डाउनलोड करना केवल-ओनर है:

# The registered export formats: { id, name, content_type, drops, includes_archived }
curl https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/export/formats \
  -H "X-TrackerToken: $TRACKER_TOKEN"

# Download one format (eat is the full-fidelity round-trip CSV)
curl https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/export/eat \
  -H "X-TrackerToken: $TRACKER_TOKEN" -o project-export.csv

इंटरचेंज प्रारूप id: eat, jira, pivotal, shortcut, trello, asana, gitlab, linear, plane, plane_json, साथ ही दस्तावेज़ प्रारूप pdf और docx। हर अटैचमेंट GET /projects/{id}/export/attachments से एक zip के रूप में डाउनलोड करने योग्य है।

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

सभी त्रुटियाँ 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 के साथ)। उनका उपयोग करें। 429 rate_limited उसी JSON लिफ़ाफ़े में एक Retry-After हेडर के साथ आता है।

पेजिनेशन

लिस्ट एंडपॉइंट limit और cursor स्वीकार करते हैं। कर्सर अपारदर्शी है; पिछली प्रतिक्रिया से next_cursor पास करें। limit की सीमा प्रति एंडपॉइंट है — स्टोरी, टिप्पणियों, और प्रोजेक्ट पर 200, इवेंट पर 500, खोज और ऑडिट लॉग पर 1000। एक सादी (बिना कर्सर वाली) लिस्ट जिसे अपनी प्रतिक्रिया छोटी करनी पड़ी, यह हेडर में बताती है: X-Tracker-Pagination-Truncated, -Limit, -Offset, और -Next-Offset, जिसे आप अगले पेज के लिए offset= के रूप में वापस पास करते हैं। कोई कुल-गिनती हेडर नहीं है।

आगे क्या है

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