Publish an image as a version

POST
/v1/agents/{id}/versions

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.

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

id*string

The agent id.

Request Body

application/json
  1. body
manifestHash*string

The hash of the manifest you uploaded for this build (64 lowercase hex characters).

Match^[0-9a-f]{64}$
image*string

The pushed image, by digest: sha256:… or registry.vlayers.ai/<workspace>/<agent>@sha256:…. A tag is refused.

Length1 <= length <= 512
note?string

A note kept with the version (up to 500 characters).

Lengthlength <= 500

Response Body

Accepted: the version waits for its room to register

application/json
  1. response
status*
warnings*array<string>
Example Request
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"  }'
Example Response
{  "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": []}