Assets & Folders

Assets are the images you upload to Vizco. Folders let you organize assets for easier management.

Assets

An asset is an uploaded image file with associated metadata. When you upload a file, Vizco stores it in S3-compatible storage and records its properties.

Asset properties

Name	Type	Default	Description
`id`	UUID	—	Unique identifier
`filename`	string	—	Original or custom filename
`originalUrl`	string	—	Direct URL to the original file
`contentType`	string	—	MIME type (e.g. image/jpeg)
`sizeBytes`	number	—	File size in bytes
`width`	number	—	Image width in pixels
`height`	number	—	Image height in pixels
`altText`	string	—	Accessibility description
`tags`	string[]	—	Searchable tags
`metadata`	JSON	—	Custom key-value metadata
`folderId`	UUID \| null	—	Folder the asset belongs to, or null if unfiled

Uploading

Upload images as multipart form data:

POST/api/projects/{projectId}/assetsJWT

curl -X POST https://your-api.com/api/projects/{projectId}/assets \
-H "Authorization: Bearer {token}" \
-F "file=@photo.jpg"

Updating metadata

You can update the filename, alt text, tags, and custom metadata after upload:

Request body

{
"filename": "hero-banner.jpg",
"altText": "A scenic mountain landscape",
"tags": ["hero", "landscape", "featured"],
"metadata": { "photographer": "Jane Doe" }
}

Asset delivery

Individual assets can be delivered via CDN with on-the-fly transformations:

GET/api/v1/deliver/{projectId}/{assetId}

Query parameters allow resizing and format conversion:

# Resize to 800px wide, convert to webp
https://your-api.com/api/v1/deliver/{projectId}/{assetId}?w=800&format=webp

Response includes immutable cache headers: Cache-Control: public, max-age=31536000, immutable

Folders

Folders are an organizational tool for grouping related assets. They have no effect on widgets — widgets reference assets directly via an ordered list of asset IDs.

Folder properties

Name	Type	Default	Description
`id`	UUID	—	Unique identifier
`name`*	string	—	Display name
`slug`*	string	—	URL-friendly identifier, unique per project
`description`	string	—	Optional description

Moving assets into folders

Assets can be moved into a folder. An asset belongs to at most one folder at a time.

POST/api/projects/{projectId}/folders/{folderId}/assetsJWT

Move assets

{
"assetIds": [
  "550e8400-e29b-41d4-a716-446655440000",
  "660e8400-e29b-41d4-a716-446655440001"
]
}

DELETE/api/projects/{projectId}/folders/{folderId}/assets/{assetId}JWT

Moving an asset to a different folder or removing it from a folder does not affect any widgets that reference the asset.

On this page