এটি মূল ইংরেজি নথির একটি মেশিন অনুবাদ। এই অনুবাদ এবং মূল ইংরেজি সংস্করণের মধ্যে কোনো বিরোধ দেখা দিলে, ইংরেজি সংস্করণটিই প্রাধান্য পাবে। মূল ইংরেজি সংস্করণটি পড়ুন

পাবলিক API

caiioo-তে একটি REST API রয়েছে যা আপনাকে প্রোগ্রাম্যাটিকভাবে সবকিছু নিয়ন্ত্রণ করতে দেয়: এজেন্ট চালানো, টুল পরিচালনা করা, টাস্ক শিডিউল করা এবং আরও অনেক কিছু। এই API সেই একই লোকাল সার্ভারে থাকে যা ডেস্কটপ অ্যাপ এবং ব্রাউজার ব্রিজ পরিচালনা করে।

বেস URL: http://localhost:3847/v1

অথেন্টিকেশন: অথেন্টিকেশনের দুটি উপায় রয়েছে, উভয়ই সেটিংসের API টগল দ্বারা নিয়ন্ত্রিত:

এক্সটার্নাল কনজিউমারদের জন্য (স্ক্রিপ্ট, ইন্টিগ্রেশন, curl): সেটিংস > API অ্যাক্সেস-এ একটি API অ্যাক্সেস টোকেন সেট করুন, তারপর এটি Bearer টোকেন হিসেবে ব্যবহার করুন:

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

লোকাল অ্যাপের জন্য (স্বয়ংক্রিয়): Caiioo ডেস্কটপ অ্যাপ, ব্রাউজার এক্সটেনশন এবং মোবাইল অ্যাপগুলো বিদ্যমান রিলে অথ হেডার (X-Relay-Auth) এর মাধ্যমে স্বয়ংক্রিয়ভাবে অথেন্টিকেট হয়। কোনো ম্যানুয়াল সেটআপের প্রয়োজন নেই — অ্যাপটি পর্দার আড়ালে এটি পরিচালনা করে।

সেটআপ: ১. Caiioo সেটিংস > API অ্যাক্সেস খুলুন ২. Enable Public API টগলটি চালু করুন ৩. একটি API অ্যাক্সেস টোকেন সেট করুন (আপনার পছন্দমতো যেকোনো স্ট্রিং — এটিকে পাসওয়ার্ডের মতো মনে করুন) ৪. সমস্ত 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\": \"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 রিটার্ন করে — সেগুলো শুধুমাত্র পাঠযোগ্য (read-only)।

একটি এজেন্ট মুছে ফেলুন:

DELETE /v1/agents/my-research-agent

টম্বস্টোনের মাধ্যমে সফট-ডিলিট করে (ডিভাইস জুড়ে সিঙ্ক হয়)। 204 রিটার্ন করে।

এজেন্ট চালানো (Running Agents)

এটিই মূল কাজ — একটি মেসেজ প্রসেস করার জন্য এজেন্টকে কল করুন।

সিনক্রোনাস মোড (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": "নবায়নযোগ্য শক্তির প্রবণতা নিয়ে ২০০০ শব্দের একটি বিশ্লেষণ লিখুন" },
  "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 হলো কথোপকথন। প্রতিটি agent রান একটি thread-এর মধ্যে ঘটে এবং সেশন শেষ হওয়ার পরেও thread-গুলো সংরক্ষিত থাকে। API আপনাকে প্রোগ্রাম্যাটিকভাবে thread-গুলোর তালিকা দেখতে, পড়তে, তৈরি করতে এবং পরিচালনা করতে দেয়।

সবগুলো thread-এর তালিকা দেখুন (শুধুমাত্র metadata):

GET /v1/threads

পারফরম্যান্সের সুবিধার্থে মেসেজগুলো বাদ দিয়ে বর্তমান প্রোফাইলের thread-গুলো রিটার্ন করে। প্রতিটি 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 রিটার্ন করে। মুছে ফেলা thread-গুলো ট্র্যাশে চলে যায় এবং ট্র্যাশ খালি না করা পর্যন্ত সেগুলো পুনরুদ্ধার করা সম্ভব।

সক্রিয় 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 } রিটার্ন করে

