Sign in
assets

Upload a new asset

Uploads a new asset (binary content plus metadata) and registers it in the asset database.

post/api/assets

Request body

urlstring uri required

[cloud-only] URL of the file to import as an asset

namestring

Display name for the asset

tagsstring

Comma-separated tags

user_metadatastring

JSON-encoded user metadata

hashstring

Blake3 hash of the file content (e.g. blake3:abc123...)

mime_typestring

MIME type of the file (overrides auto-detected type)

preview_idstring uuid

ID of an existing asset to use as the preview image

idstring uuid nullable

[cloud-only] Client-supplied asset ID for idempotent creation. If an asset with this ID already exists, the existing asset is returned.

Response

Asset already exists (returned existing asset)

idstring uuid required

Unique identifier for the asset

namestring required

Name of the asset file

hashstring nullable

Blake3 content hash of the asset (preferred over asset_hash)

asset_hashstring nullable

Deprecated: use hash instead. Blake3 hash of the asset content.

sizeinteger required

Size of the asset in bytes

mime_typestring

MIME type of the asset

tagsstring[]

Tags associated with the asset

user_metadataobject

Custom user metadata

metadataobject

System-managed metadata (read-only)

preview_urlstring uri

URL for asset preview/thumbnail

preview_idstring uuid

ID of the preview asset if available

prompt_idstring uuid nullable

Deprecated: use job_id instead. ID of the prompt that created this asset.

job_idstring uuid nullable

ID of the job that created this asset

created_atstring date-time required
updated_atstring date-time required
last_access_timestring date-time
is_immutableboolean

Whether this asset is immutable

created_newboolean required

Whether this was a new creation (true) or returned existing (false)

Changes