Agent Studio

The 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	Limit
GET	List genies: /api/agentic/genies	1,000 requests per minute
GET	Get a genie by ID: /api/agentic/genies/:id	1,000 requests per minute
All	All other genie endpoints	60 requests per minute
GET	List Knowledge bases: /api/agentic/knowledge_bases	1,000 requests per minute
GET	Get a Knowledge base by ID: /api/agentic/knowledge_bases/:id	1,000 requests per minute
All	All other Knowledge bases endpoints	60 requests per minute
GET	List Skills: /api/agentic/skills	1,000 requests per minute
GET	Get a skill by ID: api/agentic/skills/:id	1,000 requests per minute
All	All other Skills endpoints	60 requests per minute

Quick reference

Type	Resource	Description
GET	/api/agentic/genies	Returns a list of genies.
POST	/api/agentic/genies	Creates a new genie.
PUT	/api/agentic/genies/:id	Updates an existing genie.
GET	/api/agentic/genies/:id	Returns the genie associated with the ID you specify.
DELETE	/api/agentic/genies/:id	Deletes a genie.
POST	/api/agentic/genies/:id/start	Starts the genie associated with the ID you specify.
POST	/api/agentic/genies/:id/stop	Stops the genie associated with the ID you specify.
POST	/api/agentic/genies/:id/assign_skills	Assigns skills to the genie associated with the ID you specify.
POST	/api/agentic/genies/:id/remove_skills	Removes skills from the genie associated with the ID you specify.
POST	/api/agentic/genies/:id/assign_knowledge_bases	Assigns knowledge bases to the genie associated with the ID you specify.
POST	/api/agentic/genies/:id/remove_knowledge_bases	Removes knowledge bases from the genie associated with the ID you specify.
POST	/api/agentic/genies/:id/assign_user_groups	Assigns user group access to the genie associated with the ID you specify.
POST	/api/agentic/genies/:id/remove_user_groups	Removes user group access from the genie associated with the ID you specify.
GET	/api/agentic/genies/clients	Returns a list of genie clients.
POST	/api/agentic/genies/clients	Creates a new genie client (API key or OAuth).
PUT	/api/agentic/genies/clients/:client_id	Updates a genie client's name.
DELETE	/api/agentic/genies/clients/:client_id	Deletes a genie client.
POST	/api/agentic/genies/clients/:client_id/regenerate	Regenerates the API key for a genie client.
POST	/api/agentic/genies/:id/clients	Attaches a client to a genie.
DELETE	/api/agentic/genies/:id/clients/:client_id	Detaches a client from a genie.
GET	/api/agentic/genies/:genie_id/guardrails	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	Creates or updates a single guardrail policy on the genie associated with the ID you specify.
GET	/api/agentic/genies/guardrails/policies/pii_entities	Returns the list of PII entity type strings you can use in a `pii_detection` policy.
GET	/api/agentic/knowledge_bases	Returns a list of knowledge bases.
POST	/api/agentic/knowledge_bases	Creates a new knowledge base.
GET	/api/agentic/knowledge_bases/:id	Returns the knowledge base associated with the ID you specify.
PUT	/api/agentic/knowledge_bases/:id	Updates an existing knowledge base.
DELETE	/api/agentic/knowledge_bases/:id	Deletes a knowledge base.
GET	/api/agentic/knowledge_bases/:id/data_sources	Returns the data sources associated with the knowledge base ID you specify.
GET	/api/agentic/knowledge_bases/:id/recipes	Returns the recipes associated with the knowledge base ID you specify.
GET	/api/agentic/skills	Returns a list of skills.
POST	/api/agentic/skills	Creates a new skill.
GET	/api/agentic/skills/: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.

bash

GET /api/agentic/genies

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

shell

curl  -X GET "https://www.workato.com/api/agentic/genies?per_page=10&page=1" \
      -H 'Authorization: Bearer <api_token>'

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.

bash

POST /api/agentic/genies

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

shell

curl -X POST https://www.workato.com/api/agentic/genies \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "name": "Customer Support Genie",
           "description": "Handles customer support inquiries and provides quick responses.",
           "folder_id": "7498",
           "instructions": "You are a helpful, friendly support agent who answers customer questions clearly and politely.",
           "ai_provider": "open_ai",
           "shared_account_id": 1234,
           "custom_oauth_key_id": 5678,
           "matrix": true,
           "channel_mode": "everywhere",
           "channel_scope": "specific",
           "response_mode": "helpdesk",
           "channel_whitelist": ["C0A9H9EN7J6", "C1B2C3D4E5F"]
         }'

