Sign in

v1

latestOpenAPI 3.1.02026-07-22100167210.7 KB
Replica

Create Replica

Creates a new replica in your organization and sends an initial message to the coding agent. The workspace and agent are initialized asynchronously.

post/v1/replica

Headers

X-Replicas-Api-Version'2026-05-17'

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.

Request body

namestring required

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

messagestring required

Initial message to send to the coding agent

environment_idstring 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_idstring uuid

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

repository_idsstring[]

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

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

Coding agent to use

modelstring

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.

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

Lifecycle policy for the replica

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 Codex goal. 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'

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).

size'small' | 'large'

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.

Response

Replica created successfully