---
title: "Create replica"
method: POST
path: "/v1/replica"
tags: ["Replica"]
---

# Create replica

`POST /v1/replica`

## Request

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

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.

## Headers

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

## Request body

- CreateReplicaRequest: Request body for creating a new workspace
  - `name` string, required: Human-readable name for the workspace. Must not contain whitespace.
  - `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` '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.
  - `model` string: Model ID. Defaults to the organization default for the coding agent.
  - `images` ImageContent[]: Images to attach to the initial message
    - `type` 'image', required: Content type, always 'image'
    - `source` union, required: Image source data
      - object
        - `type` 'base64', required
        - `media_type` 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp', required: MIME type of the image
        - `data` string, required: Base64-encoded image data
      - object
        - `type` 'url', required
        - `url` string, uri, required: URL to the image
  - `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.
  - `config` WorkspaceConfig: Workspace behavior configuration. Defaults depend on the workspace source; see each setting.
    - `memoryRetentionEnabled` boolean: Whether sessions are added to session history when the workspace sleeps. Defaults to false for API and automation workspaces.
    - `capabilities` object: Actions this workspace is allowed to perform. Automations snapshot this config onto each workspace they create; API-created workspaces can set it at creation time.
      - `pr_followups` boolean: Whether matching pull requests can receive Replicas follow-up actions. Only applies to workspaces created from an automation, where it defaults to false; other workspaces always receive follow-ups. When enabled, later CI and review-comment replies can route back to this workspace.
      - `read_only_contents` boolean: Whether the workspace GitHub token is restricted to read-only repository contents, keeping write access for pull request comments, issues, and checks. Defaults to false, so the workspace can push branches and open pull requests.
    - `preferences` object: Workspace behavior preferences that do not grant new action permissions.
      - `keep_open_on_pr_merge` boolean: Whether the workspace should remain open after its last tracked PR is merged. Defaults to false.
      - `keep_open_on_pr_close` boolean: Whether the workspace should remain open after its last tracked PR is closed without merging. Defaults to false.
    - `provisioning_error` object: Setup/provisioning or wake/resume failure captured when the workspace remains queryable in `error` status. Some wake/resume failures can be retried; the `error` status can also represent an unrecoverable sandbox failure.
      - `message` string: Underlying setup failure message, such as repository clone/auth errors.
  - `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` '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.
  - `webhook_url` union: URL that receives `replica.ready`, `replica.turn_completed`, `replica.deleted`, and `replica.error` events.
    - string, uri
    - ReplicaWebhookConfig
      - `url` string, uri, required: HTTPS endpoint the platform POSTs JSON events to.
      - `secret` string: Optional shared secret used to compute the `X-Replicas-Signature` header (`sha256=` HMAC of the raw JSON body).
  - `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](https://docs.replicas.dev/admin/billing#rates) for per-size rates. Defaults to `small` when omitted.
  - `kind` 'standard' | 'mothership': `mothership` creates a [Mothership](https://docs.replicas.dev/features/workspaces/motherships). Needs a personal API key, and `lifecycle_policy` defaults to `default`.

## Response `201`

Replica created successfully

- CreateReplicaResponse
  - `replica` ReplicaListItem, required: A workspace item in list responses
    - `id` string, uuid, required: Unique identifier for the workspace
    - `name` string, required: Human-readable name for the workspace. Must not contain whitespace.
    - `status` 'active' | 'sleeping' | 'archived' | 'preparing' | 'error', required: Current status of the workspace
    - `source` 'api' | 'dashboard' | 'slack' | 'linear' | 'github' | 'gitlab' | 'automation', required: How the workspace was created
    - `created_at` string, date-time, required: Timestamp when the workspace was created
    - `last_activity_at` string, date-time, nullable, required: Timestamp of the last activity on the workspace
    - `repositories` RepositoryReference[], required: Repositories associated with the workspace
      - `id` string, uuid, required: Repository ID
      - `name` string, required: Repository name
      - `url` string, uri, required: Repository URL
    - `pull_requests` PullRequest[], required: Associated pull requests
      - `repository` string, required: Repository name
      - `number` integer, required: Pull request number
      - `url` string, uri, required: URL to the pull request

## Other responses

- `400`: Bad request - Missing or invalid parameters
- `401`: Unauthorized - Invalid or missing API key
- `402`: Payment Required - The organization has used up its trial or YC deal credit, reached its usage limit, or has a failed usage payment.
- `404`: Repository not found
- `409`: Conflict - Resource already exists or operation conflicts with current state
- `429`: The organization already has 100 metered API and Automation workspaces active or preparing
- `500`: Internal server error
- `503`: Service unavailable - The service is temporarily overloaded or under maintenance

---

[API](https://skmtc.dev/replicas/apis/replicas-api.md) - [All operations](https://skmtc.dev/replicas/apis/replicas-api/llms.txt) - [OpenAPI document](https://skmtc.dev/replicas/apis/replicas-api/revisions/2703ac1c9cb7?raw)