API रेफरेंस

Cuneiform Chat का डेवलपर REST API आपके डेवलपर्स को knowledge डॉक्यूमेंट प्रबंधित करने, agents बनाने और कॉन्फ़िगर करने, और प्रोग्रामेटिक रूप से agents चलाने देता है — वही क्षमताएँ जो एडमिन पैनल उजागर करता है, एक क्रेडेंशियल-संरक्षित, वर्ज़न्ड HTTP सरफेस पर उपलब्ध।

यह रेफरेंस सार्वजनिक /v1 अनुबंध का दस्तावेज़ीकरण करता है: हर endpoint, उसके पैरामीटर, एक उदाहरण अनुरोध, और प्रतिक्रिया का सटीक रूप।

बेस URL

सभी endpoints एक ही वर्ज़न्ड बेस URL के अंतर्गत रहते हैं:

https://cuneiform.chat/api/developer/v1

किसी endpoint का पूरा पाथ बेस URL और हर पृष्ठ पर दिखाया गया पाथ होता है — उदाहरण के लिए, GET /agents है:

https://cuneiform.chat/api/developer/v1/agents

वर्ज़निंग

API URL प्रिफ़िक्स में वर्ज़न्ड है (/v1)। कोई हेडर-आधारित या तिथि-आधारित वर्ज़निंग नहीं है — आप जो वर्ज़न कॉल करते हैं वही पाथ में मौजूद वर्ज़न है। /v1 अनुबंध स्थिर है: फ़ील्ड केवल जोड़े जाते हैं, कभी हटाए या पुनः उपयोग नहीं किए जाते, और एक नया मेजर वर्ज़न (यदि कभी आवश्यक हुआ) एक नए प्रिफ़िक्स के अंतर्गत जारी होगा। रिलीज़ बेसलाइन के लिए चेंजलॉग नोट देखें।

एक पंक्ति में प्रमाणीकरण

हर अनुरोध एक डेवलपर API key (cuk_…) से प्रमाणित होता है, जिसे एक Bearer टोकन के रूप में भेजा जाता है:

Authorization: Bearer cuk_live_xxxxxxxxxxxxxxxx

Key आपके organization और उसे दिए गए scopes में रिज़ॉल्व होती है — आप कभी organization id नहीं भेजते। पूरे अनुबंध के लिए प्रमाणीकरण और API Keys देखें।

आपकी पहली कॉल

1. एक key बनाएँ। एडमिन पैनल में, /org/developer-api पर डेवलपर कंसोल खोलें, एक key बनाएँ और सीक्रेट कॉपी करें (यह केवल एक बार दिखाया जाता है — API Keys देखें)।
2. API कॉल करें। अपने agents सूचीबद्ध करें:

curl https://cuneiform.chat/api/developer/v1/agents \
  -H "Authorization: Bearer cuk_live_xxxxxxxxxxxxxxxx"

एक सफल प्रतिक्रिया एक कर्सर-पेजिनेटेड पृष्ठ है:

{
  "data": [
    {
      "id": "agt_123",
      "name": "Support Bot",
      "status": "active"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

इस रेफरेंस को कैसे पढ़ें

हर endpoint एक एक-पंक्ति विवरण, एक पैरामीटर तालिका (path, query, header और body), एक उदाहरण curl अनुरोध, और एक उदाहरण प्रतिक्रिया के साथ दस्तावेज़ित है। आवश्यक scope, सफलता स्थिति, और प्रासंगिक त्रुटि श्रेणियाँ हर endpoint के लिए नोट की जाती हैं।

OpenAPI स्पेसिफिकेशन

पूरा अनुबंध एक हाथ से लिखी OpenAPI 3.1 स्पेसिफिकेशन, openapi.yaml के रूप में भी प्रकाशित है, जो इस रेफरेंस के साथ डाउनलोड करने योग्य है। यह सत्य का एकमात्र स्रोत है जिसके विरुद्ध यहाँ के पृष्ठ लिखे गए हैं — हर स्कीमा फ़ील्ड वह है जो API वास्तव में लौटाता है, और कोई आंतरिक फ़ील्ड प्रकट नहीं होता।

पात्रता

डेवलपर REST API Starter और उससे ऊपर उपलब्ध है। Trial organizations keys नहीं बना सकते; एक प्रयास 403 tier_error लौटाता है।