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

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

सेटअप:

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

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

दर सीमाएं (Rate limits): प्रत्येक /v1/* अनुरोध प्रति क्लाइंट IP दर-सीमित है — पढ़ने के लिए प्रति मिनट 100 GET अनुरोध और संयुक्त रूप से प्रति मिनट 30 राइट अनुरोध (POST / PATCH / DELETE)। सीमा से अधिक अनुरोधों को 429 मिलता है। वेबहुक डिलीवरी (POST /v1/webhooks/:id) बियरर-ऑथेंटिकेटेड नहीं हैं और इन सीमाओं के अधीन नहीं हैं।

Profiles

एक ही डिवाइस में कई उपयोगकर्ता प्रोफाइल हो सकते हैं (जैसे व्यक्तिगत + कार्य)। 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 } लौटाता है। एक प्रोफाइल (threads, attachments, settings, skills) के दायरे में आने वाले सभी /v1/* संसाधन इसी के विरुद्ध काम करते हैं।

सक्रिय प्रोफाइल स्विच करें:

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

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

नये सक्रिय प्रोफाइल के लिए { profile } लौटाता है। यदि ID कोई ज्ञात प्रोफाइल नहीं है तो 404 लौटाता है।

Providers & Models

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

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

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`	प्रदाता एक रीजनिंग/थिंकिंग बजट प्रदर्शित करता है
`supportsPromptCaching`	प्रदाता प्रॉम्प्ट-कैश निर्देशों का समर्थन करता है
`nativeReasoningBlocks`	प्रदाता थिंकिंग को नेटिव मैसेज ब्लॉक के रूप में उत्सर्जित करता है (बनाम टेक्स्ट)
`requiresThoughtSignature`	प्रदाता को हस्ताक्षरित थॉट टोकन को वापस प्रतिध्वनित (echo) करने की आवश्यकता होती है

Capability फ्लैग प्रत्येक प्रदाता क्लास के readonly capabilities फ़ील्ड को दर्शाते हैं (देखें src/shared/providers/*-provider.ts) और एक ड्रिफ्ट सेंटिनल टेस्ट द्वारा मान्य किए जाते हैं — मैट्रिक्स को हार्डकोड करने के बजाय रनटाइम पर इस एंडपॉइंट को कॉल करें।

BYOK प्रदाताओं के लिए नोट्स:

perplexity Sonar मॉडलों की एक क्यूरेटेड सूची प्रदर्शित करता है (Perplexity का कोई सार्वजनिक /models एंडपॉइंट नहीं है)।
cloudflare (AI Gateway) BYOK + मल्टी-वेंडर है; मॉडल सूची आपके गेटवे कॉन्फ़िगरेशन द्वारा निर्धारित की जाती है और /v1/providers/cloudflare/models द्वारा एक खाली एरे के रूप में लौटाई जाती है। अपने स्वयं के गेटवे कैटलॉग का उपयोग करें।

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

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\": \"वेब खोजता है और निष्कर्षों का सारांश देता है\"
  },
  \"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 लौटाता है।

Agents चलाना

यह मुख्य इवेंट है — किसी संदेश को प्रोसेस करने के लिए एक एजेंट को इनवोक करें।

Request body — समर्थित फ़ील्ड

फ़ील्ड	आवश्यक	विवरण
`agentId`	हाँ	Builtin मोड ID (जैसे `general`) या एक कस्टम एजेंट ID
`input.message`	हाँ	उपयोगकर्ता संदेश टेक्स्ट
`input.attachments`	नहीं	अटैचमेंट ID का ऐरे (जो पहले ही `/v1/attachments` के माध्यम से अपलोड किए जा चुके हैं) जिन्हें इस टर्न में जोड़ना है
`input.variables`	नहीं	प्रति-रन वेरिएबल ओवरराइड्स जो एजेंट के वेरिएबल रिज़ॉल्वर में मर्ज किए जाते हैं
`input.tabContext`	नहीं	पेज-कॉन्टेक्स्ट के रूप में इंजेक्ट किया गया फ्री-फॉर्म स्ट्रिंग (ब्राउज़र ब्रिज द्वारा उपयोग किया जाता है)
`input.messageId`	नहीं	क्लाइंट द्वारा प्रदान की गई संदेश ID — यदि आप पुनः प्रयास करते हैं तो डुप्लीकेशन हटाने के लिए उपयोगी है
`threadId`	नहीं	जारी रखने के लिए मौजूदा थ्रेड। यदि छोड़ दिया जाता है, तो एक नया थ्रेड बनाया और वापस किया जाता है
`mode`	नहीं	`"sync"` या `"async"`। डिफ़ॉल्ट `"async"` है

Synchronous मोड

पूर्ण प्रतिक्रिया की प्रतीक्षा करें:

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 मोड

चलाएं और भूल जाएं — लंबे समय तक चलने वाले कार्यों के लिए उपयोगी:

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 वापस करता है।

स्टेटस के लिए पोल करें:

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)।

टर्मिनल इवेंट के बाद, सर्वर स्ट्रीम के स्पष्ट अंत के संकेत के रूप में event: terminal और एक खाली डेटा पेलोड के साथ एक अंतिम SSE फ्रेम भेजता है, फिर कनेक्शन बंद कर देता है। क्लाइंट्स को उस फ्रेम की प्राप्ति (या कनेक्शन बंद होने) को पढ़ना बंद करने के संकेत के रूप में मानना चाहिए।

यदि आप रन समाप्त होने के बाद सब्सक्राइब करते हैं, तो सर्वर RUN_SNAPSHOT प्रकार का एक फ्रेम रिप्ले करता है जिसमें पूर्ण अंतिम record होता है, उसके बाद event: terminal संकेत आता है, और फिर बंद हो जाता है।

रन रद्द करें:

POST /v1/runs/{runId}/cancel

{ run: { ..., status: "cancelled" } } वापस करता है।

Threads

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

सभी threads की सूची (केवल metadata):

GET /v1/threads

वर्तमान प्रोफाइल के लिए { threads: [...] } लौटाता है जिसमें messages हटा दिए जाते हैं (जब आपको उनकी आवश्यकता हो तो detail endpoint का उपयोग करें)। अन्य सभी फ़ील्ड सुरक्षित रहते हैं — id, title, createdAt, updatedAt, modeId, archived, उपयोग के आंकड़े, साथ ही सेट होने पर subAgentHistories, anonymizerSnapshot, threadToolApprovals, threadVariables, threadToolOverrides, messagingBinding, scheduledTaskId| (अधिक विस्तृत पेलोड विशेष रूप से API के लिए है — WebSocket साइडबार ब्रॉडकास्ट ट्रांसपोर्ट सीमाओं के भीतर रहने के लिए एक संक्षिप्त स्ट्रिप का उपयोग करता है।)

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

GET /v1/threads/{id}

इसके messages ऐरे सहित पूरा thread लौटाता है — प्रत्येक उपयोगकर्ता संदेश, असिस्टेंट प्रतिक्रिया, 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 लौटाता है। नया 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 ट्रैश में चले जाते हैं और ट्रैश खाली होने तक उन्हें रिकवर किया जा सकता है।

सक्रिय 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 पर अनुवर्ती संदेश (follow-up message) भेजने के लिए, 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 से बातचीत का पूरा इतिहास देखता है।

अटैचमेंट्स

अटैचमेंट्स थ्रेड्स से जुड़ी फाइलें हैं — स्क्रीनशॉट, 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 सर्वर कॉन्फ़िगरेशन लौटाता है। संवेदनशील फ़ील्ड्स (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"] }

पैच करने योग्य फ़ील्ड्स POST अनुमति सूची (allowlist) के समान हैं (जिसमें credentialId और oauthConnectionId शामिल हैं — बिना डिलीट और री-क्रिएट किए OAuth कनेक्शन को रोटेट करने के लिए उपयोगी)। सर्वर-प्रबंधित फ़ील्ड्स केवल-पठन (read-only) रहते हैं।

सर्वर को सक्षम/अक्षम (Enable/disable) करें:

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 पढ़ता है और प्रोसेस को स्पॉन (spawn) करता है। प्रोसेस स्टेटस लौटाता है।

सर्वर रोकें:

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 के माध्यम से एक्सपोज़ नहीं किए गए हैं।

Tools और Toolkits

उन टूल्स को ब्राउज़ करें और इनवोक करें जिनका उपयोग एजेंट करते हैं — वेब ब्राउज़िंग, सर्च, कैलेंडर, Gmail, Slate, और बहुत कुछ।

Toolkits की सूची (समूहबद्ध):

GET /v1/toolkits

कैटेगरी (Productivity, Search, Utilities, आदि) के आधार पर समूहबद्ध एम्बेडेड टूल्स और अलग toolkits के रूप में किसी भी कनेक्टेड MCP सर्वर्स को उनके कार्यों (actions) की सूची के साथ लौटाता है।

सभी टूल्स की सूची (फ्लैट):

GET /v1/tools
GET /v1/tools?source=embedded   # केवल बिल्ट-इन टूल्स
GET /v1/tools?source=mcp        # केवल MCP सर्वर टूल्स

input schema के साथ टूल का विवरण प्राप्त करें:

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 — public API क्या अस्वीकार करता है:

Tier-gated टूल्स (metadata.requiredTier !== 'free') → 403। एजेंट लूप यूजर के सेशन के विरुद्ध टियर की जांच करता है; public API में कोई टियर संदर्भ नहीं होता है, इसलिए रूढ़िवादी नीति इसे अस्वीकार करने की है। इसके बजाय सही टियर वाले एजेंट के साथ POST /v1/runs का उपयोग करें।
मंजूरी-आवश्यक टूल्स (metadata.approval.requiresApproval === true) → 403। पूछने के लिए लूप में कोई मानव नहीं है। POST /v1/runs के माध्यम से इनवोक करें (जो यूजर को प्रॉम्प्ट दिखाता है) या बाईपास करने के लिए ऐप में टूल अप्रूवल मोड को approve_all पर सेट करें।
रिमोट MCP टूल्स → 501, /v1/runs का उपयोग करने के मार्गदर्शन के साथ (उन्हें एजेंट सबप्रोसेस ट्रांसपोर्ट की आवश्यकता होती है)।

Vision और इमेज-उपयोग वाले टूल्स: पहले POST /v1/attachments के माध्यम से अपलोड करें, फिर लौटाए गए अटैचमेंट ID को input के अंदर पास करें (जैसे { "input": { "attachment_id": "att_abc", "prompt": "इस इमेज में क्या है?" } })। टूल threadId के माध्यम से स्टोरेज से बाइनरी पढ़ता है; आप बाइट्स को इनलाइन पास नहीं करते हैं।

कनेक्टर्स

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

ट्रिगर्स

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

प्रत्येक ट्रिगर में एक kind भेदक होता है: schedule (डिफ़ॉल्ट — घड़ी पर चलता है), webhook (तब चलता है जब कोई बाहरी सेवा वेबहुक पथ पर POST करती है), या messaging (एक जुड़े हुए मैसेजिंग एडॉप्टर से चलता है — जैसे चैनल फ़िल्टर से मेल खाने वाले इनबाउंड Slack/Discord संदेश)।

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

GET /v1/triggers

{ triggers: [...] } लौटाता है। प्रत्येक प्रविष्टि में उसका kind, शेड्यूल और प्रकार-विशिष्ट फ़ील्ड शामिल होते हैं।

एकल ट्रिगर प्राप्त करें:

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 मिनट में
{ \"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

Webhook triggers बाहरी सेवाओं (CI/CD, मॉनिटरिंग, फॉर्म बिल्डर्स) को HTTP के माध्यम से एक एजेंट रन ट्रिगर करने की अनुमति देते हैं।

एक webhook trigger बनाएँ:

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

{
  "name": "Deploy hook",
  "prompt": "A deploy happened: {{webhook.body}}",
  "modeId": "general",
  "kind": "webhook"
}

यह webhookSecret और webhookPath के साथ 201 लौटाता है। सीक्रेट को सुरक्षित रखें — पेलोड को साइन करने के लिए आपको इसकी आवश्यकता होगी।

एक webhook भेजें:

# रॉ रिक्वेस्ट बॉडी का 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"}

Webhook एंडपॉइंट को bearer auth की आवश्यकता नहीं होती है — इसके बजाय यह HMAC सत्यापन का उपयोग करता है। यह डिस्पैच किए गए रन के threadId के साथ 202 लौटाता है। ट्रिगर प्रॉम्प्ट में {{webhook.body}} प्लेसहोल्डर को रॉ रिक्वेस्ट बॉडी से बदल दिया जाता है।

Messaging triggers

Messaging triggers तब सक्रिय होते हैं जब एक कनेक्टेड मैसेजिंग एडेप्टर (जैसे Community Hub के माध्यम से इंस्टॉल किया गया Slack या Discord इंटीग्रेशन) ट्रिगर के फ़िल्टर से मेल खाने वाला इनबाउंड संदेश प्राप्त करता है। kind: "messaging" के साथ बनाएँ:

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

{
  "name": "Mention responder",
  "prompt": "Reply helpfully to: {{message.text}}",
  "modeId": "general",
  "kind": "messaging",
  "messagingAdapterId": "slack-team-acme",
  "messagingChannelFilter": "#support"
}

एडेप्टर ट्रिगर में मिलान करने वाली घटनाओं को भेजने के लिए ज़िम्मेदार है; messagingChannelFilter एडेप्टर-विशिष्ट है।

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

अपने स्वयं के टूल बनाएं जिन्हें एजेंट कॉल कर सकें। फंक्शन्स 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}

Skills

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 (वैकल्पिक) स्किल को विशिष्ट एजेंट ID तक सीमित करता है; सभी मोड के लिए इसे छोड़ दें। नए स्किल (सर्वर द्वारा असाइन किए गए id, createdAt, updatedAt सहित) के साथ 201 लौटाता है।

एक स्किल अपडेट करें:

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": "नवीकरणीय ऊर्जा रुझानों पर शोध करें" },
      { "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`	सत्यापन त्रुटि — इनपुट टूल स्कीमा से मेल नहीं खाता
`429`	रेट-लिमिटेड — Authentication अनुभाग में रेट-लिमिट बजट देखें
`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.