# Add an action

`POST https://api.chat-data.com/api/v2/add-action`

Canonical: https://www.chat-data.com/api-reference/add-action

## Authentication

Send an API key as a Bearer token: `Authorization: Bearer $CHAT_DATA_API_KEY`. Workspace keys reach every chatbot in the workspace; chatbot-scoped keys reach only their chatbot. Keep keys on the server.

## Description

Adds a new action to the specified chatbot. Top-level fields are checked (see the 400 response); `headers`, `pathParams`, `queryParams` and `bodyParams` items are stored as sent, without schema checks. An `api` action is also tested before it is saved: Chat Data sends a request to its `url`, filling each parameter with its `example` value, and rejects the action if that request fails.

`mcp` actions cannot be added with this endpoint. A new action is enabled unless `enabled` is `false`; enabled actions count toward your plan's action limit.

## Request body (`application/json`)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| chatbotId | string | yes | The ID of the chatbot to which the action will be added. |
| action | object | yes | The action to add. |
| action.name | string | yes | The name of the action. Only letters, numbers, underscores and hyphens are allowed. |
| action.description | string | yes | Description of when to trigger the action. |
| action.type | string | yes | The type of action. One of: `api`, `search`, `lead`, `button`. |
| action.url | string | no | For API actions, the URL to call. Use `{name}` placeholders for path parameters. |
| action.method | string | no | For API actions, the HTTP method. One of: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`. |
| action.headers | array of object | no | For API actions, the HTTP headers of the request. |
| action.headers[].name | string | yes | The name of the header. |
| action.headers[].value | string | yes | The value of the header. |
| action.pathParams | array of object | no | For API actions, the URL path parameters. |
| action.pathParams[].name | string | yes | The name of the parameter. |
| action.pathParams[].type | string | yes | The data type of the parameter. One of: `string`, `number`, `boolean`, `array`, `object`. |
| action.pathParams[].description | string | yes | Description of the parameter. |
| action.pathParams[].required | boolean | yes | Whether this parameter is required. |
| action.pathParams[].static | boolean | no | Indicates whether the parameter is static. A static parameter always sends its example value instead of a value generated by the chatbot. |
| action.pathParams[].example | string | no | Stringified example value. For non-string types (number, boolean, array, object), the value should be JSON-parseable. |
| action.pathParams[].items | object | no | For array types, describes the array items. |
| action.pathParams[].items.name | string | yes | The name of the property. |
| action.pathParams[].items.type | string | yes | The data type of the property. One of: `string`, `number`, `boolean`, `array`, `object`. |
| action.pathParams[].items.description | string | yes | Description of the property. |
| action.pathParams[].items.required | boolean | no | Whether this property is required. |
| action.pathParams[].items.items | object | no |  |
| action.pathParams[].items.properties | array of object | no | For object types, describes the object's properties. |
| action.pathParams[].properties | array of object | no | For object types, describes the object's properties. |
| action.pathParams[].properties[].name | string | yes | The name of the property. |
| action.pathParams[].properties[].type | string | yes | The data type of the property. One of: `string`, `number`, `boolean`, `array`, `object`. |
| action.pathParams[].properties[].description | string | yes | Description of the property. |
| action.pathParams[].properties[].required | boolean | no | Whether this property is required. |
| action.pathParams[].properties[].items | object | no |  |
| action.pathParams[].properties[].properties | array of object | no | For object types, describes the object's properties. |
| action.queryParams | array of object | no | For API actions, the URL query parameters. |
| action.queryParams[].name | string | yes | The name of the parameter. |
| action.queryParams[].type | string | yes | The data type of the parameter. One of: `string`, `number`, `boolean`, `array`, `object`. |
| action.queryParams[].description | string | yes | Description of the parameter. |
| action.queryParams[].required | boolean | yes | Whether this parameter is required. |
| action.queryParams[].static | boolean | no | Indicates whether the parameter is static. A static parameter always sends its example value instead of a value generated by the chatbot. |
| action.queryParams[].example | string | no | Stringified example value. For non-string types (number, boolean, array, object), the value should be JSON-parseable. |
| action.queryParams[].items | object | no | For array types, describes the array items. |
| action.queryParams[].items.name | string | yes | The name of the property. |
| action.queryParams[].items.type | string | yes | The data type of the property. One of: `string`, `number`, `boolean`, `array`, `object`. |
| action.queryParams[].items.description | string | yes | Description of the property. |
| action.queryParams[].items.required | boolean | no | Whether this property is required. |
| action.queryParams[].items.items | object | no |  |
| action.queryParams[].items.properties | array of object | no | For object types, describes the object's properties. |
| action.queryParams[].properties | array of object | no | For object types, describes the object's properties. |
| action.queryParams[].properties[].name | string | yes | The name of the property. |
| action.queryParams[].properties[].type | string | yes | The data type of the property. One of: `string`, `number`, `boolean`, `array`, `object`. |
| action.queryParams[].properties[].description | string | yes | Description of the property. |
| action.queryParams[].properties[].required | boolean | no | Whether this property is required. |
| action.queryParams[].properties[].items | object | no |  |
| action.queryParams[].properties[].properties | array of object | no | For object types, describes the object's properties. |
| action.bodyParams | array of object | no | For API actions, the request body parameters. |
| action.bodyParams[].name | string | yes | The name of the parameter. |
| action.bodyParams[].type | string | yes | The data type of the parameter. One of: `string`, `number`, `boolean`, `array`, `object`. |
| action.bodyParams[].description | string | yes | Description of the parameter. |
| action.bodyParams[].required | boolean | yes | Whether this parameter is required. |
| action.bodyParams[].static | boolean | no | Indicates whether the parameter is static. A static parameter always sends its example value instead of a value generated by the chatbot. |
| action.bodyParams[].example | string | no | Stringified example value. For non-string types (number, boolean, array, object), the value should be JSON-parseable. |
| action.bodyParams[].items | object | no | For array types, describes the array items. |
| action.bodyParams[].items.name | string | yes | The name of the property. |
| action.bodyParams[].items.type | string | yes | The data type of the property. One of: `string`, `number`, `boolean`, `array`, `object`. |
| action.bodyParams[].items.description | string | yes | Description of the property. |
| action.bodyParams[].items.required | boolean | no | Whether this property is required. |
| action.bodyParams[].items.items | object | no |  |
| action.bodyParams[].items.properties | array of object | no | For object types, describes the object's properties. |
| action.bodyParams[].properties | array of object | no | For object types, describes the object's properties. |
| action.bodyParams[].properties[].name | string | yes | The name of the property. |
| action.bodyParams[].properties[].type | string | yes | The data type of the property. One of: `string`, `number`, `boolean`, `array`, `object`. |
| action.bodyParams[].properties[].description | string | yes | Description of the property. |
| action.bodyParams[].properties[].required | boolean | no | Whether this property is required. |
| action.bodyParams[].properties[].items | object | no |  |
| action.bodyParams[].properties[].properties | array of object | no | For object types, describes the object's properties. |
| action.includeImages | boolean | no | For search actions, whether to include images in the results. Defaults to `true`. |
| action.prioritizeRecentResults | boolean | no | For search actions, whether to prioritize recent results. |
| action.enableDateRestriction | boolean | no | For search actions, whether to enable the date restriction. |
| action.includedDomains | array of string | no | For search actions, the domains to restrict the web search to, as full URLs (for example `https://www.example.com`). Leave empty to search all domains. |
| action.link | string | no | For button actions, the link the button opens. Required for button actions. |
| action.label | string | no | For button actions, the button label. Required for button actions. |
| action.enabled | boolean | no | Whether the action is enabled. New actions are enabled unless this is `false`. |

