Skip to content

Reference

HTTP API

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

Last updated:

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 a request carries a session cookie or an API key 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

ParameterInRequiredType
cursorquerynostring
limitquerynointeger
project_idquerynostring

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:

PropertyTypeRequiredDescription
colorsobjectnoName to #RRGGBB or #RRGGBBAA; at most 32.
fontsobjectnoFamily to its files; at most 16 families, each file already in the font store.
logostringnosha256: 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

ParameterInRequiredType
namepathyesstring

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:

PropertyTypeRequiredDescription
pathstringyesAn 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

ParameterInRequiredType
noncequeryyesstring

Responses: 200 OK, 401, 422, default.

jobs#

GET /jobs/{job_id}#

Read a job

ParameterInRequiredType
wait_msquerynointeger
job_idpathyesstring

Responses: 200 OK, 401, 422, default.

POST /jobs/{job_id}/cancel#

Cancel a job

ParameterInRequiredType
job_idpathyesstring

Request body:

PropertyTypeRequiredDescription

Responses: 200 OK, 401, 422, default.

GET /jobs/{job_id}/file#

Download the file of a finished export

ParameterInRequiredType
job_idpathyesstring

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:

PropertyTypeRequiredDescription
expires_in_daysintegerno1 to 365, default 90; 1 to 30 with admin.
namestringyes1 to 60 characters.
project_idstringnoLimits the key to one project; not with admin.
scopesarray of stringyesA 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)

ParameterInRequiredType
key_idpathyesstring

Responses: 200 OK, 401, 422, default.

projects#

GET /projects#

List projects

ParameterInRequiredType
statequerynostring
cursorquerynostring
limitquerynointeger

Responses: 200 OK, 401, 422, default.

POST /projects#

Create a project

Request body:

PropertyTypeRequiredDescription
dry_runbooleanno
fpsstringno30 (default); n or n/1001.
idstringnoAn id of your own; E_ID_EXISTS when taken.
namestringyes1 to 120 characters.
presetstringno9:16 (default), 1:1, 16:9 or 4:5.

Responses: 201 Created, 401, 422, default.

GET /projects/{id}#

Read a project

ParameterInRequiredType
detailquerynostring
cursorquerynostring
limitquerynointeger
idpathyesstring

Responses: 200 OK, 401, 422, default.

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

Download a rasterized text or shape

ParameterInRequiredType
idpathyesstring
keypathyesstring

Responses: 200 OK, 401, 422, default.

POST /projects/{id}/bundle#

Export a project as a .vvbundle

ParameterInRequiredType
idpathyesstring

Request body:

PropertyTypeRequiredDescription
include_logboolean or nullnofalse leaves the history out, to share a project without it. Default true.
wait_msintegerno0 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

ParameterInRequiredType
idpathyesstring

Request body:

PropertyTypeRequiredDescription
base_revisionintegeryesThe revision the batch was planned against.
dry_runbooleanno
idempotency_keystringno8 to 64 characters; the Idempotency-Key header is the same.
operationsarray of #/components/schemas/Operationyesat least 1 items; at most 200 items

Responses: 200 OK, 401, 422, default.

GET /projects/{id}/events#

Stream the events of a project

ParameterInRequiredType
sincequerynostring
idpathyesstring

Responses: 200 OK, 401, 422, default.

GET /projects/{id}/frame#

Render one frame

ParameterInRequiredType
atquerynostring
revquerynointeger
asset_idquerynostring
max_tokensquerynointeger
widthquerynointeger
idpathyesstring

Responses: 200 OK, 401, 422, default.

GET /projects/{id}/history#

List the history of a project

ParameterInRequiredType
actorquerynostring
cursorquerynostring
limitquerynointeger
idpathyesstring

Responses: 200 OK, 401, 422, default.

GET /projects/{id}/jobs#

List the jobs of a project

ParameterInRequiredType
statequerynostring
cursorquerynostring
limitquerynointeger
idpathyesstring

Responses: 200 OK, 401, 422, default.

POST /projects/{id}/jobs#

Start a job

ParameterInRequiredType
idpathyesstring

Request body:

PropertyTypeRequiredDescription
argsobjectnoThe arguments of the kind: start, end and format (mp4, gif, wav or aac; default mp4) for an export.
dry_runbooleanno
kindstringyesexport.
wait_msintegerno0 to 25000: hold the call until the job is final.

Responses: 202 Accepted, 401, 422, default.

GET /projects/{id}/lint#

Lint a project

ParameterInRequiredType
severityquerynostring
cursorquerynostring
limitquerynointeger
idpathyesstring

Responses: 200 OK, 401, 422, default.

GET /projects/{id}/media#

List the assets of a project

ParameterInRequiredType
cursorquerynostring
limitquerynointeger
idpathyesstring

Responses: 200 OK, 401, 422, default.

POST /projects/{id}/media#

Import media files

ParameterInRequiredType
idpathyesstring

Request body:

PropertyTypeRequiredDescription
dry_runbooleanno
filesarray of #/components/schemas/importFileInyesat least 1 items; at most 50 items
wait_msintegerno0 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

ParameterInRequiredType
sectionsquerynostring
min_silencequerynostring
cursorquerynostring
limitquerynointeger
idpathyesstring
asset_idpathyesstring

Responses: 200 OK, 401, 422, default.

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

Download the audio peaks of an asset

ParameterInRequiredType
idpathyesstring
asset_idpathyesstring

Responses: 200 OK, 401, 422, default.

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

Download the proxy of an asset