সুরক্ষিত thread-গুলো (যা ডেটা রিটেনশন টগলের মাধ্যমে রাখা হয়েছে) ট্র্যাশ খালি করার সময় বাদ দেওয়া হয়।

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। নতুন অ্যাটাচমেন্ট আইডি সহ 201 রিটার্ন করে। অ্যাটাচমেন্টটি নির্দিষ্ট থ্রেডের সাথে যুক্ত হয়।

অ্যাটাচমেন্ট মেটাডেটা আপডেট করুন:

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

{ "description": "আপডেট করা বর্ণনা", "fileName": "new-name.pdf" }

একটি অ্যাটাচমেন্ট মুছে ফেলুন:

DELETE /v1/attachments/{id}

Tombstone-এর মাধ্যমে সফট-ডিলিট করে। 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"] }

একটি সার্ভার সক্রিয়/নিষ্ক্রিয় করুন:

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 পড়ে এবং প্রসেসটি স্পন (spawn) করে। প্রসেস স্ট্যাটাস রিটার্ন করে।

একটি সার্ভার বন্ধ করুন:

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

সার্ভার প্রসেসটি যথাযথভাবে বন্ধ করে (SIGTERM এবং প্রয়োজনে SIGKILL ব্যবহার করে)।

সরাসরি একটি JSON-RPC মেথড কল করুন:

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

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

সার্ভারে একটি র (raw) 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 Schema রিটার্ন করে, যাতে আপনি কল করার আগে যাচাই করতে পারেন।

সরাসরি একটি টুল কল করুন:

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

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

{ result } রিটার্ন করে। ইনপুটটি টুলের স্কিমার বিপরীতে যাচাই করা হয় — অবৈধ ইনপুট বিস্তারিত সহ 422 রিটার্ন করে। রিমোট MCP টুলগুলো /v1/runs ব্যবহারের নির্দেশিকা সহ 501 রিটার্ন করে (সেগুলোর জন্য এজেন্ট সাবপ্রসেস ট্রান্সপোর্ট প্রয়োজন)।

কানেক্টর

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": "সকালের ব্রিফিং",
  "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)

ওয়েব হুক ট্রিগারগুলো এক্সটার্নাল সার্ভিসকে (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 নোডের vm স্যান্ডবক্সে চলে (ফাইল সিস্টেম বা নেটওয়ার্ক অ্যাক্সেস নেই, ১০ সেকেন্ড টাইমআউট)। Python একটি সাবপ্রসেস হিসেবে ৩০ সেকেন্ড টাইমআউট সহ চলে। উভয়ই এক্সিকিউশনের আগে ইনপুট যাচাই করে।

আপডেট বা ডিলিট:

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

ওয়ার্কফ্লো

একটি DAG (directed acyclic graph)-এ একাধিক এজেন্ট পরিচালনা করুন — যেখানে সম্ভব সেখানে সমান্তরালভাবে ধাপগুলো চালান এবং আগের ধাপের আউটপুট পরের ধাপে ইনপুট হিসেবে দিন।

একটি ওয়ার্কফ্লো গ্রাফ যাচাই করুন:

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: [...] } রিটার্ন করে। এটি সাইকেল, ডুপ্লিকেট আইডি এবং অনুপস্থিত ডিপেন্ডেন্সি রেফারেন্স চেক করে।

একটি ওয়ার্কফ্লো এক্সিকিউট করুন:

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}} প্লেসহোল্ডারটি সংশ্লিষ্ট আপস্ট্রিম নোডের কন্টেন্ট আউটপুট দ্বারা প্রতিস্থাপিত হয়। প্রতিটি নোড একটি পূর্ণাঙ্গ এজেন্ট রান, তাই এটি টুল ব্যবহার করতে পারে, ওয়েব ব্রাউজ করতে পারে এবং টার্গেট এজেন্টের সমস্ত সক্ষমতা অ্যাক্সেস করতে পারে।

