# Open a preview of a version

Source: https://docs.vlayers.ai/reference/hosting/open-endpoint-preview

`POST /v1/endpoints/{endpoint}/previews` · scope `workspace:write`

Opens a preview of one version of the endpoint's agent, at `run.vlayers.ai/<endpoint>--<version>/<kind>`, for your workspace alone, or finds the one already open. The answer carries one link per kind with a token that works for 60 seconds and opens once: follow it in the browser that should hold the preview's cookie (`HttpOnly`, `Secure`, `SameSite=Strict`, scoped to that preview). The first request after the preview has been idle waits for its room for a few seconds, and otherwise answers 503 `starting`. If the workspace is at its limit of previews, the oldest idle one ends to make room (`endedToMakeRoom`); when none is idle the call is refused with 422 and the reason `preview_limit`.

Requires an API key with the `workspace:write` scope.

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `endpoint` | path | string | yes | The endpoint id: the first segment of its `run.vlayers.ai` URL. Example: `"x7k2p4q9m3vd"` |
| `versionId` | body | string | yes | The id of the version to preview (from the agent's versions). It must carry an image and publish at least one endpoint. |

## Request

cURL:

```bash
curl -X POST "https://api.vlayers.ai/v1/endpoints/$ENDPOINT_ID/previews" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "versionId": "0e9d8c7b-6a5f-4e3d-8c1b-0a9f8e7d6c5b"
  }'
```

TypeScript:

```ts
import { VoiceLayer } from '@voicelayer/api';

const voicelayer = new VoiceLayer();

const { links } = await voicelayer.hosting.openEndpointPreview('<endpoint-id>', {
  versionId: '0e9d8c7b-6a5f-4e3d-8c1b-0a9f8e7d6c5b'
});
console.log(links);
```

Python:

```python
from voicelayer import VoiceLayer

vl = VoiceLayer()

result = vl.hosting.open_endpoint_preview(
    "<endpoint-id>",
    version_id="0e9d8c7b-6a5f-4e3d-8c1b-0a9f8e7d6c5b",
)
print(result.links)
```

## Response `201`

```json
{
  "preview": {
    "id": "0192f5c1-5e6f-7a8b-9c0d-1e2f3a4b5c67",
    "endpointId": "x7k2p4q9m3vd",
    "agentId": "0192f5c2-6f7a-7b9c-8d1e-2f3a4b5c6d78",
    "environment": "dev",
    "versionId": "0192f5c2-6f7a-7b9c-8d1e-2f3a4b5c6d78",
    "state": "asleep",
    "createdAt": "2026-10-20T15:04:05.000Z",
    "expiresAt": "2026-10-20T15:04:05.000Z",
    "lastRequestAt": "2026-10-20T15:04:05.000Z",
    "sleepsAt": null,
    "endedAt": null,
    "endedReason": null,
    "endedMessage": null,
    "routes": [
      {
        "kind": "api",
        "url": "https://run.vlayers.ai/x7k2p4q9m3vd--0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b/api"
      }
    ]
  },
  "links": [
    {
      "kind": "api",
      "url": "https://run.vlayers.ai/x7k2p4q9m3vd--0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b/api?vl_preview=<single-use token>"
    }
  ],
  "tokenExpiresAt": "2026-10-20T15:04:05.000Z",
  "endedToMakeRoom": null
}
```
