Skip to content

Wowza Video Intelligence Framework API (2.0.0)

This reference documents every endpoint in the Wowza Video Intelligence Framework (VIF) REST API, including the parameters each one takes and the request and response bodies it works with. VIF adds real-time AI video analysis, such as object detection and scene recognition, to streams running on Wowza Streaming Engine, and this API is served by the Video Intelligence Controller (VIC), a module that runs alongside the Engine's own REST interface, on port 8087 by default.

Almost everything you do with this API comes down to one idea: a config, the group of settings that tells VIF how to analyze a stream (which detector to run, what to do with the results, and so on). You'll run into a config in three places, and each one uses it a little differently. A stream group config applies a config to every stream whose name matches a pattern you choose, such as cam.*. An override applies a config to one specific stream, by its exact name instead of a pattern. A running stream reports the config it's actually using right now, alongside its live connection state and performance. Wherever you see one of these documents in the reference below, look for a config member: that's where the settings live. The rest of the document, the match rule, the stream's identity, its live state, just says how that config gets used, and isn't part of the config itself.

Configs also build on each other in layers: a stream's final settings come from a default config, then a matching stream group config, then a per-stream override, then any changes made directly to the running stream. Each layer can fill in whatever the one below it left unset. The Config schema, wherever it appears in this reference, explains exactly how that merge works, including the two members, detector and listeners, that don't merge field by field like the rest.

Endpoints are grouped below by what they work with: durable configuration you save to disk, the live streams currently running, one-off video analysis jobs, connectivity checks, and framework-wide status. Each group's description explains what you'll find in it.

A few things are worth knowing before you make your first request. Every error this API returns is application/problem+json (RFC 7807), so error.title, error.status, and error.detail tell you what went wrong; the exceptions are failures the API never gets to handle, like a URL the Engine can't route or an Engine-level authentication or license failure, which come back in the Engine's own {success, code, message} format instead. Every document you can edit under /persist comes with an ETag header; send that value back as If-Match when you write, and the API answers 428 if you forget it and 412 if it's gone stale, so you never overwrite a change you haven't seen yet. PATCH requests are a JSON Merge Patch (RFC 7386), not a full replacement: send only the fields you want to change, and anything you leave out keeps its current value. Sending a field as null removes it instead, letting it inherit from whatever's underneath, except on a running stream, where null isn't accepted for config or config.active, because a running instance needs values to actually run with; use POST .../reset there if you want to discard your changes instead. The verbs you'll use are GET, POST, PATCH, and DELETE: POST creates a document (409 if one already exists by that name) or triggers an action, like resetting a stream or resuming a job; PATCH edits a document that already exists (404 if it doesn't); DELETE removes one. This API has no PUT. Wherever an endpoint isn't JSON, uploading or downloading a video file, for example, its description says so explicitly; everything else you send or receive is JSON.

Note: This is version 2 of the VIF REST API. Version 1 is deprecated, and we strongly recommend moving any integration that writes configuration to v2. Saving through v1 rewrites your configuration files in an older format: a per-stream override saved that way loses what made it an override, and comes back instead as a stream group config matched to that one stream's literal name. Reading through v1 stays safe at any time; just make sure every integration that writes configuration moves to v2, and that you don't mix the two on one installation.

Authentication

Engine REST credentials (engineBasic). Requests are additionally subject to the Engine license entitlement (402 without it) and Engine RBAC (the "basic" role is read-only).

Download OpenAPI description
Languages
Servers
{scheme}://{host}:{port}/v2/vif

Server

Framework-wide status: which VIS instances are connected, which streams are running, and which detection models are available on them. These endpoints are read-only.

Operations

Runtime

The stream instances currently running. A GET here shows a stream's live, resolved configuration alongside its health and performance. Writes are ephemeral: they change only the running instance, are never saved to disk, and are lost if the stream or the Engine restarts. A 404 on any Runtime endpoint means the stream isn't currently running, not that it doesn't exist at all.

Operations

List running streams

Request

Security
engineBasic
Query
applicationstring

Only streams in this Engine application; absent lists every application.

detectorstring(DetectorType)

Only streams running this kind of analysis.

Enum"scene""object""vlm""synthetic"
activeboolean

Filter on whether analysis runs. A published stream with active: false is listed but analyzes nothing.

curl -i -X GET \
  -u <username>:<password> \
  ''

Responses

Running streams matching the filters.

