curl -X POST \
https://api.agent37.com/v1/instances/ab12cd34ef/update \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"template": "agent37-hermes@<tag>"
}'
import requests
response = requests.post(
"https://api.agent37.com/v1/instances/ab12cd34ef/update",
headers={
"Authorization": "Bearer sk_live_...",
"Content-Type": "application/json"
},
json={
"template": "agent37-hermes@<tag>"
},
)
response.raise_for_status()
print(response.json())
const response = await fetch(
"https://api.agent37.com/v1/instances/ab12cd34ef/update",
{
method: "POST",
headers: {
"Authorization": "Bearer sk_live_...",
"Content-Type": "application/json"
},
body: JSON.stringify({
"template": "agent37-hermes@<tag>"
}),
},
);
if (!response.ok) {
throw new Error(await response.text());
}
console.log(await response.json());
{
"id": "ab12cd34ef",
"status": "running",
"image_ref": "ghcr.io/agent37-platform/hermes:2026.10.05a",
"image_digest": "sha256:d3f6f28fae8128274b15256a3f17ecf6b2cc5e209db886def17f0595900a1045",
"template_revision": null
}
Lifecycle
Update an instance
Apply a template image while preserving data in /home/node and /home/linuxbrew.
POST
/
v1
/
instances
/
{id}
/
update
curl -X POST \
https://api.agent37.com/v1/instances/ab12cd34ef/update \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"template": "agent37-hermes@<tag>"
}'
import requests
response = requests.post(
"https://api.agent37.com/v1/instances/ab12cd34ef/update",
headers={
"Authorization": "Bearer sk_live_...",
"Content-Type": "application/json"
},
json={
"template": "agent37-hermes@<tag>"
},
)
response.raise_for_status()
print(response.json())
const response = await fetch(
"https://api.agent37.com/v1/instances/ab12cd34ef/update",
{
method: "POST",
headers: {
"Authorization": "Bearer sk_live_...",
"Content-Type": "application/json"
},
body: JSON.stringify({
"template": "agent37-hermes@<tag>"
}),
},
);
if (!response.ok) {
throw new Error(await response.text());
}
console.log(await response.json());
{
"id": "ab12cd34ef",
"status": "running",
"image_ref": "ghcr.io/agent37-platform/hermes:2026.10.05a",
"image_digest": "sha256:d3f6f28fae8128274b15256a3f17ecf6b2cc5e209db886def17f0595900a1045",
"template_revision": null
}
curl -X POST \
https://api.agent37.com/v1/instances/ab12cd34ef/update \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"template": "agent37-hermes@<tag>"
}'
import requests
response = requests.post(
"https://api.agent37.com/v1/instances/ab12cd34ef/update",
headers={
"Authorization": "Bearer sk_live_...",
"Content-Type": "application/json"
},
json={
"template": "agent37-hermes@<tag>"
},
)
response.raise_for_status()
print(response.json())
const response = await fetch(
"https://api.agent37.com/v1/instances/ab12cd34ef/update",
{
method: "POST",
headers: {
"Authorization": "Bearer sk_live_...",
"Content-Type": "application/json"
},
body: JSON.stringify({
"template": "agent37-hermes@<tag>"
}),
},
);
if (!response.ok) {
throw new Error(await response.text());
}
console.log(await response.json());
{
"id": "ab12cd34ef",
"status": "running",
"image_ref": "ghcr.io/agent37-platform/hermes:2026.10.05a",
"image_digest": "sha256:d3f6f28fae8128274b15256a3f17ecf6b2cc5e209db886def17f0595900a1045",
"template_revision": null
}
Authorization: Bearer sk_live_... on https://api.agent37.com.
Path parameters
string
required
The instance id, returned when you create an instance.
Request body
string
Optional template name or version pin. Omit it to re-resolve the stored template. See the behavior below for migration and pinning rules.
Behavior and errors
POST /v1/instances/{id}/update pulls the template’s image, resets the operating system layer to it, and preserves the data in /home/node and /home/linuxbrew. It is the one lifecycle call that discards changes outside those directories, which also makes it the clean-slate repair tool: use it to move an instance onto a newer version after a release (or after you point a workspace template at a new tag), or to recover a failed/stuck instance (read its logs first to see why it failed). A running or recoverable non-stopped instance is recreated and returns running; a stopped instance pulls the image pointer now and stays stopped, then uses that image the next time it starts.
The body is optional. Without one, update re-resolves the instance’s stored template: a workspace instance installs the template’s current image and revision, an unpinned system instance moves to the template’s current image, and a version-pinned instance stays on its pin. The one accepted field, template, takes any template name: the same template with an @<version>, a published tag on a system template or a published revision number on a workspace template, pins that release (this works on an unpinned instance too, and pinning an earlier workspace revision is the rollback), the bare name clears the pin to follow latest, and a different template migrates the instance onto it. A template migration keeps the instance’s id, URLs, public ports, and data, and the recreated container adopts the new template’s image, default port, and agent type; the instance keeps its shape, which every template offers. Any other field returns 400. The ack carries the resulting status, the applied template when one was passed, image_ref, image_digest, and template_revision. A sleeping instance is woken first and then updated, so it comes back running; while its checkpoint is still being written the call returns 409 try_again, so retry with backoff. A bad image reference on the template surfaces here as a 502 provisioning_failed.
curl
curl -X POST https://api.agent37.com/v1/instances/ab12cd34ef/update \
-H "Authorization: Bearer sk_live_..."
# -> { "id": "ab12cd34ef", "status": "running", "image_ref": "ghcr.io/acme/my-agent:v2", "image_digest": "sha256:9b2e...c41f", "template_revision": 2 }
# Set or move a version pin (or pass the bare name to clear it): a system tag,
# or a workspace revision like '{ "template": "my-agent@1" }' to roll back:
curl -X POST https://api.agent37.com/v1/instances/ab12cd34ef/update \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "template": "agent37-hermes@<tag>" }'
# Migrate the instance onto a different template (data kept, container recreated from the new image):
curl -X POST https://api.agent37.com/v1/instances/ab12cd34ef/update \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "template": "my-custom-agent" }'
# -> { "id": "ab12cd34ef", "status": "running", "template": "my-custom-agent", "image_ref": "ghcr.io/acme/my-agent:v2", "image_digest": "sha256:9b2e...c41f", "template_revision": 1 }