curl -X PATCH \
https://api.agent37.com/v1/instances/ab12cd34ef \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Production agent",
"metadata": {
"plan": "pro"
},
"env": {
"APP_GATEWAY_URL": "https://api.example.com",
"RETIRED_FLAG": null
},
"auto_sleep": true,
"idle_timeout_seconds": 900
}'
import requests
response = requests.patch(
"https://api.agent37.com/v1/instances/ab12cd34ef",
headers={
"Authorization": "Bearer sk_live_...",
},
json={
"name": "Production agent",
"metadata": {
"plan": "pro",
},
"env": {
"APP_GATEWAY_URL": "https://api.example.com",
"RETIRED_FLAG": None,
},
"auto_sleep": True,
"idle_timeout_seconds": 900,
},
)
response.raise_for_status()
print(response.json())
const response = await fetch(
"https://api.agent37.com/v1/instances/ab12cd34ef",
{
method: "PATCH",
headers: {
Authorization: "Bearer sk_live_...",
"Content-Type": "application/json",
},
body: JSON.stringify({
name: "Production agent",
metadata: {
plan: "pro",
},
env: {
APP_GATEWAY_URL: "https://api.example.com",
RETIRED_FLAG: null,
},
auto_sleep: true,
idle_timeout_seconds: 900,
}),
},
);
if (!response.ok) {
throw new Error(await response.text());
}
console.log(await response.json());
{
"id": "ab12cd34ef",
"name": "Production agent",
"metadata": {
"plan": "pro"
},
"auto_sleep": true,
"idle_timeout_seconds": 900
}
Instances
Edit an instance
Change an instance’s labels, metadata, environment variables, or auto-sleep settings.
PATCH
/
v1
/
instances
/
{id}
curl -X PATCH \
https://api.agent37.com/v1/instances/ab12cd34ef \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Production agent",
"metadata": {
"plan": "pro"
},
"env": {
"APP_GATEWAY_URL": "https://api.example.com",
"RETIRED_FLAG": null
},
"auto_sleep": true,
"idle_timeout_seconds": 900
}'
import requests
response = requests.patch(
"https://api.agent37.com/v1/instances/ab12cd34ef",
headers={
"Authorization": "Bearer sk_live_...",
},
json={
"name": "Production agent",
"metadata": {
"plan": "pro",
},
"env": {
"APP_GATEWAY_URL": "https://api.example.com",
"RETIRED_FLAG": None,
},
"auto_sleep": True,
"idle_timeout_seconds": 900,
},
)
response.raise_for_status()
print(response.json())
const response = await fetch(
"https://api.agent37.com/v1/instances/ab12cd34ef",
{
method: "PATCH",
headers: {
Authorization: "Bearer sk_live_...",
"Content-Type": "application/json",
},
body: JSON.stringify({
name: "Production agent",
metadata: {
plan: "pro",
},
env: {
APP_GATEWAY_URL: "https://api.example.com",
RETIRED_FLAG: null,
},
auto_sleep: true,
idle_timeout_seconds: 900,
}),
},
);
if (!response.ok) {
throw new Error(await response.text());
}
console.log(await response.json());
{
"id": "ab12cd34ef",
"name": "Production agent",
"metadata": {
"plan": "pro"
},
"auto_sleep": true,
"idle_timeout_seconds": 900
}
curl -X PATCH \
https://api.agent37.com/v1/instances/ab12cd34ef \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Production agent",
"metadata": {
"plan": "pro"
},
"env": {
"APP_GATEWAY_URL": "https://api.example.com",
"RETIRED_FLAG": null
},
"auto_sleep": true,
"idle_timeout_seconds": 900
}'
import requests
response = requests.patch(
"https://api.agent37.com/v1/instances/ab12cd34ef",
headers={
"Authorization": "Bearer sk_live_...",
},
json={
"name": "Production agent",
"metadata": {
"plan": "pro",
},
"env": {
"APP_GATEWAY_URL": "https://api.example.com",
"RETIRED_FLAG": None,
},
"auto_sleep": True,
"idle_timeout_seconds": 900,
},
)
response.raise_for_status()
print(response.json())
const response = await fetch(
"https://api.agent37.com/v1/instances/ab12cd34ef",
{
method: "PATCH",
headers: {
Authorization: "Bearer sk_live_...",
"Content-Type": "application/json",
},
body: JSON.stringify({
name: "Production agent",
metadata: {
plan: "pro",
},
env: {
APP_GATEWAY_URL: "https://api.example.com",
RETIRED_FLAG: null,
},
auto_sleep: true,
idle_timeout_seconds: 900,
}),
},
);
if (!response.ok) {
throw new Error(await response.text());
}
console.log(await response.json());
{
"id": "ab12cd34ef",
"name": "Production agent",
"metadata": {
"plan": "pro"
},
"auto_sleep": true,
"idle_timeout_seconds": 900
}
Authorization: Bearer sk_live_... on https://api.agent37.com.
Path parameters
string
required
The instance id, returned when you create an instance.
Request body
The examples include every editable field. Send only the fields you want to change.string | null
optional
A label for the instance, up to 60 characters.
null or "" clears it.object | null
optional
Your key/value pairs, up to 4 KB serialized. The object replaces the stored one, it is not merged.
null or {} clears it.object
optional
Environment variables for the container. The keys you send are set, a
null value unsets that one variable, and the rest of the stored environment is left alone. Stored only: the new values reach the container on its next start, restart, update, or resize, never on a wake. Write-only, so env is never returned.boolean
optional
Turn auto-sleep on or off. Takes effect within about half a minute, with no restart and no recreate.
integer
optional
The new idle timeout: an integer from
300 to 86400 seconds.string | object
optional
Where the instance can connect:
"allow-all", "deny-all", or { "allow": [...] }. Applies to the running instance within seconds, with no restart. See Network access.Response
The response contains the full instance object, including its resources, URLs, and timestamps. The example shows only the id and edited fields.Update behavior
PATCH /v1/instances/{id} edits the instance’s name and metadata after creation, plus its auto-sleep settings and its network access. These are the same fields you can set at create, and they are the only things this call changes: it never touches the running container. It returns 200 with the full instance object, the same shape as GET.
The patch is partial: only the keys you send change, the rest are left alone. Send a string to set a label field, or null (or "") to clear it. You must send at least one of name, metadata, env, auto_sleep, idle_timeout_seconds, or network; an empty body returns 400 invalid_request.
Edits never bill and never recreate the container, and they work in any state except deleted. Unknown, deleted, or other-workspace ids return 404 not_found.
env is the one field whose effect is not immediate. A container is handed its environment when it starts, so an edit changes what the next container build carries: restart the instance (or stop and start it, update it, or resize it) for the new values to arrive. Processes already running keep the environment they started with, and so does a sleeping instance that wakes, because a wake restores that same process: restart a sleeper to boot it on the new values. An edit that would push the merged environment past the limits on Environment variables, or that names a platform-owned variable, returns 400 invalid_request and changes nothing.