Bodyapplication/jsonArray [
applicationstringrequired

Engine application the stream is published to.

namestringrequired

The stream's name.

vhoststring

Engine virtual host holding the application, normally _defaultVHost_.

instancestring

Application instance the stream is published to, normally _definst_.

stateobjectrequired

The stream's live connection state and performance counters.

state.​connectionstringrequired

VIS connection state (e.g. connected); stays connected during an AI-endpoint outage.

state.​endpoint_degradedboolean or null

True while the stream's AI endpoint (VLM or SVD NIM) is unreachable.

state.​reasonstring or null

Detail behind the current connection or endpoint_degraded state, when there is any.

state.​service_versionstring or null

Version of the VIS instance serving this stream.

state.​performanceobject or null

Live counters for the stream. The *_avg members are rolling averages in milliseconds; the three below them are not times and are noted individually.

videoobject

The source video's resolution, frame rate and GOP size.

configobjectrequired

The settings that make a stream analyze: which detector runs, what its listeners do with the results, how frames are processed, which service analyzes them, and diagnostics. Every document that carries one keeps it under a member literally named config — see "Model" in this API's description for how stream group configs, overrides and running streams each use one.

Except on a running stream, where every layer is already resolved, a config is sparse: an omitted member isn't a value, it inherits from the layer below. Most members merge field by field; detector replaces the whole section at once instead, and listeners merge per entry by name — see "Model" for why.

config.​activeboolean

Whether analysis runs.

config.​detectorobject or null

The analysis running on a stream. type selects the subtype; a patch that changes it replaces the whole detector section.

config.​listenersobject

Listeners, keyed by name. Each entry merges independently of the others.

config.​processingobject

How frames are sampled and shipped to analysis; absent inherits from the layer below.

config.​serviceobject

Which Video Intelligence Service analyzes the stream; absent inherits from the layer below.

config.​diagnosticsobject

Debug aids; absent inherits from the layer below.

ephemeral_changesbooleanread-only

True while the running instance diverges from its persisted configuration (stream group config plus override) because of runtime writes. POST .../reset discards the divergence.

etagstring or null

This stream's configuration revision, to quote as If-Match on a write. Carried on the document so a client that listed streams can write one without reading it again; a single-stream read repeats it in the ETag header. It covers the config only, not the live counters under state. Server-assigned and ignored on a write.

]
Response
application/json
[ { "application": "string", "name": "string", "vhost": "string", "instance": "string", "state": {}, "video": {}, "config": {}, "ephemeral_changes": true, "etag": "string" } ]

One running stream

Request

Effective config, health and performance for the stream.

Security
engineBasic
Path
appstringrequired

Engine application holding the stream (e.g. live). The vhost and application instance are the ones VIC serves and are not addressed here.

streamstringrequired

One stream's exact name, never a pattern — patterns belong to a stream group config's match.stream_pattern.

curl -i -X GET \
  -u <username>:<password> \
  ''

Responses

The stream's resolved config and live state.

Headers
ETagstring

Opaque revision tag of the returned document.

Bodyapplication/json
applicationstringrequired

Engine application the stream is published to.

namestringrequired

The stream's name.

vhoststring

Engine virtual host holding the application, normally _defaultVHost_.

instancestring

Application instance the stream is published to, normally _definst_.

stateobjectrequired

The stream's live connection state and performance counters.

state.​connectionstringrequired

VIS connection state (e.g. connected); stays connected during an AI-endpoint outage.

state.​endpoint_degradedboolean or null

True while the stream's AI endpoint (VLM or SVD NIM) is unreachable.

state.​reasonstring or null

Detail behind the current connection or endpoint_degraded state, when there is any.

state.​service_versionstring or null

Version of the VIS instance serving this stream.

state.​performanceobject or null

Live counters for the stream. The *_avg members are rolling averages in milliseconds; the three below them are not times and are noted individually.

videoobject

The source video's resolution, frame rate and GOP size.

configobjectrequired

The settings that make a stream analyze: which detector runs, what its listeners do with the results, how frames are processed, which service analyzes them, and diagnostics. Every document that carries one keeps it under a member literally named config — see "Model" in this API's description for how stream group configs, overrides and running streams each use one.

Except on a running stream, where every layer is already resolved, a config is sparse: an omitted member isn't a value, it inherits from the layer below. Most members merge field by field; detector replaces the whole section at once instead, and listeners merge per entry by name — see "Model" for why.

config.​activeboolean

Whether analysis runs.

config.​detectorobject or null

The analysis running on a stream. type selects the subtype; a patch that changes it replaces the whole detector section.

config.​listenersobject

Listeners, keyed by name. Each entry merges independently of the others.

config.​processingobject

How frames are sampled and shipped to analysis; absent inherits from the layer below.

config.​serviceobject

Which Video Intelligence Service analyzes the stream; absent inherits from the layer below.

config.​diagnosticsobject

Debug aids; absent inherits from the layer below.

ephemeral_changesbooleanread-only

True while the running instance diverges from its persisted configuration (stream group config plus override) because of runtime writes. POST .../reset discards the divergence.

etagstring or null

This stream's configuration revision, to quote as If-Match on a write. Carried on the document so a client that listed streams can write one without reading it again; a single-stream read repeats it in the ETag header. It covers the config only, not the live counters under state. Server-assigned and ignored on a write.

