Skip to main content
POST
Create an agent account and inbox
Requires the agent-onboarding API release. See Set up your agent for credential handling, safe retries and the human claim flow.

Headers

Idempotency-Key
string
required

Credential-like high-entropy secret. Generate at least 32 random bytes encoded as URL-safe text, save privately before sending, and reuse with the exact saved body for retries. Never log this header.

Required string length: 32 - 128
Pattern: ^[A-Za-z0-9_-]{32,128}$

Body

application/json
name
string

Workspace display name. Trimmed; control characters are rejected. Defaults to Agent workspace.

Required string length: 1 - 100
local_part
string

Optional inbox local part. Trimmed and lowercased; letters, digits, dots, underscores and hyphens, with a letter or digit at each end and no consecutive dots. Reserved or occupied names are rejected. Omit to allocate a name.

Required string length: 1 - 64

Response

Original signup response replayed; the inbox and API key are unchanged.

tenant_id
string
required
inbox
object
required
api_key
string<password>
required

Save privately before proceeding. Bearer credential for this tenant; unchanged across signup replays and claiming.

onboarding_state
string
required
Allowed value: "unclaimed"
capabilities
object
required
limits
object
required
unclaimed_expires_at
string<date-time>
required

Account expiry unless claimed, seven days by default.

claim_url
string<uri>
required

Private console claim URL, with a separate bearer secret in the #token fragment. Share only with the operator in an existing trusted channel; never log or email it.

claim_expires_at
string<date-time>
required

Link expiry, default 30 minutes, bounded by account expiry. A new link does not extend account lifetime.

instructions
string[]
required