# Start a live preview of a branch Koidog produced.

> A task's branch (`taskId`), or a managed crew's integration branch (`crewId` alone).
> https://koi.dog/docs/api/previews/create-preview/

`POST /api/v1/previews` · Scope: `crews`

Starts or reuses a cloud VM under the crew's budget and limits, so it can cost money. Asking again for the same commit answers the same preview. When an API key calls it, the timeline records who did what and the outcome. No path or query parameters.

## Headers.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | `string` | no | Makes a retry safe: the same key with the same request returns the first answer and does nothing else. |

## Body.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `crewId` | `string` | yes | The crew whose branch to preview. At least 5 characters. |
| `taskId` | `string` | no | Preview this task's branch. Absent: the crew's integration branch (managed crews). At least 5 characters. |
| `access` | `enum` | no | `private`: the URL carries an access token. `public`: no token; it needs an approval first. Default `private`. |
| `ttlMinutes` | `5–240` | no | Koidog stops it after this long. Default `30`. |

## Response.

201 Created: a `Preview`. The example has placeholder values.

- **409**: Refused with `409` and the reason when it cannot run (no preview command on the project, cloud not connected, a Mac-only crew, the budget).
- **422 validation_failed**: The body does not match its schema; each problem is in `details`.

## Request.

```sh
curl -X POST https://app.koi.dog/api/v1/previews \
    -H "Authorization: Bearer $KOIDOG_API_KEY" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{
      "crewId": "crw_1m7h6entrgqb9z64svs"
    }'
```

```js
const res = await fetch("https://app.koi.dog/api/v1/previews", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KOIDOG_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    crewId: "crw_1m7h6entrgqb9z64svs",
  }),
});
console.log(await res.json());
```

```python
import os
import uuid

import requests

r = requests.post(
    "https://app.koi.dog/api/v1/previews",
    headers={
        "Authorization": f"Bearer {os.environ['KOIDOG_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "crewId": "crw_1m7h6entrgqb9z64svs",
    },
)
r.raise_for_status()
print(r.json())
```

## Response example.

```json
{
  "id": "string",
  "crewId": "string",
  "projectId": "string",
  "branch": "string",
  "sha": "string",
  "where": "boat",
  "access": "private",
  "state": "pending_approval",
  "stateReason": "string",
  "stage": "string",
  "url": "string",
  "origin": "string",
  "vmId": "string",
  "port": 0,
  …
}
```
