Developer API - Agent Studio ​

このページは機械翻訳により提供されています。翻訳内容と英語版に相違がある場合は、英語版が優先されます。

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

レート制限 ​

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

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

クイックリファレンス ​

タイプリソース説明
GET/api/agentic/geniesGenieのリストを返します。
POST/api/agentic/genies新しいGenieを作成します。
PUT/api/agentic/genies/:id既存のGenieを更新します。
GET/api/agentic/genies/:id指定したIDに関連付けられているGenieを返します。
DELETE/api/agentic/genies/:idGenieを削除します。
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/clientsGenieクライアントのリストを返します。
POST/api/agentic/genies/clients新しいGenieクライアント(APIキーまたはOAuth)を作成します。
GET/api/agentic/genies/clients/:client_id指定したIDに関連付けられているGenieクライアントを返します。
PUT/api/agentic/genies/clients/:client_idGenieクライアントの名前とOAuthリダイレクトURLを更新します。
DELETE/api/agentic/genies/clients/:client_idGenieクライアントを削除します。
POST/api/agentic/genies/clients/:client_id/regenerateGenieクライアントのAPIキーを再生成します。
POST/api/agentic/genies/clients/:client_id/pauseGenieクライアントを一時停止します。
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/interfacesGenieのすべてのチャットインターフェーストリガーを単一のリストで返します。
GET/api/agentic/genies/:genie_id/conversationsGenieの会話のリストを返します。イベントレベルの詳細は含まれません。
GET/api/agentic/genies/:genie_id/conversations/:conversation_id指定したGenieの会話を返します。イベントレベルの詳細は含まれません。
GET/api/agentic/genies/:genie_id/conversations/:conversation_id/events1つの会話のすべてのイベントを返します。
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_entitiespii_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_idstring
任意
Genieが存在するフォルダのID。
project_idstring
任意
Genieが存在するプロジェクトのID。
statestring
任意
Genieの状態。例: activeまたはinactive。
pageinteger
任意
取得するGenieのページ番号。最小値は1です。
per_pageinteger
任意
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

ペイロード ​

名前タイプ説明
namestring
required
Genieの名前。
説明string
required
Genieの目的の説明。
folder_idstring
required
Genieが存在するフォルダのID。
instructionsstring
required
Genieが目的、パーソナリティ、ジョブの説明を識別するために使用する指示。
ai_modelstring
任意
Genieが使用するモデル。例えば: gpt-4o. ai_providerと併用します。カスタムプロバイダの場合はnullを返します。
ai_providerstring
任意
Genieを動作させる内部プロバイダエンジン。許可されている値はopen_ai、anthropic、byollmです。 ai_modelと併用します。
ai_provider_typestring
任意
Genieを動作させるAIプロバイダの種類。 ai_provider_idと併用します。
ai_provider_idstring
任意
Genieを動作させるAIプロバイダのID。 ai_provider_typeと併用します。
shared_account_idinteger
必須
GenieのコネクションID。 triggers[] を推奨とし、これは非推奨です。 triggers[] を送信した場合は無視されます。
custom_oauth_key_idinteger
必須
カスタムOAuthキーID。 triggers[] を推奨とし、これは非推奨です。 triggers[] を送信した場合は無視されます。
matrixboolean
必須
Workato GOをチャットインターフェイスとして有効にするかどうかを決定します。使用できる値はtrueまたはfalseです。
channel_modestring
任意
Genieが応答する場所を制御します。使用可能な値はdms_onlyまたはeverywhereです。デフォルトはdms_onlyです。 triggers[] を推奨とし、これは非推奨です。 triggers[] を送信した場合は無視されます。
channel_scopestring
任意
Genieが応答するチャネルを決定します。使用可能な値はspecificまたはall_invitedです。デフォルトはspecificです。 triggers[] を推奨とし、これは非推奨です。 triggers[] を送信した場合は無視されます。
response_modestring
任意
Genieがチャネルでトリガーされる方法を制御します。使用可能な値はon_mentionまたはhelpdeskです。デフォルトはon_mentionです。 triggers[] を推奨とし、これは非推奨です。 triggers[] を送信した場合は無視されます。
channel_whiteliststring[]
任意
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"]
         }'

Create a genie with triggers[]:

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

クエリパラメータ ​

