कन्वेंशन

ये कन्वेंशन हर डेवलपर API endpoint पर लागू होते हैं। इन्हें एक बार पढ़ने से हर endpoint पृष्ठ अपने स्वयं के पैरामीटर और रूपों पर केंद्रित रह सकता है।

हर जगह JSON

अनुरोध और प्रतिक्रिया के बॉडी JSON हैं (Content-Type: application/json), एक अपवाद के साथ: डॉक्यूमेंट अपलोड multipart/form-data का उपयोग करता है (Knowledge डॉक्यूमेंट endpoints देखें)। सभी टाइमस्टैम्प UTC में ISO-8601 स्ट्रिंग हैं, जैसे 2026-06-07T12:34:56Z।

कर्सर पेजिनेशन

लिस्ट endpoints एक कर्सर-पेजिनेटेड पृष्ठ लौटाते हैं, कभी एक ऑफ़सेट/पृष्ठ-संख्या स्कीम नहीं। रैपर हमेशा एक ही रूप का होता है:

{
  "data": [ /* the items on this page */ ],
  "has_more": true,
  "next_cursor": "eyJpZCI6ImFndF8xMjMifQ"
}

दो query पैरामीटर से पेजिंग नियंत्रित करें:

next_cursor को एक अपारदर्शी मान के रूप में मानें — इसे कभी पार्स, निर्मित या संशोधित न करें। हर पृष्ठ पर जाने के लिए, has_more के false होने तक पिछली प्रतिक्रिया के next_cursor से अनुरोध करते रहें:

# First page
curl "https://cuneiform.chat/api/developer/v1/agents?limit=50" \
  -H "Authorization: Bearer cuk_live_xxxxxxxxxxxxxxxx"
 
# Next page
curl "https://cuneiform.chat/api/developer/v1/agents?limit=50&cursor=eyJpZCI6ImFndF8xMjMifQ" \
  -H "Authorization: Bearer cuk_live_xxxxxxxxxxxxxxxx"

एक विकृत कर्सर 400 invalid_request_error (invalid_cursor) लौटाता है।

आइडेमपोटेंट अनुरोध

म्यूटेटिंग POST अनुरोध एक वैकल्पिक Idempotency-Key हेडर स्वीकार करते हैं ताकि एक पुनः प्रयास — एक नेटवर्क त्रुटि या टाइमआउट के बाद — कभी ऑपरेशन को दो बार न करे।

curl -X POST https://cuneiform.chat/api/developer/v1/agents \
  -H "Authorization: Bearer cuk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f1c4b7a-2e3d-4f5a-8b6c-1d2e3f4a5b6c" \
  -d '{ "name": "Support Bot", "configuration": { "model": "gpt-4o-mini", "system_prompt": "You are helpful." } }'

यह कैसे काम करता है:

• हर तार्किक ऑपरेशन के लिए एक अद्वितीय key बनाएँ (एक UUID आदर्श है) और इसे अनुरोध के साथ भेजें।
• 24 घंटे के भीतर समान key ले जाने वाला एक दोहराया गया अनुरोध ऑपरेशन को फिर से चलाने के बजाय मूल संग्रहीत प्रतिक्रिया को फिर से चलाता है।
• keys आपके organization तक सीमित हैं।
• 24 घंटे के बाद key समाप्त हो जाती है; एक समाप्त key वाला अनुरोध एक नए के रूप में माना जाता है।

Idempotency-Key को ब्लॉकिंग agent-क्वेरी पाथ पर सम्मानित किया जाता है, लेकिन स्ट्रीमिंग (stream: true) पाथ पर अनदेखा किया जाता है।

डिफ़ॉल्ट रूप से अस्वीकृति वाली प्रतिक्रियाएँ

प्रतिक्रिया बॉडी केवल हर endpoint पृष्ठ पर दस्तावेज़ित फ़ील्ड उजागर करती हैं। वे कभी आंतरिक पहचानकर्ता, स्टोरेज इंटरनल, LLM प्रोवाइडर/मॉडल स्ट्रिंग, या लागत के आँकड़े शामिल नहीं करतीं। यदि कोई फ़ील्ड दस्तावेज़ित रूप में नहीं है, तो API इसे नहीं लौटाता।

चेंजलॉग

v1 वर्तमान, स्थिर अनुबंध है। परिवर्तन योगात्मक हैं — नए फ़ील्ड और नए endpoints दिखाई दे सकते हैं, लेकिन मौजूदा फ़ील्ड v1 के भीतर कभी हटाए या पुनः उपयोग नहीं किए जाते।