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

公開 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、ヘッダー名は大文字小文字を区別しません）を介して自動的に認証されます。手動のセットアップは不要で、アプリがバックグラウンドで処理します。リレイ認証リクエストは、すでに信頼されているため「公開 API を有効にする」トグルをバイパスします。Bearer トークンのリクエストのみがトグルによって制限されます。

セットアップ:

Caiioo の設定 > API アクセスを開きます
公開 API を有効にする をオンにします
API アクセストークン を設定します（任意の文字列。パスワードのように扱ってください）
すべての API リクエストでそのトークンを使用します

API は localhost およびプライベートリレイ経由で利用可能です。現在のステータスとセットアップ手順については、GET /v1/auth/info（認証不要）を確認してください。

レート制限: すべての /v1/* リクエストはクライアント IP ごとに制限されます。読み取り用の GET リクエストは毎分 100 回、書き込みリクエスト（POST / PATCH / DELETE）は合計で 毎分 30 回 です。制限を超えたリクエストには 429 が返されます。ウェブフックの配信（POST /v1/webhooks/:id）は Bearer 認証を必要とせず、これらの制限の対象外です。

プロフィール

1つのデバイスで複数のユーザープロフィール（例：個人用と仕事用）を保持できます。APIを使用すると、外部スクリプトで利用可能なプロフィールを確認し、他の作業を行う前にアクティブなプロフィールを切り替えることができます。プロフィールの作成、更新、削除は、意図的にパブリックAPIには公開されていません。これらのフローはアプリのオンボーディングUIで行います。

プロフィール一覧を取得:

GET /v1/profiles

削除されていないプロフィールごとに1つのエントリを含む { 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/* リソース（スレッド、添付ファイル、設定、スキル）はこのプロフィールに対して動作します。

アクティブなプロフィールを切り替える:

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

{ "profileId": "一覧から取得したユーザーUUID" }

新しくアクティブになったプロフィールの { 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 オブジェクトが含まれます。

ケイパビリティフラグ	意味
`supportsVision`	プロバイダーが画像入力を受け入れ可能
`supportsPdfFile`	プロバイダーが生の PDF ファイルコンテンツブロックをネイティブに受け入れ可能
`supportsToolCalling`	プロバイダーが関数/ツール呼び出し（tool calling）をサポート
`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 は空の配列を返します。独自のゲートウェイカタログを使用してください。

特定のプロバイダーのモデル一覧:

GET /v1/providers/openrouter/models

そのプロバイダーのモデルカタログを返します。各モデルには id、displayName、および利用可能な場合は contextLength が含まれます。プロバイダーに API キーがない場合、またはアップストリームのカタログにアクセスできない場合は 503 を返します。

全プロバイダーの統合カタログ:

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 を返します。

Running Agents

これはメインのイベントです — エージェントを呼び出してメッセージを処理します。

Request body — サポートされているフィールド

フィールド	必須	説明
`agentId`	はい	組み込みモードのID（例：`general`）またはカスタムエージェントのID
`input.message`	はい	ユーザーのメッセージテキスト
`input.attachments`	いいえ	このターンに添付する添付ファイルID（既に `/v1/attachments` 経由でアップロード済み）の配列
`input.variables`	いいえ	エージェントの変数リゾルバーにマージされる、実行ごとの変数オーバーライド
`input.tabContext`	いいえ	ページコンテキストとして注入される自由形式の文字列（ブラウザブリッジで使用）
`input.messageId`	いいえ	クライアント提供のメッセージID — リトライ時の重複排除に有用
`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 を返します。同期実行は、終端イベントが受信されない場合、5分でタイムアウトし status: "error" となります。それ以上の時間がかかる可能性がある場合は、async + SSE を使用してください。

Asynchronous Mode（非同期モード）

投げっぱなし（Fire and forget） — 長時間のタスクに有用です：

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 を返します。

ステータスのポーリング:

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 フレームを1つ送信し、接続を閉じます。クライアントはそのフレームの受信（または接続の切断）を、読み取りを停止するシグナルとして扱う必要があります。

実行が既に終了した後にサブスクライブした場合、サーバーは完全な最終 record を含む RUN_SNAPSHOT 型のフレームを1つ再生し、続いて event: terminal 番兵を送信してから閉じます。

実行のキャンセル:

POST /v1/runs/{runId}/cancel

{ run: { ..., status: "cancelled" } } を返します。

Threads

Threads（スレッド）は会話を意味します。すべてのエージェントの実行はスレッド内で行われ、スレッドはセッションをまたいで保持されます。APIを使用すると、プログラムからスレッドの一覧取得、読み取り、作成、管理を行うことができます。

すべてのスレッドをリスト表示する（メタデータのみ）:

GET /v1/threads

現在のプロファイルに対して { threads: [...] } を返します。この際、messages は除外されます（メッセージが必要な場合は詳細エンドポイントを使用してください）。その他のすべてのフィールド（id、title、createdAt、updatedAt、modeId、archived、使用統計、および設定されている場合は subAgentHistories、anonymizerSnapshot、threadToolApprovals、threadVariables、threadToolOverrides、messagingBinding、scheduledTaskId）は保持されます。（この詳細なペイロードは API 専用です。WebSocket のサイドバー配信では、転送制限内に収めるためにより厳密な除外が行われます。）

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

GET /v1/threads/{id}

messages 配列（すべてのユーザーメッセージ、アシスタントの応答、ツール呼び出し、ツールの実行結果）を含む完全なスレッドオブジェクトを返します。

メッセージのみを取得する:

GET /v1/threads/{id}/messages

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

スレッドを作成する:

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

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

201 ステータスと { thread } を返します。新しいスレッドは（WebSocket 配信を介して）即座にサイドバーに表示されます。API は作成時にアプリのアクティブなスレッドを切り替えることはありません。切り替えが必要な場合は、別途 PUT /v1/threads/active を呼び出してください。

スレッドを更新する:

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            # Body: { "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"
}

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"] }

更新可能なフィールドは POST の許可リストと同じです（credentialId や oauthConnectionId も含まれます。これは、削除・再作成を行わずに OAuth 接続をローテーションする際に便利です）。サーバー管理フィールドは読み取り専用のままです。

サーバーの有効化/無効化:

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 を通じて公開されていないメソッドを呼び出す際に有用です。

Tools & Toolkits

エージェントが使用するツール（ウェブブラウジング、検索、カレンダー、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 を渡してください。

ゲーティング — パブリック API で拒否されるもの:

ティア制限のあるツール (metadata.requiredTier !== 'free') → 403。エージェントのループはユーザーのセッションに対してティアを確認しますが、パブリック API には保持されたティアコンテキストがないため、保守的なポリシーとして拒否されます。代わりに、適切なティアを持つエージェントを使用して POST /v1/runs を利用してください。
承認が必要なツール (metadata.approval.requiresApproval === true) → 403。確認を行う人間がループ内に存在しないためです。POST /v1/runs（ユーザーにプロンプトを表示します）経由で呼び出すか、アプリ内でツールの承認モードを approve_all に設定してバイパスしてください。
リモート MCP ツール → 501。/v1/runs を使用するよう案内が返されます（これらはエージェントのサブプロセス・トランスポートを必要とするためです）。

Vision および画像を使用するツール: 最初に POST /v1/attachments 経由でアップロードし、返された添付ファイル ID を input 内で渡します（例：{ "input": { "attachment_id": "att_abc", "prompt": "What is in this image?" } }）。ツールは threadId を介してストレージからバイナリを読み取ります。バイトデータをインラインで渡すことはありません。

コネクタ

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

利用可能な連携を閲覧する:

GET /v1/connectors/catalog

登録されているすべての OAuth プロバイダーの名前、カテゴリ、デフォルトのスコープを返します。

接続済みアカウントを一覧表示する:

GET /v1/connectors

現在のプロフィールの有効な接続を返します。トークンが公開されることは決してありません。メタデータ（プロバイダー、メール、ステータス、スコープ、タイムスタンプ）のみが返されます。

単一の接続を取得する:

GET /v1/connectors/{id}

1 つの接続のメタデータを返します。トークンは公開されません。

接続の健全性を確認する:

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、スケジュール、および種類固有のフィールド（例：ウェブフックトリガーの場合は webhookSecret/webhookPath、メッセージングトリガーの場合は messagingAdapterId/messagingChannelFilter）が含まれます。

単一のトリガーを取得する:

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 分ごと（最小 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}

ウェブフック

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

ウェブフックトリガーを作成する:

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

{
  \"name\": \"Deploy hook\",
  \"prompt\": \"デプロイが発生しました: {{webhook.body}}\",
  \"modeId\": \"general\",
  \"kind\": \"webhook\"
}

webhookSecret と webhookPath を含む 201 を返します。ペイロードの署名に必要となるため、シークレットを保存してください。

ウェブフックを送信する:

# リクエストボディの 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\"}

ウェブフックのエンドポイントは Bearer 認証を必要とせず、代わりに HMAC 検証を使用します。ディスパッチされた実行の threadId を含む 202 を返します。トリガープロンプト内の {{webhook.body}} プレースホルダーは、生のリクエストボディに置き換えられます。

メッセージングトリガー

メッセージングトリガーは、接続されたメッセージングアダプター（コミュニティハブ経由でインストールされた Slack や Discord の統合など）がトリガーのフィルターに一致するメッセージを受信したときに実行されます。kind: \"messaging\" で作成します：

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

{
  \"name\": \"Mention responder\",
  \"prompt\": \"次に対して役立つ返信をして: {{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": "身長と体重から 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}

スキル

スキルは、エージェントが参照したり、空の会話ビューからクイック起動したりできる保存済みのプロンプトです。ハブからインストールされたスキル（パッケージインストール経由で管理）はここには含まれません。ユーザーが作成したスキルのみがリスト表示され、編集可能です。

スキル一覧を取得:

GET /v1/skills

アクティブなプロフィールのユーザー作成スキルの { skills: [...] } を返します。削除済み（Tombstoned）、ハブオーバーレイ、同期シャドウスキルは除外されます。

特定のスキルを取得:

GET /v1/skills/{id}

スキルを作成:

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

{
  "prompt": "ページの内容を3つの箇条書きで要約してください。",
  "tags": ["utility", "summarize"],
  "isFavorite": true,
  "modes": ["general"],
  "displayName": "クイック要約",
  "description": "アクティブなページの3つの箇条書きによる要約"
}

prompt のみが必須です。modes（任意）はスキルを特定のエージェントIDに限定します。すべてのモードで有効にする場合は省略してください。サーバーが割り当てた id、createdAt、updatedAt を含む新しいスキルを 201 で返します。

スキルを更新:

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

{ "prompt": "更新されたプロンプト", "isFavorite": false }

更新可能なフィールド: prompt、tags、modes、displayName、description、isFavorite。ハブオーバーレイスキルを更新しようとすると 404 を返します。

スキルを削除:

DELETE /v1/skills/{id}

論理削除（Tombstone）を行います。204 を返します。ハブオーバーレイスキルの場合は 404 を返します。代わりにソースパッケージをアンインストールしてください。

ワークフロー

複数のエージェントを 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`	バリデーションエラー — 入力がツールのスキーマと不一致
`429`	レート制限 — 認証セクションの制限予算を確認
`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.