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-5. Supported ids: https://agent.docs.creao.ai/developer-api/supported-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

CREAO CLI 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

Settlement credits plus an optional per-model breakdown for the run. Omitted when the run incurred no cost and collected no model usage. models is present only for Super Agent–allowlisted accounts. Token fields appear only for token-metered capabilities. Per-image and per-second capabilities use generated_images or duration_seconds instead. kind tells the client which fields apply.

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