# Files

Assets, uploads, collections, versions and variants.

Scopes for this area: `files:read`, `files:write` and `files:admin`.

62 operations.

## asset

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/assets` | List assets with filters. | read | `rivier files asset list` |
| GET | `/assets/summary` | Counts by state and kind, with the brand's limits and use. | read | `rivier files asset summary` |
| GET | `/assets/expiring` | Assets whose rights lapse soon. | read | `rivier files asset expiring` |
| GET | `/assets/exists` | Is a checksum already held? | read | `rivier files asset exists` |
| GET | `/assets/used-by` | The assets a post, page or agent uses. | read | `rivier files asset used by` |
| POST | `/assets` | Upload a small file as a base64 body. | write | `rivier files asset create` |
| POST | `/assets/stream` | Upload a file as the request body, streamed. | write | `rivier files asset stream` |
| GET | `/assets/{id}` | One asset with its current version. | read | `rivier files asset get` |
| PATCH | `/assets/{id}` | Change an asset's name, description, tags, licence or disclosure. | write | `rivier files asset update` |
| DELETE | `/assets/{id}` | Move an asset to the bin, or purge it with ?purge=1. An asset still in use is refused (409 with where it is used) unless ?force=1. | write | `rivier files asset delete` |
| POST | `/assets/{id}/restore` | Take an asset out of the bin. | write | `rivier files asset restore` |
| GET | `/assets/{id}/content` | Download the bytes, with ranges. | read | `rivier files asset content` |
| POST | `/assets/{id}/link` | A signed, expiring download link. | write | `rivier files asset link` |
| POST | `/assets/{id}/revoke-links` | Invalidate every signed link of an asset. | write | `rivier files asset revoke links` |
| POST | `/assets/{id}/submit` | Send an asset for review. | write | `rivier files asset submit` |
| POST | `/assets/{id}/approve` | Approve an asset (a person's decision). | write | `rivier files asset approve` |
| POST | `/assets/{id}/reject` | Send an asset back with a reason. | write | `rivier files asset reject` |
| POST | `/assets/{id}/publish` | Give an approved asset its public address. | write | `rivier files asset publish` |
| POST | `/assets/{id}/unpublish` | Withdraw the public address. | write | `rivier files asset unpublish` |
| POST | `/assets/{id}/archive` | Archive an asset. | write | `rivier files asset archive` |
| POST | `/assets/{id}/reopen` | Reopen a rejected or archived asset as a draft. | write | `rivier files asset reopen` |
| POST | `/assets/{id}/process` | Work out a video or audio file's length, a still frame and a waveform and keep them beside it. Needs ffmpeg on the machine. | write | `rivier files asset process` |
| POST | `/assets/{id}/jobs` | Ask the media worker for a job on a published file: image sizes and formats with a placeholder and palette, audio peaks and stream, HLS with a sprite, or a transcript. The same version, kind and parameters share one result. | write | `rivier files asset job request` |
| GET | `/assets/{id}/jobs` | The media jobs of a file and where each stands (queued, claimed, processing, ready, failed). | read | `rivier files asset job list` |
| PUT | `/assets/{id}/media-facts` | Set chapters, captions, audio tracks or the transcript of a video or audio file. A model's drafts are held as unreviewed until a person reviews them. | write | `rivier files asset media facts` |
| POST | `/assets/{id}/transcribe` | Have a speech provider write the transcript of a video or audio file. It is saved marked as written by a model until a person has read it. | write | `rivier files asset transcribe` |
| POST | `/assets/{id}/stream` | Ask for adaptive streaming (HLS) of a video or audio file. The build host cuts it and reports back; until then, or where no runner is connected, the original file plays. | write | `rivier files asset adaptive` |
| POST | `/assets/{id}/stream/ready` | The build host's runner reports that a streaming job is done: the job and the https address of the manifest. | write | `rivier files asset adaptive ready` |
| PUT | `/assets/{id}/transcript` | Save the transcript of a video or audio file (text, optional timed segments); say when a model wrote it. | write | `rivier files asset transcript` |
| POST | `/assets/{id}/quick-publish` | Give an upload a licence of own, approve it and publish it, as far as the caller's role and the brand's rules allow; says where it stopped and why. | write | `rivier files asset quick publish` |
| GET | `/assets/{id}/usable` | Whether an asset may be used now, and why not. | read | `rivier files asset usable` |

## settings

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/assets/settings` | Limits and rules for the brand's files. | read | `rivier files settings get` |
| PUT | `/assets/settings` | Change limits and rules. | write | `rivier files settings update` |