名前タイプ説明
idstring
required
更新するGenieのID。
namestring
任意
Genieの名前。
説明string
任意
Genieの目的の説明。
folder_idstring
任意
Genieが存在するフォルダのID。
instructionsstring
任意
Genieが目的、パーソナリティ、ジョブの説明を識別するために使用する指示。
ai_providerstring
任意
Genieを動作させる内部プロバイダエンジン。許可されている値はopen_ai、anthropic、byollmです。 ai_modelと併用します。
ai_modelstring
任意
Genieが使用するモデル。例えば: gpt-4o. ai_providerと併用します。カスタムプロバイダの場合はnullを返します。
ai_provider_typestring
任意
Genieを動作させるAIプロバイダの種類。 ai_provider_idと併用します。
ai_provider_idstring
任意
Genieを動作させるAIプロバイダのID。 ai_provider_typeと併用します。
shared_account_idinteger
任意
GenieのコネクションID。 triggers[] を推奨とし、これは非推奨です。 triggers[] を送信した場合は無視されます。
custom_oauth_key_idinteger
任意
カスタムOAuthキーID。 triggers[] を推奨とし、これは非推奨です。 triggers[] を送信した場合は無視されます。
matrixboolean
任意
Workato GOをチャットインターフェイスとして有効にするかどうかを決定します。使用できる値はtrueまたはfalseです。
channel_modestring
任意
Genieが応答する場所を制御します。使用可能な値はdms_onlyまたはeverywhereです。 triggers[] を推奨とし、これは非推奨です。 triggers[] を送信した場合は無視されます。
channel_scopestring
任意
Genieが応答するチャネルを決定します。使用可能な値はspecificまたはall_invitedです。 triggers[] を推奨とし、これは非推奨です。 triggers[] を送信した場合は無視されます。
response_modestring
任意
Genieがチャネルでトリガーされる方法を制御します。使用可能な値はon_mentionまたはhelpdeskです。 triggers[] を推奨とし、これは非推奨です。 triggers[] を送信した場合は無視されます。
channel_whiteliststring[]
任意
Genieによる応答が許可されているSlackチャネルIDの配列です。 channel_scopeがspecificの場合にのみ適用されます。空の配列を渡すと、リストがクリアされます。 triggers[] を推奨とし、これは非推奨です。 triggers[] を送信した場合は無視されます。
トリガーオブジェクトの配列
任意
The complete list of chat triggers for the genie. This replaces all existing triggers atomically. Refer to Genie triggers for the replacement semantics, validation rules, and legacy field behavior.

サンプルリクエスト ​
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"]
         }'

Update a genie's triggers. This example updates an existing trigger and creates a new one. Any existing trigger missing from the array is removed:

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": "Updated to handle billing inquiries in addition to general support.",
  "folder_id": "7498",
  "project_id": "4567",
  "instructions": "You are a knowledgeable, polite support assistant. Always prioritize clear, concise answers.",
  "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を返します。 The genie includes a triggers[] array and the LLM configuration, ai_provider_type and ai_provider_id. 詳細についてはGenieトリガーを参照してください。

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

クエリパラメータ ​

名前タイプ説明
idstring
required
取得するGenieのID。
サンプルリクエスト ​
shell
curl -X GET https://YOUR_DATA_CENTER/api/agentic/genies/:id \
     -H 'Authorization: Bearer <api_token>'
サンプルレスポンス ​

Channel configuration fields are returned with the default values when no explicit configuration is set.

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

json
{
  "data": {
    "id": "gin-ZWSMPR4a-TaG7S9",
    "name": "カスタマーサポートGenie v2",
    "description": "一般的なサポートに加えて請求に関する問い合わせにも対応するよう更新されています。",
    "state": "inactive",
    "folder_id": 21285720,
    "project_id": 93761783,
    "instructions": "あなたは知識が豊富で丁寧なサポートアシスタントです。常に明確で簡潔な回答を最優先してください。",
    "ai_provider": "anthropic",
    "chat_interface": "slack",
    "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": "カスタマーアシスタント"
      }
    ],
    "logo_url": "https://example.com/logo.png",
    "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": []
      }
    ],
    "user_groups": [],
    "created_at": "2026-02-24T08:54:34.170-08:00",
    "updated_at": "2026-02-25T09:34:14.300-08:00",
    "ai_model": "claude-sonnet-4-6",
    "ai_provider_type": "default",
    "ai_provider_id": "claude-sonnet-4-6",
    "ai_model_label": "Claude Sonnet 4.6",
    "guardrails": {
      "id": "aigrl-Abw694Q4-YsapGf-B6",
      "policies": [
        {
          "id": "aigrlp-Abw696Cf-GtErhP-B6",
          "policy_type": "harmful_content",
          "configuration": {
            "filters": [
              { "type": "HATE", "strength": "NONE" },
              { "type": "INSULTS", "strength": "NONE" },
              { "type": "SEXUAL", "strength": "NONE" },
              { "type": "VIOLENCE", "strength": "NONE" },
              { "type": "MISCONDUCT", "strength": "NONE" }
            ]
          }
        },
        {
          "id": "aigrlp-Abw696Ca-CKs8Cr-B6",
          "policy_type": "prompt_attack",
          "configuration": {
            "strength": "NONE"
          }
        }
      ]
    }
  }
}

