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

# Create Agent

<span class="badge--post">POST</span> <code class="endpoint-url">/workflows</code>

Create a new agent (funnel + statuses) from scratch — entirely via API. This is the first step in the API-first agent lifecycle:

1. **Create** the agent (this endpoint). It's born **paused**.
2. [Set its prompt](/docs/en/api/workflows/set-workflow-prompt) — what it says and how it behaves.
3. Optionally [add custom statuses/fields](/docs/en/api/workflows/update-workflow-structure) or [custom tools](/docs/en/api/workflow-tools/create-workflow-tool) it can call.
4. [Activate it](/docs/en/api/workflows/update-workflow) by setting `is_paused: false`.

**Idempotent.** If an agent with the same `name` already exists on your account, this returns the existing one (`status: "existed"`) instead of creating a duplicate — safe to retry.

## Request Body

| Field           | Type   | Required | Description                                                                                                                                                  |
| --------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`          | string | **Yes**  | Agent name. Used for the idempotency check                                                                                                                   |
| `goal_type`     | string | **Yes**  | One of: `appointment`, `sale`, `qualification`, `information`, `payment_link`, `support`, `custom`                                                           |
| `statuses`      | array  | **Yes**  | Non-empty array of funnel statuses (see below). If none is marked `is_initial`, the first one is used; if none is marked `is_terminal`, the last one is used |
| `description`   | string | No       | Agent description                                                                                                                                            |
| `global_prompt` | string | No       | Base prompt. You can also set this later via `PATCH /workflows/:id/prompt`                                                                                   |
| `language`      | string | No       | Default `es`                                                                                                                                                 |
| `channels`      | array  | No       | Channels to enable, e.g. `["whatsapp", "email"]`. Default `["whatsapp"]`                                                                                     |
| `fields`        | array  | No       | Custom lead fields to collect (see [Update Structure](/docs/en/api/workflows/update-workflow-structure) for the shape)                                       |

### `statuses[]` shape

| Field         | Type    | Required | Description                           |
| ------------- | ------- | -------- | ------------------------------------- |
| `key`         | string  | **Yes**  | Stable identifier for the status      |
| `name`        | string  | **Yes**  | Display label (`label` also accepted) |
| `is_initial`  | boolean | No       | Marks the funnel's entry status       |
| `is_terminal` | boolean | No       | Marks a funnel-ending status          |
| `sort_order`  | integer | No       | Defaults to array index               |

## Responses

### `201` — Agent created

```json theme={null}
{
  "success": true,
  "workflow_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "created"
}
```

### `200` — Already existed (idempotent replay)

```json theme={null}
{
  "success": true,
  "workflow_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "existed"
}
```

### `400` — Validation error

```json theme={null}
{
  "error": "Invalid input",
  "message": "name is required"
}
```

Other validation errors:

* `"goal_type must be one of: appointment, sale, qualification, information, payment_link, support, custom"`
* `"statuses must be a non-empty array"`
* `"each status needs a key and a name"`

### `401` — Authentication error

See [Authentication](/docs/en/api/authentication).

### `500` — Internal server error