Developer API - Agent Studio

Agent Studio APIを使用すると、Genie、ナレッジベース、スキルなどのAgent Studioアセットをプログラムで作成および管理できます。

レート制限

Agent Studioリソースには、次のレート制限があります:

タイプ	リソース	クォータ
GET	Genieを一覧表示: /api/agentic/genies	1分あたり1,000リクエスト
GET	IDでGenieを取得: /api/agentic/genies/:id	1分あたり1,000リクエスト
GET	すべての Genie会話エンドポイント	1秒あたり10リクエスト
すべて	その他すべてのGenieエンドポイント	1分あたり60リクエスト
GET	ナレッジベースを一覧表示: /api/agentic/knowledge_bases	1分あたり1,000リクエスト
GET	IDでナレッジベースを取得: /api/agentic/knowledge_bases/:id	1分あたり1,000リクエスト
すべて	その他すべてのナレッジベースエンドポイント	1分あたり60リクエスト
GET	スキルを一覧表示: /api/agentic/skills	1分あたり1,000リクエスト
GET	IDでスキルを取得: api/agentic/skills/:id	1分あたり1,000リクエスト
すべて	その他すべてのスキルエンドポイント	1分あたり60リクエスト

クイックリファレンス

タイプ	リソース	説明
GET	/api/agentic/genies	Genieのリストを返します。
POST	/api/agentic/genies	新しいGenieを作成します。
PUT	/api/agentic/genies/:id	既存のGenieを更新します。
GET	/api/agentic/genies/:id	指定したIDに関連付けられているGenieを返します。
DELETE	/api/agentic/genies/:id	Genieを削除します。
POST	/api/agentic/genies/:id/start	指定したIDに関連付けられているGenieを開始します。
POST	/api/agentic/genies/:id/stop	指定したIDに関連付けられているGenieを停止します。
POST	/api/agentic/genies/:id/assign_skills	指定したIDに関連付けられたgenieにSkillおよびMCPサーバーを割り当てます。
POST	/api/agentic/genies/:id/remove_skills	指定したIDに関連付けられているGenieからスキルを削除します。
POST	/api/agentic/genies/:id/assign_knowledge_bases	指定したIDに関連付けられているGenieにナレッジベースを割り当てます。
POST	/api/agentic/genies/:id/remove_knowledge_bases	指定したIDに関連付けられているGenieからナレッジベースを削除します。
POST	/api/agentic/genies/:id/assign_user_groups	指定したIDに関連付けられているGenieにユーザーグループアクセスを割り当てます。
POST	/api/agentic/genies/:id/remove_user_groups	指定したIDに関連付けられているGenieからユーザーグループアクセスを削除します。
GET	/api/agentic/genies/clients	Genieクライアントのリストを返します。
POST	/api/agentic/genies/clients	新しいGenieクライアント（APIキーまたはOAuth）を作成します。
GET	/api/agentic/genies/clients/:client_id	指定したIDに関連付けられているGenieクライアントを返します。
PUT	/api/agentic/genies/clients/:client_id	Genieクライアントの名前とOAuthリダイレクトURLを更新します。
DELETE	/api/agentic/genies/clients/:client_id	Genieクライアントを削除します。
POST	/api/agentic/genies/clients/:client_id/regenerate	GenieクライアントのAPIキーを再生成します。
POST	/api/agentic/genies/clients/:client_id/pause	Genieクライアントを一時停止します。
POST	/api/agentic/genies/clients/:client_id/start	一時停止中のGenieクライアントを開始します。
POST	/api/agentic/genies/:id/clients	クライアントをGenieにアタッチします。
DELETE	/api/agentic/genies/:id/clients/:client_id	クライアントをGenieからデタッチします。
GET	/api/agentic/genies/:genie_id/interfaces	Genieのすべてのチャットインターフェーストリガーを単一のリストで返します。
GET	/api/agentic/genies/:genie_id/conversations	Genieの会話のリストを返します。イベントレベルの詳細は含まれません。
GET	/api/agentic/genies/:genie_id/conversations/:conversation_id	指定したGenieの会話を返します。イベントレベルの詳細は含まれません。
GET	/api/agentic/genies/:genie_id/conversations/:conversation_id/events	1つの会話のすべてのイベントを返します。
GET	/api/agentic/genies/:genie_id/guardrails	指定したIDに関連付けられているGenieのガードレールとそのポリシーを返します。
PUT	/api/agentic/genies/:genie_id/guardrails/policies/:policy_type	指定したIDに関連付けられているGenieで、単一のガードレールポリシーを作成または更新します。
GET	/api/agentic/genies/guardrails/policies/pii_entities	`pii_detection`ポリシーで使用できるPIIエンティティタイプ文字列のリストを返します。
GET	/api/agentic/knowledge_bases	ナレッジベースのリストを返します。
POST	/api/agentic/knowledge_bases	新しいナレッジベースを作成します。
GET	/api/agentic/knowledge_bases/:id	指定したIDに関連付けられているナレッジベースを返します。
PUT	/api/agentic/knowledge_bases/:id	既存のナレッジベースを更新します。
DELETE	/api/agentic/knowledge_bases/:id	ナレッジベースを削除します。
GET	/api/agentic/knowledge_bases/:id/data_sources	指定したナレッジベースIDに関連付けられているデータソースを返します。
GET	/api/agentic/knowledge_bases/:id/recipes	指定したナレッジベースIDに関連付けられているレシピを返します。
GET	/api/agentic/skills	スキルのリストを返します。
POST	/api/agentic/skills	新しいスキルを作成します。
GET	/api/agentic/skills/:id	指定したIDに関連付けられているスキルを返します。

Genie

Agent StudioのGenieは、次のエンドポイントと構成をサポートしています：

Genieの一覧表示

Genieのリストを返します。各Genieには triggers[] 配列が含まれます。詳細についてはGenieトリガーを参照してください。

GET https://YOUR_DATA_CENTER/api/agentic/genies

クエリパラメーター

名前	タイプ	説明
folder_id	string 任意	Genieが存在するフォルダのID。
project_id	string 任意	Genieが存在するプロジェクトのID。
state	string 任意	Genieの状態。例: `active`または`inactive`。
page	integer 任意	取得するGenieのページ番号。最小値は`1`です。
per_page	integer 任意	1ページで返すGenieの数。最小値は`1`です。最大値は`50`です。

サンプルリクエスト

shell

curl  -X GET https://YOUR_DATA_CENTER/api/agentic/genies?per_page=:per_page_value&page=:page_value \
      -H 'Authorization: Bearer <api_token>'

サンプルレスポンス

明示的な設定がない場合、チャネル設定フィールドはデフォルト値で返されます。

レスポンスには Deprecation: true ヘッダーが含まれます。トップレベルの connection_id、custom_oauth_key_id、およびチャネル関連フィールドは非推奨です。代わりに triggers[] を使用してください。

json

[
  {
      "id": "gin-BWLSPX4z-BaT3D9",
      "name": "Customer Support Genie",
      "description": "顧客サポートの問い合わせを処理し、迅速に応答します。",
      "state": "stopped",
      "folder_id": 22991030,
      "instructions": "あなたは親切でフレンドリーなサポートエージェントです。顧客からの質問に、わかりやすく丁寧に回答します。",
      "ai_provider": "open_ai",
      "chat_interface": "slack",
      "channel_mode": "dms_only",
      "channel_scope": "specific",
      "response_mode": "on_mention",
      "channel_whitelist": [],
      "triggers": [
        {
          "id": "ginct-abc123",
          "platform": "slack",
          "name": "Slack - Acme",
          "status": "active",
          "shared_account_id": 1234,
          "custom_oauth_key_id": 5678,
          "channel_mode": "dms_only",
          "channel_scope": "specific",
          "response_mode": "on_mention",
          "channel_whitelist": []
        }
      ],
      "skills_count": 5,
      "knowledge_bases_count": 3,
      "user_groups_count": 0,
      "active_recipes_count": 0,
      "inactive_skills_count": 5,
      "logo_url": "https://example.com/logo.png",
      "created_at": "2025-07-15T11:07:34.060-07:00",
      "updated_at": "2026-02-24T08:38:29.099-08:00"
  },
  {
      "id": "gin-ZWSMPR4a-TaG7S9",
      "name": "Customer Support Genie v2",
      "description": "一般的なサポートに加えて、請求に関する問い合わせも処理するように更新されています。",
      "state": "stopped",
      "folder_id": 21285720,
      "instructions": "あなたは知識が豊富で丁寧なサポートアシスタントです。常に明確で簡潔な回答を優先してください。",
      "ai_provider": "open_ai",
      "chat_interface": "slack",
      "channel_mode": "everywhere",
      "channel_scope": "all_invited",
      "response_mode": "helpdesk",
      "channel_whitelist": [],
      "triggers": [
        {
          "id": "ginct-def456",
          "platform": "slack",
          "name": "Slack - Acme",
          "status": "active",
          "shared_account_id": 1234,
          "custom_oauth_key_id": 5678,
          "channel_mode": "everywhere",
          "channel_scope": "all_invited",
          "response_mode": "helpdesk",
          "channel_whitelist": []
        }
      ],
      "skills_count": 5,
      "knowledge_bases_count": 3,
      "user_groups_count": 0,
      "active_recipes_count": 0,
      "inactive_skills_count": 5,
      "logo_url": "https://example.com/logo.png",
      "created_at": "2026-02-24T08:54:34.585-08:00",
      "updated_at": "2026-02-25T09:34:14.013-08:00"
  }
]

Genieを作成する

新しいGenieを作成します。

POST https://YOUR_DATA_CENTER/api/agentic/genies

ペイロード

名前	タイプ	説明
name	string 必須	Genieの名前。
説明	string 必須	Genieの目的の説明。
folder_id	string 必須	Genieが存在するフォルダのID。
instructions	string 必須	Genieが目的、パーソナリティ、ジョブの説明を識別するために使用する指示。
ai_model	string 任意	Genieが使用するモデル。例えば: `gpt-4o`. `ai_provider`と併用します。カスタムプロバイダの場合は`null`を返します。
ai_provider	string 任意	Genieを動作させる内部プロバイダエンジン。許可されている値は`open_ai`、`anthropic`、`byollm`です。 `ai_model`と併用します。
ai_provider_type	string 任意	Genieを動作させるAIプロバイダの種類。 `ai_provider_id`と併用します。
ai_provider_id	string 任意	Genieを動作させるAIプロバイダのID。 `ai_provider_type`と併用します。
shared_account_id	integer 必須	GenieのコネクションID。 `triggers[]` を推奨とし、これは非推奨です。 `triggers[]` を送信した場合は無視されます。
custom_oauth_key_id	integer 必須	カスタムOAuthキーID。 `triggers[]` を推奨とし、これは非推奨です。 `triggers[]` を送信した場合は無視されます。
matrix	boolean 必須	Workato GOをチャットインターフェイスとして有効にするかどうかを決定します。使用できる値は`true`または`false`です。
channel_mode	string 任意	Genieが応答する場所を制御します。使用可能な値は`dms_only`または`everywhere`です。デフォルトは`dms_only`です。 `triggers[]` を推奨とし、これは非推奨です。 `triggers[]` を送信した場合は無視されます。
channel_scope	string 任意	Genieが応答するチャネルを決定します。使用可能な値は`specific`または`all_invited`です。デフォルトは`specific`です。 `triggers[]` を推奨とし、これは非推奨です。 `triggers[]` を送信した場合は無視されます。
response_mode	string 任意	Genieがチャネルでトリガーされる方法を制御します。使用可能な値は`on_mention`または`helpdesk`です。デフォルトは`on_mention`です。 `triggers[]` を推奨とし、これは非推奨です。 `triggers[]` を送信した場合は無視されます。
channel_whitelist	string[] 任意	Genieによる応答が許可されているSlackチャネルIDの配列です。 `channel_scope`が`specific`の場合にのみ適用されます。デフォルトは`[]`です。 `triggers[]` を推奨とし、これは非推奨です。 `triggers[]` を送信した場合は無視されます。
トリガー	オブジェクトの配列任意	Genieのチャットトリガー。サーバーが各エントリ用の `id` を生成します。スキーマ、検証ルール、レガシーフィールドの動作についてはGenieトリガーを参照してください。