Response
application/json
{ "application": "string", "name": "string", "vhost": "string", "instance": "string", "state": { "connection": "string", "endpoint_degraded": true, "reason": "string", "service_version": "string", "performance": {} }, "video": { "width": 0, "height": 0, "frame_rate": 0, "gop_size": 0 }, "config": { "active": true, "detector": {}, "listeners": {}, "processing": {}, "service": {}, "diagnostics": {} }, "ephemeral_changes": true, "etag": "string" }

Update stream settings (ephemeral)

Request

JSON Merge Patch over the stream's config, applied to the running instance and never saved: a stream or Engine restart reverts it. The body is {"config": {…}}; a member at the top level other than config (and the etag a listed document carries, which is ignored) is a 400. config.detector and config.listeners have their own subresources; naming either one here is a 409.

Security
engineBasic
Path
appstringrequired

Engine application holding the stream (e.g. live). The vhost and application instance are the ones VIC serves and are not addressed here.

streamstringrequired

One stream's exact name, never a pattern — patterns belong to a stream group config's match.stream_pattern.

Headers
If-Matchstringrequired

ETag of the revision this write is based on. * is not supported: quoting "any revision" defeats the concurrency check and is rejected with 412.

Bodyapplication/merge-patch+jsonrequired
configobject

The settings that make a stream analyze: which detector runs, what its listeners do with the results, how frames are processed, which service analyzes them, and diagnostics. Every document that carries one keeps it under a member literally named config — see "Model" in this API's description for how stream group configs, overrides and running streams each use one.

Except on a running stream, where every layer is already resolved, a config is sparse: an omitted member isn't a value, it inherits from the layer below. Most members merge field by field; detector replaces the whole section at once instead, and listeners merge per entry by name — see "Model" for why.

curl -i -X PATCH \
  -u <username>:<password> \
  '' \
  -H 'Content-Type: application/merge-patch+json' \
  -H 'If-Match: string' \
  -d '{
    "config": {
      "active": true,
      "detector": {
        "type": "scene"
      },
      "listeners": {
        "property1": {
          "type": "overlay",
          "name": "string",
          "enabled": true,
          "trigger": "immediate",
          "min_confidence": 1,
          "suppress_empty": true,
          "etag": "string"
        },
        "property2": {
          "type": "overlay",
          "name": "string",
          "enabled": true,
          "trigger": "immediate",
          "min_confidence": 1,
          "suppress_empty": true,
          "etag": "string"
        }
      },
      "processing": {
        "inference_fps": 0,
        "window_seconds": 0,
        "video_height": 0,
        "grayscale": true,
        "frame_source": "transcoder",
        "grab_interval_seconds": 0,
        "buffer_frames": 0,
        "auto_throttle": true,
        "catch_up": {
          "enabled": true,
          "max_behind_seconds": 0
        },
        "rollup_interval_seconds": 0,
        "gpu_ids": [
          0
        ]
      },
      "service": {
        "url": "string",
        "api_key": "string",
        "model_idle_timeout_seconds": 0
      },
      "diagnostics": {
        "save_images": true,
        "timing_log_seconds": 0,
        "max_logged_messages": 0
      }
    }
  }'

Responses

The stream after the change.

Headers
ETagstring

Opaque revision tag of the returned document.

Bodyapplication/json
applicationstringrequired

Engine application the stream is published to.

namestringrequired

The stream's name.

vhoststring

Engine virtual host holding the application, normally _defaultVHost_.

instancestring

Application instance the stream is published to, normally _definst_.

stateobjectrequired

The stream's live connection state and performance counters.

state.​connectionstringrequired

VIS connection state (e.g. connected); stays connected during an AI-endpoint outage.

state.​endpoint_degradedboolean or null

True while the stream's AI endpoint (VLM or SVD NIM) is unreachable.

state.​reasonstring or null

Detail behind the current connection or endpoint_degraded state, when there is any.

state.​service_versionstring or null

Version of the VIS instance serving this stream.

state.​performanceobject or null

Live counters for the stream. The *_avg members are rolling averages in milliseconds; the three below them are not times and are noted individually.

videoobject

The source video's resolution, frame rate and GOP size.

configobjectrequired

The settings that make a stream analyze: which detector runs, what its listeners do with the results, how frames are processed, which service analyzes them, and diagnostics. Every document that carries one keeps it under a member literally named config — see "Model" in this API's description for how stream group configs, overrides and running streams each use one.

Except on a running stream, where every layer is already resolved, a config is sparse: an omitted member isn't a value, it inherits from the layer below. Most members merge field by field; detector replaces the whole section at once instead, and listeners merge per entry by name — see "Model" for why.

config.​activeboolean

Whether analysis runs.

config.​detectorobject or null

The analysis running on a stream. type selects the subtype; a patch that changes it replaces the whole detector section.

config.​listenersobject

Listeners, keyed by name. Each entry merges independently of the others.

config.​processingobject

How frames are sampled and shipped to analysis; absent inherits from the layer below.

