Open a preview of a version
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.
apiKeyAuthorizationBearer <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.
endpoint*stringThe endpoint id: the first segment of its run.vlayers.ai URL.
application/json- body
versionId*stringThe id of the version to preview (from the agent's versions). It must carry an image and publish at least one endpoint.
uuidThe preview, and one single-use link per kind
application/json- response
preview*links*array<>tokenExpiresAt*stringdate-timeendedToMakeRoom*|uuidcurl -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" }'{ "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}