サンプルリクエスト

shell


curl -X POST https://YOUR_DATA_CENTER/api/agentic/genies \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "name": ":genie_name",
           "description": ":description",
           "folder_id": ":folder_id",
           "instructions": ":instructions",
           "ai_provider": ":ai_provider",
           "shared_account_id": :shared_account_id,
           "custom_oauth_key_id": :custom_oauth_key_id,
           "matrix": :true_or_false,
           "channel_mode": ":channel_mode",
           "channel_scope": ":channel_scope",
           "response_mode": ":response_mode",
           "channel_whitelist": [":channel_id", ":channel_id"]
         }'

triggers[] を使用してGenieを作成:

shell


curl -X POST https://YOUR_DATA_CENTER/api/agentic/genies \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "name": ":genie_name",
           "description": ":description",
           "folder_id": ":folder_id",
           "instructions": ":instructions",
           "ai_provider": ":anthropic",
           "triggers": [
             {
               "platform": "slack",
               "name": ":trigger_name",
               "shared_account_id": :shared_account_id,
               "custom_oauth_key_id": :custom_oauth_key_id,
               "channel_mode": ":channel_mode",
               "channel_scope": ":channel_scope",
               "response_mode": ":response_mode",
               "channel_whitelist": [":channel_id"]
             }
           ]
         }'

サンプルレスポンス

json

{
  "id": "gin-BWLSPX4z-BaT3D9"
}

Genieを更新

既存のGenieを更新します。

PUT https://YOUR_DATA_CENTER/api/agentic/genies/:id

クエリパラメータ

名前	タイプ	説明
id	string 必須	更新するGenieのID。
name	string 任意	Genieの名前。
説明	string 任意	Genieの目的の説明。
folder_id	string 任意	Genieが存在するフォルダのID。
instructions	string 任意	Genieが目的、パーソナリティ、ジョブの説明を識別するために使用する指示。
ai_provider	string 任意	Genieを動作させる内部プロバイダエンジン。許可されている値は`open_ai`、`anthropic`、`byollm`です。 `ai_model`と併用します。
ai_model	string 任意	Genieが使用するモデル。例えば: `gpt-4o`. `ai_provider`と併用します。カスタムプロバイダの場合は`null`を返します。
ai_provider_type	string 任意	Genieを動作させるAIプロバイダの種類。 `ai_provider_id`と併用します。
ai_provider_id	string 任意	Genieを動作させるAIプロバイダのID。 `ai_provider_type`と併用します。
shared_account_id	integer 任意	GenieのコネクションID。 `triggers[]` を推奨とし、これは非推奨です。 `triggers[]` を送信した場合は無視されます。
custom_oauth_key_id	integer 任意	カスタムOAuthキーID。 `triggers[]` を推奨とし、これは非推奨です。 `triggers[]` を送信した場合は無視されます。
matrix	boolean 任意	Workato GOをチャットインターフェイスとして有効にするかどうかを決定します。使用できる値は`true`または`false`です。
channel_mode	string 任意	Genieが応答する場所を制御します。使用可能な値は`dms_only`または`everywhere`です。 `triggers[]` を推奨とし、これは非推奨です。 `triggers[]` を送信した場合は無視されます。
channel_scope	string 任意	Genieが応答するチャネルを決定します。使用可能な値は`specific`または`all_invited`です。 `triggers[]` を推奨とし、これは非推奨です。 `triggers[]` を送信した場合は無視されます。
response_mode	string 任意	Genieがチャネルでトリガーされる方法を制御します。使用可能な値は`on_mention`または`helpdesk`です。 `triggers[]` を推奨とし、これは非推奨です。 `triggers[]` を送信した場合は無視されます。
channel_whitelist	string[] 任意	Genieによる応答が許可されているSlackチャネルIDの配列です。 `channel_scope`が`specific`の場合にのみ適用されます。空の配列を渡すと、リストがクリアされます。 `triggers[]` を推奨とし、これは非推奨です。 `triggers[]` を送信した場合は無視されます。
トリガー	オブジェクトの配列任意	Genieのチャットトリガーの完全な一覧。既存のすべてのトリガーをアトミックに置き換えます。置換のセマンティクス、検証ルール、レガシーフィールドの動作についてはGenieトリガーを参照してください。

サンプルリクエスト

shell

curl -X PUT https://YOUR_DATA_CENTER/api/agentic/genies/:id \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "name": ":genie_name",
           "description": ":description",
           "instructions": ":instructions",
           "matrix": :true_or_false,
           "channel_mode": ":channel_mode_setting",
           "channel_scope": ":channel_scope",
           "response_mode": ":response_mode",
           "channel_whitelist": [":channel_id"]
         }'

Genieのトリガーを更新します。この例では、既存のトリガーを更新し、新しいトリガーを作成します。配列から欠落している既存のトリガーは削除されます:

shell

curl -X PUT https://YOUR_DATA_CENTER/api/agentic/genies/:id \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "triggers": [
             {
               "id": ":trigger_id",
               "status": "inactive",
               "channel_mode": ":channel_mode",
               "channel_scope": ":channel_scope",
               "channel_whitelist": [":channel_id"]
             },
             {
               "platform": "ms_teams",
               "shared_account_id": :shared_account_id,
               "custom_oauth_key_id": :custom_oauth_key_id
             }
           ]
         }'

サンプルレスポンス

json

{
  "id": "gin-ZWSMPR4a-TaG7S9",
  "name": "Customer Support Genie v2",
  "description": "一般的なサポートに加えて、請求に関する問い合わせも処理するように更新されています。",
  "folder_id": "7498",
  "project_id": "4567",
  "instructions": "あなたは知識が豊富で丁寧なサポートアシスタントです。常に明確で簡潔な回答を優先してください。",
  "ai_provider": "open_ai",
  "ai_provider_type": "<ai_provider_type>",
  "ai_provider_id": "<ai_provider_id>",
  "shared_account_id": 1234,
  "custom_oauth_key_id": 5678,
  "matrix": false,
  "channel_mode": "everywhere",
  "channel_scope": "specific",
  "response_mode": "on_mention",
  "channel_whitelist": ["C0A9H9EN7J6"]
}

IDでGenieを取得

指定したIDに関連付けられているGenieを返します。 Genieにはtriggers[]配列と、LLM構成であるai_provider_typeおよびai_provider_idが含まれます。詳細についてはGenieトリガーを参照してください。

GET https://YOUR_DATA_CENTER/api/agentic/genies/:id

クエリパラメータ

名前	タイプ	説明
id	string 必須	取得するGenieのID。

サンプルリクエスト

shell

curl -X GET https://YOUR_DATA_CENTER/api/agentic/genies/:id \
     -H 'Authorization: Bearer <api_token>'

サンプルレスポンス

明示的な設定がない場合、チャネル設定フィールドはデフォルト値で返されます。

json

{
  "id": "gin-ZWSMPR4a-TaG7S9",
  "name": "Customer Support Genie v2",
  "description": "一般的なサポートに加えて、請求に関する問い合わせも処理するように更新されています。",
  "state": "stopped",
  "folder_id": 21285720,
  "project_id": 93761783,
  "instructions": "あなたは知識が豊富で丁寧なサポートアシスタントです。常に明確で簡潔な回答を優先してください。",
  "ai_provider": "open_ai",
  "ai_provider_type": "<ai_provider_type>",
  "ai_provider_id": "<ai_provider_id>",
  "chat_interface": "slack",
  "channel_mode": "dms_only",
  "channel_scope": "specific",
  "response_mode": "on_mention",
  "channel_whitelist": [],
  "triggers": [
    {
      "id": "ginct-abc123",
      "platform": "slack",
      "name": "Slack - Acme",
      "status": "active",
      "shared_account_id": null,
      "custom_oauth_key_id": 5678,
      "channel_mode": "dms_only",
      "channel_scope": "specific",
      "response_mode": "on_mention",
      "channel_whitelist": []
    }
  ],
  "skills_count": 5,
  "knowledge_bases_count": 3,
  "user_groups_count": 0,
  "active_recipes_count": 0,
  "inactive_skills_count": 5,
  "custom_oauth_key_id": 5678,
  "connection_id": null,
  "folders": [
      {
          "id": 21285720,
          "name": "Customer Assistants"
      }
  ],
  "logo_url": "https://example.com/logo.png",
  "user_groups": [],
  "created_at": "2026-02-24T08:54:34.170-08:00",
  "updated_at": "2026-02-25T09:34:14.300-08:00"
}

Genieを削除

Genieを削除します。

DELETE https://YOUR_DATA_CENTER/api/agentic/genies/:id

クエリパラメータ

名前	タイプ	説明
id	string 必須	削除するGenieのID。

サンプルリクエスト

shell

curl -X DELETE https://YOUR_DATA_CENTER/api/agentic/genies/:id \
     -H 'Authorization: Bearer <api_token>'

サンプルレスポンス

json

{
    "success": "true"
}

Genieを開始

指定したIDに関連付けられているGenieを開始します。

POST https://YOUR_DATA_CENTER/api/agentic/genies/:id/start

クエリパラメータ

名前	タイプ	説明
id	string 必須	開始するGenieのID。

サンプルリクエスト

shell

curl -X POST https://YOUR_DATA_CENTER/api/agentic/genies/:id/start \
     -H 'Authorization: Bearer <api_token>'

サンプルレスポンス

json

{
  "success": true
}

Genieを停止

指定したIDに関連付けられているGenieを停止します。

POST https://YOUR_DATA_CENTER/api/agentic/genies/:id/stop

クエリパラメータ

名前	タイプ	説明
id	string 必須	停止するGenieのID。

サンプルリクエスト

shell