config.​serviceobject

Which Video Intelligence Service analyzes the stream; absent inherits from the layer below.

config.​diagnosticsobject

Debug aids; absent inherits from the layer below.

ephemeral_changesbooleanread-only

True while the running instance diverges from its persisted configuration (stream group config plus override) because of runtime writes. POST .../reset discards the divergence.

etagstring or null

This stream's configuration revision, to quote as If-Match on a write. Carried on the document so a client that listed streams can write one without reading it again; a single-stream read repeats it in the ETag header. It covers the config only, not the live counters under state. Server-assigned and ignored on a write.

Response
application/json
{ "application": "string", "name": "string", "vhost": "string", "instance": "string", "state": { "connection": "string", "endpoint_degraded": true, "reason": "string", "service_version": "string", "performance": {} }, "video": { "width": 0, "height": 0, "frame_rate": 0, "gop_size": 0 }, "config": { "active": true, "detector": {}, "listeners": {}, "processing": {}, "service": {}, "diagnostics": {} }, "ephemeral_changes": true, "etag": "string" }

Discard the stream's ephemeral changes

Request

Action endpoint: reverts the running instance to its persisted configuration (stream group config plus override) and applies it live, immediately — restarting the detector session when the change calls for it, never the stream itself. Returns the resulting stream — fresh state and ETag, so the client needs no follow-up GET. Idempotent — succeeds whether or not ephemeral changes exist. No If-Match: this is an action, not a conditional edit.

Security
engineBasic
Path
appstringrequired

Engine application holding the stream (e.g. live). The vhost and application instance are the ones VIC serves and are not addressed here.

streamstringrequired

One stream's exact name, never a pattern — patterns belong to a stream group config's match.stream_pattern.

curl -i -X POST \
  -u <username>:<password> \
  ''

Responses

The stream after the reset.

Headers
ETagstring

Opaque revision tag of the returned document.

Bodyapplication/json
applicationstringrequired

Engine application the stream is published to.

namestringrequired

The stream's name.

vhoststring

Engine virtual host holding the application, normally _defaultVHost_.

instancestring

Application instance the stream is published to, normally _definst_.

stateobjectrequired

The stream's live connection state and performance counters.

state.​connectionstringrequired

VIS connection state (e.g. connected); stays connected during an AI-endpoint outage.

state.​endpoint_degradedboolean or null

True while the stream's AI endpoint (VLM or SVD NIM) is unreachable.

state.​reasonstring or null

Detail behind the current connection or endpoint_degraded state, when there is any.

state.​service_versionstring or null

Version of the VIS instance serving this stream.

state.​performanceobject or null

Live counters for the stream. The *_avg members are rolling averages in milliseconds; the three below them are not times and are noted individually.

videoobject

The source video's resolution, frame rate and GOP size.

configobjectrequired

The settings that make a stream analyze: which detector runs, what its listeners do with the results, how frames are processed, which service analyzes them, and diagnostics. Every document that carries one keeps it under a member literally named config — see "Model" in this API's description for how stream group configs, overrides and running streams each use one.

Except on a running stream, where every layer is already resolved, a config is sparse: an omitted member isn't a value, it inherits from the layer below. Most members merge field by field; detector replaces the whole section at once instead, and listeners merge per entry by name — see "Model" for why.

config.​activeboolean

Whether analysis runs.

config.​detectorobject or null

The analysis running on a stream. type selects the subtype; a patch that changes it replaces the whole detector section.

config.​listenersobject

Listeners, keyed by name. Each entry merges independently of the others.

config.​processingobject

How frames are sampled and shipped to analysis; absent inherits from the layer below.

config.​serviceobject

Which Video Intelligence Service analyzes the stream; absent inherits from the layer below.

config.​diagnosticsobject

Debug aids; absent inherits from the layer below.

ephemeral_changesbooleanread-only

True while the running instance diverges from its persisted configuration (stream group config plus override) because of runtime writes. POST .../reset discards the divergence.

etagstring or null

This stream's configuration revision, to quote as If-Match on a write. Carried on the document so a client that listed streams can write one without reading it again; a single-stream read repeats it in the ETag header. It covers the config only, not the live counters under state. Server-assigned and ignored on a write.

Response
application/json
{ "application": "string", "name": "string", "vhost": "string", "instance": "string", "state": { "connection": "string", "endpoint_degraded": true, "reason": "string", "service_version": "string", "performance": {} }, "video": { "width": 0, "height": 0, "frame_rate": 0, "gop_size": 0 }, "config": { "active": true, "detector": {}, "listeners": {}, "processing": {}, "service": {}, "diagnostics": {} }, "ephemeral_changes": true, "etag": "string" }

Effective detector

Request

Security
engineBasic
Path
appstringrequired

Engine application holding the stream (e.g. live). The vhost and application instance are the ones VIC serves and are not addressed here.

streamstringrequired