Genieを削除 ​

Genieを削除します。

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

クエリパラメータ ​

名前タイプ説明
idstring
required
削除する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

クエリパラメータ ​

名前タイプ説明
idstring
required
開始する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

クエリパラメータ ​

名前タイプ説明
idstring
required
停止する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

クエリパラメータ ​

名前タイプ説明
idstring
required
スキルを割り当てるGenieのID。

ペイロード ​

名前タイプ説明
skill_idsarray of string
optional
Genieに割り当てるスキルIDの配列。
mcp_server_idsarray of string
optional
An array of MCP server IDs to assign to a genie.

You must send at least one of skill_ids or mcp_server_ids.

サンプルリクエスト ​

Assign a skill:

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"
    }
  ],
}
Assign an MCP server sample request ​

Assign an MCP server:

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

クエリパラメータ ​

名前タイプ説明
idstring
required
スキルを削除するGenieのID。

ペイロード ​

名前タイプ説明
skill_idsstringの配列
必須
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

クエリパラメータ ​

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

ペイロード ​

名前タイプ説明
knowledge_base_idsstringの配列
必須
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

クエリパラメータ ​

名前タイプ説明
idstring
required
ナレッジベースを削除するGenieのID。

ペイロード ​

名前タイプ説明
knowledge_base_idsstringの配列
必須
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

クエリパラメータ ​

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

ペイロード ​

名前タイプ説明
user_group_idsstringの配列
必須
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

クエリパラメータ ​

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

ペイロード ​

名前タイプ説明
user_group_idsstringの配列
必須
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 triggers ​

A trigger is a chat interface a genie responds through, such as Slack, Microsoft Teams, or Workato GO. The triggers[] array is available on List genies, Get a genie by ID, Create a genie, and Update a genie. Custom clients are a separate resource and aren't part of triggers[]. Refer to Genie clients for more information.

Add the following privilege to your API client to use this endpoint:

権限Required for
genie_interfaces.indexList genie chat interface triggers

Trigger fields ​

名前タイプ説明
idstringThe trigger handle, for example ginct-abc123. The server generates this value. Omit it on create and include it on update to modify an existing trigger.
platformstringThe chat platform. Accepted values are slack, ms_teams, or matrix. matrix is Workato GO.
namestring
任意
A name for the trigger.
statusstring
任意
The desired state of the trigger. Accepted values in requests are active or inactive. Use inactive to pause a trigger and active to start it. New triggers start as active. Responses return active, inactive, or warning. Any other value in a request returns 422.
shared_account_idinteger
任意
The Connection ID of the trigger. Returned as null for matrix triggers.
custom_oauth_key_idinteger
任意
カスタムOAuthキーID。 Returned as null for matrix triggers.
channel_modestring
任意
Genieが応答する場所を制御します。使用可能な値はdms_onlyまたはeverywhereです。
channel_scopestring
任意
Genieが応答するチャネルを決定します。使用可能な値はspecificまたはall_invitedです。
response_modestring
任意
Genieがチャネルでトリガーされる方法を制御します。使用可能な値はon_mentionまたはhelpdeskです。
channel_whiteliststring[]
任意
Genieによる応答が許可されているSlackチャネルIDの配列です。 channel_scopeがspecificの場合にのみ適用されます。

Sample trigger response ​

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

Replacement semantics on update ​

triggers[] on Update a genie is an atomic full replacement:

  • An entry without an id creates a new trigger.
  • An entry with an id updates the existing trigger.
  • An existing trigger missing from the array is removed.
  • "triggers": [] removes all triggers.
  • An unknown id returns 422 and nothing is applied.