curl -X POST https://YOUR_DATA_CENTER/api/agentic/genies/:id/stop \
     -H 'Authorization: Bearer <api_token>'

サンプルレスポンス

json

{
  "success": true
}

Genieにスキルを割り当て

指定したIDに関連付けられたgenieにSkillおよびMCPサーバーを割り当てます。

POST https://YOUR_DATA_CENTER/api/agentic/genies/:id/assign_skills

クエリパラメータ

名前	タイプ	説明
id	string 必須	スキルを割り当てるGenieのID。

ペイロード

名前	タイプ	説明
skill_ids	文字列の配列任意	Genieに割り当てるスキルIDの配列。
mcp_server_ids	文字列の配列任意	Genieに割り当てるMCPサーバーIDの配列。

skill_idsまたはmcp_server_idsの少なくとも一方は送信する必要があります。

サンプルリクエスト

スキルを割り当て:

shell

curl -X POST https://YOUR_DATA_CENTER/api/agentic/genies/:id/assign_skills \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "skill_ids": [":skill_id", ":skill_id", ":skill_id"]
         }'

サンプルレスポンス

json

{
    "skills": [
    {
      "id": "65001201",
      "name": "Sales Lead"
    },
    {
      "id": "65704499",
      "name": "Ticket Escalation"
    },
    {
      "id": "65039789",
      "name": "Order Tracking"
    }
  ],
}

MCPサーバー割り当てサンプルリクエスト

MCPサーバーを割り当て:

shell

curl -X POST https://YOUR_DATA_CENTER/api/agentic/genies/:id/assign_skills \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "mcp_server_ids": [":mcp_server_id"]
         }'

Genieからスキルを削除

指定したIDに関連付けられているGenieからスキルを削除します。

POST https://YOUR_DATA_CENTER/api/agentic/genies/:id/remove_skills

クエリパラメータ

名前	タイプ	説明
id	string 必須	スキルを削除するGenieのID。

ペイロード

名前	タイプ	説明
skill_ids	stringの配列必須	Genieから削除するスキルIDの配列。

サンプルリクエスト

shell

curl -X POST https://YOUR_DATA_CENTER/api/agentic/genies/:id/remove_skills \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "skill_ids": [":skill_id", ":skill_id"]
         }'

サンプルレスポンス

json

{
    "skills": [
    {
      "id": "65001201",
      "name": "Sales Lead"
    },
    {
      "id": "65704499",
      "name": "Ticket Escalation"
    }
  ],
}

Genieにナレッジベースを割り当て

指定したIDに関連付けられているGenieにナレッジベースを割り当てます。

POST https://YOUR_DATA_CENTER/api/agentic/genies/:id/assign_knowledge_bases

クエリパラメータ

名前	タイプ	説明
id	string 必須	ナレッジベースを割り当てるGenieのID。

ペイロード

名前	タイプ	説明
knowledge_base_ids	stringの配列必須	Genieに割り当てるナレッジベースIDの配列。

サンプルリクエスト

shell

curl -X POST https://YOUR_DATA_CENTER/api/agentic/genies/:id/assign_knowledge_bases \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "knowledge_base_ids": [":knowledge_base_id", ":knowledge_base_id"]
         }'

サンプルレスポンス

json

{
    "knowledge_bases": [
    {
      "id": "kb-WSm8kore-blMxrh",
      "name": "Sync Jira"
    },
    {
      "id": "kb-ATx0crok-saMvba",
      "name": "PRD sync"
    }
  ],
}

Genieからナレッジベースを削除

指定したIDに関連付けられているGenieからナレッジベースを削除します。

POST https://YOUR_DATA_CENTER/api/agentic/genies/:id/remove_knowledge_bases

クエリパラメータ

名前	タイプ	説明
id	string 必須	ナレッジベースを削除するGenieのID。

ペイロード

名前	タイプ	説明
knowledge_base_ids	stringの配列必須	Genieから削除するナレッジベースIDの配列。

サンプルリクエスト

shell

curl -X POST https://YOUR_DATA_CENTER/api/agentic/genies/:id/remove_knowledge_bases \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "knowledge_base_ids": [":knowledge_base_id"]
         }'

サンプルレスポンス

json

{
    "knowledge_bases": [
    {
      "id": "kb-WSm8kore-blMxrh",
      "name": "Sync Jira"
    }
  ],
}

Genieにユーザーグループを割り当て

指定したIDに関連付けられているGenieにユーザーグループアクセスを割り当てます。

POST https://YOUR_DATA_CENTER/api/agentic/genies/:id/assign_user_groups

クエリパラメータ

名前	タイプ	説明
id	string 必須	ユーザーグループアクセスを割り当てるGenieのID。

ペイロード

名前	タイプ	説明
user_group_ids	stringの配列必須	Genieに追加するユーザーグループIDの配列。

サンプルリクエスト

shell

curl -X POST https://YOUR_DATA_CENTER/api/agentic/genies/:id/assign_user_groups \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "user_group_ids": [":user_group_id", ":user_group_id"]
         }'

サンプルレスポンス

json

{
    "user_groups": [
    {
      "id": "ertXU2Z3sQaL47T8PssX2V",
      "name": "Sales"
    },
    {
      "id": "gpzHU1Y3mJaG77W1JbbZ2B",
      "name": "Finance"
    },
  ],
}

Genieからユーザーグループを削除

指定したIDに関連付けられているGenieからユーザーグループアクセスを削除します。

POST https://YOUR_DATA_CENTER/api/agentic/genies/:id/remove_user_groups

クエリパラメータ

名前	タイプ	説明
id	string 必須	ユーザーグループアクセスを削除するGenieのID。

ペイロード

名前	タイプ	説明
user_group_ids	stringの配列必須	Genieから削除するユーザーグループIDの配列。

サンプルリクエスト

shell

curl -X POST https://YOUR_DATA_CENTER/api/agentic/genies/:id/remove_user_groups \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "user_group_ids": [":user_group_id"]
         }'

サンプルレスポンス

json

{
    "user_groups": [
    {
      "id": "ertXU2Z3sQaL47T8PssX2V",
      "name": "Sales"
    }
  ],
}

Genieトリガー

トリガーは、Slack、Microsoft Teams、またはWorkato GOなど、Genieが応答するチャットインターフェースです。 triggers[] 配列は、List genies、Get a genie by ID、Create a genie、Update a genie で利用できます。カスタムクライアントは別個のリソースであり、triggers[] の一部ではありません。詳細についてはGenieクライアントを参照してください。

このエンドポイントを使用するには、次の権限をAPIクライアントに追加します。

権限	必須対象
`genie_interfaces.index`	Genieのチャットインターフェーストリガーの一覧

トリガーフィールド

名前	タイプ	説明
id	string	トリガーのハンドル。例: `ginct-abc123`。この値はサーバーが生成します。作成時には省略し、既存のトリガーを変更する場合は更新時に含めてください。
プラットフォーム	string	チャットプラットフォーム。許可される値は `slack`、`ms_teams`、`matrix` です。 `matrix` はWorkato GOです。
name	string 任意	トリガーの名前。
status	string 任意	トリガーの希望する状態。リクエストで指定できる値は `active` または `inactive` です。トリガーを一時停止するには `inactive` を、開始するには `active` を使用します。新しいトリガーは `active` として開始されます。レスポンスでは `active`、`inactive`、または `warning` が返されます。その他の値をリクエストに指定した場合は `422` が返されます。
shared_account_id	integer 任意	トリガーのConnection ID。 `matrix` トリガーの場合は `null` として返されます。
custom_oauth_key_id	integer 任意	カスタムOAuthキーID。 `matrix` トリガーの場合は `null` として返されます。
channel_mode	string 任意	Genieが応答する場所を制御します。使用可能な値は`dms_only`または`everywhere`です。
channel_scope	string 任意	Genieが応答するチャネルを決定します。使用可能な値は`specific`または`all_invited`です。
response_mode	string 任意	Genieがチャネルでトリガーされる方法を制御します。使用可能な値は`on_mention`または`helpdesk`です。
channel_whitelist	string[] 任意	Genieによる応答が許可されているSlackチャネルIDの配列です。 `channel_scope`が`specific`の場合にのみ適用されます。

トリガーレスポンスのサンプル

json

{
  "data": {
    "id": 123,
    "name": "My Genie",
    "triggers": [
      {
        "id": "ginct-abc123",
        "platform": "slack",
        "name": "Slack - Acme",
        "status": "active",
        "shared_account_id": 1234,
        "custom_oauth_key_id": 5678,
        "channel_mode": "everywhere",
        "channel_scope": "specific",
        "response_mode": "on_mention",
        "channel_whitelist": ["C1H9RESGL"]
      },
      {
        "id": "ginct-def456",
        "platform": "matrix",
        "name": "Workato Go",
        "status": "active",
        "shared_account_id": null,
        "custom_oauth_key_id": null,
        "channel_mode": "dms_only",
        "channel_scope": "specific",
        "response_mode": "on_mention",
        "channel_whitelist": []
      }
    ],
    "connection_id": 1234,
    "custom_oauth_key_id": 5678,
    "channel_mode": "everywhere"
  }
}

更新時の置換セマンティクス

Update a genie での triggers[] はアトミックな全置換です。

id のないエントリは新しいトリガーを作成します。
id を持つエントリは既存のトリガーを更新します。
配列から欠落している既存のトリガーは削除されます。
"triggers": [] はすべてのトリガーを削除します。
不明な id が含まれている場合は 422 が返され、何も適用されません。

1 回のリクエストで 2 つのトリガー間でコネクションを入れ替えることができます。

検証

検証はアトミックです。いずれかのエントリが失敗した場合、そのエントリを含め何も適用されません。エラーには、triggers[2].field: message の形式でエントリインデックスが含まれます。

ケース	エラー
`channel_scope` が `specific` であり、かつ非空の `channel_whitelist` が指定されていない	`triggers[i].channel_whitelist` に対して `422`
`channel_mode` が `dms_only`、または `channel_scope` が `all_invited` に設定されている状態で `channel_whitelist` が空でない	`triggers[i].channel_whitelist` に対して `422`
同じ `shared_account_id` を持つエントリが 1 回のリクエスト内に 2 つある	`422` コネクションの排他制約
別のトリガーまたはGenieですでに使用されているコネクション	`422` コネクションの排他制約
エントリが50件を超えている	`422` 上限
更新時の `id` が不明	`422` 不明なトリガーID
`status` が `active` または `inactive` ではない	`triggers[i].status` に対して `422`
Genie に対する `matrix` エントリが複数存在する。 Genie は Workato GO トリガーを複数サポートします。	`422`
`triggers` が配列ではない	`400`

コネクションフィールド shared_account_id と custom_oauth_key_id、およびチャネルフィールド channel_mode、channel_scope、response_mode、channel_whitelist は、matrix トリガーでは無視されます。 matrix トリガーはデフォルト値を保持します。

レガシーフィールドとの互換性

