> 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/collections/collection-items.md). # Collection Items API Items are the individual files inside a [Virtual Collection](/umber/concepts/virtual-collections.md) — a collection holds identity and configuration, each item holds one uploaded file, and an item can belong to more than one collection at once. This reference covers creating, reading, listing and removing items. Setting a collection's anchor item, moving/copying items between collections, and deploying a collection aren't covered here. {% hint style="info" %} This is a low-level HTTP reference. For collection-level operations (create/update/delete a collection), see the [Virtual Collections API](/umber/api-reference-v2/collections.md). {% endhint %} ## Base URL and authentication ``` https://api.umbercloud.io/api/v2/{domainId}/vc/{collectionId}/items ``` `{collectionId}` must be an existing virtual collection. Authenticate with the same `apikey` header as the [Virtual Assets API](/umber/api-reference-v2/virtual-assets.md#base-url-and-authentication). ## The item object | Field | Type | On create | Returned in responses | | ------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------- | | `assetItemId` | string | not accepted — generated automatically | yes | | `assetItemName` | string, ≤ 64 chars | required | yes | | `assetType` | string (an [asset type](/umber/concepts/asset-types.md) code, or `"9999"` for "Other") | required — must be one of the collection's allowed asset types, or `"9999"` | yes | | `mimetype` | string | not accepted — taken from the uploaded file | yes | | `size` | integer, raw bytes | not accepted — computed from the uploaded file | yes | | `fileName` | string | not accepted — taken from the uploaded file's name | yes | | `parentCollections` | array of collection id strings | not accepted — set to `[{collectionId}]` on create | 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 | | `uploadStatus` | `"Committed"` | not accepted — always `"Committed"` for this endpoint | yes | | `createdAt` / `updatedAt` | ISO 8601 timestamp | set automatically | yes | {% hint style="warning" %} `size` is a plain integer byte count for items — unlike [versions](/umber/api-reference-v2/virtual-assets/versions.md) and the [Virtual Assets API](/umber/api-reference-v2/virtual-assets.md), which return size as a formatted string like `"2.35MB"`. {% endhint %} There is no way to read an item's file location or download URL directly through this API — items are served through the parent collection's own deployed URL, not addressed individually. Send the file as `Content-Type: multipart/form-data` with the file in a field named `assetFile`; a plain JSON body works for removing an item. ## 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": "Asset Item not found", "status": 404, "detail": "Asset Item not found" } ``` | Status | Meaning | | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | `collectionId` doesn't exist or wasn't provided; the collection isn't editable; the collection's item limit is reached; `assetType` missing or not allowed in this collection; no file, or the file's type isn't allowed; `createdBy`/`deletedBy` missing. | | `403` | Missing or invalid `apikey`, or your plan's storage/upload-size limit was hit. | | `404` | The item doesn't exist, or exists but isn't a member of `{collectionId}`. | | `500` | Unexpected server error. | {% hint style="warning" %} A missing `collectionId` returns `400`, not `404` — the opposite of how a missing item itself is reported (`404`). Check the status code, not just the message, when handling a not-found case. {% endhint %} ## 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 an item `POST /api/v2/{domainId}/vc/{collectionId}/items` ```bash curl -X POST "https://api.umbercloud.io/api/v2/acme-games/vc/season-pass-bundle/items" \ -H "apikey: $ASSET_API_KEY" \ -F "assetFile=@banner.png" \ -F "assetItemName=Season Banner" \ -F "assetType=0001" \ -F "createdBy=dev@acme-games.com" ``` `201 Created` ```json { "assetItemId": "a1b2c3d4e5f6", "assetItemName": "Season Banner", "parentCollections": ["season-pass-bundle"], "domain": "acme-games", "assetType": "0001", "mimetype": "image/png", "createdBy": "dev@acme-games.com", "updatedBy": "dev@acme-games.com", "size": 245678, "fileName": "banner.png", "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "uploadStatus": "Committed" } ``` The item is added to the parent collection's item list as part of this call — it counts against the collection's item limit immediately. ## Get an item `GET /api/v2/{domainId}/vc/{collectionId}/items/{assetItemId}` ```bash curl "https://api.umbercloud.io/api/v2/acme-games/vc/season-pass-bundle/items/a1b2c3d4e5f6" \ -H "apikey: $ASSET_API_KEY" ``` `200 OK` — same shape as the create response. `404` if `assetItemId` doesn't exist, or exists but isn't a member of `{collectionId}`. ## List items `GET /api/v2/{domainId}/vc/{collectionId}/items` Query params: `pageNumber`, `pageSize`, `startDate`/`endDate` (filters on `createdAt`). ```bash curl "https://api.umbercloud.io/api/v2/acme-games/vc/season-pass-bundle/items?pageNumber=1&pageSize=50" \ -H "apikey: $ASSET_API_KEY" ``` `200 OK` ```json { "totalResults": 1, "pageNumber": 1, "pageSize": 50, "results": [ { "assetItemId": "a1b2c3d4e5f6", "assetItemName": "Season Banner", "parentCollections": ["season-pass-bundle"], "domain": "acme-games", "assetType": "0001", "mimetype": "image/png", "createdBy": "dev@acme-games.com", "updatedBy": "dev@acme-games.com", "size": 245678, "fileName": "banner.png", "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "uploadStatus": "Committed" } ] } ``` {% hint style="warning" %} The `updatable` and `shareable` query filters documented internally for this endpoint don't currently appear to work — a type mismatch between the query string and the stored field means they match nothing. Don't rely on them; filter client-side if you need this today. {% endhint %} ## Remove an item `DELETE /api/v2/{domainId}/vc/{collectionId}/items/{assetItemId}` This detaches the item from `{collectionId}` — including its deployed URLs and anchor status in that collection — rather than deleting the item outright. Requires `deletedBy` in the body. {% tabs %} {% tab title="JSON" %} ```json { "deletedBy": "dev@acme-games.com" } ``` {% endtab %} {% tab title="cURL" %} ```bash curl -X DELETE "https://api.umbercloud.io/api/v2/acme-games/vc/season-pass-bundle/items/a1b2c3d4e5f6" \ -H "apikey: $ASSET_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "deletedBy": "dev@acme-games.com" }' ``` {% endtab %} {% endtabs %} `200 OK` ```json { "message": "Asset Item removed successfully" } ``` `404` if the item doesn't exist or isn't currently a member of `{collectionId}`. {% hint style="warning" %} If `{collectionId}` was this item's last remaining collection, the item is fully removed from the active item store, not just detached — there's no "list orphaned items" endpoint in this API to find or restore it afterward. Make sure it's really the last reference you want before removing it. {% 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/collections/collection-items.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.