You can swap connections between two triggers in a single request.

Validation ​

Validation is atomic. No entries are applied if an entry fails. Errors include the entry index in the format triggers[2].field: message.

ケースエラー
channel_scope is specific without a non-empty channel_whitelist422 on triggers[i].channel_whitelist
Non-empty channel_whitelist with channel_mode set to dms_only or channel_scope set to all_invited422 on triggers[i].channel_whitelist
Two entries with the same shared_account_id in one request422 connection exclusivity
Connection already used by another trigger or genie422 connection exclusivity
More than 50 entries422 cap
Unknown id on update422 unknown trigger id
status isn't active or inactive422 on triggers[i].status
More than one matrix entry for a genie. A genie supports one Workato GO trigger.422
triggers isn't an array400

The connection fields, shared_account_id and custom_oauth_key_id, and channel fields, channel_mode, channel_scope, response_mode and channel_whitelist, are ignored for matrix triggers. A matrix trigger retains default values.

Legacy field compatibility ​

The top-level connection_id, custom_oauth_key_id, channel_mode, channel_scope, response_mode, and channel_whitelist fields remain available but are deprecated. Responses from List genies and Get a genie by ID include a Deprecation: true header.

  • Responses: Legacy fields mirror the oldest active trigger, triggers[0].
  • Requests: Legacy flat fields, such as connection_id or shared_account_id, custom_oauth_key_id, and channel_*, apply only when you don't send triggers[]. These fields apply to the oldest active trigger, triggers[0]. Other triggers are untouched.
  • The flat fields are ignored and only triggers[] applies when you send both.

Genieクライアント ​

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

MULTIPLE CLIENTS PER GENIE, ONE GENIE PER CLIENT

A genie supports multiple attached clients. A client belongs to only one genie at a time. Attaching a client that's already attached to another genie returns a 409 conflict with the message Client is already assigned to another genie. クライアントの向き先を変更するには、まず既存のペアリングをデタッチします。

A genie supports a single client if multiple clients per genie isn't enabled for your workspace. Attempting to attach a second client returns a 409 conflict.

A genie can have a custom client and a Slack or Microsoft Teams interface at the same time.

AVAILABILITY AND PRIVILEGES

The following require multiple clients per genie to be enabled for your workspace. Contact your customer manager to enable it.

  • triggers[] in genie requests and responses
  • status, type, base_host, activated_at, and genie_ids in genie client responses
  • The get, pause, and start genie client endpoints
  • The list genie interfaces endpoint
  • trigger_id and trigger_name in conversation responses, and the trigger_id conversation filter
  • List genie interfaces

These endpoints return a 403 error if multiple clients per genie isn't enabled.

Add the following privileges to your API client to use the endpoints:

権限Required for
genie_clients.showGet a genie client
genie_clients.startStart a genie client
genie_clients.pausePause a genie client

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

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

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

Query parameters ​

名前タイプ説明
genie_idstring
任意
The handle of a genie to filter results by. Returns only the clients assigned to that genie. For example, gin-abc.
サンプルリクエスト ​
shell
curl -X GET https://YOUR_DATA_CENTER/api/agentic/genies/clients \
     -H 'Authorization: Bearer <api_token>'

Filter by genie:

shell
curl -X GET "https://YOUR_DATA_CENTER/api/agentic/genies/clients?genie_id=:genie_handle" \
     -H 'Authorization: Bearer <api_token>'
サンプルレスポンス ​

Each client also returns status, type, base_host, activated_at, ip_allow_list, and genie_ids when multiple clients per genie is enabled for your workspace. Refer to 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 response fields ​

名前タイプ説明
client_idstringThe ID of the client.
client_namestringThe name of the client.
statusstringThe state of the client. Returns active, inactive, or warning.
typestringThe authentication type of the client. Returns api_key or oauth.
base_hoststringThe host the client uses to call the genie.
activated_atstringThe time the client was first activated. Returns null if it hasn't been activated.
ip_allow_listarrayThe IP addresses allowed to use the client.
genie_idsarray of stringThe handles of the genies the client is assigned to.

Genieクライアントの作成 ​

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

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

ペイロード ​

