# HTTP API

> Every route of the local HTTP API, generated from its OpenAPI document.

Source: https://alexgalhardo.github.io/vukem-video/pt-br/docs/reference/http-api/

The API is served at `/api/v1` by `vukem-video serve`, on `127.0.0.1:7878`. In local mode every route needs the bearer token from `<workspace>/token`; in [network mode](/docs/self-hosting/network-mode) a request carries a session cookie or an [API key](/docs/self-hosting/api-keys) instead, and the key scopes decide what it may do. Errors are `application/problem+json` with `code`, `message`, `hint` and `retryable`. The OpenAPI document itself is at `/openapi.json` while the server runs.

## audit

### `GET /audit`

List the audit table

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `cursor` | query | no | `string` |
| `limit` | query | no | `integer` |
| `project_id` | query | no | `string` |

Responses: `200` OK, `401`, `422`, `default`.

## brand-kit

### `GET /brand-kit`

Read the brand kit

Responses: `200` OK, `401`, `default`.

### `PUT /brand-kit`

Replace the brand kit

Request body:

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Name to #RRGGBB or #RRGGBBAA; at most 32. |
| `fonts` | `object` | no | Family to its files; at most 16 families, each file already in the font store. |
| `logo` | `string` | no | sha256: and 64 hex digits of an image asset of the workspace. |

Responses: `200` OK, `401`, `422`, `default`.

## commands

### `GET /commands`

List the commands

Responses: `200` OK, `401`, `default`.

### `GET /commands/{name}`

Explain one command

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `name` | path | yes | `string` |

Responses: `200` OK, `401`, `422`, `default`.

## fonts

### `GET /fonts`

List the bundled font families and weights

Responses: `200` OK, `401`, `default`.

### `POST /fonts`

Import a font file into the font store

Request body:

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `path` | `string` | yes | An absolute path to a TrueType or OpenType file on the machine that runs the server. |

Responses: `201` Created, `401`, `422`, `default`.

## handshake

### `GET /handshake`

Prove that the server knows the local token

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `nonce` | query | yes | `string` |

Responses: `200` OK, `401`, `422`, `default`.

## jobs

### `GET /jobs/{job_id}`

Read a job

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `wait_ms` | query | no | `integer` |
| `job_id` | path | yes | `string` |

Responses: `200` OK, `401`, `422`, `default`.

### `POST /jobs/{job_id}/cancel`

Cancel a job

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `job_id` | path | yes | `string` |

Request body:

| Property | Type | Required | Description |
| --- | --- | --- | --- |

Responses: `200` OK, `401`, `422`, `default`.

### `GET /jobs/{job_id}/file`

Download the file of a finished export

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `job_id` | path | yes | `string` |

Responses: `200` OK, `401`, `422`, `default`.

## keys

### `GET /keys`

List your API keys (a logged-in session only; network mode)

Responses: `200` OK, `401`, `default`.

### `POST /keys`

Create an API key (a logged-in session only; network mode)

Request body:

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `expires_in_days` | `integer` | no | 1 to 365, default 90; 1 to 30 with admin. |
| `name` | `string` | yes | 1 to 60 characters. |
| `project_id` | `string` | no | Limits the key to one project; not with admin. |
| `scopes` | array of `string` | yes | A non-empty subset of your scopes. |

Responses: `201` Created, `401`, `422`, `default`.

### `DELETE /keys/{key_id}`

Revoke an API key (a logged-in session only; network mode)

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `key_id` | path | yes | `string` |

Responses: `200` OK, `401`, `422`, `default`.

## projects

### `GET /projects`

List projects

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `state` | query | no | `string` |
| `cursor` | query | no | `string` |
| `limit` | query | no | `integer` |

Responses: `200` OK, `401`, `422`, `default`.

### `POST /projects`

Create a project

Request body:

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `dry_run` | `boolean` | no |  |
| `fps` | `string` | no | 30 (default); n or n/1001. |
| `id` | `string` | no | An id of your own; E_ID_EXISTS when taken. |
| `name` | `string` | yes | 1 to 120 characters. |
| `preset` | `string` | no | 9:16 (default), 1:1, 16:9 or 4:5. |

