assets

POST /assets

Upload bytes. Idempotent on content.

R34, Q14. The body is the raw bytes. The daemon hashes them, writes `<name>.tmp`, fsyncs and renames into the blob store (06 §4), then makes the library hardlink. When the sha256 already exists, nothing is stored and the existing asset is returned with 200. Either way the caller gains read access to it (Q9). `pinned=true` pins; nothing unpins. Images are probed for width and height; video and audio take the hints given (Q13). A body over the upload limit is 413 `too_large` with `details.limit`; a body the disk cannot hold, with the same headroom rule as weight downloads, is 507 `disk_space` (`QuotaExceeded`: out of room, do not retry) before anything is written (M4 first review, #16, second review #9; the limit's value is still open). The check uses the request's Content-Length when it is sent. An asset stays out of reclaim until an item or item input first references it (M4 first review, #3).

Needs the assets capability.

Request body: string (*/*)

GET /assets/{id}

The asset's bytes, with Range.

R37. Readable by the rules in Q9; anything else is 404. `ETag` is the sha256. A single byte range answers 206; an unsatisfiable one 416 (`Invalid`). When the row exists and its file does not, 410 `asset_missing`. Needs the Bearer header; a studio's page loads it through the runtime SDK's same-origin proxy, which adds the header, as `/helm/api/v1/assets/{id}` (M6 Q10).

Needs the assets capability.

GET /assets/{id}/lineage

Downstream provenance — every item ever made from this asset, recursively.

02 §8, Q16. Follows `item_inputs` from the asset to the items that used it, then from each of those items' assets onward. Other studios' items are left out unless the caller holds `gallery.read_all`; the walk still passes through them, so a later own item is found. Ordered `created_at` descending. Soft-deleted items are left out of the result, and the walk passes through them too.

Needs the gallery capability.

GET /assets/{id}/thumb

A thumbnail, generated once and cached.

R36, Q13. Images only in M4; video and audio answer 501 `unsupported` until the ffmpeg decision. The only width is 320 (02 §5's `thumb-320`). Needs the Bearer header; a studio's page loads it through the runtime SDK's same-origin proxy, as `/helm/api/v1/assets/{id}/thumb` (M6 Q10).

Needs the assets capability.

POST /assets:adopt

Adopt a file from the stage or data directory by hardlink — no copy, no HTTP body.

R34, 07 §4, Q10 as amended by the M4 first review (#4), Q11. **Where the file may be.** `path` must resolve, with no symlink in it, inside the caller's stage directory (`HELM_STAGE_DIR`, `paths.stage`) or its data directory (`{data}`, `paths.data`). Anywhere else is 422 `outside_roots`. It must be a regular file (422 `not_a_file`). **What happens to it.** The file is hardlinked into the blob store and made read-only (0444). - From stage, the stage entry is then unlinked. - From data, the studio's file stays where it is. It is the blob's inode, so it is read-only too. **When the bytes already exist.** Nothing is stored and the existing asset returns with 200 (02 §7). A stage entry is unlinked; a data file is left alone. **Adoption never copies.** A blob hardlink that fails across volumes is 422 `cross_device`, and the file is left in place. A library hardlink that fails across volumes still adopts, with `library_path` null and a warning. An asset stays out of reclaim until an item or item input first references it (M4 first review, #3).

Needs the assets capability.

Request body: AdoptRequest (application/json)