本文件為英文原版的機器翻譯。若翻譯版本與英文原版之間存在任何歧義，概以英文原版為準。 閱讀英文原版

公開 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 存取
將啟用公開 API 切換為開啟
設定一個 API 存取權杖（您選擇的任何字串 — 請將其視為密碼）
在所有 API 請求中使用該權杖

該 API 可在 localhost 和透過私有中繼存取。請查看 GET /v1/auth/info（無需驗證）以獲取目前狀態和設定說明。

供應商與模型

探索已配置的 LLM 供應商以及可用的模型。

列出供應商：

GET /v1/providers

返回所有已配置的供應商類型（Anthropic、OpenAI、Google、OpenRouter、Ollama、Poe、MLX、Baseten 以及其他新增的供應商），包含功能標記（supportsVision、supportsToolCalling、supportsStreaming 等）以及是否已配置 API 金鑰。

列出供應商的模型：

GET /v1/providers/anthropic/models

返回該供應商的模型目錄。每個模型包含 id、displayName 以及可用的 contextLength。

跨供應商的扁平化目錄：

GET /v1/models

將所有已配置供應商的模型合併為一個列表。未配置 API 金鑰的供應商將被跳過並列在 warnings 中。

代理 (Agents)

代理是 Caiioo 的核心。每個代理都是一個模式 (Mode) —— 一個配置好的個性，擁有自己的系統提示詞、工具、變數和技能。

列出所有代理：

GET /v1/agents

返回內建代理（購物、職場、一般）以及您建立的任何自定義代理。每個代理都標有 source: \"builtin\" 或 source: \"custom\"。

建立自定義代理：

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

{
  \"id\": \"my-research-agent\",
  \"branding\": {
    \"name\": \"研究代理\",
    \"description\": \"搜尋網頁並總結發現\"
  },
  \"defaultSettings\": {
    \"systemPrompt\": \"你是一位研究助手。務必引用來源。\",
    \"enabledTools\": { \"web_browsing\": true, \"search_tools\": true }
  },
  \"settingLevels\": {}
}

返回 201 以及建立的代理。系統會自動附加向量時鐘用於同步。

更新代理：

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

{ \"branding\": { \"name\": \"研究代理\", \"description\": \"更新後的描述\" } }

將補丁合併到現有代理中並更新向量時鐘。內建代理返回 403 —— 它們是唯讀的。

刪除代理：

DELETE /v1/agents/my-research-agent

透過標記 (tombstone) 進行軟刪除（跨裝置同步）。返回 204。

執行代理

這是核心功能 —— 調用代理來處理訊息。

同步模式

等待完整回應：

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

{
  "agentId": "general",
  "input": { "message": "今天巴黎的天氣如何？" },
  "mode": "sync"
}

代理完成後返回 200 以及 { content, usage, status: "completed" }。如果代理出錯，返回 500 以及 { error, status: "error" }。

非同步模式

發送後即不管 —— 適用於長時間運行的任務：

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

{
  "agentId": "my-research-agent",
  "input": { "message": "寫一份 2000 字的再生能源趨勢分析" },
  "mode": "async"
}

立即返回 202 以及 { runId, threadId, status: "running" }。

輪詢狀態：

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（僅限中繼資料）：

GET /v1/threads

傳回目前設定檔的 Thread，為了效能考量已移除訊息內容。每個 Thread 包含 id、title、createdAt、updatedAt、modeId、archived 以及使用統計數據。

獲取包含完整訊息的 Thread：

GET /v1/threads/{id}

傳回完整的 Thread，包括其 messages 陣列 —— 包含每一條使用者訊息、助手回應、工具調用（tool call）及工具結果。

僅獲取訊息：

GET /v1/threads/{id}/messages

僅傳回 messages 陣列 —— 當您只需要對話內容時，這比完整的 Thread 物件更輕量。

建立 Thread：

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

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

傳回 201 及新建立的 Thread。預設情況下，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}

軟刪除（soft-delete）該 Thread（用於同步的標記）。傳回 204。刪除的 Thread 會移至垃圾桶，在清理垃圾桶前皆可復原。

活動 Thread：

GET /v1/threads/active            # 傳回 { threadId }
PUT /v1/threads/active            # 主體：{ "threadId": "..." }

垃圾桶管理：

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

受保護的 Thread（透過資料保留切換開關保留）將不包含在清理垃圾桶的範圍內。

透過 API 繼續對話： 若要向現有的 Thread 發送後續訊息，請使用 POST /v1/runs 並帶上該 Thread 的 ID：

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 文字、解析後的 markdown）、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 以及新的附件 ID。附件會連結到指定的對話串。

更新附件元數據：

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) 伺服器連線 — 這些伺服器為代理（agents）提供存取外部工具和資料來源的權限。

列出已配置的伺服器：

GET /v1/mcp-servers

回傳目前設定檔（profile）的所有 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 伺服器，請使用 "url" 代替 "command"：

