---
url: 'https://docs.workato.com/en/workato-api/agent-studio.md'
description: >-
  Reference for the Agent Studio API to create and manage genies, knowledge
  bases, skills, and guardrail policies programmatically.
---

# Developer API - Agent Studio

The [Agent Studio](/en/agentic/agent-studio) APIs allow you to programmatically create and manage Agent Studio assets, such as genies, knowledge bases, and skills.

## Rate limits

Agent Studio resources have the following rate limits:

| Type | Resource | Quota |
| --- | --- | --- |
| GET | List genies: [/api/agentic/genies](https://docs.workato.com/workato-api/agent-studio.html#list-genies) | 1,000 requests per minute |
| GET | Get a genie by ID: [/api/agentic/genies/:id](https://docs.workato.com/workato-api/agent-studio.html#get-a-genie-by-id) | 1,000 requests per minute |
| GET | All [genie conversation](https://docs.workato.com/workato-api/agent-studio.html#conversations) endpoints | 10 requests per second |
| All | All other [genie](https://docs.workato.com/workato-api/agent-studio.html#genies) endpoints | 60 requests per minute |
| GET | List Knowledge bases: [/api/agentic/knowledge\_bases](https://docs.workato.com/workato-api/agent-studio.html#list-knowledge-bases) | 1,000 requests per minute |
| GET | Get a Knowledge base by ID: [/api/agentic/knowledge\_bases/:id](https://docs.workato.com/workato-api/agent-studio.html#get-a-knowledge-base-by-id) | 1,000 requests per minute |
| All | All other [Knowledge bases](https://docs.workato.com/workato-api/agent-studio.html#knowledge-bases) endpoints | 60 requests per minute |
| GET | List Skills: [/api/agentic/skills](https://docs.workato.com/workato-api/agent-studio.html#list-skills) | 1,000 requests per minute |
| GET | Get a skill by ID: [api/agentic/skills/:id](https://docs.workato.com/workato-api/agent-studio.html#get-a-skill-by-id) | 1,000 requests per minute |
| All | All other [Skills](https://docs.workato.com/workato-api/agent-studio.html#skills) endpoints | 60 requests per minute |

### Quick reference

| Type | Resource | Description |
| --- | --- | --- |
| GET | [/api/agentic/genies](#genies) | Returns a list of genies. |
| POST | [/api/agentic/genies](#create-a-genie) | Creates a new genie. |
| PUT | [/api/agentic/genies/:id](#update-a-genie) | Updates an existing genie. |
| GET | [/api/agentic/genies/:id](#get-a-genie-by-id) | Returns the genie associated with the ID you specify. |
| DELETE | [/api/agentic/genies/:id](#delete-a-genie) | Deletes a genie. |
| POST | [/api/agentic/genies/:id/start](#start-a-genie) | Starts the genie associated with the ID you specify. |
| POST | [/api/agentic/genies/:id/stop](#stop-a-genie) | Stops the genie associated with the ID you specify. |
| POST | [/api/agentic/genies/:id/assign\_skills](#assign-a-skill-to-a-genie) | Assigns skills to the genie associated with the ID you specify. |
| POST | [/api/agentic/genies/:id/remove\_skills](#remove-a-skill-from-a-genie) | Removes skills from the genie associated with the ID you specify. |
| POST | [/api/agentic/genies/:id/assign\_knowledge\_bases](#assign-a-knowledge-base-to-a-genie) | Assigns knowledge bases to the genie associated with the ID you specify. |
| POST | [/api/agentic/genies/:id/remove\_knowledge\_bases](#remove-a-knowledge-base-from-a-genie) | Removes knowledge bases from the genie associated with the ID you specify. |
| POST | [/api/agentic/genies/:id/assign\_user\_groups](#assign-a-user-group-to-a-genie) | Assigns user group access to the genie associated with the ID you specify. |
| POST | [/api/agentic/genies/:id/remove\_user\_groups](#remove-a-user-group-from-a-genie) | Removes user group access from the genie associated with the ID you specify. |
| GET | [/api/agentic/genies/clients](#list-genie-clients) | Returns a list of genie clients. |
| POST | [/api/agentic/genies/clients](#create-a-genie-client) | Creates a new genie client (API key or OAuth). |
| PUT | [/api/agentic/genies/clients/:client\_id](#update-a-genie-client) | Updates a genie client's name. |
| DELETE | [/api/agentic/genies/clients/:client\_id](#delete-a-genie-client) | Deletes a genie client. |
| POST | [/api/agentic/genies/clients/:client\_id/regenerate](#regenerate-a-genie-client-key) | Regenerates the API key for a genie client. |
| POST | [/api/agentic/genies/:id/clients](#attach-a-client-to-a-genie) | Attaches a client to a genie. |
| DELETE | [/api/agentic/genies/:id/clients/:client\_id](#detach-a-client-from-a-genie) | Detaches a client from a genie. |
| GET | [/api/agentic/genies/:genie\_id/conversations](#list-conversations) | Returns a list of a genie's conversations. Doesn't include event-level detail. |
| GET | [/api/agentic/genies/:genie\_id/conversations/:conversation\_id](#get-a-conversation) | Returns a genie conversation you specify. Doesn't include event-level detail. |
| GET | [/api/agentic/genies/:genie\_id/conversations/:conversation\_id/events](#list-conversation-events) | Returns the full events of a single conversation. |
| GET | [/api/agentic/genies/:genie\_id/guardrails](#get-a-genies-guardrail) | Returns the guardrail and its policies for the genie associated with the ID you specify. |
| PUT | [/api/agentic/genies/:genie\_id/guardrails/policies/:policy\_type](#create-or-update-a-policy) | Creates or updates a single guardrail policy on the genie associated with the ID you specify. |
| GET | [/api/agentic/genies/guardrails/policies/pii\_entities](#list-pii-entity-types) | Returns the list of PII entity type strings you can use in a `pii_detection` policy. |
| GET | [/api/agentic/knowledge\_bases](#list-knowledge-bases) | Returns a list of knowledge bases. |
| POST | [/api/agentic/knowledge\_bases](#create-a-knowledge-base) | Creates a new knowledge base. |
| GET | [/api/agentic/knowledge\_bases/:id](#get-a-knowledge-base-by-id) | Returns the knowledge base associated with the ID you specify. |
| PUT | [/api/agentic/knowledge\_bases/:id](#update-a-knowledge-base) | Updates an existing knowledge base. |
| DELETE | [/api/agentic/knowledge\_bases/:id](#delete-a-knowledge-base) | Deletes a knowledge base. |
| GET | [/api/agentic/knowledge\_bases/:id/data\_sources](#get-knowledge-base-data-sources) | Returns the data sources associated with the knowledge base ID you specify. |
| GET | [/api/agentic/knowledge\_bases/:id/recipes](#get-knowledge-base-recipes) | Returns the recipes associated with the knowledge base ID you specify. |
| GET | [/api/agentic/skills](#list-skills) | Returns a list of skills. |
| POST | [/api/agentic/skills](#create-a-skill) | Creates a new skill. |
| GET | [/api/agentic/skills/:id](#get-a-skill-by-id) | Returns the skill associated with the ID you specify. |

## Genies

Agent Studio genies support the following endpoints and configurations:

### List genies

Returns a list of genies.

<api-code no-copy-method>

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

</api-code>

#### Query parameters

| Name | Type | Description |
| --- | --- | --- |
| folder\_id | **string** _optional_ | The ID of the folder where the genie resides. |
| project\_id | **string** _optional_ | The ID of the project where the genie resides. |
| state | **string** _optional_ | The state of the genie. For example: `active` or `inactive`. |
| page | **integer** _optional_ | Page number of the genies to fetch. Minimum value is `1`. |
| per\_page | **integer** _optional_ | Number of genies to return in a single page. Minimum value is `1`. Maximum value is `50`. |

##### Sample request

<api-code>

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

</api-code>

##### Sample response

Channel configuration fields are always returned, using their default values when no explicit configuration has been set.

```json
[
  {
      "id": "gin-BWLSPX4z-BaT3D9",
      "name": "Customer Support Genie",
      "description": "Handles customer support inquiries and provides quick responses.",
      "state": "stopped",
      "folder_id": 22991030,
      "instructions": "You are a helpful, friendly support agent who answers customer questions clearly and politely.",
      "ai_provider": "open_ai",
      "chat_interface": "slack",
      "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": "Updated to handle billing inquiries in addition to general support.",
      "state": "stopped",
      "folder_id": 21285720,
      "instructions": "You are a knowledgeable, polite support assistant. Always prioritize clear, concise answers.",
      "ai_provider": "open_ai",
      "chat_interface": "slack",
      "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"
  }
]
```

### Create a genie

Creates a new genie.

<api-code no-copy-method>

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

</api-code>

#### Payload

| Name | Type | Description |
| --- | --- | --- |
| name | **string** _required_ | The name of the genie. |
| description | **string** _required_ | A description of the genie's purpose. |
| folder\_id | **string** _required_ | The ID of the folder where the genie resides. |
| instructions | **string** _required_ | The instructions your genie uses to identify its purpose, personality, and job description. |
| ai\_provider | **string** _required_ | The AI provider that powers your genie. Accepted values are `anthropic` or `open_ai`. |
| shared\_account\_id | **integer** _required_ | The Connection ID of your genie. |
| custom\_oauth\_key\_id | **integer** _required_ | Custom OAuth key ID. |
| matrix | **boolean** _required_ | Determines whether Workato GO is enabled as your chat interface or not. Accepted values are `true` or `false`. |
| channel\_mode | **string** _optional_ | Controls where the genie responds. Accepted values are `dms_only` or `everywhere`. Defaults to `dms_only`. |
| channel\_scope | **string** _optional_ | Determines which channels the genie responds in. Accepted values are `specific` or `all_invited`. Defaults to `specific`. |
| response\_mode | **string** _optional_ | Controls how the genie is triggered in a channel. Accepted values are `on_mention` or `helpdesk`. Defaults to `on_mention`. |
| channel\_whitelist | **string\[\]** _optional_ | An array of Slack channel IDs the genie is permitted to respond in. Only applies when `channel_scope` is `specific`. Defaults to `[]`. |

##### Sample request

<api-code>

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

</api-code>

##### Sample response

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

### Update a genie

Updates an existing genie.

<api-code no-copy-method>

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

</api-code>

#### Query parameters

| Name | Type | Description |
| --- | --- | --- |
| id | **string** _required_ | The ID of the genie you plan to update. |
| name | **string** _optional_ | The name of the genie. |
| description | **string** _optional_ | A description of the genie's purpose. |
| folder\_id | **string** _optional_ | The ID of the folder where the genie resides. |
| instructions | **string** _optional_ | The instructions your genie uses to identify its purpose, personality, and job description. |
| ai\_provider | **string** _optional_ | The AI provider that powers your genie. Accepted values are `anthropic` or `open_ai`. |
| shared\_account\_id | **integer** _optional_ | The Connection ID of your genie. |
| custom\_oauth\_key\_id | **integer** _optional_ | Custom OAuth key ID. |
| matrix | **boolean** _optional_ | Determines whether Workato GO is enabled as your chat interface or not. Accepted values are `true` or `false`. |
| channel\_mode | **string** _optional_ | Controls where the genie responds. Accepted values are `dms_only` or `everywhere`. |
| channel\_scope | **string** _optional_ | Determines which channels the genie responds in. Accepted values are `specific` or `all_invited`. |
| response\_mode | **string** _optional_ | Controls how the genie is triggered in a channel. Accepted values are `on_mention` or `helpdesk`. |
| channel\_whitelist | **string\[\]** _optional_ | An array of Slack channel IDs the genie is permitted to respond in. Only applies when `channel_scope` is `specific`. Pass an empty array to clear the list. |

##### Sample request

<api-code>

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

</api-code>

##### Sample response

```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",
  "shared_account_id": 1234,
  "custom_oauth_key_id": 5678,
  "matrix": false,
  "channel_mode": "everywhere",
  "channel_scope": "specific",
  "response_mode": "on_mention",
  "channel_whitelist": ["C0A9H9EN7J6"]
}
```

### Get a genie by ID

Returns the genie associated with the ID you specify.

<api-code no-copy-method>

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

</api-code>

#### Query parameters

| Name | Type | Description |
| --- | --- | --- |
| id | **string** _required_ | The ID of the genie you plan to retrieve. |

##### Sample request

<api-code>

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

</api-code>

##### Sample response

Channel configuration fields are always returned, using their default values when no explicit configuration has been set.

```json
{
  "id": "gin-ZWSMPR4a-TaG7S9",
  "name": "Customer Support Genie v2",
  "description": "Updated to handle billing inquiries in addition to general support.",
  "state": "stopped",
  "folder_id": 21285720,
  "project_id": 93761783,
  "instructions": "You are a knowledgeable, polite support assistant. Always prioritize clear, concise answers.",
  "ai_provider": "open_ai",
  "chat_interface": "slack",
  "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"
}
```

### Delete a genie

Deletes a genie.

<api-code no-copy-method>


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

</api-code>

#### Query parameters

| Name | Type | Description |
| --- | --- | --- |
| id | **string** _required_ | The ID of the genie you plan to delete. |

##### Sample request

<api-code>

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

</api-code>

##### Sample response

```json
{
    "success": "true"
}
```

### Start a genie

Starts the genie associated with the ID you specify.

<api-code no-copy-method>

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

</api-code>

#### Query parameters

| Name | Type | Description |
| --- | --- | --- |
| id | **string** _required_ | The ID of the genie you plan to start. |

##### Sample request

<api-code>

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

</api-code>

##### Sample response

```json
{
  "success": true
}
```

### Stop a genie

Stops the genie associated with the ID you specify.

<api-code no-copy-method>

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

</api-code>

#### Query parameters

| Name | Type | Description |
| --- | --- | --- |
| id | **string** _required_ | The ID of the genie you plan to stop. |

##### Sample request

<api-code>

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

</api-code>

##### Sample response

```json
{
  "success": true
}
```

### Assign a skill to a genie

Assigns skills to the genie associated with the ID you specify.

<api-code no-copy-method>

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

</api-code>

#### Query parameters

| Name | Type | Description |
| --- | --- | --- |
| id | **string** _required_ | The ID of the genie you to which you plan to assign skills. |

#### Payload

| Name | Type | Description |
| --- | --- | --- |
| skill\_ids | **array of string** _required_ | An array of skill IDs to assign to a genie. |

###### Sample request

<api-code>

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

</api-code>

###### Sample response

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

### Remove a skill from a genie

Removes a skill from the genie associated with the ID you specify.

<api-code no-copy-method>

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

</api-code>

#### Query parameters

| Name | Type | Description |
| --- | --- | --- |
| id | **string** _required_ | The ID of the genie you from which you plan to remove skills. |

#### Payload

| Name | Type | Description |
| --- | --- | --- |
| skill\_ids | **array of string** _required_ | An array of skill IDs to remove from a genie. |

###### Sample request

<api-code>

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

</api-code>

###### Sample response

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

### Assign a knowledge base to a genie

Assigns knowledge bases to the genie associated with the ID you specify.

<api-code no-copy-method>

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

</api-code>

#### Query parameters

| Name | Type | Description |
| --- | --- | --- |
| id | **string** _required_ | The ID of the genie you to which you plan to assign knowledge bases. |

#### Payload

| Name | Type | Description |
| --- | --- | --- |
| knowledge\_base\_ids | **array of string** _required_ | An array of knowledge base IDs to assign to a genie. |

###### Sample request

<api-code>

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

</api-code>

###### Sample response

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

### Remove a knowledge base from a genie

Removes a knowledge base from the genie associated with the ID you specify.

<api-code no-copy-method>

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

</api-code>

#### Query parameters

| Name | Type | Description |
| --- | --- | --- |
| id | **string** _required_ | The ID of the genie you from which you plan to remove knowledge bases. |

#### Payload

| Name | Type | Description |
| --- | --- | --- |
| knowledge\_base\_ids | **array of string** _required_ | An array of knowledge base IDs to remove from a genie. |

###### Sample request

<api-code>

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

</api-code>

###### Sample response

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

### Assign a user group to a genie

Assigns user group access to the genie associated with the ID you specify.

<api-code no-copy-method>

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

</api-code>

#### Query parameters

| Name | Type | Description |
| --- | --- | --- |
| id | **string** _required_ | The ID of the genie you to which you plan to assign user group access. |

#### Payload

| Name | Type | Description |
| --- | --- | --- |
| user\_group\_ids | **array of string** _required_ | An array of user group IDs to add to a genie. |

###### Sample request

<api-code>

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

</api-code>

###### Sample response

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

### Remove a user group from a genie

Removes user group access from the genie associated with the ID you specify.

<api-code no-copy-method>

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

</api-code>

#### Query parameters

| Name | Type | Description |
| --- | --- | --- |
| id | **string** _required_ | The ID of the genie you from which you plan to remove user group access. |

#### Payload

| Name | Type | Description |
| --- | --- | --- |
| user\_group\_ids | **array of string** _required_ | An array of user group IDs to remove from a genie. |

###### Sample request

<api-code>

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

</api-code>

###### Sample response

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

## Genie clients

Genie clients use the runtime credentials applications use to call a genie through the [Headless API](/en/agentic/agent-studio/chat-interface/headless-api). You must create a client and attach it to a genie. A client authenticates at runtime with either an API key or OAuth 2.0 (PKCE).

> **ONE CLIENT PER GENIE**
> 
> A genie supports a single attached client. The client-to-genie relationship is **1:1**: attaching a client to a genie that already has one, or attaching a client already attached to another genie, returns a `409` conflict. [Detach](#detach-a-client-from-a-genie) the existing pairing first to re-point a client.

### List genie clients

Returns the genie clients in the workspace.

<api-code no-copy-method>

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

</api-code>

##### Sample request

<api-code>

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

</api-code>

##### Sample response

```json
{
  "data": [
    { "client_id": "gincl-AaBGpLGx-HLdsJL", "client_name": "HR Concierge Web" }
  ],
  "total": 1,
  "page": 1,
  "per_page": 10
}
```

### Create a genie client

Creates a genie client. Set `auth.type` to `api_key` for a server-to-server credential, or `oauth` for a browser-based OAuth 2.0 (PKCE) client.

<api-code no-copy-method>

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

</api-code>

#### Payload

| Name | Type | Description |
| --- | --- | --- |
| client\_name | **string** _required_ | A name for the client. |
| auth | **object** _required_ | The authentication configuration. |
| auth.type | **string** _required_ | The authentication type. Accepted values are `api_key` and `oauth`. |
| auth.oauth\_redirect\_url | **string** _optional_ | The redirect URL registered for the OAuth flow. Required when `auth.type` is `oauth`. |

##### Sample request

<api-code>

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

</api-code>

##### Sample response

API-key clients use the `api_key` with the 64-character hex string returned only once, at creation. Every client also returns a public `oauth_client_id`. OAuth clients don't return secrets.

```json
{
  "data": {
    "client_id": "gincl-AaBGpLGx-HLdsJL",
    "client_name": "HR Concierge Web",
    "oauth_client_id": "MtaJ4c5oIc3_c0TASWnCW0rfmCr6R4UTO7",
    "api_key": "<64-character hex string>"
  }
}
```

### Update a genie client

Updates a genie client's name.

<api-code no-copy-method>

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

</api-code>

#### Payload

| Name | Type | Description |
| --- | --- | --- |
| client\_name | **string** _required_ | The new name for the client. |

##### Sample request

<api-code>

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

</api-code>

### Delete a genie client

Deletes a genie client and invalidates its credentials. [Detach](#detach-a-client-from-a-genie) a genie client to remove it from a genie without deleting it.

<api-code no-copy-method>

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

</api-code>

##### Sample request

<api-code>

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

</api-code>

### Regenerate a genie client key

Regenerates the API key for an API-key client. The previous key is invalidated immediately, and the new key is returned only once.

<api-code no-copy-method>

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

</api-code>

##### Sample request

<api-code>

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

</api-code>

##### Sample response

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

### Attach a client to a genie

Attaches a client to the genie you specify. The genie can't have an existing client. The client can only be attached to one genie at a time.

<api-code no-copy-method>

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

</api-code>

#### Payload

| Name | Type | Description |
| --- | --- | --- |
| genie\_client\_id | **string** _required_ | The ID of the client to attach. |

##### Sample request

<api-code>

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

</api-code>

### Detach a client from a genie

Detaches a client from the genie you specify. The client isn't deleted and can be attached to another genie.

<api-code no-copy-method>

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

</api-code>

##### Sample request

<api-code>

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

</api-code>

## 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](/en/features/activity-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.

### List conversations

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

<api-code no-copy-method>

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

</api-code>

#### Path parameters

| Name | Type | Description |
| --- | --- | --- |
| genie\_id | **string** _required_ | The ID of the genie whose conversations to retrieve. |

#### Query parameters

| Name | Type | Description |
| --- | --- | --- |
| page\[after\] | **string** _optional_ | The starting point for the next set of results based on the last result of the current page. |
| page\[size\] | **integer** _optional_ | The number of items to retrieve per page. The default value is `50` and maximum value is `100`. |
| from | **string** _optional_ | The lower bound on `created_at`, in ISO 8601 format (`YYYY-MM-DDTHH:mm:ss.SSSZ`). Defaults to the start of the retention window. |
| to | **string** _optional_ | The upper bound on `created_at`, in ISO 8601 format (`YYYY-MM-DDTHH:mm:ss.SSSZ`). Defaults to the current time. |
| app\_type | **string** _optional_ | 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. |
| identity\_user\_id | **string** _optional_ | 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

<api-code>

```shell
curl -X GET "https://www.workato.com/api/agentic/genies/gin-AaDdXzLX-dAFvWn-B6/conversations" \
     -H 'Authorization: Bearer <api_token>'
```

</api-code>

Filter by conversations that received positive or negative feedback:

<api-code>

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

</api-code>

##### Sample response

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

### Get a conversation

Returns a genie conversation you specify.

<api-code no-copy-method>

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

</api-code>

#### Path parameters

| Name | Type | Description |
| --- | --- | --- |
| genie\_id | **string** _required_ | The ID of the genie to retrieve a conversation from. |
| conversation\_id | **string** _required_ | The ID of the conversation to retrieve. |

##### Sample request

<api-code>

```shell
curl -X GET https://www.workato.com/api/agentic/genies/gin-AaDdXzLX-dAFvWn-B6/conversations/conversation-01KSR1JDQMT001AWVTPMTRJ3K8 \
     -H 'Authorization: Bearer <api_token>'
```

</api-code>

##### 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](#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.

```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",
        "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

Returns the full events of a single conversation. Refer to [Genie conversation events](/en/features/activity-audit-log-streaming-sample#genie-conversations) for information about each event type.

<api-code no-copy-method>

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

</api-code>

#### Path parameters

| Name | Type | Description |
| --- | --- | --- |
| genie\_id | **string** _required_ | The ID of the genie to retrieve conversation events from. |
| conversation\_id | **string** _required_ | The ID of the conversation to retrieve conversation events from. |

#### Query parameters

| Name | Type | Description |
| --- | --- | --- |
| page\[after\] | **string** _optional_ | The starting point for the next set of results based on the last result of the current page. |
| page\[size\] | **integer** _optional_ | 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. |
| order | **string** _optional_ | 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\_id | **string** _optional_ | The ID of a run to filter results by. Defaults to all runs. |

##### Sample request

<api-code>

```shell
curl -X GET "https://www.workato.com/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'
```

</api-code>

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

[Guardrails](/en/agentic/agent-studio/guardrails/guardrails) let you attach content safety policies to a genie. Every chat turn is evaluated against its policies before the model responds when a guardrail is present. Each guardrail has two default policies when first attached: `prompt_attack` and `harmful_content`.

> **BETA FEATURE**
> 
> Guardrails API endpoints are in beta. Contact your customer manager for more information.

### Disable or remove a policy

There isn't a `DELETE` guardrail endpoint to enable you to remove a policy from a guardrail through the API. You must reconfigure the guardrail with the [Create or update a policy](#create-or-update-a-policy) endpoint. Use the following table to determine how to turn a policy off based on its type:

| Policy type | How to turn off the policy |
| --- | --- |
| `pii_detection`, `profanity_filter` | Set `enabled: false`. The policy stays attached but takes no action. |
| `harmful_content` | Set each category's filter to `strength: "NONE"` to disable it. `filters` must stay non-empty (an empty array returns `422`), so a fully disabled policy keeps all five entries at `strength: "NONE"`. Sending `enabled` returns `422`. |
| `prompt_attack` | Set `strength: "NONE"`. Sending `enabled` returns `422`. |
| `custom_word_filter` | Send `custom_words: []` to clear the list. |
| `topic_boundary` | `topics` must be non-empty. Reconfigure the topics rather than emptying the array. |

`NONE` is a valid `strength` value and is used by the genie builder UI to turn `prompt_attack` and `harmful_content` off. The two default policies, `prompt_attack` and `harmful_content`, are always present after a guardrail is attached. You can turn off these policies with `strength: "NONE"`, but you can't remove the policies.

### Get a genie guardrail

Returns the guardrail and its policies for the genie associated with the ID you specify.

<api-code no-copy-method>

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

</api-code>

#### Query parameters

| Name | Type | Description |
| --- | --- | --- |
| genie\_id | **string** _required_ | The ID of the genie whose guardrail you plan to retrieve. Genie handles begin with `gin-`. For example `gin-aBC123-xYz789-prod1`. |

##### Sample request

<api-code>

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

</api-code>

##### Sample response

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

##### Sample response

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

#### Error responses

| Status | When |
| --- | --- |
| `401 Unauthorized` | Missing or invalid API token. |
| `404 Not Found` | Genie handle unknown, outside your folder scope, or the `genie_guardrails_enabled` flag is off. |

* * *

### Create or update a policy

Creates or updates a single guardrail policy on the genie associated with the ID you specify. A new policy is created if no policy exists for the `policy_type` you provide. Otherwise the existing policy's configuration is replaced in full. You must send the complete configuration you plan to use. Partial updates aren't supported.

<api-code no-copy-method>

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

</api-code>

#### Query parameters

| Name | Type | Description |
| --- | --- | --- |
| genie\_id | **string** _required_ | The ID of the genie whose policy you plan to create or update. |
| policy\_type | **string** _required_ | The type of policy to create or update. Accepted values: `harmful_content`, `prompt_attack`, `pii_detection`, `topic_boundary`, `profanity_filter`, `custom_word_filter`. |

#### Payload

| Name | Type | Description |
| --- | --- | --- |
| configuration | **object** _required_ | The policy configuration. Shape varies by `policy_type`. Refer to [Policy types](#policy-types) for more information. |

##### Sample request

<api-code>

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

</api-code>

##### Sample response

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

#### Error responses

| Status | When |
| --- | --- |
| `400 Bad Request` | `policy_type` isn't one of the six valid values. |
| `401 Unauthorized` | Missing or invalid API token. |
| `404 Not Found` | Genie not found, no guardrail attached to the genie, or the feature flag is off. |
| `422 Unprocessable Entity` | `configuration` failed validation. This can be caused by missing a required field, an unknown key, an invalid enum value, or if the request exceeds quotas. |

##### Sample 422 response

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

* * *

### List available PII entity types

Returns the list of PII entity type strings you can use in a `pii_detection` policy's `pii_entities[].type` field. This list isn't specific to your current environment.

<api-code no-copy-method>

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

</api-code>

##### Sample request

<api-code>

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

</api-code>

##### Sample response

```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 types

Each `policy_type` accepts a specific `configuration` shape. Sending unknown top-level keys fails with `422`.

#### harmful\_content

Filters user input and model output for categories of harmful content.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `filters` | array | yes | Non-empty. Each element is `{ "type": <category>, "strength": <strength> }`. |
| `filters[].type` | string | yes | One of `HATE`, `INSULTS`, `SEXUAL`, `VIOLENCE`, `MISCONDUCT`, `PROMPT_ATTACK`. |
| `filters[].strength` | string | yes | One of `NONE`, `LOW`, `MEDIUM`, `HIGH`. Use `NONE` or omit the entry to disable the category. |

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

Detects attempts to override system instructions, jailbreak, or otherwise manipulate the genie within the user's prompt.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `strength` | string | yes | One of `NONE`, `LOW`, `MEDIUM`, `HIGH`. Use `NONE` to turn off the policy. |

```json
{ "configuration": { "strength": "HIGH" } }
```

#### pii\_detection

Detects PII in chat content and blocks, anonymizes, or tokenizes it. You can match by built-in entity type, custom regex, or both.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `enabled` | boolean | yes | Enables the feature. Other fields are accepted but ignored when set to `false`. |
| `action` | string | yes | One of `BLOCK`, `ANONYMIZE`, `TOKENIZE`. Required even when `enabled` is `false`. |
| `pii_entities` | array | conditional | Required (non-empty) if `enabled` is `true` and `pii_custom_regexes` is empty or absent. Each element is `{ "type": <entity> }`. Use [List available PII entity types](#list-pii-entity-types) to view valid values. |
| `pii_custom_regexes` | array | conditional | Required (non-empty) if `enabled` is `true` and `pii_entities` is empty or absent. Up to 10 entries. Each is `{ "name": <label>, "pattern": <regex> }`. |
| `pii_custom_regexes[].name` | string | yes | Non-blank label shown in audit logs. |
| `pii_custom_regexes[].pattern` | string | yes | Valid regular expression. Must be less than 500 characters. |

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

Restricts the conversation to specific topics. Optional example utterances help the model classify borderline cases.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `topics` | array | yes | Non-empty. Up to 30 topics. |
| `topics[].name` | string | yes | Must be less than 50 characters. Non-blank. |
| `topics[].description` | string | no | Must be less than 300 characters. |
| `topics[].examples` | array of strings | no | Up to 5 examples, each must be less than 300 characters. |

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

The profanity filter can be enabled or disabled.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `enabled` | boolean | yes | `true` to enable, `false` to disable. |

```json
{ "configuration": { "enabled": true } }
```

#### custom\_word\_filter

Blocks messages containing any of an explicit list of words or short phrases.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `custom_words` | array of strings | yes | Up to 100 entries. Each entry must be less than 50 characters. Send an empty array to clear the list. |

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

## Knowledge bases

### List knowledge bases

Returns a list of knowledge bases.

<api-code no-copy-method>

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

</api-code>

#### Query parameters

| Name | Type | Description |
| --- | --- | --- |
| folder\_id | **string** _optional_ | The ID of the folder where the knowledge base resides. |
| project\_id | **string** _optional_ | The ID of the project where the knowledge base resides. |
| query | **string** _optional_ | Search query. |
| page | **integer** _optional_ | Page number of the knowledge base to fetch. Minimum value is `1`. |
| per\_page | **integer** _optional_ | Number of knowledge bases to return in a single page. Minimum value is `1`. Maximum value is `50`. |
| sort\_term | **string** _optional_ | The field or term to sort results by. For example: `name` or `latest_activity`. |

###### Sample request

<api-code>

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

```

</api-code>

###### Sample response

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

### Create a knowledge base

Creates a new knowledge base.

<api-code no-copy-method>

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

</api-code>

#### Payload

| Name | Type | Description |
| --- | --- | --- |
| name | **string** _required_ | The name of the knowledge base. |
| description | **string** _required_ | A description of the knowledge base. |
| folder\_id | **string** _required_ | The ID of the folder where the knowledge base resides. |
| source\_type | **string** _required_ | The source of the knowledge base, such as a recipe. |
| data\_sources | **string** _required_ | Configure data sources for the knowledge base. |

###### Sample request

<api-code>

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

</api-code>

###### Sample response

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

### Get a knowledge base by ID

Returns the knowledge base associated with the ID you specify.

<api-code no-copy-method>

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

</api-code>

#### Query parameters

| Name | Type | Description |
| --- | --- | --- |
| id | **string** _required_ | The ID of the knowledge base you plan to retrieve. |

###### Sample request

<api-code>

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

</api-code>

###### Sample response

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

### Update a knowledge base

Updates an existing knowledge base.

<api-code no-copy-method>

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

</api-code>

#### Query parameters

| Name | Type | Description |
| --- | --- | --- |
| id | **string** _required_ | The ID of the knowledge base you plan to update. |
| name | **string** _optional_ | The name of the knowledge base. |
| description | **string** _optional_ | The description of the knowledge base. |
| folder\_id | **string** _optional_ | The ID of the folder where the knowledge base resides. |
| data\_sources | **object** _optional_ | The configured data sources for the knowledge base. |

##### Sample request

<api-code>

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

</api-code>

##### Sample response

```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 a knowledge base

Deletes a knowledge base.

<api-code no-copy-method>

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

</api-code>

#### Query parameters

| Name | Type | Description |
| --- | --- | --- |
| id | **string** _required_ | The ID of the knowledge base you plan to delete. |

##### Sample request

<api-code>

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

</api-code>

##### Sample response

```json
{
    "success": "true"
}
```

### Get knowledge base data sources

Returns the data sources associated with the knowledge base ID you specify.

<api-code no-copy-method>

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

</api-code>

#### Query parameters

| Name | Type | Description |
| --- | --- | --- |
| id | **string** _required_ | The ID of the knowledge base for which you plan to retrieve data sources. |

##### Sample request

<api-code>

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

</api-code>

##### Sample response

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

### Get knowledge base recipes

Returns the recipes associated with the knowledge base ID you specify.

<api-code no-copy-method>

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

</api-code>

#### Query parameters

| Name | Type | Description |
| --- | --- | --- |
| id | **string** _required_ | The ID of the knowledge base for which you plan to retrieve associated recipes. |
| query | **string** _optional_ | Search query. |
| page | **integer** _optional_ | Page number of the genies to fetch. Minimum value is `1`. |
| per\_page | **integer** _optional_ | Number of genies to return in a single page. Minimum value is `1`. Maximum value is `50`. |
| sort\_term | **string** _optional_ | The field or term to sort results by. For example: `name` or `latest_activity`. |

##### Sample request

<api-code>

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

</api-code>

##### Sample response

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

## Skills

Use the following endpoints to work with skills programmatically:

### List skills

Returns a list of skills.

<api-code no-copy-method>

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

</api-code>

#### Query parameters

| Name | Type | Description |
| --- | --- | --- |
| folder\_id | **string** _optional_ | The ID of the folder where the genie resides. |
| project\_id | **string** _optional_ | The ID of the project where the genie resides. |
| query | **string** _optional_ | Search query. |
| page | **integer** _optional_ | Page number of the genies to fetch. Minimum value is `1`. |
| per\_page | **integer** _optional_ | Number of genies to return in a single page. Minimum value is `1`. Maximum value is `50`. |
| sort\_term | **string** _optional_ | The field or term to sort results by. For example: `name` or `latest_activity`. |

##### Sample request

<api-code>

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

</api-code>

##### Sample response

```json
[
  {
    "id": 65001201,
    "name": "Zendesk Ticket Management",
    "description": "Skill for handling customer support tickets from Zendesk.",
    "folder_id": "7498",
    "project_id": "4567"
  },
  {
    "id": 65039789,
    "name": "Slack Notifications",
    "description": "Skill for sending targeted Slack alerts.",
    "folder_id": "7302",
    "project_id": "4567"
  }
]
```

### Create a skill from an existing recipe

Converts an existing recipe into a skill. The recipe must use a [Start workflow](/en/agentic/agent-studio/connectors/workato-skill-connector/start-workflow) trigger with defined inputs and actions. Call this endpoint with the `recipe_id` to register the recipe as a skill in Agent Studio.

<api-code no-copy-method>

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

</api-code>

#### Payload

| Name | Type | Description |
| --- | --- | --- |
| recipe\_id | **integer** _required_ | The ID of the recipe to convert into a skill. |

##### Sample request

<api-code>

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

</api-code>

##### Sample response

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

### Get a skill by ID

Returns the skill associated with the ID you specify.

<api-code no-copy-method>

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

</api-code>

#### Query parameters

| Name | Type | Description |
| --- | --- | --- |
| id | **string** _required_ | The ID of the skill for you plan to retrieve. |

##### Sample request

<api-code>

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

</api-code>

##### Sample response

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