Skip to main content
POST
/
v1
/
replica
Create Replica
curl --request POST \
  --url https://api.tryreplicas.com/v1/replica \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "message": "<string>",
  "environment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "repository_set_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "repository_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "coding_agent": "claude",
  "model": "<string>",
  "images": [
    {
      "type": "<string>",
      "source": {
        "type": "<string>",
        "data": "<string>"
      }
    }
  ],
  "config": {
    "capabilities": {
      "pr_followups": true
    },
    "preferences": {
      "keep_open_on_pr_merge": false
    }
  },
  "plan_mode": true,
  "goal_mode": true,
  "fast_mode": true,
  "webhook_url": "<string>"
}
'
{
  "replica": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "last_activity_at": "2023-11-07T05:31:56Z",
    "repositories": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "<string>",
        "url": "<string>"
      }
    ],
    "pull_requests": [
      {
        "repository": "<string>",
        "number": 123,
        "url": "<string>"
      }
    ]
  }
}

Authorizations

​
Authorization
string
header
required

API key authentication. Obtain your API key from the Replicas dashboard under Settings > API Keys.

Headers

​
X-Replicas-Api-Version
enum<string>

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.

Available options:
2026-05-17

Body

application/json

Request body for creating a new replica

​
name
string
required

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

Pattern: ^\S+$
​
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

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

​
repository_ids
string<uuid>[]
deprecated

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

​
coding_agent
enum<string>
default:claude

Coding agent to use

Available options:
claude,
codex,
cursor,
opencode
​
model
string

Model to use for the coding agent

​
images
object[]

Images to attach to the initial message

​
lifecycle_policy
enum<string>

Lifecycle policy for the replica

Available options:
default,
delete_when_done,
delete_after_inactivity
​
config
object

Workspace behavior configuration. Missing capabilities and preferences default to disabled.

​
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
enum<string>

Thinking/reasoning level. Controls how much effort the agent puts into reasoning. Falls back to provider default when omitted (Claude default: high, Codex default: medium, Cursor default: medium, Opencode default: medium).

Available options:
low,
medium,
high,
max
​
webhook_url

Callback target for replica.ready, replica.turn_completed, replica.deleted, and replica.error events. Pass a bare URL string or { url, secret }; with a secret the platform sets X-Replicas-Signature: sha256=<hex HMAC> on every delivery.

​
size
enum<string>

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. Omit to inherit the org's sandbox tier and the legacy $0.0166/min rate.

Available options:
small,
large

Response

Replica created successfully

​
replica
object
required

A replica item in list responses