Skip to main content
POST
Create an agent

Authorizations

Authorization
string
header
default:cr_sk_your_key_here
required

Account API key from Developer Console. Keys start with cr_sk_.

Body

application/json
input
string
required

Natural-language request describing the agent to create. Serialized input must be 256 KB or smaller.

Maximum string length: 262144
model
string

Model id to run with (for example, anthropic/claude-haiku-4-5). Omit to use the default model, currently anthropic/claude-sonnet-5. Supported ids: GET /v1/models. Unknown ids return 400 MODEL_NOT_SUPPORTED; models not available on your plan return 403 MODEL_NOT_ALLOWED.

Maximum string length: 100
conversation_id
string<uuid>

Existing creation conversation to continue. Omit to create a new conversation.

webhook_url
string<uri>

Public http or https URL for the terminal agent-creation result.

Maximum string length: 2048

Response

Agent creation run accepted.

run_id
string<uuid>
required

Developer API run ID.

status
enum<string>
required
Available options:
pending,
running,
completed,
failed,
cancelled
agent_id
string<uuid> | null
required

Agent that ran. Creation runs return null until the agent is created, then the completed run includes the new agent ID.

conversation_id
string<uuid> | null
required

Conversation ID for follow-up runs.

model
string | null
required

Model id this run executed with. null only for runs created before model selection shipped.

workspace_id
string<uuid> | null

Personal workspace bound to this conversation, when set.

result
object

Final agent output. Completed runs commonly include text; agent-creation runs also include agent_id.

usage
object
error
object
created_at
string<date-time>
started_at
string<date-time> | null
completed_at
string<date-time> | null
webhook_delivered_at
string<date-time> | null