Initialize Server
curl --request POST \
--url https://api.example.com/api/init \
--header 'Content-Type: application/json' \
--header 'X-Session-API-Key: <api-key>' \
--data '
{
"allow_cors_origins": [
"<string>"
],
"bash_events_dir": "<string>",
"conversation_worktree_root": "<string>",
"conversations_path": "<string>",
"env": {},
"max_concurrent_runs": 2,
"secret_key": "<string>",
"session_api_keys": [
"<string>"
],
"telemetry": {
"deployment_kind": "local",
"event_buffer_size": 20,
"exporter": "none",
"flush_delay": 30,
"http_endpoint": "<string>",
"http_token": "<string>",
"max_queue_size": 1000,
"num_retries": 2,
"posthog_api_key": "<string>",
"posthog_host": "https://us.i.posthog.com",
"retry_delay": 5,
"salt": "<string>"
},
"web_url": "<string>",
"webhooks": [
{
"base_url": "<string>",
"event_buffer_size": 5,
"flush_delay": 30,
"headers": {},
"max_batch_bytes": 5242880,
"max_queue_bytes": 52428800,
"max_queue_size": 1000,
"num_retries": 3,
"retry_delay": 5
}
]
}
'import requests
url = "https://api.example.com/api/init"
payload = {
"allow_cors_origins": ["<string>"],
"bash_events_dir": "<string>",
"conversation_worktree_root": "<string>",
"conversations_path": "<string>",
"env": {},
"max_concurrent_runs": 2,
"secret_key": "<string>",
"session_api_keys": ["<string>"],
"telemetry": {
"deployment_kind": "local",
"event_buffer_size": 20,
"exporter": "none",
"flush_delay": 30,
"http_endpoint": "<string>",
"http_token": "<string>",
"max_queue_size": 1000,
"num_retries": 2,
"posthog_api_key": "<string>",
"posthog_host": "https://us.i.posthog.com",
"retry_delay": 5,
"salt": "<string>"
},
"web_url": "<string>",
"webhooks": [
{
"base_url": "<string>",
"event_buffer_size": 5,
"flush_delay": 30,
"headers": {},
"max_batch_bytes": 5242880,
"max_queue_bytes": 52428800,
"max_queue_size": 1000,
"num_retries": 3,
"retry_delay": 5
}
]
}
headers = {
"X-Session-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Session-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
allow_cors_origins: ['<string>'],
bash_events_dir: '<string>',
conversation_worktree_root: '<string>',
conversations_path: '<string>',
env: {},
max_concurrent_runs: 2,
secret_key: '<string>',
session_api_keys: ['<string>'],
telemetry: {
deployment_kind: 'local',
event_buffer_size: 20,
exporter: 'none',
flush_delay: 30,
http_endpoint: '<string>',
http_token: '<string>',
max_queue_size: 1000,
num_retries: 2,
posthog_api_key: '<string>',
posthog_host: 'https://us.i.posthog.com',
retry_delay: 5,
salt: '<string>'
},
web_url: '<string>',
webhooks: [
{
base_url: '<string>',
event_buffer_size: 5,
flush_delay: 30,
headers: {},
max_batch_bytes: 5242880,
max_queue_bytes: 52428800,
max_queue_size: 1000,
num_retries: 3,
retry_delay: 5
}
]
})
};
fetch('https://api.example.com/api/init', 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.example.com/api/init",
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([
'allow_cors_origins' => [
'<string>'
],
'bash_events_dir' => '<string>',
'conversation_worktree_root' => '<string>',
'conversations_path' => '<string>',
'env' => [
],
'max_concurrent_runs' => 2,
'secret_key' => '<string>',
'session_api_keys' => [
'<string>'
],
'telemetry' => [
'deployment_kind' => 'local',
'event_buffer_size' => 20,
'exporter' => 'none',
'flush_delay' => 30,
'http_endpoint' => '<string>',
'http_token' => '<string>',
'max_queue_size' => 1000,
'num_retries' => 2,
'posthog_api_key' => '<string>',
'posthog_host' => 'https://us.i.posthog.com',
'retry_delay' => 5,
'salt' => '<string>'
],
'web_url' => '<string>',
'webhooks' => [
[
'base_url' => '<string>',
'event_buffer_size' => 5,
'flush_delay' => 30,
'headers' => [
],
'max_batch_bytes' => 5242880,
'max_queue_bytes' => 52428800,
'max_queue_size' => 1000,
'num_retries' => 3,
'retry_delay' => 5
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Session-API-Key: <api-key>"
],
]);
$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.example.com/api/init"
payload := strings.NewReader("{\n \"allow_cors_origins\": [\n \"<string>\"\n ],\n \"bash_events_dir\": \"<string>\",\n \"conversation_worktree_root\": \"<string>\",\n \"conversations_path\": \"<string>\",\n \"env\": {},\n \"max_concurrent_runs\": 2,\n \"secret_key\": \"<string>\",\n \"session_api_keys\": [\n \"<string>\"\n ],\n \"telemetry\": {\n \"deployment_kind\": \"local\",\n \"event_buffer_size\": 20,\n \"exporter\": \"none\",\n \"flush_delay\": 30,\n \"http_endpoint\": \"<string>\",\n \"http_token\": \"<string>\",\n \"max_queue_size\": 1000,\n \"num_retries\": 2,\n \"posthog_api_key\": \"<string>\",\n \"posthog_host\": \"https://us.i.posthog.com\",\n \"retry_delay\": 5,\n \"salt\": \"<string>\"\n },\n \"web_url\": \"<string>\",\n \"webhooks\": [\n {\n \"base_url\": \"<string>\",\n \"event_buffer_size\": 5,\n \"flush_delay\": 30,\n \"headers\": {},\n \"max_batch_bytes\": 5242880,\n \"max_queue_bytes\": 52428800,\n \"max_queue_size\": 1000,\n \"num_retries\": 3,\n \"retry_delay\": 5\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Session-API-Key", "<api-key>")
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.example.com/api/init")
.header("X-Session-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"allow_cors_origins\": [\n \"<string>\"\n ],\n \"bash_events_dir\": \"<string>\",\n \"conversation_worktree_root\": \"<string>\",\n \"conversations_path\": \"<string>\",\n \"env\": {},\n \"max_concurrent_runs\": 2,\n \"secret_key\": \"<string>\",\n \"session_api_keys\": [\n \"<string>\"\n ],\n \"telemetry\": {\n \"deployment_kind\": \"local\",\n \"event_buffer_size\": 20,\n \"exporter\": \"none\",\n \"flush_delay\": 30,\n \"http_endpoint\": \"<string>\",\n \"http_token\": \"<string>\",\n \"max_queue_size\": 1000,\n \"num_retries\": 2,\n \"posthog_api_key\": \"<string>\",\n \"posthog_host\": \"https://us.i.posthog.com\",\n \"retry_delay\": 5,\n \"salt\": \"<string>\"\n },\n \"web_url\": \"<string>\",\n \"webhooks\": [\n {\n \"base_url\": \"<string>\",\n \"event_buffer_size\": 5,\n \"flush_delay\": 30,\n \"headers\": {},\n \"max_batch_bytes\": 5242880,\n \"max_queue_bytes\": 52428800,\n \"max_queue_size\": 1000,\n \"num_retries\": 3,\n \"retry_delay\": 5\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/init")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Session-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"allow_cors_origins\": [\n \"<string>\"\n ],\n \"bash_events_dir\": \"<string>\",\n \"conversation_worktree_root\": \"<string>\",\n \"conversations_path\": \"<string>\",\n \"env\": {},\n \"max_concurrent_runs\": 2,\n \"secret_key\": \"<string>\",\n \"session_api_keys\": [\n \"<string>\"\n ],\n \"telemetry\": {\n \"deployment_kind\": \"local\",\n \"event_buffer_size\": 20,\n \"exporter\": \"none\",\n \"flush_delay\": 30,\n \"http_endpoint\": \"<string>\",\n \"http_token\": \"<string>\",\n \"max_queue_size\": 1000,\n \"num_retries\": 2,\n \"posthog_api_key\": \"<string>\",\n \"posthog_host\": \"https://us.i.posthog.com\",\n \"retry_delay\": 5,\n \"salt\": \"<string>\"\n },\n \"web_url\": \"<string>\",\n \"webhooks\": [\n {\n \"base_url\": \"<string>\",\n \"event_buffer_size\": 5,\n \"flush_delay\": 30,\n \"headers\": {},\n \"max_batch_bytes\": 5242880,\n \"max_queue_bytes\": 52428800,\n \"max_queue_size\": 1000,\n \"num_retries\": 3,\n \"retry_delay\": 5\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"state": "dormant",
"error": "<string>"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"ctx": {},
"input": "<unknown>"
}
]
}Init
Initialize Server
Initialize a dormant server with runtime configuration.
Returns 400 if the server has already been initialized (state != dormant).
Returns 500 if initialization fails; in that case the state rolls back to
dormant so the orchestrator can retry.
POST
/
api
/
init
Initialize Server
curl --request POST \
--url https://api.example.com/api/init \
--header 'Content-Type: application/json' \
--header 'X-Session-API-Key: <api-key>' \
--data '
{
"allow_cors_origins": [
"<string>"
],
"bash_events_dir": "<string>",
"conversation_worktree_root": "<string>",
"conversations_path": "<string>",
"env": {},
"max_concurrent_runs": 2,
"secret_key": "<string>",
"session_api_keys": [
"<string>"
],
"telemetry": {
"deployment_kind": "local",
"event_buffer_size": 20,
"exporter": "none",
"flush_delay": 30,
"http_endpoint": "<string>",
"http_token": "<string>",
"max_queue_size": 1000,
"num_retries": 2,
"posthog_api_key": "<string>",
"posthog_host": "https://us.i.posthog.com",
"retry_delay": 5,
"salt": "<string>"
},
"web_url": "<string>",
"webhooks": [
{
"base_url": "<string>",
"event_buffer_size": 5,
"flush_delay": 30,
"headers": {},
"max_batch_bytes": 5242880,
"max_queue_bytes": 52428800,
"max_queue_size": 1000,
"num_retries": 3,
"retry_delay": 5
}
]
}
'import requests
url = "https://api.example.com/api/init"
payload = {
"allow_cors_origins": ["<string>"],
"bash_events_dir": "<string>",
"conversation_worktree_root": "<string>",
"conversations_path": "<string>",
"env": {},
"max_concurrent_runs": 2,
"secret_key": "<string>",
"session_api_keys": ["<string>"],
"telemetry": {
"deployment_kind": "local",
"event_buffer_size": 20,
"exporter": "none",
"flush_delay": 30,
"http_endpoint": "<string>",
"http_token": "<string>",
"max_queue_size": 1000,
"num_retries": 2,
"posthog_api_key": "<string>",
"posthog_host": "https://us.i.posthog.com",
"retry_delay": 5,
"salt": "<string>"
},
"web_url": "<string>",
"webhooks": [
{
"base_url": "<string>",
"event_buffer_size": 5,
"flush_delay": 30,
"headers": {},
"max_batch_bytes": 5242880,
"max_queue_bytes": 52428800,
"max_queue_size": 1000,
"num_retries": 3,
"retry_delay": 5
}
]
}
headers = {
"X-Session-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Session-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
allow_cors_origins: ['<string>'],
bash_events_dir: '<string>',
conversation_worktree_root: '<string>',
conversations_path: '<string>',
env: {},
max_concurrent_runs: 2,
secret_key: '<string>',
session_api_keys: ['<string>'],
telemetry: {
deployment_kind: 'local',
event_buffer_size: 20,
exporter: 'none',
flush_delay: 30,
http_endpoint: '<string>',
http_token: '<string>',
max_queue_size: 1000,
num_retries: 2,
posthog_api_key: '<string>',
posthog_host: 'https://us.i.posthog.com',
retry_delay: 5,
salt: '<string>'
},
web_url: '<string>',
webhooks: [
{
base_url: '<string>',
event_buffer_size: 5,
flush_delay: 30,
headers: {},
max_batch_bytes: 5242880,
max_queue_bytes: 52428800,
max_queue_size: 1000,
num_retries: 3,
retry_delay: 5
}
]
})
};
fetch('https://api.example.com/api/init', 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.example.com/api/init",
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([
'allow_cors_origins' => [
'<string>'
],
'bash_events_dir' => '<string>',
'conversation_worktree_root' => '<string>',
'conversations_path' => '<string>',
'env' => [
],
'max_concurrent_runs' => 2,
'secret_key' => '<string>',
'session_api_keys' => [
'<string>'
],
'telemetry' => [
'deployment_kind' => 'local',
'event_buffer_size' => 20,
'exporter' => 'none',
'flush_delay' => 30,
'http_endpoint' => '<string>',
'http_token' => '<string>',
'max_queue_size' => 1000,
'num_retries' => 2,
'posthog_api_key' => '<string>',
'posthog_host' => 'https://us.i.posthog.com',
'retry_delay' => 5,
'salt' => '<string>'
],
'web_url' => '<string>',
'webhooks' => [
[
'base_url' => '<string>',
'event_buffer_size' => 5,
'flush_delay' => 30,
'headers' => [
],
'max_batch_bytes' => 5242880,
'max_queue_bytes' => 52428800,
'max_queue_size' => 1000,
'num_retries' => 3,
'retry_delay' => 5
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Session-API-Key: <api-key>"
],
]);
$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.example.com/api/init"
payload := strings.NewReader("{\n \"allow_cors_origins\": [\n \"<string>\"\n ],\n \"bash_events_dir\": \"<string>\",\n \"conversation_worktree_root\": \"<string>\",\n \"conversations_path\": \"<string>\",\n \"env\": {},\n \"max_concurrent_runs\": 2,\n \"secret_key\": \"<string>\",\n \"session_api_keys\": [\n \"<string>\"\n ],\n \"telemetry\": {\n \"deployment_kind\": \"local\",\n \"event_buffer_size\": 20,\n \"exporter\": \"none\",\n \"flush_delay\": 30,\n \"http_endpoint\": \"<string>\",\n \"http_token\": \"<string>\",\n \"max_queue_size\": 1000,\n \"num_retries\": 2,\n \"posthog_api_key\": \"<string>\",\n \"posthog_host\": \"https://us.i.posthog.com\",\n \"retry_delay\": 5,\n \"salt\": \"<string>\"\n },\n \"web_url\": \"<string>\",\n \"webhooks\": [\n {\n \"base_url\": \"<string>\",\n \"event_buffer_size\": 5,\n \"flush_delay\": 30,\n \"headers\": {},\n \"max_batch_bytes\": 5242880,\n \"max_queue_bytes\": 52428800,\n \"max_queue_size\": 1000,\n \"num_retries\": 3,\n \"retry_delay\": 5\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Session-API-Key", "<api-key>")
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.example.com/api/init")
.header("X-Session-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"allow_cors_origins\": [\n \"<string>\"\n ],\n \"bash_events_dir\": \"<string>\",\n \"conversation_worktree_root\": \"<string>\",\n \"conversations_path\": \"<string>\",\n \"env\": {},\n \"max_concurrent_runs\": 2,\n \"secret_key\": \"<string>\",\n \"session_api_keys\": [\n \"<string>\"\n ],\n \"telemetry\": {\n \"deployment_kind\": \"local\",\n \"event_buffer_size\": 20,\n \"exporter\": \"none\",\n \"flush_delay\": 30,\n \"http_endpoint\": \"<string>\",\n \"http_token\": \"<string>\",\n \"max_queue_size\": 1000,\n \"num_retries\": 2,\n \"posthog_api_key\": \"<string>\",\n \"posthog_host\": \"https://us.i.posthog.com\",\n \"retry_delay\": 5,\n \"salt\": \"<string>\"\n },\n \"web_url\": \"<string>\",\n \"webhooks\": [\n {\n \"base_url\": \"<string>\",\n \"event_buffer_size\": 5,\n \"flush_delay\": 30,\n \"headers\": {},\n \"max_batch_bytes\": 5242880,\n \"max_queue_bytes\": 52428800,\n \"max_queue_size\": 1000,\n \"num_retries\": 3,\n \"retry_delay\": 5\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/init")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Session-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"allow_cors_origins\": [\n \"<string>\"\n ],\n \"bash_events_dir\": \"<string>\",\n \"conversation_worktree_root\": \"<string>\",\n \"conversations_path\": \"<string>\",\n \"env\": {},\n \"max_concurrent_runs\": 2,\n \"secret_key\": \"<string>\",\n \"session_api_keys\": [\n \"<string>\"\n ],\n \"telemetry\": {\n \"deployment_kind\": \"local\",\n \"event_buffer_size\": 20,\n \"exporter\": \"none\",\n \"flush_delay\": 30,\n \"http_endpoint\": \"<string>\",\n \"http_token\": \"<string>\",\n \"max_queue_size\": 1000,\n \"num_retries\": 2,\n \"posthog_api_key\": \"<string>\",\n \"posthog_host\": \"https://us.i.posthog.com\",\n \"retry_delay\": 5,\n \"salt\": \"<string>\"\n },\n \"web_url\": \"<string>\",\n \"webhooks\": [\n {\n \"base_url\": \"<string>\",\n \"event_buffer_size\": 5,\n \"flush_delay\": 30,\n \"headers\": {},\n \"max_batch_bytes\": 5242880,\n \"max_queue_bytes\": 52428800,\n \"max_queue_size\": 1000,\n \"num_retries\": 3,\n \"retry_delay\": 5\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"state": "dormant",
"error": "<string>"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"ctx": {},
"input": "<unknown>"
}
]
}Authorizations
Body
application/json
Runtime configuration delivered at /api/init time.
Each field is optional and overrides the equivalent field on the dormant
Config. Fields not provided keep the value the server was constructed
with (typically from env vars at pod startup). The set of overridable
fields is intentionally narrow — it covers the values that today are
"env-var shaped" and must change per-user, not image-build-time
configuration (Python deps, plugin set, etc.) which stays bound to the
warm-pool flavor.
CORS origins to add to the existing localhost allowlist.
Directory where bash events are persisted. Typically located inside the mounted user workspace.
Root directory for conversation git worktrees. Override this to point at the mounted user workspace.
Directory where conversations are persisted. Override this to point at the mounted user workspace.
Process environment variables to set before conversation services start. Useful for credentials consumed by tools (e.g. GITHUB_TOKEN). These are applied with os.environ.update; existing values are overwritten.
Show child attributes
Show child attributes
Override the conversation-step concurrency limit.
Required range:
x >= 1Symmetric secret used to encrypt persisted secrets. If not provided, falls back to the first session_api_key (matching the default Config behavior).
Per-user session API keys. If provided, all subsequent /api/* requests must authenticate with one of these keys via the X-Session-API-Key header.
Product-analytics policy for this pod. Without this, a warm-pool pod keeps whatever mode it booted with (normally 'disabled'), so a deployment that expects telemetry must supply it here.
Show child attributes
Show child attributes
External URL where this server is reachable, used for root-path calculation. Only honored when not already set in dormant config.
Per-user webhooks (e.g. for streaming events back).
Show child attributes
Show child attributes
Response
Successful Response
dormant — server is up but waiting for /api/init. initializing — /api/init has been received and services are starting. ready — initialization complete; all /api/* routes are live.
Available options:
dormant, initializing, ready If a previous /api/init attempt failed, the error message. The state rolls back to dormant so /api/init can be retried.
Was this page helpful?