トップレベルの connection_id、custom_oauth_key_id、channel_mode、channel_scope、response_mode、channel_whitelist フィールドは引き続き利用できますが、非推奨です。 List genies および Get a genie by ID のレスポンスには、Deprecation: true ヘッダーが含まれます。

レスポンス: レガシーフィールドは最も古いアクティブなトリガー triggers[0] を反映します。
リクエスト: connection_id や shared_account_id、custom_oauth_key_id、channel_* などのレガシーなフラットフィールドは、triggers[] を送信しない場合にのみ適用されます。これらのフィールドは、最も古いアクティブなトリガー triggers[0] に適用されます。その他のトリガーは変更されません。
両方を送信した場合、フラットフィールドは無視され、triggers[] のみが適用されます。

Genieクライアント

Genieクライアントは、アプリケーションがHeadless API経由でGenieを呼び出すために使用するランタイム認証情報を使用します。クライアントを作成し、Genieにアタッチする必要があります。クライアントは実行時にAPIキーまたはOAuth 2.0（PKCE）で認証します。

Genie ごとの複数クライアント、クライアントごとの単一 Genie

Genie には複数のクライアントを紐付けることができます。クライアントは、常に 1 つの Genie にのみ属します。すでに別のGenieに紐付いているクライアントをアタッチしようとすると、Client is already assigned to another genie というメッセージ付きで 409 コンフリクトが返されます。クライアントの向き先を変更するには、まず既存のペアリングをデタッチします。

ワークスペースで Genie あたり複数クライアントが有効になっていない場合、Genie は単一のクライアントのみをサポートします。 2 つ目のクライアントをアタッチしようとすると、409 コンフリクトが返されます。

Genie は、カスタムクライアントと Slack または Microsoft Teams インターフェースを同時に持つことができます。

利用可能状況と権限

次の機能を使用するには、ワークスペースでGenieあたり複数クライアントが有効になっている必要があります。有効化についてはカスタマーマネージャーに連絡してください。

Genieのリクエストおよびレスポンス内の triggers[]
Genieクライアントレスポンス内の status、type、base_host、activated_at、genie_ids
Genieクライアントのget、pause、startエンドポイント
Genieインターフェース一覧エンドポイント
会話レスポンス内の trigger_id および trigger_name、ならびに trigger_id 会話フィルター
Genie インターフェースの一覧

これらのエンドポイントは、Genieあたり複数クライアントが有効になっていない場合、403 エラーを返します。

これらのエンドポイントを使用するには、次の権限をAPIクライアントに追加します。

権限	必須対象
`genie_clients.show`	Genie クライアントの取得
`genie_clients.start`	Genie クライアントの開始
`genie_clients.pause`	Genie クライアントの一時停止

Genieクライアントのリスト

ワークスペース内のGenieクライアントを返します。

GET https://YOUR_DATA_CENTER/api/agentic/genies/clients

クエリパラメータ

名前	タイプ	説明
genie_id	string 任意	結果をフィルタリングするためのGenieのハンドル。そのGenieに割り当てられているクライアントのみが返されます。例: `gin-abc`。

サンプルリクエスト

shell

curl -X GET https://YOUR_DATA_CENTER/api/agentic/genies/clients \
     -H 'Authorization: Bearer <api_token>'

Genieで絞り込む:

shell

curl -X GET "https://YOUR_DATA_CENTER/api/agentic/genies/clients?genie_id=:genie_handle" \
     -H 'Authorization: Bearer <api_token>'

サンプルレスポンス

ワークスペースでGenieあたり複数クライアントが有効になっている場合、各クライアントは status、type、base_host、activated_at、ip_allow_list、genie_ids も返します。 Client response fields を参照してください。

json

{
  "data": [
    {
      "client_id": "gincl-AaBGpLGx-HLdsJL",
      "client_name": "HR Concierge Web",
      "status": "active",
      "type": "api_key",
      "base_host": "genie-api.workato.com",
      "activated_at": null,
      "ip_allow_list": [],
      "genie_ids": ["gin-abc"]
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 10
}

クライアントレスポンスフィールド

名前	タイプ	説明
client_id	string	クライアントのID。
client_name	string	クライアントの名前。
status	string	クライアントの状態。 `active`、`inactive`、または `warning` が返されます。
type	string	クライアントの認証タイプ。 `api_key` または `oauth` が返されます。
base_host	string	クライアントがGenieを呼び出す際に使用するホスト。
activated_at	string	クライアントが最初にアクティブ化された時刻。まだアクティブ化されていない場合は `null` が返されます。
ip_allow_list	array	クライアントの使用を許可されているIPアドレス。
genie_ids	文字列の配列	クライアントが割り当てられているGenieのハンドル。

Genieクライアントの作成

Genieクライアントを作成します。サーバー間認証情報にはauth.typeをapi_keyに設定し、ブラウザーベースのOAuth 2.0（PKCE）クライアントにはoauthを設定します。

POST https://YOUR_DATA_CENTER/api/agentic/genies/clients

ペイロード

名前	タイプ	説明
client_name	string 必須	クライアントの名前。
auth	オブジェクト必須	認証設定。
auth.type	string 必須	認証タイプ。使用できる値は`api_key`および`oauth`です。
auth.oauth_redirect_url	文字列または文字列の配列任意	OAuthフロー用に登録されたリダイレクトURLまたはURLの一覧。複数のリダイレクトURLを登録するには、配列を渡します。 `auth.type`が`oauth`の場合は必須です。

サンプルリクエスト

shell

curl -X POST https://YOUR_DATA_CENTER/api/agentic/genies/clients \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{ "client_name": ":client_name", "auth": { "type": ":auth_type" } }'

複数のリダイレクトURLを持つOAuthクライアントを作成:

shell

curl -X POST https://YOUR_DATA_CENTER/api/agentic/genies/clients \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "client_name": ":client_name",
           "auth": {
             "type": "oauth",
             "oauth_redirect_url": [":redirect_url", ":redirect_url"]
           }
         }'

サンプルレスポンス

APIキーのクライアントは、作成時に1回だけ返される64文字の16進文字列を持つapi_keyを使用します。すべてのクライアントは公開oauth_client_idも返します。 OAuthクライアントはシークレットを返しません。

ワークスペースでGenieあたり複数クライアントが有効になっている場合、レスポンスには status、type、base_host、activated_at、ip_allow_list、genie_ids も含まれます。

json

{
  "data": {
    "client_id": "gincl-AaBGpLGx-HLdsJL",
    "client_name": "HR Concierge Web",
    "oauth_client_id": "MtaJ4c5oIc3_c0TASWnCW0rfmCr6R4UTO7",
    "api_key": "<64-character hex string>",
    "status": "active",
    "type": "api_key",
    "base_host": "genie-api.workato.com",
    "activated_at": null,
    "ip_allow_list": [],
    "genie_ids": []
  }
}

Genieクライアントを取得

指定したIDに関連付けられているGenieクライアントを返します。 OAuthクライアントは、oauth_client_id および oauth_redirect_url も返します。 genie_clients.show 権限が必要です。

GET https://YOUR_DATA_CENTER/api/agentic/genies/clients/:client_id

パスパラメータ

名前	タイプ	説明
client_id	string 必須	取得するクライアントのID。

サンプルリクエスト

shell

curl -X GET https://YOUR_DATA_CENTER/api/agentic/genies/clients/:client_id \
     -H 'Authorization: Bearer <api_token>'

サンプルレスポンス

json

{
  "data": {
    "client_id": "gincl-xyz789",
    "client_name": "Custom API Client 1",
    "status": "active",
    "type": "api_key",
    "base_host": "genie-api.workato.com",
    "activated_at": null,
    "ip_allow_list": [],
    "genie_ids": ["gin-abc"]
  }
}

OAuthクライアントは次のフィールドも返します。

json

{
  "data": {
    "client_id": "gincl-AaBGpLGx-HLdsJL",
    "client_name": "HR Concierge Web",
    "status": "active",
    "type": "oauth",
    "base_host": "genie-api.workato.com",
    "activated_at": null,
    "ip_allow_list": [],
    "genie_ids": ["gin-abc"],
    "oauth_client_id": "MtaJ4c5oIc3_c0TASWnCW0rfmCr6R4UTO7",
    "oauth_redirect_url": ["https://example.com/callback"]
  }
}

エラーレスポンス

Status	条件
`403 Forbidden`	ワークスペースでGenieあたり複数クライアントが有効になっていないか、APIクライアントに `genie_clients.show` 権限がありません。
`404 Not Found`	クライアントが存在しないか、削除されています。

Genieクライアントの更新

Genieクライアントの名前とOAuthリダイレクトURLを更新します。

PUT https://YOUR_DATA_CENTER/api/agentic/genies/clients/:client_id

ペイロード

名前	タイプ	説明
client_name	string 必須	クライアントの新しい名前。
auth.oauth_redirect_url	文字列または文字列の配列任意	OAuthクライアント用のリダイレクトURLまたはURLの一覧。既存のリダイレクトURLを置き換えます。複数のリダイレクトURLを登録するには、配列を渡します。 OAuthクライアントに対して空の配列を指定すると `422` が返されます。

サンプルリクエスト

shell

curl -X PUT https://YOUR_DATA_CENTER/api/agentic/genies/clients/:client_id \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{ "client_name": ":client_name" }'

OAuthクライアントのリダイレクトURLを更新:

shell

curl -X PUT https://YOUR_DATA_CENTER/api/agentic/genies/clients/:client_id \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "client_name": ":client_name",
           "auth": { "oauth_redirect_url": [":redirect_url", ":redirect_url"] }
         }'

Genieクライアントの削除

Genieクライアントを削除し、その認証情報を無効にします。 Genieクライアントを削除せずにGenieから取り外すには、Genieクライアントをデタッチします。

DELETE https://YOUR_DATA_CENTER/api/agentic/genies/clients/:client_id

サンプルリクエスト

shell

curl -X DELETE https://YOUR_DATA_CENTER/api/agentic/genies/clients/:client_id \
     -H 'Authorization: Bearer <api_token>'

Genieクライアントキーの再生成

APIキーのクライアントのAPIキーを再生成します。以前のキーは直ちに無効になり、新しいキーは1回だけ返されます。

POST https://YOUR_DATA_CENTER/api/agentic/genies/clients/:client_id/regenerate

サンプルリクエスト

shell

curl -X POST https://YOUR_DATA_CENTER/api/agentic/genies/clients/:client_id/regenerate \
     -H 'Authorization: Bearer <api_token>'

サンプルレスポンス

json

{
  "data": {
    "api_key": "<64-character hex string>",
    "updated_at": "2026-06-15T06:44:40-07:00"
  }
}

Genieクライアントを一時停止

Genieクライアントを一時停止します。クライアントの status は inactive に変更されます。すでに一時停止されているクライアントを再度一時停止しても効果はなく、200 が返されます。 genie_clients.pause 権限が必要です。

POST https://YOUR_DATA_CENTER/api/agentic/genies/clients/:client_id/pause

サンプルリクエスト

shell

