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

Name shown in the dashboard sidebar. Spaces are allowed.

message
string
required

Initial message to send to the coding agent

environment_id
string<uuid>
required

ID of the environment to use. The server clones the environment's repositories.

coding_agent
enum<string>

Coding agent to use. Defaults to your default agent, which is the first agent you connected until you choose another.

Available options:
claude,
codex,
cursor,
gemini,
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>
default:delete_when_done

Lifecycle policy for the workspace. Defaults to delete_when_done (default for a Manager), which deletes the workspace once the agent finishes; pass default to keep it for follow-up messages or reading history afterwards.

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

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

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), ultra (8 vCPU, 32 GB memory), or auto (starts small and resizes with load); see Billing for per-size rates. Defaults to the organization's default size (auto unless an admin changed it) when omitted.

Available options:
small,
large,
ultra,
auto
kind
enum<string>
default:standard

manager creates a Manager. Needs a personal API key, and lifecycle_policy defaults to default. mothership, its old name, is still accepted.

Available options:
standard,
manager,
mothership

Response

Replica created successfully

replica
object
required

A workspace as returned on creation