यह मूल अंग्रेजी दस्तावेज़ का मशीन अनुवाद है। इस अनुवाद और मूल अंग्रेजी संस्करण के बीच किसी भी विवाद की स्थिति में, अंग्रेजी संस्करण ही मान्य होगा। मूल अंग्रेजी संस्करण पढ़ें

पब्लिक 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) के माध्यम से स्वचालित रूप से प्रमाणित होते हैं। किसी मैन्युअल सेटअप की आवश्यकता नहीं है — ऐप इसे पर्दे के पीछे संभालता है।

सेटअप:

Caiioo Settings > API Access खोलें
Enable Public API को ऑन करें
एक API access token सेट करें (अपनी पसंद का कोई भी स्ट्रिंग — इसे पासवर्ड की तरह मानें)
सभी API अनुरोधों में उस टोकन का उपयोग करें

API लोकलहोस्ट और प्राइवेट रिले के माध्यम से उपलब्ध है। वर्तमान स्थिति और सेटअप निर्देशों के लिए GET /v1/auth/info (किसी ऑथ की आवश्यकता नहीं) देखें।

प्रदाता और मॉडल

खोजें कि कौन से LLM प्रदाता कॉन्फ़िगर किए गए हैं और कौन से मॉडल उपलब्ध हैं।

प्रदाताओं की सूची:

GET /v1/providers

क्षमता फ़्लैग (supportsVision, supportsToolCalling, supportsStreaming, आदि) और API कुंजी कॉन्फ़िगर है या नहीं, इसके साथ सभी कॉन्फ़िगर किए गए प्रदाता प्रकार (Anthropic, OpenAI, Google, OpenRouter, Ollama, Poe, MLX, Baseten, और अन्य जैसे-जैसे वे जोड़े जाते हैं) लौटाता है।

प्रदाता के लिए मॉडल की सूची:

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\": \"वेब खोजता है और निष्कर्षों का सारांश देता है\"
  },
  \"defaultSettings\": {
    \"systemPrompt\": \"आप एक शोध सहायक हैं। हमेशा स्रोतों का हवाला दें।\",
    \"enabledTools\": { \"web_browsing\": true, \"search_tools\": true }
  },
  \"settingLevels\": {}
}

बनाए गए एजेंट के साथ 201 लौटाता है। सिंक के लिए एक वेक्टर क्लॉक स्वचालित रूप से संलग्न की जाती है।

एक एजेंट अपडेट करें:

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

{ \"branding\": { \"name\": \"Research Agent\", \"description\": \"अपडेट किया गया विवरण\" } }

पैच को मौजूदा एजेंट में मर्ज करता है और वेक्टर क्लॉक को बढ़ाता है। बिल्ट-इन एजेंट 403 लौटाते हैं — वे केवल पढ़ने के लिए हैं।

एक एजेंट को हटाएँ:

DELETE /v1/agents/my-research-agent

टॉम्बस्टोन के माध्यम से सॉफ्ट-डिलीट (डिवाइसों में सिंक होता है)। 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)। अंतिम इवेंट के बाद स्ट्रीम समाप्त हो जाती है।

रन रद्द करें:

POST /v1/runs/{runId}/cancel

{ run: { ..., status: "cancelled" } } लौटाता है।

Threads

Threads बातचीत (conversations) हैं। प्रत्येक agent रन एक thread के भीतर होता है, और threads सत्रों (sessions) के दौरान बने रहते हैं। API आपको प्रोग्रामेटिक रूप से threads को सूचीबद्ध करने, पढ़ने, बनाने और प्रबंधित करने की अनुमति देता है।

सभी threads सूचीबद्ध करें (केवल metadata):

GET /v1/threads

प्रदर्शन के लिए संदेशों को हटाकर वर्तमान प्रोफाइल के threads लौटाता है। प्रत्येक thread में id, title, createdAt, updatedAt, modeId, archived, और उपयोग के आंकड़े शामिल होते हैं।

पूर्ण संदेशों के साथ एक thread प्राप्त करें:

GET /v1/threads/{id}

अपने messages ऐरे के साथ पूरा thread लौटाता है — प्रत्येक उपयोगकर्ता संदेश, assistant प्रतिक्रिया, tool call, और tool result।

