> ## 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/capsules — Create a capsule

> POST /v1/capsules — Create a new capsule. Accepts template, vcpus, memory_mb, and timeout_sec. Returns the capsule object with its ID and status.

Use this endpoint to provision a new microVM capsule for your team. The capsule starts in `pending` status and transitions to `starting`, then `running` as the VM boots. All fields are optional — omit them to accept the defaults (`minimal` template, 1 vCPU, 512 MiB RAM, no auto-pause).

## Endpoint

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

## Authentication

Pass your API key in the `X-API-Key` header. You can generate a key in the Wrenn dashboard.

```http theme={null}
X-API-Key: wrn_your_key
```

## Request body

<ParamField body="template" type="string" default="minimal">
  Name of the base template or snapshot template to boot from. Defaults to `"minimal"`.
</ParamField>

<ParamField body="vcpus" type="integer" default="1">
  Number of virtual CPUs to allocate to the capsule.
</ParamField>

<ParamField body="memory_mb" type="integer" default="512">
  Memory to allocate, in MiB.
</ParamField>

<ParamField body="timeout_sec" type="integer" default="0">
  Inactivity TTL in seconds. The capsule is automatically paused after this many seconds with no exec calls or pings. Set to `0` to disable auto-pause.
</ParamField>

### Example request body

```json theme={null}
{
  "template": "base-python",
  "vcpus": 2,
  "memory_mb": 1024,
  "timeout_sec": 300
}
```

## Response

Returns a `201 Created` with the capsule object.

<ResponseField name="id" type="string" required>
  Unique capsule ID. Always prefixed with `cl-` (e.g., `"cl-abc123"`).
</ResponseField>

<ResponseField name="status" type="string" required>
  Current lifecycle status. One of: `pending`, `starting`, `running`, `paused`, `stopped`, `error`.
</ResponseField>

<ResponseField name="template" type="string" required>
  Name of the template used to create the capsule.
</ResponseField>

<ResponseField name="vcpus" type="integer" required>
  Number of virtual CPUs allocated.
</ResponseField>

<ResponseField name="memory_mb" type="integer" required>
  Memory allocated, in MiB.
</ResponseField>

<ResponseField name="timeout_sec" type="integer" required>
  Inactivity TTL in seconds. `0` means auto-pause is disabled.
</ResponseField>

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

<ResponseField name="last_updated" type="string" required>
  ISO 8601 timestamp of the most recent status change.
</ResponseField>

<ResponseField name="started_at" type="string">
  ISO 8601 timestamp of when the capsule last reached `running` status. `null` until the VM has booted at least once.
</ResponseField>

<ResponseField name="last_active_at" type="string">
  ISO 8601 timestamp of the last exec call or ping. Used to calculate the auto-pause TTL.
</ResponseField>

### Example response

```json theme={null}
{
  "id": "cl-abc123",
  "status": "starting",
  "template": "base-python",
  "vcpus": 2,
  "memory_mb": 1024,
  "timeout_sec": 300,
  "created_at": "2024-11-01T10:00:00Z",
  "started_at": null,
  "last_active_at": null,
  "last_updated": "2024-11-01T10:00:00Z"
}
```

## curl

```bash theme={null}
curl --request POST \
  --url https://app.wrenn.dev/api/v1/capsules \
  --header 'X-API-Key: wrn_your_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "template": "base-python",
    "vcpus": 2,
    "memory_mb": 1024,
    "timeout_sec": 300
  }'
```

## Python SDK

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

capsule = Capsule(
    template="base-python",
    vcpus=2,
    memory_mb=1024,
    timeout=300,
    wait=True,  # block until status is "running"
)
print(capsule.id)      # "cl-abc123"
print(capsule.status)  # "running"
```

<Note>
  Pass `wait=True` to block until the capsule reaches `running` status before your code continues. Without it, `status` will be `"pending"` or `"starting"` immediately after the call.
</Note>

## Error responses

| Status             | Code | Description                                                                            |
| ------------------ | ---- | -------------------------------------------------------------------------------------- |
| `401 Unauthorized` | —    | Missing or invalid `X-API-Key`.                                                        |
| `502 Bad Gateway`  | —    | The host agent returned an error while provisioning the VM. Retry after a short delay. |