Responses: `201` Created, `401`, `422`, `default`.

### `GET /projects/{id}`

Read a project

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `detail` | query | no | `string` |
| `cursor` | query | no | `string` |
| `limit` | query | no | `integer` |
| `id` | path | yes | `string` |

Responses: `200` OK, `401`, `422`, `default`.

### `GET /projects/{id}/bitmaps/{key}`

Download a rasterized text or shape

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `id` | path | yes | `string` |
| `key` | path | yes | `string` |

Responses: `200` OK, `401`, `422`, `default`.

### `POST /projects/{id}/bundle`

Export a project as a .vvbundle

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `id` | path | yes | `string` |

Request body:

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `include_log` | `boolean or null` | no | false leaves the history out, to share a project without it. Default true. |
| `wait_ms` | `integer` | no | 0 to 25000: hold the call until the job is final. |

Responses: `202` Accepted, `401`, `422`, `default`.

### `POST /projects/{id}/edit`

Apply a batch of operations

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `id` | path | yes | `string` |

Request body:

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `base_revision` | `integer` | yes | The revision the batch was planned against. |
| `dry_run` | `boolean` | no |  |
| `idempotency_key` | `string` | no | 8 to 64 characters; the Idempotency-Key header is the same. |
| `operations` | array of `#/components/schemas/Operation` | yes | at least 1 items; at most 200 items |

Responses: `200` OK, `401`, `422`, `default`.

### `GET /projects/{id}/events`

Stream the events of a project

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `since` | query | no | `string` |
| `id` | path | yes | `string` |

Responses: `200` OK, `401`, `422`, `default`.

### `GET /projects/{id}/frame`

Render one frame

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `at` | query | no | `string` |
| `rev` | query | no | `integer` |
| `asset_id` | query | no | `string` |
| `max_tokens` | query | no | `integer` |
| `width` | query | no | `integer` |
| `id` | path | yes | `string` |

Responses: `200` OK, `401`, `422`, `default`.

### `GET /projects/{id}/history`

List the history of a project

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `actor` | query | no | `string` |
| `cursor` | query | no | `string` |
| `limit` | query | no | `integer` |
| `id` | path | yes | `string` |

Responses: `200` OK, `401`, `422`, `default`.

### `GET /projects/{id}/jobs`

List the jobs of a project

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `state` | query | no | `string` |
| `cursor` | query | no | `string` |
| `limit` | query | no | `integer` |
| `id` | path | yes | `string` |

Responses: `200` OK, `401`, `422`, `default`.

### `POST /projects/{id}/jobs`

Start a job

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `id` | path | yes | `string` |

Request body:

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `args` | `object` | no | The arguments of the kind: start, end and format (mp4, gif, wav or aac; default mp4) for an export. |
| `dry_run` | `boolean` | no |  |
| `kind` | `string` | yes | export. |
| `wait_ms` | `integer` | no | 0 to 25000: hold the call until the job is final. |

Responses: `202` Accepted, `401`, `422`, `default`.

### `GET /projects/{id}/lint`

Lint a project

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `severity` | query | no | `string` |
| `cursor` | query | no | `string` |
| `limit` | query | no | `integer` |
| `id` | path | yes | `string` |

Responses: `200` OK, `401`, `422`, `default`.

### `GET /projects/{id}/media`

List the assets of a project

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `cursor` | query | no | `string` |
| `limit` | query | no | `integer` |
| `id` | path | yes | `string` |

Responses: `200` OK, `401`, `422`, `default`.

### `POST /projects/{id}/media`

Import media files

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `id` | path | yes | `string` |

Request body:

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `dry_run` | `boolean` | no |  |
| `files` | array of `#/components/schemas/importFileIn` | yes | at least 1 items; at most 50 items |
| `wait_ms` | `integer` | no | 0 to 25000: hold the call until the assets are ready. |

Responses: `202` Accepted, `401`, `422`, `default`.

### `GET /projects/{id}/media/{asset_id}`

