> ## 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.

# Edit an instance

> Change an instance's labels, metadata, or auto-sleep settings without restarting it.

<RequestExample>
  ```bash curl wrap theme={null}
  curl -X PATCH \
    https://api.agent37.com/v1/instances/ab12cd34ef \
    -H "Authorization: Bearer sk_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Production agent",
      "user": "u_882",
      "metadata": {
        "plan": "pro"
      },
      "auto_sleep": true,
      "idle_timeout_seconds": 900
    }'
  ```

  ```python Python wrap theme={null}
  import requests

  response = requests.patch(
      "https://api.agent37.com/v1/instances/ab12cd34ef",
      headers={
          "Authorization": "Bearer sk_live_...",
      },
      json={
          "name": "Production agent",
          "user": "u_882",
          "metadata": {
              "plan": "pro",
          },
          "auto_sleep": True,
          "idle_timeout_seconds": 900,
      },
  )
  response.raise_for_status()
  print(response.json())
  ```

  ```javascript Node wrap theme={null}
  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",
        user: "u_882",
        metadata: {
          plan: "pro",
        },
        auto_sleep: true,
        idle_timeout_seconds: 900,
      }),
    },
  );
  if (!response.ok) {
    throw new Error(await response.text());
  }
  console.log(await response.json());
  ```
</RequestExample>

<ResponseExample>
  ```json 200 (excerpt) wrap theme={null}
  {
    "id": "ab12cd34ef",
    "name": "Production agent",
    "user": "u_882",
    "metadata": {
      "plan": "pro"
    },
    "auto_sleep": true,
    "idle_timeout_seconds": 900
  }
  ```
</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

The examples include every editable field. Send only the fields you want to change.

<ParamField body="name" type="string | null" post={["optional"]}>
  A label for the instance, up to 60 characters. `null` or `""` clears it.
</ParamField>

<ParamField body="user" type="string | null" post={["optional"]}>
  Your attribution tag, up to 200 characters. `null` or `""` clears it.
</ParamField>

<ParamField body="metadata" type="object | null" post={["optional"]}>
  Your key/value pairs, up to 4 KB serialized. The object replaces the stored one, it is not merged. `null` or `{}` clears it.
</ParamField>

<ParamField body="auto_sleep" type="boolean" post={["optional"]}>
  Turn [auto-sleep](/docs/agents-api/instance-auto-sleep) on or off. Takes effect within about half a minute, with no restart and no recreate.
</ParamField>

<ParamField body="idle_timeout_seconds" type="integer" post={["optional"]}>
  The new idle timeout: an integer from `300` to `86400` seconds.
</ParamField>

## Response

The response contains the full [instance object](/docs/agents-api/instances/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`, `user` tag, and `metadata` after creation, plus its [auto-sleep](/docs/agents-api/instance-auto-sleep) settings. 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`, `user`, `metadata`, `auto_sleep`, or `idle_timeout_seconds`; 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`.


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