Skip to main content
POST
agents.create({ template, metadata? })

Authorizations

Authorization
string
header
required

An API key, or a session token on its own session

Body

application/json
template
string
required
Pattern: ^[a-z0-9-]{1,64}@[1-9][0-9]*$
metadata
object

The customer's own string keys and values; never case-converted.

Response

Created

id
string
required
Pattern: ^agt_[0-7][0-9a-hjkmnp-tv-z]{25}$
template
string
required
Pattern: ^[a-z0-9-]{1,64}@[1-9][0-9]*$
harness
enum<string>
required
Available options:
claude-code,
codex,
pi
model
string
required

The effective model: the agent's own if set, otherwise the template's.

generation
integer
required

The generation of its effective configuration; it increases each time the configuration changes.

Required range: x >= 1
status
enum<string>
required
Available options:
sleeping,
waking,
awake,
unavailable
lastError
object | null
required
capabilities
object
required
sessionCount
integer
required

Its active sessions.

Required range: x >= 0
metadata
object
required

The customer's own string keys and values; never case-converted.

createdAt
string<date-time>
required

RFC 3339 in UTC with milliseconds.

Pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$