API

Let tools on the local network list files at each stage from Delivery to On Servers, set a file’s programming status, note and flag, and start and check Distribution jobs.

Enabling the API

The API defaults to off and is turned on with the enable switch in the API section of Settings. Volare then listens on every network address the workstation has, at the port set there (default 3100).

To change the port, type the new one and press Enter or click out of the field.

Identifying a file

A file is identified by its path inside Staged, or inside Delivery if it hasn’t been staged yet. Files in Delivery can’t be changed through the API. For a file at D:\Show\Staged\Song_01\Intro_v02.mov, either of these works:

• Song_01/Intro_v02.mov
• Intro_v02.mov

Leave out the Staged (or Delivery) folder itself and anything above it. File paths are case-insensitive, and forward or back slashes both work.

If two folders in Staged hold a file with the same name, looking it up returns both. To change one of them, send enough of its path to pick it out, such as Song_01/Intro_v02.mov instead of Intro_v02.mov. Otherwise Volare changes nothing and answers with both paths.

Finding files

Method	Route
GET	/assets

Returns files by path, by where they are on their journey, or both. A path on its own looks in Staged. A search that matches nothing returns an empty list.

Query parameters

Send path, location or both.

Name	Type	Required	Description
path	String	No	Any trailing part of the file’s path, URI encoded. See Identifying a file.
location	String	No	inDelivery, staged, syncing or onServers: every file at that stage.

Request

const VOLARE = "http://192.168.30.151:3100";
const path = encodeURIComponent("Song_01/Intro_v02.mov");
const res = await fetch(`${VOLARE}/assets?path=${path}`);
const { assets } = await res.json();

To list every file in Delivery:

const res = await fetch(`${VOLARE}/assets?location=inDelivery`);

Response

Returns 200 OK with an assets list of Asset objects.

{
  "assets": [
    {
      "id": "6c1d0f9e-2b7a-4e35-9d84-0a3f5c2e7b19",
      "path": "Song_01/Intro_v02.mov",
      "location": "staged",
      "originalName": "Intro_IN120_OUT1920_v02.mov",
      "programmingStatus": "needsReview",
      "inFrame": 120,
      "outFrame": 1920,
      "holdFrame": null,
      "flagged": false,
      "notes": null,
      "errorCheck": {
        "codec": "pass",
        "resolution": "pass",
        "frameRate": "pass",
        "sampleRate": "pass",
        "bitDepth": "pass",
        "channels": "fail"
      }
    }
  ]
}

Setting the programming status

Method	Route
PUT	/assets/programming-status

Sets a file’s programming status to needsProgramming, needsReview, programmed or notUsed.

Body

Name	Type	Required	Description
path	String	Yes	Identifies one file in Staged. See Identifying a file.
status	String	Yes	needsProgramming, needsReview, programmed or notUsed.

Request

const VOLARE = "http://192.168.30.151:3100";
const res = await fetch(`${VOLARE}/assets/programming-status`, {
  method: "PUT",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ path: "Song_01/Intro_v02.mov", status: "programmed" }),
});
const asset = await res.json();

Response

Returns 200 OK with the updated Asset object.

Flagging a file

Method	Route
PUT	/assets/flag

Flags a file or clears its flag.

Body

Name	Type	Required	Description
path	String	Yes	Identifies one file in Staged. See Identifying a file.
flagged	Boolean	Yes	true flags the file; false clears the flag.

Request

const VOLARE = "http://192.168.30.151:3100";
const res = await fetch(`${VOLARE}/assets/flag`, {
  method: "PUT",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ path: "Song_01/Intro_v02.mov", flagged: true }),
});
const asset = await res.json();

Response

Returns 200 OK with the updated Asset object.

Setting the note

Method	Route
PUT	/assets/notes

Sets a file’s note.

Body

Name	Type	Required	Description
path	String	Yes	Identifies one file in Staged. See Identifying a file.
notes	String	Yes	The whole note, replacing the old one. "" clears it.

Request

