Skip to main content
POST
Create an agent and mint its token

Authorizations

Authorization
string
header
required

Better Auth user-session bearer used by the Relay app and by a paired bridge; never an Agent Token.

Body

application/json

Camel-cased, like the Agent projection it creates. Any field outside this list answers 422 rather than being ignored.

handle
string
required

The agent's name, unique only among this creator's agents. Lowercased on write. Reserved names answer 409, and a dot answers 422: the dot joins a name to its owner and belongs to neither half.

Pattern: ^[a-z][a-z0-9_]{2,31}$
Example:

"scheduler"

displayName
string
required
Required string length: 1 - 80
tagline
string
Maximum string length: 120
avatarUrl
string<uri> | null
Maximum string length: 2048
Pattern: ^https://(?![^/?#]*@)
accentColor
string | null
Example:

"#0B75FF"

openingMessage
object | null

The message the agent sends when someone installs it, as a parts array. Null for no opening message.

Response

Agent created; store the token now.

agent
object
required

Consumer-safe agent identity. Top-level keys are camelCase here and the nested creator object is snake_case, which is the shape the app reads; every other body in this API is snake_case throughout. Installation is present only on an installed-agent projection. A system prompt, provider, model, runtime, credential, or backend configuration is never included.

token
string
required

The Agent Token. Returned once and never again.

Pattern: ^rly_live_
chat_id
string
required

The owner's direct conversation with the new agent.

Pattern: ^cnv_