Huu ni utafsiri wa mashine wa hati asili ya Kiingereza. Ikitokea mgongano wowote kati ya tafsiri hii na toleo asili la Kiingereza, toleo la Kiingereza ndilo litakalozingatiwa. Soma toleo asili la Kiingereza

API ya Umma

Caiioo inajumuisha REST API inayokuruhusu kudhibiti kila kitu kwa programu: kuendesha mawakala, kudhibiti zana, kupanga kazi, na zaidi. API inaishi kwenye seva ile ile ya ndani inayowezesha programu ya kompyuta na bridge ya kivinjari.

Base URL: http://localhost:3847/v1

Uidhinishaji: Njia mbili za kuidhinisha, zote zikidhibitiwa na swichi ya API kwenye mipangilio:

Kwa watumiaji wa nje (hati, ushirikiano, curl): Weka tokeni ya ufikiaji wa API katika Mipangilio > API Access, kisha itumie kama Bearer token:

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

Kwa programu ya ndani (otomatiki): Programu ya kompyuta ya Caiioo, viunganisho vya kivinjari, na programu za simu huidhinisha otomatiki kupitia kichwa cha uidhinishaji cha relay kilichopo (x-relay-auth). Hakuna usanidi wa mwongozo unaohitajika — programu inashughulikia hili nyuma ya pazia. Maombi ya relay-auth yanapita swichi ya Enable Public API kwa sababu tayari yanaaminika; maombi ya bearer-token pekee ndiyo yanadhibitiwa na swichi hiyo.

Usanidi:

Fungua Mipangilio ya Caiioo > API Access
Washa Enable Public API
Weka tokeni ya ufikiaji wa API (mfululizo wowote wa herufi unaochagua — ichukulie kama nywila)
Tumia tokeni hiyo katika maombi yote ya API

API inapatikana kwenye localhost na kupitia relay ya kibinafsi. Angalia GET /v1/auth/info (hakuna uidhinishaji unaohitajika) kwa hali ya sasa na maelekezo ya usanidi.

