Open a preview of a version

POST
/v1/endpoints/{endpoint}/previews

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.

Authorization

apiKey
headerAuthorizationBearer <token>

A secret API key from the dashboard (Developers → API keys): vl_live_…, or vl_test_… for test mode. Each operation says which scope the key needs.

Path Parameters

endpoint*string

The endpoint id: the first segment of its run.vlayers.ai URL.

Request Body

application/json
  1. body
versionId*string

The id of the version to preview (from the agent's versions). It must carry an image and publish at least one endpoint.

Formatuuid

Response Body

The preview, and one single-use link per kind

application/json
  1. response
preview*
links*array<>
tokenExpiresAt*string
Formatdate-time
endedToMakeRoom*|
Formatuuid
Example Request
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"  }'
Example Response
{  "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}