One stream's exact name, never a pattern — patterns belong to a stream group config's match.stream_pattern.

curl -i -X GET \
  -u <username>:<password> \
  ''

Responses

Detector.

Headers
ETagstring

Opaque revision tag of the returned document.

Bodyapplication/json
typestringrequired

Detector subtype: scene, object, vlm, or synthetic.

Enum"scene""object""vlm""synthetic"
Discriminator
classesArray of strings

Scene classes to detect.

sensitivityinteger[ 1 .. 10 ]

Higher detects more; per-class overrides in class_sensitivity. Default 5.

class_sensitivityobject

Per-class sensitivity overrides, keyed by class name; unlisted classes use sensitivity.

min_confidencenumber[ 0 .. 1 ]

Detections below this confidence are dropped. Default 0.3.

baselineobject

The class set a frame's scores are normalized against. Sensitivity is read as a distance from the mean score over this set, so it decides what counts as an unusual match — not which classes are reported, which is classes. Leave it alone unless the stream's subject matter makes the general-purpose baseline a poor reference.

Response
application/json
{ "type": "scene", "classes": [ "string" ], "sensitivity": 1, "class_sensitivity": { "property1": 1, "property2": 1 }, "min_confidence": 1, "baseline": { "set": "DEFAULT", "custom_classes": [] } }

Update detector fields (ephemeral)

Request

JSON Merge Patch within the detector, memory only. A patch that changes type replaces the whole detector section. 404 when the stream is not running or runs no detector.

Security
engineBasic
Path
appstringrequired

Engine application holding the stream (e.g. live). The vhost and application instance are the ones VIC serves and are not addressed here.

streamstringrequired

One stream's exact name, never a pattern — patterns belong to a stream group config's match.stream_pattern.

Headers
If-Matchstringrequired

ETag of the revision this write is based on. * is not supported: quoting "any revision" defeats the concurrency check and is rejected with 412.

Bodyapplication/merge-patch+jsonrequired
typestringrequired

Detector subtype: scene, object, vlm, or synthetic.

Enum"scene""object""vlm""synthetic"
Discriminator
classesArray of strings

Scene classes to detect.

sensitivityinteger[ 1 .. 10 ]

Higher detects more; per-class overrides in class_sensitivity. Default 5.

class_sensitivityobject

Per-class sensitivity overrides, keyed by class name; unlisted classes use sensitivity.

min_confidencenumber[ 0 .. 1 ]

Detections below this confidence are dropped. Default 0.3.

baselineobject

The class set a frame's scores are normalized against. Sensitivity is read as a distance from the mean score over this set, so it decides what counts as an unusual match — not which classes are reported, which is classes. Leave it alone unless the stream's subject matter makes the general-purpose baseline a poor reference.

curl -i -X PATCH \
  -u <username>:<password> \
  '' \
  -H 'Content-Type: application/merge-patch+json' \
  -H 'If-Match: string' \
  -d '{
    "type": "scene",
    "classes": [
      "string"
    ],
    "sensitivity": 1,
    "class_sensitivity": {
      "property1": 1,
      "property2": 1
    },
    "min_confidence": 1,
    "baseline": {
      "set": "DEFAULT",
      "custom_classes": [
        "string"
      ]
    }
  }'

Responses

Applied detector.

Headers
ETagstring

Opaque revision tag of the returned document.

Bodyapplication/json
typestringrequired

Detector subtype: scene, object, vlm, or synthetic.

Enum"scene""object""vlm""synthetic"
Discriminator
classesArray of strings

Scene classes to detect.

sensitivityinteger[ 1 .. 10 ]

Higher detects more; per-class overrides in class_sensitivity. Default 5.

class_sensitivityobject

Per-class sensitivity overrides, keyed by class name; unlisted classes use sensitivity.

min_confidencenumber[ 0 .. 1 ]

Detections below this confidence are dropped. Default 0.3.

baselineobject

The class set a frame's scores are normalized against. Sensitivity is read as a distance from the mean score over this set, so it decides what counts as an unusual match — not which classes are reported, which is classes. Leave it alone unless the stream's subject matter makes the general-purpose baseline a poor reference.

Response
application/json
{ "type": "scene", "classes": [ "string" ], "sensitivity": 1, "class_sensitivity": { "property1": 1, "property2": 1 }, "min_confidence": 1, "baseline": { "set": "DEFAULT", "custom_classes": [] } }

Effective listeners

Request

Security
engineBasic
Path
appstringrequired

Engine application holding the stream (e.g. live). The vhost and application instance are the ones VIC serves and are not addressed here.

streamstringrequired

One stream's exact name, never a pattern — patterns belong to a stream group config's match.stream_pattern.

curl -i -X GET \
  -u <username>:<password> \
  ''

Responses

Listeners, keyed by name.

Bodyapplication/json
property name*object(Listener)additional property

What happens with detection results. type selects the subtype; custom is the escape hatch for customer modules.