নলেজ বেস

ডকুমেন্টগুলোকে অনুসন্ধানযোগ্য সংগ্রহে সংগঠিত করুন যা এজেন্টরা রেফারেন্স হিসেবে ব্যবহার করতে পারে।

নলেজ বেসের তালিকা:

GET /v1/knowledge/bases

একটি নলেজ বেস তৈরি করুন:

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

{ "name": "গবেষণাপত্র" }

নতুন বেস আইডি সহ 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": "নবায়নযোগ্য শক্তির প্রবণতা ২০২৬"
}

dataUrl ফিল্ডটি একটি base64-এনকোডেড ডাটা URL। ডকুমেন্ট মেটাডেটা সহ 201 রিটার্ন করে।

একটি নলেজ বেসের ডকুমেন্টের তালিকা:

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

একটি নলেজ বেসের মধ্যে অনুসন্ধান করুন:

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

{ "query": "নবায়নযোগ্য শক্তি" }

ফাইলের নাম এবং বর্ণনার ভিত্তিতে ম্যাচিং ডকুমেন্টগুলো রিটার্ন করে। সিম্যান্টিক (ভেক্টর) সার্চ ভবিষ্যতে কোনো রিলিজে আসবে।

একটি ডকুমেন্ট বা নলেজ বেস মুছে ফেলুন:

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 রিটার্ন করে।

এরর হ্যান্ডলিং

API স্ট্যান্ডার্ড HTTP স্ট্যাটাস কোড ব্যবহার করে:

কোড	অর্থ
`200`	সফল
`201`	তৈরি করা হয়েছে
`202`	গৃহীত (অ্যাসিনক্রোনাস অপারেশন শুরু হয়েছে)
`204`	মুছে ফেলা হয়েছে (কোনো কন্টেন্ট নেই)
`400`	ভুল রিকোয়েস্ট — বিস্তারিত জানার জন্য `error` ফিল্ড চেক করুন
`401`	অননুমোদিত — সেশন সিক্রেট নেই বা অবৈধ
`403`	নিষিদ্ধ — যেমন, একটি বিল্ট-ইন এজেন্ট পরিবর্তন করার চেষ্টা করা
`404`	পাওয়া যায়নি
`409`	দ্বন্দ্ব — যেমন, এজেন্ট আইডি ইতিমধ্যে বিদ্যমান
`422`	ভ্যালিডেশন এরর — ইনপুট টুলের স্কিমার সাথে মিলছে না
`500`	সার্ভার এরর — `error` ফিল্ড চেক করুন
`501`	বাস্তবায়িত হয়নি — ফিচারটি বিদ্যমান কিন্তু এভাবে উপলব্ধ নয়
`503`	সার্ভিস অনুপলব্ধ — স্টোরেজ বা প্রোভাইডার প্রস্তুত নয়

সমস্ত এরর রেসপন্সে { "error": "মানুষের পাঠযোগ্য মেসেজ" } অন্তর্ভুক্ত থাকে।

কুইক স্টার্ট উদাহরণ

এখানে একটি সম্পূর্ণ ওয়ার্কফ্লো দেওয়া হলো: একটি এজেন্ট তৈরি করা, সেটি চালানো এবং ফলাফল স্ট্রিম করা।

# ১. একটি কাস্টম এজেন্ট তৈরি করুন
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": "যেকোনো ইনপুটকে সংক্ষেপে ৩টি বুলেট পয়েন্টে সারসংক্ষেপ করুন।",
      "enabledTools": { "web_browsing": true }
    },
    "settingLevels": {}
  }'

# ২. এটি অ্যাসিনক্রোনাসভাবে চালান
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')

# ৩. ইভেন্টগুলো স্ট্রিম করুন
curl -N http://localhost:3847/v1/runs/$RUN_ID/events \
  -H "Authorization: Bearer $API_TOKEN"

# ৪. শেয়ার করার জন্য এজেন্টটি এক্সপোর্ট করুন
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.