curl -X POST https://YOUR_DATA_CENTER/api/agentic/genies/clients/:client_id/pause \
     -H 'Authorization: Bearer <api_token>'

サンプルレスポンス

json

{
  "data": {
    "status": "inactive"
  }
}

エラーレスポンス

Status	条件
`403 Forbidden`	ワークスペースでGenieあたり複数クライアントが有効になっていないか、APIクライアントに `genie_clients.pause` 権限がありません。
`404 Not Found`	クライアントが存在しないか、削除されています。

Genieクライアントを開始

一時停止中のGenieクライアントを開始します。クライアントの status は active に変更されます。すでにアクティブなクライアントを開始しても効果はなく、200 が返されます。 genie_clients.start 権限が必要です。

POST https://YOUR_DATA_CENTER/api/agentic/genies/clients/:client_id/start

サンプルリクエスト

shell

curl -X POST https://YOUR_DATA_CENTER/api/agentic/genies/clients/:client_id/start \
     -H 'Authorization: Bearer <api_token>'

サンプルレスポンス

json

{
  "data": {
    "status": "active"
  }
}

エラーレスポンス

Status	条件
`403 Forbidden`	ワークスペースでGenieあたり複数クライアントが有効になっていないか、APIクライアントに `genie_clients.start` 権限がありません。
`404 Not Found`	クライアントが存在しないか、削除されています。

クライアントのGenieへのアタッチ

指定したGenieにクライアントをアタッチします。 Genie には複数のクライアントを持たせることができます。クライアントは一度に1つのGenieにのみアタッチできます。すでに別のGenieに紐付いているクライアントをアタッチしようとすると、Client is already assigned to another genie というメッセージとともに 409 が返されます。レスポンスにはクライアントの status が含まれます。

ワークスペースでGenieあたり複数クライアントが有効になっていない場合、そのGenieには既存のクライアントが存在していてはなりません。

POST https://YOUR_DATA_CENTER/api/agentic/genies/:id/clients

ペイロード

名前	タイプ	説明
genie_client_id	string 必須	アタッチするクライアントのID。

サンプルリクエスト

shell

curl -X POST https://YOUR_DATA_CENTER/api/agentic/genies/:id/clients \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{ "genie_client_id": ":genie_client_id" }'

クライアントのGenieからのデタッチ

指定したGenieからクライアントをデタッチします。クライアントは削除されず、別のGenieにアタッチできます。

DELETE https://YOUR_DATA_CENTER/api/agentic/genies/:id/clients/:client_id

サンプルリクエスト

shell

curl -X DELETE https://YOUR_DATA_CENTER/api/agentic/genies/:id/clients/:client_id \
     -H 'Authorization: Bearer <api_token>'

チャットインターフェーストリガー

チャットインターフェーストリガーをプログラムから使用するには、次の要件を満たしていることを確認してください。

ワークスペースでGenieあたり複数クライアントが有効になっていること
genie_interfaces.index 権限

チャットインターフェーストリガーの一覧

Genie に対するチャットインターフェーストリガーを単一の一覧として返します。 type フィールドを使用してチャットインターフェーストリガーを判別します。slack、ms_teams、matrix に加えて、カスタムクライアントには api、レシピには recipe が使用されます。結果は名前でソートされます。このエンドポイントは読み取り専用です。このエンドポイントを使用するには、genie_interfaces.index 権限が必要です。

GET https://YOUR_DATA_CENTER/api/agentic/genies/:genie_id/interfaces

パスパラメータ

名前	タイプ	説明
genie_id	string 必須	インターフェースを取得する対象のGenieのID。

クエリパラメータ

名前	タイプ	説明
query	string 任意	チャットインターフェーストリガー名に対して大文字小文字を区別せずに照合する部分文字列。すべてのインターフェースタイプに適用されます。
page	integer 任意	取得するページ番号。 `1`から開始します。
per_page	integer 任意	1 ページ内で返すインターフェース数。デフォルトは`20`です。最大値は`50`です。より大きい値は `50` に切り詰められます。

サンプルリクエスト

shell

curl -X GET "https://YOUR_DATA_CENTER/api/agentic/genies/:genie_id/interfaces?query=:query&page=:page_value&per_page=:per_page_value" \
     -H 'Authorization: Bearer <api_token>'

サンプルレスポンス

total は、query を適用した後、ページングを行う前の、条件に一致するチャットインターフェーストリガーの数です。チャットインターフェーストリガーは connection_id を返します。これはGenieの triggers[] 配列における shared_account_id と同じ値です。

json

{
  "data": [
    {
      "id": "ginct-abc",
      "name": "Slack - Acme",
      "type": "slack",
      "status": "active",
      "connection_id": 42,
      "channel_mode": "everywhere"
    },
    {
      "id": "gincl-xyz",
      "name": "API Client 1",
      "type": "api",
      "status": "active",
      "auth_type": "api_key",
      "base_host": "genie-api.workato.com",
      "ip_allow_list": [],
      "activated_at": null
    },
    {
      "id": "1842",
      "name": "Handle ticket",
      "type": "recipe",
      "status": "inactive",
      "running": false,
      "trigger_application": "salesforce",
      "latest_activity": {}
    }
  ],
  "total": 3,
  "page": 1,
  "per_page": 20
}

エラーレスポンス

ワークスペースでGenieあたり複数クライアントが有効になっていないか、APIクライアントに genie_interfaces.index 権限がない場合、403 Forbidden エラーレスポンスが返されます。

会話

会話エンドポイントは、サポートチケットへのトランスクリプトの添付、アドホック調査、レシピベースの自動化など、リアルタイムストリーミングを必要としないユースケース向けにGenieの会話データを公開します。リアルタイムストリーミングが必要なケースでは、監査ログストリーミングを使用します。

ENVIRONMENTスコープのエンドポイント

すべての会話エンドポイントは、使用されたAPIクライアントのEnvironmentにスコープ設定されたデータを返します。レスポンス内のenvironment_typeフィールドとenvironment_idフィールドは、データが属するEnvironmentを識別します。 Environment全体で会話データを取得するには、個別のAPIクライアントを作成して結果を結合します。

会話の一覧表示

Genieが行った会話のリストを返します。最近アクティブだった会話が最初に返されます。

GET /api/agentic/genies/:genie_id/conversations

パスパラメーター

名前	タイプ	説明
genie_id	string 必須	取得する会話が属するGenieのID。

クエリパラメータ

名前	タイプ	説明
page[after]	string 任意	現在のページの最後の結果に基づく、次の結果セットの開始位置。
page[size]	integer 任意	ページごとに取得する項目数。デフォルト値は`50`、最大値は`100`です。
from	string 任意	ISO 8601形式（`YYYY-MM-DDTHH:mm:ss.SSSZ`）での`created_at`の下限。デフォルトは保持期間の開始時点です。
to	string 任意	ISO 8601形式（`YYYY-MM-DDTHH:mm:ss.SSSZ`）での`created_at`の上限。デフォルトは現在時刻です。
app_type	string 任意	結果のフィルタリングに使用するトリガーソース。使用できる値は`slack`、`teams`、`go`、`headless_api`、`test_mode`、`genie_task`、または`app_event`です。デフォルトはすべてのソースです。
trigger_id	string 任意	会話をフィルタリングするためのチャットトリガー（`ginct-…`）またはカスタムクライアント（`gincl-…`）のID。そのクライアントが開始した会話のみが返されます。ワークスペースでGenieあたり複数クライアントが有効になっていない場合は無視されます。
identity_user_id	string 任意	会話をフィルタリングするWorkato IdentityユーザーのID。デフォルトはすべてのユーザーです。
feedback[]	文字列の配列任意	会話をフィルタリングするフィードバック状態。使用できる値は`has_positive`、`has_negative`、`has_comments`、または`no_feedback`です。 `has_positive`、`has_negative`、および`has_comments`は`OR`と一緒に渡すことができます。 `no_feedback`は排他的であり、他の`feedback[]`値と組み合わせることはできません。他の値と組み合わせたリクエストは`400 Invalid request`を返します。ワークスペースでフィードバックフィルタリング機能フラグを有効にする必要があります。

サンプルリクエスト

shell

curl -X GET "https://YOUR_DATA_CENTER/api/agentic/genies/gin-AaDdXzLX-dAFvWn-B6/conversations" \
     -H 'Authorization: Bearer <api_token>'

肯定的または否定的なフィードバックを受け取った会話でフィルタリングします。

shell

curl -X GET "https://YOUR_DATA_CENTER/api/agentic/genies/gin-AaDdXzLX-dAFvWn-B6/conversations?feedback[]=has_positive&feedback[]=has_negative" \
     -H 'Authorization: Bearer <api_token>'

会話を開始したトリガーまたはクライアントで絞り込む:

shell

curl -X GET "https://YOUR_DATA_CENTER/api/agentic/genies/gin-AaDdXzLX-dAFvWn-B6/conversations?trigger_id=ginct-abc123" \
     -H 'Authorization: Bearer <api_token>'

サンプルレスポンス

ワークスペースでGenieあたり複数クライアントが有効になっている場合、各会話には trigger_id および trigger_name が含まれ、会話を開始したチャットトリガー（ginct-…）またはカスタムクライアント（gincl-…）を識別します。これらのフィールドは、ハンドルを持たないレガシーな会話、およびトリガーが削除されている場合には null としてではなく省略されます。

json

{
    "data": [
        {
            "id": "conversation-01KSR1JDQMT001AWVTPMTRJ3K8",
            "topic": "IT support request classification",
            "created_at": 1779997161292,
            "last_message_at": 1779997161292,
            "started_by": {
                "user_id": "5XwAGRPmbmjAwRgRrt7X2D"
            },
            "started_via": "Recipe",
            "app_type": "genie_task",
            "chat_type": "GENIE",
            "genie_version": 0,
            "test_conversation": false,
            "conversation_origin": "genie_task",
            "trigger_id": "ginct-abc123",
            "trigger_name": "Slack - Acme",
            "genie_id": "6055",
            "genie_handle": "gin-AaDdXzLX-dAFvWn-B6",
            "genie_name": "IT Support genie",
            "workspace_id": 40291,
            "environment_id": 40291,
            "environment_type": "dev"
        }
    ],
    "next_cursor": null
}

会話の取得

指定したGenieの会話を返します。

GET /api/agentic/genies/:genie_id/conversations/:conversation_id

パスパラメーター

名前	タイプ	説明
genie_id	string 必須	会話を取得するGenieのID。
conversation_id	string 必須	取得する会話のID。

サンプルリクエスト

shell

curl -X GET https://YOUR_DATA_CENTER/api/agentic/genies/gin-AaDdXzLX-dAFvWn-B6/conversations/conversation-01KSR1JDQMT001AWVTPMTRJ3K8 \
     -H 'Authorization: Bearer <api_token>'

サンプルレスポンス

Get conversationエンドポイントは、LLM呼び出し、ツール実行、ガードレール評価などの基礎となるイベントペイロードを返しません。イベントレベルの詳細を取得するには、会話イベントを一覧表示を使用します。

