Overview
Upload files, store them public or private, and read back their URLs and dimensions.
Assets are stored files — images embedded in content, downloads, attachments. Upload is multipart, and whether the object is publicly readable is decided at upload time.
curl -X POST https://api.console.buildbase.app/api/assets \
-H "Authorization: $BUILDBASE_TOKEN" \
-F "[email protected]" \
-F "public=true"Before you start
Send the file under the field name file, one per request. public is read
as the string "true" — a JSON boolean in a multipart form will not
register, and the asset lands private.
Limits
| Constraint | Value |
|---|---|
| Maximum file size | 5 MB |
| Files per request | 1 |
| Accepted types | Any — no MIME allowlist |
A file over 5 MB is rejected by the upload middleware before the handler runs.
What is stored
| Field | Contents |
|---|---|
name | The original filename |
uniqueName | The generated storage name |
mimeType | Detected content type |
size | Bytes |
encoding | Transfer encoding |
bucket | { name, url, path } — where the object lives |
public | Whether the object URL is publicly readable |
image | { width, height } |
metadata | Empty object, reserved |
creator | The uploading user |
image dimensions are read from the file for image/* uploads only. For any
other type both values stay 0 — a 0 × 0 asset is a non-image, not a failed
upload.
Warning
Files are stored as uploaded. There is no resizing, format conversion, or thumbnail generation, and the URL is a plain object-storage URL with no transform parameters. Requesting a smaller version by appending query parameters does nothing.
If you need responsive images, generate the variants before uploading and store them as separate assets.
Public and private
Visibility is set at upload and can be changed afterwards:
| Method | Path | Effect |
|---|---|---|
PATCH | /api/assets/:id/public | Make the object publicly readable |
PATCH | /api/assets/:id/private | Restrict it again |
The two states write to different storage paths, so the URL changes when visibility changes. Anything already referencing the old URL breaks — update the references, or decide visibility before you publish the link.
Public means public: the object URL is unguessable but unauthenticated. Do not use it for anything you would gate behind a permission.
Reading
| Method | Path | Purpose |
|---|---|---|
GET | /api/assets | List assets, paginated |
GET | /api/assets/:id | One asset |
Filter with the standard parameters — by MIME type, for example:
curl -G https://api.console.buildbase.app/api/assets \
-H "Authorization: $BUILDBASE_TOKEN" \
--data-urlencode 'filter={"public":true}' \
--data-urlencode 'sort={"createdAt":-1}'Using an asset in content
Content stores the asset's URL, not the asset record. The two are linked only by that reference, so deleting an asset leaves a broken link in any post embedding it — nothing checks for inbound references first.
Check usage before deleting, or prefer making an asset private over removing it.