Ito ay isang machine translation ng orihinal na dokumentong Ingles. Sa kaganapan ng anumang salungatan sa pagitan ng pagsasaling ito at ng orihinal na bersyong Ingles, ang bersyong Ingles ang mangingibabaw. Basahin ang orihinal na bersyong Ingles

Public API

Ang Caiioo ay may kasamang REST API na nagbibigay-daan sa iyong kontrolin ang lahat sa pamamagitan ng programming: magpatakbo ng mga agent, mamahala ng mga tool, mag-iskedyul ng mga gawain, at marami pang iba. Ang API ay nasa parehong lokal na server na nagpapatakbo sa desktop app at browser bridge.

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

Authentication: Dalawang paraan para mag-authenticate, parehong kinokontrol ng API toggle sa mga setting:

Para sa mga external consumer (mga script, integration, curl): Magtakda ng API access token sa Mga Setting > API Access, pagkatapos ay gamitin ito bilang Bearer token:

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

Para sa lokal na app (awtomatiko): Ang Caiioo desktop app, mga extension sa browser, at mga mobile app ay awtomatikong nag-a-authenticate sa pamamagitan ng umiiral na relay auth header (X-Relay-Auth). Walang kailangang manual na setup — ang app na ang bahala rito sa background.

Setup:

  1. Buksan ang Caiioo Mga Setting > API Access
  2. I-on ang I-enable ang Public API
  3. Magtakda ng API access token (anumang string na gusto mo — ituring itong parang password)
  4. Gamitin ang token na iyon sa lahat ng API request

Ang API ay available sa localhost at sa pamamagitan ng private relay. I-check ang GET /v1/auth/info (walang auth na kailangan) para sa kasalukuyang status at mga tagubilin sa pag-setup.

Mga Provider at Modelo

Alamin kung aling mga LLM provider ang naka-configure at kung anong mga modelo ang available.

I-lista ang mga provider:

GET /v1/providers

Ibinabalik ang lahat ng naka-configure na uri ng provider (Anthropic, OpenAI, Google, OpenRouter, Ollama, Poe, MLX, Baseten, at iba pa habang idinaragdag ang mga ito) kasama ang mga capability flag (supportsVision, supportsToolCalling, supportsStreaming, atbp.) at kung may naka-configure na API key.

I-lista ang mga modelo para sa isang provider:

GET /v1/providers/anthropic/models

Ibinabalik ang catalog ng modelo para sa provider na iyon. Bawat modelo ay may kasamang id, displayName, at contextLength kung available.

Flat catalog sa lahat ng provider:

GET /v1/models

Pinagsasama ang mga modelo mula sa bawat naka-configure na provider sa isang listahan. Ang mga provider na walang API key ay lalaktawan at ililista sa warnings.

Mga Agent

Ang mga agent ang puso ng caiioo. Ang bawat agent ay isang Mode — isang na-configure na personalidad na may sariling system prompt, mga tool, variable, at skills.

Ilista ang lahat ng agent:

GET /v1/agents

Nagbabalik ng mga builtin agent (Shopping, Workplace, General) at anumang custom agent na iyong ginawa. Ang bawat isa ay naka-tag ng source: \"builtin\" o source: \"custom\".

Gumawa ng custom agent:

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

{
  \"id\": \"my-research-agent\",
  \"branding\": {
    \"name\": \"Research Agent\",
    \"description\": \"Naghahanap sa web at nagbubuod ng mga natuklasan\"
  },
  \"defaultSettings\": {
    \"systemPrompt\": \"Isa kang research assistant. Palaging magbanggit ng mga pinagmulan.\",
    \"enabledTools\": { \"web_browsing\": true, \"search_tools\": true }
  },
  \"settingLevels\": {}
}

Nagbabalik ng 201 kasama ang ginawang agent. Isang vector clock ang awtomatikong ikinakabit para sa sync.

I-update ang isang agent:

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

