Skip to main content
POST
Create an 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:
  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.

Customer content limit

Each task has a maximum of 20,000 customer tokens, including its shared identity when it belongs to an agent. Nexor’s internal instructions do not use this allowance, but a task that takes calls also has a 28,000-token call limit that includes them. The limit covers the task configuration described in Your content limit. The API returns 422 CUSTOMER_PROMPT_TOO_LARGE when the resulting customer configuration exceeds this limit. If a call would exceed the call limit, it returns 503 VOICE_PROMPT_CAPACITY_EXCEEDED with capacity.tokens and capacity.limit. Shorten the prompt or instructions by at least capacity.tokens - capacity.limit tokens. Creation can involve several writes, so read the current task state before retrying a failed request. If the task’s call flow would exceed 390,000 bytes, the API returns 422 CONVERSATION_FLOW_TOO_LARGE with projected_bytes, limit, and the parts that drive its size. If the call flow cannot be built from the configuration, it returns 422 CONVERSATION_FLOW_CONFIGURATION_INVALID with a reason.

Request Body

Available goals

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

Responses

201 — Agent created

If a select or multiselect field in fields had no usable option, Nexor saves it as text and adds coerced_fields to the response. Each entry has the field’s key, requested_type, saved_type (text), reason (no_options), and a hint. To make the field a list, send it to Update Structure with type set to select or multiselect and a non-empty options array.

200 — Already existed (idempotent replay)

400 — Validation error

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.

503 — Validation unavailable

503 VOICE_PROMPT_BUDGET_UNAVAILABLE means Nexor could not complete the capacity check. Retry when validation is available.

Authorizations

X-API-Key
string
header
required

API key for authentication. Keys are prefixed with nxr_live_. To work inside a sub-account with a main account key, also send the optional X-Nexor-Sub-Account-Id header.

Body

application/json
name
string
required
Minimum string length: 1
goal_type
enum<string>
required
Available options:
appointment,
sale,
qualification,
information,
payment_link,
support,
custom,
quote,
document_collection
statuses
object[]
required
Minimum array length: 1
master_workflow_id
string<uuid> | null
language
enum<string>
Available options:
es-CL,
es-MX,
es-PE,
es-CO,
es-AR,
es-US,
en-US,
en-AU,
ko-KR,
pt-BR,
fr-FR,
ar-AE,
zh-CN,
vi-VN,
th-TH
agent_name
string | null
Maximum string length: 200
agent_role
string | null
Maximum string length: 200
company_name
string | null
Maximum string length: 200
begin_message
string | null
Maximum string length: 1000
timezone
string

Valid IANA time-zone name.

region_style
enum<string>
Available options:
cl,
mx,
pe,
co,
ar,
es,
latam,
us,
au,
gb,
in,
nz,
kr,
br,
pt
global_prompt
string
channels
enum<string>[]
Available options:
whatsapp,
call,
voice,
retell,
email,
sms
fields
object[]
description
string | null

Response

Successful response.

success
enum<boolean>
required
Available options:
true
workflow_id
string<uuid>
required
master_workflow_id
string<uuid> | null
required
status
enum<string>
required
Available options:
existed
Last modified on November 12, 2026