Console API リファレンス
AI Agent 向け: このページの Markdown 版は https://ankole.agentbull.com/ja-JP/docs/console-api/index.md、ドキュメント索引は https://ankole.agentbull.com/ja-JP/llms.txt にあります。
Console API はマルチアカウント対応のブラウザーセッション認証を使用します。Cookie ヘッダーで暗号化・署名済みのセッション Cookie を送信し、x-ankole-authentication ヘッダーで操作対象のアカウントを指定します。サーバー側では RequireSiteAdminSession が有効な管理者セッションを解決し、対象 Human のアクセス状態を確認したうえで Ankole.AuthZ の actor(console_rest)をバインドし、Ankole.AuthZ.Authorizer が各 Ash アクションを site_console:** および tenant_console:** 権限で認可します。認証に失敗した場合は 401 が返ります。また、GET と HEAD 以外のリクエストにはシェルから取得した x-csrf-token ヘッダーが必須であり、CSRF トークンの欠落・不一致や権限不足の場合は 403 が返ります。
Console の設定変更、集約ビューの取得、および監査対象のシークレット操作はすべて /api/v2 配下に集約されています。サイト全体の管理ルートは /api/v2/site 配下に置かれ、テナント単位のルートは選択されたデータテナントに対して実行されます。以下の各表では、それぞれのルートの完全パスを記載しています。
/api/v2 のリクエストとレスポンスには application/vnd.api+json を使用し、詳細な型定義は各操作の OpenAPI スキーマで規定されています。通常の作成・更新では data.type と data.attributes を使用しますが、generic アクションでは引数を data 直下に置き、JSON:API リソースドキュメントではなく型付きオブジェクトを返す場合があります(たとえば PUT /api/v2/worker-envs/EXAMPLE は {"data":{"value":"example","secret":false}} を受け取り、worker_env オブジェクトを返します)。一覧取得ルートでスキーマにキーセットページネーションが宣言されている場合は、page[limit] と page[after] を使用します。
テナント単位のルートでは、x-ankole-tenant: <tenant UUID> ヘッダーで操作対象のデータテナントを指定します(省略時は呼び出し元アカウントの所属テナントが使われます)。指定されたテナントが無効・利用不可・削除中のいずれかである場合は、data_tenant_unavailable とともに 404 が返ります。なお、このヘッダーによって呼び出し元自身の Identity やサイト管理権限が変わることはなく、/api/v2/site ルートのスコープにも影響しません。
Console 操作およびサイト管理操作の OpenAPI 3.1 ドキュメントは /api/v2/openapi.json と /api/v2/site/openapi.json で公開されており、閲覧には対象ルートと同じ認証が必要です。これ以外のブラウザー向け JSON:API スコープでも、/api/v2/pod/openapi.json(Pod ワークスペースおよび pod_admin 向けの /api/v2/pod/admin/* ルート)と /api/v2/browser/openapi.json(ブラウザー認証および初期セットアップ)がそれぞれ公開されています。ファイルのアップロードとダウンロードには後述する /api/v2 のネイティブルートを使用し、ランタイムの AI 呼び出し・OIDC プロトコル・Webhook にはそれぞれ専用の API 契約を使用します。
configuration の surface
API ルートは内部コントローラーの都合ではなく、「運用者が何を構成するか」という対象ごとに整理されています。主な設定用エンドポイントは次のとおりです。
Provider と model アクセス
Agent を稼働させるには背後のモデル接続が不可欠です。運用者は AIGateway の provider 管理ルートと Agent のモデルプロファイルを通じてこれらを紐付けます。
| メソッド | パス | 用途 |
|---|---|---|
GET |
/api/v2/site/ai-gateway/provider-kinds |
このデプロイインスタンスで利用可能な provider kind を一覧取得 |
GET |
/api/v2/site/ai-gateway/models |
Console の設定画面向けに capability 付きの provider モデル一覧を取得 |
GET |
/api/v2/site/ai-gateway/providers |
設定済みの provider を一覧取得 |
GET |
/api/v2/site/ai-gateway/providers/:provider_id |
特定の provider とその credential pool の状態を取得 |
PATCH |
/api/v2/site/ai-gateway/providers/:provider_id |
provider を作成または置換 |
DELETE |
/api/v2/site/ai-gateway/providers/:provider_id |
provider を削除 |
POST |
/api/v2/site/ai-gateway/providers/:provider_id/credentials |
credential pool にメンバーを追加 |
PATCH |
/api/v2/site/ai-gateway/providers/:provider_id/credentials/:credential_id |
プールメンバーの設定更新または再認証 |
DELETE |
/api/v2/site/ai-gateway/providers/:provider_id/credentials/:credential_id |
プールメンバーを削除 |
PATCH |
/api/v2/site/ai-gateway/providers/:provider_id/credential-pool/strategy |
プールのメンバー選択戦略を設定 |
POST |
/api/v2/site/ai-gateway/providers/:provider_id/chatgpt-login |
ChatGPT のデバイスログインまたはブラウザーログインを開始 |
POST |
/api/v2/site/ai-gateway/providers/:provider_id/chatgpt-login/poll |
デバイスログインの完了状態を 1 回ポーリング |
POST |
/api/v2/site/ai-gateway/providers/:provider_id/chatgpt-login/browser-callback |
ブラウザーコールバック URL 貼り付けによる代替ログインを完了 |
POST |
/api/v2/site/ai-gateway/providers/:provider_id/chatgpt-enterprise-credentials |
Enterprise アクセストークンを追加 |
GET |
/api/v2/model-profiles |
Pod またはサイトの既定モデルプロファイルおよび provider-hosted スイッチを取得 |
PUT |
/api/v2/model-profiles/:profile |
Pod またはサイトの既定モデルプロファイルを設定 |
DELETE |
/api/v2/model-profiles/:profile |
Pod またはサイトの既定モデルプロファイルを削除(?defaults_scope= で対象スコープを指定) |
PUT |
/api/v2/model-profiles/provider-hosted |
Pod またはサイトの provider-hosted 機能スイッチを設定 |
GET |
/api/v2/system-principals |
登録済みのシステムサービス Principal(ankole_brain、system など)を一覧取得 |
GET |
/api/v2/system-principals/:uid/model-profiles |
システム Principal のモデルプロファイル上書き値と実効設定を取得 |
PUT |
/api/v2/system-principals/:uid/model-profiles/:profile |
システム Principal の固定スロットモデル上書きを設定 |
DELETE |
/api/v2/system-principals/:uid/model-profiles/:profile |
システム Principal の上書きを削除し、Pod・サイト既定値の継承に戻す |
GET |
/api/v2/agents/:agent_uid/model-profiles |
Agent のモデルプロファイル上書き値・継承値・実効プロファイルを取得 |
PUT |
/api/v2/agents/:agent_uid/model-profiles/:profile |
Agent の固定スロット上書きまたはカスタムプロファイルを設定 |
DELETE |
/api/v2/agents/:agent_uid/model-profiles/:profile |
Agent のプロファイル上書きまたはカスタムプロファイルを削除 |
PUT |
/api/v2/agents/:agent_uid/provider-hosted |
特定の Agent に対する provider-hosted 機能の上書きを設定 |
Provider の認証情報は暗号化されたプールメンバーとして control plane 内にのみ保管され、Agent の実行環境へ渡されることはありません。モデルプロファイルは「サイト既定値 → Pod 既定値 → Agent またはシステムサービス Principal の上書き(ankole_brain は Brain の抽出・Dreaming・URL 取得・リランク用、system は内部処理用)」の階層で解決され、AIGateway がその provider 内の正常なメンバーを選択します。API のレスポンスには安全なアカウント識別情報、ヘルス状態、レート制限情報、使用量だけが含まれます。
Agent とその能力
Agent は、運用者が各種設定を組み立てる際の中心となる単位です。
| メソッド | パス | 用途 |
|---|---|---|
GET |
/api/v2/agents |
Agent を一覧取得 |
POST |
/api/v2/agents |
Agent を新規作成 |
GET |
/api/v2/agents/:agent_uid |
特定の Agent の詳細を取得 |
PATCH |
/api/v2/agents/:agent_uid |
Agent の設定を更新 |
POST |
/api/v2/agents/:agent_uid/enable |
無効化されている Agent を再有効化 |
POST |
/api/v2/agents/:agent_uid/rename |
無効化済み Agent の Worker 終了後に UID を変更 |
DELETE |
/api/v2/agents/:agent_uid |
有効な Agent なら無効化し、すでに無効化済みの Agent なら完全に削除 |
Worker provider
各 Agent は作成時に使用する Worker provider を選択し、作成後は変更できません。Provider の YAML 構成と暗号化された認証情報は分けて保存されます。ライフサイクルと永続ストレージの仕様については、Worker 管理を参照してください。
| メソッド | パス | 用途 |
|---|---|---|
GET |
/api/v2/site/worker-provider-kinds |
利用可能な provider kind、YAML サンプル、必要な認証情報項目を一覧取得 |
GET |
/api/v2/site/worker-providers |
設定済みの Worker provider を一覧取得 |
POST |
/api/v2/site/worker-providers |
Worker provider を新規作成 |
PATCH |
/api/v2/site/worker-providers/:provider_id |
設定または認証情報を更新 |
GET |
/api/v2/site/worker-providers/:provider_id/check |
接続性と権限をテスト |
DELETE |
/api/v2/site/worker-providers/:provider_id |
どの Agent からも使われていない provider を削除 |
PUT |
/api/v2/agents/:agent_uid/worker-provider |
移行後などで provider 未設定状態の Agent に provider を割り当て |
signal routing rule
signal routing rule(API スキーマ上の名称は Signal Binding)は、外部チャネルのアダプターを特定の AI Colleague へルーティングするか(ai_colleague モード)、共有の Lark/Feishu・Slack Personal Assistant Bot で一致した送信者ごとの Personal Assistant へルーティングします(sender_personal_assistant モード、agent_uid は null)。
| メソッド | パス | 用途 |
|---|---|---|
GET |
/api/v2/signal-adapters |
このデプロイインスタンスで利用可能な signal アダプターを一覧取得 |
GET |
/api/v2/signal-bindings |
ルーティングルールを一覧取得(?agent= で対象 Agent を絞り込み可能) |
GET |
/api/v2/signal-bindings/:id |
ルーティングルールの詳細を取得 |
PUT |
/api/v2/signal-bindings/:adapter_id/:binding_name |
ルーティングルールを作成または再有効化 |
PATCH |
/api/v2/signal-bindings/:id |
ルーティングルールを更新 |
DELETE |
/api/v2/signal-bindings/:id |
ルーティングルールを無効化 |
POST |
/api/v2/agents/:agent_uid/signal-deliveries/requeue |
配信失敗した送信 Signal を再キューイング |
GET |
/api/v2/conversations/:conversation_id/standing-orders |
特定の Conversation の standing orders を取得 |
PUT |
/api/v2/conversations/:conversation_id/standing-orders |
特定の Conversation の standing orders を更新 |
binding を無効化すると、設定レコード自体を残したまま、新着 Signal による Agent の起動だけを止められます。
Agent Library の能力
Agent Library の既定値は選択中のテナントに属し、Agent ごとの上書き設定もそのテナント内で適用されます。
| メソッド | パス | 用途 |
|---|---|---|
GET |
/api/v2/agent-library/capabilities |
テナントのライブラリ機能一覧を取得 |
PUT |
/api/v2/agent-library/agent-plugins/:id |
Agent Plugin のテナント既定状態を設定 |
PUT |
/api/v2/agent-library/skills/:id |
Skill のテナント既定状態を設定 |
GET |
/api/v2/agents/:agent_uid/library-capabilities |
対象 Agent の実効能力一覧を取得 |
PUT |
/api/v2/agents/:agent_uid/library-capabilities/agent-plugins/:id |
特定の Agent に対して Plugin 設定を上書き |
PUT |
/api/v2/agents/:agent_uid/library-capabilities/skills/:id |
特定の Agent に対して Skill 設定を上書き |
GET |
/api/v2/agents/:agent_uid/library-documents |
Agent の永続ドキュメント一覧を取得 |
GET |
/api/v2/agents/:agent_uid/skill-lessons |
有効な Skill 教訓および廃止済み教訓を一覧取得 |
POST |
/api/v2/agents/:agent_uid/skill-lessons |
有効な Skill に人間由来の教訓を追加 |
POST |
/api/v2/agents/:agent_uid/skill-lessons/:lesson_id/retire |
Skill 教訓を廃止 |
まずテナント単位で既定の有効セットを決め、必要に応じて Agent ごとに許可範囲を絞ったり広げたりできます。Skill 教訓を使うと、元の SKILL.md を書き換えずに特定の Agent へ追加の作業指針を渡せます。一覧レスポンスには根拠や廃止履歴も含まれ、廃止された教訓は実行時に配信されなくなるほか、人間が却下・廃止した内容は Dreaming の再学習禁止リストに保持されます。ライフサイクルと制限の詳細については、Skill 教訓を参照してください。
環境変数(WorkerEnv)
WorkerEnv はサイト既定値、テナント上書き値、および Agent 個別の割り当て値の 3 階層を持ちます。通常の一覧・更新ルートが返すのはメタデータのみであり、暗号化された平文値の取得は監査証跡が残る専用の decryptions ルートで行います。
| メソッド | パス | 用途 |
|---|---|---|
GET |
/api/v2/site/worker-envs |
サイト既定の環境変数一覧を取得 |
PUT |
/api/v2/site/worker-envs/:name |
サイト既定値を設定 |
DELETE |
/api/v2/site/worker-envs/:name |
サイト既定値を削除 |
POST |
/api/v2/site/worker-envs/:name/decryptions |
サイト設定値を復号して取得 |
GET |
/api/v2/worker-envs |
テナントの環境変数一覧を取得 |
PUT |
/api/v2/worker-envs/:name |
テナント値を設定 |
DELETE |
/api/v2/worker-envs/:name |
テナント値を削除 |
POST |
/api/v2/worker-envs/:name/decryptions |
テナント設定値を復号して取得 |
GET |
/api/v2/agents/:agent_uid/worker-envs |
Agent の環境変数割り当て一覧を取得 |
PUT |
/api/v2/agents/:agent_uid/worker-envs/:name |
Agent 個別の値を設定・上書き |
DELETE |
/api/v2/agents/:agent_uid/worker-envs/:name |
Agent 個別の割り当てを削除 |
POST |
/api/v2/agents/:agent_uid/worker-envs/:name/decryptions |
Agent 個別の値を復号して取得 |
Agent の実行時には「Agent 個別値 → テナント値 → サイト既定値」の優先順で環境変数が解決されます。解決は Worker 上で新しい作業が始まるタイミングで行われ、すでに開いている既存の workspace は作成時点の環境変数を維持します。
Control Plane Plugin
| メソッド | パス | 用途 |
|---|---|---|
GET |
/api/v2/site/control-plane-plugins |
Control Plane Plugin の一覧と現在の状態を取得 |
PUT |
/api/v2/site/control-plane-plugins |
プラグインの有効/無効を切り替え |
Control Plane Plugin はコンパイル時に組み込まれるファーストパーティ拡張であり、Signals アダプター、Identity Provider アダプター、AI Gateway provider、Worker provider などの機能を control plane に追加します。activation: :always のプラグインはビルドに含まれ常時有効となります。PUT /api/v2/site/control-plane-plugins では次回起動時に有効にする :optional プラグインを切り替えますが、その際、使用中の Worker provider など有効なリソースを抱えているプラグインが誤って無効化されないよう、各サブシステムの veto_disable チェックが実行されます。
Identity provider と AppConfiguration
| メソッド | パス | 用途 |
|---|---|---|
GET |
/api/v2/identity-provider-adapters |
このデプロイインスタンスが対応する IdP アダプターを一覧取得 |
GET |
/api/v2/identity-providers |
設定済みの Identity Provider を一覧取得 |
PUT |
/api/v2/identity-providers/:provider_id |
IdP を作成または置換 |
POST |
/api/v2/identity-providers/:provider_id/sync-runs |
IdP からディレクトリおよびグループを同期 |
GET |
/api/v2/site/app-configurations |
サイトスコープの設定キー一覧を取得 |
PUT |
/api/v2/site/app-configurations/:key |
サイトスコープの設定値を更新 |
POST |
/api/v2/site/app-configurations/:key/decryptions |
サイトスコープの暗号化設定値を復号 |
GET |
/api/v2/app-configurations |
テナントスコープの設定キー一覧を取得 |
PUT |
/api/v2/app-configurations/:key |
テナントスコープの設定値を更新 |
POST |
/api/v2/app-configurations/:key/decryptions |
テナントスコープの暗号化設定値を復号 |
AppConfiguration は宣言済みの運用パラメータをサイト単位またはテナント単位で保持します。サイトキーは /api/v2/site/app-configurations で、テナントキーは /api/v2/app-configurations で管理し、いずれも一覧取得・単一キー取得・値の設定・上書きのリセット・監査付きの復号に対応しています。なお、PostgreSQL 接続前のブートストラップに必要な認証情報や初期設定は、環境変数またはシークレットマウントで渡します。
Tenant 管理
| メソッド | パス | 用途 |
|---|---|---|
GET |
/api/v2/site/tenants |
テナントを一覧取得 |
POST |
/api/v2/site/tenants |
テナントを新規作成 |
PATCH |
/api/v2/site/tenants/:tenant_id |
テナント情報を更新 |
DELETE |
/api/v2/site/tenants/:tenant_id |
テナントの削除を要求 |
POST |
/api/v2/site/tenants/:tenant_id/suspension |
テナントを一時停止 |
DELETE |
/api/v2/site/tenants/:tenant_id/suspension |
テナントの一時停止を解除 |
GET |
/api/v2/site/privileged-tenant |
特権テナントの情報を取得 |
PATCH |
/api/v2/site/privileged-tenant |
サイト管理権限を持つ特権テナントを別テナントへ移管 |
読み取り用の surface
Console API は設定変更だけでなく、システム全体の稼働状況を把握する観測(observability)経路としても機能します。各サブシステムの状態は次のルートから参照できます。
- 稼働中の Agent セッションとスケジュール:
/api/v2/agents/:agent_uid/sessions、および Agent ごとの cron スケジュール・checkback 管理ルート(テナント横断の一覧エンドポイントではagentクエリパラメータで絞り込み可能)。 - Worker の状態:
/api/v2/agent-workersから各 Agent の Worker 状態を一覧取得できます。 - 統合ドライブ(Unified Drive):
GET /api/v2/drive/:tenant_id/nodesでテナント内の各ルートや子ノードを一覧取得し、POST /api/v2/drive/:tenant_id/nodesでページや空ファイルを作成、PATCH /api/v2/drive/:tenant_id/nodes/:idで移動または名前変更、DELETE /api/v2/drive/:tenant_id/nodes/:idでサブツリーをゴミ箱へ移動します。バイナリ転送にはネイティブルートを使い、POST /api/v2/drive/:tenant_id/uploadsがマルチパートアップロード、GET /api/v2/drive/:tenant_id/nodes/:id/contentがバイトストリームのダウンロードに対応します。すべて同じブラウザーセッション、CSRF 検証、site_console:drive権限のもとで認可され、稼働中の Worker を必要としません。 - Background Agent Job:
/api/v2/background-agent-jobs(一覧取得、詳細取得、キャンセル)。 - AI 呼び出し履歴:
/api/v2/ai-gateway/conversations(会話ごとのモデル入出力メッセージ)。 - Principal、AuthZ、OIDC クライアント:
/api/v2/principals(POST /api/v2/principals/:uid/rename、PATCH /api/v2/principals/:uid/membership、POST /api/v2/principals/:uid/access-disables、POST /api/v2/principals/:uid/access-restorationsを含む)、/api/v2/principal-groups、/api/v2/permission-grants、および/api/v2/oidc-clients。これらは Principal と AuthZ で解説している権限モデルに対応しています。
ここに含まれないものについて
外部連携用の /webhooks/* では送信元プロバイダーの署名・トークン検証を行い、ランタイム AI 呼び出し用の /api/v1/ai-gateway/* では AIGateway トークン認証を使用します。このページで説明したブラウザーセッションおよび CSRF 検査が使われるのは、Console 向けの /api/v2 ルートです。
次のステップ
- Console から設定する各ランタイム境界の詳細については、AIGateway API、Signals、Sessions を参照してください。
- Console API 自身の認可を支える権限モデルについては、Principal と AuthZ を参照してください。
- 新しいデプロイインスタンスの立ち上げ手順については、クイックスタートの deployment セクション を参照してください。