Inspect an asset

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `sections` | query | no | `string` |
| `min_silence` | query | no | `string` |
| `cursor` | query | no | `string` |
| `limit` | query | no | `integer` |
| `id` | path | yes | `string` |
| `asset_id` | path | yes | `string` |

Responses: `200` OK, `401`, `422`, `default`.

### `GET /projects/{id}/media/{asset_id}/peaks`

Download the audio peaks of an asset

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `id` | path | yes | `string` |
| `asset_id` | path | yes | `string` |

Responses: `200` OK, `401`, `422`, `default`.

### `GET /projects/{id}/media/{asset_id}/proxy`

Download the proxy of an asset

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `id` | path | yes | `string` |
| `asset_id` | path | yes | `string` |

Responses: `200` OK, `401`, `422`, `default`.

### `POST /projects/{id}/media/{asset_id}/restore`

Restore an asset from the trash

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `id` | path | yes | `string` |
| `asset_id` | path | yes | `string` |

Request body:

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `dry_run` | `boolean` | no |  |

Responses: `200` OK, `401`, `422`, `default`.

### `GET /projects/{id}/media/{asset_id}/strip`

Download the tile strip of an asset

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `id` | path | yes | `string` |
| `asset_id` | path | yes | `string` |

Responses: `200` OK, `401`, `422`, `default`.

### `GET /projects/{id}/media/{asset_id}/thumbnail`

Download a thumbnail of an asset

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `width` | query | no | `string` |
| `id` | path | yes | `string` |
| `asset_id` | path | yes | `string` |

Responses: `200` OK, `401`, `422`, `default`.

### `POST /projects/{id}/media/{asset_id}/trash`

Move an asset to the trash

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `id` | path | yes | `string` |
| `asset_id` | path | yes | `string` |

Request body:

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `dry_run` | `boolean` | no |  |

Responses: `200` OK, `401`, `422`, `default`.

### `GET /projects/{id}/otio`

Export a project as OpenTimelineIO

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `id` | path | yes | `string` |

Responses: `200` OK, `401`, `422`, `default`.

### `POST /projects/{id}/otio`

Import an OpenTimelineIO file into a project

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `id` | path | yes | `string` |

Request body:

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `base_revision` | `integer` | no | The revision the import is applied to. |
| `dry_run` | `boolean` | no |  |
| `path` | `string` | yes | An absolute path to an .otio file on the machine that runs the server. |

Responses: `200` OK, `401`, `422`, `default`.

### `GET /projects/{id}/plan`

Read the render plan of a window

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `from` | query | no | `integer` |
| `until` | query | no | `integer` |
| `to` | query | no | `integer` |
| `rev` | query | no | `integer` |
| `width` | query | no | `integer` |
| `id` | path | yes | `string` |

Responses: `200` OK, `401`, `422`, `default`.

### `POST /projects/{id}/redo`

Redo the caller's latest undone step

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `id` | path | yes | `string` |

Request body:

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `dry_run` | `boolean` | no |  |

Responses: `200` OK, `401`, `422`, `default`.

### `POST /projects/{id}/restore`

Restore a project from the trash

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `id` | path | yes | `string` |

Request body:

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `dry_run` | `boolean` | no |  |

Responses: `200` OK, `401`, `422`, `default`.

### `GET /projects/{id}/sheet`

Render a contact sheet

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `times` | query | no | `string` |
| `from` | query | no | `string` |
| `until` | query | no | `string` |
| `to` | query | no | `string` |
| `count` | query | no | `integer` |
| `cols` | query | no | `integer` |
| `rev` | query | no | `integer` |
| `asset_id` | query | no | `string` |
| `max_tokens` | query | no | `integer` |
| `id` | path | yes | `string` |

Responses: `200` OK, `401`, `422`, `default`.

### `GET /projects/{id}/snap-points`

Read the snap points and trim limits

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `rev` | query | no | `integer` |
| `words` | query | no | `integer` |
| `id` | path | yes | `string` |

Responses: `200` OK, `401`, `422`, `default`.

### `POST /projects/{id}/trash`

Move a project to the trash

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `id` | path | yes | `string` |

Request body:

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `dry_run` | `boolean` | no |  |

Responses: `200` OK, `401`, `422`, `default`.