## upload

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| POST | `/assets/uploads` | Start a resumable upload. | write | `rivier files upload begin` |
| GET | `/assets/uploads/{id}` | Progress of a resumable upload. | read | `rivier files upload get` |
| PUT | `/assets/uploads/{id}/parts/{n}` | Send one part of a resumable upload. | write | `rivier files upload part` |
| POST | `/assets/uploads/{id}/complete` | Finish a resumable upload. | write | `rivier files upload complete` |
| DELETE | `/assets/uploads/{id}` | Abandon a resumable upload. | write | `rivier files upload abort` |

## collection

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/assets/collections` | List collections. | read | `rivier files collection list` |
| POST | `/assets/collections` | Create a collection. | write | `rivier files collection create` |
| GET | `/assets/collections/{id}` | One collection with its assets. | read | `rivier files collection get` |
| PATCH | `/assets/collections/{id}` | Rename or describe a collection. | write | `rivier files collection update` |
| DELETE | `/assets/collections/{id}` | Delete a collection (its assets stay). | write | `rivier files collection delete` |
| PUT | `/assets/collections/{id}/items/{assetId}` | Put an asset in a collection. | write | `rivier files collection add item` |
| DELETE | `/assets/collections/{id}/items/{assetId}` | Take an asset out of a collection. | write | `rivier files collection remove item` |

## version

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/assets/{id}/versions` | The versions of an asset. | read | `rivier files version list` |
| POST | `/assets/{id}/versions` | Add a version from a base64 body. | write | `rivier files version create` |

## variant

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| POST | `/assets/{id}/variants/{label}` | Add a size, format or theme variant; the body is the file. | write | `rivier files variant add` |
| DELETE | `/assets/{id}/variants/{label}` | Remove a variant. | write | `rivier files variant remove` |

## gallery

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/galleries/{ownerKind}/{ownerId}` | The ordered pictures and files of a product, room type, service, property, unit, amenity, rate plan or content entry, with caption, alt text, focal point and whether each can show on the site. | read | `rivier files gallery get` |
| PUT | `/galleries/{ownerKind}/{ownerId}` | Replace the gallery of an item with this ordered list of library files. | write | `rivier files gallery set` |

## usage

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/assets/{id}/usage` | Where an asset is used. | read | `rivier files usage list` |
| POST | `/assets/{id}/usage` | Record that something uses an asset. | write | `rivier files usage record` |
| DELETE | `/assets/{id}/usage/{usageId}` | Remove a usage record. | write | `rivier files usage remove` |

## media

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| POST | `/galleries/suggest` | A suggested alt text, caption and tags for a stored picture, marked as made by AI. Nothing is saved. | write | `rivier files media suggest` |

## library

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/workspace/files` | The files the business keeps. | read | `rivier files library list` |
| GET | `/workspace/files/download` | Download a file. | read | `rivier files library download` |

## creative

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/creative/status` | Whether picture and video generation are connected for this project, and whether the plan allowance has room for one more of each. | read | `rivier files creative status` |
| GET | `/creative/generations` | Pictures and clips asked for, newest first, with their state: running, ready, refused or failed. | read | `rivier files creative list` |
| GET | `/creative/generations/{id}` | One generation. A running clip is checked with the provider before the answer, and a finished one is stored in the asset library as a draft for review. | read | `rivier files creative get` |
| POST | `/creative/images` | Generate a picture from a description. The brand kit is applied, the plan allowance is checked first, and the result is saved in the asset library as an AI-generated draft waiting for review. Answers 409 not_configured when no picture model is connected, and 422 safety_refusal when the provider declines the description. | write | `rivier files creative image` |
| POST | `/creative/videos` | Start a short clip from a description. A clip takes minutes: the answer is a running generation; read it until it is ready, and the clip is then in the asset library as an AI-generated draft waiting for review. | write | `rivier files creative video` |