AI Actions

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

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

Python

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

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

Python

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

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

Python

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

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

Python

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

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

Python

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

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

Python

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.

Note

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.

---