Create a pod
curl --request POST \
--url https://compute.x402layer.cc/pods/v1/pods \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--header 'X-API-Key: <api-key>' \
--data '
{
"tier": "starter",
"name": "<string>",
"external_ref": "<string>",
"model": "<string>",
"system_prompt": "<string>",
"region": "<string>",
"term_hours": 24,
"capabilities": {
"endpoint": true,
"wallet": true,
"platform_tools": true,
"connectors": true,
"channels": true,
"scheduler": true,
"backups": true
},
"ai": {
"mode": "managed",
"api_key": "<string>",
"base_url": "<string>",
"api": "<string>"
}
}
'import requests
url = "https://compute.x402layer.cc/pods/v1/pods"
payload = {
"tier": "starter",
"name": "<string>",
"external_ref": "<string>",
"model": "<string>",
"system_prompt": "<string>",
"region": "<string>",
"term_hours": 24,
"capabilities": {
"endpoint": True,
"wallet": True,
"platform_tools": True,
"connectors": True,
"channels": True,
"scheduler": True,
"backups": True
},
"ai": {
"mode": "managed",
"api_key": "<string>",
"base_url": "<string>",
"api": "<string>"
}
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
'X-API-Key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
tier: 'starter',
name: '<string>',
external_ref: '<string>',
model: '<string>',
system_prompt: '<string>',
region: '<string>',
term_hours: 24,
capabilities: {
endpoint: true,
wallet: true,
platform_tools: true,
connectors: true,
channels: true,
scheduler: true,
backups: true
},
ai: {mode: 'managed', api_key: '<string>', base_url: '<string>', api: '<string>'}
})
};
fetch('https://compute.x402layer.cc/pods/v1/pods', 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://compute.x402layer.cc/pods/v1/pods",
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([
'tier' => 'starter',
'name' => '<string>',
'external_ref' => '<string>',
'model' => '<string>',
'system_prompt' => '<string>',
'region' => '<string>',
'term_hours' => 24,
'capabilities' => [
'endpoint' => true,
'wallet' => true,
'platform_tools' => true,
'connectors' => true,
'channels' => true,
'scheduler' => true,
'backups' => true
],
'ai' => [
'mode' => 'managed',
'api_key' => '<string>',
'base_url' => '<string>',
'api' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>",
"X-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://compute.x402layer.cc/pods/v1/pods"
payload := strings.NewReader("{\n \"tier\": \"starter\",\n \"name\": \"<string>\",\n \"external_ref\": \"<string>\",\n \"model\": \"<string>\",\n \"system_prompt\": \"<string>\",\n \"region\": \"<string>\",\n \"term_hours\": 24,\n \"capabilities\": {\n \"endpoint\": true,\n \"wallet\": true,\n \"platform_tools\": true,\n \"connectors\": true,\n \"channels\": true,\n \"scheduler\": true,\n \"backups\": true\n },\n \"ai\": {\n \"mode\": \"managed\",\n \"api_key\": \"<string>\",\n \"base_url\": \"<string>\",\n \"api\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("X-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://compute.x402layer.cc/pods/v1/pods")
.header("Idempotency-Key", "<idempotency-key>")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"tier\": \"starter\",\n \"name\": \"<string>\",\n \"external_ref\": \"<string>\",\n \"model\": \"<string>\",\n \"system_prompt\": \"<string>\",\n \"region\": \"<string>\",\n \"term_hours\": 24,\n \"capabilities\": {\n \"endpoint\": true,\n \"wallet\": true,\n \"platform_tools\": true,\n \"connectors\": true,\n \"channels\": true,\n \"scheduler\": true,\n \"backups\": true\n },\n \"ai\": {\n \"mode\": \"managed\",\n \"api_key\": \"<string>\",\n \"base_url\": \"<string>\",\n \"api\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://compute.x402layer.cc/pods/v1/pods")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"tier\": \"starter\",\n \"name\": \"<string>\",\n \"external_ref\": \"<string>\",\n \"model\": \"<string>\",\n \"system_prompt\": \"<string>\",\n \"region\": \"<string>\",\n \"term_hours\": 24,\n \"capabilities\": {\n \"endpoint\": true,\n \"wallet\": true,\n \"platform_tools\": true,\n \"connectors\": true,\n \"channels\": true,\n \"scheduler\": true,\n \"backups\": true\n },\n \"ai\": {\n \"mode\": \"managed\",\n \"api_key\": \"<string>\",\n \"base_url\": \"<string>\",\n \"api\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"pod": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"slug": "<string>",
"external_ref": "<string>",
"status": "provisioning",
"tier": "starter",
"model": "<string>",
"ai": {
"mode": "managed"
},
"capabilities": {
"endpoint": true,
"wallet": true,
"platform_tools": true,
"connectors": true,
"channels": true,
"scheduler": true,
"backups": true
},
"endpoint": {
"base_url": "https://compute.x402layer.cc/pods/{id}/v1"
},
"billing": {
"expires_at": "2023-11-07T05:31:56Z",
"auto_renew": true,
"is_trial": true
},
"created_at": "2023-11-07T05:31:56Z"
}
}{
"pod": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"slug": "<string>",
"external_ref": "<string>",
"status": "provisioning",
"tier": "starter",
"model": "<string>",
"ai": {
"mode": "managed"
},
"capabilities": {
"endpoint": true,
"wallet": true,
"platform_tools": true,
"connectors": true,
"channels": true,
"scheduler": true,
"backups": true
},
"endpoint": {
"base_url": "https://compute.x402layer.cc/pods/{id}/v1"
},
"billing": {
"expires_at": "2023-11-07T05:31:56Z",
"auto_renew": true,
"is_trial": true
},
"created_at": "2023-11-07T05:31:56Z"
}
}{
"error": {
"code": "invalid_request",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_request",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_request",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_request",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_request",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_request",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_request",
"message": "<string>",
"details": {}
}
}Agent Pods API
Create a pod
Base URL https://compute.x402layer.cc/pods/v1. Auth is X-API-Key only. This is the PROGRAMMATIC surface and is NOT the same as the dashboard pod routes (POST /pods, PATCH /pods/{id}/settings, …), which take a wallet signature or a browser session and are free to change. Every response carries x-request-id.
Idempotency-Key is REQUIRED and the request is refused without it. This call provisions a machine and charges for it. Replaying the same key returns the ORIGINAL response byte for byte with Idempotent-Replay: true and a 200 instead of a 201, rather than making a second pod. The same key with a DIFFERENT body is a 409 carrying details.code = idempotency_mismatch, because that is a bug in your code and swallowing it would hide it.
Use an id you already have - an order number, a job id. A generated UUID protects a retry inside one process; only a stable id protects a retry after that process dies.
Returns 201 with status: provisioning. The machine takes a few minutes to boot; poll GET /pods/v1/pods/{id} until status is online.
Rate limit: 60 creates per HOUR, a separate and tighter bucket than ordinary writes, because this is the call that costs money. The idempotency key stops an accidental double-create; it does nothing about a deliberate loop, which is what this bucket is for.
Rate limit: 60 creates per hour, a separate and tighter bucket than the 60/min write limit. This is the call that provisions a machine and charges for it, so a runaway loop costs money rather than a wasted query. The Idempotency-Key prevents an accidental double-create; it does nothing about a deliberate loop.
POST
/
pods
/
v1
/
pods
Create a pod
curl --request POST \
--url https://compute.x402layer.cc/pods/v1/pods \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--header 'X-API-Key: <api-key>' \
--data '
{
"tier": "starter",
"name": "<string>",
"external_ref": "<string>",
"model": "<string>",
"system_prompt": "<string>",
"region": "<string>",
"term_hours": 24,
"capabilities": {
"endpoint": true,
"wallet": true,
"platform_tools": true,
"connectors": true,
"channels": true,
"scheduler": true,
"backups": true
},
"ai": {
"mode": "managed",
"api_key": "<string>",
"base_url": "<string>",
"api": "<string>"
}
}
'import requests
url = "https://compute.x402layer.cc/pods/v1/pods"
payload = {
"tier": "starter",
"name": "<string>",
"external_ref": "<string>",
"model": "<string>",
"system_prompt": "<string>",
"region": "<string>",
"term_hours": 24,
"capabilities": {
"endpoint": True,
"wallet": True,
"platform_tools": True,
"connectors": True,
"channels": True,
"scheduler": True,
"backups": True
},
"ai": {
"mode": "managed",
"api_key": "<string>",
"base_url": "<string>",
"api": "<string>"
}
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
'X-API-Key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
tier: 'starter',
name: '<string>',
external_ref: '<string>',
model: '<string>',
system_prompt: '<string>',
region: '<string>',
term_hours: 24,
capabilities: {
endpoint: true,
wallet: true,
platform_tools: true,
connectors: true,
channels: true,
scheduler: true,
backups: true
},
ai: {mode: 'managed', api_key: '<string>', base_url: '<string>', api: '<string>'}
})
};
fetch('https://compute.x402layer.cc/pods/v1/pods', 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://compute.x402layer.cc/pods/v1/pods",
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([
'tier' => 'starter',
'name' => '<string>',
'external_ref' => '<string>',
'model' => '<string>',
'system_prompt' => '<string>',
'region' => '<string>',
'term_hours' => 24,
'capabilities' => [
'endpoint' => true,
'wallet' => true,
'platform_tools' => true,
'connectors' => true,
'channels' => true,
'scheduler' => true,
'backups' => true
],
'ai' => [
'mode' => 'managed',
'api_key' => '<string>',
'base_url' => '<string>',
'api' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>",
"X-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://compute.x402layer.cc/pods/v1/pods"
payload := strings.NewReader("{\n \"tier\": \"starter\",\n \"name\": \"<string>\",\n \"external_ref\": \"<string>\",\n \"model\": \"<string>\",\n \"system_prompt\": \"<string>\",\n \"region\": \"<string>\",\n \"term_hours\": 24,\n \"capabilities\": {\n \"endpoint\": true,\n \"wallet\": true,\n \"platform_tools\": true,\n \"connectors\": true,\n \"channels\": true,\n \"scheduler\": true,\n \"backups\": true\n },\n \"ai\": {\n \"mode\": \"managed\",\n \"api_key\": \"<string>\",\n \"base_url\": \"<string>\",\n \"api\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("X-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://compute.x402layer.cc/pods/v1/pods")
.header("Idempotency-Key", "<idempotency-key>")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"tier\": \"starter\",\n \"name\": \"<string>\",\n \"external_ref\": \"<string>\",\n \"model\": \"<string>\",\n \"system_prompt\": \"<string>\",\n \"region\": \"<string>\",\n \"term_hours\": 24,\n \"capabilities\": {\n \"endpoint\": true,\n \"wallet\": true,\n \"platform_tools\": true,\n \"connectors\": true,\n \"channels\": true,\n \"scheduler\": true,\n \"backups\": true\n },\n \"ai\": {\n \"mode\": \"managed\",\n \"api_key\": \"<string>\",\n \"base_url\": \"<string>\",\n \"api\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://compute.x402layer.cc/pods/v1/pods")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"tier\": \"starter\",\n \"name\": \"<string>\",\n \"external_ref\": \"<string>\",\n \"model\": \"<string>\",\n \"system_prompt\": \"<string>\",\n \"region\": \"<string>\",\n \"term_hours\": 24,\n \"capabilities\": {\n \"endpoint\": true,\n \"wallet\": true,\n \"platform_tools\": true,\n \"connectors\": true,\n \"channels\": true,\n \"scheduler\": true,\n \"backups\": true\n },\n \"ai\": {\n \"mode\": \"managed\",\n \"api_key\": \"<string>\",\n \"base_url\": \"<string>\",\n \"api\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"pod": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"slug": "<string>",
"external_ref": "<string>",
"status": "provisioning",
"tier": "starter",
"model": "<string>",
"ai": {
"mode": "managed"
},
"capabilities": {
"endpoint": true,
"wallet": true,
"platform_tools": true,
"connectors": true,
"channels": true,
"scheduler": true,
"backups": true
},
"endpoint": {
"base_url": "https://compute.x402layer.cc/pods/{id}/v1"
},
"billing": {
"expires_at": "2023-11-07T05:31:56Z",
"auto_renew": true,
"is_trial": true
},
"created_at": "2023-11-07T05:31:56Z"
}
}{
"pod": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"slug": "<string>",
"external_ref": "<string>",
"status": "provisioning",
"tier": "starter",
"model": "<string>",
"ai": {
"mode": "managed"
},
"capabilities": {
"endpoint": true,
"wallet": true,
"platform_tools": true,
"connectors": true,
"channels": true,
"scheduler": true,
"backups": true
},
"endpoint": {
"base_url": "https://compute.x402layer.cc/pods/{id}/v1"
},
"billing": {
"expires_at": "2023-11-07T05:31:56Z",
"auto_renew": true,
"is_trial": true
},
"created_at": "2023-11-07T05:31:56Z"
}
}{
"error": {
"code": "invalid_request",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_request",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_request",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_request",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_request",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_request",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_request",
"message": "<string>",
"details": {}
}
}Authorizations
A compute API key (x402c_...). Mint one in the dashboard under Settings -> API Keys. This is the ONLY auth /pods/v1/* accepts - wallet signatures are bound to method+path+body and do not survive the internal hop, so signature callers must use the dashboard routes instead. Two extra scopes gate the dangerous powers: pods:wallet:write (pod wallet money, backup passphrase) and pods:control:write (connectors, full-power control socket).
Headers
REQUIRED. A stable id of your own. Replaying it returns the original response instead of creating a second pod.
Optional correlation id, echoed back on the response.
Body
application/json
Only these fields are read. Anything else is ignored - internal pricing and provisioning fields are deliberately not forwardable from a public caller.
Capability/price tier. Defaults to starter.
Example:
"starter"
Your display name for the pod.
Maximum string length:
120YOUR id. Comes back on every read and filters GET /pods, so you can find the pod again from your own database without storing ours.
Maximum string length:
128Model slug. Managed pods clamp this to the tier's allowed list.
Initial system prompt for the agent.
Optional datacentre pin. Omit it and we choose - picking a datacentre is our job, not yours.
Prepaid runtime in hours. Minimum 24.
Required range:
x >= 24What this pod was provisioned with. Omitting capabilities on create gives every capability.
Show child attributes
Show child attributes
managed = we run and meter the LLM. byok = the pod calls your own OpenAI-compatible endpoint.
Show child attributes
Show child attributes
Response
Idempotent replay: this exact Idempotency-Key already created a pod, so the ORIGINAL response body is returned unchanged. 200, not 201 - the pod was created by the earlier call.
The public projection of a pod on /pods/v1. An allowlist: it never carries the engine, its version, the provider, the region, the machine plan, the IP, or any credential, so the pod's implementation can change without breaking your integration.
Show child attributes
Show child attributes
Was this page helpful?