केवल संदेश प्राप्त करें:

GET /v1/threads/{id}/messages

केवल messages ऐरे लौटाता है — जब आपको केवल बातचीत की आवश्यकता हो, तो यह पूर्ण thread ऑब्जेक्ट की तुलना में हल्का होता है।

एक 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| परिवर्तन वास्तविक समय में साइडबार पर प्रसारित होते हैं।

एक thread हटाएं:

DELETE /v1/threads/{id}

Thread को सॉफ्ट-डिलीट करता है (सिंक के लिए tombstone)। 204 लौटाता है। हटाए गए threads ट्रैश में चले जाते हैं और ट्रैश खाली होने तक उन्हें रिकवर किया जा सकता है।

सक्रिय thread:

GET /v1/threads/active            # { threadId } लौटाता है
PUT /v1/threads/active            # Body: { "threadId": "..." }

ट्रैश प्रबंधन:

GET /v1/threads/trash/count       # { count } लौटाता है
POST /v1/threads/trash/empty      # { 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"
}

Agent thread से बातचीत का पूरा इतिहास देखता है।

अटैचमेंट्स

अटैचमेंट्स थ्रेड्स से जुड़ी फाइलें हैं — स्क्रीनशॉट, PDF, दस्तावेज़, अपलोड की गई छवियां, जेनरेट किए गए आर्टिफैक्ट्स। 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": "तिमाही रिपोर्ट",
  "dataUrl": "data:application/pdf;base64,JVBERi0xLjQ..."
}

dataUrl एक base64-एन्कोडेड डेटा URL है। नई अटैचमेंट ID के साथ 201 लौटाता है। अटैचमेंट निर्दिष्ट थ्रेड से जुड़ा होता है।

अटैचमेंट मेटाडेटा अपडेट करें:

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

{ "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 के लिए, आप सर्वर प्रोसेस को सीधे प्रबंधित कर सकते हैं।

चल रहे प्रोसेस की सूची प्राप्त करें:

GET /v1/mcp-servers/processes

pid, startedAt, और running स्टेटस के साथ चल रहे सर्वर प्रोसेस लौटाता है।

सर्वर शुरू करें:

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

सर्वर कॉन्फ़िगरेशन से command/args/env पढ़ता है और प्रोसेस शुरू करता है। प्रोसेस स्टेटस लौटाता है।

सर्वर रोकें:

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

सर्वर प्रोसेस को सुरक्षित रूप से बंद करता है (SIGKILL के विकल्प के साथ SIGTERM)।

सीधे JSON-RPC मेथड कॉल करें:

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

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

सर्वर को एक रॉ JSON-RPC 2.0 रिक्वेस्ट भेजता है और परिणाम लौटाता है। यह डिबगिंग या उन मेथड्स को कॉल करने के लिए उपयोगी है जो टूल्स API के माध्यम से उपलब्ध नहीं हैं।

टूल्स और टूलकिट्स

उन टूल्स को ब्राउज़ करें और कॉल करें जिनका उपयोग एजेंट करते हैं — वेब ब्राउजिंग, सर्च, कैलेंडर, 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 स्कीमा लौटाता है, ताकि आप कॉल करने से पहले वैलिडेट कर सकें।

किसी टूल को सीधे कॉल करें:

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

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

{ result } लौटाता है। इनपुट को टूल के स्कीमा के विरुद्ध वैलिडेट किया जाता है — अमान्य इनपुट विवरण के साथ 422 लौटाता है। रिमोट MCP टूल्स 501 लौटाते हैं और इसके बजाय /v1/runs का उपयोग करने का सुझाव देते हैं (उन्हें एजेंट सबप्रोसेस ट्रांसपोर्ट की आवश्यकता होती है)।

कनेक्टर्स

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 फ्लो की आवश्यकता होती है।

ट्रिगर्स

एजेंटों को स्वचालित रूप से चलाने के लिए शेड्यूल करें — दैनिक ब्रीफिंग, साप्ताहिक रिपोर्ट, अंतराल-आधारित निगरानी।

ट्रिगर्स की सूची:

GET /v1/triggers

एक शेड्यूल किया गया ट्रिगर बनाएं:

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 ऑथ की आवश्यकता नहीं होती है — यह इसके बजाय HMAC सत्यापन का उपयोग करता है। भेजे गए रन के threadId के साथ 202 लौटाता है। ट्रिगर प्रॉम्प्ट में {{webhook.body}} प्लेसहोल्डर को रॉ रिक्वेस्ट बॉडी से बदल दिया जाता है।

कस्टम फंक्शन्स

अपने स्वयं के टूल बनाएं जिन्हें एजेंट कॉल कर सकें। फंक्शन्स JavaScript या Python में लिखे जाते हैं और एक सैंडबॉक्स में निष्पादित होते हैं।

फंक्शन्स की सूची:

GET /v1/functions

एक फंक्शन बनाएं:

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

{
  "name": "calculate_bmi",
  "description": "ऊंचाई और वजन से बॉडी मास इंडेक्स की गणना करें",
  "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 Node के vm सैंडबॉक्स में चलता है (कोई फाइलसिस्टम या नेटवर्क एक्सेस नहीं, 10s टाइमआउट)। Python 30s टाइमआउट के साथ एक सबप्रोसेस के रूप में चलता है। दोनों निष्पादन से पहले इनपुट को वैलिडेट करते हैं।

अपडेट करें या हटाएं:

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": "नवीकरणीय ऊर्जा रुझानों पर शोध करें" },
      { "id": "analyze", "agentId": "general", "prompt": "प्रतिस्पर्धी मूल्य निर्धारण पर शोध करें" },
      { "id": "report", "agentId": "general", "prompt": "एक रिपोर्ट लिखें जिसमें शामिल हो: {{outputs.research}} और {{outputs.analyze}}", "dependsOn": ["research", "analyze"] }
    ]
  }
}