{ \"branding\": { \"name\": \"Research Agent\", \"description\": \"Na-update na paglalarawan\" } }

Isinasama ang patch sa umiiral na agent at itinataas ang vector clock. Ang mga builtin agent ay nagbabalik ng 403 — ang mga ito ay read-only.

Mag-delete ng agent:

DELETE /v1/agents/my-research-agent

Soft-delete sa pamamagitan ng tombstone (nag-si-sync sa mga device). Nagbabalik ng 204.

Pagpapatakbo ng mga Agent

Ito ang pangunahing kaganapan — i-invoke ang isang agent para mag-proseso ng mensahe.

Synchronous Mode

Maghintay para sa buong tugon:

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

{
  "agentId": "general",
  "input": { "message": "Ano ang lagay ng panahon sa Paris ngayon?" },
  "mode": "sync"
}

Ibinabalik ang 200 na may { content, usage, status: "completed" } pagkatapos matapos ng agent. Kung nagka-error ang agent, ibinabalik ang 500 na may { error, status: "error" }.

Asynchronous Mode

I-fire at kalimutan — kapaki-pakinabang para sa mga gawaing matagal matapos:

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

{
  "agentId": "my-research-agent",
  "input": { "message": "Sumulat ng 2000-salitang pagsusuri tungkol sa mga trend sa renewable energy" },
  "mode": "async"
}

Ibinabalik agad ang 202 na may { runId, threadId, status: "running" }.

I-poll para sa status:

GET /v1/runs/{runId}

Ibinabalik ang { run: { runId, threadId, agentId, status, createdAt, content?, usage?, error? } }. Ang status ay isa sa mga sumusunod: running, completed, error, o cancelled.

I-stream ang mga event nang real time (SSE):

GET /v1/runs/{runId}/events

Ibinabalik ang isang text/event-stream kasama ang bawat event ng agent habang nangyayari ito: GENERATION_STARTED, STREAMING_CONTENT, mga tool call, aktibidad ng subagent, at ang terminal event (GENERATION_COMPLETE, GENERATION_ERROR, o GENERATION_CANCELLED). Nagtatapos ang stream pagkatapos ng terminal event.

I-cancel ang isang run:

POST /v1/runs/{runId}/cancel

Ibinabalik ang { run: { ..., status: "cancelled" } }.

Threads

Ang mga Threads ay mga pag-uusap. Ang bawat pagtakbo ng agent ay nangyayari sa loob ng isang thread, at ang mga thread ay nananatili sa iba't ibang session. Pinapayagan ka ng API na ilista, basahin, likhain, at pamahalaan ang mga thread sa paraang programmatiko.

Ilista ang lahat ng thread (metadata lamang):

GET /v1/threads

Nagbabalik ng mga thread para sa kasalukuyang profile kung saan tinanggal ang mga mensahe para sa performance. Ang bawat thread ay may kasamang id, title, createdAt, updatedAt, modeId, archived, at mga istatistika ng paggamit.

Kunin ang isang thread na may kumpletong mga mensahe:

GET /v1/threads/{id}

Nagbabalik ng kumpletong thread kasama ang messages array nito — bawat mensahe ng user, tugon ng assistant, tool call, at resulta ng tool.

Kunin lamang ang mga mensahe:

GET /v1/threads/{id}/messages

Nagbabalik lamang ng messages array — mas magaan kaysa sa buong thread object kapag ang pag-uusap lamang ang kailangan mo.

Lumikha ng thread:

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

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

Nagbabalik ng 201 kasama ang bagong thread. Bilang default, HINDI pinapalitan ng API ang active thread ng app — ipasa ang "setActive": true sa body kung gusto mo iyon. Lalabas agad ang bagong thread sa sidebar (sa pamamagitan ng WebSocket broadcast).

I-update ang isang thread:

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

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

Mga field na maaaring i-update: title, modeId, archived, lastUsedModel. Ang mga pagbabago ay ibino-broadcast sa sidebar sa real time.

I-delete ang isang thread:

DELETE /v1/threads/{id}

Soft-delete sa thread (tombstone para sa sync). Nagbabalik ng 204. Ang mga deleted na thread ay napupunta sa trash at maaaring ma-recover hangga't hindi pa naba-bakante ang trash.

Active thread:

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

Pamamahala ng trash:

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

Ang mga protected thread (pinanatili sa pamamagitan ng data retention toggle) ay hindi kasama sa pag-bakante ng trash.

Pagpapatuloy ng pag-uusap sa pamamagitan ng API: Upang magpadala ng follow-up na mensahe sa isang umiiral na thread, gamitin ang POST /v1/runs kasama ang ID ng thread:

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

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

Makikita ng agent ang buong kasaysayan ng pag-uusap mula sa thread.

Mga Attachment

Ang mga attachment ay mga file na nakaugnay sa mga thread — mga screenshot, PDF, dokumento, in-upload na larawan, at mga ginawang artifact. Hinahayaan ka ng API na i-list, i-upload, i-download, at pamahalaan ang mga ito.

I-list ang lahat ng attachment (metadata lang):

GET /v1/attachments

Ibinabalik ang metadata ng attachment para sa kasalukuyang profile. Ang mabibigat na field (dataUrl, extractedContent, extractedImages) ay tinatanggal — gamitin ang detail o content endpoint para sa mga iyon.

I-list ang mga attachment para sa isang partikular na thread:

GET /v1/threads/{threadId}/attachments

Kunin ang metadata ng attachment:

GET /v1/attachments/{id}

Ibinabalik ang buong metadata kasama ang extractedContent (OCR text, parsed markdown), contentType, fileName, size, at isang hasContent flag. Ang raw binary ay HINDI kasama — gamitin ang /content endpoint para doon.

I-download ang binary ng attachment:

GET /v1/attachments/{id}/content

Ibinabalik ang raw file na may tamang Content-Type at Content-Disposition header. I-pipe ito sa isang file:

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

Mag-upload ng attachment:

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

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

Ang dataUrl ay isang base64-encoded data URL. Ibinabalik ang 201 kasama ang bagong attachment ID. Ang attachment ay nakaugnay sa tinukoy na thread.

I-update ang metadata ng attachment:

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

{ "description": "Na-update na paglalarawan", "fileName": "new-name.pdf" }

I-delete ang isang attachment:

DELETE /v1/attachments/{id}

Soft-delete sa pamamagitan ng tombstone. Ibinabalik ang 204.

MCP Servers

Pamahalaan ang iyong mga koneksyon sa MCP (Model Context Protocol) server — ang mga server na nagbibigay sa mga agent ng access sa mga external tool at data source.

Ilista ang mga naka-configure na server:

GET /v1/mcp-servers

Ibinabalik ang lahat ng MCP server config para sa kasalukuyang profile. Ang mga sensitive field (authToken, env, credentialId) ay tinatanggal mula sa response.

Kunin ang config ng isang server:

GET /v1/mcp-servers/{id}

Magdagdag ng bagong 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"
}