## Example request

```bash
curl 'https://api.chat-data.com/api/v2/add-action' \
  -H "Authorization: Bearer $CHAT_DATA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "chatbotId": "6650f1c2a9e4b83d2c7a1f05",
  "action": {
    "name": "stockPriceLookup",
    "description": "The user wants to know the current stock price of a company",
    "type": "search"
  }
}'
```

## Example response (200)

```json
{
  "status": "success",
  "action": {
    "index": 0,
    "name": "stockPriceLookup",
    "description": "The user wants to know the current stock price of a company",
    "type": "api",
    "url": "https://api.example.com/stocks/{symbol}/price",
    "method": "GET",
    "headers": [
      {
        "name": "Authorization",
        "value": "Bearer stk_live_3f9a2c7d1e"
      }
    ],
    "pathParams": [
      {
        "name": "symbol",
        "type": "string",
        "description": "The stock ticker symbol to look up.",
        "required": true,
        "example": "AAPL"
      }
    ],
    "return_file": false
  }
}
```

## Responses

| Status | Description |
| --- | --- |
| 200 | Action successfully added. |
| 400 | The action was rejected. For example: `chatbotId` or `action` is missing, a required field is missing, a field is not allowed or has the wrong type, `name` contains characters other than letters, numbers, underscores and hyphens or is already used, `type` is `mcp` or not supported, a button action lacks `label` or `link`, `includedDomains` is not an array of valid URLs, the chatbot already has the maximum number of actions or the plan's action limit is reached, or the test request of an `api` action failed. A failed test request may return the test result object instead of `{ status, message }`. |
| 401 | Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which. |
| 403 | The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace. |
| 429 | The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying. |