Create a custom action

POST

custom-actions

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

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

This endpoint is for the VIP plan only. Other plans get a 403. See 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 for the request your endpoint gets. After you create it, attach it to an agent. Returns 201.

Body

string

required

The workspace. Required.

string

required

The action’s name.

string

When the agent should use it.

string

required

GET, POST, PUT, PATCH or DELETE.

string

required

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

object[]

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

boolean

Whether agents can use it.

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-EncodingorConnection.</ParamField> <ParamField body="authType" type="string">bearer, api_keyorbasic.</ParamField> <ParamField body="authValue" type="string">The secret for authType. Needed when you set authType`.

authValue and header values are write only. We never send them back. A response shows hasAuth and the header names.

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

{
  "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.

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

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

API Reference

Workspaces

Agents

Phone Numbers

Contacts

Knowledge

Templates

Campaigns

Workflows

Conversations

Create a custom action

Body

Errors