AI Actions

Manage your AI Agent's AI Actions via the API.

Optional example checks

Preview JSONPath matches. Check root, field, array-index and wildcard paths against supplied JSON. This does not run an Action or save conversation memory.
Check a sample MCP connection. Initialize and list tools on the Cloudflare documentation or Microsoft Learn endpoint only. No sign-in or tool execution is performed.

In a compatible browser, these checks are also available as site tools. The links open the standard forms.

AI Actions

AI Actions extend your AI Agent’s capabilities beyond answering questions from the Knowledge Base. They let you define triggered behaviors — things the AI should do when it detects specific situations in a conversation.

What AI Actions do:

HTTP Request Actions — Call external APIs when triggered. For example, check order status in your backend, create a support ticket, or look up account information — all during the conversation.
MCP Actions: Connect to Model Context Protocol servers for advanced tool integrations (e.g., Shopify product lookups, custom database queries).

Typical use cases:

Look up real-time information (order status, account details, inventory) from your backend systems during conversations
Create tickets, update CRM records, or trigger workflows in external systems based on conversation context
Provide personalized recommendations by querying your product catalog

Each action has a name, description (for HTTP Request Actions, the description tells the AI when to trigger it), and a type-specific configuration. Actions can be enabled/disabled individually via the API. Actions are created and fully configured in the Quickchat Dashboard — the API provides list, update (enable/disable), and delete operations, plus dedicated endpoints to create and configure MCP Actions.

List All AI Actions

Scope: read_all

GET https://app.quickchat.ai/v1/api/ai_actions

Shell
Python

curl https://app.quickchat.ai/v1/api/ai_actions \
  -H 'Authorization: Bearer <API_TOKEN>'

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/ai_actions",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Response 200 OK

[
  {
    "id": 1,
    "name": "Check Order Status",
    "description": "Look up order status when customer asks about their order.",
    "is_active": true,
    "type": "http_request",
    "icon": null,
    "icon_color": null,
    "is_valid": true
  }
]

Field	Description
`id` integer	AI Action identifier
`name` string	Display name
`description` string	When the action triggers
`is_active` boolean	Whether enabled
`type` string	`"http_request"`, `"remote_mcp"`, `"shopify_remote_mcp"`, or `"knowledge_base"`
`icon` string or null	Icon identifier
`icon_color` string or null	Icon color
`is_valid` boolean	Whether properly configured

Update AI Action

Scope: write_all

PATCH https://app.quickchat.ai/v1/api/ai_actions/{action_id}

Request Body

Parameter	Description
`is_active` boolean	Enable/disable the action
`icon` string	Icon identifier (max 200 chars)
`icon_color` string	Icon color (max 50 chars)

Shell
Python

curl -X PATCH https://app.quickchat.ai/v1/api/ai_actions/1 \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"is_active": false}'

import requests

response = requests.patch(
    url="https://app.quickchat.ai/v1/api/ai_actions/1",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={"is_active": False},
)
data = response.json()

Response 200 OK — Returns the updated AI Action snapshot.

Delete AI Action

Scope: write_all

DELETE https://app.quickchat.ai/v1/api/ai_actions/{action_id}

Shell
Python

curl -X DELETE https://app.quickchat.ai/v1/api/ai_actions/1 \
  -H 'Authorization: Bearer <API_TOKEN>'

import requests

response = requests.delete(
    url="https://app.quickchat.ai/v1/api/ai_actions/1",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)

Response 200 OK (empty body)

Create MCP Action

Scope: write_all

POST https://app.quickchat.ai/v1/api/ai_actions/remote_mcp

Connects a remote MCP server to your AI Agent as an MCP Action. Requires an API token with the write_all scope (API tokens require the Business plan or higher).

Request Body

Parameter	Description
`remote_mcp_url` string, required	The MCP server’s URL. Must use `https://`; URLs that resolve to private or internal network addresses are rejected
`headers` array, required	Connection headers sent to the server, e.g. a static `Authorization` token. Each entry is `{"id", "name", "value"}` — pick any unique string as `id`. Send `[]` if the server needs none
`allowed_tools` array, required	Per-tool switches, each `{"name", "is_active"}`. Send `[]` to leave tool availability to `default_tool_is_active`
`name` string	Display name shown in the Actions list (max 100 chars). Defaults to a label derived from the server’s host
`description` string	Description shown in the Actions list (max 2500 chars)
`icon` string	Icon identifier (max 200 chars)
`icon_color` string	Icon color (max 50 chars)

name and description are operator-facing labels: they identify the action in the dashboard, and the AI never reads them. The AI works from the tool descriptions the MCP server itself publishes.

Shell
Python

