Assets

An asset is a file: an image, a video, an audio clip or a document. The API never carries the bytes: they go straight to object storage, and the API holds the record. Content, tenants and users reference an asset by id.

Public and private

visibility is chosen at upload and never changes.

	Used for	Delivered as
public	Atoms' media, sequence and cohort covers, surface pictures, tenant logos	A stable URL, safe to serve before sign-in
private	A user's avatar, a chat attachment	A short-lived signed URL, minted for each reader after their access is checked

Only public assets can be used in content, and only they carry tags. A private asset always belongs to the person it is about, and is reached only as that person's record is: by them, or by staff of their tenant while their consent stands.

Uploading

1. createAsset with the file's name, type, size and SHA-256. The asset comes back pending, with a URL and form fields for posting the bytes straight to storage.
2. Post the bytes there exactly as given.
3. completeAsset. The platform reads back what landed, checks the size against the ceiling for its kind, sniffs the real type against the allowed list (JPEG, PNG, WebP; MP4, WebM; MP3, M4A, AAC; PDF), checks the SHA-256, reads an image's dimensions, and marks the asset ready or failed. Renaming a file doesn't get it in. SVG is refused, because it can carry script.

Nothing can point at an asset until it is ready. replaceAssetBytes runs the same steps on an existing asset; the old bytes stay live until the new ones are proved, and every reference keeps working.

Using one

A reference is the asset's id. Reading the referencing record inlines the resolved assetUrl beside the id, derived at read time and never stored, so don't keep a URL beyond the screen it was fetched for. The apps play an atom's media by the address (see Atoms); a document has no player, so link to it from a button atom.

Deleting

A delete is refused with asset_in_use while any version of an atom names the asset. A surface, sequence cover or other column reference is cleared instead, and the item draws without a picture. Archive an asset to take it out of the picker and leave everything using it alone.