Response
application/json
{ "property1": { "type": "overlay", "enabled": true, "trigger": "immediate", "min_confidence": 1, "suppress_empty": true, "etag": "string" }, "property2": { "type": "overlay", "enabled": true, "trigger": "immediate", "min_confidence": 1, "suppress_empty": true, "etag": "string" } }

Add a listener (ephemeral)

Request

The listener's name travels in the body's name member, required here (400 without it). 409 when a listener with that name already exists.

Security
engineBasic
Path
appstringrequired

Engine application holding the stream (e.g. live). The vhost and application instance are the ones VIC serves and are not addressed here.

streamstringrequired

One stream's exact name, never a pattern — patterns belong to a stream group config's match.stream_pattern.

Bodyapplication/jsonrequired
typestringrequired

Listener subtype: selects which fields beyond this apply.

Enum"overlay""webhook""id3""log""custom"
Discriminator
namestringwrite-only

Creation only: the listener's key in the collection. Ignored on other operations.

enabledboolean

Whether the listener runs. Default true.

Default true
triggerstring

When the listener fires — per detection, per batch, or per rollup window.

Enum"immediate""batch""rollup"
min_confidencenumber or null[ 0 .. 1 ]

Only forward detections at or above this confidence.

suppress_emptyboolean or null

Skip events that contain no detections.

etagstring or null

This listener's revision, to quote as If-Match on a write. The collection response carries it per listener so a client that listed them can write one without reading it again; a single-listener read repeats it in the ETag header. Server-assigned and ignored on a write.

widthinteger or null

Overlay stream width in pixels; null matches the source.

heightinteger or null

Overlay stream height in pixels; null matches the source.

frame_ratenumber or null

Overlay stream frame rate; null matches the source.

overlay_delayinteger or null

How many initial detection events are skipped before overlays start rendering, to let the overlay stream align with the video. A count of events, not a time.

fade_stepinteger or null

Over how many frames an expiring box fades to invisible — larger fades slower. A whole number of frames.

jitterinteger or null

Smoothing tolerance for box movement, in pixels.

replace_videoboolean or null

Replace the video with the overlay instead of compositing.

show_statsboolean or null

Render the stats block on the overlay.

debug_stringstring or null

Title overlay, a date-format pattern with {{app_name}}, {{stream_name}}, {{detector_type}} variables.

curl -i -X POST \
  -u <username>:<password> \
  '' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "overlay",
    "name": "string",
    "enabled": true,
    "trigger": "immediate",
    "min_confidence": 1,
    "suppress_empty": true,
    "etag": "string",
    "width": 0,
    "height": 0,
    "frame_rate": 0,
    "overlay_delay": 0,
    "fade_step": 0,
    "jitter": 0,
    "replace_video": true,
    "show_stats": true,
    "debug_string": "string"
  }'

Responses

Listener created on the running instance.

Headers
ETagstring

Opaque revision tag of the returned document.

Bodyapplication/json
typestringrequired

Listener subtype: selects which fields beyond this apply.

Enum"overlay""webhook""id3""log""custom"
Discriminator
enabledboolean

Whether the listener runs. Default true.

Default true
triggerstring

When the listener fires — per detection, per batch, or per rollup window.

Enum"immediate""batch""rollup"
min_confidencenumber or null[ 0 .. 1 ]

Only forward detections at or above this confidence.

suppress_emptyboolean or null

Skip events that contain no detections.

etagstring or null

This listener's revision, to quote as If-Match on a write. The collection response carries it per listener so a client that listed them can write one without reading it again; a single-listener read repeats it in the ETag header. Server-assigned and ignored on a write.

widthinteger or null

Overlay stream width in pixels; null matches the source.

heightinteger or null

Overlay stream height in pixels; null matches the source.

frame_ratenumber or null

Overlay stream frame rate; null matches the source.

overlay_delayinteger or null

How many initial detection events are skipped before overlays start rendering, to let the overlay stream align with the video. A count of events, not a time.

fade_stepinteger or null

Over how many frames an expiring box fades to invisible — larger fades slower. A whole number of frames.

jitterinteger or null

Smoothing tolerance for box movement, in pixels.

replace_videoboolean or null

Replace the video with the overlay instead of compositing.

show_statsboolean or null

Render the stats block on the overlay.

debug_stringstring or null

Title overlay, a date-format pattern with {{app_name}}, {{stream_name}}, {{detector_type}} variables.

Response
application/json
{ "type": "overlay", "enabled": true, "trigger": "immediate", "min_confidence": 1, "suppress_empty": true, "etag": "string", "width": 0, "height": 0, "frame_rate": 0, "overlay_delay": 0, "fade_step": 0, "jitter": 0, "replace_video": true, "show_stats": true, "debug_string": "string" }

One effective listener

Request

Security
engineBasic
Path
appstringrequired

