> ## Documentation Index
> Fetch the complete documentation index at: https://www.agent37.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Update an instance

> Apply a template image while preserving data in /home/node and /home/linuxbrew.

<RequestExample>
  ```bash curl wrap theme={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>"
    }'
  ```

  ```python Python wrap theme={null}
  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())
  ```

  ```javascript Node wrap theme={null}
  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());
  ```
</RequestExample>

<ResponseExample>
  ```json 200 wrap theme={null}
  {
    "id": "ab12cd34ef",
    "status": "running",
    "image_ref": "ghcr.io/agent37-platform/hermes:2026.10.05a",
    "image_digest": "sha256:d3f6f28fae8128274b15256a3f17ecf6b2cc5e209db886def17f0595900a1045",
    "template_revision": null
  }
  ```
</ResponseExample>

Authenticate with `Authorization: Bearer sk_live_...` on `https://api.agent37.com`.

## Path parameters

<ParamField path="id" type="string" required>
  The instance id, returned when you create an instance.
</ParamField>

## Request body

<ParamField body="template" type="string" post={["optional"]}>
  Optional template name or version pin. Omit it to re-resolve the stored template. See the behavior below for migration and pinning rules.
</ParamField>

## 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](/docs/agents-api/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](/docs/agents-api/templates#pin-a-template-version) 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`.

```bash curl wrap theme={null}
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 }
```

See [Instance lifecycle](/docs/agents-api/instance-lifecycle) for disk persistence and boot hooks. Retrieve the [instance object](/docs/agents-api/instances/get) for its full representation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.