# Publish an image as a version

Source: https://docs.vlayers.ai/reference/hosting/submit-hosted-version

`POST /v1/agents/{id}/versions` · scope `workspace:write`

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.

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | The agent id. Example: `"0192f5c2-6f7a-7b9c-8d1e-2f3a4b5c6d78"` |
| `manifestHash` | body | string | yes | The hash of the manifest you uploaded for this build (64 lowercase hex characters). |
| `image` | body | string | yes | The pushed image, by digest: `sha256:…` or `registry.vlayers.ai/<workspace>/<agent>@sha256:…`. A tag is refused. |
| `note` | body | string | no | A note kept with the version (up to 500 characters). |

## Request

cURL:

```bash
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"
  }'
```

TypeScript:

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

const voicelayer = new VoiceLayer();

const { status } = await voicelayer.hosting.submitHostedVersion('<agent-id>', {
  manifestHash: '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
  image: 'sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
  note: 'Handle refunds'
});
console.log(status.state);
```

Python:

```python
from voicelayer import VoiceLayer

vl = VoiceLayer()

result = vl.hosting.submit_hosted_version(
    "<agent-id>",
    manifest_hash="0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    image="sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    note="Handle refunds",
)
print(result.status.state)
```

## Response `202`

```json
{
  "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": []
}
```