Engine application holding the stream (e.g. live). The vhost and application instance are the ones VIC serves and are not addressed here.

streamstringrequired

One stream's exact name, never a pattern — patterns belong to a stream group config's match.stream_pattern.

namestringrequired

Listener name (e.g. Overlays, Webhooks).

curl -i -X GET \
  -u <username>:<password> \
  ''

Responses

Listener.

Headers
ETagstring

Opaque revision tag of the returned document.

Bodyapplication/json
typestringrequired

Listener subtype: selects which fields beyond this apply.

Enum"overlay""webhook""id3""log""custom"
Discriminator
enabledboolean

Whether the listener runs. Default true.

Default true
triggerstring

When the listener fires — per detection, per batch, or per rollup window.

Enum"immediate""batch""rollup"
min_confidencenumber or null[ 0 .. 1 ]

Only forward detections at or above this confidence.

suppress_emptyboolean or null

Skip events that contain no detections.

etagstring or null

This listener's revision, to quote as If-Match on a write. The collection response carries it per listener so a client that listed them can write one without reading it again; a single-listener read repeats it in the ETag header. Server-assigned and ignored on a write.

widthinteger or null

Overlay stream width in pixels; null matches the source.

heightinteger or null

Overlay stream height in pixels; null matches the source.

frame_ratenumber or null

Overlay stream frame rate; null matches the source.

overlay_delayinteger or null

How many initial detection events are skipped before overlays start rendering, to let the overlay stream align with the video. A count of events, not a time.

fade_stepinteger or null

Over how many frames an expiring box fades to invisible — larger fades slower. A whole number of frames.

jitterinteger or null

Smoothing tolerance for box movement, in pixels.

replace_videoboolean or null

Replace the video with the overlay instead of compositing.

show_statsboolean or null

Render the stats block on the overlay.

debug_stringstring or null

Title overlay, a date-format pattern with {{app_name}}, {{stream_name}}, {{detector_type}} variables.

Response
application/json
{ "type": "overlay", "enabled": true, "trigger": "immediate", "min_confidence": 1, "suppress_empty": true, "etag": "string", "width": 0, "height": 0, "frame_rate": 0, "overlay_delay": 0, "fade_step": 0, "jitter": 0, "replace_video": true, "show_stats": true, "debug_string": "string" }

Update listener fields (ephemeral)

Request

Security
engineBasic
Path
appstringrequired

Engine application holding the stream (e.g. live). The vhost and application instance are the ones VIC serves and are not addressed here.

streamstringrequired

One stream's exact name, never a pattern — patterns belong to a stream group config's match.stream_pattern.

namestringrequired

Listener name (e.g. Overlays, Webhooks).

Headers
If-Matchstringrequired

ETag of the revision this write is based on. * is not supported: quoting "any revision" defeats the concurrency check and is rejected with 412.

Bodyapplication/merge-patch+jsonrequired
typestringrequired

Listener subtype: selects which fields beyond this apply.

Enum"overlay""webhook""id3""log""custom"
Discriminator
namestringwrite-only

Creation only: the listener's key in the collection. Ignored on other operations.

enabledboolean

Whether the listener runs. Default true.

Default true
triggerstring

When the listener fires — per detection, per batch, or per rollup window.

Enum"immediate""batch""rollup"
min_confidencenumber or null[ 0 .. 1 ]

Only forward detections at or above this confidence.

suppress_emptyboolean or null

Skip events that contain no detections.

etagstring or null

This listener's revision, to quote as If-Match on a write. The collection response carries it per listener so a client that listed them can write one without reading it again; a single-listener read repeats it in the ETag header. Server-assigned and ignored on a write.

widthinteger or null

Overlay stream width in pixels; null matches the source.

heightinteger or null

Overlay stream height in pixels; null matches the source.

frame_ratenumber or null

Overlay stream frame rate; null matches the source.

overlay_delayinteger or null

How many initial detection events are skipped before overlays start rendering, to let the overlay stream align with the video. A count of events, not a time.

fade_stepinteger or null

Over how many frames an expiring box fades to invisible — larger fades slower. A whole number of frames.

jitterinteger or null

Smoothing tolerance for box movement, in pixels.

replace_videoboolean or null

Replace the video with the overlay instead of compositing.

show_statsboolean or null

Render the stats block on the overlay.

debug_stringstring or null

Title overlay, a date-format pattern with {{app_name}}, {{stream_name}}, {{detector_type}} variables.

curl -i -X PATCH \
  -u <username>:<password> \
  '' \
  -H 'Content-Type: application/merge-patch+json' \
  -H 'If-Match: string' \
  -d '{
    "type": "overlay",
    "name": "string",
    "enabled": true,
    "trigger": "immediate",
    "min_confidence": 1,
    "suppress_empty": true,
    "etag": "string",
    "width": 0,
    "height": 0,
    "frame_rate": 0,
    "overlay_delay": 0,
    "fade_step": 0,
    "jitter": 0,
    "replace_video": true,
    "show_stats": true,
    "debug_string": "string"
  }'

