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

পাবলিক API

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

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

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

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

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

লোকাল অ্যাপের জন্য (স্বয়ংক্রিয়): Caiioo ডেস্কটপ অ্যাপ, ব্রাউজার এক্সটেনশন এবং মোবাইল অ্যাপগুলো বিদ্যমান রিলে অথ হেডার (x-relay-auth) এর মাধ্যমে স্বয়ংক্রিয়ভাবে অথেন্টিকেট করে। কোনো ম্যানুয়াল সেটআপের প্রয়োজন নেই — অ্যাপটি পর্দার আড়ালে এটি পরিচালনা করে। রিলে-অথ রিকোয়েস্টগুলো Enable Public API টগলকে বাইপাস করে কারণ সেগুলো আগে থেকেই বিশ্বস্ত; শুধুমাত্র বেয়ারার-টোকেন রিকোয়েস্টগুলো টগলের মাধ্যমে নিয়ন্ত্রিত হয়।

সেটআপ: ১. Caiioo Settings > API Access খুলুন ২. Enable Public API চালু করুন ৩. একটি API অ্যাক্সেস টোকেন সেট করুন (আপনার পছন্দমতো যেকোনো স্ট্রিং — এটিকে পাসওয়ার্ডের মতো মনে করুন) ৪. সমস্ত API রিকোয়েস্টে সেই টোকেনটি ব্যবহার করুন

API-টি লোকালহোস্টে এবং প্রাইভেট রিলে-এর মাধ্যমে উপলব্ধ। বর্তমান স্ট্যাটাস এবং সেটআপ নির্দেশাবলীর জন্য GET /v1/auth/info (অথেন্টিকেশন প্রয়োজন নেই) চেক করুন।

