یہ اصل انگریزی دستاویز کا مشینی ترجمہ ہے۔ اس ترجمے اور اصل انگریزی ورژن کے درمیان کسی بھی تضاد کی صورت میں، انگریزی ورژن ہی معتبر تصور ہوگا۔ اصل انگریزی ورژن پڑھیں

---

پبلک API

Caiioo میں ایک REST API شامل ہے جو آپ کو پروگرام کے ذریعے سب کچھ کنٹرول کرنے دیتا ہے: ایجنٹس چلانا، ٹولز کا انتظام کرنا، کاموں کو شیڈول کرنا اور بہت کچھ۔ API اسی مقامی سرور پر موجود ہے جو ڈیسک ٹاپ ایپ اور براؤزر برج کو طاقت دیتا ہے۔

بیس URL: http://localhost:3847/v1

تصدیق (Authentication): تصدیق کے دو طریقے ہیں، دونوں سیٹنگز میں API ٹوگل کے ذریعے کنٹرول ہوتے ہیں:

بیرونی صارفین کے لیے (اسکرپٹس، انٹیگریشنز، curl): Settings > API Access میں ایک API ایکسیس ٹوکن سیٹ کریں، پھر اسے Bearer ٹوکن کے طور پر استعمال کریں:

curl -H \"Authorization: Bearer YOUR_API_TOKEN\" http://localhost:3847/v1/providers

مقامی ایپ کے لیے (خودکار): Caiioo ڈیسک ٹاپ ایپ، براؤزر ایکسٹینشنز، اور موبائل ایپس موجودہ ریلے اتھارٹی ہیڈر (x-relay-auth) کے ذریعے خودکار طور پر تصدیق کرتی ہیں۔ کسی دستی سیٹ اپ کی ضرورت نہیں ہے — ایپ پس منظر میں اسے سنبھالتی ہے۔ ریلے اتھارٹی کی درخواستیں Enable Public API ٹوگل کو نظر انداز کرتی ہیں کیونکہ وہ پہلے سے قابل بھروسہ ہیں؛ صرف بیئرر ٹوکن کی درخواستیں ٹوگل کے ذریعے کنٹرول ہوتی ہیں۔

سیٹ اپ:

1. Caiioo Settings > API Access کھولیں
2. Enable Public API کو آن کریں
3. ایک API ایکسیس ٹوکن سیٹ کریں (اپنی پسند کا کوئی بھی سٹرنگ — اسے پاس ورڈ کی طرح سمجھیں)
4. تمام API درخواستوں میں وہ ٹوکن استعمال کریں

API لوکل ہوسٹ اور پرائیویٹ ریلے کے ذریعے دستیاب ہے۔ موجودہ صورتحال اور سیٹ اپ کی ہدایات کے لیے GET /v1/auth/info (کسی تصدیق کی ضرورت نہیں) چیک کریں۔