{ valid: true/false, errors: [...] } लौटाता है। साइकिल, डुप्लिकेट ID और गायब डिपेंडेंसी संदर्भों की जांच करता है।

वर्कफ़्लो निष्पादित करें:

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

{
  "graph": {
    "nodes": [
      { "id": "research", "agentId": "general", "prompt": "नवीकरणीय ऊर्जा रुझानों पर शोध करें" },
      { "id": "summarize", "agentId": "general", "prompt": "सारांश दें: {{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" }

नई बेस ID के साथ 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": "नवीकरणीय ऊर्जा रुझान 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 पैकेज लौटाता है जिसमें एजेंट परिभाषा, टूल आवश्यकताएँ (सक्षम टूल से प्राप्त), कनेक्टर आवश्यकताएँ (किन OAuth प्रदाताओं की आवश्यकता है), और ट्रिगर टेम्प्लेट शामिल हैं। सिंक मेटाडेटा हटा दिया जाता है — पैकेज एक साफ, स्व-निहित ब्लूप्रिंट है।

एक एजेंट इम्पोर्ट करें:

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

{
  \"package\": {
    \"$schema\": \"caiioo.agent.package/v1\",
    \"agent\": {
      \"id\": \"shared-research-agent\",
      \"branding\": { \"name\": \"Research Agent\", \"description\": \"टीम की ओर से\" },
      \"defaultSettings\": { \"systemPrompt\": \"आप चीजों पर शोध करते हैं।\" },
      \"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`	वैलिडेशन त्रुटि — इनपुट टूल स्कीमा से मेल नहीं खाता
`500`	सर्वर त्रुटि — `error` फ़ील्ड जांचें
`501`	लागू नहीं किया गया — सुविधा मौजूद है लेकिन इस तरह उपलब्ध नहीं है
`503`	सेवा अनुपलब्ध — स्टोरेज या प्रोवाइडर तैयार नहीं है

सभी त्रुटि प्रतिक्रियाओं में { "error": "मानव-पठनीय संदेश" } शामिल होता है।

क्विक स्टार्ट उदाहरण

यहाँ एक पूर्ण वर्कफ़्लो है: एक एजेंट बनाएं, उसे चलाएं, और परिणामों को स्ट्रीम करें।

# 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": "किसी भी इनपुट का 3 बुलेट पॉइंट्स में संक्षेप में सारांश दें।",
      "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.