Skip to main content
Version: v2

OptiView Live REST API

OptiView Live provides a REST API to manage channels, receive events, create reports, and set up webhooks.

Alternatively, you can perform the most common actions directly from the OptiView Live dashboard. See our getting started guide for more information.

To get started with the API, see the Authentication guide.

The full API specification is also available as a Swagger document.

Channels

📄️Stop a channel (will stop all connected engines and rtsp-pull ingests)

Stops all connected engines and all connected rtsp-pull ingests of the channel. Running engines are stopped gracefully (playlists are closed so that viewers see the stream end, then the engine is torn down; `stopping` for typically 10–20 seconds). To skip the graceful shutdown use `POST /channels/{id}/force-stop`; engines that are already `stopping` are force stopped by this endpoint as well, so calling it twice also force stops the channel. Engines in `error` are always force stopped.

📄️Force stop a channel (will force stop all connected engines and rtsp-pull ingests)

Stops all connected engines and all connected rtsp-pull ingests of the channel immediately, skipping the graceful shutdown: the engines are torn down right away without closing their playlists first, so viewers may see playback fail instead of the stream ending cleanly. Works from any non-stopped state, including while engines are `stopping` after a regular stop. Engines report `stopping` until the teardown has completed (usually a few seconds), then `stopped`. Prefer `POST /channels/{id}/stop` unless the engines have to be gone immediately.

Ingests

Engines

📄️Stop an engine

Stops the engine gracefully: its playlists are closed so that viewers see the stream end, after which the engine is torn down. The engine reports `stopping` until the teardown has completed (typically 10–20 seconds), then `stopped`. To skip the graceful shutdown use `POST /engines/{id}/force-stop`; calling this endpoint again while the engine is `stopping` also force stops it. An engine in `error` is always force stopped. The engine can only be started again once it is `stopped`.

📄️Force stop an engine

Stops the engine immediately, skipping the graceful shutdown: the engine is torn down right away without closing its playlists first, so viewers may see playback fail instead of the stream ending cleanly. Works from any non-stopped state, including while the engine is `stopping` after a regular stop. The engine reports `stopping` until the teardown has completed (usually a few seconds), then `stopped`, and can only be started again once it is `stopped`. Prefer `POST /engines/{id}/stop` unless the engine has to be gone immediately. Returns 409 `already_stopped` for a stopped engine.

Distributions

Regions

ABR Ladders

Webhooks

Schedulers

Custom Endpoints

Monitoring

Enhancements

📄️Get all speech dictionaries

A speech dictionary is a flat list of terms (names, proper nouns, acronyms, specialized terminology) that helps the speech recognition correctly caption the source audio of a speech enhancement. It does not translate terms: the source audio is first captioned in the source language (aided by the dictionary) and then translated into the target languages. Connect a dictionary to an ingest via the `dictionary` field of the speech enhancement entry; the dictionary `language` must match that enhancement's `sourceLanguage`.

📄️Create a new speech dictionary

A speech dictionary is a flat list of terms (names, proper nouns, acronyms, specialized terminology) that helps the speech recognition correctly caption the source audio of a speech enhancement. It does not translate terms: the source audio is first captioned in the source language (aided by the dictionary) and then translated into the target languages. Connect a dictionary to an ingest via the `dictionary` field of the speech enhancement entry; the dictionary `language` must match that enhancement's `sourceLanguage`. Terms are cleaned up automatically (whitespace normalized, empty and duplicate entries dropped); terms that cannot be fixed automatically (forbidden characters ';' or '/', more than 6 words) are rejected with `invalid_value`.

📄️Get all postprocessing dictionaries

A postprocessing dictionary is a list of find/replace rules applied to the source-language transcript of a speech enhancement after speech recognition and before translation: it reliably corrects spellings, standardizes formatting, removes filler words or censors terms, and the corrected text carries over into every translated text track. Unlike a speech dictionary (a hint to the speech recognition) the rules are always applied. Connect a postprocessing dictionary to an ingest via the `postprocessingDictionary` field of the speech enhancement entry; the dictionary `language` must match that enhancement's `sourceLanguage`.

📄️Create a new postprocessing dictionary

A postprocessing dictionary is a list of find/replace rules applied to the source-language transcript of a speech enhancement after speech recognition and before translation: it reliably corrects spellings, standardizes formatting, removes filler words or censors terms, and the corrected text carries over into every translated text track. Unlike a speech dictionary (a hint to the speech recognition) the rules are always applied. Connect a postprocessing dictionary to an ingest via the `postprocessingDictionary` field of the speech enhancement entry; the dictionary `language` must match that enhancement's `sourceLanguage`. Each entry has the format 'replacement|pattern,pattern' (an empty replacement removes the matched word). Entries are cleaned up automatically (whitespace normalized, empty and duplicate entries dropped); entries without a pattern, with spaces in a pattern, or rejected by the captioning provider (e.g. an invalid regular expression) fail with `invalid_value`.

Maintenance windows

📄️Get the maintenance windows of the organization

Maintenance windows are recurring time slots (in UTC) during which the organization allows THEO to perform maintenance on its long-running engines. Maintenance means moving an engine to fresh infrastructure: the engine is restarted with the same configuration, the stream is briefly interrupted (viewers see a clean end of stream) and the contributing encoder reconnects. The same applies to push and pull ingests on the shared ingest infrastructure: when the infrastructure carrying such an ingest is retired, the ingest is moved inside a window (the encoder reconnects to the same ingest URL, or the source is pulled again). Maintenance is only performed on engines and ingests that need it, one per channel at a time, and always inside a window. A window recurs every week, or only in selected weeks of the month (e.g. the second tuesday of the month); together the windows must offer a maintenance opportunity at least once a month. There is no default: when no windows are configured, THEO has no maintenance opportunity for the organization and maintenance that is needed stays pending. Engines and ingests report their pending or ongoing maintenance in their `maintenance` field, and the `engine.maintenance.*` / `ingest.maintenance.*` webhook events announce every step. Configuring windows does not schedule any restarts by itself.

📄️Set the maintenance windows of the organization

Maintenance windows are recurring time slots (in UTC) during which the organization allows THEO to perform maintenance on its long-running engines. Maintenance means moving an engine to fresh infrastructure: the engine is restarted with the same configuration, the stream is briefly interrupted (viewers see a clean end of stream) and the contributing encoder reconnects. The same applies to push and pull ingests on the shared ingest infrastructure: when the infrastructure carrying such an ingest is retired, the ingest is moved inside a window (the encoder reconnects to the same ingest URL, or the source is pulled again). Maintenance is only performed on engines and ingests that need it, one per channel at a time, and always inside a window. A window recurs every week, or only in selected weeks of the month (e.g. the second tuesday of the month); together the windows must offer a maintenance opportunity at least once a month. There is no default: when no windows are configured, THEO has no maintenance opportunity for the organization and maintenance that is needed stays pending. Engines and ingests report their pending or ongoing maintenance in their `maintenance` field, and the `engine.maintenance.*` / `ingest.maintenance.*` webhook events announce every step. Configuring windows does not schedule any restarts by itself. The list of windows is replaced as a whole; set an empty list to remove all windows. Windows may not overlap.