ریٹ لمیٹس: ہر /v1/* درخواست فی کلائنٹ IP ریٹ لمیٹڈ ہے — پڑھنے کے لیے فی منٹ 100 GET درخواستیں اور لکھنے کے لیے فی منٹ 30 درخواستیں (POST / PATCH / DELETE) مجموعی طور پر۔ حد سے زیادہ درخواستوں پر 429 ملتا ہے۔ ویب ہک ڈیلیوریز (POST /v1/webhooks/:id) بیئرر تصدیق شدہ نہیں ہیں اور ان حدود کے تابع نہیں ہیں۔

پروفائلز

ایک ہی ڈیوائس میں متعدد صارف پروفائلز ہو سکتے ہیں (مثلاً ذاتی + کام)۔ API بیرونی اسکرپٹس کو دستیاب پروفائلز کا معائنہ کرنے اور دیگر کام کرنے سے پہلے فعال پروفائل کو تبدیل کرنے کی اجازت دیتا ہے۔ پروفائل کی تخلیق، اپ ڈیٹ، اور حذف کو جان بوجھ کر پبلک API کے ذریعے ظاہر نہیں کیا گیا ہے — یہ فلو ایپ کے آن بورڈنگ UI کا حصہ ہیں۔

پروفائلز کی فہرست:

GET /v1/profiles

ہر غیر حذف شدہ پروفائل کے لیے ایک اندراج کے ساتھ { profiles: [...] } واپس کرتا ہے۔ ہر اندراج میں id ، name ، email ، avatarUrl ، tier ، accessibleModes ، license ، organization ، preferences ، onboardingComplete ، createdAt ، lastAccessedAt شامل ہوتے ہیں۔ ٹوکن والے فیلڈز (serviceCredentials, oauthConnections) اور سنک انٹرنلز (vectorClock, lastModifiedBy) کو ہٹا دیا جاتا ہے۔ OAuth کنکشنز کا معائنہ کرنے کے لیے /v1/connectors استعمال کریں۔

فعال پروفائل حاصل کریں:

GET /v1/profiles/active

اس سرور کے ذریعے فی الحال استعمال ہونے والے پروفائل کے لیے { profile } واپس کرتا ہے۔ پروفائل کے دائرہ کار میں آنے والے تمام /v1/* وسائل (تھریڈز، اٹیچ منٹس، سیٹنگز، اسکلز) اسی پر کام کرتے ہیں۔

فعال پروفائل تبدیل کریں:

PUT /v1/profiles/active
Content-Type: application/json

{ "profileId": "user-uuid-from-list" }

نئے فعال پروفائل کے لیے { profile } واپس کرتا ہے۔ اگر ID کوئی معلوم پروفائل نہیں ہے تو 404 واپس کرتا ہے۔

Providers & Models

دریافت کریں کہ کون سے LLM فراہم کنندگان (providers) کنفیگر شدہ ہیں اور کون سے ماڈلز دستیاب ہیں۔

فراہم کنندگان کی فہرست:

GET /v1/providers

تمام تعاون یافتہ فراہم کنندگان کی اقسام واپس کرتا ہے۔ فی الحال: anthropic ، openai ، google ، openrouter ، ollama ، poe ، mlx ، perplexity ، baseten ، cloudflare۔ ہر اندراج میں type ، displayName ، icon ، requiresApiKey ، hasApiKey ، اور ایک capabilities آبجیکٹ شامل ہوتا ہے جس میں نیچے دیے گئے فلیگز ہوتے ہیں۔

Capability flag	مطلب
supportsVision	فراہم کنندہ تصویری ان پٹ قبول کر سکتا ہے
supportsPdfFile	فراہم کنندہ مقامی طور پر خام PDF فائل مواد کے بلاکس قبول کر سکتا ہے
supportsToolCalling	فراہم کنندہ فنکشن/ٹول کالنگ کو سپورٹ کرتا ہے
supportsStreaming	فراہم کنندہ ٹوکنز کو بتدریج اسٹریم کرتا ہے
supportsExtendedThinking	فراہم کنندہ استدلال/سوچنے کا بجٹ (reasoning/thinking budget) ظاہر کرتا ہے
supportsPromptCaching	فراہم کنندہ prompt-cache ہدایات کو سپورٹ کرتا ہے
nativeReasoningBlocks	فراہم کنندہ سوچ کو مقامی میسج بلاکس کے طور پر خارج کرتا ہے (بمقابلہ ٹیکسٹ)
requiresThoughtSignature	فراہم کنندہ کو دستخط شدہ سوچ کے ٹوکنز واپس بھیجنے کی ضرورت ہوتی ہے

Capability flags ہر فراہم کنندہ کلاس کے readonly capabilities فیلڈ کی عکاسی کرتے ہیں (دیکھیں src/shared/providers/*-provider.ts) اور ایک drift sentinel ٹیسٹ کے ذریعے ان کی تصدیق کی جاتی ہے — میٹرکس کو ہارڈ کوڈ کرنے کے بجائے رن ٹائم پر اس اینڈ پوائنٹ کو کال کریں۔

BYOK فراہم کنندگان کے لیے نوٹس:

• perplexity Sonar ماڈلز کی ایک منتخب فہرست فراہم کرتا ہے (Perplexity کا کوئی عوامی /models اینڈ پوائنٹ نہیں ہے)۔
• cloudflare (AI Gateway) ایک BYOK + ملٹی وینڈر سروس ہے؛ ماڈل کی فہرست آپ کے گیٹ وے کنفیگریشن سے طے ہوتی ہے اور /v1/providers/cloudflare/models کے ذریعے خالی ایرے (empty array) کے طور پر واپس کی جاتی ہے۔ اپنا گیٹ وے کیٹلاگ استعمال کریں۔

کسی فراہم کنندہ کے ماڈلز کی فہرست:

GET /v1/providers/openrouter/models

اس فراہم کنندہ کے لیے ماڈل کیٹلاگ واپس کرتا ہے۔ ہر ماڈل میں id ، displayName ، اور جہاں دستیاب ہو وہاں contextLength شامل ہوتا ہے۔ اگر فراہم کنندہ کے پاس API کلید نہ ہو یا اس کا اپ اسٹریم کیٹلاگ ناقابل رسائی ہو تو 503 واپس کرتا ہے۔

تمام فراہم کنندگان کا مشترکہ کیٹلاگ:

GET /v1/models

ہر کنفیگر شدہ فراہم کنندہ کے ماڈلز کو ایک فہرست میں ضم کرتا ہے۔ جن فراہم کنندگان کے پاس API کلید نہیں ہوتی انہیں چھوڑ دیا جاتا ہے اور warnings میں درج کیا جاتا ہے۔

ایجنٹس

ایجنٹس Caiioo کا مرکز ہیں۔ ہر ایجنٹ ایک Mode ہے — ایک کنفیگر کردہ شخصیت جس کا اپنا سسٹم پرامپٹ، ٹولز، متغیرات اور اسکلز ہوتے ہیں۔

تمام ایجنٹس کی فہرست:

GET /v1/agents

یہ بلٹ ان ایجنٹس (Shopping, Workplace, General) اور آپ کے بنائے ہوئے کسی بھی کسٹم ایجنٹس کو واپس کرتا ہے۔ ہر ایک پر source: \"builtin\" یا source: \"custom\" کا ٹیگ ہوتا ہے۔

کسٹم ایجنٹ بنائیں:

POST /v1/agents
Content-Type: application/json

{
  \"id\": \"my-research-agent\",
  \"branding\": {
    \"name\": \"Research Agent\",
    \"description\": \"Searches the web and summarizes findings\"
  },
  \"defaultSettings\": {
    \"systemPrompt\": \"You are a research assistant. Always cite sources.\",
    \"enabledTools\": { \"web_browsing\": true, \"search_tools\": true }
  },
  \"settingLevels\": {}
}

تخلیق کردہ ایجنٹ کے ساتھ 201 واپس کرتا ہے۔ سنک کے لیے ایک ویکٹر کلاک خود بخود منسلک ہو جاتی ہے۔

ایجنٹ کو اپ ڈیٹ کریں:

PATCH /v1/agents/my-research-agent
Content-Type: application/json

{ \"branding\": { \"name\": \"Research Agent\", \"description\": \"Updated description\" } }

پیچ کو موجودہ ایجنٹ میں ضم کرتا ہے اور ویکٹر کلاک کو بڑھاتا ہے۔ بلٹ ان ایجنٹس 403 واپس کرتے ہیں — وہ صرف پڑھنے کے لیے ہیں۔

ایجنٹ کو حذف کریں:

DELETE /v1/agents/my-research-agent

ٹومب اسٹون (tombstone) کے ذریعے سافٹ ڈیلیٹ کرتا ہے (آلات پر سنک ہوتا ہے)۔ 204 واپس کرتا ہے۔

Agents چلانا

یہ مرکزی مرحلہ ہے — کسی پیغام پر کارروائی کرنے کے لیے ایک ایجنٹ کو کال کریں۔

Request body — معاونت یافتہ فیلڈز

فیلڈ	ضروری	تفصیل
agentId	ہاں	بلٹ ان موڈ ID (مثلاً general) یا ایک کسٹم ایجنٹ ID
input.message	ہاں	صارف کے پیغام کا متن
input.attachments	نہیں	اٹیچمنٹ IDs کی لسٹ (جو پہلے ہی /v1/attachments کے ذریعے اپ لوڈ ہو چکی ہوں) تاکہ اس باری کے ساتھ منسلک کی جا سکیں
input.variables	نہیں	فی رن (Per-run) ویری ایبل اوور رائیڈز جو ایجنٹ کے ویری ایبل ریزولور میں ضم ہو جاتے ہیں
input.tabContext	نہیں	فری فارم اسٹرنگ جو پیج کانٹیکسٹ کے طور پر شامل کی جاتی ہے (براؤزر برج کے ذریعے استعمال ہوتی ہے)
input.messageId	نہیں	کلائنٹ کی فراہم کردہ میسج ID — دوبارہ کوشش (retry) کی صورت میں ڈپلیکیشن ختم کرنے کے لیے مفید ہے
threadId	نہیں	جاری رکھنے کے لیے موجودہ تھریڈ۔ اگر اسے چھوڑ دیا جائے تو ایک نیا تھریڈ بنتا ہے اور واپس کیا جاتا ہے
mode	نہیں	"sync" یا "async"۔ ڈیفالٹ "async" ہے

Synchronous Mode

مکمل جواب کا انتظار کریں:

POST /v1/runs
Content-Type: application/json

{
  "agentId": "general",
  "input": { "message": "What's the weather in Paris today?" },
  "mode": "sync"
}

ایجنٹ کے فارغ ہونے کے بعد { content, usage, status: "completed" } کے ساتھ 200 واپس کرتا ہے۔ اگر ایجنٹ میں کوئی خرابی آتی ہے تو { error, status: "error" } کے ساتھ 500 واپس کرتا ہے۔ اگر کوئی ٹرمینل ایونٹ موصول نہ ہو تو Sync رنز 5 منٹ کے بعد status: "error" کے ساتھ ٹائم آؤٹ ہو جاتے ہیں — ایسی کسی بھی چیز کے لیے جو زیادہ وقت لے سکتی ہو، async + SSE استعمال کریں۔

Asynchronous Mode

فائر اینڈ فارگیٹ (Fire and forget) — طویل کاموں کے لیے مفید:

POST /v1/runs
Content-Type: application/json

{
  "agentId": "my-research-agent",
  "input": { "message": "Write a 2000-word analysis of renewable energy trends" },
  "mode": "async"
}

فوری طور پر { runId, threadId, status: "running" } کے ساتھ 202 واپس کرتا ہے۔

اسٹیٹس چیک کریں (Poll for status):

GET /v1/runs/{runId}

یہ { run: { runId, threadId, agentId, status, createdAt, content?, usage?, error? } } واپس کرتا ہے۔ اسٹیٹس running، completed، error یا cancelled میں سے ایک ہوتا ہے۔

ریئل ٹائم میں ایونٹس اسٹریم کریں (SSE):

GET /v1/runs/{runId}/events

یہ ایک text/event-stream واپس کرتا ہے جس میں ایجنٹ کا ہر ایونٹ وقوع پذیر ہوتے ہی شامل ہوتا ہے: GENERATION_STARTED، STREAMING_CONTENT ، ٹول کالز، سب ایجنٹ کی سرگرمی، اور ٹرمینل ایونٹ (GENERATION_COMPLETE ، GENERATION_ERROR ، یا GENERATION_CANCELLED)۔

ٹرمینل ایونٹ کے بعد، سرور ایک آخری SSE فریم جاری کرتا ہے جس میں event: terminal اور خالی ڈیٹا پے لوڈ ہوتا ہے جو اسٹریم کے واضح خاتمے کی علامت ہے، پھر کنکشن بند کر دیتا ہے۔ کلائنٹس کو اس فریم کی وصولی (یا کنکشن بند ہونے) کو پڑھنا بند کرنے کے سگنل کے طور پر لینا چاہیے۔

اگر آپ رن ختم ہونے کے بعد سبسکرائب کرتے ہیں، تو سرور RUN_SNAPSHOT ٹائپ کا ایک فریم ری پلے کرتا ہے جس میں مکمل فائنل record ہوتا ہے، اس کے بعد event: terminal سگنل آتا ہے، اور پھر کنکشن بند ہو جاتا ہے۔

رن منسوخ کریں:

POST /v1/runs/{runId}/cancel

یہ { run: { ..., status: "cancelled" } } واپس کرتا ہے۔

Threads

Threads گفتگوئیں ہیں۔ ہر ایجنٹ رن ایک thread کے اندر ہوتا ہے، اور threads سیشنز کے دوران برقرار رہتے ہیں۔ API آپ کو پروگرام کے ذریعے threads کی فہرست دیکھنے، پڑھنے، تخلیق کرنے اور ان کا انتظام کرنے کی اجازت دیتا ہے۔

تمام threads کی فہرست (صرف میٹا ڈیٹا):

GET /v1/threads

موجودہ پروفائل کے لیے { threads: [...] } واپس کرتا ہے جس میں سے messages کو ہٹا دیا جاتا ہے (جب آپ کو ان کی ضرورت ہو تو ڈیٹیل اینڈ پوائنٹ استعمال کریں)۔ دیگر تمام فیلڈز محفوظ رہتے ہیں — id، title، createdAt، updatedAt، modeId، archived ، استعمال کے اعداد و شمار، بشمول subAgentHistories، anonymizerSnapshot، threadToolApprovals، threadVariables، threadToolOverrides، messagingBinding اور سیٹ ہونے کی صورت میں scheduledTaskId۔ (زیادہ تفصیلی پے لوڈ صرف API کے لیے مخصوص ہے — WebSocket سائڈبار براڈکاسٹ ٹرانسپورٹ کی حدود کے اندر رہنے کے لیے ایک مختصر ڈیٹا استعمال کرتا ہے۔)

مکمل پیغامات کے ساتھ ایک thread حاصل کریں:

GET /v1/threads/{id}

مکمل thread بشمول اس کی messages لسٹ واپس کرتا ہے — ہر صارف کا پیغام، اسسٹنٹ کا جواب، ٹول کال، اور ٹول کا نتیجہ۔

صرف پیغامات حاصل کریں:

GET /v1/threads/{id}/messages

صرف messages لسٹ واپس کرتا ہے — جب آپ کو صرف گفتگو کی ضرورت ہو تو یہ مکمل thread آبجیکٹ کے مقابلے میں ہلکا ہوتا ہے۔

ایک thread تخلیق کریں:

POST /v1/threads
Content-Type: application/json

{ "title": "Research project", "modeId": "general" }

{ thread } کے ساتھ 201 واپس کرتا ہے۔ نیا thread فوری طور پر سائڈبار میں ظاہر ہو جاتا ہے (بذریعہ WebSocket براڈکاسٹ)۔ API تخلیق پر کبھی بھی ایپ کے فعال thread کو تبدیل نہیں کرتا — اگر آپ وہ چاہتے ہیں تو الگ سے PUT /v1/threads/active کال کریں۔

ایک thread کو اپ ڈیٹ کریں:

PATCH /v1/threads/{id}
Content-Type: application/json

{ "title": "Renamed project", "archived": true }

قابلِ ترمیم فیلڈز: title، modeId، archived، lastUsedModel۔ تبدیلیاں حقیقی وقت میں سائڈبار پر براڈکاسٹ ہوتی ہیں۔

ایک thread کو حذف کریں:

DELETE /v1/threads/{id}

thread کو سافٹ ڈیلیٹ (سنک کے لیے ٹومب اسٹون) کرتا ہے۔ 204 واپس کرتا ہے۔ حذف شدہ threads ردی کی ٹوکری (trash) میں چلے جاتے ہیں اور ردی خالی ہونے تک بحال کیے جا سکتے ہیں۔

فعال thread:

GET /v1/threads/active            # Returns { threadId }
PUT /v1/threads/active            # Body: { "threadId": "..." }

ردی (Trash) کا انتظام:

GET /v1/threads/trash/count       # Returns { count }
POST /v1/threads/trash/empty      # Returns { deletedCount, protectedCount }

محفوظ شدہ threads (جو ڈیٹا برقرار رکھنے کے ٹوگل کے ذریعے رکھے گئے ہیں) ردی خالی کرنے کے عمل سے خارج ہوتے ہیں۔

API کے ذریعے گفتگو جاری رکھنا: کسی موجودہ thread میں فالو اپ پیغام بھیجنے کے لیے، thread کی ID کے ساتھ POST /v1/runs استعمال کریں:

POST /v1/runs
Content-Type: application/json

{
  "agentId": "general",
  "threadId": "existing-thread-id",
  "input": { "message": "Follow up on that last point" },
  "mode": "sync"
}

ایجنٹ thread سے گفتگو کی مکمل تاریخ دیکھ سکتا ہے۔

منسلکات (Attachments)

منسلکات تھریڈز سے منسلک فائلیں ہیں — اسکرین شاٹس، PDFs، دستاویزات، اپ لوڈ کردہ تصاویر، تخلیق کردہ نمونے۔ API آپ کو ان کی فہرست بنانے، اپ لوڈ کرنے، ڈاؤن لوڈ کرنے اور ان کا انتظام کرنے کی اجازت دیتا ہے۔

تمام منسلکات کی فہرست (صرف میٹا ڈیٹا):

GET /v1/attachments

موجودہ پروفائل کے لیے اٹیچمنٹ میٹا ڈیٹا واپس کرتا ہے۔ بھاری فیلڈز (dataUrl ، extractedContent ، extractedImages) ہٹا دی جاتی ہیں — ان کے لیے ڈیٹیل یا کنٹینٹ اینڈ پوائنٹس استعمال کریں۔

کسی مخصوص تھریڈ کے لیے منسلکات کی فہرست:

GET /v1/threads/{threadId}/attachments

اٹیچمنٹ میٹا ڈیٹا حاصل کریں:

GET /v1/attachments/{id}

مکمل میٹا ڈیٹا واپس کرتا ہے بشمول extractedContent (OCR ٹیکسٹ، پارس شدہ مارک ڈاؤن)، contentType ، fileName ، size ، اور ایک hasContent جھنڈا۔ خام بائنری شامل نہیں ہے — اس کے لیے /content اینڈ پوائنٹ استعمال کریں۔

اٹیچمنٹ بائنری ڈاؤن لوڈ کریں:

GET /v1/attachments/{id}/content

درست Content-Type اور Content-Disposition ہیڈرز کے ساتھ خام فائل واپس کرتا ہے۔ اسے فائل میں پائپ کریں:

curl -o output.pdf \
  -H "Authorization: Bearer $API_TOKEN" \
  http://localhost:3847/v1/attachments/{id}/content

اٹیچمنٹ اپ لوڈ کریں:

POST /v1/attachments
Content-Type: application/json

{
  "threadId": "thread-id",
  "type": "user_upload",
  "contentType": "application/pdf",
  "fileName": "report.pdf",
  "description": "Quarterly report",
  "dataUrl": "data:application/pdf;base64,JVBERi0xLjQ..."
}

dataUrl ایک base64-انکوڈ شدہ ڈیٹا URL ہے۔ نئی اٹیچمنٹ آئی ڈی کے ساتھ 201 واپس کرتا ہے۔ اٹیچمنٹ مخصوص تھریڈ سے منسلک ہو جاتی ہے۔

اٹیچمنٹ میٹا ڈیٹا اپ ڈیٹ کریں:

PATCH /v1/attachments/{id}
Content-Type: application/json

{ "description": "Updated description", "fileName": "new-name.pdf" }

اٹیچمنٹ حذف کریں:

DELETE /v1/attachments/{id}

ٹومب اسٹون کے ذریعے سافٹ ڈیلیٹ کرتا ہے۔ 204 واپس کرتا ہے۔

MCP Servers

اپنے MCP (Model Context Protocol) سرور کنکشنز کا انتظام کریں — وہ سرورز جو ایجنٹس کو بیرونی ٹولز اور ڈیٹا کے ذرائع تک رسائی فراہم کرتے ہیں۔

کنفیگر شدہ سرورز کی فہرست حاصل کریں:

GET /v1/mcp-servers

موجودہ پروفائل کے لیے تمام MCP سرور کنفیگریشنز واپس کرتا ہے۔ حساس فیلڈز (authToken ، env ، credentialId) جواب سے خارج کر دی جاتی ہیں۔

کسی سرور کی کنفیگریشن حاصل کریں:

GET /v1/mcp-servers/{id}

نیا MCP سرور شامل کریں:

POST /v1/mcp-servers
Content-Type: application/json

{
  "id": "my-server",
  "name": "My MCP Server",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"],
  "serverType": "local"
}

ریموٹ HTTP سرورز کے لیے، "command" کے بجائے "url" استعمال کریں:

{
  "id": "remote-server",
  "name": "Remote API",
  "url": "https://my-mcp-server.example.com/sse",
  "serverType": "remote"
}

POST پر قبول شدہ اختیاری فیلڈز: command ، args ، env ، url ، description ، transportType ، authType ، authToken ، authHeader ، headers ، specType ، specPath ، timeoutMs ، credentialId ، oauthConnectionId ، approval۔ سرور کے زیرِ انتظام فیلڈز (customOAuth ، hubPackageId ، profileId ، connectorId ، teamPublished ، teamOrgId ، vectorClock ، ...) API کے ذریعے سیٹ نہیں کیے جا سکتے۔

سرور کو اپ ڈیٹ کریں:

PATCH /v1/mcp-servers/{id}
Content-Type: application/json

{ "name": "Renamed Server", "args": ["-y", "@mcp/server-v2"] }

پیچ (Patch) کے قابل فیلڈز POST کی اجازت یافتہ فہرست کے مطابق ہیں (بشمول credentialId اور oauthConnectionId — جو کہ ڈیلیٹ اور دوبارہ بنائے بغیر OAuth کنکشن کو تبدیل کرنے کے لیے مفید ہیں)۔ سرور کے زیرِ انتظام فیلڈز صرف پڑھنے کے لیے (read-only) رہیں گے۔

سرور کو فعال/غیر فعال کریں:

POST /v1/mcp-servers/{id}/toggle
Content-Type: application/json

{ "enabled": false }

سرور کو حذف کریں:

DELETE /v1/mcp-servers/{id}

پراسیس مینجمنٹ (Process Management)

مقامی (stdio) MCP سرورز کے لیے، آپ سرور پراسیس کا براہ راست انتظام کر سکتے ہیں۔

جاری پراسیسز کی فہرست حاصل کریں:

GET /v1/mcp-servers/processes

جاری سرور پراسیسز کو pid ، startedAt ، اور running اسٹیٹس کے ساتھ واپس کرتا ہے۔

سرور شروع کریں:

POST /v1/mcp-servers/{id}/start

سرور کنفیگریشن سے command/args/env پڑھتا ہے اور پراسیس شروع کرتا ہے۔ پراسیس کی صورتحال واپس کرتا ہے۔

سرور روکیں:

POST /v1/mcp-servers/{id}/stop

سرور پراسیس کو باقاعدگی سے بند کرتا ہے (SIGTERM کے ساتھ، اور ضرورت پڑنے پر SIGKILL کا استعمال کرتا ہے)۔

براہ راست JSON-RPC میتھڈ کال کریں:

POST /v1/mcp-servers/{id}/call
Content-Type: application/json

{ "method": "tools/list", "params": {} }

سرور کو خام JSON-RPC 2.0 درخواست بھیجتا ہے اور نتیجہ واپس کرتا ہے۔ یہ ڈیبگنگ یا ان میتھڈز کو کال کرنے کے لیے مفید ہے جو ٹولز API کے ذریعے ظاہر نہیں کیے گئے ہیں۔

Tools & Toolkits

ان ٹولز کو براؤز اور انووک (invoke) کریں جو ایجنٹس استعمال کرتے ہیں — ویب براؤزنگ، سرچ، کیلنڈر، Gmail، Slate، اور بہت کچھ۔

ٹول کٹس کی فہرست (گروپ شدہ):

GET /v1/toolkits

زمرہ جات (Productivity، Search، Utilities، وغیرہ) کے لحاظ سے گروپ کردہ ایمبیڈڈ ٹولز اور کسی بھی منسلک MCP سرورز کو الگ ٹول کٹس کے طور پر واپس کرتا ہے، جن میں سے ہر ایک کے ایکشنز درج ہوتے ہیں۔

تمام ٹولز کی فہرست (فلیٹ):

GET /v1/tools
GET /v1/tools?source=embedded   # صرف بلٹ ان ٹولز
GET /v1/tools?source=mcp        # صرف MCP سرور ٹولز

ان پٹ اسکیما کے ساتھ ٹول کی تفصیلات حاصل کریں:

GET /v1/tools/calculator

واپس کرتا ہے { tool: { name, displayName, description, source, category, inputSchema, actions?, requiredTier?, requiredRuntimes?, riskTier?, riskExplanation?, requiresApproval? } }۔

فیلڈ	مطلب
inputSchema	ٹول کے ان پٹ کے لیے JSON Schema — انووک کرنے سے پہلے تصدیق کریں
actions	اختیاری ذیلی ایکشنز (مثلاً Slate read/write)؛ ہر ایک کی id، displayName، description اور اختیاری requiredTier ہوتی ہے
requiredTier	صارف کا کم از کم ٹائر (اگر درج نہ ہو تو free)۔ Public-API انووکیشن free سے اوپر کی کسی بھی چیز کو مسترد کر دیتی ہے
requiredRuntimes	وہ پلیٹ فارمز جہاں یہ ٹول دستیاب ہے (macos، ios وغیرہ)؛ اگر درج نہ ہو تو ⇒ ہر جگہ
riskTier	رضامندی کا خطرہ: low (ڈیفالٹ)، medium، high
riskExplanation	riskTier کے بلند ہونے کی انسانی فہم کے مطابق وجہ
requiresApproval	true جب ٹول کو ہر کال پر صارف کی منظوری کی ضرورت ہو — public-API انووکیشن ان کو مسترد کر دیتی ہے

کسی ٹول کو براہ راست انووک کریں:

POST /v1/tools/calculator/invoke
Content-Type: application/json

{ "input": { "expression": "sqrt(144) + 3^2" }, "threadId": "optional-thread-id" }

واپس کرتا ہے { result }۔ ان پٹ کی تصدیق ٹول کے اسکیما کے مطابق کی جاتی ہے — غلط ان پٹ تفصیلات کے ساتھ 422 واپس کرتا ہے۔ اگر ٹول کو تھریڈ کے دائرہ کار کے سیاق و سباق (مثلاً اٹیچمنٹ کی تلاش) کی ضرورت ہو تو ایک اختیاری threadId پاس کریں۔

گیٹنگ (Gating) — پبلک API کن چیزوں کو مسترد کرتا ہے:

• ٹائر-گیٹڈ ٹولز (metadata.requiredTier !== 'free') → 403۔ ایجنٹ لوپ صارف کے سیشن کے مطابق ٹائر چیک کرتا ہے؛ پبلک API میں کوئی ٹائر سیاق و سباق نہیں ہوتا، اس لیے محتاط پالیسی یہ ہے کہ اسے مسترد کر دیا جائے۔ اس کے بجائے صحیح ٹائر والے ایجنٹ کے ساتھ POST /v1/runs استعمال کریں۔
• منظوری کے حامل ٹولز (metadata.approval.requiresApproval === true) → 403۔ پوچھنے کے لیے لوپ میں کوئی انسان موجود نہیں ہے۔ POST /v1/runs کے ذریعے انووک کریں (جو صارف کو پرامپٹ دکھاتا ہے) یا بائی پاس کرنے کے لیے ایپ میں ٹول اپروول موڈ کو approve_all پر سیٹ کریں۔
• ریموٹ MCP ٹولز → 501 اس رہنمائی کے ساتھ کہ /v1/runs استعمال کریں (انہیں ایجنٹ سب پروسیس ٹرانسپورٹ کی ضرورت ہوتی ہے)۔

ویژن اور امیج استعمال کرنے والے ٹولز: پہلے POST /v1/attachments کے ذریعے اپ لوڈ کریں، پھر واپس آنے والی اٹیچمنٹ ID کو input کے اندر پاس کریں (مثلاً { "input": { "attachment_id": "att_abc", "prompt": "What is in this image?" } })۔ ٹول threadId کے ذریعے اسٹوریج سے بائنری پڑھتا ہے؛ آپ بائٹس کو ان لائن پاس نہیں کرتے۔

کنیکٹرز (Connectors)

OAuth انٹیگریشنز کا انتظام کریں — Google، Microsoft، GitHub، Notion، Slack اور مزید۔

دستیاب انٹیگریشنز دیکھیں:

GET /v1/connectors/catalog

تمام رجسٹرڈ OAuth فراہم کنندگان کو ان کے نام، زمرہ اور ڈیفالٹ اسکوپس کے ساتھ واپس کرتا ہے۔

اپنے منسلک اکاؤنٹس کی فہرست دیکھیں:

GET /v1/connectors

موجودہ پروفائل کے لیے فعال کنکشنز واپس کرتا ہے۔ ٹوکن کبھی بھی ظاہر نہیں کیے جاتے — صرف میٹا ڈیٹا (فراہم کنندہ، ای میل، اسٹیٹس، اسکوپس، ٹائم اسٹیمپس)۔

ایک کنکشن حاصل کریں:

GET /v1/connectors/{id}

ایک کنکشن کا میٹا ڈیٹا واپس کرتا ہے۔ ٹوکن کبھی ظاہر نہیں کیے جاتے۔

کنکشن کی صحت چیک کریں:

POST /v1/connectors/{id}/test

{ health: { status, isTokenExpired, canRefresh } } واپس کرتا ہے۔

کنکشن ختم کریں:

DELETE /v1/connectors/{id}

نئے کنکشن بنانے کے لیے ایپ UI یا /auth/* روٹس کے ذریعے انٹرایکٹو OAuth فلو کی ضرورت ہوتی ہے۔

ٹریگرز (Triggers)

ایجنٹس کو خودکار طور پر چلانے کے لیے شیڈول کریں — روزانہ کی بریفنگ، ہفتہ وار رپورٹس، وقفے وقفے سے نگرانی۔

ہر ٹریگر میں ایک kind امتیاز کنندہ ہوتا ہے: schedule (ڈیفالٹ — گھڑی کے مطابق چلتا ہے)، webhook (تب چلتا ہے جب کوئی بیرونی سروس ویب ہک پاتھ پر POST کرتی ہے)، یا messaging (منسلک میسجنگ اڈاپٹر سے چلتا ہے — مثلاً چینل فلٹر سے مطابقت رکھنے والے ان باؤنڈ Slack/Discord پیغامات)۔

ٹریگرز کی فہرست:

GET /v1/triggers

یہ { triggers: [...] } واپس کرتا ہے۔ ہر اندراج میں اس کی kind (قسم)، شیڈول، اور قسم کے لحاظ سے مخصوص فیلڈز شامل ہوتے ہیں (مثلاً ویب ہک ٹریگرز کے لیے webhookSecret/webhookPath ، میسجنگ ٹریگرز کے لیے messagingAdapterId/messagingChannelFilter)۔

ایک واحد ٹریگر حاصل کریں:

GET /v1/triggers/{id}

ایک شیڈول شدہ ٹریگر بنائیں:

POST /v1/triggers
Content-Type: application/json

{
  "name": "Morning Briefing",
  "prompt": "میرے نہ پڑھے گئے ای میلز اور آج کے کیلنڈر کا خلاصہ کریں",
  "modeId": "general",
  "schedule": { "type": "daily", "time": "08:00" }
}

تعاون یافتہ شیڈول کی اقسام:

• { "type": "interval", "minutes": 60 } — ہر N منٹ بعد (کم از کم 15، زیادہ سے زیادہ 1440)
• { "type": "daily", "time": "09:00" } — روزانہ ایک مخصوص وقت پر
• { "type": "weekly", "day": "mon", "time": "09:00" } — ہفتہ وار
• { "type": "weekdays", "time": "08:30" } — پیر سے جمعہ تک
• { "type": "daysOfWeek", "days": ["mon", "wed", "fri"], "time": "10:00" } — مخصوص دن
• { "type": "monthly", "dayOfMonth": 1, "time": "09:00" } — ماہانہ
• { "type": "manual" } — صرف تب جب API کے ذریعے چلایا جائے

ٹریگر کو دستی طور پر چلائیں:

POST /v1/triggers/{id}/fire

نتیجے میں آنے والے رن کے لیے threadId کے ساتھ 202 واپس کرتا ہے۔

اپ ڈیٹ یا ڈیلیٹ کریں:

PATCH /v1/triggers/{id}
DELETE /v1/triggers/{id}

ویب ہکس (Webhooks)

ویب ہک ٹریگرز بیرونی سروسز (CI/CD، مانیٹرنگ، فارم بلڈرز) کو HTTP کے ذریعے ایجنٹ رن شروع کرنے کی اجازت دیتے ہیں۔

ویب ہک ٹریگر بنائیں:

POST /v1/triggers
Content-Type: application/json

{
  "name": "Deploy hook",
  "prompt": "ایک ڈیپلائے ہوا ہے: {{webhook.body}}",
  "modeId": "general",
  "kind": "webhook"
}

webhookSecret اور webhookPath کے ساتھ 201 واپس کرتا ہے۔ سیکریٹ کو محفوظ رکھیں — پے لوڈز پر دستخط کرنے کے لیے آپ کو اس کی ضرورت ہوگی۔

ویب ہک بھیجیں:

# خام درخواست کی باڈی کا HMAC-SHA256 کمپیوٹ کریں
SIGNATURE=$(echo -n '{"repo":"my-app","branch":"main"}' | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | awk '{print $2}')

POST /v1/webhooks/{triggerId}
Content-Type: application/json
X-Webhook-Signature: $SIGNATURE

{"repo": "my-app", "branch": "main"}

ویب ہک اینڈ پوائنٹ کو بیئرر اتھارٹی (bearer auth) کی ضرورت نہیں ہے — یہ اس کے بجائے HMAC تصدیق کا استعمال کرتا ہے۔ ڈسپیچ شدہ رن کے threadId کے ساتھ 202 واپس کرتا ہے۔ ٹریگر پرامپٹ میں موجود {{webhook.body}} پلیس ہولڈر کو خام درخواست کی باڈی سے بدل دیا جاتا ہے۔

میسجنگ ٹریگرز

میسجنگ ٹریگرز تب چلتے ہیں جب کوئی منسلک میسجنگ اڈاپٹر (مثلاً کمیونٹی ہب کے ذریعے انسٹال کردہ Slack یا Discord انٹیگریشن) ٹریگر کے فلٹر سے مطابقت رکھنے والا ان باؤنڈ پیغام وصول کرتا ہے۔ kind: "messaging" کے ساتھ بنائیں:

POST /v1/triggers
Content-Type: application/json

{
  "name": "Mention responder",
  "prompt": "اس کا مددگار جواب دیں: {{message.text}}",
  "modeId": "general",
  "kind": "messaging",
  "messagingAdapterId": "slack-team-acme",
  "messagingChannelFilter": "#support"
}

اڈاپٹر مطابقت رکھنے والے ایونٹس کو ٹریگر میں بھیجنے کا ذمہ دار ہے؛ messagingChannelFilter اڈاپٹر کے لحاظ سے مخصوص ہوتا ہے۔

حسب ضرورت فنکشنز (Custom Functions)

اپنے ٹولز بنائیں جنہیں ایجنٹس کال کر سکیں۔ فنکشنز JavaScript یا Python میں لکھے جاتے ہیں اور ایک سینڈ باکس میں چلتے ہیں۔

فنکشنز کی فہرست:

GET /v1/functions

فنکشن بنائیں:

POST /v1/functions
Content-Type: application/json

{
  "name": "calculate_bmi",
  "description": "Calculate Body Mass Index from height and weight",
  "language": "javascript",
  "source": "return { bmi: (input.weightKg / (input.heightM * input.heightM)).toFixed(1) };",
  "inputSchema": {
    "type": "object",
    "properties": {
      "weightKg": { "type": "number" },
      "heightM": { "type": "number" }
    },
    "required": ["weightKg", "heightM"]
  }
}

JavaScript فنکشنز input وصول کرتے ہیں اور انہیں نتیجہ واپس کرنا چاہیے۔ Python فنکشنز ایک result متغیر سیٹ کرتے ہیں:

# Python مثال
result = {"bmi": round(input["weightKg"] / (input["heightM"] ** 2), 1)}

فنکشن کو براہ راست چلائیں:

POST /v1/functions/{id}/execute
Content-Type: application/json

{ "input": { "weightKg": 75, "heightM": 1.80 } }

سیکیورٹی: JavaScript نوڈ کے vm سینڈ باکس میں چلتی ہے (فائل سسٹم یا نیٹ ورک تک رسائی نہیں، 10 سیکنڈ کا ٹائم آؤٹ)۔ Python ایک سب پروسیس کے طور پر چلتی ہے جس کا ٹائم آؤٹ 30 سیکنڈ ہے۔ دونوں چلنے سے پہلے ان پٹ کی تصدیق کرتے ہیں۔

اپ ڈیٹ یا حذف کریں:

PATCH /v1/functions/{id}
DELETE /v1/functions/{id}

مہارتیں (Skills)

مہارتیں محفوظ کردہ پرامپٹس ہیں جن کا ایجنٹس حوالہ دے سکتے ہیں اور خالی گفتگو کے منظر سے فوری شروع کر سکتے ہیں۔ ہب سے انسٹال کردہ مہارتیں (جو پیکیج انسٹال کے ذریعے مینیج ہوتی ہیں) یہاں شامل نہیں ہیں — صرف صارف کی تخلیق کردہ مہارتیں درج اور قابل ترمیم ہیں۔

مہارتوں کی فہرست:

GET /v1/skills

فعال پروفائل کے لیے صارف کی تخلیق کردہ مہارتوں کا { skills: [...] } واپس کرتا ہے۔ ٹومب اسٹونڈ، ہب اوورلے، اور سنک شیڈو مہارتوں کو فلٹر کر دیا جاتا ہے۔

ایک مہارت حاصل کریں:

GET /v1/skills/{id}

مہارت تخلیق کریں:

POST /v1/skills
Content-Type: application/json

{
  "prompt": "صفحے کا 3 اہم نکات میں خلاصہ کریں۔",
  "tags": ["utility", "summarize"],
  "isFavorite": true,
  "modes": ["general"],
  "displayName": "Quick Summary",
  "description": "فعال صفحے کا تین نکات پر مشتمل خلاصہ"
}

صرف prompt ضروری ہے۔ modes (اختیاری) مہارت کو مخصوص ایجنٹ IDs تک محدود کرتا ہے؛ تمام موڈز کے لیے اسے چھوڑ دیں۔ نئے اسکل کے ساتھ 201 واپس کرتا ہے (بشمول سرور کی طرف سے تفویض کردہ id, createdAt, updatedAt)۔

مہارت کو اپ ڈیٹ کریں:

PATCH /v1/skills/{id}
Content-Type: application/json

{ "prompt": "Updated prompt", "isFavorite": false }

قابل ترمیم فیلڈز: prompt, tags, modes, displayName, description, isFavorite۔ ہب اوورلے اسکل کو پیچ کرنے کی کوشش پر 404 واپس آتا ہے۔

مہارت حذف کریں:

DELETE /v1/skills/{id}

ٹومب اسٹون کے ذریعے سافٹ ڈیلیٹ کرتا ہے۔ 204 واپس کرتا ہے۔ ہب اوورلے اسکلز 404 واپس کرتے ہیں — اس کے بجائے سورس پیکیج کو ان انسٹال کریں۔

ورک فلوز (Workflows)

ایک DAG (ڈائریکٹڈ ایسائکلک گراف) میں متعدد ایجنٹس کو ترتیب دیں — جہاں ممکن ہو مراحل کو متوازی طور پر چلائیں، اور پہلے کے مراحل کے آؤٹ پٹس کو بعد کے مراحل میں فیڈ کریں۔

ورک فلو گراف کی تصدیق کریں:

POST /v1/workflows/validate
Content-Type: application/json

{
  "graph": {
    "nodes": [
      { "id": "research", "agentId": "general", "prompt": "Research renewable energy trends" },
      { "id": "analyze", "agentId": "general", "prompt": "Research competitor pricing" },
      { "id": "report", "agentId": "general", "prompt": "Write a report combining: {{outputs.research}} and {{outputs.analyze}}", "dependsOn": ["research", "analyze"] }
    ]
  }
}

{ valid: true/false, errors: [...] } واپس کرتا ہے۔ سائیکلز، ڈپلیکیٹ آئی ڈیز، اور لاپتہ انحصاری حوالوں کو چیک کرتا ہے۔

ورک فلو چلائیں:

POST /v1/workflows/execute
Content-Type: application/json

{
  "graph": {
    "nodes": [
      { "id": "research", "agentId": "general", "prompt": "Research renewable energy trends" },
      { "id": "summarize", "agentId": "general", "prompt": "Summarize: {{outputs.research}}", "dependsOn": ["research"] }
    ]
  }
}

{ status: "completed", outputs: { research: "...", summarize: "..." }, nodeResults: {...} } واپس کرتا ہے۔

آزاد نوڈس (بغیر مشترکہ انحصار کے) متوازی طور پر چلتے ہیں۔ نوڈ کے پرامپٹ میں موجود {{outputs.nodeId}} پلیس ہولڈر کو نامزد اپ اسٹریم نوڈ کے مواد کے آؤٹ پٹ سے بدل دیا جاتا ہے۔ ہر نوڈ ایک مکمل ایجنٹ رن ہے، لہذا یہ ٹولز استعمال کر سکتا ہے، ویب براؤز کر سکتا ہے، اور ٹارگٹ ایجنٹ کی تمام صلاحیتوں تک رسائی حاصل کر سکتا ہے۔

نالج بیسز (Knowledge Bases)

دستاویزات کو تلاش کے قابل مجموعوں میں ترتیب دیں جن کا ایجنٹس حوالہ دے سکیں۔

نالج بیسز کی فہرست:

GET /v1/knowledge/bases

نالج بیس بنائیں:

POST /v1/knowledge/bases
Content-Type: application/json

{ "name": "Research Papers" }

نئی بیس آئی ڈی کے ساتھ 201 واپس کرتا ہے۔

نالج بیس میں دستاویز اپ لوڈ کریں:

POST /v1/knowledge/bases/{id}/documents
Content-Type: application/json

{
  "fileName": "research-paper.pdf",
  "contentType": "application/pdf",
  "dataUrl": "data:application/pdf;base64,JVBERi0xLjQ...",
  "description": "Renewable energy trends 2026"
}

dataUrl فیلڈ ایک base64-انکوڈ شدہ ڈیٹا URL ہے۔ دستاویز کے میٹا ڈیٹا کے ساتھ 201 واپس کرتا ہے۔

نالج بیس میں دستاویزات کی فہرست:

GET /v1/knowledge/bases/{id}/documents

نالج بیس کے اندر تلاش کریں:

POST /v1/knowledge/bases/{id}/search
Content-Type: application/json

{ "query": "renewable energy" }

فائل کے نام اور تفصیل کی بنیاد پر مماثل دستاویزات واپس کرتا ہے۔ سیمنٹک (ویکٹر) سرچ مستقبل کی ریلیز میں آ رہی ہے۔

دستاویز یا نالج بیس حذف کریں:

DELETE /v1/knowledge/bases/{id}/documents/{docId}
DELETE /v1/knowledge/bases/{id}

ایجنٹس ایکسپورٹ اور امپورٹ کریں

ایجنٹس کو پورٹیبل پیکجز کے طور پر شیئر کریں — آلات، ٹیموں، یا کمیونٹی ہب پر۔

ایجنٹ ایکسپورٹ کریں:

POST /v1/agents/{id}/export

ایک JSON پیکج واپس کرتا ہے جس میں ایجنٹ کی تعریف، ٹول کی ضروریات، کنیکٹر کی ضروریات، اور ٹرگر ٹیمپلیٹس شامل ہوتے ہیں۔ سنک میٹا ڈیٹا ہٹا دیا جاتا ہے — پیکج ایک صاف، خود مختار خاکہ ہوتا ہے۔

ایجنٹ امپورٹ کریں:

POST /v1/agents/import
Content-Type: application/json

{
  \"package\": {
    \"$schema\": \"caiioo.agent.package/v1\",
    \"agent\": {
      \"id\": \"shared-research-agent\",
      \"branding\": { \"name\": \"Research Agent\", \"description\": \"From the team\" },
      \"defaultSettings\": { \"systemPrompt\": \"You research things.\" },
      \"settingLevels\": {}
    },
    \"toolRequirements\": [
      { \"toolId\": \"web_browsing\", \"enabled\": true },
      { \"toolId\": \"search_tools\", \"enabled\": true }
    ]
  }
}

انسٹال شدہ ایجنٹ کے ساتھ 201 واپس کرتا ہے۔ بلٹ ان یا موجودہ ایجنٹس کے ساتھ ID کے ٹکراؤ کی صورت میں 409 واپس کرتا ہے۔

غلطیوں کی ہینڈلنگ (Error Handling)

API معیاری HTTP اسٹیٹس کوڈز استعمال کرتا ہے:

کوڈ	مطلب
200	کامیابی
201	تخلیق ہو گیا
202	قبول کر لیا گیا (غیر مطابقت پذیر آپریشن شروع ہو گیا)
204	حذف کر دیا گیا (کوئی مواد نہیں)
400	غلط درخواست — تفصیلات کے لیے error فیلڈ چیک کریں
401	غیر مجاز — سیشن سیکریٹ غائب یا غلط ہے
403	ممنوع — مثلاً، بلٹ ان ایجنٹ میں ترمیم کرنے کی کوشش
404	نہیں ملا
409	تنازع — مثلاً، ایجنٹ ID پہلے سے موجود ہے
422	توثیق کی غلطی — ان پٹ ٹول اسکیما سے مطابقت نہیں رکھتا
429	ریٹ لمیٹڈ — توثیق (Authentication) کے سیکشن میں ریٹ لمیٹ بجٹ دیکھیں
500	سرور کی غلطی — error فیلڈ چیک کریں
501	نافذ نہیں کیا گیا — فیچر موجود ہے لیکن اس طریقے سے دستیاب نہیں ہے
503	سروس دستیاب نہیں — اسٹوریج یا فراہم کنندہ تیار نہیں ہے

تمام غلطی کے جوابات میں { "error": "human-readable message" } شامل ہوتا ہے۔

فوری آغاز کی مثال (Quick Start Example)

یہاں ایک مکمل ورک فلو ہے: ایک ایجنٹ بنائیں، اسے چلائیں، اور نتائج اسٹریم کریں۔

# 1. ایک حسب ضرورت ایجنٹ بنائیں
curl -X POST http://localhost:3847/v1/agents \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "quick-summarizer",
    "branding": { "name": "Quick Summarizer" },
    "defaultSettings": {
      "systemPrompt": "Summarize any input concisely in 3 bullet points.",
      "enabledTools": { "web_browsing": true }
    },
    "settingLevels": {}
  }'

# 2. اسے غیر ہم آہنگ طریقے سے چلائیں
RUN=$(curl -s -X POST http://localhost:3847/v1/runs \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "quick-summarizer", "input": { "message": "Summarize https://en.wikipedia.org/wiki/Artificial_intelligence" }, "mode": "async" }')

RUN_ID=$(echo $RUN | jq -r '.runId')

# 3. ایونٹس اسٹریم کریں
curl -N http://localhost:3847/v1/runs/$RUN_ID/events \
  -H "Authorization: Bearer $API_TOKEN"

# 4. شیئرنگ کے لیے ایجنٹ ایکسپورٹ کریں
curl -X POST http://localhost:3847/v1/agents/quick-summarizer/export \
  -H "Authorization: Bearer $API_TOKEN"

---

This guide is maintained by the Caiioo team using Slate, our built-in editor.