ワークスペースでフィードバックフィルタリング機能フラグが有効になっている場合、totalsには、肯定的および否定的なリアクションの数と、それらのリアクションのうちコメント付きの数を含むfeedbackブロックが含まれます。会話がフィードバックを受け取っていない場合、countとcommentsはどちらも0です。

ワークスペースでGenieあたり複数クライアントが有効になっている場合、レスポンスには trigger_id および trigger_name が含まれます。これらのフィールドは、ハンドルを持たないレガシーな会話、およびトリガーが削除されている場合には null としてではなく省略されます。

json

{
    "data": {
        "id": "conversation-01KSR1JDQMT001AWVTPMTRJ3K8",
        "topic": "IT support request classification",
        "created_at": 1779997161292,
        "last_message_at": 1779997176899,
        "started_by": {
            "user_id": "5XwAGRPmbmjAwRgRrt7X2D"
        },
        "started_via": "Recipe",
        "app_type": "genie_task",
        "chat_type": "GENIE",
        "genie_version": 0,
        "totals": {
            "errors": {
                "count": 0
            },
            "skill_calls": {
                "count": 0
            },
            "kb_calls": {
                "count": 1
            },
            "feedback": {
                "positive": {
                    "count": 6,
                    "comments": 2
                },
                "negative": {
                    "count": 2,
                    "comments": 1
                }
            }
        },
        "test_conversation": false,
        "conversation_origin": "genie_task",
        "trigger_id": "ginct-abc123",
        "trigger_name": "Slack - Acme",
        "genie_id": "6055",
        "genie_handle": "gin-AaDdXzLX-dAFvWn-B6",
        "genie_name": "IT Support genie",
        "workspace_id": 40291,
        "environment_id": 40291,
        "environment_type": "dev"
    }
}

会話イベントを一覧表示

1つの会話のすべてのイベントを返します。各イベントタイプの詳細については、Genie会話イベントを参照してください。

GET /api/agentic/genies/:genie_id/conversations/:conversation_id/events

パスパラメーター

名前	タイプ	説明
genie_id	string 必須	会話イベントを取得するGenieのID。
conversation_id	string 必須	会話イベントを取得する会話のID。

クエリパラメーター

名前	タイプ	説明
page[after]	string 任意	現在のページの最後の結果に基づく、次の結果セットの開始位置。
page[size]	integer 任意	ページごとに取得する項目数。デフォルト値は`20`、最大値は`100`です。イベントに大きなLLMペイロードが含まれる場合は、小さい値を使用することをお勧めします。
order	string 任意	最新の結果を先に返す（`desc`）か、最も古い結果を先に返す（`asc`）かを指定します。デフォルトは`asc`です。
include_event_types[]	文字列の配列任意	結果のフィルタリングに使用するイベントタイプを指定します。デフォルトはすべてのイベントタイプです。
genie_run_id	string 任意	結果のフィルタリングに使用する実行のID。デフォルトはすべての実行です。

サンプルリクエスト

shell

curl -X GET "https://YOUR_DATA_CENTER/api/agentic/genies/gin-AaDdXzLX-dAFvWn-B6/conversations/conversation-01KSR1JDQMT001AWVTPMTRJ3K8/events?include_event_types[]=structured_output_formatting_completed" \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json'

サンプルレスポンス

json

{
    "data": [
        {
            "event_id": "191140b7-9735-4b35-acd5-26d91333d391",
            "event_type": "structured_output_formatting_completed",
            "date_time": "2026-05-28T19:39:38.427751Z",
            "workspace_id": 40291,
            "environment_id": 40291,
            "conversation_id": "conversation-01KSR1JDQMT001AWVTPMTRJ3K8",
            "genie_run_id": "1a11ce5f-f04f-44a3-8dd7-818d24fc3ce1",
            "identity_user_id": "5XwAGRPmbmjAwRgRrt7X2D",
            "genie_handle": "gin-AaDdXzLX-dAFvWn-B6",
            "chat_type": "GENIE",
            "request_id": "00-10f680ac3928f4324a8ce8fc602eb58b-d5e7379818cd3c89-01",
            "app_type": "genie_task",
            "data": "{\"message\":\"{\\\"Category\\\": \\\"Hardware / Performance\\\", \\\"Priority\\\": \\\"Medium\\\", \\\"Summary\\\": \\\"The user is experiencing significant performance degradation on their laptop, including a very slow boot time of approximately 5 minutes, possibly caused by several common endpoint issues.\\\"}\",\"error_message\":null}"
        }
    ],
    "next_cursor": null
}

Guardrails

ガードレールを使用すると、コンテンツ安全性ポリシーをGenieにアタッチできます。ガードレールが存在する場合、モデルが応答する前に、各チャットターンがそのポリシーに照らして評価されます。各ガードレールには、最初にアタッチされたときに2つのデフォルトポリシーがあります: prompt_attackとharmful_content。

ベータ機能

Guardrails APIエンドポイントはベータ版です。詳細については、カスタマーマネージャーにお問い合わせください。

ポリシーの無効化または削除

APIを使用してガードレールからポリシーを削除するためのDELETEガードレールエンドポイントはありません。ポリシーの作成または更新エンドポイントでガードレールを再構成する必要があります。次の表で、タイプに基づいてポリシーをオフにする方法を確認してください。

ポリシー種別	ポリシーをオフにする方法
`pii_detection`, `profanity_filter`	`enabled: false`を設定します。ポリシーはアタッチされたままですが、アクションは実行されません。
`harmful_content`	各カテゴリのフィルターを`strength: "NONE"`に設定して無効にします。 `filters`は空でない状態を維持する必要があります（空の配列は`422`を返します）。そのため、完全に無効化されたポリシーでは5つすべてのエントリが`strength: "NONE"`のままになります。 `enabled`を送信すると`422`が返されます。
`prompt_attack`	`strength: "NONE"`を設定します。 `enabled`を送信すると`422`が返されます。
`custom_word_filter`	リストをクリアするには`custom_words: []`を送信します。
`topic_boundary`	`topics`は空でない必要があります。配列を空にするのではなく、トピックを再構成します。

NONEは有効なstrength値であり、GenieビルダーUIでprompt_attackとharmful_contentをオフにするために使用されます。ガードレールがアタッチされると、prompt_attack と harmful_content のデフォルトポリシーが存在します。これらのポリシーはstrength: "NONE"でオフにできますが、ポリシーを削除することはできません。

Genieガードレールの取得

指定したIDに関連付けられているGenieのガードレールとそのポリシーを返します。

GET https://YOUR_DATA_CENTER/api/agentic/genies/:genie_id/guardrails

クエリパラメータ

名前	タイプ	説明
genie_id	string 必須	取得するガードレールが属するGenieのID。 Genieハンドルは`gin-`で始まります。例: `gin-aBC123-xYz789-prod1`。

サンプルリクエスト

shell

curl -sS https://YOUR_DATA_CENTER/api/agentic/genies/:id/guardrails \
  -H 'Authorization: Bearer <api_token>'

サンプルレスポンス

json

{
  "data": {
    "id": "aigrl-aBC123-xYz789-prod1",
    "policies": [
      {
        "id": "aigrlp-aBC123-pQr456-prod1",
        "policy_type": "harmful_content",
        "configuration": {
          "filters": [
            { "type": "HATE",        "strength": "LOW" },
            { "type": "INSULTS",     "strength": "LOW" },
            { "type": "SEXUAL",      "strength": "LOW" },
            { "type": "VIOLENCE",    "strength": "LOW" },
            { "type": "MISCONDUCT",  "strength": "LOW" }
          ]
        }
      },
      {
        "id": "aigrlp-aBC123-sTu789-prod1",
        "policy_type": "prompt_attack",
        "configuration": { "strength": "LOW" }
      }
    ]
  }
}

サンプルレスポンス

json

{ "data": { "id": null, "policies": [] } }

エラーレスポンス

Status	条件
`401 Unauthorized`	APIトークンが欠落しているか無効です。
`404 Not Found`	Genieハンドルが不明である、フォルダスコープ外である、または`genie_guardrails_enabled`フラグがオフです。

ポリシーの作成または更新

指定したIDに関連付けられているGenieで、単一のガードレールポリシーを作成または更新します。指定したpolicy_typeのポリシーが存在しない場合、新しいポリシーが作成されます。それ以外の場合、既存のポリシーの設定が完全に置き換えられます。使用する予定の完全な設定を送信する必要があります。部分更新はサポートされていません。

PUT https://YOUR_DATA_CENTER/api/agentic/genies/:id/guardrails/policies/:policy_type

クエリパラメータ

名前	タイプ	説明
genie_id	string 必須	作成または更新するポリシーが属するGenieのID。
policy_type	string 必須	作成または更新するポリシーのタイプ。使用可能な値: `harmful_content`、`prompt_attack`、`pii_detection`、`topic_boundary`、`profanity_filter`、`custom_word_filter`。

ペイロード

名前	タイプ	説明
configuration	オブジェクト必須	ポリシーの設定。形式は`policy_type`によって異なります。詳細については、ポリシータイプを参照してください。

サンプルリクエスト

shell

curl -X PUT https://YOUR_DATA_CENTER/api/agentic/genies/:id/guardrails/policies/:policy_type \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "configuration": {
             "filters": [
               { "type": ":policy_type","strength": ":strength-level" },
               { "type": ":policy_type","strength": ":strength-level" },
               { "type": ":policy_type","strength": ":strength-level" },
               { "type": ":policy_type","strength": ":strength-level" },
               { "type": ":policy_type","strength": ":strength-level" }
             ]
           }
         }'

サンプルレスポンス

json

{
  "data": {
    "id": "aigrlp-aBC123-pQr456-prod1",
    "policy_type": "harmful_content",
    "configuration": {
      "filters": [
        { "type": "HATE",       "strength": "HIGH" },
        { "type": "INSULTS",    "strength": "HIGH" },
        { "type": "SEXUAL",     "strength": "HIGH" },
        { "type": "VIOLENCE",   "strength": "MEDIUM" },
        { "type": "MISCONDUCT", "strength": "MEDIUM" }
      ]
    }
  }
}

エラーレスポンス

Status	条件
`400 Bad Request`	`policy_type`が6つの有効な値のいずれでもありません。
`401 Unauthorized`	APIトークンが欠落しているか無効です。
`404 Not Found`	Genieが見つからない、Genieにガードレールがアタッチされていない、または機能フラグがオフです。
`422 Unprocessable Entity`	`configuration`の検証に失敗しました。これは、必須フィールドの欠落、不明なキー、無効な列挙値、またはリクエストがクォータを超過している場合に発生する可能性があります。

サンプル422レスポンス

json

{
  "errors": [
    {
      "code": 422,
      "title": "Failed to update policy",
      "detail": "Configuration contains unknown keys: junk"
    }
  ]
}

使用可能なPIIエンティティタイプの一覧表示