Para sa mga remote HTTP server, gamitin ang "url" sa halip na "command":

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

I-update ang isang server:

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

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

I-enable/i-disable ang isang server:

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

{ "enabled": false }

I-delete ang isang server:

DELETE /v1/mcp-servers/{id}

Pamamahala ng Proseso

Para sa mga lokal na (stdio) MCP server, maaari mong direktang pamahalaan ang proseso ng server.

Ilista ang mga tumatakbong proseso:

GET /v1/mcp-servers/processes

Ibinabalik ang mga tumatakbong proseso ng server kasama ang pid, startedAt, at status na running.

Simulan ang isang server:

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

Binabasa ang command/args/env mula sa server config at inilulunsad ang proseso. Ibinabalik ang status ng proseso.

Ihinto ang isang server:

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

Maayos na ititigil ang proseso ng server (SIGTERM na may fallback sa SIGKILL).

Tumawag sa isang JSON-RPC method nang direkta:

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

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

Nagpapadala ng raw JSON-RPC 2.0 request sa server at ibinabalik ang resulta. Kapaki-pakinabang para sa debugging o pagtawag sa mga method na hindi nakalantad sa pamamagitan ng tools API.

Mga Tool at Toolkit

Mag-browse at i-invoke ang mga tool na ginagamit ng mga agent — web browsing, search, calendar, Gmail, Slate, at iba pa.

