Create Replica
curl --request POST \
--url https://api.replicas.dev/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": "image",
"source": {
"type": "base64",
"data": "<string>"
}
}
],
"config": {
"memoryRetentionEnabled": true,
"capabilities": {
"pr_followups": true,
"read_only_contents": true
},
"preferences": {
"keep_open_on_pr_merge": false,
"keep_open_on_pr_close": false
},
"provisioning_error": {
"message": "<string>"
}
},
"plan_mode": true,
"goal_mode": true,
"fast_mode": true,
"webhook_url": "<string>"
}
'import requests
url = "https://api.replicas.dev/v1/replica"
payload = {
"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": "image",
"source": {
"type": "base64",
"data": "<string>"
}
}
],
"config": {
"memoryRetentionEnabled": True,
"capabilities": {
"pr_followups": True,
"read_only_contents": True
},
"preferences": {
"keep_open_on_pr_merge": False,
"keep_open_on_pr_close": False
},
"provisioning_error": { "message": "<string>" }
},
"plan_mode": True,
"goal_mode": True,
"fast_mode": True,
"webhook_url": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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: 'image', source: {type: 'base64', data: '<string>'}}],
config: {
memoryRetentionEnabled: true,
capabilities: {pr_followups: true, read_only_contents: true},
preferences: {keep_open_on_pr_merge: false, keep_open_on_pr_close: false},
provisioning_error: {message: '<string>'}
},
plan_mode: true,
goal_mode: true,
fast_mode: true,
webhook_url: '<string>'
})
};
fetch('https://api.replicas.dev/v1/replica', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.replicas.dev/v1/replica",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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' => 'image',
'source' => [
'type' => 'base64',
'data' => '<string>'
]
]
],
'config' => [
'memoryRetentionEnabled' => true,
'capabilities' => [
'pr_followups' => true,
'read_only_contents' => true
],
'preferences' => [
'keep_open_on_pr_merge' => false,
'keep_open_on_pr_close' => false
],
'provisioning_error' => [
'message' => '<string>'
]
],
'plan_mode' => true,
'goal_mode' => true,
'fast_mode' => true,
'webhook_url' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.replicas.dev/v1/replica"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"message\": \"<string>\",\n \"environment_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"repository_set_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"repository_ids\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"coding_agent\": \"claude\",\n \"model\": \"<string>\",\n \"images\": [\n {\n \"type\": \"image\",\n \"source\": {\n \"type\": \"base64\",\n \"data\": \"<string>\"\n }\n }\n ],\n \"config\": {\n \"memoryRetentionEnabled\": true,\n \"capabilities\": {\n \"pr_followups\": true,\n \"read_only_contents\": true\n },\n \"preferences\": {\n \"keep_open_on_pr_merge\": false,\n \"keep_open_on_pr_close\": false\n },\n \"provisioning_error\": {\n \"message\": \"<string>\"\n }\n },\n \"plan_mode\": true,\n \"goal_mode\": true,\n \"fast_mode\": true,\n \"webhook_url\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.replicas.dev/v1/replica")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"message\": \"<string>\",\n \"environment_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"repository_set_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"repository_ids\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"coding_agent\": \"claude\",\n \"model\": \"<string>\",\n \"images\": [\n {\n \"type\": \"image\",\n \"source\": {\n \"type\": \"base64\",\n \"data\": \"<string>\"\n }\n }\n ],\n \"config\": {\n \"memoryRetentionEnabled\": true,\n \"capabilities\": {\n \"pr_followups\": true,\n \"read_only_contents\": true\n },\n \"preferences\": {\n \"keep_open_on_pr_merge\": false,\n \"keep_open_on_pr_close\": false\n },\n \"provisioning_error\": {\n \"message\": \"<string>\"\n }\n },\n \"plan_mode\": true,\n \"goal_mode\": true,\n \"fast_mode\": true,\n \"webhook_url\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.replicas.dev/v1/replica")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"message\": \"<string>\",\n \"environment_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"repository_set_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"repository_ids\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"coding_agent\": \"claude\",\n \"model\": \"<string>\",\n \"images\": [\n {\n \"type\": \"image\",\n \"source\": {\n \"type\": \"base64\",\n \"data\": \"<string>\"\n }\n }\n ],\n \"config\": {\n \"memoryRetentionEnabled\": true,\n \"capabilities\": {\n \"pr_followups\": true,\n \"read_only_contents\": true\n },\n \"preferences\": {\n \"keep_open_on_pr_merge\": false,\n \"keep_open_on_pr_close\": false\n },\n \"provisioning_error\": {\n \"message\": \"<string>\"\n }\n },\n \"plan_mode\": true,\n \"goal_mode\": true,\n \"fast_mode\": true,\n \"webhook_url\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"replica": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"status": "active",
"source": "api",
"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>"
}
]
}
}{
"error": "<string>",
"details": "<string>",
"code": "<string>"
}{
"error": "<string>",
"details": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "INSUFFICIENT_MINUTES"
}{
"error": "<string>",
"details": "<string>",
"code": "<string>"
}{
"error": "<string>",
"details": "<string>",
"code": "<string>"
}{
"error": "<string>",
"details": "<string>",
"code": "<string>"
}{
"error": "<string>",
"details": "<string>",
"code": "<string>"
}{
"error": "<string>",
"details": "<string>",
"code": "<string>"
}Replica
Create Replica
Creates a new replica in your organization and sends an initial message to the coding agent. User-session JWTs are not accepted for workspace creation; use an API key or workspace engine secret. The workspace and agent are initialized asynchronously. Each organization can have up to 100 metered API and Automation workspaces active or preparing at once.
POST
/
v1
/
replica
Create Replica
curl --request POST \
--url https://api.replicas.dev/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": "image",
"source": {
"type": "base64",
"data": "<string>"
}
}
],
"config": {
"memoryRetentionEnabled": true,
"capabilities": {
"pr_followups": true,
"read_only_contents": true
},
"preferences": {
"keep_open_on_pr_merge": false,
"keep_open_on_pr_close": false
},
"provisioning_error": {
"message": "<string>"
}
},
"plan_mode": true,
"goal_mode": true,
"fast_mode": true,
"webhook_url": "<string>"
}
'import requests
url = "https://api.replicas.dev/v1/replica"
payload = {
"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": "image",
"source": {
"type": "base64",
"data": "<string>"
}
}
],
"config": {
"memoryRetentionEnabled": True,
"capabilities": {
"pr_followups": True,
"read_only_contents": True
},
"preferences": {
"keep_open_on_pr_merge": False,
"keep_open_on_pr_close": False
},
"provisioning_error": { "message": "<string>" }
},
"plan_mode": True,
"goal_mode": True,
"fast_mode": True,
"webhook_url": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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: 'image', source: {type: 'base64', data: '<string>'}}],
config: {
memoryRetentionEnabled: true,
capabilities: {pr_followups: true, read_only_contents: true},
preferences: {keep_open_on_pr_merge: false, keep_open_on_pr_close: false},
provisioning_error: {message: '<string>'}
},
plan_mode: true,
goal_mode: true,
fast_mode: true,
webhook_url: '<string>'
})
};
fetch('https://api.replicas.dev/v1/replica', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.replicas.dev/v1/replica",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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' => 'image',
'source' => [
'type' => 'base64',
'data' => '<string>'
]
]
],
'config' => [
'memoryRetentionEnabled' => true,
'capabilities' => [
'pr_followups' => true,
'read_only_contents' => true
],
'preferences' => [
'keep_open_on_pr_merge' => false,
'keep_open_on_pr_close' => false
],
'provisioning_error' => [
'message' => '<string>'
]
],
'plan_mode' => true,
'goal_mode' => true,
'fast_mode' => true,
'webhook_url' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.replicas.dev/v1/replica"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"message\": \"<string>\",\n \"environment_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"repository_set_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"repository_ids\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"coding_agent\": \"claude\",\n \"model\": \"<string>\",\n \"images\": [\n {\n \"type\": \"image\",\n \"source\": {\n \"type\": \"base64\",\n \"data\": \"<string>\"\n }\n }\n ],\n \"config\": {\n \"memoryRetentionEnabled\": true,\n \"capabilities\": {\n \"pr_followups\": true,\n \"read_only_contents\": true\n },\n \"preferences\": {\n \"keep_open_on_pr_merge\": false,\n \"keep_open_on_pr_close\": false\n },\n \"provisioning_error\": {\n \"message\": \"<string>\"\n }\n },\n \"plan_mode\": true,\n \"goal_mode\": true,\n \"fast_mode\": true,\n \"webhook_url\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.replicas.dev/v1/replica")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"message\": \"<string>\",\n \"environment_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"repository_set_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"repository_ids\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"coding_agent\": \"claude\",\n \"model\": \"<string>\",\n \"images\": [\n {\n \"type\": \"image\",\n \"source\": {\n \"type\": \"base64\",\n \"data\": \"<string>\"\n }\n }\n ],\n \"config\": {\n \"memoryRetentionEnabled\": true,\n \"capabilities\": {\n \"pr_followups\": true,\n \"read_only_contents\": true\n },\n \"preferences\": {\n \"keep_open_on_pr_merge\": false,\n \"keep_open_on_pr_close\": false\n },\n \"provisioning_error\": {\n \"message\": \"<string>\"\n }\n },\n \"plan_mode\": true,\n \"goal_mode\": true,\n \"fast_mode\": true,\n \"webhook_url\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.replicas.dev/v1/replica")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"message\": \"<string>\",\n \"environment_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"repository_set_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"repository_ids\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"coding_agent\": \"claude\",\n \"model\": \"<string>\",\n \"images\": [\n {\n \"type\": \"image\",\n \"source\": {\n \"type\": \"base64\",\n \"data\": \"<string>\"\n }\n }\n ],\n \"config\": {\n \"memoryRetentionEnabled\": true,\n \"capabilities\": {\n \"pr_followups\": true,\n \"read_only_contents\": true\n },\n \"preferences\": {\n \"keep_open_on_pr_merge\": false,\n \"keep_open_on_pr_close\": false\n },\n \"provisioning_error\": {\n \"message\": \"<string>\"\n }\n },\n \"plan_mode\": true,\n \"goal_mode\": true,\n \"fast_mode\": true,\n \"webhook_url\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"replica": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"status": "active",
"source": "api",
"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>"
}
]
}
}{
"error": "<string>",
"details": "<string>",
"code": "<string>"
}{
"error": "<string>",
"details": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "INSUFFICIENT_MINUTES"
}{
"error": "<string>",
"details": "<string>",
"code": "<string>"
}{
"error": "<string>",
"details": "<string>",
"code": "<string>"
}{
"error": "<string>",
"details": "<string>",
"code": "<string>"
}{
"error": "<string>",
"details": "<string>",
"code": "<string>"
}{
"error": "<string>",
"details": "<string>",
"code": "<string>"
}Authorizations
apiKeyengineSecret & workspaceId
API key authentication. Obtain your API key from the Replicas dashboard under Organization → Settings → API Keys.
Headers
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
Human-readable name for the replica. Must not contain whitespace.
Pattern:
^\S+$Initial message to send to the coding agent
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.
Deprecated. Use environment_id instead. Provided for backwards compatibility: the server resolves the first environment bound to this repository set.
Deprecated. Use environment_id instead. Provided for backwards compatibility: the server resolves the first environment bound to one of the given repositories.
Coding agent to use
Available options:
claude, codex, cursor, muse, opencode, pi Model to use for the coding agent. Muse Code accepts muse-spark-1.3 and muse-spark-1.2. With OpenRouter, Pi and Opencode accept models available to the connected OpenRouter account. The OpenRouter models selection in Coding Agents settings controls model-picker visibility only; it does not restrict explicit model requests or saved defaults.
Images to attach to the initial message
Show child attributes
Show child attributes
Lifecycle policy for the replica
Available options:
default, archive_when_done, sleep_when_done, delete_after_inactivity Workspace behavior configuration. Defaults depend on the workspace source; see each setting.
Show child attributes
Show child attributes
Whether to run the initial message in plan mode. Leading /plan in the message is also detected and stripped.
Whether to set the initial message as the active goal (Claude Code and Codex). Leading /goal in the message is also detected and stripped.
Whether to run the initial message in fast mode. Leading /fast in the message is also detected and stripped.
Thinking/reasoning level. Controls how much effort the agent puts into reasoning. ultra is available for Codex and Muse Code; ultracode is Claude Code-only. Falls back to provider default when omitted (Claude default: high, Codex default: medium, Cursor default: medium, Muse Code default: high, Opencode default: medium, Pi default: medium).
Available options:
low, medium, high, xhigh, max, ultra, ultracode 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.
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.
Available options:
small, large Response
Replica created successfully
A replica item in list responses
Show child attributes
Show child attributes
⌘I