Skip to main content
POST
Generate an agent from a prompt
Starts asynchronous generation of a new inbound agent and its first flow from a natural-language prompt. Send a unique Idempotency-Key with every logical request. Repeating the same request with the same key returns the existing generation instead of creating another agent. Reusing the key with different request data returns an idempotency conflict. The initial response includes a generationId and a Location header. Poll that location until the status is completed or failed.
Store the idempotency key until generation reaches a terminal status. Retrying a failed generation with the same request and key safely reuses its reserved agent and flow instead of provisioning duplicates.

Generation statuses

Only users with permission to edit agent design in the selected organization can generate an agent.

Authorizations

X-Authorization
string
header
required

Headers

Idempotency-Key
string
required

A unique key for this logical generation request. Maximum 128 characters.

Required string length: 1 - 128

Body

application/json
orgId
string
required

Organization in which to create the agent

Required string length: 1 - 128
agentName
string
required

Name for the generated agent

Required string length: 1 - 50
source
object
required
timezone
string

Valid IANA timezone. Defaults to UTC.

Required string length: 1 - 64
Example:

"America/New_York"

Response

The idempotent request already completed

generationId
string
required
Pattern: ^gen_[a-f0-9]{40}$
status
enum<string>
required
Available options:
queued,
generating,
completed,
failed
createdAt
string<date-time>
required
updatedAt
string<date-time>
required
agentId
string

Generated agent identifier. Present when status is completed.

workflowId
string

Generated first-flow identifier. Present when status is completed.

error
object
Last modified on August 4, 2026