I-list ang mga toolkit (naka-grupo):

GET /v1/toolkits

Ibinabalik ang mga embedded tool na naka-grupo ayon sa kategorya (Productivity, Search, Utilities, atbp.) at anumang konektadong MCP server bilang hiwalay na mga toolkit, bawat isa ay may listahan ng kanilang mga action.

I-list ang lahat ng tool (flat):

GET /v1/tools
GET /v1/tools?source=embedded   # Mga builtin tool lang
GET /v1/tools?source=mcp        # Mga MCP server tool lang

Kunin ang mga detalye ng tool kasama ang input schema:

GET /v1/tools/calculator

Ibinabalik ang JSON Schema ng tool para sa mga input parameter nito, para makapag-validate ka bago mag-invoke.

I-invoke nang direkta ang isang tool:

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

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

Ibinabalik ang { result }. Ang input ay iba-validate laban sa schema ng tool — ang invalid na input ay magbabalik ng 422 kasama ang mga detalye. Ang mga remote MCP tool ay magbabalik ng 501 na may gabay na gamitin ang /v1/runs sa halip (kinakailangan nila ang agent subprocess transport).

Mga Connector

Mamahala ng mga OAuth integration — Google, Microsoft, GitHub, Notion, Slack, at iba pa.

Mag-browse ng mga available na integration:

GET /v1/connectors/catalog

Ibinabalik ang lahat ng rehistradong OAuth provider kasama ang kanilang pangalan, kategorya, at mga default scope.

I-list ang iyong mga konektadong account:

GET /v1/connectors

Ibinabalik ang mga aktibong koneksyon para sa kasalukuyang profile. Ang mga token ay hinding-hindi ilalantad — metadata lang (provider, email, status, scopes, timestamps).

I-check ang kalusugan ng koneksyon:

POST /v1/connectors/{id}/test

Ibinabalik ang { health: { status, isTokenExpired, canRefresh } }.

Mag-alis ng koneksyon:

DELETE /v1/connectors/{id}

