この文書は元の英語版を機械翻訳したものです。翻訳版と英語版の間に相違がある場合は、英語版が優先されるものとします。 英語版の原文を読む

パブリックAPI

Caiiooには、エージェントの実行、ツールの管理、タスクのスケジュールなど、すべてをプログラムで制御できるREST APIが含まれています。このAPIは、デスクトップアプリやブラウザブリッジを動かしているのと同じローカルサーバー上で動作します。

ベースURL: http://localhost:3847/v1

認証: 2つの認証方法があり、どちらも設定の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

設定済みのすべてのプロバイダーのモデルを1つのリストに統合します。API キーのないプロバイダーはスキップされ、warnings にリストされます。

エージェント

エージェントはCaiiooの核となる存在です。各エージェントはモードであり、独自のシステムプロンプト、ツール、変数、スキルを持つ設定済みのパーソナリティです。

すべてのエージェントをリスト表示：

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

トゥームストーンによる論理削除を行い、デバイス間で同期されます。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（スレッド）は会話を意味します。すべてのエージェントの実行はスレッド内で行われ、スレッドはセッションをまたいで保持されます。APIを使用すると、プログラムからスレッドの一覧取得、読み取り、作成、管理を行うことができます。

すべてのスレッドを一覧表示（メタデータのみ）:

GET /v1/threads

現在のプロファイルのスレッドを返します。パフォーマンス向上のため、メッセージ内容は除外されます。各スレッドには id、title、createdAt、updatedAt、modeId、archived、および使用統計が含まれます。

メッセージ全文を含むスレッドを取得:

GET /v1/threads/{id}

messages 配列を含む完全なスレッドを返します。これには、すべてのユーザーメッセージ、アシスタントの応答、ツール呼び出し、およびツールの実行結果が含まれます。

メッセージのみを取得:

GET /v1/threads/{id}/messages

messages 配列のみを返します。会話内容だけが必要な場合、フルスレッドオブジェクトよりも軽量です。

スレッドを作成:

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

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

新しいスレッドと共に 201 を返します。デフォルトでは、APIはアプリのアクティブなスレッドを切り替えません。切り替えたい場合は、ボディに "setActive": true を含めてください。新しいスレッドは（WebSocketブロードキャストを介して）即座にサイドバーに表示されます。

スレッドを更新:

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

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

更新可能なフィールド: title、modeId、archived、lastUsedModel。変更はリアルタイムでサイドバーにブロードキャストされます。

スレッドを削除:

DELETE /v1/threads/{id}

スレッドを論理削除します（同期用のトゥームストーン）。204 を返します。削除されたスレッドはゴミ箱に移動し、ゴミ箱を空にするまで復元可能です。

アクティブなスレッド:

GET /v1/threads/active            # { threadId } を返す
PUT /v1/threads/active            # ボディ: { "threadId": "..." }

ゴミ箱の管理:

GET /v1/threads/trash/count       # { count } を返す
POST /v1/threads/trash/empty      # { deletedCount, protectedCount } を返す

保護されたスレッド（データ保持設定により保持されているもの）は、ゴミ箱を空にする対象から除外されます。

API経由で会話を継続する: 既存のスレッドにフォローアップメッセージを送信するには、スレッドの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"
}

エージェントはスレッドから会話の全履歴を参照します。

添付ファイル

添付ファイルは、スレッドにリンクされたファイル（スクリーンショット、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 です。新しい添付ファイル ID と共に 201 を返します。添付ファイルは指定されたスレッドにリンクされます。

添付ファイルメタデータの更新:

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

{ "description": "更新された説明文", "fileName": "new-name.pdf" }

添付ファイルの削除:

DELETE /v1/attachments/{id}

トゥームストーンによるソフトデリートを行います。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"
}

サーバーの更新:

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}

プロセス管理

ローカル（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 リクエストを送信し、結果を返します。デバッグや、ツール 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 の使用を促します（エージェントのサブプロセス転送が必要なため）。

コネクタ

Google、Microsoft、GitHub、Notion、Slack などの OAuth 統合を管理します。

利用可能な統合の閲覧:

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

実行結果の threadId と共に 202 を返します。

更新または削除:

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

Webhook

Webhook トリガーを使用すると、外部サービス（CI/CD、監視、フォーム作成ツールなど）から HTTP 経由でエージェントの実行を開始できます。

Webhook トリガーの作成:

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

{
  "name": "デプロイフック",
  "prompt": "デプロイが発生しました: {{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 認証を必要とせず、代わりに HMAC 検証を使用します。実行された threadId と共に 202 を返します。トリガープロンプト内の {{webhook.body}} プレースホルダーは、生のリクエストボディに置き換えられます。

カスタム関数

エージェントが呼び出せる独自のツールを作成します。関数は JavaScript または Python で記述され、サンドボックス内で実行されます。

関数一覧:

GET /v1/functions

関数の作成:

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

{
  "name": "calculate_bmi",
  "description": "身長と体重から BMI を計算します",
  "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": "研究論文" }

新しいベース ID と共に 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": "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

エージェントの定義、ツールの要件、コネクタの要件（必要なOAuthプロバイダー）、トリガーテンプレートを含むJSONパッケージを返します。同期メタデータは削除され、クリーンで自己完結した設計図となります。

エージェントを読み込む：

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://ja.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.