pii_detectionポリシーのpii_entities[].typeフィールドで使用できるPIIエンティティタイプ文字列のリストを返します。このリストは現在のEnvironmentに固有のものではありません。

GET https://YOUR_DATA_CENTER/api/agentic/genies/guardrails/policies/pii_entities

サンプルリクエスト

shell

curl -sS https://YOUR_DATA_CENTER/api/agentic/genies/guardrails/policies/pii_entities \
     -H 'Authorization: Bearer <api_token>'

サンプルレスポンス

json

{
  "data": [
    "ADDRESS", "AGE", "AWS_ACCESS_KEY", "AWS_SECRET_KEY",
    "CA_HEALTH_NUMBER", "CA_SOCIAL_INSURANCE_NUMBER",
    "CREDIT_DEBIT_CARD_CVV", "CREDIT_DEBIT_CARD_EXPIRY", "CREDIT_DEBIT_CARD_NUMBER",
    "DRIVER_ID", "EMAIL", "INTERNATIONAL_BANK_ACCOUNT_NUMBER",
    "IP_ADDRESS", "LICENSE_PLATE", "MAC_ADDRESS", "NAME",
    "PASSWORD", "PHONE", "PIN", "SWIFT_CODE",
    "UK_NATIONAL_HEALTH_SERVICE_NUMBER", "UK_NATIONAL_INSURANCE_NUMBER", "UK_UNIQUE_TAXPAYER_REFERENCE_NUMBER",
    "URL", "USERNAME",
    "US_BANK_ACCOUNT_NUMBER", "US_BANK_ROUTING_NUMBER",
    "US_INDIVIDUAL_TAX_IDENTIFICATION_NUMBER", "US_PASSPORT_NUMBER", "US_SOCIAL_SECURITY_NUMBER",
    "VEHICLE_IDENTIFICATION_NUMBER"
  ]
}

ポリシータイプ

各policy_typeは特定のconfiguration形式を受け入れます。不明なトップレベルキーを送信すると422で失敗します。

harmful_content

有害なコンテンツのカテゴリについて、ユーザー入力とモデル出力をフィルタリングします。

フィールド	タイプ	必須	メモ
`filters`	配列	はい	空でないこと。各要素は`{ "type": <category>, "strength": <strength> }`です。
`filters[].type`	string	はい	`HATE`、`INSULTS`、`SEXUAL`、`VIOLENCE`、`MISCONDUCT`、`PROMPT_ATTACK`のいずれか。
`filters[].strength`	string	はい	`NONE`、`LOW`、`MEDIUM`、`HIGH`のいずれか。カテゴリを無効にするには、`NONE`を使用するか、エントリを省略します。

json

{
  "configuration": {
    "filters": [
      { "type": "HATE",       "strength": "HIGH" },
      { "type": "INSULTS",    "strength": "HIGH" },
      { "type": "SEXUAL",     "strength": "HIGH" },
      { "type": "VIOLENCE",   "strength": "MEDIUM" },
      { "type": "MISCONDUCT", "strength": "MEDIUM" }
    ]
  }
}

prompt_attack

ユーザーのプロンプト内で、システム指示の上書き、脱獄、またはその他の方法でGenieを操作しようとする試みを検出します。

フィールド	タイプ	必須	メモ
`strength`	string	はい	`NONE`、`LOW`、`MEDIUM`、`HIGH`のいずれか。ポリシーをオフにするには`NONE`を使用します。

json

{ "configuration": { "strength": "HIGH" } }

pii_detection

チャットコンテンツ内のPIIを検出し、ブロック、匿名化、またはトークン化します。組み込みエンティティタイプ、カスタム正規表現、またはその両方で照合できます。

フィールド	タイプ	必須	メモ
`enabled`	boolean	はい	機能を有効にします。 `false`に設定されている場合、他のフィールドは受け入れられますが無視されます。
`action`	string	はい	`BLOCK`、`ANONYMIZE`、`TOKENIZE`のいずれか。 `enabled`が`false`の場合でも必須です。
`pii_entities`	配列	条件付き	`enabled`が`true`で、`pii_custom_regexes`が空または存在しない場合は必須（空でないこと）。各要素は`{ "type": <entity> }`です。有効な値を確認するには、使用可能なPIIエンティティタイプの一覧表示を使用します。
`pii_custom_regexes`	配列	条件付き	`enabled`が`true`で、`pii_entities`が空または存在しない場合は必須（空でないこと）。最大10エントリ。各エントリは`{ "name": <label>, "pattern": <regex> }`です。
`pii_custom_regexes[].name`	string	はい	監査ログに表示される空でないラベル。
`pii_custom_regexes[].pattern`	string	はい	有効な正規表現。 500文字未満である必要があります。

json

{
  "configuration": {
    "enabled": true,
    "action": "ANONYMIZE",
    "pii_entities": [
      { "type": "EMAIL" },
      { "type": "PHONE" },
      { "type": "CREDIT_DEBIT_CARD_NUMBER" },
      { "type": "US_SOCIAL_SECURITY_NUMBER" }
    ],
    "pii_custom_regexes": []
  }
}

topic_boundary

会話を特定のトピックに制限します。任意の発話例は、境界線上のケースをモデルが分類するのに役立ちます。

フィールド	タイプ	必須	メモ
`topics`	配列	はい	空でないこと。最大30トピック。
`topics[].name`	string	はい	50文字未満である必要があります。空でないこと。
`topics[].description`	string	いいえ	300文字未満である必要があります。
`topics[].examples`	文字列の配列	いいえ	最大5件の例。各例は300文字未満である必要があります。

json

{
  "configuration": {
    "topics": [
      {
        "name": "Investment advice",
        "description": "Refuse to provide personalized financial or investment advice; suggest the user contact a licensed advisor.",
        "examples": [
          "Should I buy NVDA stock?",
          "How should I allocate my 401(k)?",
          "Is now a good time to invest in crypto?"
        ]
      }
    ]
  }
}

profanity_filter

不適切表現フィルタは有効または無効にできます。

フィールド	タイプ	必須	メモ
`enabled`	boolean	はい	有効にするには`true`、無効にするには`false`。

json

{ "configuration": { "enabled": true } }

custom_word_filter

明示的な単語または短いフレーズのリストに含まれるいずれかを含むメッセージをブロックします。

フィールド	タイプ	必須	メモ
`custom_words`	文字列の配列	はい	最大100エントリ。各エントリは50文字未満である必要があります。リストをクリアするには空の配列を送信します。

json

{
  "configuration": {
    "custom_words": ["Project Atlas", "Operation Falcon", "internal-only"]
  }
}

ナレッジベース

ナレッジベースの一覧表示

ナレッジベースのリストを返します。

GET https://YOUR_DATA_CENTER/api/agentic/knowledge_bases

クエリパラメータ

名前	タイプ	説明
folder_id	string 任意	ナレッジベースが存在するフォルダのID。
project_id	string 任意	ナレッジベースが存在するプロジェクトのID。
query	string 任意	検索クエリ。
page	integer 任意	取得するナレッジベースのページ番号。最小値は`1`です。
per_page	integer 任意	1ページで返すナレッジベースの数。最小値は`1`です。最大値は`50`です。
sort_term	string 任意	結果の並べ替えに使用するフィールドまたは用語。例: `name`または`latest_activity`。
genie_ids[]	文字列の配列任意	結果をフィルタリングするためのGenie IDの配列。指定したGenieの少なくとも1つ以上に割り当てられているナレッジベースのみを返します。

サンプルリクエスト

shell

curl -X GET https://YOUR_DATA_CENTER/api/agentic/knowledge_bases \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "per_page": :per_page_value,
           "page": :page_value,
           "sort_term": ":sort_term"
         }'

サンプルレスポンス

各ナレッジベースには、それが割り当てられているGenieのgenies[]配列が含まれます。

json

[
  {
    "id": "kb-WSm8kore-blMxrh",
    "name": "Support FAQs",
    "description": "よくある顧客サポートの質問を含むナレッジベース。",
    "folder_id": "7498",
    "project_id": "4567",
    "genies": [
      {
        "id": "gin-BWLSPX4z-BaT3D9",
        "name": "Customer Support Genie"
      }
    ]
  },
  {
    "id": "kb-BLm8cove-brMxrh",
    "name": "Sales Playbook",
    "description": "営業チーム向けのガイドラインおよびリソース。",
    "folder_id": "7302",
    "project_id": "9876",
    "genies": []
  }
]

ナレッジベースを作成する

新しいナレッジベースを作成します。

POST https://YOUR_DATA_CENTER/api/agentic/knowledge_bases

ペイロード

名前	タイプ	説明
name	string 必須	ナレッジベースの名前。
説明	string 必須	ナレッジベースの説明。
folder_id	string 必須	ナレッジベースが存在するフォルダのID。
source_type	string 必須	レシピなど、ナレッジベースのソース。
data_sources	string 必須	ナレッジベースのデータソースを設定します。

サンプルリクエスト

shell

curl -X POST https://YOUR_DATA_CENTER/api/agentic/knowledge_bases \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "name": ":name",
           "description": ":description",
           "folder_id": ":folder_id",
           "source_type": ":source_type",
           "data_sources": ":data_sources"
         }'

サンプルレスポンス

json

{
  "id": "kb-BRm8coke-rhMxsa",
  "name": "Support FAQs",
  "description": "Knowledge base with frequently asked customer support questions.",
  "folder_id": "7498",
  "source_type": "recipe",
  "data_sources": "zendesk_articles"

IDでナレッジベースを取得

指定したIDに関連付けられているナレッジベースを返します。

GET https://YOUR_DATA_CENTER/api/agentic/knowledge_bases/:id

クエリパラメータ

名前	タイプ	説明
id	string 必須	取得するナレッジベースのID。

サンプルリクエスト

shell

curl -X GET https://YOUR_DATA_CENTER/api/agentic/knowledge_bases/:id \
     -H 'Authorization: Bearer <api_token>' \

サンプルレスポンス

json

[
  {
    "id": "kb-WSm8kore-blMxrh",
    "name": "Support FAQs",
    "description": "Knowledge base with frequently asked customer support questions.",
    "folder_id": "7498",
    "project_id": "4567"
  }
]

ナレッジベースを更新

既存のナレッジベースを更新します。

PUT https://YOUR_DATA_CENTER/api/agentic/knowledge_bases/:id

クエリパラメータ

名前	タイプ	説明
id	string 必須	更新するナレッジベースのID。
name	string 任意	ナレッジベースの名前。
説明	string 任意	ナレッジベースの説明。
folder_id	string 任意	ナレッジベースが存在するフォルダのID。
data_sources	object 任意	ナレッジベースに設定されているデータソース。

サンプルリクエスト

shell

curl -X PUT https://YOUR_DATA_CENTER/api/agentic/knowledge_bases/:id \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "name": ":name",
           "description": ":description",
           "data_sources": {
             ":data-source-name": :true_or_false,
             ":data-source-name": :true_or_false
           }
         }'

サンプルレスポンス

json