রেট লিমিট: প্রতিটি /v1/* রিকোয়েস্ট ক্লায়েন্ট আইপি অনুযায়ী রেট-লিমিটেড — রিড করার জন্য প্রতি মিনিটে ১০০টি GET রিকোয়েস্ট এবং রাইট করার জন্য (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 } রিটার্ন করে। একটি প্রোফাইলের আওতাভুক্ত সমস্ত /v1/* রিসোর্স (threads, attachments, settings, skills) এটির বিপরীতে কাজ করে।

সক্রিয় প্রোফাইল পরিবর্তন করুন:

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`	প্রোভাইডারের ক্ষেত্রে সাইনড থট টোকেনগুলো ইকো ব্যাক করা প্রয়োজন

ক্যাপাবিলিটি ফ্ল্যাগগুলো প্রতিটি প্রোভাইডার ক্লাসের readonly capabilities ফিল্ডকে অনুসরণ করে (দেখুন src/shared/providers/*-provider.ts) এবং একটি ড্রিফট সেন্টিনেল টেস্ট দ্বারা যাচাই করা হয় — ম্যাট্রিক্সটি হার্ডকোড করার পরিবর্তে রানটাইমে এই এন্ডপয়েন্টটি কল করুন।

BYOK প্রোভাইডারদের জন্য নোট:

perplexity সোনার (Sonar) মডেলগুলোর একটি কিউরেটেড তালিকা প্রকাশ করে (Perplexity-র কোনো পাবলিক /models এন্ডপয়েন্ট নেই)।
cloudflare (AI Gateway) হলো BYOK + মাল্টি-ভেন্ডর; মডেল তালিকা আপনার গেটওয়ে কনফিগারেশন দ্বারা নির্ধারিত হয় এবং /v1/providers/cloudflare/models দ্বারা একটি খালি অ্যারে (empty array) হিসেবে রিটার্ন করা হয়। আপনার নিজস্ব গেটওয়ে ক্যাটালগ ব্যবহার করুন।

একটি প্রোভাইডারের মডেল তালিকা:

GET /v1/providers/openrouter/models

ঐ প্রোভাইডারের মডেল ক্যাটালগ প্রদান করে। প্রতিটি মডেলে id, displayName, এবং যেখানে সম্ভব contextLength অন্তর্ভুক্ত থাকে। যখন প্রোভাইডারের API কী থাকে না বা এর আপস্ট্রিম ক্যাটালগ অ্যাক্সেস করা যায় না, তখন এটি 503 রিটার্ন করে।

সব প্রোভাইডারের সম্মিলিত ক্যাটালগ:

GET /v1/models

প্রতিটি কনফিগার করা প্রোভাইডারের মডেলগুলোকে একটি তালিকায় একত্রিত করে। API কী বিহীন প্রোভাইডারগুলোকে বাদ দেওয়া হয় এবং warnings-এ তালিকাভুক্ত করা হয়।

এজেন্টসমূহ

এজেন্ট হলো caiioo-এর মূল ভিত্তি। প্রতিটি এজেন্ট হলো একটি Mode — নিজস্ব সিস্টেম প্রম্পট, টুলস, ভেরিয়েবল এবং স্কিলসহ একটি কনফিগার করা ব্যক্তিত্ব।

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

GET /v1/agents

এটি বিল্টইন এজেন্ট (Shopping, Workplace, General) এবং আপনার তৈরি করা যেকোনো কাস্টম এজেন্ট রিটার্ন করে। প্রতিটি source: \"builtin\" অথবা source: \"custom\" দিয়ে ট্যাগ করা থাকে।

একটি কাস্টম এজেন্ট তৈরি করুন:

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

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

তৈরি করা এজেন্টের সাথে 201 রিটার্ন করে। সিঙ্কের জন্য একটি ভেক্টর ক্লক স্বয়ংক্রিয়ভাবে সংযুক্ত হয়।

একটি এজেন্ট আপডেট করুন:

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

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

প্যাচটিকে বিদ্যমান এজেন্টের সাথে মার্জ করে এবং ভেক্টর ক্লক আপডেট করে। বিল্টইন এজেন্টগুলো 403 রিটার্ন করে — সেগুলো শুধুমাত্র পাঠযোগ্য (read-only)।

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

DELETE /v1/agents/my-research-agent

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

Running Agents

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

Request body — সমর্থিত ফিল্ডসমূহ

ফিল্ড	প্রয়োজনীয়	বিবরণ
`agentId`	হ্যাঁ	বিল্ট-ইন মোড ID (যেমন: `general`) অথবা একটি কাস্টম এজেন্ট ID
`input.message`	হ্যাঁ	ব্যবহারকারীর মেসেজ টেক্সট
`input.attachments`	না	এই টার্নের সাথে যুক্ত করার জন্য অ্যাটাচমেন্ট ID-এর অ্যারে (যা ইতিমধ্যে `/v1/attachments`-এর মাধ্যমে আপলোড করা হয়েছে)
`input.variables`	না	প্রতি-রান ভেরিয়েবল ওভাররাইড যা এজেন্টের ভেরিয়েবল রিজলভারের সাথে মার্জ করা হয়
`input.tabContext`	না	পেজ-কনটেক্সট হিসেবে ইনজেক্ট করা ফ্রি-ফর্ম স্ট্রিং (ব্রাউজার ব্রিজ দ্বারা ব্যবহৃত)
`input.messageId`	না	ক্লায়েন্ট-প্রদত্ত মেসেজ ID — আপনি পুনরায় চেষ্টা করলে ডুপ্লিকেট এড়াতে (dedup) দরকারী
`threadId`	না	চালিয়ে যাওয়ার জন্য বিদ্যমান থ্রেড। বাদ দিলে, একটি নতুন থ্রেড তৈরি এবং রিটার্ন করা হবে
`mode`	না	`"sync"` অথবা `"async"`। ডিফল্ট হলো `"async"`

Synchronous Mode

সম্পূর্ণ রেসপন্সের জন্য অপেক্ষা করুন:

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

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

এজেন্ট শেষ করার পর { content, usage, status: "completed" } সহ 200 রিটার্ন করে। যদি এজেন্টে কোনো ত্রুটি দেখা দেয়, তবে { error, status: "error" } সহ 500 রিটার্ন করে। যদি কোনো টার্মিনাল ইভেন্ট না পাওয়া যায়, তবে Sync রানগুলো ৫ মিনিট পর status: "error" সহ টাইম আউট হয়ে যায় — দীর্ঘ সময় নিতে পারে এমন কিছুর জন্য async + SSE ব্যবহার করুন।

Asynchronous Mode

অনুরোধ পাঠিয়ে কাজ শেষ হতে দিন — দীর্ঘমেয়াদী কাজের জন্য দরকারী:

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

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

অবিলম্বে { runId, threadId, status: "running" } সহ 202 রিটার্ন করে।

স্ট্যাটাস পোল (Poll) করুন:

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 ফ্রেম পাঠায়, তারপর সংযোগটি বন্ধ করে দেয়। ক্লায়েন্টদের উচিত সেই ফ্রেমটি পাওয়াকে (অথবা সংযোগ বন্ধ হওয়াকে) রিডিং বন্ধ করার সংকেত হিসেবে গণ্য করা।

যদি রান ইতিমধ্যে শেষ হওয়ার পর আপনি সাবস্ক্রাইব করেন, তবে সার্ভার সম্পূর্ণ চূড়ান্ত record সম্বলিত RUN_SNAPSHOT টাইপের একটি ফ্রেম রিপ্লে করে, এরপর event: terminal সেন্টিনেল পাঠায় এবং সংযোগ বন্ধ করে দেয়।

একটি রান বাতিল করুন:

POST /v1/runs/{runId}/cancel

এটি { run: { ..., status: "cancelled" } } রিটার্ন করে।

Threads

Threads হলো কথোপকথন। প্রতিটি এজেন্ট রান একটি thread-এর মধ্যে ঘটে এবং সেশন শেষ হওয়ার পরেও thread-গুলো সংরক্ষিত থাকে। API আপনাকে প্রোগ্রাম্যাটিকভাবে thread-গুলোর তালিকা দেখতে, পড়তে, তৈরি করতে এবং পরিচালনা করতে দেয়।

সবগুলো thread-এর তালিকা (শুধুমাত্র 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 রিটার্ন করে — যার মধ্যে প্রতিটি ইউজার মেসেজ, অ্যাসিস্ট্যান্ট রেসপন্স, টুল কল এবং টুল রেজাল্ট অন্তর্ভুক্ত থাকে।

শুধুমাত্র মেসেজগুলো পান:

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 রিটার্ন করে। মুছে ফেলা 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"
}

এজেন্ট ওই 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 সার্ভার কনফিগারেশন রিটার্ন করে। সংবেদনশীল ফিল্ডগুলো (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"] }

প্যাচযোগ্য (Patchable) ফিল্ডগুলো POST-এর অনুমোদিত তালিকার অনুরূপ (যার মধ্যে credentialId এবং oauthConnectionId অন্তর্ভুক্ত — যা ডিলিট এবং পুনরায় তৈরি না করেই একটি OAuth কানেকশন রোটেট করার জন্য সুবিধাজনক)। সার্ভার-পরিচালিত ফিল্ডগুলো শুধুমাত্র পাঠযোগ্য (read-only) থাকবে।

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

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

{ "enabled": false }

একটি সার্ভার মুছে ফেলুন:

DELETE /v1/mcp-servers/{id}

প্রসেস ম্যানেজমেন্ট

লোকাল (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

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

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

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

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

সার্ভারে একটি র (raw) JSON-RPC 2.0 রিকোয়েস্ট পাঠায় এবং ফলাফল রিটার্ন করে। এটি ডিবাগিং বা টুলস API-এর মাধ্যমে প্রকাশ করা হয়নি এমন মেথডগুলো কল করার জন্য দরকারী।

Tools ও Toolkits

এজেন্টরা যে টুলগুলো ব্যবহার করে সেগুলো ব্রাউজ এবং ইনভোক (invoke) করুন — যেমন ওয়েব ব্রাউজিং, সার্চ, ক্যালেন্ডার, Gmail, Slate এবং আরও অনেক কিছু।

টুলকিট তালিকা (গ্রুপ করা):

GET /v1/toolkits

ক্যাটাগরি অনুযায়ী (Productivity, Search, Utilities, ইত্যাদি) গ্রুপ করা এমবেডেড টুল এবং সংযুক্ত যেকোনো MCP সার্ভারকে আলাদা টুলকিট হিসেবে রিটার্ন করে, যেখানে প্রতিটির অ্যাকশন তালিকাভুক্ত থাকে।

সব টুলের তালিকা (ফ্ল্যাট):

GET /v1/tools
GET /v1/tools?source=embedded   # শুধুমাত্র বিল্ট-ইন টুল
GET /v1/tools?source=mcp        # শুধুমাত্র MCP সার্ভার টুল

ইনপুট স্কিমাসহ টুলের বিস্তারিত তথ্য:

GET /v1/tools/calculator

এটি { tool: { name, displayName, description, source, category, inputSchema, actions?, requiredTier?, requiredRuntimes?, riskTier?, riskExplanation?, requiresApproval? } } রিটার্ন করে।

ফিল্ড	অর্থ
`inputSchema`	টুলের ইনপুটের জন্য JSON Schema — ইনভোক করার আগে যাচাই করুন
`actions`	ঐচ্ছিক সাব-অ্যাকশন (যেমন Slate-এর `read`/`write`); প্রতিটির `id`, `displayName`, `description` এবং ঐচ্ছিক `requiredTier` থাকে
`requiredTier`	ব্যবহারকারীর সর্বনিম্ন টিয়ার (বাদ দিলে `free`)। পাবলিক-API ইনভোকেশন `free`-এর উপরের যেকোনো কিছু প্রত্যাখ্যান করে
`requiredRuntimes`	যে প্ল্যাটফর্মগুলোতে এই টুলটি উপলব্ধ (`macos`, `ios`, ইত্যাদি); বাদ দিলে ⇒ সব জায়গায়
`riskTier`	সম্মতির ঝুঁকি: `low` (ডিফল্ট), `medium`, `high`
`riskExplanation`	`riskTier` কেন উচ্চতর তার মানুষের পাঠযোগ্য কারণ
`requiresApproval`	`true` যখন টুলের প্রতিটি কলের জন্য ব্যবহারকারীর অনুমোদনের প্রয়োজন হয় — পাবলিক-API ইনভোকেশন এগুলো প্রত্যাখ্যান করে

সরাসরি একটি টুল ইনভোক করুন:

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

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

এটি { result } রিটার্ন করে। ইনপুটটি টুলের স্কিমা অনুযায়ী যাচাই করা হয় — ইনপুট অবৈধ হলে বিস্তারিতসহ 422 রিটার্ন করে। যদি টুলের থ্রেড-স্কোপড কনটেক্সট (যেমন অ্যাটাচমেন্ট লুকআপ) প্রয়োজন হয় তবে একটি ঐচ্ছিক threadId পাস করুন।

গেটিং (Gating) — পাবলিক API যা প্রত্যাখ্যান করে:

টিয়ার-গেটেড টুলস (metadata.requiredTier !== 'free') → 403। এজেন্ট লুপ ব্যবহারকারীর সেশনের বিপরীতে টিয়ার যাচাই করে; পাবলিক API-তে কোনো টিয়ার কনটেক্সট থাকে না, তাই রক্ষণশীল নীতি হিসেবে এটি প্রত্যাখ্যান করা হয়। এর পরিবর্তে সঠিক টিয়ার আছে এমন এজেন্টের সাথে POST /v1/runs ব্যবহার করুন।
অনুমোদন-প্রয়োজনীয় টুলস (metadata.approval.requiresApproval === true) → 403। এখানে জিজ্ঞাসা করার মতো কোনো মানুষ লুপের মধ্যে নেই। POST /v1/runs-এর মাধ্যমে ইনভোক করুন (যা ব্যবহারকারীর কাছে প্রম্পটটি প্রদর্শন করে) অথবা বাইপাস করতে অ্যাপে টুল অ্যাপ্রুভাল মোড approve_all সেট করুন।
রিমোট MCP টুলস → 501, সাথে /v1/runs ব্যবহার করার নির্দেশনা (এগুলোর জন্য এজেন্ট সাবপ্রসেস ট্রান্সপোর্ট প্রয়োজন)।

ভিশন এবং ইমেজ-ব্যবহারকারী টুলস: প্রথমে POST /v1/attachments-এর মাধ্যমে আপলোড করুন, তারপর রিটার্ন করা অ্যাটাচমেন্ট ID-টি input-এর ভেতরে পাস করুন (যেমন { "input": { "attachment_id": "att_abc", "prompt": "What is in this image?" } })। টুলটি threadId-এর মাধ্যমে স্টোরেজ থেকে বাইনারি ফাইলটি পড়ে নেয়; আপনাকে ইনলাইনে বাইট পাস করতে হবে না।

কানেক্টরসমূহ

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 ট্রিগারগুলি এক্সটার্নাল সার্ভিসগুলোকে (CI/CD, মনিটরিং, ফর্ম বিল্ডার) HTTP-এর মাধ্যমে একটি এজেন্ট রান ট্রিগার করতে দেয়।

একটি webhook ট্রিগার তৈরি করুন:

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

যখন একটি কানেক্টেড মেসেজিং অ্যাডাপ্টার (যেমন Community Hub-এর মাধ্যমে ইনস্টল করা Slack বা Discord ইন্টিগ্রেশন) ট্রিগারের ফিল্টারের সাথে মিলে যায় এমন কোনো ইনবাউন্ড মেসেজ পায়, তখন Messaging triggers সক্রিয় হয়। 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 নোডের vm স্যান্ডবক্সে চলে (ফাইল সিস্টেম বা নেটওয়ার্ক অ্যাক্সেস নেই, ১০ সেকেন্ড টাইমআউট)। Python একটি সাবপ্রসেস হিসেবে ৩০ সেকেন্ড টাইমআউট সহ চলে। উভয়ই এক্সিকিউশনের আগে ইনপুট যাচাই করে।

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

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

Skills

Skills হলো সংরক্ষিত প্রম্পট যা এজেন্টরা রেফারেন্স হিসেবে ব্যবহার করতে পারে এবং ফাঁকা কনভারসেশন ভিউ থেকে দ্রুত লঞ্চ করতে পারে। Hub-ইনস্টল করা স্কিলগুলো (প্যাকেজ ইনস্টলের মাধ্যমে ম্যানেজ করা) এখানে অন্তর্ভুক্ত নয় — শুধুমাত্র ব্যবহারকারীর তৈরি করা স্কিলগুলো তালিকাভুক্ত এবং এডিট করা যায়।

স্কিল তালিকা:

GET /v1/skills

সক্রিয় প্রোফাইলের জন্য ব্যবহারকারীর তৈরি করা স্কিলগুলোর { skills: [...] } রিটার্ন করে। টম্বস্টোনড, হাব-ওভারলে এবং সিঙ্ক-শ্যাডো স্কিলগুলো ফিল্টার করে বাদ দেওয়া হয়।

একটি স্কিল দেখুন:

GET /v1/skills/{id}

একটি স্কিল তৈরি করুন:

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

{
  "prompt": "Summarize the page in 3 bullet points.",
  "tags": ["utility", "summarize"],
  "isFavorite": true,
  "modes": ["general"],
  "displayName": "Quick Summary",
  "description": "Three-bullet TL;DR of the active page"
}

শুধুমাত্র 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 রিটার্ন করে — পরিবর্তে সোর্স প্যাকেজটি আনইনস্টল করুন।

ওয়ার্কফ্লো

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

Error Handling

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

কোড	অর্থ
`200`	সফল
`201`	তৈরি করা হয়েছে
`202`	গৃহীত (অ্যাসিনক্রোনাস অপারেশন শুরু হয়েছে)
`204`	মুছে ফেলা হয়েছে (কোনো কন্টেন্ট নেই)
`400`	ভুল রিকোয়েস্ট — বিস্তারিত জানতে `error` ফিল্ড চেক করুন
`401`	অননুমোদিত — সেশন সিক্রেট নেই বা ভুল
`403`	নিষিদ্ধ — যেমন, একটি বিল্ট-ইন এজেন্ট পরিবর্তন করার চেষ্টা করা
`404`	পাওয়া যায়নি
`409`	দ্বন্দ্ব — যেমন, এজেন্ট ID ইতিমধ্যে বিদ্যমান
`422`	ভ্যালিডেশন ত্রুটি — ইনপুট টুল স্কিমার সাথে মিলছে না
`429`	রেট-লিমিটেড — Authentication সেকশনে রেট-লিমিট বাজেট দেখুন
`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.