Ang paggawa ng mga bagong koneksyon ay nangangailangan ng interactive na OAuth flow sa pamamagitan ng UI ng app o sa mga /auth/* na route.

Mga Trigger

Mag-iskedyul ng mga agent na awtomatikong tatakbo — mga daily briefing, weekly report, at interval-based na pag-monitor.

I-list ang mga trigger:

GET /v1/triggers

Gumawa ng naka-iskedyul na trigger:

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

{
  "name": "Morning Briefing",
  "prompt": "I-summarize ang aking mga hindi pa nababasang email at ang kalendaryo ko ngayong araw",
  "modeId": "general",
  "schedule": { "type": "daily", "time": "08:00" }
}

Mga suportadong uri ng iskedyul:

  • { "type": "interval", "minutes": 60 } — bawat N minuto (min 15, max 1440)
  • { "type": "daily", "time": "09:00" } — araw-araw sa partikular na oras
  • { "type": "weekly", "day": "mon", "time": "09:00" } — lingguhan
  • { "type": "weekdays", "time": "08:30" } — Lunes hanggang Biyernes
  • { "type": "daysOfWeek", "days": ["mon", "wed", "fri"], "time": "10:00" } — mga partikular na araw
  • { "type": "monthly", "dayOfMonth": 1, "time": "09:00" } — buwanan
  • { "type": "manual" } — kapag na-fire lang sa pamamagitan ng API

I-fire ang isang trigger nang manual:

POST /v1/triggers/{id}/fire

Ibinabalik ang 202 kasama ang isang threadId para sa magiging run.

I-update o i-delete:

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

Mga Webhook

Ang mga webhook trigger ay nagbibigay-daan sa mga external service (CI/CD, monitoring, form builders) na mag-trigger ng pagtakbo ng agent sa pamamagitan ng HTTP.

Gumawa ng webhook trigger:

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

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

Ibinabalik ang 201 kasama ang isang webhookSecret at webhookPath. Itago ang secret — kakailanganin mo ito para pirmahan ang mga payload.

Magpadala ng webhook:

# I-compute ang HMAC-SHA256 ng raw request body
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"}

Ang webhook endpoint ay HINDI nangangailangan ng bearer auth — gumagamit ito ng HMAC verification sa halip. Ibinabalik ang 202 kasama ang threadId ng ipinadalang run. Ang {{webhook.body}} placeholder sa trigger prompt ay papalitan ng raw request body.

Mga Custom Function

Gumawa ng sarili mong mga tool na maaaring tawagan ng mga agent. Ang mga function ay isinusulat sa JavaScript o Python at tumatakbo sa isang sandbox.

I-list ang mga function:

GET /v1/functions

Gumawa ng function:

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

{
  "name": "calculate_bmi",
  "description": "I-calculate ang Body Mass Index mula sa taas at timbang",
  "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"]
  }
}

Ang mga JavaScript function ay tumatanggap ng input at dapat magbalik ng resulta. Ang mga Python function naman ay nagse-set ng result variable:

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

I-execute nang direkta ang isang function:

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

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

Seguridad: Ang JavaScript ay tumatakbo sa vm sandbox ng Node (walang access sa filesystem o network, 10s timeout). Ang Python ay tumatakbo bilang isang subprocess na may 30s timeout. Parehong nagva-validate ng input bago ang execution.

I-update o i-delete:

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

Mga Workflow

Mag-orchestrate ng maraming agent sa isang DAG (directed acyclic graph) — magpatakbo ng mga step nang sabay-sabay kung posible, at gamitin ang mga output mula sa mga naunang step sa mga susunod.

I-validate ang isang workflow graph:

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

{
  "graph": {
    "nodes": [
      { "id": "research", "agentId": "general", "prompt": "Magsaliksik tungkol sa mga trend sa renewable energy" },
      { "id": "analyze", "agentId": "general", "prompt": "Magsaliksik tungkol sa presyo ng mga kakumpitensya" },
      { "id": "report", "agentId": "general", "prompt": "Sumulat ng report na pinagsasama ang: {{outputs.research}} at {{outputs.analyze}}", "dependsOn": ["research", "analyze"] }
    ]
  }
}

Ibinabalik ang { valid: true/false, errors: [...] }. Sinusuri nito kung may mga cycle, duplicate na ID, at nawawalang dependency reference.

I-execute ang isang workflow:

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

{
  "graph": {
    "nodes": [
      { "id": "research", "agentId": "general", "prompt": "Magsaliksik tungkol sa mga trend sa renewable energy" },
      { "id": "summarize", "agentId": "general", "prompt": "I-summarize: {{outputs.research}}", "dependsOn": ["research"] }
    ]
  }
}

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

Ang mga independent node (walang shared dependency) ay tumatakbo nang sabay-sabay. Ang {{outputs.nodeId}} placeholder sa prompt ng isang node ay pinapalitan ng content output ng pinangalanang upstream node. Ang bawat node ay isang ganap na pagtakbo ng agent, kaya maaari itong gumamit ng mga tool, mag-browse sa web, at ma-access ang lahat ng kakayahan ng target agent.

Mga Knowledge Base

Ayusin ang mga dokumento sa mga searchable collection na maaaring sangguniin ng mga agent.

I-list ang mga knowledge base:

GET /v1/knowledge/bases

Gumawa ng knowledge base:

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

{ "name": "Mga Research Paper" }

Ibinabalik ang 201 kasama ang bagong base ID.

Mag-upload ng dokumento sa isang knowledge base:

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

{
  "fileName": "research-paper.pdf",
  "contentType": "application/pdf",
  "dataUrl": "data:application/pdf;base64,JVBERi0xLjQ...",
  "description": "Mga trend sa renewable energy 2026"
}

Ang dataUrl field ay isang base64-encoded data URL. Ibinabalik ang 201 kasama ang metadata ng dokumento.

I-list ang mga dokumento sa isang knowledge base:

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

Mag-search sa loob ng isang knowledge base:

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

{ "query": "renewable energy" }

Ibinabalik ang mga tumutugmang dokumento batay sa pangalan ng file at paglalarawan. Ang semantic (vector) search ay darating sa susunod na release.

I-delete ang isang dokumento o knowledge base:

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

Mag-export at Mag-import ng mga Agent

Ibahagi ang mga agent bilang mga portable package — sa mga device, team, o sa Community Hub.

I-export ang isang agent:

POST /v1/agents/{id}/export

Nagbabalik ng isang JSON package na naglalaman ng agent definition, tool requirements (mula sa mga enabled tool), connector requirements (kung aling mga OAuth provider ang kailangan), at mga trigger template. Ang sync metadata ay tinatanggal — ang package ay isang malinis at self-contained na blueprint.

Mag-import ng isang agent:

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

{
  \"package\": {
    \"$schema\": \"caiioo.agent.package/v1\",
    \"agent\": {
      \"id\": \"shared-research-agent\",
      \"branding\": { \"name\": \"Research Agent\", \"description\": \"Mula sa team\" },
      \"defaultSettings\": { \"systemPrompt\": \"Nagsasaliksik ka ng mga bagay.\" },
      \"settingLevels\": {}
    },
    \"toolRequirements\": [
      { \"toolId\": \"web_browsing\", \"enabled\": true },
      { \"toolId\": \"search_tools\", \"enabled\": true }
    ]
  }
}

Nagbabalik ng 201 kasama ang na-install na agent. Ang mga ID collision sa mga builtin o umiiral na agent ay nagbabalik ng 409.

Paghawak ng Error

Gumagamit ang API ng mga standard na HTTP status code:

Code Kahulugan
200 Tagumpay
201 Nalikha
202 Tinanggap (nagsimula na ang async operation)
204 Nabura (walang content)
400 Bad request — tingnan ang error field para sa mga detalye
401 Unauthorized — kulang o invalid ang session secret
403 Forbidden — hal., sinusubukang baguhin ang isang builtin agent
404 Hindi nahanap
409 Conflict — hal., umiiral na ang agent ID
422 Validation error — hindi tumutugma ang input sa schema ng tool
500 Server error — tingnan ang error field
501 Not implemented — umiiral ang feature pero hindi available sa paraang ito
503 Service unavailable — hindi handa ang storage o provider

Lahat ng tugon sa error ay may kasamang { "error": "mensaheng nababasa ng tao" }.

Halimbawa ng Quick Start

Narito ang isang kumpletong workflow: gumawa ng agent, patakbuhin ito, at i-stream ang mga resulta.

# 1. Gumawa ng custom agent
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": "I-summarize ang anumang input nang maikli sa 3 bullet point.",
      "enabledTools": { "web_browsing": true }
    },
    "settingLevels": {}
  }'

# 2. Patakbuhin ito nang asynchronously
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": "I-summarize ang https://en.wikipedia.org/wiki/Artificial_intelligence" }, "mode": "async" }')

RUN_ID=$(echo $RUN | jq -r '.runId')

# 3. I-stream ang mga event
curl -N http://localhost:3847/v1/runs/$RUN_ID/events \
  -H "Authorization: Bearer $API_TOKEN"

# 4. I-export ang agent para maibahagi
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.