ParameterInRequiredType
idpathyesstring
asset_idpathyesstring

Responses: 200 OK, 401, 422, default.

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

Restore an asset from the trash

ParameterInRequiredType
idpathyesstring
asset_idpathyesstring

Request body:

PropertyTypeRequiredDescription
dry_runbooleanno

Responses: 200 OK, 401, 422, default.

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

Download the tile strip of an asset

ParameterInRequiredType
idpathyesstring
asset_idpathyesstring

Responses: 200 OK, 401, 422, default.

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

Download a thumbnail of an asset

ParameterInRequiredType
widthquerynostring
idpathyesstring
asset_idpathyesstring

Responses: 200 OK, 401, 422, default.

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

Move an asset to the trash

ParameterInRequiredType
idpathyesstring
asset_idpathyesstring

Request body:

PropertyTypeRequiredDescription
dry_runbooleanno

Responses: 200 OK, 401, 422, default.

GET /projects/{id}/otio#

Export a project as OpenTimelineIO

ParameterInRequiredType
idpathyesstring

Responses: 200 OK, 401, 422, default.

POST /projects/{id}/otio#

Import an OpenTimelineIO file into a project

ParameterInRequiredType
idpathyesstring

Request body:

PropertyTypeRequiredDescription
base_revisionintegernoThe revision the import is applied to.
dry_runbooleanno
pathstringyesAn 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

ParameterInRequiredType
fromquerynointeger
untilquerynointeger
toquerynointeger
revquerynointeger
widthquerynointeger
idpathyesstring

Responses: 200 OK, 401, 422, default.

POST /projects/{id}/redo#

Redo the caller's latest undone step

ParameterInRequiredType
idpathyesstring

Request body:

PropertyTypeRequiredDescription
dry_runbooleanno

Responses: 200 OK, 401, 422, default.

POST /projects/{id}/restore#

Restore a project from the trash

ParameterInRequiredType
idpathyesstring

Request body:

PropertyTypeRequiredDescription
dry_runbooleanno

Responses: 200 OK, 401, 422, default.

GET /projects/{id}/sheet#

Render a contact sheet

ParameterInRequiredType
timesquerynostring
fromquerynostring
untilquerynostring
toquerynostring
countquerynointeger
colsquerynointeger
revquerynointeger
asset_idquerynostring
max_tokensquerynointeger
idpathyesstring

Responses: 200 OK, 401, 422, default.

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

Read the snap points and trim limits

ParameterInRequiredType
revquerynointeger
wordsquerynointeger
idpathyesstring

Responses: 200 OK, 401, 422, default.

POST /projects/{id}/trash#

Move a project to the trash

ParameterInRequiredType
idpathyesstring

Request body:

PropertyTypeRequiredDescription
dry_runbooleanno

Responses: 200 OK, 401, 422, default.

POST /projects/{id}/undo#

Undo the caller's latest step

ParameterInRequiredType
idpathyesstring

Request body:

PropertyTypeRequiredDescription
dry_runbooleanno

Responses: 200 OK, 401, 422, default.

POST /projects/import#

Import a .vvbundle as a project

Request body:

PropertyTypeRequiredDescription
as_newbooleannotrue makes a new project id and leaves the history out; false keeps the id.
dry_runbooleanno
pathstringyesAn 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

ParameterInRequiredType
fullquerynoboolean
verifyquerynoboolean

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:

PropertyTypeRequiredDescription
modelstringnoThe model, one the manifest of this build pins; default small.
namestringyesThe tool to install, for example whisper.

Responses: 202 Accepted, 401, 422, default.

templates#

GET /templates#

List the templates

ParameterInRequiredType
cursorquerynostring
limitquerynointeger

Responses: 200 OK, 401, 422, default.

POST /templates#

Save a project as a template

Request body:

PropertyTypeRequiredDescription
descriptionstringno
dry_runbooleanno
namestringyes
project_idstringyes

Responses: 201 Created, 401, 422, default.

POST /templates/{template_id}/export#

Write the file of a template

ParameterInRequiredType
template_idpathyesstring

Request body:

PropertyTypeRequiredDescription

Responses: 200 OK, 401, 422, default.

GET /templates/{template_id}/file#

Download the file of a template

ParameterInRequiredType
template_idpathyesstring

Responses: 200 OK, 401, 422, default.

POST /templates/{template_id}/instantiate#

Make a project from a template

ParameterInRequiredType
template_idpathyesstring

Request body:

PropertyTypeRequiredDescription
brand_colorsarray of stringnoNames of template colours that take the colour of the brand kit.
brand_fontsarray of stringnoFamilies of the brand kit added to the fonts of the project.
dry_runbooleanno
fillobjectnoSlot name to a value: one of asset_id, text or words.
idstringnoOptional project id; local mode only.
namestringyes

Responses: 201 Created, 401, 422, default.

POST /templates/import#

Import a template file

Request body:

PropertyTypeRequiredDescription
dry_runbooleanno
pathstringyesAn 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:

PropertyTypeRequiredDescription
older_than_daysintegernoEmpty only what has been in the trash this many days.
project_idstringnoEmpty 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:

PropertyTypeRequiredDescription
emailstringyesA plain mailbox; it is lower-cased and must be unused.
passwordstringyes12 to 1,024 characters.
rolestringnoadmin 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)

ParameterInRequiredType
user_idpathyesstring

Request body:

PropertyTypeRequiredDescription
disabledboolean or nullnoTrue disables the user; false enables them again.
rolestring or nullnoadmin or member.

Responses: 200 OK, 401, 422, default.