Skip to main content
POST
cURL

Authorizations

Authorization
string
header
required

JWT Bearer token obtained from authentication. Pass as: Authorization: Bearer

Body

application/json

Request body for creating a new agent

name
string
required

Human-readable display name for the agent

Required string length: 2 - 100
slug
string
required

URL-friendly unique identifier (lowercase alphanumeric and hyphens only)

Required string length: 2 - 64
Pattern: ^[a-z0-9-]+$
orgId
string

Organization ID that owns this agent (derived from auth if omitted)

Pattern: ^[cC][^\s-]{8,}$
email
string<email>

Optional email address to provision for this agent

provisionPhone
boolean
default:false

Whether to automatically provision a phone number for this agent

metadata
object

Arbitrary key-value metadata associated with the agent

voiceId
string

Voice for this agent's calls, e.g. "thalia". Choose an id from GET /voice/catalog; defaults to the system voice when omitted.

inboxId
string

ID of an existing inbox to associate with this agent. If omitted, a new inbox is created automatically.

Pattern: ^[cC][^\s-]{8,}$

Response

200 - application/json

OK

Full agent resource representation

id
string
required

Unique identifier of the agent

Pattern: ^[cC][^\s-]{8,}$
orgId
string
required

Organization ID that owns this agent

Pattern: ^[cC][^\s-]{8,}$
name
string
required

Human-readable display name

slug
string
required

URL-friendly unique identifier

status
enum<string>
required

Current lifecycle status

Available options:
ACTIVE,
SUSPENDED,
DELETED
apiKeyPrefix
string | null
required

Prefix of the agent's API key for identification, or null if no key is set

keyRotatedAt
string<date-time> | null
required

ISO 8601 timestamp of the last API-key rotation, null if never rotated

metadata
object
required

Arbitrary key-value metadata

voiceId
string | null
required

The agent's chosen voice id, or null for the system default.

emailIdentities
object[]
required

Email identities associated with this agent

phoneIdentities
object[]
required

Phone identities associated with this agent

createdAt
string<date-time>
required

Timestamp when the agent was created

updatedAt
string<date-time>
required

Timestamp when the agent was last updated

readiness
object

Per-capability readiness summary. Optional for backward compatibility — clients without readiness handling continue to work; clients that branch on it get the delayed-verification gap closed.