Create Agent

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

Create the agent (this endpoint). It’s born paused.
Set its prompt — what it says and how it behaves.
Optionally add custom statuses/fields or custom tools it can call.
Activate it 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 the values in Available goals
`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 for the shape)

Available goals

`goal_type`	Expected outcome	Notes
`appointment`	Book a meeting	Enables calendar capabilities.
`payment_link`	Send a payment link and complete payment	The integration that creates or supplies the link must be configured.
`qualification`	Qualify the lead from collected data	Pair it with fields and stages that express the criteria.
`information`	Answer questions	Usually depends on a knowledge base.
`support`	Resolve or escalate support requests	Define explicit escalation rules.
`document_collection`	Request and verify documents	The dashboard shows a Documents section for this goal.
`quote`	Generate a quote from a catalog	Requires an assigned catalog.
`custom`	Achieve an operator-written objective	Does not enable calendar tools.
`sale`	Complete a sale	API-compatible value; it is not a preset in the current dashboard picker.

Onboarding also offers Qualify, then book. That option is stored as appointment with a qualification pipeline and rules; do not send qualify_then_book to this public endpoint.

The `custom` goal

Use custom when the agent’s objective is not one of the preset goals — debt collection, client win-back, post-sale follow-up, or surveys. The agent pursues an objective written in the operator’s own words, configured in the Dashboard under Agent settings → Goal and stored as config.goal_statement. It accepts up to 600 characters and should describe the outcome, not the procedure. Two things to know:

A custom agent does not schedule meetings — the calendar tools are not available to it. If the goal ends in a booked meeting, use appointment.
You must send statuses as with every other goal. This endpoint does not infer the pipeline; a typical custom setup can use new → contacted → engaged → converted → lost with transition instructions adapted to the written outcome.

`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

{
  "success": true,
  "workflow_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "created"
}

`200` — Already existed (idempotent replay)

{
  "success": true,
  "workflow_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "existed"
}

`400` — Validation error

{
  "error": "Invalid input",
  "message": "name is required"
}

Other validation errors:

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

`401` — Authentication error

See Authentication.

Quick Start

WhatsApp

Agents

Assistant

Advanced

API Reference

Leads

Agents

Workflow Tools

Client Tools

Groups

Campaigns

Conversions

Reports

Conversations

Tags

Messages

Background Jobs

Meetings

Team

Processors

Create Agent

Request Body

Available goals

The `custom` goal

`statuses[]` shape

Responses

`201` — Agent created

`200` — Already existed (idempotent replay)

`400` — Validation error

`401` — Authentication error

`500` — Internal server error

​Request Body

​Available goals

​The custom goal

​statuses[] shape

​Responses

​201 — Agent created

​200 — Already existed (idempotent replay)

​400 — Validation error

​401 — Authentication error

​500 — Internal server error

Request Body

Available goals

The `custom` goal

`statuses[]` shape

Responses

`201` — Agent created

`200` — Already existed (idempotent replay)

`400` — Validation error

`401` — Authentication error

`500` — Internal server error