Assets API

All asset endpoints require authentication and are scoped to a vault.

Base path: /api/v1/vaults/{vaultId}/assets

Upload Asset

POST /api/v1/vaults/{vaultId}/assets
Content-Type: multipart/form-data

Parameters

Field	Type	Required	Description
`file`	File	Yes	The file to upload (max 100MB)
`partition`	string	Yes	Top-level category (e.g., `marketing`)
`collection`	string	Yes	Sub-category (e.g., `blog`)
`channel`	string	Yes	Specific grouping (e.g., `hero-images`)
`filename`	string	No	Override filename (defaults to uploaded name)
`metadata`	string	No	JSON object of custom metadata
`tags`	string	No	JSON array of tag strings

Path Component Rules

Lowercase alphanumeric characters and hyphens only
1–64 characters
Must start and end with alphanumeric character
Pattern: /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/

Response (201)

{
  "id": "asset_01abc...",
  "vault_id": "vault_01abc...",
  "partition": "marketing",
  "collection": "blog",
  "channel": "hero-images",
  "filename": "photo.jpg",
  "r2_key": "vault_01abc.../marketing/blog/hero-images/asset_01abc..._photo.jpg",
  "size": 245760,
  "mime_type": "image/jpeg",
  "width": null,
  "height": null,
  "metadata": "{}",
  "tags": "[]",
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:30:00Z"
}

List Assets

GET /api/v1/vaults/{vaultId}/assets

Query Parameters

Param	Type	Description
`partition`	string	Filter by partition
`collection`	string	Filter by collection
`channel`	string	Filter by channel
`cursor`	string	Pagination cursor from previous response
`limit`	number	Results per page (1–200, default 50)

Response (200)

{
  "data": [{ "id": "asset_...", ... }],
  "cursor": "eyJjcmVhdGVkX2F0...",
  "has_more": true
}

Get Asset

GET /api/v1/vaults/{vaultId}/assets/{assetId}

Returns a single asset record or 404 if not found.

Update Asset

PATCH /api/v1/vaults/{vaultId}/assets/{assetId}
Content-Type: application/json

Body

{
  "metadata": { "alt": "Hero image for blog post" },
  "tags": ["hero", "blog", "featured"]
}

metadata is merged with existing metadata
tags replaces the existing tags array
At least one field must be provided

Delete Asset

DELETE /api/v1/vaults/{vaultId}/assets/{assetId}

Returns 204 No Content on success. Deletes from both D1 metadata and R2 storage.

Assets API

On this page