Skip to main content
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.
This operation destroys the source capsule after snapshotting it. Save any data you need before calling this endpoint — the capsule cannot be recovered afterward.

​
Endpoint

POST https://app.wrenn.dev/api/v1/snapshots

​
Authentication

​
X-API-Key
string
required
Your team’s API key. Pass the full wrn_... key value.

​
Query parameters

​
overwrite
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.

​
Request body

​
sandbox_id
string
required
The ID of the running capsule to snapshot (e.g., "cl-abc123"). The capsule must be in the running state.
​
name
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.

​
Example request

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"
  }'

{
  "sandbox_id": "cl-abc123",
  "name": "my-template"
}
The request body field is named sandbox_id for compatibility. Pass the capsule ID (prefixed cl-) as its value.

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

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

StatusMeaning
409 ConflictA template with that name already exists and ?overwrite=true was not set, or the capsule is not in the running state.