Publish an image as a version
Creates a new version of the agent that runs a pushed image, and starts its rooms. Give the manifest you uploaded for this build and the image by digest (sha256:…, or registry.vlayers.ai/<workspace>/<agent>@sha256:…); a tag is refused with tag_refused, because a tag can move. The answer is 202: the version goes live once its first room has registered, and GET /v1/agents/{id}/versions/{version}/publish-status tells you how it is going. A scan with findings still publishes and records them.
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.
id*stringThe agent id.
application/json- body
manifestHash*stringThe hash of the manifest you uploaded for this build (64 lowercase hex characters).
^[0-9a-f]{64}$image*stringThe pushed image, by digest: sha256:… or registry.vlayers.ai/<workspace>/<agent>@sha256:…. A tag is refused.
1 <= length <= 512note?stringA note kept with the version (up to 500 characters).
length <= 500Accepted: the version waits for its room to register
application/json- response
status*warnings*array<string>curl -X POST "https://api.vlayers.ai/v1/agents/$AGENT_ID/versions" \ -H "Authorization: Bearer $VOICELAYER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "manifestHash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "image": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "note": "Handle refunds" }'{ "status": { "version": 3, "versionId": "0192f5d5-9cad-7ebf-9a4b-5c6d7e8f9012", "state": "waiting", "image": { "digest": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "repository": "registry.vlayers.ai/0192f5a1-5e6f-7a7b-8c8d-9e0f1a2b3c45/0192f5c2-6f7a-7b9c-8d1e-2f3a4b5c6d78", "workspaceId": "0192f5a1-5e6f-7a7b-8c8d-9e0f1a2b3c45", "agentId": "0192f5c2-6f7a-7b9c-8d1e-2f3a4b5c6d78", "pushedAt": "2026-10-20T15:04:05.000Z", "sizeBytes": 148000000, "platform": "linux/amd64", "scan": { "status": "complete", "scanner": "trivy", "scannedAt": "2026-10-20T15:04:05.000Z", "findings": { "critical": 0, "high": 1, "medium": 4, "low": 9, "unknown": 0 }, "reportRef": null, "error": null }, "sbom": { "format": "spdx-json", "ref": "sbom/0123456789ab.json" }, "referencedBy": 1 }, "rooms": [ { "id": "room_0192f5d4-8b9c-7dae-8f3a-4b5c6d7e8f90", "state": "starting", "stateChangedAt": "2026-10-20T15:04:05.000Z" } ], "failure": null }, "warnings": []}