curl -X POST https://app.quickchat.ai/v1/api/ai_actions/remote_mcp \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "remote_mcp_url": "https://mcp.example.com/mcp",
    "headers": [
      {"id": "h-1", "name": "Authorization", "value": "Bearer <SERVER_TOKEN>"}
    ],
    "allowed_tools": [],
    "name": "Example MCP"
  }'

import requests

response = requests.post(
    url="https://app.quickchat.ai/v1/api/ai_actions/remote_mcp",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "remote_mcp_url": "https://mcp.example.com/mcp",
        "headers": [
            {"id": "h-1", "name": "Authorization", "value": "Bearer <SERVER_TOKEN>"}
        ],
        "allowed_tools": [],
        "name": "Example MCP",
    },
)
data = response.json()

Response 201 Created

{
  "id": 2,
  "name": "Example MCP",
  "description": "Connected MCP server",
  "is_active": false,
  "type": "remote_mcp",
  "icon": "FaMixcloud",
  "icon_color": "#EF4444",
  "is_valid": true,
  "validation_issues": [],
  "remote_mcp_url": "https://mcp.example.com/mcp",
  "remote_mcp_auth_token": "",
  "default_tool_is_active": true,
  "allowed_tools": [],
  "headers": [
    {"id": 10, "name": "Authorization", "value": "Bearer <SERVER_TOKEN>"}
  ],
  "oauth": null,
  "recommended_tools": []
}

Field	Description
`remote_mcp_url` string	The connected MCP server’s URL
`default_tool_is_active` boolean	Whether tools not listed in `allowed_tools` may be used
`allowed_tools` array	Per-tool switches, `{"name", "is_active"}`
`headers` array	Stored connection headers
`remote_mcp_auth_token` string or null	Legacy static-token field. It cannot be set through this API — pass credentials via `headers` instead
`oauth` object or null	Authorization status for servers connected with an OAuth sign-in (`null` otherwise)
`recommended_tools` array	Tool names Quickchat recommends for servers with a curated profile (read-only)
`validation_issues` array	Names of failed configuration checks; empty when `is_valid` is `true`

The remaining fields match List All AI Actions.

The action is created with is_active: false. For servers without a curated Quickchat profile it also starts with default_tool_is_active: true, so every tool discovered at reply time is allowed until you restrict it. To switch the action on, use the Update AI Action endpoint above: PATCH /v1/api/ai_actions/{action_id} with {"is_active": true}.

Get MCP Action Configuration

Scope: read_all

GET https://app.quickchat.ai/v1/api/ai_actions/{action_id}/remote_mcp

Shell
Python

curl https://app.quickchat.ai/v1/api/ai_actions/2/remote_mcp \
  -H 'Authorization: Bearer <API_TOKEN>'

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/ai_actions/2/remote_mcp",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Response 200 OK — Returns the MCP-specific configuration, in the same shape as the create response above.

Update MCP Action Configuration

Scope: write_all

PATCH https://app.quickchat.ai/v1/api/ai_actions/{action_id}/remote_mcp

All fields are optional; only the fields you send change.

Request Body

Parameter	Description
`remote_mcp_url` string	New server URL (validated like on create). Changing the URL of a server connected with OAuth clears the stored authorization and switches the action off
`headers` array	Replaces the connection headers
`allowed_tools` array	Replaces the per-tool switches, each `{"name", "is_active"}`
`default_tool_is_active` boolean	Whether tools not listed in `allowed_tools` may be used
`name` string	Display name (max 100 chars)
`description` string	Description shown in the Actions list (max 2500 chars)

Shell
Python

curl -X PATCH https://app.quickchat.ai/v1/api/ai_actions/2/remote_mcp \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "allowed_tools": [
      {"name": "search_docs", "is_active": true},
      {"name": "delete_page", "is_active": false}
    ],
    "default_tool_is_active": false
  }'

import requests

response = requests.patch(
    url="https://app.quickchat.ai/v1/api/ai_actions/2/remote_mcp",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "allowed_tools": [
            {"name": "search_docs", "is_active": True},
            {"name": "delete_page", "is_active": False},
        ],
        "default_tool_is_active": False,
    },
)
data = response.json()

Response 200 OK — Returns the updated MCP Action, in the same shape as the create response.

Connection testing and tool discovery — the dashboard’s Connect probe — are not available on the public API. The dashboard runs the probe automatically when you connect or reconnect a server, and servers protected by OAuth must complete their authorization in the dashboard; the oauth field in the responses above reports that status.

AI Actions

Optional example checks

AI Actions

List All AI Actions

Update AI Action

Delete AI Action

Create MCP Action

Get MCP Action Configuration

Update MCP Action Configuration

Get started

AI Agent

Actions

Conversations

Channels

Your website

Helpdesk & CRM

Messaging apps

Account & billing

Get started

Configuration

Knowledge Base

Conversations