Responses

Applied listener.

Headers
ETagstring

Opaque revision tag of the returned document.

Bodyapplication/json
typestringrequired

Listener subtype: selects which fields beyond this apply.

Enum"overlay""webhook""id3""log""custom"
Discriminator
enabledboolean

Whether the listener runs. Default true.

Default true
triggerstring

When the listener fires — per detection, per batch, or per rollup window.

Enum"immediate""batch""rollup"
min_confidencenumber or null[ 0 .. 1 ]

Only forward detections at or above this confidence.

suppress_emptyboolean or null

Skip events that contain no detections.

etagstring or null

This listener's revision, to quote as If-Match on a write. The collection response carries it per listener so a client that listed them can write one without reading it again; a single-listener read repeats it in the ETag header. Server-assigned and ignored on a write.

widthinteger or null

Overlay stream width in pixels; null matches the source.

heightinteger or null

Overlay stream height in pixels; null matches the source.

frame_ratenumber or null

Overlay stream frame rate; null matches the source.

overlay_delayinteger or null

How many initial detection events are skipped before overlays start rendering, to let the overlay stream align with the video. A count of events, not a time.

fade_stepinteger or null

Over how many frames an expiring box fades to invisible — larger fades slower. A whole number of frames.

jitterinteger or null

Smoothing tolerance for box movement, in pixels.

replace_videoboolean or null

Replace the video with the overlay instead of compositing.

show_statsboolean or null

Render the stats block on the overlay.

debug_stringstring or null

Title overlay, a date-format pattern with {{app_name}}, {{stream_name}}, {{detector_type}} variables.

Response
application/json
{ "type": "overlay", "enabled": true, "trigger": "immediate", "min_confidence": 1, "suppress_empty": true, "etag": "string", "width": 0, "height": 0, "frame_rate": 0, "overlay_delay": 0, "fade_step": 0, "jitter": 0, "replace_video": true, "show_stats": true, "debug_string": "string" }

Remove a listener (ephemeral)

Request

Security
engineBasic
Path
appstringrequired

Engine application holding the stream (e.g. live). The vhost and application instance are the ones VIC serves and are not addressed here.

streamstringrequired

One stream's exact name, never a pattern — patterns belong to a stream group config's match.stream_pattern.

namestringrequired

Listener name (e.g. Overlays, Webhooks).

Headers
If-Matchstringrequired

ETag of the revision this write is based on. * is not supported: quoting "any revision" defeats the concurrency check and is rejected with 412.

curl -i -X DELETE \
  -u <username>:<password> \
  '' \
  -H 'If-Match: string'

Responses

Listener removed from the running instance.

Response
No content

Thumbnail image of the running stream

Request

The latest decoded frame, or a given one. 404 when the stream is not running or has produced no frame yet.

Security
engineBasic
Path
appstringrequired

Engine application holding the stream (e.g. live). The vhost and application instance are the ones VIC serves and are not addressed here.

streamstringrequired

One stream's exact name, never a pattern — patterns belong to a stream group config's match.stream_pattern.

Query
widthinteger>= 0

Target width in pixels; 0, the default, keeps the source width.

heightinteger>= 0

Target height in pixels; 0, the default, keeps the source height.

fitstring

How the frame is fitted when the requested size has another aspect ratio: letterbox pads, crop trims, fitwidth/fitheight scale to that side and let the other follow, matchsource keeps the source size.

Default "letterbox"
Enum"letterbox""fitwidth""fitheight""matchsource""crop"
formatstring

Encoding of the returned image, which sets the response media type.

Default "png"
Enum"jpg""png"
frame_idinteger(int64)

0, the default, is the latest frame. A specific frame is served from the analysis buffer at its own size, so width, height and fit do not apply.

Default 0
overlayboolean

Render the detection overlay. Falls back to the -vi overlay rendition, then to the plain source frame, when the annotated frame is not available.

Default false
curl -i -X GET \
  -u <username>:<password> \
  ''

Responses

Thumbnail image.

Body
string(binary)
Response
No content

Persist

The durable configuration that lives on disk whether or not a stream is running: stream group configs, which apply automatically to any stream whose name matches a pattern, and per-stream overrides. Writing here saves the document, and if a running stream is governed by it, applies the change to that stream immediately. You can also write an override for a stream that isn't running yet; it takes effect as soon as the stream starts.

Operations

Probes

Connectivity checks for external endpoints, such as the vision-language model a detector calls out to. Use these before you save a configuration, to confirm VIF can actually reach the endpoint you're pointing it at.

Operations

VOD

On-demand analysis: the video files under the Engine's content directory, and the jobs that analyze them. Unlike a running stream, a job outlives its analysis and is neither a config nor a stream. It just names the config it should use when you submit it, and keeps a record of what it actually used once it's done.

Operations