Sample response

json

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

Update a genie

Updates an existing genie.

bash

PUT /api/agentic/genies/:id

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

shell

curl -X PUT https://www.workato.com/api/agentic/genies/101 \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "name": "Customer Support Genie v2",
           "description": "Updated to handle billing inquiries in addition to general support.",
           "instructions": "You are a knowledgeable, polite support assistant. Always prioritize clear, concise answers.",
           "matrix": false,
           "channel_mode": "everywhere",
           "channel_scope": "specific",
           "response_mode": "on_mention",
           "channel_whitelist": ["C0A9H9EN7J6"]
         }'

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.

bash

GET /api/agentic/genies/:id

Query parameters

Name	Type	Description
id	string required	The ID of the genie you plan to retrieve.

Sample request

shell

curl -X GET https://www.workato.com/api/agentic/genies/gin-ZWSMPR4a-TaG7S9 \
     -H 'Authorization: Bearer <api_token>'

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.

bash

DELETE /api/agentic/genies/:id

Query parameters

Name	Type	Description
id	string required	The ID of the genie you plan to delete.

Sample request

shell

curl -X DELETE https://www.workato.com/api/agentic/genies/gin-ZWSMPR4a-TaG7S9 \
     -H 'Authorization: Bearer <api_token>'

Sample response

json

{
    "success": "true"
}

Start a genie

Starts the genie associated with the ID you specify.

bash

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

Query parameters

Name	Type	Description
id	string required	The ID of the genie you plan to start.

Sample request

shell

curl -X POST https://www.workato.com/api/agentic/genies/gin-ZWSMPR4a-TaG7S9/start \
     -H 'Authorization: Bearer <api_token>'

Sample response

json

{
  "success": true
}

Stop a genie

Stops the genie associated with the ID you specify.

bash

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

Query parameters

Name	Type	Description
id	string required	The ID of the genie you plan to stop.

Sample request

shell

curl -X POST https://www.workato.com/api/agentic/genies/gin-ZWSMPR4a-TaG7S9/stop \
     -H 'Authorization: Bearer <api_token>'

Sample response

json

{
  "success": true
}

Assign a skill to a genie

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

bash

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

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

shell

curl -X POST https://www.workato.com/api/agentic/genies/gin-ZWSMPR4a-TaG7S9/assign_skills \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "skill_ids": ["65001201", "65704499", "65039789"]
         }'

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.

bash

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

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

shell

curl -X POST https://www.workato.com/api/agentic/genies/gin-ZWSMPR4a-TaG7S9/assign_skills \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "skill_ids": ["65001201", "65704499"]
         }'

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.

bash

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

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

shell

curl -X POST https://www.workato.com/api/agentic/genies/gin-ZWSMPR4a-TaG7S9/assign_knowledge_bases \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "knowledge_base_ids": ["kb-WSm8kore-blMxrh", "kb-ATx0crok-saMvba"]
         }'

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.

bash

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

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

shell

curl -X POST https://www.workato.com/api/agentic/genies/gin-ZWSMPR4a-TaG7S9/remove_knowledge_bases \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "knowledge_base_ids": ["kb-WSm8kore-blMxrh"]
         }'

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.

bash

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

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

shell

curl -X POST https://www.workato.com/api/agentic/genies/gin-ZWSMPR4a-TaG7S9/assign_user_groups \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "user_group_ids": ["ertXU2Z3sQaL47T8PssX2V, gpzHU1Y3mJaG77W1JbbZ2B"]
         }'

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.

bash

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

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

shell

curl -X POST https://www.workato.com/api/agentic/genies/gin-ZWSMPR4a-TaG7S9/remove_user_groups \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "user_group_ids": ["ertXU2Z3sQaL47T8PssX2V"]
         }'

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. 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 the existing pairing first to re-point a client.

List genie clients

Returns the genie clients in the workspace.

bash

GET /api/agentic/genies/clients

Sample request

shell

curl -X GET https://www.workato.com/api/agentic/genies/clients \
     -H 'Authorization: Bearer <api_token>'

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.

