Skip to main content
The POST /v1/objects endpoint lets you upload a file to Virtus Cloud Blob storage. Once uploaded, your file is distributed through the Virtus Cloud CDN and immediately accessible via the URL returned in the response. You control the file’s name, optional prefix, expiration window, and download behavior through query parameters. Endpoint: POST https://blob.virtuscloud.app/v1/objects
The maximum supported file size is 100 MB. Files smaller than 1 KB are rejected. Support for larger files is planned for a future release.

​
Authentication

Include your API key in the Authorization header: 
Authorization: <your-api-key>
See the Authentication page for details.

​
Request Parameters

The request body must use multipart/form-data encoding.

​
Body

​
file
file
required
The file to upload. Send this as a multipart/form-data field. Maximum size is 100 MB; minimum size is 1 KB.

​
Query Parameters

​
name
string
required
A name for the uploaded file, without a file extension. Must be 3–32 characters long and contain only letters (a–z, A–Z), digits (0–9), and underscores (_).
​
prefix
string
An optional organizational prefix for the file. Must be 3–32 characters long and contain only letters (a–z, A–Z), digits (0–9), and underscores (_). Use prefixes to group related files together.
​
expire
number
Optional number of days until the file expires and is automatically deleted. Must be an integer between 1 and 365. If omitted, the file does not expire.
​
security_hash
boolean
Set to true to append a security hash to the file’s URL. This makes the URL harder to guess and prevents unauthorized access via enumeration. Defaults to false.
​
auto_download
boolean
Set to true to configure the file URL so that browsers automatically trigger a file download instead of rendering the file inline. Defaults to false.

​
Example Request

curl -X POST "https://blob.virtuscloud.app/v1/objects?name=my_photo&expire=30&security_hash=true" \
  -H "Authorization: <your-api-key>" \
  -F "file=@/path/to/photo.png"

​
Response

​
status
string
Indicates whether the request succeeded. Returns "success" on success or "error" on failure.
​
response
object
Example Response
{
  "status": "success",
  "response": {
    "id": "3155597145698959364/test_lxch4k7y-07ee.png",
    "name": "test",
    "size": 416230,
    "url": "https://public-blob.virtuscloud.dev/3155597145698959364/test_lxch4k7y-07ee.png"
  }
}

​
Troubleshooting

A 400 response means one or more of your request parameters failed validation.Object parameter errors:
// The name contains disallowed characters or is outside 3–32 characters.
{
  "status": "error",
  "code": "INVALID_OBJECT_NAME"
}
File errors:
The current maximum file size is 100 MB. Virtus Cloud plans to raise this limit in the future, but the CDN currently enforces the 100 MB cap.
// The file field is missing or the uploaded data is corrupt.
{
  "status": "error",
  "code": "INVALID_FILE"
}