API: बुनियादी बातें

VentionDesk API वही है जिसका इस्तेमाल इंटरफ़ेस करता है। ऑटोमेशन के लिए — Claude, आपकी अपनी स्क्रिप्ट, CI — आप एक API कुंजी से साइन इन करते हैं। सभी URL https://api.ventiondesk.com से शुरू होते हैं; सभी बॉडी और जवाब UTF-8 में JSON होते हैं।

API कुंजी से साइन इन करना (Signing in with an API key)

मालिक सेटिंग्स › API कुंजियाँ › “नई कुंजी” में कुंजी बनाता है। यह ठीक एक बार सादे टेक्स्ट में दिखती है।

हर अनुरोध इसे बेयरर टोकन के रूप में भेजता है:

curl https://api.ventiondesk.com/v1/tasks?status=todo \
  -H "Authorization: Bearer vd_live_…"

इसे बदलने के लिए कोई अलग एंडपॉइंट नहीं है: VentionDesk कुंजी को उसके प्रीफ़िक्स से पहचानता है, हर अनुरोध पर उसे जाँचता है (वापस ली गई? समाप्त?) और फिर कुंजी के खाते के सेशन के साथ काम करता है। इसलिए कुंजी पर वही डेटाबेस नियम लागू होते हैं जो किसी व्यक्ति पर — वह केवल वही देखती है जो उसका स्कोप अनुमति देता है।

कुंजी की जगह OAuth से जुड़े किसी AI ऐप का साइन इन भी बेयरर टोकन के रूप में आ सकता है। यह एक एजेंट कुंजी की तरह गिना जाता है, उन अनुमतियों और प्रोजेक्ट के साथ जो व्यक्ति ने सहमति के समय चुने थे — कभी उस व्यक्ति की अपनी अनुमतियों के साथ नहीं — और डिस्कनेक्ट करते ही तुरंत ख़त्म हो जाता है।

एजेंट कुंजी एजेंट भूमिका वाला एक अलग खाता है। यह उन एंडपॉइंट के लिए है जिन पर API रेफ़रेंस में स्कोप दिखता है, साथ ही GET /v1/me और एजेंट रन के लिए। जिन एंडपॉइंट के लिए “मालिक” या “मालिक और स्टाफ़ सदस्य” चाहिए, उन्हें वेब इंटरफ़ेस साइन इन किए हुए व्यक्ति के सेशन से चलाता है; API कुंजी को वे 403 से जवाब देते हैं।

स्कोप (Scopes)

एजेंट कुंजी क्या कर सकती है, यह उसके स्कोप तय करते हैं:

कोई स्कोप ठीक उन्हीं एंडपॉइंट पर दिखता है जो उसे मानते हैं — API रेफ़रेंस हर एंडपॉइंट के साथ उसका नाम बताता है। deployments:read किसी एंडपॉइंट पर नहीं दिखता: यह मिरर किए गए कमिट, पुल रिक्वेस्ट और डिप्लॉयमेंट के डेटाबेस नियमों के ज़रिए लागू होता है।

प्रोजेक्ट बाइंडिंग (Project binding)

एक कुंजी सभी प्रोजेक्ट या एक चयन पर लागू होती है। बंधी हुई कुंजी केवल अपने प्रोजेक्ट का डेटा देखती है — और जान-बूझकर बिना प्रोजेक्ट वाला कुछ भी नहीं, जैसे वे टिकट जो अभी किसी प्रोजेक्ट को नहीं सौंपे गए। अपने प्रोजेक्ट से बाहर की पंक्ति पर API 404 या 403 से जवाब देता है। इनटेक कुंजी हमेशा ठीक एक प्रोजेक्ट से बंधी होती है।

दायरा बदलने के लिए नई कुंजी ज़रूरी नहीं। स्कोप और प्रोजेक्ट मालिक कुंजी सूची में “अनुमतियाँ” के तहत बदलता है; अगला अनुरोध पहले से नए दायरे के साथ काम करता है। वापस ली गई या समाप्त कुंजी अगले अनुरोध पर अस्वीकार कर दी जाती है।

त्रुटियाँ (Errors)

हर त्रुटि जवाब का आकार एक जैसा होता है:

{ "ok": false, "error": "Diese Aufgabe gibt es nicht.", "code": "not_found" }

error लोगों के लिए एक जर्मन वाक्य है, code प्रोग्राम के लिए एक स्थिर अंग्रेज़ी मान। आम जवाब:

हर जवाब x-request-id हेडर में एक ID देता है। अगर आप ख़ुद एक भेजते हैं (128 अक्षरों तक), तो उसी का इस्तेमाल होता है। कुछ गड़बड़ होने पर इसे सपोर्ट को दें।

रेट लिमिट (Rate limits)

प्रति मिनट गिना जाता है, प्रति कुंजी या प्रति IP पता:

सीमा से ऊपर API 429 और rate_limited से जवाब देता है; RateLimit और RateLimit-Policy हेडर मौजूदा गिनती और सीमा बताते हैं।

सूचियाँ और फ़िल्टर (Lists and filters)

सूची वाले एंडपॉइंट क्वेरी पैरामीटर से फ़िल्टर करते हैं और limit से सीमित करते हैं; कर्सर या ऑफ़सेट वाले पेज नहीं हैं। उदाहरण:

• GET /v1/tasks?projectSlug=shop&status=todo&claimable=true&limit=20 — वे टास्क जो अभी लिए जा सकते हैं।
• GET /v1/projects?status=active — सक्रिय प्रोजेक्ट।

कौन-सा एंडपॉइंट कौन-से पैरामीटर जानता है और कौन-से फ़ील्ड लौटाता है, यह API रेफ़रेंस में दिया गया है — उसी कॉन्ट्रैक्ट से पढ़ा गया, जिससे VentionDesk अनुरोध जाँचता है।

एजेंट का सामान्य राउंड (The typical round of an agent)

1. GET /v1/tasks?claimable=true — क्या करना है?
2. POST /v1/tasks/:id/claim — टास्क को एटॉमिक रूप से लें। दो रन को कभी एक ही टास्क नहीं मिलता।
3. काम करें; बीच में POST /v1/tasks/:id/result के साथ "state": "arbeitet", जीवित होने के संकेत के रूप में।
4. POST /v1/tasks/:id/result के साथ kontrolle, frage, master, blockiert या erledigt — kontrolle और erledigt के साथ evidence में सबूत भी दें।

अगर आप इसे ख़ुद नहीं बनाना चाहते, तो Claude और MCP इस्तेमाल करें।