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.
Wowza Video Intelligence...
- Reference
- REST API
- The VOD settings document
Default config
Update fields of the default config
List stream group configs
Create a stream group config
One stream group config
Update fields of a stream group config
Delete a stream group config
List the saved per-stream overrides
The stream's saved override document
Create the stream's override
Update fields of the stream's override
Delete the stream's override
The detector saved in the stream's override
Update saved detector fields
Remove the override detector
The saved override listeners
Create a saved listener (and apply if running)
One saved listener
Update saved listener fields
Remove a saved listener
Edit the VOD settings
The names of the configured secrets
Set, rotate or remove secrets
The VOD settings document
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.
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
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
- http://localhost:8087/v2/vif/persist/apps/{app}/streams/{stream}/listeners/{name}
- curl
- Java
- Python
- JavaScript
curl -i -X DELETE \
-u <username>:<password> \
'' \
-H 'If-Match: string'Request
How this Engine runs on-demand analysis: how many jobs run at once and how many are kept, how long a finished job stays, where the content and the job records live, the default lifecycle webhook and its credential, whether jobs resume on their own, and the upload cap. Stored in its own file, conf.modules/vif/vod/settings.json, beside the stream configuration and never part of it.
Security
engineBasic
- http://localhost:8087/v2/vif/persist/vod-settings
- curl
- Java
- Python
- JavaScript
curl -i -X GET \
-u <username>:<password> \
''The settings.
How long a finished job stays before retention removes it; 0 keeps them until evicted. Default 0.
The content directory jobs read from and uploads land in, relative to the Engine home unless absolute. Applies at the next Engine start.
Where job records, results and thumbnails are stored. Applies at the next Engine start.
The default destination of every job's state changes; a job may override or turn it off.
The name of the secret sent as Authorization to the default destination — and only to it.
Whether a job that stops for a transient reason is resumed on its own. Default true.
The largest upload POST /vod/files accepts; beyond it, 413. Default 10 GiB.
Response
application/json
{ "max_concurrent_jobs": 1, "max_jobs": 1, "job_ttl_seconds": 0, "content_dir": "string", "jobs_dir": "string", "lifecycle_webhook": "string", "lifecycle_webhook_secret": "string", "auto_resume": true, "max_upload_bytes": 1, "etag": "string" }
Request
A merge patch, applied to the running registry at once — a smaller max_jobs evicts, a new job_ttl_seconds reschedules retention, a new webhook or default takes effect for the next job. content_dir and jobs_dir are read at Engine start and apply at the next one. 400 for a bound violation or a lifecycle_webhook_secret naming no configured secret.
Security
engineBasic
How long a finished job stays before retention removes it; 0 keeps them until evicted. Default 0.
The content directory jobs read from and uploads land in, relative to the Engine home unless absolute. Applies at the next Engine start.
Where job records, results and thumbnails are stored. Applies at the next Engine start.
The default destination of every job's state changes; a job may override or turn it off.
The name of the secret sent as Authorization to the default destination — and only to it.
Whether a job that stops for a transient reason is resumed on its own. Default true.
The largest upload POST /vod/files accepts; beyond it, 413. Default 10 GiB.
- http://localhost:8087/v2/vif/persist/vod-settings
- curl
- Java
- Python
- JavaScript
curl -i -X PATCH \
-u <username>:<password> \
'' \
-H 'Content-Type: application/merge-patch+json' \
-H 'If-Match: string' \
-d '{
"max_concurrent_jobs": 1,
"max_jobs": 1,
"job_ttl_seconds": 0,
"content_dir": "string",
"jobs_dir": "string",
"lifecycle_webhook": "string",
"lifecycle_webhook_secret": "string",
"auto_resume": true,
"max_upload_bytes": 1,
"etag": "string"
}'The applied settings.
How long a finished job stays before retention removes it; 0 keeps them until evicted. Default 0.
The content directory jobs read from and uploads land in, relative to the Engine home unless absolute. Applies at the next Engine start.
Where job records, results and thumbnails are stored. Applies at the next Engine start.
The default destination of every job's state changes; a job may override or turn it off.
The name of the secret sent as Authorization to the default destination — and only to it.
Whether a job that stops for a transient reason is resumed on its own. Default true.
The largest upload POST /vod/files accepts; beyond it, 413. Default 10 GiB.
Response
application/json
{ "max_concurrent_jobs": 1, "max_jobs": 1, "job_ttl_seconds": 0, "content_dir": "string", "jobs_dir": "string", "lifecycle_webhook": "string", "lifecycle_webhook_secret": "string", "auto_resume": true, "max_upload_bytes": 1, "etag": "string" }
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