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

# POST /v1/snapshots — Create a capsule snapshot template

> POST /v1/snapshots — Snapshot a running capsule into a reusable template. The capsule is paused and destroyed; use the template name to boot new capsules.

Use this endpoint to capture a running capsule as a reusable snapshot template. The server pauses the capsule, copies its full snapshot (VM state, memory, and root filesystem) to the images directory, then destroys the source capsule. The resulting template can be passed as the `template` parameter when creating new capsules.

<Warning>
  This operation destroys the source capsule after snapshotting it. Save any data you need before calling this endpoint — the capsule cannot be recovered afterward.
</Warning>

## Endpoint

```http theme={null}
POST https://app.wrenn.dev/api/v1/snapshots
```

## Authentication

<ParamField header="X-API-Key" type="string" required>
  Your team's API key. Pass the full `wrn_...` key value.
</ParamField>

## Query parameters

<ParamField query="overwrite" type="string">
  Set to `"true"` to overwrite an existing snapshot template with the same name. Without this parameter, the request returns `409` if the name is already in use.
</ParamField>

## Request body

<ParamField body="sandbox_id" type="string" required>
  The ID of the running capsule to snapshot (e.g., `"cl-abc123"`). The capsule must be in the `running` state.
</ParamField>

<ParamField body="name" type="string">
  A name for the snapshot template. Used as the `template` value when creating capsules from this snapshot. If omitted, a name is auto-generated.
</ParamField>

### Example request

```bash theme={null}
curl -X POST "https://app.wrenn.dev/api/v1/snapshots?overwrite=true" \
  -H "X-API-Key: wrn_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "sandbox_id": "cl-abc123",
    "name": "my-template"
  }'
```

```json theme={null}
{
  "sandbox_id": "cl-abc123",
  "name": "my-template"
}
```

<Note>
  The request body field is named `sandbox_id` for compatibility. Pass the capsule ID (prefixed `cl-`) as its value.
</Note>

````

## Response

Returns `201 Created` with a `Template` object.

<ResponseField name="name" type="string" required>
  The name of the snapshot template. Use this value as the `template` parameter when creating new capsules.
</ResponseField>

<ResponseField name="type" type="string" required>
  Always `"snapshot"` for templates created via this endpoint.
</ResponseField>

<ResponseField name="vcpus" type="integer">
  Number of vCPUs captured in the snapshot. May be `null` for base templates.
</ResponseField>

<ResponseField name="memory_mb" type="integer">
  Memory in MiB captured in the snapshot. May be `null` for base templates.
</ResponseField>

<ResponseField name="size_bytes" type="integer">
  Total size of the snapshot files on disk, in bytes.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 timestamp of when the snapshot was created.
</ResponseField>

### Example response

```json
{
  "name": "my-template",
  "type": "snapshot",
  "vcpus": 2,
  "memory_mb": 1024,
  "size_bytes": 536870912,
  "created_at": "2024-11-01T10:00:00Z"
}
````

## Python SDK

```python theme={null}
from wrenn import Capsule

with Capsule(template="base-python", wait=True) as capsule:
    # ... set up your environment ...

    # Snapshot the capsule into a reusable template
    # Note: this destroys the capsule
    template = capsule.create_snapshot(name="my-template", overwrite=True)
    print(template.name)        # "my-template"
    print(template.size_bytes)  # 536870912
```

## Error responses

| Status         | Meaning                                                                                                                   |
| -------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `409 Conflict` | A template with that name already exists and `?overwrite=true` was not set, or the capsule is not in the `running` state. |