> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nedzo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a custom action

> Create a custom action that calls your own endpoint during a conversation.

> [!NOTE]
>
> This endpoint is for the VIP plan only. Other plans get a `403`. See [Plan access](https://docs.nedzo.ai/api-reference/introduction.md#plan-access).

A custom action calls your endpoint during a conversation. It belongs to the workspace, so one action can serve many agents. See [Actions](https://docs.nedzo.ai/agents/actions.md) for the request your endpoint gets. After you create it, [attach it to an agent](https://docs.nedzo.ai/api-reference/agents/custom-actions/attach.md). Returns `201`.

## Body

**workspaceId** `string` *required*

The workspace. Required.

**name** `string` *required*

The action's name.

**condition** `string`

When the agent should use it.

**method** `string` *required*

`GET`, `POST`, `PUT`, `PATCH` or `DELETE`.

**url** `string` *required*

Your endpoint. It must be a public address. We refuse private and internal addresses.

**parameters** `object[]`

What the agent fills in from the conversation. Each has `name`, `description`, `type` (`string`, `number` or `boolean`) and `required`.

**isActive** `boolean`

Whether agents can use it.

**headers** `object`

Headers to send with every call. A name may only use letters, digits and `!#$%&'*+-.^_`|\~`, a value can't hold a line break, and you can't set `Host`, `Content-Length`, `Transfer-Encoding`or`Connection`.</ParamField> <ParamField body="authType" type="string">`bearer`, `api\_key`or`basic`.</ParamField> <ParamField body="authValue" type="string">The secret for `authType`. Needed when you set `authType\`.

> [!WARNING]
>
> `authValue` and header values are write only. We never send them back. A response shows `hasAuth` and the header names.

```bash cURL theme={null}
curl -X POST "https://api.nedzo.ai/v1/custom-actions" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "workspaceId": "789e4567-e89b-12d3-a456-426614174000",
      "name": "Check zip code",
      "condition": "The caller gives a zip code",
      "method": "POST",
      "url": "https://example.com/coverage",
      "parameters": [{ "name": "zip", "type": "string", "required": true }],
      "headers": { "X-Team": "sales" },
      "authType": "bearer",
      "authValue": "YOUR_ENDPOINT_TOKEN"
    }'
```

```json 201 theme={null}
{
  "id": "5a3c1e2b-8d7f-4b6a-9c0e-1f2a3b4c5d6e",
  "workspaceId": "789e4567-e89b-12d3-a456-426614174000",
  "name": "Check zip code",
  "condition": "The caller gives a zip code",
  "method": "POST",
  "url": "https://example.com/coverage",
  "parameters": [{ "name": "zip", "type": "string", "required": true }],
  "isActive": true,
  "authType": "bearer",
  "hasAuth": true,
  "headerNames": ["X-Team"],
  "createdAt": "2026-10-11T10:00:00Z",
  "updatedAt": "2026-10-11T10:00:00Z"
}
```

## Errors

| Status | When |
| - | - |
| `400` | A field is missing or wrong, the URL is not a public address, `authType` came without `authValue`, or a header is not allowed. |
| `400` | `workspaceId is required`: `workspaceId` is missing. |
| `404` | The workspace is not in your API key's scope. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.