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",
"model": "<string>",
"images": [
{
"type": "image",
"source": {
"type": "base64",
"data": "<string>"
}
}
],
"lifecycle_policy": "delete_when_done",
"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>"
}
},
"goal_mode": true,
"fast_mode": true,
"webhook_url": "<string>",
"kind": "standard"
}
'import requests
url = "https://api.replicas.dev/v1/replica"
payload = {
"name": "<string>",
"message": "<string>",
"environment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"model": "<string>",
"images": [
{
"type": "image",
"source": {
"type": "base64",
"data": "<string>"
}
}
],
"lifecycle_policy": "delete_when_done",
"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>" }
},
"goal_mode": True,
"fast_mode": True,
"webhook_url": "<string>",
"kind": "standard"
}
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',
model: '<string>',
images: [{type: 'image', source: {type: 'base64', data: '<string>'}}],
lifecycle_policy: 'delete_when_done',
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>'}
},
goal_mode: true,
fast_mode: true,
webhook_url: '<string>',
kind: 'standard'
})
};
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',
'model' => '<string>',
'images' => [
[
'type' => 'image',
'source' => [
'type' => 'base64',
'data' => '<string>'
]
]
],
'lifecycle_policy' => 'delete_when_done',
'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>'
]
],
'goal_mode' => true,
'fast_mode' => true,
'webhook_url' => '<string>',
'kind' => 'standard'
]),
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 \"model\": \"<string>\",\n \"images\": [\n {\n \"type\": \"image\",\n \"source\": {\n \"type\": \"base64\",\n \"data\": \"<string>\"\n }\n }\n ],\n \"lifecycle_policy\": \"delete_when_done\",\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 \"goal_mode\": true,\n \"fast_mode\": true,\n \"webhook_url\": \"<string>\",\n \"kind\": \"standard\"\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 \"model\": \"<string>\",\n \"images\": [\n {\n \"type\": \"image\",\n \"source\": {\n \"type\": \"base64\",\n \"data\": \"<string>\"\n }\n }\n ],\n \"lifecycle_policy\": \"delete_when_done\",\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 \"goal_mode\": true,\n \"fast_mode\": true,\n \"webhook_url\": \"<string>\",\n \"kind\": \"standard\"\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 \"model\": \"<string>\",\n \"images\": [\n {\n \"type\": \"image\",\n \"source\": {\n \"type\": \"base64\",\n \"data\": \"<string>\"\n }\n }\n ],\n \"lifecycle_policy\": \"delete_when_done\",\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 \"goal_mode\": true,\n \"fast_mode\": true,\n \"webhook_url\": \"<string>\",\n \"kind\": \"standard\"\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",
"repositories": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"url": "<string>"
}
]
}
}{
"error": "<string>",
"details": "<string>",
"code": "<string>"
}{
"error": "<string>",
"details": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "INSUFFICIENT_MINUTES",
"balance": {
"plan": "trial",
"period_start": "2023-11-07T05:31:56Z",
"period_end": "2023-11-07T05:31:56Z",
"credit": {
"total_cents": 123,
"plan_cents": 123,
"one_time_cents": 123,
"used_cents": 123,
"remaining_cents": 123,
"overage_cents": 123
},
"limit": {
"kind": "credit",
"limit_cents": 123,
"used_cents": 123,
"remaining_cents": 123
},
"blocked": {
"code": "INSUFFICIENT_MINUTES",
"message": "<string>"
}
}
}{
"error": "<string>",
"details": "<string>",
"code": "<string>"
}{
"error": "<string>",
"details": "<string>",
"code": "<string>"
}{
"error": "Organization workspace creation rate limit exceeded. Try again in 442s."
}{
"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",
"model": "<string>",
"images": [
{
"type": "image",
"source": {
"type": "base64",
"data": "<string>"
}
}
],
"lifecycle_policy": "delete_when_done",
"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>"
}
},
"goal_mode": true,
"fast_mode": true,
"webhook_url": "<string>",
"kind": "standard"
}
'import requests
url = "https://api.replicas.dev/v1/replica"
payload = {
"name": "<string>",
"message": "<string>",
"environment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"model": "<string>",
"images": [
{
"type": "image",
"source": {
"type": "base64",
"data": "<string>"
}
}
],
"lifecycle_policy": "delete_when_done",
"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>" }
},
"goal_mode": True,
"fast_mode": True,
"webhook_url": "<string>",
"kind": "standard"
}
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',
model: '<string>',
images: [{type: 'image', source: {type: 'base64', data: '<string>'}}],
lifecycle_policy: 'delete_when_done',
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>'}
},
goal_mode: true,
fast_mode: true,
webhook_url: '<string>',
kind: 'standard'
})
};
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',
'model' => '<string>',
'images' => [
[
'type' => 'image',
'source' => [
'type' => 'base64',
'data' => '<string>'
]
]
],
'lifecycle_policy' => 'delete_when_done',
'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>'
]
],
'goal_mode' => true,
'fast_mode' => true,
'webhook_url' => '<string>',
'kind' => 'standard'
]),
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 \"model\": \"<string>\",\n \"images\": [\n {\n \"type\": \"image\",\n \"source\": {\n \"type\": \"base64\",\n \"data\": \"<string>\"\n }\n }\n ],\n \"lifecycle_policy\": \"delete_when_done\",\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 \"goal_mode\": true,\n \"fast_mode\": true,\n \"webhook_url\": \"<string>\",\n \"kind\": \"standard\"\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 \"model\": \"<string>\",\n \"images\": [\n {\n \"type\": \"image\",\n \"source\": {\n \"type\": \"base64\",\n \"data\": \"<string>\"\n }\n }\n ],\n \"lifecycle_policy\": \"delete_when_done\",\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 \"goal_mode\": true,\n \"fast_mode\": true,\n \"webhook_url\": \"<string>\",\n \"kind\": \"standard\"\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 \"model\": \"<string>\",\n \"images\": [\n {\n \"type\": \"image\",\n \"source\": {\n \"type\": \"base64\",\n \"data\": \"<string>\"\n }\n }\n ],\n \"lifecycle_policy\": \"delete_when_done\",\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 \"goal_mode\": true,\n \"fast_mode\": true,\n \"webhook_url\": \"<string>\",\n \"kind\": \"standard\"\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",
"repositories": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"url": "<string>"
}
]
}
}{
"error": "<string>",
"details": "<string>",
"code": "<string>"
}{
"error": "<string>",
"details": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "INSUFFICIENT_MINUTES",
"balance": {
"plan": "trial",
"period_start": "2023-11-07T05:31:56Z",
"period_end": "2023-11-07T05:31:56Z",
"credit": {
"total_cents": 123,
"plan_cents": 123,
"one_time_cents": 123,
"used_cents": 123,
"remaining_cents": 123,
"overage_cents": 123
},
"limit": {
"kind": "credit",
"limit_cents": 123,
"used_cents": 123,
"remaining_cents": 123
},
"blocked": {
"code": "INSUFFICIENT_MINUTES",
"message": "<string>"
}
}
}{
"error": "<string>",
"details": "<string>",
"code": "<string>"
}{
"error": "<string>",
"details": "<string>",
"code": "<string>"
}{
"error": "Organization workspace creation rate limit exceeded. Try again in 442s."
}{
"error": "<string>",
"details": "<string>",
"code": "<string>"
}{
"error": "<string>",
"details": "<string>",
"code": "<string>"
}Authorizations
Headers
API version. 2026-10-07 returns snake_case responses. See versioning.
2026-10-07 Body
Request body for creating a new workspace
Lifecycle policy for the workspace. Defaults to delete_when_done (default for a Manager), which deletes the workspace once the agent finishes; pass default to keep it for follow-up messages or reading history afterwards.
default, archive_when_done, sleep_when_done, delete_when_done, delete_after_inactivity Compute size for this replica. small (2 vCPU, 8 GB memory), large (4 vCPU, 16 GB memory), ultra (8 vCPU, 32 GB memory), or auto (starts small and resizes with load); see Billing for per-size rates. Defaults to the organization's default size (auto unless an admin changed it) when omitted.
small, large, ultra, auto manager creates a Manager. Needs a personal API key, and lifecycle_policy defaults to default. mothership, its old name, is still accepted.
standard, manager, mothership