bash

POST /api/agentic/genies/clients

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

shell

curl -X POST https://www.workato.com/api/agentic/genies/clients \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{ "client_name": "HR Concierge Web", "auth": { "type": "api_key" } }'

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.

bash

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

Payload

Name	Type	Description
client_name	string required	The new name for the client.

Sample request

shell

curl -X PUT https://www.workato.com/api/agentic/genies/clients/gincl-AaBGpLGx-HLdsJL \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{ "client_name": "HR Concierge Web v2" }'

Delete a genie client

Deletes a genie client and invalidates its credentials. Detach a genie client to remove it from a genie without deleting it.

bash

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

Sample request

shell

curl -X DELETE https://www.workato.com/api/agentic/genies/clients/gincl-AaBGpLGx-HLdsJL \
     -H 'Authorization: Bearer <api_token>'

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.

bash

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

Sample request

shell

curl -X POST https://www.workato.com/api/agentic/genies/clients/gincl-AaBGpLGx-HLdsJL/regenerate \
     -H 'Authorization: Bearer <api_token>'

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.

bash

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

Payload

Name	Type	Description
genie_client_id	string required	The ID of the client to attach.

Sample request

shell

curl -X POST https://www.workato.com/api/agentic/genies/gin-ZWSMPR4a-TaG7S9/clients \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{ "genie_client_id": "gincl-AaBGpLGx-HLdsJL" }'

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.

bash

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

Sample request

shell

curl -X DELETE https://www.workato.com/api/agentic/genies/gin-ZWSMPR4a-TaG7S9/clients/gincl-AaBGpLGx-HLdsJL \
     -H 'Authorization: Bearer <api_token>'

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

bash

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

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

shell

curl -sS https://www.workato.com/api/agentic/genies/gin-aBC123-xYz789-prod1/guardrails \
  -H 'Authorization: Bearer <api_token>'

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.

bash

PUT /api/agentic/genies/:genie_id/guardrails/policies/:policy_type

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 for more information.

Sample request

shell

curl -X PUT https://www.workato.com/api/agentic/genies/gin-aBC123-xYz789-prod1/guardrails/policies/harmful_content \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "configuration": {
             "filters": [
               { "type": "HATE",      "strength": "HIGH" },
               { "type": "INSULTS",   "strength": "HIGH" },
               { "type": "SEXUAL",    "strength": "HIGH" },
               { "type": "VIOLENCE",  "strength": "MEDIUM" },
               { "type": "MISCONDUCT","strength": "MEDIUM" }
             ]
           }
         }'

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 limits.

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.

bash

GET /api/agentic/genies/guardrails/policies/pii_entities

Sample request

shell

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

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

bash

GET /api/agentic/knowledge_bases

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

shell

curl -X GET https://www.workato.com/api/agentic/knowledge_bases \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "per_page": 10,
           "page": 1,
           "sort_term": "name"
         }'

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.

bash

POST /api/agentic/knowledge_bases

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

shell

curl -X POST https://www.workato.com/api/agentic/knowledge_bases \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "name": "Support FAQs",
           "description": "Knowledge base with frequently asked customer support questions.",
           "folder_id": "7498",
           "source_type": "recipe",
           "data_sources": "zendesk_articles"
         }'

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.

bash

GET /api/agentic/knowledge_bases/:id

Query parameters

Name	Type	Description
id	string required	The ID of the knowledge base you plan to retrieve.

Sample request

shell

curl -X GET https://www.workato.com/api/agentic/knowledge_bases/kb-WSm8kore-blMxrh \
     -H 'Authorization: Bearer <api_token>' \

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.

bash

PUT /api/agentic/knowledge_bases/:id

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

shell

curl -X PUT https://www.workato.com/api/agentic/knowledge_bases/kb-WSm8kore-blMxrh \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "name": "Support FAQs v2",
           "description": "Updated to include billing FAQs in addition to support.",
           "data_sources": {
             "zendesk_articles": true,
             "internal_docs": true
           }
         }'

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.

bash

DELETE /api/agentic/knowledge_bases/:id

Query parameters

Name	Type	Description
id	string required	The ID of the knowledge base you plan to delete.

Sample request

shell

