> ## 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.

# Attach a custom action

> Let an agent use a custom action from its workspace.

> [!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).

The action must be in the agent's workspace. Returns `201` with the action.

## Path Parameters

**agentId** `string` *required*

Agent UUID

## Body

**customActionId** `string` *required*

The custom action to attach.

```bash cURL theme={null}
curl -X POST "https://api.nedzo.ai/v1/agents/123e4567-e89b-12d3-a456-426614174000/custom-actions" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "customActionId": "5a3c1e2b-8d7f-4b6a-9c0e-1f2a3b4c5d6e" }'
```

```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` | An id is not a valid UUID. |
| `404` | The action or agent is not in your API key's scope, or the action is in another workspace than the agent. |
| `409` | The action is already attached to the agent. |


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