Skip to main content
POST
Create Replica

Authorizations

Authorization
string
header
required

API key authentication. Obtain your API key from the Replicas dashboard under Organization → Settings → API Keys. User-session JWTs are not accepted by /v1/replica endpoints.

Headers

X-Replicas-Api-Version
enum<string>

Optional dated API version. When omitted, the request blocks until the workspace reaches active and the response includes the populated engine details (legacy behavior). When set to 2026-05-17, the request returns immediately with a preparing workspace; the initial message is still delivered to the agent in the background. See the API Versioning section for details.

Available options:
2026-05-17

Body

application/json

Request body for creating a new replica

name
string
required

Human-readable name for the replica. Must not contain whitespace.

Pattern: ^\S+$
message
string
required

Initial message to send to the coding agent

environment_id
string<uuid>

ID of the environment to use. The server derives the repository or repository set from the environment binding. Required unless repository_set_id or repository_ids is provided for backwards compatibility.

repository_set_id
string<uuid>
deprecated

Deprecated. Use environment_id instead. Provided for backwards compatibility: the server resolves the first environment bound to this repository set.

repository_ids
string<uuid>[]
deprecated

Deprecated. Use environment_id instead. Provided for backwards compatibility: the server resolves the first environment bound to one of the given repositories.

coding_agent
enum<string>
default:claude

Coding agent to use

Available options:
claude,
codex,
cursor,
opencode,
pi
model
string

Model to use for the coding agent. Pi and Opencode accept z-ai/glm-5.2, minimax/minimax-m3, xiaomi/mimo-v2.5-pro, and moonshotai/kimi-k2.6 through OpenRouter.

images
object[]

Images to attach to the initial message

lifecycle_policy
enum<string>

Lifecycle policy for the replica

Available options:
default,
archive_when_done,
sleep_when_done,
delete_after_inactivity
config
object

Workspace behavior configuration. Missing capabilities and preferences default to disabled.

plan_mode
boolean

Whether to run the initial message in plan mode. Leading /plan in the message is also detected and stripped.

goal_mode
boolean

Whether to set the initial message as the active Codex goal. Leading /goal in the message is also detected and stripped.

fast_mode
boolean

Whether to run the initial message in fast mode. Leading /fast in the message is also detected and stripped.

thinking_level
enum<string>

Thinking/reasoning level. Controls how much effort the agent puts into reasoning. ultra is Codex-only; ultracode is Claude Code-only. Falls back to provider default when omitted (Claude default: high, Codex default: medium, Cursor default: medium, Opencode default: medium, Pi default: model default).

Available options:
low,
medium,
high,
xhigh,
max,
ultra,
ultracode
webhook_url

Callback target for replica.ready, replica.turn_completed, replica.deleted, and replica.error events. replica.deleted fires only on explicit deletion; closing a linked PR or issue now archives the workspace silently, so automated cleanup no longer emits it. replica.error is emitted when the workspace enters error state and remains queryable; the payload includes the failure message. Some wake/resume errors can be retried with the wake endpoint. Pass a bare URL string or { url, secret }; with a secret the platform sets X-Replicas-Signature: sha256=<hex HMAC> on every delivery.

size
enum<string>

Compute size for this replica. small (2 vCPU, 8 GB memory, 20 GB disk) bills at $0.008/min; large (4 vCPU, 16 GB memory, 32 GB disk) bills at $0.016/min. Defaults to small when omitted.

Available options:
small,
large

Response

Replica created successfully

replica
object
required

A replica item in list responses