名前タイプ説明
client_namestring
required
クライアントの名前。
authオブジェクト
必須
認証設定。
auth.typestring
required
認証タイプ。使用できる値はapi_keyおよびoauthです。
auth.oauth_redirect_urlstring or array of string
optional
The redirect URL or URLs registered for the OAuth flow. Pass an array to register multiple redirect URLs. 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" } }'

Create an OAuth client with multiple redirect URLs:

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クライアントはシークレットを返しません。

When multiple clients per genie is enabled for your workspace, the response also includes status, type, base_host, activated_at, ip_allow_list, and 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": []
  }
}

Get a genie client ​

指定したIDに関連付けられているGenieクライアントを返します。 OAuth clients also return oauth_client_id and oauth_redirect_url. Requires the genie_clients.show privilege.

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

Path parameters ​

名前タイプ説明
client_idstring
required
The ID of the client you plan to retrieve.
Sample request ​
shell
curl -X GET https://YOUR_DATA_CENTER/api/agentic/genies/clients/:client_id \
     -H 'Authorization: Bearer <api_token>'
Sample response ​
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 clients also return the following fields:

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

Error responses ​

Status条件
403 ForbiddenMultiple clients per genie isn't enabled for your workspace, or your API client lacks the genie_clients.show privilege.
404 Not FoundThe client doesn't exist or was deleted.

Genieクライアントの更新 ​

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

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

ペイロード ​

名前タイプ説明
client_namestring
required
クライアントの新しい名前。
auth.oauth_redirect_urlstring or array of string
optional
The redirect URL or URLs for an OAuth client. Replaces the existing redirect URLs. Pass an array to register multiple redirect URLs. An empty array for an OAuth client returns 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" }'

Update the redirect URLs of an OAuth client:

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

Pause a genie client ​

Genieクライアントを一時停止します。 The client's status changes to inactive. Pausing a client that's already paused has no effect and returns 200. Requires the genie_clients.pause privilege.

POST https://YOUR_DATA_CENTER/api/agentic/genies/clients/:client_id/pause
Sample request ​
shell
curl -X POST https://YOUR_DATA_CENTER/api/agentic/genies/clients/:client_id/pause \
     -H 'Authorization: Bearer <api_token>'
Sample response ​
json
{
  "data": {
    "status": "inactive"
  }
}

Error responses ​

Status条件
403 ForbiddenMultiple clients per genie isn't enabled for your workspace, or your API client lacks the genie_clients.pause privilege.
404 Not FoundThe client doesn't exist or was deleted.

Start a genie client ​

一時停止中のGenieクライアントを開始します。 The client's status changes to active. Starting a client that's already active has no effect and returns 200. Requires the genie_clients.start privilege.

POST https://YOUR_DATA_CENTER/api/agentic/genies/clients/:client_id/start
Sample request ​
shell
curl -X POST https://YOUR_DATA_CENTER/api/agentic/genies/clients/:client_id/start \
     -H 'Authorization: Bearer <api_token>'
Sample response ​
json
{
  "data": {
    "status": "active"
  }
}

Error responses ​

Status条件
403 ForbiddenMultiple clients per genie isn't enabled for your workspace, or your API client lacks the genie_clients.start privilege.
404 Not FoundThe client doesn't exist or was deleted.

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

指定したGenieにクライアントをアタッチします。 A genie can have multiple clients. クライアントは一度に1つのGenieにのみアタッチできます。 Attaching a client that's already attached to another genie returns 409 with the message Client is already assigned to another genie. The response includes the client's status.

When multiple clients per genie isn't enabled for your workspace, the genie can't have an existing client.

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

ペイロード ​

名前タイプ説明
genie_client_idstring
required
アタッチするクライアントの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>'

Chat interface triggers ​

Ensure that you meet the following requirements to use chat interface triggers programmatically:

  • Multiple clients per genie is enabled for your workspace
  • The genie_interfaces.index privilege

List chat interface triggers ​

Returns a genie's chat interface triggers in a single list. Use the type field to determine the chat interface triggers, including slack, ms_teams, or matrix, api for custom clients, and recipe for recipes. Results are sorted by name. This endpoint is read-only. You must have the genie_interfaces.index privilege to use this endpoint.

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

Path parameters ​

名前タイプ説明
genie_idstring
required
The ID of the genie whose interfaces to retrieve.

Query parameters ​

名前タイプ説明
querystring
任意
A case-insensitive substring to match against the chat interface trigger name. Applies to all interface types.
pageinteger
任意
Page number to fetch. 1から開始します。
per_pageinteger
任意
Number of interfaces to return in a single page. デフォルトは20です。最大値は50です。 Higher values are reduced to 50.
Sample request ​
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>'
Sample response ​

