# AI Actions

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

## 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](/ai-agent/actions/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](https://app.quickchat.ai/) — the API provides list, update (enable/disable), and delete operations, plus dedicated endpoints to create and configure [MCP Actions](/ai-agent/actions/mcp-actions/).

### List All AI Actions

**Scope: read_all**

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

**Shell**

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

**Python**

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

```json
[
  {
    "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` <br/> integer | AI Action identifier |
| `name` <br/> string | Display name |
| `description` <br/> string | When the action triggers |
| `is_active` <br/> boolean | Whether enabled |
| `type` <br/> string | `"http_request"`, `"remote_mcp"`, `"shopify_remote_mcp"`, or `"knowledge_base"` |
| `icon` <br/> string or null | Icon identifier |
| `icon_color` <br/> string or null | Icon color |
| `is_valid` <br/> 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` <br/> boolean | Enable/disable the action |
| `icon` <br/> string | Icon identifier (max 200 chars) |
| `icon_color` <br/> string | Icon color (max 50 chars) |

**Shell**

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

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

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

**Python**

```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](/ai-agent/actions/mcp-actions/). Requires an API token with the `write_all` scope (API tokens require the **Business plan** or higher).

**Request Body**

| Parameter | Description |
|-----------|-------------|
| `remote_mcp_url` <br/> string, required | The MCP server's URL. Must use `https://`; URLs that resolve to private or internal network addresses are rejected |
| `headers` <br/> 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` <br/> array, required | Per-tool switches, each `{"name", "is_active"}`. Send `[]` to leave tool availability to `default_tool_is_active` |
| `name` <br/> string | Display name shown in the Actions list (max 100 chars). Defaults to a label derived from the server's host |
| `description` <br/> string | Description shown in the Actions list (max 2500 chars) |
| `icon` <br/> string | Icon identifier (max 200 chars) |
| `icon_color` <br/> 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**

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

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

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

The remaining fields match [List All AI Actions](#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](#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**

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

**Python**

```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` <br/> 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` <br/> array | Replaces the connection headers |
| `allowed_tools` <br/> array | Replaces the per-tool switches, each `{"name", "is_active"}` |
| `default_tool_is_active` <br/> boolean | Whether tools not listed in `allowed_tools` may be used |
| `name` <br/> string | Display name (max 100 chars) |
| `description` <br/> string | Description shown in the Actions list (max 2500 chars) |

**Shell**

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

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

---