Upload and manage files

Upload, list, fetch, update, move, delete, and restore assets through the Storage API.

Every file in Storage is an asset: the bytes plus metadata like its name, folder, visibility, alt text, and tags. This page covers the management operations you run against the asset API. All of them go through the gateway at https://api.revenexx.com/v1/storage and carry the auth headers X-Revenexx-Api-Key (or Authorization: Bearer) and X-Revenexx-Tenant.

Upload a file

Send one multipart/form-data request. The file part is required. The rest is optional metadata you can also change later.

curl -X POST https://api.revenexx.com/v1/storage/assets \
  -H "X-Revenexx-Api-Key: <API_KEY>" \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -F "file=@./datasheet.pdf" \
  -F "folder_id=<FOLDER_ID>" \
  -F "visibility=private" \
  -F "display_name=Product datasheet" \
  -F "tags=spec,2026"

The fields you can send with an upload:

FieldDescription
fileThe file to upload. Required.
folder_idFolder to place the asset in. Defaults to the tenant root.
visibilitypublic or private. Public assets are served without auth; private ones need a signed URL.
display_nameA human-friendly name, up to 255 characters.
alt_textAlternative text for images, up to 1000 characters.
descriptionA longer description.
tagsOne or more tags, comma-separated or repeated. Each tag is up to 64 characters.

A single file can be up to 96 MiB. The SDKs and a plain multipart request both work; there is no separate chunked-upload protocol to implement. For large recurring imports, use SFTP sync instead.

The response carries the asset id. Keep it: every operation below addresses an asset by its id.

Upload several files at once

To upload a batch in one request, post to the bulk endpoint with repeated files[] parts. A batch is up to 20 files and 200 MiB total. The response is a multi-status report, one entry per file, so you can see which succeeded and which didn't.

Bash
curl -X POST https://api.revenexx.com/v1/storage/assets/bulk \
  -H "X-Revenexx-Api-Key: <API_KEY>" \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -F "files[]=@./a.jpg" \
  -F "files[]=@./b.jpg" \
  -F "folder_id=<FOLDER_ID>"

List files

List assets in the tenant, with filtering, search, sorting, and pagination. Return at most 200 per page.

Bash
curl "https://api.revenexx.com/v1/storage/assets?filter[folder_id]=<FOLDER_ID>&sort=-created_at&limit=50" \
  -H "X-Revenexx-Api-Key: <API_KEY>" \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>"

Filter with filter[folder_id], filter[kind], filter[status] and a filter[created_at][gte]/[lte] range, pass a search term, sort with sort (created_at, size_bytes or original_name; a leading - reverses), and page with limit and page. Storage uses this filter[...]/sort/page form rather than the ?field=value/order/offset form most services take; see Pagination & filtering.

Get one file's metadata

Bash
curl https://api.revenexx.com/v1/storage/assets/<ASSET_ID> \
  -H "X-Revenexx-Api-Key: <API_KEY>" \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>"

This returns metadata, not bytes. To serve the file to end users, link to its delivery path. To pull the original bytes from a backend, use the download endpoint below.

Download the original

Streams the original, untransformed file. Useful for server-side processing.

Bash
curl https://api.revenexx.com/v1/storage/assets/<ASSET_ID>/download \
  -H "X-Revenexx-Api-Key: <API_KEY>" \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -o datasheet.pdf

Update metadata, rename, or move

A PATCH updates any metadata field. To rename a file, set name. To move it to another folder, set folder_id.

Bash
curl -X PATCH https://api.revenexx.com/v1/storage/assets/<ASSET_ID> \
  -H "X-Revenexx-Api-Key: <API_KEY>" \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "Content-Type: application/json" \
  -d '{ "display_name": "2026 datasheet", "folder_id": "<NEW_FOLDER_ID>", "visibility": "public" }'

You can change display_name, alt_text, description, visibility, tags, folder_id (move), and name (rename).

Delete and restore

Deleting an asset is a soft delete: the file is hidden and scheduled for removal, but recoverable for a retention window (30 days by default).

Bash
curl -X DELETE https://api.revenexx.com/v1/storage/assets/<ASSET_ID> \
  -H "X-Revenexx-Api-Key: <API_KEY>" \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>"

Restore a soft-deleted asset within the retention window:

Bash
curl -X POST https://api.revenexx.com/v1/storage/assets/<ASSET_ID>/restore \
  -H "X-Revenexx-Api-Key: <API_KEY>" \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>"

To erase an asset for good, call DELETE /v1/storage/assets/<ASSET_ID>/permanent. It works on live and soft-deleted assets, removes the stored file, and returns its bytes to your used storage. This cannot be undone: there is no restore afterwards, and links to the asset stop resolving at once. The call needs an administrator-level key.

Unpack an archive

POST /v1/storage/assets/<ASSET_ID>/unpack adds the files inside an archive asset as separate assets. The archive must already be uploaded and must be a supported archive type.

Bash
curl -X POST https://api.revenexx.com/v1/storage/assets/<ASSET_ID>/unpack \
  -H "X-Revenexx-Api-Key: <API_KEY>" \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "Content-Type: application/json" \
  -d '{ "target_folder_id": "<FOLDER_ID>", "keep_archive": true }'
  • The files land in a folder named after the archive. It is created under target_folder_id, or under the archive's own folder when you omit it. The archive's internal folder structure is kept inside that folder.
  • Each file is checked like any upload. A file that fails is skipped, and the rest continue.
  • keep_archive decides whether the archive asset itself survives. It defaults to true.
  • The call answers 202 once the work is queued. Check the folder or the asset list for the results.

Storage usage

GET /v1/storage/tenant/usage reports the bytes in use, the byte quota (null when the tenant has no cap) and how many assets the tenant holds. Soft-deleted assets still count until they are permanently deleted.

Bash
curl https://api.revenexx.com/v1/storage/tenant/usage \
  -H "X-Revenexx-Api-Key: <API_KEY>" \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>"

GET /v1/storage/tenant/stats breaks the library down by asset kind (image, video, audio, pdf, document, archive, model3d, other), with a count and a byte total for each kind that has assets. It is a dashboard figure: it names no asset and cannot be filtered.

Allowed file types

Storage accepts common image, video, document, audio, archive, data, and 3D model formats. For safety, executable types (such as exe, dll, sh, bat, jar, app, dmg, msi) are rejected regardless of the declared content type.

What's next

Was this page helpful?