total is the number of matching chat interface triggers after applying query and before paging. Chat interface triggers return connection_id, which is the same value as shared_account_id in the triggers[] array of a genie.

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
}

Error responses ​

A 403 Forbidden error response is returned when multiple clients per genie isn't enabled for your workspace, or your API client lacks the genie_interfaces.index privilege.

Conversations ​

Conversation endpoints expose genie conversation data for use cases that don't require real-time streaming, such as attaching transcripts to support tickets, ad-hoc investigation, or recipe-based automation. Use Audit log streaming for cases that require real-time streaming.

ENVIRONMENT-SCOPED ENDPOINTS

All conversation endpoints return data scoped to the environment of the API client used. The environment_type and environment_id fields in the response identify which environment the data belongs to. Create separate API clients and combine the results to retrieve conversation data across environments.

会話の一覧表示 ​

Returns a list of conversations a genie has had. The most recently active conversations return first.

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

Path parameters ​

名前タイプ説明
genie_idstring
required
The ID of the genie whose conversations to retrieve.

クエリパラメータ ​

名前タイプ説明
page[after]string
任意
The starting point for the next set of results based on the last result of the current page.
page[size]integer
任意
The number of items to retrieve per page. The default value is 50 and maximum value is 100.
fromstring
任意
The lower bound on created_at, in ISO 8601 format (YYYY-MM-DDTHH:mm:ss.SSSZ). Defaults to the start of the retention window.
tostring
任意
The upper bound on created_at, in ISO 8601 format (YYYY-MM-DDTHH:mm:ss.SSSZ). Defaults to the current time.
app_typestring
任意
The trigger source to filter results by. Accepted values are slack, teams, go, headless_api, test_mode, genie_task, or app_event. Defaults to all sources.
trigger_idstring
任意
The ID of a chat trigger (ginct-…) or custom client (gincl-…) to filter conversations by. Returns only conversations that client originated. Ignored when multiple clients per genie isn't enabled for your workspace.
identity_user_idstring
任意
The ID of a Workato Identity user to filter conversations by. Defaults to all users.
feedback[]array of string
optional
The feedback state to filter conversations by. Accepted values are has_positive, has_negative, has_comments, or no_feedback. You can pass has_positive, has_negative, and has_comments together with OR. no_feedback is exclusive and can't be combined with any other feedback[] values. Requests that combine it with other values return 400 Invalid request. Requires the feedback filtering feature flag to be enabled for your workspace.
Sample request ​
shell
curl -X GET "https://YOUR_DATA_CENTER/api/agentic/genies/gin-AaDdXzLX-dAFvWn-B6/conversations" \
     -H 'Authorization: Bearer <api_token>'

Filter by conversations that received positive or negative feedback:

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>'

Filter by the trigger or client that originated the conversation:

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>'
Sample response ​

When multiple clients per genie is enabled for your workspace, each conversation includes trigger_id and trigger_name, which identify the chat trigger (ginct-…) or custom client (gincl-…) that originated the conversation. These fields are omitted, not returned as null, for legacy conversations without a handle and when the trigger was deleted.

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

Path parameters ​

名前タイプ説明
genie_idstring
required
The ID of the genie to retrieve a conversation from.
conversation_idstring
required
The ID of the conversation to retrieve.
Sample request ​
shell
curl -X GET https://YOUR_DATA_CENTER/api/agentic/genies/gin-AaDdXzLX-dAFvWn-B6/conversations/conversation-01KSR1JDQMT001AWVTPMTRJ3K8 \
     -H 'Authorization: Bearer <api_token>'
Sample response ​

The Get conversation endpoint doesn't return the underlying event payload, such as LLM calls, tool executions, and guardrail evaluations. Use List conversation events to retrieve event-level detail.

When the feedback filtering feature flag is enabled for your workspace, totals includes a feedback block with counts of positive and negative reactions and the number of those reactions that carried a comment. Both count and comments are 0 when the conversation has received no feedback.

When multiple clients per genie is enabled for your workspace, the response includes trigger_id and trigger_name. These fields are omitted, not returned as null, for legacy conversations without a handle and when the trigger was deleted.

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

List conversation events ​

1つの会話のすべてのイベントを返します。 Refer to Genie conversation events for information about each event type.

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

