Skip to main content
POST
Create Environment

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.

Body

application/json

Request body for creating a new environment.

name
string
required

Human-readable name (must be unique within the selected scope)

description
string | null

Optional description

scope
enum<string>
default:org

org creates a team environment. user creates a personal environment visible only to the authenticated user.

Available options:
org,
user
source_environment_id
string<uuid> | null

Optional source. Team environments copy from the source on create. Personal environments inherit from a team source and keep inherited config locked.

repository_id
string<uuid> | null

Bind to this repository. Mutually exclusive with repository_set_id.

repository_set_id
string<uuid> | null

Bind to this repository set. Mutually exclusive with repository_id.

system_prompt
string | null

Optional system prompt prepended to the coding agent.

mobile_testing_enabled
boolean
default:false

Enable mobile testing. Only valid for team environments on trial, Team, and Enterprise plans; otherwise returns PLAN_UPGRADE_REQUIRED.

Response

Environment created

environment
object
required

An environment — the config bundle workspaces are created from. Holds an optional repository binding plus the runtime variables, files, skills, MCPs, and warm hook applied to every workspace built from it. Every organization has a singleton Global environment (is_global: true) whose values are layered onto every other environment. Personal environments have user_id set and are visible only to their owner. Source-backed personal environments expose source-derived repository binding and system prompt values while keeping the source link in source_environment_id.