REreplicas
Replica

Create replica

Creates a replica from an environment and sends the first message. Returns immediately with status: "preparing"; use GET /v1/replica/{id}/wait to wait for it. An organization can have 100 API and automation replicas active or preparing at once.

post/v1/replica

Request

  • Base URL
    https://api.replicas.dev
  • URL
    https://api.replicas.dev/v1/replica
  • Auth
    HTTP bearer

Headers

X-Replicas-Api-Version'2026-10-07'

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

Request body

namestring required

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

messagestring required

Initial message to send to the coding agent

environment_idstring uuid required

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

coding_agent'claude' | 'codex' | 'cursor' | 'muse' | 'opencode' | 'pi'

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

modelstring

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

lifecycle_policy'default' | 'archive_when_done' | 'sleep_when_done' | 'delete_when_done' | 'delete_after_inactivity'

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

plan_modeboolean

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

goal_modeboolean

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_modeboolean

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

thinking_level'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'ultra' | 'ultracode'

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

size'small' | 'large' | 'ultra'

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.

kind'standard' | 'mothership'

mothership creates a Mothership. Needs a personal API key, and lifecycle_policy defaults to default.

Response

Replica created successfully

Changes

No recorded changes to this operation across all 1 revision of this API.