curl -X DELETE https://www.workato.com/api/agentic/knowledge_bases/kb-WSm8kore-blMxrh \
     -H 'Authorization: Bearer <api_token>' \

Sample response

json

{
    "success": "true"
}

Get knowledge base data sources

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

bash

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

Query parameters

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

Sample request

shell

curl -X GET https://www.workato.com/api/agentic/knowledge_bases/kb-WSm8kore-blMxrh/data_sources \
     -H 'Authorization: Bearer <api_token>'

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.

bash

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

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

shell

curl -X GET https://www.workato.com/api/agentic/knowledge_bases/kb-WSm8kore-blMxr/recipes \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "per_page": 10,
           "page": 1,
           "sort_term": "name"
         }'

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

List skills

Returns a list of skills.

bash

GET /api/agentic/skills

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

shell

curl -X GET https://www.workato.com/api/agentic/skills \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "per_page": 10,
           "page": 1,
           "sort_term": "name"
         }'

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 trigger with defined inputs and actions. Call this endpoint with the recipe_id to register the recipe as a skill in Agent Studio.

bash

POST /api/agentic/skills

Payload

Name	Type	Description
recipe_id	integer required	The ID of the recipe to convert into a skill.

Sample request

shell

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

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.

bash

GET /api/agentic/skills/:id

Query parameters

Name	Type	Description
id	string required	The ID of the skill for you plan to retrieve.

Sample request

shell

curl -X GET https://www.workato.com/api/agentic/skills/65039789 \
     -H 'Authorization: Bearer <api_token>' \

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

Last updated:

Agent Studio ​

Rate limits ​

Quick reference ​

Genies ​

List genies ​

Query parameters ​

Sample request ​

Sample response ​

Create a genie ​

Payload ​

Sample request ​

Sample response ​

Update a genie ​

Query parameters ​

Sample request ​

Sample response ​

Get a genie by ID ​

Query parameters ​

Sample request ​

Sample response ​

Delete a genie ​

Query parameters ​

Sample request ​

Sample response ​

Start a genie ​

Query parameters ​

Sample request ​

Sample response ​

Stop a genie ​

Query parameters ​

Sample request ​

Sample response ​

Assign a skill to a genie ​

Query parameters ​

Payload ​

Sample request ​

Sample response ​

Remove a skill from a genie ​

Query parameters ​

Payload ​

Sample request ​

Sample response ​

Assign a knowledge base to a genie ​

Query parameters ​

Payload ​

Sample request ​

Sample response ​

Remove a knowledge base from a genie ​

Query parameters ​

Payload ​

Sample request ​

Sample response ​

Assign a user group to a genie ​

Query parameters ​

Payload ​

Sample request ​

Sample response ​

Remove a user group from a genie ​

Query parameters ​

Payload ​

Sample request ​

Sample response ​

Genie clients ​

List genie clients ​

Sample request ​

Sample response ​

Create a genie client ​

Payload ​

Sample request ​

Sample response ​

Update a genie client ​

Payload ​

Sample request ​

Delete a genie client ​

Sample request ​

Regenerate a genie client key ​

Sample request ​

Sample response ​

Attach a client to a genie ​

Payload ​

Agent Studio

Rate limits

Quick reference

Genies

List genies

Query parameters

Sample request

Sample response

Create a genie

Payload

Sample request

Sample response

Update a genie

Query parameters

Sample request

Sample response

Get a genie by ID

Query parameters

Sample request

Sample response

Delete a genie

Query parameters

Sample request

Sample response

Start a genie

Query parameters

Sample request

Sample response

Stop a genie

Query parameters

Sample request

Sample response

Assign a skill to a genie

Query parameters

Payload

Sample request

Sample response

Remove a skill from a genie

Query parameters

Payload

Sample request

Sample response

Assign a knowledge base to a genie

Query parameters

Payload

Sample request

Sample response

Remove a knowledge base from a genie

Query parameters

Payload

Sample request

Sample response

Assign a user group to a genie

Query parameters

Payload

Sample request

Sample response

Remove a user group from a genie

Query parameters

Payload

Sample request

Sample response

Genie clients

List genie clients

Sample request

Sample response

Create a genie client

Payload

Sample request

Sample response

Update a genie client

Payload

Sample request

Delete a genie client

Sample request

Regenerate a genie client key

Sample request

Sample response

Attach a client to a genie

Payload