> For the complete documentation index, see [llms.txt](https://umber.gitbook.io/umber/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://umber.gitbook.io/umber/api-reference-v2/virtual-assets/versions.md). # Asset Versions API A version is the actual uploaded file behind a [Virtual Asset](/umber/concepts/virtual-assets.md) — the container holds identity and metadata, each version holds one file for one [target platform](/umber/concepts/asset-types.md). This reference covers creating, reading, listing and deleting versions of an existing virtual asset. Deploying a version to an environment, and reading back its deployed URL, is a separate API and a separate reference. {% hint style="info" %} This is a low-level HTTP reference. For adding a version through the dashboard, see [Adding a Version to an Existing Asset](/umber/guides/adding-a-version.md). For deployment state (Live/Default/Offline), see [Deployment States](/umber/concepts/deployment-states.md) and [Managing Deployments](/umber/guides/managing-deployments.md). {% endhint %} ## Base URL and authentication ``` https://api.umbercloud.io/api/v2/{domainId}/va/{assetId}/versions ``` `{assetId}` must be an existing, active virtual asset in the domain — every endpoint below returns `404` otherwise. Authenticate with the same `apikey` header as the [Virtual Assets API](/umber/api-reference-v2/virtual-assets.md#base-url-and-authentication). ## The version object | Field | Type | On create | Returned in responses | | ------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | | `versionId` | string | not accepted — generated as `{first 3 letters of the target platform, uppercased}{next sequence number for that platform}`, e.g. `AND1`, `IOS2`, `GEN3` | yes | | `version` | integer | not accepted — the numeric part of `versionId`, incrementing per platform | yes | | `versionName` | string, ≤ 64 chars | required | yes | | `targetPlatform` | string (a target platform code, e.g. `ios`) | required — passed as the `targetPlatformId` query param, not a body field | yes | | `assetType` | string (an [asset type](/umber/concepts/asset-types.md) code) | not accepted — inherited from the parent virtual asset | yes | | `secured` | boolean | not accepted — inherited from the parent virtual asset | yes | | `size` | string, e.g. `"2.35MB"` | not accepted — computed from the uploaded file | yes | | `fileName` | string | not accepted — taken from the uploaded file's own name | yes, when the version has one | | `uploadStatus` | `"Committed"` | not accepted — always `"Committed"` for this endpoint | yes | | `createdBy` | string (email) | required — must be the email of an active admin/owner user in your domain | yes | | `updatedBy` | string (email) | optional, defaults to `createdBy` | yes | | `active` | boolean | set to `true` automatically | yes | | `createdAt` / `updatedAt` | ISO 8601 timestamp | set automatically | yes | {% hint style="warning" %} The version's file location isn't part of any response in this reference — create, get and list all return the same field set above, with no `url`. To get a downloadable link once it's deployed to an environment, see [List deployed URLs for an environment](/umber/api-reference-v2/virtual-assets/version-deployment.md#list-deployed-urls-for-an-environment) or the parent asset's [asset-urls sub-resource](/umber/api-reference-v2/virtual-assets.md#list-an-assets-deployed-urls). {% endhint %} `fileName` is the uploaded file's own name. Versions created before the field existed don't carry one, so treat it as optional and don't key logic on its presence. `targetPlatform` is fixed for the life of the version — there's no endpoint to move it to a different platform afterward. Send the file as `Content-Type: multipart/form-data` with the file in a field named `assetFile`; a plain JSON body works for every other endpoint here. ## Errors Every error is a small JSON body, same shape as [the Virtual Assets API](/umber/api-reference-v2/virtual-assets.md#errors): ```json { "type": "https://docs.umbercloud.io/errors/asset-service", "title": "No Asset Version found for AND3", "status": 404, "detail": "No Asset Version found for AND3" } ``` | Status | Meaning | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | `createdBy` missing on create, or doesn't match an active admin/owner user in your domain; no file, or the file's type isn't allowed for the asset's type; delete attempted while the version is still Live or Default in some environment. | | `403` | Missing or invalid `apikey`, or your plan's storage/upload-size limit was hit. | | `404` | `assetId` doesn't exist, `targetPlatformId` doesn't match a known platform, or `versionId` doesn't exist under this asset. | | `500` | Unexpected server error. | ## Pagination Same envelope as [the Virtual Assets API](/umber/api-reference-v2/virtual-assets.md#pagination): ```json { "totalResults": 137, "pageNumber": 1, "pageSize": 50, "results": [] } ``` *** ## Create a version `POST /api/v2/{domainId}/va/{assetId}/versions?targetPlatformId={platformId}` ```bash curl -X POST "https://api.umbercloud.io/api/v2/acme-games/va/hero-skin-01/versions?targetPlatformId=android" \ -H "apikey: $ASSET_API_KEY" \ -F "assetFile=@hero-skin-01-v3.png" \ -F "versionName=Hero Skin 01 v3" \ -F "createdBy=dev@acme-games.com" ``` `201 Created` ```json { "version": 3, "versionId": "AND3", "versionName": "Hero Skin 01 v3", "assetType": "0001", "targetPlatform": "android", "createdBy": "dev@acme-games.com", "updatedBy": "dev@acme-games.com", "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "active": true, "secured": true, "size": "2.35MB", "fileName": "hero-skin-01.png", "uploadStatus": "Committed" } ``` ## Get a version `GET /api/v2/{domainId}/va/{assetId}/versions/{versionId}` ```bash curl "https://api.umbercloud.io/api/v2/acme-games/va/hero-skin-01/versions/AND3" \ -H "apikey: $ASSET_API_KEY" ``` `200 OK` ```json { "version": 3, "versionId": "AND3", "versionName": "Hero Skin 01 v3", "assetType": "0001", "targetPlatform": "android", "createdBy": "dev@acme-games.com", "updatedBy": "dev@acme-games.com", "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "active": true, "secured": true, "size": "2.35MB", "fileName": "hero-skin-01.png", "uploadStatus": "Committed" } ``` `404` if `versionId` doesn't exist under this asset. ## List versions `GET /api/v2/{domainId}/va/{assetId}/versions` ```bash curl "https://api.umbercloud.io/api/v2/acme-games/va/hero-skin-01/versions?pageNumber=1&pageSize=50" \ -H "apikey: $ASSET_API_KEY" ``` `200 OK` ```json { "totalResults": 2, "pageNumber": 1, "pageSize": 50, "results": [ { "version": 3, "versionId": "AND3", "versionName": "Hero Skin 01 v3", "assetType": "0001", "targetPlatform": "android", "createdBy": "dev@acme-games.com", "updatedBy": "dev@acme-games.com", "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "active": true, "secured": true, "size": "2.35MB", "fileName": "hero-skin-01.png", "uploadStatus": "Committed" }, { "version": 2, "versionId": "AND2", "versionName": "Hero Skin 01 v2", "assetType": "0001", "targetPlatform": "android", "createdBy": "dev@acme-games.com", "updatedBy": "dev@acme-games.com", "createdAt": "2026-08-20T09:30:00.000Z", "updatedAt": "2026-08-20T09:30:00.000Z", "active": true, "secured": true, "size": "2.10MB", "fileName": "hero-skin-01.png", "uploadStatus": "Committed" } ] } ``` There's no filtering — every call returns the asset's full set of versions, paginated. ## Delete a version `DELETE /api/v2/{domainId}/va/{assetId}/versions/{versionId}` This is a **hard delete** — no body is required. It fails if the version is currently Live or Default in any environment. ```bash curl -X DELETE "https://api.umbercloud.io/api/v2/acme-games/va/hero-skin-01/versions/AND3" \ -H "apikey: $ASSET_API_KEY" ``` `204 No Content` — no response body. `400` if it's still deployed anywhere — take it offline in every environment first (see [Deployment States](/umber/concepts/deployment-states.md)): ```json { "type": "https://docs.umbercloud.io/errors/asset-service", "title": "Please set this asset version 'Offline' in all Environments and then try to delete again.", "status": 400, "detail": "Please set this asset version 'Offline' in all Environments and then try to delete again." } ``` `404` if `versionId` doesn't exist under this asset. {% hint style="info" %} See [Deleting Assets and Versions](/umber/guides/deleting-assets-and-versions.md) for the equivalent dashboard flow. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://umber.gitbook.io/umber/api-reference-v2/virtual-assets/versions.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.