কনভেনশন

এই কনভেনশনগুলো প্রতিটি ডেভেলপার 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-এর মধ্যে কখনো সরানো বা পুনঃব্যবহার করা হয় না।