const VOLARE = "http://192.168.30.151:3100";
const res = await fetch(`${VOLARE}/assets/notes`, {
  method: "PUT",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    path: "Song_01/Intro_v02.mov",
    notes: "Frame glitch at frame 279",
  }),
});
const asset = await res.json();

Response

Returns 200 OK with the updated Asset object. A cleared note comes back as null.

Starting a Distribution job

Method	Route
POST	/distribution/runs

Starts a Distribution job.

Body

Name	Type	Required	Description
jobId	String	Yes	The 8 characters at the top right of the job’s Details section on the Distribution page.

Request

const VOLARE = "http://192.168.30.151:3100";
const res = await fetch(`${VOLARE}/distribution/runs`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ jobId: "a8f6eb77" }),
});
const { runId } = await res.json();

Response

Returns 200 OK with the new run’s ID.

{
  "started": true,
  "runId": "9d2f4a61-0c3e-4b7a-8e15-6a0b2c7d1f48"
}

Checking a Distribution job

Method	Route
GET	/distribution/runs

Returns the job’s most recent run: the one in progress, or the last one if nothing is running.

Query parameters

Name	Type	Required	Description
jobId	String	Yes	The 8 characters at the top right of the job’s Details section on the Distribution page.

Request

const VOLARE = "http://192.168.30.151:3100";
const res = await fetch(`${VOLARE}/distribution/runs?jobId=a8f6eb77`);
const { run } = await res.json();

Response

Returns 200 OK with the job’s latest run. A job that has never run returns { "run": null }.

{
  "run": {
    "runId": "9d2f4a61-0c3e-4b7a-8e15-6a0b2c7d1f48",
    "jobName": "Show VideoFile",
    "state": "completed",
    "trigger": "api",
    "startedAt": "2026-11-05T14:02:11.000Z",
    "finishedAt": "2026-11-05T14:05:40.000Z"
  }
}

Property	Type	Description
runId	String	The run’s ID, as returned when it was started through the API.
jobName	String	The job’s name.
state	String	running, completed, failed or cancelled.
trigger	String	What started it: manual (the Distribution page), schedule or api.
startedAt	String	When the run started, in UTC (ISO 8601).
finishedAt	String or null	When the run ended, in UTC (ISO 8601). null while it’s running.

The Asset object

Property	Type	Description
id	String	The file’s ID in Volare.
path	String or null	The file’s full path under the folder it’s in: Delivery for a file in Delivery, otherwise under Staged.
location	String	Where the file is on its journey: inDelivery, staged, syncing or onServers.
originalName	String	The name the file had when Volare first detected it.
programmingStatus	String or null	needsProgramming, needsReview, programmed or notUsed.
inFrame	Number or null	The frame from the file’s In tag.
outFrame	Number or null	The frame from the file’s Out tag.
holdFrame	Number or null	The frame from the file’s Hold tag.
flagged	Boolean	true when the file is flagged.
notes	String or null	The file’s note.
errorCheck	Object or null	Each check’s result, pass, fail or unknown. A video has codec, resolution and frameRate, plus sampleRate, bitDepth and channels when it has an audio track. An audio file has only sampleRate, bitDepth and channels.

Errors

When Volare can’t do what a request asks, it answers with an error status and a short message saying what went wrong:

{
  "error": "status must be one of needsProgramming, needsReview, programmed, notUsed"
}

Status	Meaning
400 Bad Request	A field is missing, a value isn’t one the request accepts, or the body isn’t JSON.
403 Forbidden	Volare isn’t licensed.
404 Not Found	There’s no such route, no Staged file matches the path, or no job has that ID.
409 Conflict	The path matches more than one file, or the job is already running or has no targets.
500 Internal Server Error	Something went wrong inside Volare.

If a path matches more than one file, the answer also lists every match under paths. Send one of those back to pick that file.

{
  "error": "Multiple files found",
  "paths": ["Song_01/Intro_v02.mov", "Song_02/Intro_v02.mov"]
}

fetch doesn’t throw an error for these statuses, so check res.ok before using the answer:

if (!res.ok) {
  const { error } = await res.json();
  console.error(`Volare refused the request (${res.status}): ${error}`);
}