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

---

عوامی API

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

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

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

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

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

مقامی ایپ کے لیے (خودکار): Caiioo ڈیسک ٹاپ ایپ، براؤزر ایکسٹینشنز، اور موبائل ایپس موجودہ ریلے آتھ ہیڈر (X-Relay-Auth) کے ذریعے خود بخود تصدیق کرتی ہیں۔ کسی دستی سیٹ اپ کی ضرورت نہیں ہے — ایپ پس پردہ اسے سنبھالتی ہے۔

سیٹ اپ:

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

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

فراہم کنندگان اور ماڈلز

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

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

GET /v1/providers

تمام کنفیگرڈ فراہم کنندگان کی اقسام (Anthropic, OpenAI, Google, OpenRouter, Ollama, Poe, MLX, Baseten، اور دیگر جیسے جیسے وہ شامل ہوں گے) مع قابلیت کے جھنڈے (supportsVision, supportsToolCalling, supportsStreaming وغیرہ) اور یہ کہ آیا API کلید کنفیگرڈ ہے یا نہیں، واپس کرتا ہے۔

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

GET /v1/providers/anthropic/models

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

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

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 واپس کرتا ہے۔

ایجنٹس چلانا

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

ہم آہنگ موڈ (Synchronous Mode)

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

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

{
  "agentId": "general",
  "input": { "message": "آج پیرس میں موسم کیسا ہے؟" },
  "mode": "sync"
}

ایجنٹ کے ختم ہونے کے بعد { content, usage, status: "completed" } کے ساتھ 200 واپس کرتا ہے۔ اگر ایجنٹ میں خرابی آتی ہے، تو { error, status: "error" } کے ساتھ 500 واپس کرتا ہے۔

غیر ہم آہنگ موڈ (Asynchronous Mode)

درخواست بھیجیں اور بھول جائیں — طویل کاموں کے لیے مفید:

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

{
  "agentId": "my-research-agent",
  "input": { "message": "قابل تجدید توانائی کے رجحانات کا 2000 الفاظ پر مشتمل تجزیہ لکھیں" },
  "mode": "async"
}

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

اسٹیٹس چیک کریں:

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)۔ ٹرمینل ایونٹ کے بعد اسٹریم ختم ہو جاتی ہے۔

رن (Run) منسوخ کریں:

POST /v1/runs/{runId}/cancel

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

Threads

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

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

GET /v1/threads

موجودہ پروفائل کے لیے threads واپس کرتا ہے جن میں کارکردگی کی خاطر پیغامات شامل نہیں ہوتے۔ ہر thread میں id ، title ، createdAt ، updatedAt ، modeId ، archived اور استعمال کے اعداد و شمار شامل ہوتے ہیں۔

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

GET /v1/threads/{id}

مکمل thread بشمول اس کے messages کی لڑی (array) واپس کرتا ہے — ہر صارف کا پیغام، اسسٹنٹ کا جواب، tool call، اور tool result۔

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

GET /v1/threads/{id}/messages

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

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

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

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

نئے thread کے ساتھ 201 واپس کرتا ہے۔ ڈیفالٹ کے طور پر، API ایپ کے فعال thread کو تبدیل نہیں کرتا — اگر آپ ایسا چاہتے ہیں تو باڈی میں "setActive": true پاس کریں۔ نیا thread فوری طور پر سائڈ بار میں ظاہر ہو جاتا ہے (بذریعہ WebSocket براڈکاسٹ)۔

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

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

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

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

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

DELETE /v1/threads/{id}

thread کو سافٹ ڈیلیٹ (sync کے لیے tombstone) کرتا ہے۔ 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 server کنفیگریشنز واپس کرتا ہے۔ حساس فیلڈز (authToken، env، credentialId) جواب سے حذف کر دی جاتی ہیں۔

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

GET /v1/mcp-servers/{id}

نیا MCP server شامل کریں:

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"
}

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

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

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

سرور کو فعال/غیر فعال (Enable/disable) کریں:

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

{ "enabled": false }

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

DELETE /v1/mcp-servers/{id}

Process Management

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

جاری پراسیسز کی فہرست دیکھیں:

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)

ان ٹولز کو براؤز اور کال کریں جو ایجنٹس استعمال کرتے ہیں — ویب براؤزنگ، سرچ، کیلنڈر، 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

ٹول کے ان پٹ پیرامیٹرز کے لیے JSON Schema واپس کرتا ہے، تاکہ آپ کال کرنے سے پہلے تصدیق کر سکیں۔

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

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

{ "input": { "expression": "sqrt(144) + 3^2" } }

{ result } واپس کرتا ہے۔ ان پٹ کی تصدیق ٹول کے اسکیما کے مطابق کی جاتی ہے — غلط ان پٹ تفصیلات کے ساتھ 422 واپس کرتا ہے۔ ریموٹ MCP ٹولز 501 واپس کرتے ہیں اور /v1/runs استعمال کرنے کی ہدایت دیتے ہیں (انہیں ایجنٹ سب پروسیس ٹرانسپورٹ کی ضرورت ہوتی ہے)۔

کنیکٹرز (Connectors)

OAuth انٹیگریشنز کا انتظام کریں — Google, Microsoft, GitHub, Notion, Slack، اور بہت کچھ۔

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

GET /v1/connectors/catalog

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

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

GET /v1/connectors

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

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

POST /v1/connectors/{id}/test

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

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

DELETE /v1/connectors/{id}

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

ٹرگرز (Triggers)

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

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

GET /v1/triggers

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

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

{
  "name": "Morning Briefing",
  "prompt": "Summarize my unread emails and today's calendar",
  "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": "A deploy happened: {{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}} پلیس ہولڈر کو خام درخواست کی باڈی سے بدل دیا جاتا ہے۔

حسب ضرورت فنکشنز (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}

ورک فلوز (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	تنازعہ — مثلاً ایجنٹ آئی ڈی پہلے سے موجود ہے
422	توثیق کی غلطی — ان پٹ ٹول اسکیما سے مطابقت نہیں رکھتا
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.