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>"
}Create replica
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.
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
Organization or personal API key from Settings → API Keys.
Headers
API version. 2026-10-07 returns snake_case responses. See versioning.
2026-10-07 Body
Request body for creating a new workspace
Human-readable name for the workspace. Must not contain whitespace.
^\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
claude, codex, cursor, muse, opencode, pi Model ID. Defaults to the organization default for the coding agent.
Images to attach to the initial message
Show child attributes
Show child attributes
Lifecycle policy for the workspace
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.
Reasoning effort. ultra is for Codex and Muse Code; ultracode is for Claude Code. Defaults to the agent's default.
low, medium, high, xhigh, max, ultra, ultracode URL that receives replica.ready, replica.turn_completed, replica.deleted, and replica.error events.
Response
Replica created successfully
A workspace item in list responses
Show child attributes
Show child attributes