Path parameters ​

名前タイプ説明
genie_idstring
required
The ID of the genie to retrieve conversation events from.
conversation_idstring
required
The ID of the conversation to retrieve conversation events from.

Query parameters ​

名前タイプ説明
page[after]string
任意
The starting point for the next set of results based on the last result of the current page.
page[size]integer
任意
The number of items to retrieve per page. The default value is 20 and maximum value is 100. We recommend smaller values when events carry large LLM payloads.
orderstring
任意
Specifies whether to return newest results first (desc) or oldest results first (asc). Defaults to asc.
include_event_types[]array of string
optional
Specifies the event types to filter results by. Defaults to all event types.
genie_run_idstring
任意
The ID of a run to filter results by. Defaults to all runs.
Sample request ​
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'
Sample response ​
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_filterenabled: falseを設定します。ポリシーはアタッチされたままですが、アクションは実行されません。
harmful_content各カテゴリのフィルターをstrength: "NONE"に設定して無効にします。 filtersは空でない状態を維持する必要があります(空の配列は422を返します)。そのため、完全に無効化されたポリシーでは5つすべてのエントリがstrength: "NONE"のままになります。 enabledを送信すると422が返されます。
prompt_attackstrength: "NONE"を設定します。 enabledを送信すると422が返されます。
custom_word_filterリストをクリアするにはcustom_words: []を送信します。
topic_boundarytopicsは空でない必要があります。配列を空にするのではなく、トピックを再構成します。

NONEは有効なstrength値であり、GenieビルダーUIでprompt_attackとharmful_contentをオフにするために使用されます。 The two default policies, prompt_attack and harmful_content, are present after a guardrail is attached. これらのポリシーはstrength: "NONE"でオフにできますが、ポリシーを削除することはできません。

Genieガードレールの取得 ​

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

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

クエリパラメータ ​

名前タイプ説明
genie_idstring
required
取得するガードレールが属する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 UnauthorizedAPIトークンが欠落しているか無効です。
404 Not FoundGenieハンドルが不明である、フォルダスコープ外である、またはgenie_guardrails_enabledフラグがオフです。

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

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

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

クエリパラメータ ​

名前タイプ説明
genie_idstring
required
作成または更新するポリシーが属するGenieのID。
policy_typestring
required
作成または更新するポリシーのタイプ。使用可能な値: 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 Requestpolicy_typeが6つの有効な値のいずれでもありません。
401 UnauthorizedAPIトークンが欠落しているか無効です。
404 Not FoundGenieが見つからない、Genieにガードレールがアタッチされていない、または機能フラグがオフです。
422 Unprocessable Entityconfigurationの検証に失敗しました。 This can be caused by missing a required field, an unknown key, an invalid enum value, or if the request exceeds quotas.
サンプル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[].typestringはいHATE、INSULTS、SEXUAL、VIOLENCE、MISCONDUCT、PROMPT_ATTACKのいずれか。
filters[].strengthstringはい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を操作しようとする試みを検出します。

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

pii_detection ​

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

フィールドタイプ必須メモ
enabledbooleanはい機能を有効にします。 falseに設定されている場合、他のフィールドは受け入れられますが無視されます。
actionstringはい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[].namestringはい監査ログに表示される空でないラベル。
pii_custom_regexes[].patternstringはい有効な正規表現。 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[].namestringはい50文字未満である必要があります。空でないこと。
topics[].descriptionstringいいえ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 ​

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

フィールドタイプ必須メモ
enabledbooleanはい有効にするには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_idstring
任意
ナレッジベースが存在するフォルダのID。
project_idstring
任意
ナレッジベースが存在するプロジェクトのID。
querystring
任意
検索クエリ。
pageinteger
任意
取得するナレッジベースのページ番号。最小値は1です。
per_pageinteger
任意
1ページで返すナレッジベースの数。最小値は1です。最大値は50です。
sort_termstring
任意
結果の並べ替えに使用するフィールドまたは用語。例: nameまたはlatest_activity。
genie_ids[]array of string
optional
An array of genie IDs to filter results by. Returns only knowledge bases assigned to at least one of the genies you specify.
サンプルリクエスト ​
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"
         }'
サンプルレスポンス ​

Each knowledge base includes a genies[] array of the genies it's assigned to.