Vikomo vya kasi: kila ombi la /v1/* lina kikomo cha kasi kwa kila IP ya mteja — maombi 100 ya GET kwa dakika kwa kusoma na maombi 30 ya kuandika kwa dakika (POST / PATCH / DELETE) kwa pamoja. Maombi yanayozidi kikomo yanapata 429. Uwasilishaji wa Webhook (POST /v1/webhooks/:id) hautumii bearer-auth na hauko chini ya vikomo hivi.

Wasifu (Profiles)

Kifaa kimoja kinaweza kuwa na wasifu nyingi za watumiaji (k.m. binafsi + kazi). API inaruhusu maandishi ya nje kukagua wasifu zinazopatikana na kubadilisha ile inayotumika kabla ya kufanya kazi nyingine. Uundaji, usasishaji, na ufutaji wa wasifu haujawekwa wazi kimakusudi kupitia API ya umma — michakato hiyo ni ya UI ya kujiunga ya programu.

Orodhesha wasifu:

GET /v1/profiles

Hurudisha { profiles: [...] } ikiwa na ingizo moja kwa kila wasifu ambao haujafutwa. Kila ingizo linajumuisha id, name, email, avatarUrl, tier, accessibleModes, license, organization, preferences, onboardingComplete, createdAt, lastAccessedAt. Nyanja zenye tokeni (serviceCredentials, oauthConnections) na mambo ya ndani ya usawazishaji (vectorClock, lastModifiedBy) yameondolewa. Tumia /v1/connectors kukagua miunganisho ya OAuth.

Pata wasifu unaotumika:

GET /v1/profiles/active

Hurudisha { profile } kwa wasifu unaotumika sasa na seva hii. Rasilimali zote za /v1/* zinazohusiana na wasifu (threads, viambatisho, mipangilio, ujuzi) hufanya kazi dhidi ya wasifu huu.

Badilisha wasifu unaotumika:

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

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

Hurudisha { profile } kwa wasifu mpya uliowashwa. Hurudisha 404 ikiwa ID si ya wasifu unaojulikana.

Watoaji & Mifano

Gundua ni watoaji gani wa LLM wamesanidiwa na ni mifano gani inayopatikana.

Orodhesha watoaji:

GET /v1/providers

Inarudisha kila aina ya mtoaji anayeungwa mkono. Kwa sasa: anthropic, openai, google, openrouter, ollama, poe, mlx, perplexity, baseten, cloudflare. Kila ingizo linajumuisha type, displayName, icon, requiresApiKey, hasApiKey, na kitu cha capabilities chenye alama hapa chini.

Alama ya uwezo	Maana
`supportsVision`	Mtoaji anaweza kupokea picha kama ingizo
`supportsPdfFile`	Mtoaji anaweza kupokea maudhui ya faili ghafi ya PDF asilia
`supportsToolCalling`	Mtoaji anaruhusu utendaji wa function/tool calling
`supportsStreaming`	Mtoaji hutiririsha tokeni hatua kwa hatua
`supportsExtendedThinking`	Mtoaji anatoa uwezo wa bajeti ya kufikiri/reasoning
`supportsPromptCaching`	Mtoaji anaruhusu maelekezo ya prompt-cache
`nativeReasoningBlocks`	Mtoaji hutoa fikra kama vizuizi asilia vya ujumbe (badala ya maandishi)
`requiresThoughtSignature`	Mtoaji anahitaji tokeni za fikra zilizotiwa saini zirudishwe

Alama za uwezo zinaakisi uwanja wa readonly capabilities wa kila darasa la mtoaji (angalia src/shared/providers/*-provider.ts) na zinathibitishwa na jaribio la drift sentinel — piga endpoint hii wakati wa utekelezaji badala ya kuandika matrix hiyo moja kwa moja kwenye kodi.

Vidokezo kwa watoaji wa BYOK:

perplexity hutoa orodha iliyochaguliwa ya mifano ya Sonar (Perplexity haina endpoint ya umma ya /models).
cloudflare (AI Gateway) ni BYOK + wauzaji wengi; orodha ya mifano inatambuliwa na usanidi wa gateway yako na inarudishwa kama safu tupu na /v1/providers/cloudflare/models. Tumia katalogi yako mwenyewe ya gateway.

Orodhesha mifano ya mtoaji:

GET /v1/providers/openrouter/models

Inarudisha katalogi ya mifano ya mtoaji huyo. Kila mfano unajumuisha id, displayName, na contextLength pale inapopatikana. Inarudisha 503 wakati mtoaji hana API key au katalogi yake ya juu haipatikani.

Katalogi ya pamoja ya watoaji wote:

GET /v1/models

Inaunganisha mifano kutoka kwa kila mtoaji aliyesanidiwa kuwa orodha moja. Watoaji wasio na API key wanarukwa na kuorodheshwa kwenye warnings.

Mawakala

Mawakala ndio msingi wa caiioo. Kila wakala ni Njia — haiba iliyosanidiwa na maelekezo yake ya mfumo, zana, vigezo, na ujuzi.

Orodhesha mawakala wote:

GET /v1/agents

Inarudisha mawakala waliojengwa ndani (Shopping, Workplace, General) na mawakala wowote maalum uliounda. Kila mmoja amewekwa alama ya source: \"builtin\" au source: \"custom\".

Unda wakala maalum:

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

{
  \"id\": \"my-research-agent\",
  \"branding\": {
    \"name\": \"Research Agent\",
    \"description\": \"Inatafuta kwenye wavuti na kufupisha matokeo\"
  },
  \"defaultSettings\": {
    \"systemPrompt\": \"Wewe ni msaidizi wa utafiti. Daima taja vyanzo.\",
    \"enabledTools\": { \"web_browsing\": true, \"search_tools\": true }
  },
  \"settingLevels\": {}
}

Inarudisha 201 pamoja na wakala aliyeundwa. Saa ya vekta inaunganishwa kiotomatiki kwa ajili ya usawazishaji.

Sasisha wakala:

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

{ \"branding\": { \"name\": \"Research Agent\", \"description\": \"Maelezo yaliyosasishwa\" } }

Inaunganisha kiraka kwenye wakala aliyepo na kuongeza saa ya vekta. Mawakala waliojengwa ndani wanarudisha 403 — ni wa kusoma tu.

Futa wakala:

DELETE /v1/agents/my-research-agent

Inafuta kwa njia ya muda (inasawazishwa kwenye vifaa). Inarudisha 204.

Kuendesha Agents

Hili ndilo tukio kuu — amuru agent kuchakata ujumbe.

Sehemu ya maombi (Request body) — sehemu zinazotumika

Sehemu	Inahitajika	Maelezo
`agentId`	ndiyo	ID ya hali iliyojengwa ndani (k.m. `general`) au ID ya agent maalum
`input.message`	ndiyo	Maandishi ya ujumbe wa mtumiaji
`input.attachments`	hapana	Safu ya ID za viambatisho (ambavyo tayari vimepakiwa kupitia `/v1/attachments`) ili kuambatisha kwenye zamu hii
`input.variables`	hapana	Mapendeleo ya vigezo kwa kila mzunguko yaliyounganishwa kwenye kisuluhishi cha vigezo cha agent
`input.tabContext`	hapana	Maandishi huru yaliyoingizwa kama muktadha wa ukurasa (hutumiwa na daraja la kivinjari)
`input.messageId`	hapana	ID ya ujumbe iliyotolewa na mteja — muhimu kwa ajili ya kuondoa nakala ikiwa utajaribu tena
`threadId`	hapana	Thread iliyopo ya kuendeleza. Ikiwa itaachwa, thread mpya itaundwa na kurudishwa
`mode`	hapana	`"sync"` au `"async"`. Chaguo-msingi ni `"async"`

Hali ya Synchronous

Subiri jibu kamili:

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

{
  "agentId": "general",
  "input": { "message": "Hali ya hewa ikoje Paris leo?" },
  "mode": "sync"
}

Inarudisha 200 ikiwa na { content, usage, status: "completed" } baada ya agent kumaliza. Ikiwa agent atapata hitilafu, inarudisha 500 ikiwa na { error, status: "error" }. Mizunguko ya Sync hukatika baada ya dakika 5 ikiwa na status: "error" ikiwa hakuna tukio la mwisho lililopokelewa — tumia async + SSE kwa chochote kinachoweza kuchukua muda mrefu zaidi.

Hali ya Asynchronous

Tuma na uendelee — muhimu kwa kazi zinazochukua muda mrefu:

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

{
  "agentId": "my-research-agent",
  "input": { "message": "Andika uchambuzi wa maneno 2000 kuhusu mienendo ya nishati mbadala" },
  "mode": "async"
}

Inarudisha 202 mara moja ikiwa na { runId, threadId, status: "running" }.

Ulizia hali (Poll for status):

GET /v1/runs/{runId}

Inarudisha { run: { runId, threadId, agentId, status, createdAt, content?, usage?, error? } }. Hali ni mojawapo ya running, completed, error, au cancelled.

Tiririsha matukio mubashara (SSE):

GET /v1/runs/{runId}/events

Inarudisha text/event-stream ikiwa na kila tukio la agent linapotokea: GENERATION_STARTED, STREAMING_CONTENT, miito ya zana, shughuli za subagent, na tukio la mwisho (GENERATION_COMPLETE, GENERATION_ERROR, au GENERATION_CANCELLED).

Baada ya tukio la mwisho, seva hutoa fremu moja ya mwisho ya SSE ikiwa na event: terminal na data tupu kama ishara ya wazi ya mwisho wa mtiririko, kisha inafunga muunganisho. Wateja wanapaswa kuchukulia upokeaji wa fremu hiyo (au kufungwa kwa muunganisho) kama ishara ya kuacha kusoma.

Ikiwa utajiunga baada ya mzunguko kumalizika, seva hurudia fremu moja ya aina ya RUN_SNAPSHOT iliyo na record kamili ya mwisho, ikifuatiwa na ishara ya event: terminal, kisha inafunga.

Ghairi mzunguko:

POST /v1/runs/{runId}/cancel

Inarudisha { run: { ..., status: "cancelled" } }.

Threads

Threads ni mazungumzo. Kila uendeshaji wa agent hufanyika ndani ya thread, na threads huendelea kuwepo katika vipindi vyote vya matumizi. API inakuwezesha kuorodhesha, kusoma, kuunda, na kudhibiti threads kupitia programu.

Orodhesha threads zote (metadata pekee):

GET /v1/threads

Inarudisha { threads: [...] } kwa wasifu wa sasa huku messages zikiwa zimeondolewa (tumia endpoint ya maelezo zaidi unapozihitaji). Kila uwanja mwingine umehifadhiwa — id, title, createdAt, updatedAt, modeId, archived, takwimu za matumizi, pamoja na subAgentHistories, anonymizerSnapshot, threadToolApprovals, threadVariables, threadToolOverrides, messagingBinding, scheduledTaskId zinapowekwa. (Data hizi nyingi zinapatikana pekee kwenye API — utangazaji wa sidebar wa WebSocket unatumia data iliyopunguzwa zaidi ili kubaki chini ya mipaka ya usafirishaji.)

Pata thread ikiwa na ujumbe kamili:

GET /v1/threads/{id}

Inarudisha thread kamili ikiwa ni pamoja na safu yake ya messages — kila ujumbe wa mtumiaji, jibu la assistant, wito wa tool, na matokeo ya tool.

Pata ujumbe pekee:

GET /v1/threads/{id}/messages

Inarudisha safu ya messages pekee — nyepesi kuliko object kamili ya thread unapohitaji mazungumzo pekee.

Unda thread:

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

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

Inarudisha 201 ikiwa na { thread }. Thread mpya inaonekana kwenye sidebar mara moja (kupitia utangazaji wa WebSocket). API haibadilishi thread inayotumika ya programu wakati wa kuunda — piga PUT /v1/threads/active kando ikiwa unataka hilo.

Sasisha thread:

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

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

Nyanja zinazoweza kusasishwa: title, modeId, archived, lastUsedModel. Mabadiliko yanatangazwa kwenye sidebar kwa wakati halisi.

Futa thread:

DELETE /v1/threads/{id}

Inafuta thread kwa muda (tombstone kwa ajili ya sync). Inarudisha 204. Threads zilizofutwa huhamia kwenye trash na zinaweza kurejeshwa hadi trash itakapofutwa kabisa.

Thread inayotumika:

GET /v1/threads/active            # Inarudisha { threadId }
PUT /v1/threads/active            # Body: { "threadId": "..." }

Usimamizi wa trash:

GET /v1/threads/trash/count       # Inarudisha { count }
POST /v1/threads/trash/empty      # Inarudisha { deletedCount, protectedCount }

Threads zilizolindwa (zinazohifadhiwa kupitia swichi ya uhifadhi wa data) hazijumuishwi wakati wa kufuta trash.

Kuendeleza mazungumzo kupitia API: Ili kutuma ujumbe wa kufuatilia kwenye thread iliyopo, tumia POST /v1/runs ukiwa na ID ya thread:

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

{
  "agentId": "general",
  "threadId": "existing-thread-id",
  "input": { "message": "Follow up on that last point" },
  "mode": "sync"
}

Agent huona historia kamili ya mazungumzo kutoka kwenye thread hiyo.

Viambatisho

Viambatisho ni faili zilizounganishwa kwenye nyuzi — picha za skrini, PDF, hati, picha zilizopakiwa, mabaki yaliyozalishwa. API inakuruhusu kuorodhesha, kupakia, kupakua, na kuvidhibiti.

Orodhesha viambatisho vyote (metadata pekee):

GET /v1/attachments

Hurudisha metadata ya kiambatisho kwa wasifu wa sasa. Mashamba mazito (dataUrl, extractedContent, extractedImages) yameondolewa — tumia sehemu za mwisho za maelezo au maudhui kwa ajili ya hayo.

Orodhesha viambatisho vya uzi maalum:

GET /v1/threads/{threadId}/attachments

Pata metadata ya kiambatisho:

GET /v1/attachments/{id}

Hurudisha metadata kamili ikiwa ni pamoja na extractedContent (maandishi ya OCR, markdown iliyochanganuliwa), contentType, fileName, size, na alama ya hasContent. Faili ghafi HAIJAJUMUISHWA — tumia sehemu ya mwisho ya /content kwa ajili hiyo.

Pakua faili ghafi ya kiambatisho:

GET /v1/attachments/{id}/content

Hurudisha faili ghafi ikiwa na vichwa sahihi vya Content-Type na Content-Disposition. Elekeza hii kwenye faili:

curl -o output.pdf \
  -H "Authorization: Bearer $API_TOKEN" \
  http://localhost:3847/v1/attachments/{id}/content

Pakia kiambatisho:

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

{
  "threadId": "thread-id",
  "type": "user_upload",
  "contentType": "application/pdf",
  "fileName": "report.pdf",
  "description": "Ripoti ya robo mwaka",
  "dataUrl": "data:application/pdf;base64,JVBERi0xLjQ..."
}

dataUrl ni URL ya data iliyosimbwa kwa base64. Hurudisha 201 ikiwa na kitambulisho kipya cha kiambatisho. Kiambatisho kinaunganishwa kwenye uzi uliotajwa.

Sasisha metadata ya kiambatisho:

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

{ "description": "Maelezo yaliyosasishwa", "fileName": "new-name.pdf" }

Futa kiambatisho:

DELETE /v1/attachments/{id}

Hufuta kwa njia ya muda. Hurudisha 204.

Seva za MCP

Dhibiti miunganisho yako ya seva ya MCP (Model Context Protocol) — seva zinazowapa mawakala ufikiaji wa zana za nje na vyanzo vya data.

Orodhesha seva zilizosanidiwa:

GET /v1/mcp-servers

Inarudisha usanidi wote wa seva ya MCP kwa wasifu wa sasa. Sehemu nyeti (authToken, env, credentialId) huondolewa kwenye jibu.

Pata usanidi wa seva:

GET /v1/mcp-servers/{id}

Ongeza seva mpya ya 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"
}

Kwa seva za mbali za HTTP, tumia "url" badala ya "command":

{
  "id": "remote-server",
  "name": "Remote API",
  "url": "https://my-mcp-server.example.com/sse",
  "serverType": "remote"
}

Sehemu za hiari zinazokubaliwa kwenye POST: command, args, env, url, description, transportType, authType, authToken, authHeader, headers, specType, specPath, timeoutMs, credentialId, oauthConnectionId, approval. Sehemu zinazosimamiwa na seva (customOAuth, hubPackageId, profileId, connectorId, teamPublished, teamOrgId, vectorClock, ...) haziwezi kuwekwa kupitia API.

Sasisha seva:

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

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

Sehemu zinazoweza kufanyiwa Patch zinafanana na orodha iliyoruhusiwa ya POST (ikiwa ni pamoja na credentialId na oauthConnectionId — muhimu kwa kubadilisha muunganisho wa OAuth bila kufuta na kuunda upya). Sehemu zinazosimamiwa na seva zinabaki kuwa za kusoma tu.

Washa/zima seva:

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

{ "enabled": false }

Futa seva:

DELETE /v1/mcp-servers/{id}

Usimamizi wa Michakato

Kwa seva za ndani (stdio) za MCP, unaweza kudhibiti mchakato wa seva moja kwa moja.

Orodhesha michakato inayofanya kazi:

GET /v1/mcp-servers/processes

Inarudisha michakato ya seva inayofanya kazi ikiwa na pid, startedAt, na hali ya running.

Anzisha seva:

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

Inasoma command/args/env kutoka kwenye usanidi wa seva na kuanzisha mchakato. Inarudisha hali ya mchakato.

Simamisha seva:

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

Inazima mchakato wa seva kwa usalama (SIGTERM ikifuatiwa na SIGKILL ikiwa itashindikana).

Ita mbinu ya JSON-RPC moja kwa moja:

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

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

Inatuma ombi ghafi la JSON-RPC 2.0 kwa seva na kurudisha matokeo. Ni muhimu kwa utatuzi wa hitilafu au kuita mbinu ambazo hazijawekwa wazi kupitia API ya zana.

Zana & Seti za Zana (Toolkits)

Vinjari na uwashe zana ambazo mawakala hutumia — kuvinjari wavuti, utafutaji, kalenda, Gmail, Slate, na nyinginezo.

Orodhesha seti za zana (zilizopangwa):

GET /v1/toolkits

Inarudisha zana zilizojumuishwa zikiwa zimepangwa kwa kategoria (Productivity, Search, Utilities, n.k.) na seva zozote za MCP zilizounganishwa kama seti za zana tofauti, kila moja ikiwa na vitendo vyake vilivyoorodheshwa.

Orodhesha zana zote (orodha bapa):

GET /v1/tools
GET /v1/tools?source=embedded   # Zana zilizojengwa ndani pekee
GET /v1/tools?source=mcp        # Zana za seva ya MCP pekee

Pata maelezo ya zana pamoja na skima ya ingizo (input schema):

GET /v1/tools/calculator

Inarudisha { tool: { name, displayName, description, source, category, inputSchema, actions?, requiredTier?, requiredRuntimes?, riskTier?, riskExplanation?, requiresApproval? } }.

Sehemu	Maana
`inputSchema`	JSON Schema kwa ajili ya ingizo la zana — thibitisha kabla ya kuwasha
`actions`	Vitendo vidogo vya hiari (k.m. Slate `read`/`write`); kila kimoja kina `id`, `displayName`, `description`, `requiredTier` ya hiari
`requiredTier`	Kiwango cha chini cha mtumiaji (`free` ikiachwa). Uwashaji wa API ya umma unakataa chochote kilicho juu ya `free`
`requiredRuntimes`	Mifumo ambapo zana hii inapatikana (`macos`, `ios`, n.k.); acha wazi ⇒ kila mahali
`riskTier`	Hatari ya idhini: `low` (msingi), `medium`, `high`
`riskExplanation`	Sababu inayosomeka na binadamu kwa nini `riskTier` imepandishwa
`requiresApproval`	`true` wakati zana inahitaji idhini ya mtumiaji kwa kila wito — uwashaji wa API ya umma unakataa hizi

Washa zana moja kwa moja:

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

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

Inarudisha { result }. Ingizo linathibitishwa dhidi ya skima ya zana — ingizo batili linarudisha 422 likiwa na maelezo. Tuma threadId ya hiari ikiwa zana inahitaji muktadha wa thread (k.m. utafutaji wa viambatisho).

Vizuizi — kile ambacho API ya umma inakataa:

Zana zenye vizuizi vya kiwango (Tier) (metadata.requiredTier !== 'free') → 403. Mzunguko wa wakala unakagua kiwango dhidi ya kikao cha mtumiaji; API ya umma haina muktadha wa kiwango uliobebwa, hivyo sera ya tahadhari ni kukataa. Tumia POST /v1/runs ukiwa na wakala mwenye kiwango sahihi badala yake.
Zana zinazohitaji idhini (metadata.approval.requiresApproval === true) → 403. Hakuna binadamu kwenye mzunguko wa kuulizwa. Washa kupitia POST /v1/runs (ambayo huonyesha ombi kwa mtumiaji) au weka hali ya idhini ya zana kuwa approve_all kwenye programu ili kupita kizuizi hiki.
Zana za mbali za MCP → 501 ikiwa na mwongozo wa kutumia /v1/runs (zinahitaji usafirishaji wa mchakato mdogo wa wakala).

Zana za uoni (Vision) na zinazotumia picha: pakia kupitia POST /v1/attachments kwanza, kisha tuma ID ya kiambatisho iliyorudishwa ndani ya input (k.m. { "input": { "attachment_id": "att_abc", "prompt": "Kuna nini kwenye picha hii?" } }). Zana husoma data ya binary kutoka kwenye hifadhi kupitia threadId; hautumi baiti (bytes) moja kwa moja.

Viunganishi

Dhibiti ushirikiano wa OAuth — Google, Microsoft, GitHub, Notion, Slack, na zaidi.

Vinjari ushirikiano unaopatikana:

GET /v1/connectors/catalog

Inarudisha watoa huduma wote wa OAuth waliosajiliwa na majina yao, kategoria, na upeo wa msingi.

Orodhesha akaunti zako zilizounganishwa:

GET /v1/connectors

Inarudisha viunganisho vinavyofanya kazi kwa wasifu wa sasa. Tokeni hazionyeshwi kamwe — metadata pekee (mtoa huduma, barua pepe, hali, upeo, alama za muda).

Pata kiunganisho kimoja:

GET /v1/connectors/{id}

Inarudisha metadata ya kiunganisho kimoja. Tokeni hazionyeshwi kamwe.

Angalia afya ya kiunganisho:

POST /v1/connectors/{id}/test

Inarudisha { health: { status, isTokenExpired, canRefresh } }.

Ondoa kiunganisho:

DELETE /v1/connectors/{id}

Kuunda viunganisho vipya kunahitaji mtiririko wa OAuth wa kuingiliana kupitia UI ya programu au njia za /auth/*.

Vichochezi (Triggers)

Panga mawakala kujiendesha kiotomatiki — muhtasari wa kila siku, ripoti za kila wiki, ufuatiliaji wa vipindi maalum.

Kila kichochezi kina kibaguzi cha kind: schedule (msingi — hufanya kazi kwa saa), webhook (hufanya kazi huduma ya nje inapofanya POST kwenye njia ya webhook), au messaging (hufanya kazi kutoka kwa adapta ya ujumbe iliyounganishwa — k.m. ujumbe wa Slack/Discord unaoingia unaolingana na chujio la chaneli).

Orodhesha vichochezi:

GET /v1/triggers

Hurudisha { triggers: [...] }. Kila ingizo linajumuisha kind yake, ratiba, na nyanja mahususi za aina hiyo (k.m. webhookSecret/webhookPath kwa vichochezi vya webhook, messagingAdapterId/messagingChannelFilter kwa vichochezi vya ujumbe).

Pata kichochezi kimoja:

GET /v1/triggers/{id}

Unda kichochezi kilichoratibiwa:

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

{
  "name": "Morning Briefing",
  "prompt": "Summarize my unread emails and today's calendar",
  "modeId": "general",
  "schedule": { "type": "daily", "time": "08:00" }
}

Aina za ratiba zinazotumika:

{ "type": "interval", "minutes": 60 } — kila baada ya dakika N (min 15, max 1440)
{ "type": "daily", "time": "09:00" } — kila siku kwa muda maalum
{ "type": "weekly", "day": "mon", "time": "09:00" } — kila wiki
{ "type": "weekdays", "time": "08:30" } — Jumatatu hadi Ijumaa
{ "type": "daysOfWeek", "days": ["mon", "wed", "fri"], "time": "10:00" } — siku maalum
{ "type": "monthly", "dayOfMonth": 1, "time": "09:00" } — kila mwezi
{ "type": "manual" } — pale tu inapochochewa kupitia API

Washa kichochezi kwa mikono:

POST /v1/triggers/{id}/fire

Hurudisha 202 ikiwa na threadId kwa ajili ya mchakato unaofuata.

Sasisha au futa:

PATCH /v1/triggers/{id}
DELETE /v1/triggers/{id}

Webhooks

Vichochezi vya Webhook huruhusu huduma za nje (CI/CD, ufuatiliaji, wajenzi wa fomu) kuchochea mchakato wa wakala kupitia HTTP.

Unda kichochezi cha webhook:

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

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

Hurudisha 201 ikiwa na webhookSecret na webhookPath. Hifadhi siri hiyo — utaihitaji ili kusaini mizigo ya data (payloads).

Tuma webhook:

# Kokotoa HMAC-SHA256 ya mwili ghafi wa ombi
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"}

Endpoint ya webhook HAIHITAJI bearer auth — inatumia uthibitishaji wa HMAC badala yake. Hurudisha 202 ikiwa na threadId ya mchakato uliotumwa. Kishika-nafasi cha {{webhook.body}} katika agizo la kichochezi hubadilishwa na mwili ghafi wa ombi.

Vichochezi vya Ujumbe (Messaging triggers)

Vichochezi vya ujumbe huwaka wakati adapta ya ujumbe iliyounganishwa (k.m. muunganisho wa Slack au Discord uliowekwa kupitia Community Hub) inapopokea ujumbe unaoingia unaolingana na chujio la kichochezi. Unda kwa 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"
}

Adapta inahusika na kutuma matukio yanayolingana kwenye kichochezi; messagingChannelFilter inategemea adapta husika.

Kazi Maalum

Unda zana zako mwenyewe ambazo mawakala wanaweza kuziita. Kazi huandikwa kwa JavaScript au Python na huendeshwa katika mazingira yaliyotengwa (sandbox).

Orodhesha kazi:

GET /v1/functions

Unda kazi:

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

{
  "name": "calculate_bmi",
  "description": "Kokotoa Kielezo cha Uzito wa Mwili (BMI) kutoka kwenye urefu na uzito",
  "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"]
  }
}

Kazi za JavaScript hupokea input na lazima zirudishe matokeo. Kazi za Python huweka kigezo cha result:

# Mfano wa Python
result = {"bmi": round(input["weightKg"] / (input["heightM"] ** 2), 1)}

Tekeleza kazi moja kwa moja:

POST /v1/functions/{id}/execute
Content-Type: application/json

{ "input": { "weightKg": 75, "heightM": 1.80 } }

Usalama: JavaScript huendeshwa katika sandbox ya vm ya Node (hakuna ufikiaji wa mfumo wa faili au mtandao, kikomo cha muda cha sekunde 10). Python huendeshwa kama mchakato mdogo wenye kikomo cha muda cha sekunde 30. Zote mbili huthibitisha ingizo kabla ya utekelezaji.

Sasisha au futa:

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

Ujuzi (Skills)

Ujuzi ni maagizo yaliyohifadhiwa ambayo mawakala wanaweza kurejelea na kuzindua haraka kutoka kwenye mwonekano wa mazungumzo tupu. Ujuzi uliowekwa kupitia Hub (unaosimamiwa kupitia usakinishaji wa kifurushi) HAUJAJUMUISHWA hapa — ni ujuzi tu ulioandikwa na mtumiaji ndio unaoorodheshwa na kuweza kuhaririwa.

Orodhesha ujuzi:

GET /v1/skills

Hurudisha { skills: [...] } ya ujuzi ulioandikwa na mtumiaji kwa wasifu unaotumika. Ujuzi uliofutwa, ule wa hub-overlay, na sync-shadow huchujwa na kuondolewa.

Pata ujuzi mmoja:

GET /v1/skills/{id}"

Unda ujuzi:

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 pekee ndiyo inayohitajika. modes (hiari) huweka ujuzi kwenye ID maalum za mawakala; acha wazi kwa ajili ya modes zote. Hurudisha 201 ikiwa na ujuzi mpya (pamoja na id, createdAt, updatedAt zilizopangwa na seva).

Sasisha ujuzi:

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

{ "prompt": "Updated prompt", "isFavorite": false }

Nyanja zinazoweza kusasishwa: prompt, tags, modes, displayName, description, isFavorite. Jaribio la kusasisha ujuzi wa hub-overlay litarudisha 404.

Futa ujuzi:

DELETE /v1/skills/{id}

Hufuta kwa muda kupitia tombstone. Hurudisha 204. Ujuzi wa hub-overlay hurudisha 404 — badala yake ondoa kifurushi chanzo.

Mitiririko ya Kazi

Panga mawakala wengi katika DAG (directed acyclic graph) — endesha hatua kwa sambamba inapowezekana, na lisha matokeo kutoka hatua za awali kwenda hatua za baadaye.

Thibitisha grafu ya mtiririko wa kazi:

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

{
  "graph": {
    "nodes": [
      { "id": "research", "agentId": "general", "prompt": "Tafiti mienendo ya nishati mbadala" },
      { "id": "analyze", "agentId": "general", "prompt": "Tafiti bei za washindani" },
      { "id": "report", "agentId": "general", "prompt": "Andika ripoti inayounganisha: {{outputs.research}} na {{outputs.analyze}}", "dependsOn": ["research", "analyze"] }
    ]
  }
}

Hurudisha { valid: true/false, errors: [...] }. Hukagua mizunguko, vitambulisho vilivyojirudia, na marejeleo ya utegemezi yanayokosekana.

Tekeleza mtiririko wa kazi:

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

{
  "graph": {
    "nodes": [
      { "id": "research", "agentId": "general", "prompt": "Tafiti mienendo ya nishati mbadala" },
      { "id": "summarize", "agentId": "general", "prompt": "Fanya muhtasari wa: {{outputs.research}}", "dependsOn": ["research"] }
    ]
  }
}

Hurudisha { status: "completed", outputs: { research: "...", summarize: "..." }, nodeResults: {...} }.

Nodi zinazojitegemea (zisizo na utegemezi wa pamoja) huendeshwa kwa sambamba. Kishika nafasi cha {{outputs.nodeId}} katika maelekezo ya nodi hubadilishwa na matokeo ya maudhui ya nodi ya juu iliyotajwa. Kila nodi ni uendeshaji kamili wa wakala, hivyo inaweza kutumia zana, kuvinjari wavuti, na kufikia uwezo wote wa wakala lengwa.

Kanzi za Maarifa

Panga nyaraka katika makusanyo yanayoweza kutafutwa ambayo mawakala wanaweza kuyarejelea.

Orodhesha kanzi za maarifa:

GET /v1/knowledge/bases

Unda kanzi ya maarifa:

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

{ "name": "Makala za Utafiti" }

Hurudisha 201 ikiwa na kitambulisho kipya cha kanzi.

Pakia hati kwenye kanzi ya maarifa:

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

{
  "fileName": "research-paper.pdf",
  "contentType": "application/pdf",
  "dataUrl": "data:application/pdf;base64,JVBERi0xLjQ...",
  "description": "Mienendo ya nishati mbadala 2026"
}

Uwanja wa dataUrl ni URL ya data iliyosimbwa kwa base64. Hurudisha 201 ikiwa na metadata ya hati.

Orodhesha hati katika kanzi ya maarifa:

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

Tafuta ndani ya kanzi ya maarifa:

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

{ "query": "nishati mbadala" }

Hurudisha hati zinazolingana kulingana na jina la faili na maelezo. Utafutaji wa kisemantiki (vekta) unakuja katika toleo lijalo.

Futa hati au kanzi ya maarifa:

DELETE /v1/knowledge/bases/{id}/documents/{docId}
DELETE /v1/knowledge/bases/{id}

Hamisha na Ingiza Mawakala

Shiriki mawakala kama vifurushi vinavyobebeka — kwenye vifaa, timu, au Community Hub.

Hamisha wakala:

POST /v1/agents/{id}/export

Inarudisha kifurushi cha JSON chenye ufafanuzi wa wakala, mahitaji ya zana (yaliyotokana na zana zilizowashwa), mahitaji ya kiunganishi (ni watoa huduma gani wa OAuth wanahitajika), na templeti za vichochezi. Metadata ya usawazishaji inaondolewa — kifurushi ni ramani safi inayojitegemea.

Ingiza wakala:

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

{
  \"package\": {
    \"$schema\": \"caiioo.agent.package/v1\",
    \"agent\": {
      \"id\": \"shared-research-agent\",
      \"branding\": { \"name\": \"Research Agent\", \"description\": \"Kutoka kwa timu\" },
      \"defaultSettings\": { \"systemPrompt\": \"Unafanya utafiti wa mambo.\" },
      \"settingLevels\": {}
    },
    \"toolRequirements\": [
      { \"toolId\": \"web_browsing\", \"enabled\": true },
      { \"toolId\": \"search_tools\", \"enabled\": true }
    ]
  }
}

Inarudisha 201 pamoja na wakala aliyesakinishwa. Migongano ya ID na mawakala waliojengwa ndani au waliopo inarudisha 409.

Kushughulikia Hitilafu

API inatumia misimbo ya hali ya kawaida ya HTTP:

Msimbo	Maana
`200`	Mafanikio
`201`	Imeundwa
`202`	Imekubaliwa (operesheni isiyo ya moja kwa moja imeanza)
`204`	Imefutwa (hakuna maudhui)
`400`	Ombi baya — angalia nyanja ya `error` kwa maelezo
`401`	Hapana idhini — siri ya kikao haipo au si sahihi
`403`	Imekatazwa — k.m., kujaribu kurekebisha wakala wa ndani
`404`	Haipatikani
`409`	Mgongano — k.m., ID ya wakala tayari ipo
`422`	Hitilafu ya uhalali — ingizo halilingani na schema ya zana
`429`	Kikomo cha kasi kimefikiwa — angalia bajeti za kikomo cha kasi katika sehemu ya Uthibitishaji
`500`	Hitilafu ya seva — angalia nyanja ya `error`
`501`	Haitekelezwi — kipengele kipo lakini hakipatikani kwa njia hii
`503`	Huduma haipatikani — hifadhi au mtoa huduma hayuko tayari

Majibu yote ya hitilafu yanajumuisha { "error": "ujumbe unaosomeka na binadamu" }.

Mfano wa Kuanza Haraka

Huu hapa ni mtiririko kamili wa kazi: unda wakala, uendeshe, na utiririshe matokeo.

# 1. Unda wakala maalum
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": "Fanya muhtasari wa ingizo lolote kwa ufupi katika nukta 3.",
      "enabledTools": { "web_browsing": true }
    },
    "settingLevels": {}
  }'

# 2. Uendeshe bila kusubiri
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. Tiririsha matukio
curl -N http://localhost:3847/v1/runs/$RUN_ID/events \
  -H "Authorization: Bearer $API_TOKEN"

# 4. Hamisha wakala kwa ajili ya kushiriki
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.