Skip to main content
POST /workflows 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 — what it says and how it behaves.
  3. Optionally add custom statuses/fields or custom tools it can call.
  4. 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

FieldTypeRequiredDescription
namestringYesAgent name. Used for the idempotency check
goal_typestringYesOne of: appointment, sale, qualification, information, payment_link, support, custom
statusesarrayYesNon-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
descriptionstringNoAgent description
global_promptstringNoBase prompt. You can also set this later via PATCH /workflows/:id/prompt
languagestringNoDefault es
channelsarrayNoChannels to enable, e.g. ["whatsapp", "email"]. Default ["whatsapp"]
fieldsarrayNoCustom lead fields to collect (see Update Structure for the shape)

​
statuses[] shape

FieldTypeRequiredDescription
keystringYesStable identifier for the status
namestringYesDisplay label (label also accepted)
is_initialbooleanNoMarks the funnel’s entry status
is_terminalbooleanNoMarks a funnel-ending status
sort_orderintegerNoDefaults 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"
  • "statuses must be a non-empty array"
  • "each status needs a key and a name"

​
401 — Authentication error

See Authentication.

​
500 — Internal server error

Last modified on July 10, 2026