json
[
  {
    "id": "kb-WSm8kore-blMxrh",
    "name": "Support FAQs",
    "description": "Knowledge base with frequently asked customer support questions.",
    "folder_id": "7498",
    "project_id": "4567",
    "genies": [
      {
        "id": "gin-BWLSPX4z-BaT3D9",
        "name": "Customer Support Genie"
      }
    ]
  },
  {
    "id": "kb-BLm8cove-brMxrh",
    "name": "Sales Playbook",
    "description": "Guidelines and resources for the sales team.",
    "folder_id": "7302",
    "project_id": "9876",
    "genies": []
  }
]

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

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

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

ペイロード ​

名前タイプ説明
namestring
required
ナレッジベースの名前。
説明string
required
ナレッジベースの説明。
folder_idstring
required
ナレッジベースが存在するフォルダのID。
source_typestring
required
レシピなど、ナレッジベースのソース。
data_sourcesstring
required
ナレッジベースのデータソースを設定します。
サンプルリクエスト ​
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

クエリパラメータ ​

名前タイプ説明
idstring
required
取得するナレッジベースの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

クエリパラメータ ​

名前タイプ説明
idstring
required
更新するナレッジベースのID。
namestring
任意
ナレッジベースの名前。
説明string
任意
ナレッジベースの説明。
folder_idstring
任意
ナレッジベースが存在するフォルダのID。
data_sourcesobject
任意
ナレッジベースに設定されているデータソース。
サンプルリクエスト ​
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

クエリパラメータ ​

名前タイプ説明
idstring
required
削除するナレッジベースの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

クエリパラメータ ​

名前タイプ説明
idstring
required
データソースを取得するナレッジベースの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

クエリパラメータ ​

名前タイプ説明
idstring
required
関連付けられているレシピを取得するナレッジベースのID。
querystring
任意
検索クエリ。
pageinteger
任意
取得するGenieのページ番号。最小値は1です。
per_pageinteger
任意
1ページで返すGenieの数。最小値は1です。最大値は50です。
sort_termstring
任意
結果の並べ替えに使用するフィールドまたは用語。例: 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"
  }
]

スキル ​

Use the following endpoints to work with skills programmatically:

スキルの一覧表示 ​

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

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

クエリパラメータ ​

名前タイプ説明
folder_idstring
任意
Genieが存在するフォルダのID。
project_idstring
任意
Genieが存在するプロジェクトのID。
querystring
任意
検索クエリ。
pageinteger
任意
取得するGenieのページ番号。最小値は1です。
per_pageinteger
任意
1ページで返すGenieの数。最小値は1です。最大値は50です。
sort_termstring
任意
結果の並べ替えに使用するフィールドまたは用語。例: nameまたはlatest_activity。
genie_ids[]array of string
optional
An array of genie IDs to filter results by. Returns only skills and MCP servers assigned to at least one of the genies you specify.
サンプルリクエスト ​
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"
         }'
サンプルレスポンス ​

The response includes both recipe-based skills and MCP servers. Use type to tell recipe-based skills and MCP servers apart. Each entry includes a genies[] array of the genies it's assigned to.

json
[
  {
    "id": 65001201,
    "name": "Zendesk Ticket Management",
    "description": "Skill for handling customer support tickets from Zendesk.",
    "type": "recipe",
    "folder_id": "7498",
    "project_id": "4567",
    "genies": [
      {
        "id": "gin-BWLSPX4z-BaT3D9",
        "name": "Customer Support Genie"
      }
    ]
  },
  {
    "id": 65039789,
    "name": "Slack Notifications",
    "description": "Skill for sending targeted Slack alerts.",
    "type": "recipe",
    "folder_id": "7302",
    "project_id": "4567",
    "genies": []
  },
  {
    "id": "<mcp_server_id>",
    "name": "Salesforce MCP server",
    "description": "MCP server that exposes Salesforce tools.",
    "type": "<mcp_server_type_value>",
    "folder_id": "7302",
    "project_id": "4567",
    "genies": []
  }
]

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

既存のレシピをスキルに変換します。 The recipe must use a Start workflow trigger with defined inputs and actions. このエンドポイントをrecipe_idで呼び出して、レシピをAgent Studioのスキルとして登録します。

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

ペイロード ​

名前タイプ説明
recipe_idinteger
必須
スキルに変換するレシピの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

クエリパラメータ ​

名前タイプ説明
idstring
required
取得するスキルの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"
}

最終更新日: