Skip to main content
POST
Create replica

Authorizations

Authorization
string
header
required

Organization or personal API key from Settings → API Keys.

Headers

X-Replicas-Api-Version
enum<string>

API version. 2026-10-07 returns snake_case responses. See versioning.

Available options:
2026-10-07

Body

application/json

Request body for creating a new workspace

name
string
required

Human-readable name for the workspace. 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,
muse,
opencode,
pi
model
string

Model ID. Defaults to the organization default for the coding agent.

images
object[]

Images to attach to the initial message

lifecycle_policy
enum<string>

Lifecycle policy for the workspace

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

Workspace behavior configuration. Defaults depend on the workspace source; see each setting.

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 goal (Claude Code and Codex). 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>

Reasoning effort. ultra is for Codex and Muse Code; ultracode is for Claude Code. Defaults to the agent's default.

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

URL that receives replica.ready, replica.turn_completed, replica.deleted, and replica.error events.

size
enum<string>

Compute size for this replica. small (2 vCPU, 8 GB memory), large (4 vCPU, 16 GB memory), or ultra (8 vCPU, 32 GB memory); see Billing for per-size rates. Defaults to small when omitted.

Available options:
small,
large,
ultra

Response

Replica created successfully

replica
object
required

A workspace item in list responses