{
  "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 伺服器，您可以直接管理伺服器程序。

列出執行中的程序：

GET /v1/mcp-servers/processes

回傳執行中的伺服器程序，包含 pid、startedAt 和 running 狀態。

啟動伺服器：

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

從伺服器配置中讀取 command/args/env 並產生程序。回傳程序狀態。

停止伺服器：

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

正常關閉伺服器程序（先發送 SIGTERM，若無效則發送 SIGKILL）。

直接呼叫 JSON-RPC 方法：

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

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

向伺服器發送原始 JSON-RPC 2.0 請求並回傳結果。適用於偵錯或呼叫未透過 tools API 公開的方法。

工具與工具箱

瀏覽並調用代理使用的工具 —— 網頁瀏覽、搜尋、行事曆、Gmail、Slate 等。

列出工具箱（分組）：

GET /v1/toolkits

返回按類別（生產力、搜尋、公用程式等）分組的內嵌工具，以及任何連接的 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 工具會返回 501 並建議改用 /v1/runs（它們需要代理子程序傳輸）。

連接器

管理 OAuth 整合 —— Google Workspace、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 分鐘（最小 15，最大 1440）
{ "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

返回 202 以及產生的執行的 threadId。

更新或刪除：

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

Webhooks

Webhook 觸發器讓外部服務（CI/CD、監控、表單建立器）能透過 HTTP 觸發代理執行。

建立 Webhook 觸發器：

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

{
  "name": "部署掛鉤",
  "prompt": "發生了一次部署：{{webhook.body}}",
  "modeId": "general",
  "kind": "webhook"
}

返回 201 以及 webhookSecret 和 webhookPath。請儲存此金鑰 —— 您將需要它來簽署負載。

發送 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 驗證 —— 它使用 HMAC 驗證。返回 202 以及分派執行的 threadId。觸發器提示詞中的 {{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 在 Node 的 vm 沙箱中運行（無檔案系統或網路存取，10 秒超時）。Python 作為子程序運行，超時時間為 30 秒。兩者在執行前都會驗證輸入。

更新或刪除：

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

工作流

在 DAG（有向無環圖）中編排多個代理 —— 盡可能平行執行步驟，並將早期步驟的輸出饋送到後續步驟中。

驗證工作流圖表：

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

{
  "graph": {
    "nodes": [
      { "id": "research", "agentId": "general", "prompt": "研究可再生能源趨勢" },
      { "id": "analyze", "agentId": "general", "prompt": "研究競爭對手定價" },
      { "id": "report", "agentId": "general", "prompt": "撰寫一份結合以下內容的報告：{{outputs.research}} 和 {{outputs.analyze}}", "dependsOn": ["research", "analyze"] }
    ]
  }
}

返回 { valid: true/false, errors: [...] }。檢查循環引用、重複 ID 以及缺失的依賴引用。

執行工作流：

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

{
  "graph": {
    "nodes": [
      { "id": "research", "agentId": "general", "prompt": "研究可再生能源趨勢" },
      { "id": "summarize", "agentId": "general", "prompt": "總結：{{outputs.research}}", "dependsOn": ["research"] }
    ]
  }
}

返回 { status: "completed", outputs: { research: "...", summarize: "..." }, nodeResults: {...} }。

獨立節點（無共享依賴）會平行執行。節點提示詞中的 {{outputs.nodeId}} 佔位符將被替換為指定上游節點的內容輸出。每個節點都是一次完整的代理執行，因此它可以使用工具、瀏覽網頁並存取目標代理的所有功能。

知識庫

將文件組織成可搜尋的集合，供代理參考。

列出知識庫：

GET /v1/knowledge/bases

建立知識庫：

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

{ "name": "研究論文" }

返回 201 以及新的知識庫 ID。

上傳文件到知識庫：

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

{
  "fileName": "research-paper.pdf",
  "contentType": "application/pdf",
  "dataUrl": "data:application/pdf;base64,JVBERi0xLjQ...",
  "description": "2026 年可再生能源趨勢"
}

dataUrl 欄位是一個 base64 編碼的資料 URL。返回 201 以及文件元數據。

列出知識庫中的文件：

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

在知識庫中搜尋：

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

{ "query": "可再生能源" }

根據檔案名稱和描述返回匹配的文件。語義（向量）搜尋將在未來版本中推出。

刪除文件或知識庫：

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

匯出與匯入代理

將代理作為可攜式套件分享 —— 跨裝置、團隊或社群中心。

匯出代理：

POST /v1/agents/{id}/export

返回一個 JSON 套件，其中包含代理定義、工具需求（衍生自啟用的工具）、連接器需求（需要哪些 OAuth 提供商）和觸發器範本。同步元數據會被移除 —— 該套件是一個乾淨、獨立的藍圖。

匯入代理：

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

{
  \"package\": {
    \"$schema\": \"caiioo.agent.package/v1\",
    \"agent\": {
      \"id\": \"shared-research-agent\",
      \"branding\": { \"name\": \"研究代理\", \"description\": \"來自團隊\" },
      \"defaultSettings\": { \"systemPrompt\": \"你負責研究事物。\" },
      \"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`	衝突 —— 例如：代理 ID 已存在
`422`	驗證錯誤 —— 輸入不符合工具架構
`500`	伺服器錯誤 —— 請檢查 `error` 欄位
`501`	未實作 —— 功能存在但無法以此方式使用
`503`	服務不可用 —— 儲存或供應商未就緒

所有錯誤回應均包含 { "error": "人類可讀的訊息" }。

快速入門範例

這是一個完整的工作流：建立代理、執行它並串流結果。

# 1. 建立自訂代理
curl -X POST http://localhost:3847/v1/agents \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "quick-summarizer",
    "branding": { "name": "快速總結器" },
    "defaultSettings": {
      "systemPrompt": "用 3 個列點簡潔地總結任何輸入。",
      "enabledTools": { "web_browsing": true }
    },
    "settingLevels": {}
  }'

# 2. 非同步執行
RUN=$(curl -s -X POST http://localhost:3847/v1/runs \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "quick-summarizer", "input": { "message": "總結 https://zh.wikipedia.org/wiki/人工智能" }, "mode": "async" }')

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

# 3. 串流事件
curl -N http://localhost:3847/v1/runs/$RUN_ID/events \
  -H "Authorization: Bearer $API_TOKEN"

# 4. 匯出代理以供分享
curl -X POST http://localhost:3847/v1/agents/quick-summarizer/export \
  -H "Authorization: Bearer $API_TOKEN"

This guide is maintained by the Caiioo team using Slate, our built-in editor.