{
  "id": "kb-WSm8kore-blMxrh",
  "name": "Support FAQs v2",
  "description": "Updated to include billing FAQs in addition to support.",
  "folder_id": "7498",
  "source_type": "recipe",
  "data_sources": {
    "zendesk_articles": true,
    "internal_docs": true
  }
}

ナレッジベースを削除

ナレッジベースを削除します。

DELETE https://YOUR_DATA_CENTER/api/agentic/knowledge_bases/:id

クエリパラメータ

名前	タイプ	説明
id	string 必須	削除するナレッジベースのID。

サンプルリクエスト

shell

curl -X DELETE https://YOUR_DATA_CENTER/api/agentic/knowledge_bases/:id \
     -H 'Authorization: Bearer <api_token>' \

サンプルレスポンス

json

{
    "success": "true"
}

ナレッジベースのデータソースを取得

指定したナレッジベースIDに関連付けられているデータソースを返します。

GET https://YOUR_DATA_CENTER/api/agentic/knowledge_bases/:id/data_sources

クエリパラメータ

名前	タイプ	説明
id	string 必須	データソースを取得するナレッジベースのID。

サンプルリクエスト

shell

curl -X GET https://YOUR_DATA_CENTER/api/agentic/knowledge_bases/:id/data_sources \
     -H 'Authorization: Bearer <api_token>'

サンプルレスポンス

json

{
  "knowledge_base_id": "kb-WSm8kore-blMxrh",
  "data_sources": {
    "zendesk_articles": true,
    "internal_docs": true,
    "slack_channels": false
  }
}

ナレッジベースのレシピを取得

指定したナレッジベースIDに関連付けられているレシピを返します。

GET https://YOUR_DATA_CENTER/api/agentic/knowledge_bases/:id/recipes

クエリパラメータ

名前	タイプ	説明
id	string 必須	関連付けられているレシピを取得するナレッジベースのID。
query	string 任意	検索クエリ。
page	integer 任意	取得するGenieのページ番号。最小値は`1`です。
per_page	integer 任意	1ページで返すGenieの数。最小値は`1`です。最大値は`50`です。
sort_term	string 任意	結果の並べ替えに使用するフィールドまたは用語。例: `name`または`latest_activity`。

サンプルリクエスト

shell

curl -X GET https://YOUR_DATA_CENTER/api/agentic/knowledge_bases/:id/recipes \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "per_page": :per_page_value,
           "page": :page_value,
           "sort_term": ":sort_term"
         }'

サンプルレスポンス

json

[
  {
    "id": 45246391,
    "name": "Customer Support Escalation",
    "description": "Routes high-priority Zendesk tickets to Slack.",
    "knowledge_base_id": "kb-WSm8kore-blMxr/recipes"
  },
  {
    "id": 87654321,
    "name": "Billing Notifications",
    "description": "Sends alerts for overdue invoices to the finance team.",
    "knowledge_base_id": "kb-WSm8kore-blMxr/recipes"
  }
]

スキル

以下のエンドポイントを使用して、プログラムでスキルを操作します:

スキルの一覧表示

スキルのリストを返します。

GET https://YOUR_DATA_CENTER/api/agentic/skills

クエリパラメータ

名前	タイプ	説明
folder_id	string 任意	Genieが存在するフォルダのID。
project_id	string 任意	Genieが存在するプロジェクトのID。
query	string 任意	検索クエリ。
page	integer 任意	取得するGenieのページ番号。最小値は`1`です。
per_page	integer 任意	1ページで返すGenieの数。最小値は`1`です。最大値は`50`です。
sort_term	string 任意	結果の並べ替えに使用するフィールドまたは用語。例: `name`または`latest_activity`。
genie_ids[]	文字列の配列任意	結果をフィルタリングするためのGenie IDの配列。指定したGenieの少なくとも1つ以上に割り当てられているスキルとMCPサーバーのみを返します。

サンプルリクエスト

shell

curl -X GET https://YOUR_DATA_CENTER/api/agentic/skills \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "per_page": :per_page_value,
           "page": :page_value,
           "sort_term": ":sort_term"
         }'

サンプルレスポンス

レスポンスには、レシピベースのスキルとMCPサーバーの両方が含まれます。 typeを使用して、レシピベースのスキルとMCPサーバーを区別します。各エントリには、それが割り当てられているGenieのgenies[]配列が含まれます。

json

[
  {
    "id": 65001201,
    "name": "Zendesk Ticket Management",
    "description": "Zendeskからの顧客サポートチケットを処理するスキル。",
    "type": "recipe",
    "folder_id": "7498",
    "project_id": "4567",
    "genies": [
      {
        "id": "gin-BWLSPX4z-BaT3D9",
        "name": "Customer Support Genie"
      }
    ]
  },
  {
    "id": 65039789,
    "name": "Slack Notifications",
    "description": "ターゲットを絞ったSlackアラートを送信するスキル。",
    "type": "recipe",
    "folder_id": "7302",
    "project_id": "4567",
    "genies": []
  },
  {
    "id": "<mcp_server_id>",
    "name": "Salesforce MCP server",
    "description": "Salesforceツールを公開するMCPサーバー。",
    "type": "<mcp_server_type_value>",
    "folder_id": "7302",
    "project_id": "4567",
    "genies": []
  }
]

既存のレシピからスキルを作成

既存のレシピをスキルに変換します。レシピでは、定義済みの入力とアクションを含むStart workflowトリガーを使用する必要があります。このエンドポイントをrecipe_idで呼び出して、レシピをAgent Studioのスキルとして登録します。

POST https://YOUR_DATA_CENTER/api/agentic/skills

ペイロード

名前	タイプ	説明
recipe_id	integer 必須	スキルに変換するレシピのID。

サンプルリクエスト

shell

curl -X POST https://YOUR_DATA_CENTER/api/agentic/skills \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "recipe_id": :recipe_id
         }'

サンプルレスポンス

json

{
  "name": "Customer Escalation Skill",
  "description": "Skill automatically routes high-priority Zendesk tickets to Slack.",
  "recipe_id": 65039789,
  "folder_id": "7498",
  "project_id": "4567"
}

IDでスキルを取得

指定したIDに関連付けられているスキルを返します。

GET https://YOUR_DATA_CENTER/api/agentic/skills/:id

クエリパラメータ

名前	タイプ	説明
id	string 必須	取得するスキルのID。

サンプルリクエスト

shell

curl -X GET https://YOUR_DATA_CENTER/api/agentic/skills/:id \
     -H 'Authorization: Bearer <api_token>' \

サンプルレスポンス

json

{
  "name": "Customer Escalation Skill",
  "description": "Skill automatically routes high-priority Zendesk tickets to Slack.",
  "recipe_id": 65039789,
  "folder_id": "7498",
  "project_id": "4567"
}

最終更新日:

Developer API - Agent Studio ​

レート制限 ​

クイックリファレンス ​

Genie ​

Genieの一覧表示 ​

クエリパラメーター ​

サンプルリクエスト ​

サンプルレスポンス ​

Genieを作成する ​

ペイロード ​

サンプルリクエスト ​

サンプルレスポンス ​

Genieを更新 ​

クエリパラメータ ​

サンプルリクエスト ​

サンプルレスポンス ​

IDでGenieを取得 ​

クエリパラメータ ​

サンプルリクエスト ​

サンプルレスポンス ​

Genieを削除 ​

クエリパラメータ ​

サンプルリクエスト ​

サンプルレスポンス ​

Genieを開始 ​

クエリパラメータ ​

サンプルリクエスト ​

サンプルレスポンス ​

Genieを停止 ​

クエリパラメータ ​

サンプルリクエスト ​

サンプルレスポンス ​

Genieにスキルを割り当て ​

クエリパラメータ ​

ペイロード ​

サンプルリクエスト ​

サンプルレスポンス ​

MCPサーバー割り当てサンプルリクエスト ​

Genieからスキルを削除 ​

クエリパラメータ ​

ペイロード ​

サンプルリクエスト ​

サンプルレスポンス ​

Genieにナレッジベースを割り当て ​

クエリパラメータ ​

ペイロード ​

サンプルリクエスト ​

サンプルレスポンス ​

Genieからナレッジベースを削除 ​

クエリパラメータ ​

ペイロード ​

サンプルリクエスト ​

サンプルレスポンス ​

Genieにユーザーグループを割り当て ​

クエリパラメータ ​

ペイロード ​

サンプルリクエスト ​

サンプルレスポンス ​

Genieからユーザーグループを削除 ​

クエリパラメータ ​

ペイロード ​

サンプルリクエスト ​

サンプルレスポンス ​

Genieトリガー ​

トリガーフィールド ​

トリガーレスポンスのサンプル ​

更新時の置換セマンティクス ​

検証 ​

レガシーフィールドとの互換性 ​

Genieクライアント ​

Genieクライアントのリスト ​

クエリパラメータ ​

サンプルリクエスト ​

サンプルレスポンス ​

クライアントレスポンスフィールド ​

Genieクライアントの作成 ​

ペイロード ​

サンプルリクエスト ​

サンプルレスポンス ​

Genieクライアントを取得 ​

Developer API - Agent Studio

レート制限

クイックリファレンス

Genie

Genieの一覧表示

クエリパラメーター

サンプルリクエスト

サンプルレスポンス

Genieを作成する

ペイロード

サンプルリクエスト

サンプルレスポンス

Genieを更新

クエリパラメータ

サンプルリクエスト

サンプルレスポンス

IDでGenieを取得

クエリパラメータ

サンプルリクエスト

サンプルレスポンス

Genieを削除

クエリパラメータ

サンプルリクエスト

サンプルレスポンス

Genieを開始

クエリパラメータ

サンプルリクエスト

サンプルレスポンス

Genieを停止

クエリパラメータ

サンプルリクエスト

サンプルレスポンス

Genieにスキルを割り当て

クエリパラメータ

ペイロード

サンプルリクエスト

サンプルレスポンス

MCPサーバー割り当てサンプルリクエスト

Genieからスキルを削除

クエリパラメータ

ペイロード

サンプルリクエスト

サンプルレスポンス

Genieにナレッジベースを割り当て

クエリパラメータ

ペイロード

サンプルリクエスト

サンプルレスポンス

Genieからナレッジベースを削除

クエリパラメータ

ペイロード

サンプルリクエスト

サンプルレスポンス

Genieにユーザーグループを割り当て

クエリパラメータ

ペイロード

サンプルリクエスト

サンプルレスポンス

Genieからユーザーグループを削除

クエリパラメータ

ペイロード

サンプルリクエスト

サンプルレスポンス

Genieトリガー

トリガーフィールド

トリガーレスポンスのサンプル

更新時の置換セマンティクス

検証

レガシーフィールドとの互換性

Genieクライアント

Genieクライアントのリスト

クエリパラメータ

サンプルリクエスト

サンプルレスポンス

クライアントレスポンスフィールド

Genieクライアントの作成

ペイロード

サンプルリクエスト

サンプルレスポンス

Genieクライアントを取得