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

# Create Replica

`POST /v1/replica`

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

## Headers

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

## Request body

- CreateReplicaRequest — Request body for creating a new replica
  - `name` string, required — Human-readable name for the replica. Must not contain whitespace.
  - `message` string, required — Initial message to send to the coding agent
  - `environment_id` string, 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_id` string, uuid — Deprecated. Use `environment_id` instead. Provided for backwards compatibility: the server resolves the first environment bound to this repository set.
  - `repository_ids` string[] — 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
  - `model` string — 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.
  - `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_after_inactivity' — Lifecycle policy for the replica
  - `config` WorkspaceConfig — Workspace behavior configuration. Missing capabilities and preferences default to disabled.
    - `capabilities` object — Actions this workspace is allowed to perform. Automations snapshot this config onto each workspace they create; API-created replicas can set it at creation time.
      - `pr_followups` boolean — Whether matching pull requests can receive Replicas follow-up actions. Defaults to true for workspaces created from the dashboard, Slack, Linear, GitHub, or the API, and to false for workspaces created from an automation. When enabled, later CI and review-comment replies can route back to this workspace.
    - `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 Codex goal. 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' — 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).
  - `webhook_url` union — Callback target for `replica.ready`, `replica.turn_completed`, `replica.deleted`, and `replica.error` events. `replica.deleted` fires only on explicit deletion; closing a linked PR or issue now archives the workspace silently, so automated cleanup no longer emits it. `replica.error` is emitted when the workspace enters `error` state and remains queryable; the payload includes the failure message. Some wake/resume errors can be retried with the wake endpoint. Pass a bare URL string or `{ url, secret }`; with a secret the platform sets `X-Replicas-Signature: sha256=<hex HMAC>` on every delivery.
    - 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' — 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 `201`

Replica created successfully

- CreateReplicaResponse
  - `replica` ReplicaListItem, required — A replica item in list responses
    - `id` string, uuid, required — Unique identifier for the replica
    - `name` string, required — Human-readable name for the replica. Must not contain whitespace.
    - `status` 'active' | 'sleeping' | 'archived' | 'preparing' | 'error', required — Current status of the replica
    - `source` 'api' | 'dashboard' | 'slack' | 'linear' | 'github' | 'gitlab' | 'automation', required — How the replica was created
    - `created_at` string, date-time, required — Timestamp when the replica was created
    - `last_activity_at` string, date-time, nullable, required — Timestamp of the last activity on the replica
    - `repositories` RepositoryReference[], required — Repositories associated with the replica
      - `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
- `404` — Repository or repository set not found
- `409` — Conflict - Resource already exists or operation conflicts with current state
- `500` — Internal server error
- `503` — Service unavailable - The service is temporarily overloaded or under maintenance

---

[API](https://skmtc.net/tryreplicas/apis/replica-api.md) · [All operations](https://skmtc.net/tryreplicas/apis/replica-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tryreplicas/replica-api/versions/aa3b4c932f7a/schema)