### `POST /projects/{id}/undo`

Undo the caller's latest step

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `id` | path | yes | `string` |

Request body:

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `dry_run` | `boolean` | no |  |

Responses: `200` OK, `401`, `422`, `default`.

### `POST /projects/import`

Import a .vvbundle as a project

Request body:

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `as_new` | `boolean` | no | true makes a new project id and leaves the history out; false keeps the id. |
| `dry_run` | `boolean` | no |  |
| `path` | `string` | yes | An absolute path to a .vvbundle on the machine that runs the server. |

Responses: `201` Created, `401`, `422`, `default`.

## system

### `GET /system`

Read the diagnostic report

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `full` | query | no | `boolean` |
| `verify` | query | no | `boolean` |

Responses: `200` OK, `401`, `422`, `default`.

### `POST /system/launch`

Issue a one-time browser launch code

Responses: `200` OK, `401`, `default`.

### `GET /system/tools`

List the installed helpers and the install progress

Responses: `200` OK, `401`, `default`.

### `POST /system/tools/install`

Install the transcription helper

Request body:

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | `string` | no | The model, one the manifest of this build pins; default small. |
| `name` | `string` | yes | The tool to install, for example whisper. |

Responses: `202` Accepted, `401`, `422`, `default`.

## templates

### `GET /templates`

List the templates

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `cursor` | query | no | `string` |
| `limit` | query | no | `integer` |

Responses: `200` OK, `401`, `422`, `default`.

### `POST /templates`

Save a project as a template

Request body:

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | `string` | no |  |
| `dry_run` | `boolean` | no |  |
| `name` | `string` | yes |  |
| `project_id` | `string` | yes |  |

Responses: `201` Created, `401`, `422`, `default`.

### `POST /templates/{template_id}/export`

Write the file of a template

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `template_id` | path | yes | `string` |

Request body:

| Property | Type | Required | Description |
| --- | --- | --- | --- |

Responses: `200` OK, `401`, `422`, `default`.

### `GET /templates/{template_id}/file`

Download the file of a template

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `template_id` | path | yes | `string` |

Responses: `200` OK, `401`, `422`, `default`.

### `POST /templates/{template_id}/instantiate`

Make a project from a template

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `template_id` | path | yes | `string` |

Request body:

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `brand_colors` | array of `string` | no | Names of template colours that take the colour of the brand kit. |
| `brand_fonts` | array of `string` | no | Families of the brand kit added to the fonts of the project. |
| `dry_run` | `boolean` | no |  |
| `fill` | `object` | no | Slot name to a value: one of asset_id, text or words. |
| `id` | `string` | no | Optional project id; local mode only. |
| `name` | `string` | yes |  |

Responses: `201` Created, `401`, `422`, `default`.

### `POST /templates/import`

Import a template file

Request body:

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `dry_run` | `boolean` | no |  |
| `path` | `string` | yes | An absolute path to a template file on the machine that runs the server. |

Responses: `201` Created, `401`, `422`, `default`.

## trash

### `POST /trash/empty`

Empty the trash for good

Request body:

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `older_than_days` | `integer` | no | Empty only what has been in the trash this many days. |
| `project_id` | `string` | no | Empty only this trashed project. |

Responses: `200` OK, `401`, `422`, `default`.

## users

### `GET /users`

List the users (an administrator session only; network mode)

Responses: `200` OK, `401`, `default`.

### `POST /users`

Create a user (an administrator session only; network mode)

Request body:

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | `string` | yes | A plain mailbox; it is lower-cased and must be unused. |
| `password` | `string` | yes | 12 to 1,024 characters. |
| `role` | `string` | no | admin or member; default member. |

Responses: `201` Created, `401`, `422`, `default`.

### `PATCH /users/{user_id}`

Change the role of a user or disable or enable them (an administrator session only; network mode)

| Parameter | In | Required | Type |
| --- | --- | --- | --- |
| `user_id` | path | yes | `string` |

Request body:

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean or null` | no | True disables the user; false enables them again. |
| `role` | `string or null` | no | admin or member. |

Responses: `200` OK, `401`, `422`, `default`.
