{ "openapi": "3.1.0", "x-group-parameters": true, "info": { "title": "Mux API", "description": "Mux is how developers build online video. This API encompasses both Mux Video and Mux Data functionality to help you build your video-related projects better and faster than ever before.", "version": "v1", "contact": { "name": "Mux DevEx", "url": "https://docs.mux.com", "email": "devex@mux.com" } }, "servers": [ { "url": "https://api.mux.com", "description": "Mux Production API" } ], "security": [ { "accessToken": [] }, { "authorizationToken": [] } ], "tags": [ { "name": "Transcription Vocabularies", "description": "Transcription Vocabularies allows you to provide collections of phrases like proper nouns, technical jargon, and uncommon words as part of captioning workflows. When using Auto-Generated Captions, Transcription Vocabularies increase the likelihood of correct speech recognition for these words and phrases." }, { "name": "Assets", "description": "An asset refers to a piece of media content that is stored or is being live streamed through the Mux system. An asset always has a duration and one or more tracks (audio, video, and text data).\n\nThe media content of an asset cannot be updated once created, however an asset can be used to create another asset, and can be modified within that process." }, { "name": "Live Streams", "description": "A Live Stream represents a unique live stream of video being pushed to Mux. It includes configuration details (a Stream Key) for live broadcasting software/hardware and a Playback ID for playing the stream anywhere. Currently, RTMP is the only supported method of ingesting video. Use rtmp://global-live.mux.com:5222/app with the Live Stream's Stream Key for getting the video into Mux, and use https://stream.mux.com with the Live Stream's Playback ID for playback.\n\nA Live Stream can be used once for a specific event, or re-used forever. If you're building an application like Facebook Live or Twitch, you could create one Live Stream per user. This allows them to configure their broadcasting software once, and the Live Stream Playback ID will always show their latest stream.\n\nEach RTMP session creates a new video asset automatically. You can set up a webhook to be notified each time a broadcast (or Live Stream RTMP session) begins or ends with the video.live_stream.active and video.live_stream.idle events respectively. Assets that are created from a Live Stream have the same behavior as other Assets you create.\n\nLearn more about [how to go live in our guides](https://docs.mux.com/guides/start-live-streaming)." }, { "name": "URL Signing Keys", "description": "A URL signing key is used as the secret when signing any Mux URL. Mux requires a [JSON Web Token](https://jwt.io/) as the value of the token query parameter. The token query parameter must be set for URLs that reference a playback ID with a signed playback policy." }, { "name": "Direct Uploads", "description": "Direct upload allows you to push assets directly to Mux storage instead of needing to go through your own first. When you create a new direct upload, we'll give you back a signed URL for a Google Cloud Storage bucket. Their storage API is S3 compatible, so whatever tool you use to upload to either GCS or S3 should work, just remember you're probably uploading large video files and should [take advantage of things like resumable or multipart uploads](https://cloud.google.com/storage/docs/json_api/v1/how-tos/resumable-upload).\n\nParticularly for customers that deal with a lot of user-generated content, it's common to expect quite a few abandoned uploads. To keep those abandoned uploads from cluttering up your asset lists, we don't create an asset for you until the upload is complete. Once that asset is created, you can expect all of the normal asset-related webhooks." }, { "name": "Delivery Usage", "description": "The Delivery Usage API allows you to get delivery/streaming usage details for each asset and across all assets. Delivery usage details are aggregated every hour at the top of the hour and can be requested for a specified time window within the last 90 days starting at 12 hours prior to when the request is made.\n\nAssets are ordered by delivery usage starting with the one with the highest usage. Only assets with delivery usage greater than 0 seconds are returned in the response." }, { "name": "Playback Restrictions", "description": "Playback Restrictions allows you to set additional rules for playing videos. You can set the domains/hostnames allowed to play your videos. For instance, viewers can play videos embedded on the `https://example.com` website when you set the Playback Restrictions with `example.com` as an allowed domain. Any Video requests from other websites are denied. Additionally, you can set rules for what user agents to allow. Please see [Using User-Agent HTTP header for validation](https://docs.mux.com/guides/secure-video-playback#using-user-agent-http-header-for-validation) for more details on this feature." }, { "name": "DRM Configurations", "description": "DRM Configurations allow you to adjust the security level of content delivered through Mux Video's Digital Rights Management (DRM) feature." }, { "name": "Playback ID", "description": "Operations related to the manipulation of playback IDs, through which users are able to stream videos and live streams from Mux." }, { "name": "Video Views", "description": "An individual video view tracked by Mux Data. For the full list of properties for each view please refer to the table of data fields in the [Export raw video view data guide](https://docs.mux.com/guides/export-raw-video-view-data)." }, { "name": "Errors", "description": "Playback errors are tracked and aggregated by Mux Data. Errors can be listed by the API, which contains data about the error code, message, and how often the error occurred." }, { "name": "Filters", "description": "Deprecated, please refer to the Dimensions APIs." }, { "name": "Dimensions", "description": "Dimensions are the types of metadata that can be collected for a video view. Some dimensions are collected automatically based on the playback or device, such as the viewer's Country or the device information. Other dimensions are specified by the developer when configuring a Mux Data video view such as the video title. The Dimensions APIs allow you to get a list of the supported dimensions and their values." }, { "name": "Exports", "description": "Exports allow you to download the daily CSV files that are generated from the video views that occurred in the previous day. Please contact [support](mailto:support@mux.com) for information about enabling exports for your organization." }, { "name": "Metrics", "description": "Historical metrics are used for tracking KPIs, diagnosing issues, and\nmeasuring viewers' quality of experience. Metrics are calculated using the\nvideo views that have been completed and are bucketed on the view end time\nfor quality of experience metrics and view start time for engagement\nmetrics. Historical metrics provide a large collection of dimensions that\ncan be used to aggregate quality of experience based on view metadata. You\ncan also easily compare experiences across viewer populations to, for\nexample, find issues with specific devices or geographies.\n\nHistorical metrics are similar but not directly comparable to the real-time\nmetrics in the Real-time APIs. These metrics are aggregated for long-term\nstorage historical reporting and are generated using different viewer\npopulations.\n" }, { "name": "Engagement", "description": "Engagement metrics are a subset of historical metrics that describe how viewers watch a specific asset, video, or playback ID across the duration of the content." }, { "name": "Monitoring", "description": "Monitoring metrics are used for operational monitoring of a video platform.\nThe metrics are aggregated in five second intervals, across the views that\nare currently being watched. The real-time metrics' timeline, breakdown,\nand histogram representations are available via the APIs.\n\nMonitoring metrics are similar but not directly comparable to the historical\nmetrics in the Metrics APIs. These metrics are aggregated to provide the most\noperational detail possible used for resolving operational issues.\nMux Data Monitoring metrics are available to Mux Data customers on a Media plan.\n" }, { "name": "Real-Time", "description": "The Mux Data Real-time API has been deprecated, please refer to the\nMux Data `Monitoring` APIs which provide the same functionality.\nMux Data Monitoring metrics are available to Mux Data customers on a Media plan.\n" }, { "name": "Incidents", "description": "Incidents occur when an anomaly alert is triggered in Mux Data. The Incidents API provides operations related to the raising and managing of alerting incidents." }, { "name": "Annotations", "description": "Annotations allow you to add notes at a specific datetime to view in the Mux Data dashboard." }, { "name": "Subview Metrics", "description": "A single video view is made up of one or more subviews — for example, a `rendition` subview tracks a continuous period spent at a specific video quality level, and a `playback_mode` subview tracks a continuous period in a specific playback mode (such as fullscreen or picture-in-picture).\n\nSubview metrics let you measure and filter on this subview-level data directly, rather than relying only on view-level metrics. For example, you can find out how much playing time was spent at 1080p vs. 720p, or broken down further by country.\n" }, { "name": "Signing Keys", "description": "Signing keys are used to sign JSON Web Tokens (JWTs) for securing certain requests, such as secure playback URLs and access to real-time viewer counts in Mux Data. **One signing key can be used to sign multiple requests - you probably only need one active at a time.** However, you can create multiple signing keys to enable key rotation, creating a new key and deleting the old only after any existing signed requests have expired." }, { "name": "Utilities", "description": "Collection of utility methods for using Mux APIs. There's only one thing in here right now, maybe there will be more later." }, { "name": "Usage Exports", "description": "Usage Exports provide programmatic access to your organization's billing usage data. The Usage Exports feature must be enabled for your organization in the Mux Dashboard under **Usage > Exports**." }, { "name": "Webhooks", "description": "Webhook endpoints allow you to configure URLs where Mux will send notifications about events in your environment (e.g. asset ready, live stream active). Requires an access token with `system:read` and/or `system:write` permissions." }, { "name": "Jobs", "description": "List and cancel jobs across all workflows." }, { "name": "Ask Questions", "description": "Ask questions about a video and get structured answers." }, { "name": "Edit Captions", "description": "Edit an existing caption track with find-and-replace edits and optional profanity censoring." }, { "name": "Find Best Thumbnails", "description": "Sample thumbnails from a Mux Video asset, score them with AI, and select the best thumbnail candidates." }, { "name": "Find Key Moments", "description": "Identify key moments in a video." }, { "name": "Find Scenes", "description": "Segment a Mux video asset into ordered scenes using shot boundaries and transcript cues." }, { "name": "Generate Chapters", "description": "Generate chapters for a video." }, { "name": "Generate Engagement Insights", "description": "Analyze viewer engagement patterns to identify high and low engagement moments with AI-powered insights." }, { "name": "Generate Premium Captions", "description": "Generate high-quality captions for a Mux asset and upload the result as a text track." }, { "name": "Moderate", "description": "Analyze a video for inappropriate content." }, { "name": "Summarize", "description": "Generate a title, description, and tags for a video." }, { "name": "Translate Audio", "description": "Translate the audio track to another language." }, { "name": "Translate Captions", "description": "Translate captions from one language to another." }, { "name": "Directives", "description": "Define which Robots workflows should run against Mux assets, and under what conditions." } ], "paths": { "/video/v1/transcription-vocabularies": { "post": { "tags": [ "Transcription Vocabularies" ], "summary": "Create a Transcription Vocabulary", "description": "Create a new Transcription Vocabulary.", "operationId": "create-transcription-vocabulary", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTranscriptionVocabularyRequest" }, "example": { "name": "Mux API Vocabulary", "phrases": [ "Mux", "Live Stream", "Playback ID", "video encoding" ] } } } }, "responses": { "201": { "description": "Transcription Vocabulary Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionVocabularyResponse" }, "example": { "data": { "id": "VDm3npt2eaEDvz9emzun8Q", "name": "Mux API Vocabulary", "phrases": [ "Mux", "Live Stream", "Playback ID", "video encoding" ], "created_at": "1609869152", "updated_at": "1609869152" } } } } } } }, "get": { "tags": [ "Transcription Vocabularies" ], "summary": "List Transcription Vocabularies", "description": "List all Transcription Vocabularies.", "operationId": "list-transcription-vocabularies", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "name": "limit", "in": "query", "description": "Number of items to include in the response", "required": false, "schema": { "type": "integer", "format": "int32", "default": 10, "maximum": 10 } }, { "$ref": "#/components/parameters/page" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTranscriptionVocabulariesResponse" }, "example": { "data": [ { "id": "VDm3npt2eaEDvz9emzun8Q", "name": "Mux API Vocabulary", "phrases": [ "Mux", "Live Stream", "Playback ID", "video encoding" ], "created_at": "1609869152", "updated_at": "1609870000" }, { "id": "M1lDlzSP102NgukTnyQyLqw", "name": "Video Codecs", "phrases": [ "h.264", "HEVC", "AV1" ], "created_at": "1609869152", "updated_at": "1609870000" } ] } } } } } } }, "/video/v1/transcription-vocabularies/{TRANSCRIPTION_VOCABULARY_ID}": { "get": { "tags": [ "Transcription Vocabularies" ], "summary": "Retrieve a Transcription Vocabulary", "description": "Retrieves the details of a Transcription Vocabulary that has previously been created. Supply the unique Transcription Vocabulary ID and Mux will return the corresponding Transcription Vocabulary information. The same information is returned when creating a Transcription Vocabulary.", "operationId": "get-transcription-vocabulary", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/transcription_vocabulary_id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionVocabularyResponse" }, "example": { "data": { "id": "VDm3npt2eaEDvz9emzun8Q", "name": "Mux API Vocabulary", "phrases": [ "Mux", "Live Stream", "Playback ID", "video encoding" ], "created_at": "1609869152", "updated_at": "1609870000" } } } } } } }, "delete": { "tags": [ "Transcription Vocabularies" ], "summary": "Delete a Transcription Vocabulary", "description": "Deletes a Transcription Vocabulary. The Transcription Vocabulary's ID will be disassociated from any live streams using it. Transcription Vocabularies can be deleted while associated live streams are active. However, the words and phrases in the deleted Transcription Vocabulary will remain attached to those streams while they are active.", "operationId": "delete-transcription-vocabulary", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/transcription_vocabulary_id" } ], "responses": { "204": { "description": "No Content" } } }, "put": { "tags": [ "Transcription Vocabularies" ], "summary": "Update a Transcription Vocabulary", "description": "Updates the details of a previously-created Transcription Vocabulary. Updates to Transcription Vocabularies are allowed while associated live streams are active. However, updates will not be applied to those streams while they are active.", "operationId": "update-transcription-vocabulary", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/transcription_vocabulary_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTranscriptionVocabularyRequest" }, "example": { "name": "Mux API Vocabulary - Updated", "phrases": [ "Mux", "Live Stream", "RTMP", "Stream Key" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionVocabularyResponse" }, "example": { "data": { "id": "VDm3npt2eaEDvz9emzun8Q", "name": "Mux API Vocabulary - Updated", "phrases": [ "Mux", "Live Stream", "RTMP", "Stream Key" ], "created_at": "1609869152", "updated_at": "1609870000" } } } } } } } }, "/video/v1/assets": { "post": { "tags": [ "Assets" ], "summary": "Create an asset", "description": "Create a new Mux Video asset.", "operationId": "create-asset", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAssetRequest" }, "example": { "inputs": [ { "url": "https://muxed.s3.amazonaws.com/leds.mp4" } ], "playback_policies": [ "public" ], "video_quality": "basic" } } } }, "responses": { "201": { "description": "Asset Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetResponse" }, "example": { "data": { "status": "preparing", "playback_ids": [ { "policy": "public", "id": "uNbxnGLKJ00yfbijDO8COxTOyVKT01xpxW" } ], "master_access": "none", "id": "SqQnqz6s5MBuXGvJaUWdXuXM93J9Q2yv", "encoding_tier": "baseline", "video_quality": "basic", "created_at": "1607452572", "max_resolution_tier": "1080p", "progress": { "state": "ingesting", "progress": 0 } } } } } } } }, "get": { "tags": [ "Assets" ], "summary": "List assets", "description": "List all Mux assets.", "operationId": "list-assets", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/list_asset_live_stream_id" }, { "$ref": "#/components/parameters/list_asset_upload_id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAssetsResponse" }, "example": { "next_cursor": "tF601CUtCLmnYuHW01Vwl6BWcWTNv001uoaiK4C01jqk1acX802plAjZhTQ", "data": [ { "tracks": [ { "type": "video", "max_width": 1920, "max_height": 800, "max_frame_rate": 24, "id": "HK01Bq7FrEQmIu3QpRiZZ98HQOOZjm6BYyg17eEunlyo", "duration": 734.166667 }, { "type": "audio", "max_channels": 2, "id": "nNKHJqw2G9cE019AoK16CJr3O27gGnbtW4w525hJWqWw", "duration": 734.143991 } ], "status": "ready", "playback_ids": [ { "policy": "public", "id": "85g23gYz7NmQu02YsY81ihuod6cZMxCp017ZrfglyLCKc" } ], "max_stored_resolution": "HD", "resolution_tier": "1080p", "max_stored_frame_rate": 24, "master_access": "none", "id": "8jd7M77xQgf2NzuocJRPYdSdEfY5dLlcRwFARtgQqU4", "encoding_tier": "baseline", "video_quality": "basic", "duration": 734.25, "created_at": "1609869152", "aspect_ratio": "12:5", "max_resolution_tier": "1080p", "progress": { "state": "completed", "progress": 100 } }, { "tracks": [ { "type": "video", "max_width": 1920, "max_height": 1080, "max_frame_rate": 29.97, "id": "RiyQPM31a1SPtfI802bEP2zD02F5FQVNL801FRHeE5t01G4", "duration": 23.8238 }, { "type": "audio", "max_channels": 2, "id": "LvINTciHVoC017knMCH01y9pSi5OrDLCRaBPNDAoNJcmg", "duration": 23.823792 } ], "status": "ready", "playback_ids": [ { "policy": "public", "id": "vAFLI2eKFFicXX00iHBS2vqt5JjJGg5HV6fQ4Xijgt1I" } ], "max_stored_resolution": "HD", "resolution_tier": "1080p", "max_stored_frame_rate": 29.97, "master_access": "none", "id": "lJ4bGGsp7ZlPf02nMg015W02iHQLN9XnuuLRBsPS00xqd68", "encoding_tier": "smart", "video_quality": "plus", "duration": 23.857167, "created_at": "1609868768", "aspect_ratio": "16:9", "max_resolution_tier": "1080p", "progress": { "state": "completed", "progress": 100 } } ] } } } } } } }, "/video/v1/assets/{ASSET_ID}": { "get": { "tags": [ "Assets" ], "summary": "Retrieve an asset", "description": "Retrieves the details of an asset that has previously been created. Supply the unique asset ID that was returned from your previous request, and Mux will return the corresponding asset information. The same information is returned when creating an asset.", "operationId": "get-asset", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/asset_id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetResponse" }, "example": { "data": { "tracks": [ { "type": "video", "max_width": 1920, "max_height": 1080, "max_frame_rate": 29.97, "id": "RiyQPM31a1SPtfI802bEP2zD02F5FQVNL801FRHeE5t01G4", "duration": 23.8238 }, { "type": "audio", "max_channels": 2, "id": "LvINTciHVoC017knMCH01y9pSi5OrDLCRaBPNDAoNJcmg", "duration": 23.823792 } ], "status": "ready", "resolution_tier": "1080p", "playback_ids": [ { "policy": "public", "id": "vAFLI2eKFFicXX00iHBS2vqt5JjJGg5HV6fQ4Xijgt1I" } ], "passthrough": "example", "max_stored_resolution": "HD", "max_stored_frame_rate": 29.97, "max_resolution_tier": "1080p", "progress": { "state": "completed", "progress": 100 }, "master_access": "none", "id": "lJ4bGGsp7ZlPf02nMg015W02iHQLN9XnuuLRBsPS00xqd68", "encoding_tier": "baseline", "video_quality": "basic", "duration": 23.857167, "created_at": "1609868768", "aspect_ratio": "16:9" } } } } } } }, "delete": { "tags": [ "Assets" ], "summary": "Delete an asset", "description": "Deletes a video asset and all its data.", "operationId": "delete-asset", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/asset_id" } ], "responses": { "204": { "description": "No Content" } } }, "patch": { "tags": [ "Assets" ], "summary": "Update an asset", "description": "Updates the details of an existing Asset with the provided Asset ID. This API currently only supports the `passthrough`, `meta` and `thumbnail_time` fields.", "operationId": "update-asset", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/asset_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAssetRequest" }, "example": { "passthrough": "Example" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetResponse" }, "example": { "data": { "tracks": [ { "type": "video", "max_width": 1920, "max_height": 1080, "max_frame_rate": 29.97, "id": "RiyQPM31a1SPtfI802bEP2zD02F5FQVNL801FRHeE5t01G4", "duration": 23.8238 }, { "type": "audio", "max_channels": 2, "id": "LvINTciHVoC017knMCH01y9pSi5OrDLCRaBPNDAoNJcmg", "duration": 23.823792 } ], "status": "ready", "playback_ids": [ { "policy": "public", "id": "vAFLI2eKFFicXX00iHBS2vqt5JjJGg5HV6fQ4Xijgt1I" } ], "max_stored_resolution": "HD", "resolution_tier": "1080p", "max_stored_frame_rate": 29.97, "master_access": "none", "id": "lJ4bGGsp7ZlPf02nMg015W02iHQLN9XnuuLRBsPS00xqd68", "encoding_tier": "baseline", "video_quality": "basic", "duration": 23.857167, "created_at": "1609868768", "updated_at": "1609869000", "aspect_ratio": "16:9", "passthrough": "Example", "max_resolution_tier": "1080p", "progress": { "state": "completed", "progress": 100 }, "thumbnail_time": 12.67 } } } } } } } }, "/video/v1/assets/{ASSET_ID}/input-info": { "get": { "tags": [ "Assets" ], "summary": "Retrieve asset input info", "description": "Returns a list of the input objects that were used to create the asset along with any settings that were applied to each input.", "operationId": "get-asset-input-info", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/asset_id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAssetInputInfoResponse" }, "example": { "data": [ { "settings": { "url": "https://muxed.s3.amazonaws.com/leds.mp4" }, "file": { "container_format": "mp4", "tracks": [ { "type": "video", "duration": 120, "width": 1280, "height": 720, "frame_rate": 30, "encoding": "h.264" }, { "type": "audio", "duration": 120, "sample_rate": 16000, "sample_size": 24, "encoding": "aac" } ] } }, { "settings": { "url": "https://example.com/my-video-en.srt" }, "file": { "container_format": "srt" } } ] } } } } } } }, "/video/v1/assets/{ASSET_ID}/playback-ids": { "post": { "tags": [ "Assets" ], "summary": "Create a playback ID", "description": "Creates a playback ID that can be used to stream the asset to a viewer.", "operationId": "create-asset-playback-id", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/asset_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePlaybackIDRequest" }, "example": { "policy": "public" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePlaybackIDResponse" }, "example": { "data": { "policy": "public", "id": "Lj02VZDorh9hCV00flNqPli8fmwf6KEppug01w8zDEYVlQ" } } } } } } } }, "/video/v1/assets/{ASSET_ID}/playback-ids/{PLAYBACK_ID}": { "get": { "tags": [ "Assets" ], "summary": "Retrieve a playback ID", "description": "Retrieves information about the specified playback ID.", "operationId": "get-asset-playback-id", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/asset_id" }, { "$ref": "#/components/parameters/playback_id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAssetPlaybackIDResponse" }, "example": { "data": { "policy": "public", "id": "vAFLI2eKFFicXX00iHBS2vqt5JjJGg5HV6fQ4Xijgt1I" } } } } } } }, "delete": { "tags": [ "Assets" ], "summary": "Delete a playback ID", "description": "Deletes a playback ID, rendering it nonfunctional for viewing an asset's video content. Please note that deleting the playback ID removes access to the underlying asset; a viewer who started playback before the playback ID was deleted may be able to watch the entire video for a limited duration.", "operationId": "delete-asset-playback-id", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/asset_id" }, { "$ref": "#/components/parameters/playback_id" } ], "responses": { "204": { "description": "No Content" } } } }, "/video/v1/assets/{ASSET_ID}/mp4-support": { "put": { "tags": [ "Assets" ], "summary": "Update MP4 support", "operationId": "update-asset-mp4-support", "servers": [ { "url": "https://api.mux.com" } ], "deprecated": true, "description": "This method has been deprecated. Please see the [Static Rendition API](https://www.mux.com/docs/guides/enable-static-mp4-renditions#after-asset-creation).\nAllows you to add or remove mp4 support for assets that were created without it. The values supported are `capped-1080p`, `audio-only`, `audio-only,capped-1080p`, `standard`(deprecated), and `none`. `none` means that an asset *does not* have mp4 support, so submitting a request with `mp4_support` set to `none` will delete the mp4 assets from the asset in question.\n", "parameters": [ { "$ref": "#/components/parameters/asset_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAssetMP4SupportRequest" }, "example": { "mp4_support": "capped-1080p" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetResponse" }, "example": { "data": { "tracks": [ { "type": "video", "max_width": 1920, "max_height": 1080, "max_frame_rate": 29.97, "id": "RiyQPM31a1SPtfI802bEP2zD02F5FQVNL801FRHeE5t01G4", "duration": 23.8238 }, { "type": "audio", "max_channels": 2, "id": "LvINTciHVoC017knMCH01y9pSi5OrDLCRaBPNDAoNJcmg", "duration": 23.823792 } ], "status": "ready", "static_renditions": { "status": "preparing" }, "playback_ids": [ { "policy": "public", "id": "Lj02VZDorh9hCV00flNqPli8fmwf6KEppug01w8zDEYVlQ" } ], "mp4_support": "capped-1080p", "max_stored_resolution": "HD", "resolution_tier": "1080p", "max_stored_frame_rate": 29.97, "master_access": "none", "id": "lJ4bGGsp7ZlPf02nMg015W02iHQLN9XnuuLRBsPS00xqd68", "encoding_tier": "smart", "video_quality": "plus", "duration": 23.857167, "created_at": "1609868768", "aspect_ratio": "16:9", "max_resolution_tier": "1080p", "progress": { "state": "completed", "progress": 100 } } } } } } } } }, "/video/v1/assets/{ASSET_ID}/master-access": { "put": { "tags": [ "Assets" ], "summary": "Update master access", "operationId": "update-asset-master-access", "servers": [ { "url": "https://api.mux.com" } ], "description": "Allows you to add temporary access to the master (highest-quality) version of the asset in MP4 format. A URL will be created that can be used to download the master version for 24 hours. After 24 hours Master Access will revert to \"none\".\nThis master version is not optimized for web and not meant to be streamed, only downloaded for purposes like archiving or editing the video offline.", "parameters": [ { "$ref": "#/components/parameters/asset_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAssetMasterAccessRequest" }, "example": { "master_access": "temporary" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetResponse" }, "example": { "data": { "tracks": [ { "type": "video", "max_width": 1920, "max_height": 1080, "max_frame_rate": 29.97, "id": "RiyQPM31a1SPtfI802bEP2zD02F5FQVNL801FRHeE5t01G4", "duration": 23.8238 }, { "type": "audio", "max_channels": 2, "id": "LvINTciHVoC017knMCH01y9pSi5OrDLCRaBPNDAoNJcmg", "duration": 23.823792 } ], "status": "ready", "playback_ids": [ { "policy": "public", "id": "Lj02VZDorh9hCV00flNqPli8fmwf6KEppug01w8zDEYVlQ" } ], "max_stored_resolution": "HD", "resolution_tier": "1080p", "max_stored_frame_rate": 29.97, "master_access": "temporary", "master": { "status": "preparing" }, "id": "lJ4bGGsp7ZlPf02nMg015W02iHQLN9XnuuLRBsPS00xqd68", "encoding_tier": "baseline", "video_quality": "basic", "duration": 23.857167, "created_at": "1609868768", "aspect_ratio": "16:9", "max_resolution_tier": "1080p", "progress": { "state": "completed", "progress": 100 } } } } } } } } }, "/video/v1/assets/{ASSET_ID}/static-renditions": { "post": { "tags": [ "Assets" ], "summary": "Create a static rendition for an asset", "description": "Creates a static rendition (i.e. MP4) for an asset", "operationId": "create-asset-static-rendition", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/asset_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStaticRenditionRequest" }, "example": { "resolution": "highest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStaticRenditionResponse" }, "example": { "data": { "id": "lJ4bGGsp7ZlPf02nMg015W02iHQLN9XnuuLRBsPS00xqd68", "type": "standard", "ext": "mp4", "status": "preparing", "resolution": "highest", "name": "highest.mp4" } } } } } } } }, "/video/v1/assets/{ASSET_ID}/static-renditions/{STATIC_RENDITION_ID}": { "delete": { "tags": [ "Assets" ], "summary": "Delete a single static rendition for an asset", "description": "Deletes a single static rendition for an asset", "operationId": "delete-asset-static-rendition", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/asset_id" }, { "$ref": "#/components/parameters/static_rendition_id" } ], "responses": { "204": { "description": "No Content" } } } }, "/video/v1/assets/{ASSET_ID}/thumbnail-time": { "delete": { "tags": [ "Assets" ], "summary": "Unset the thumbnail time for an asset", "description": "Unset the thumbnail time for an asset, returning the thumbnail to default behavior", "operationId": "delete-asset-thumbnail-time", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/asset_id" } ], "responses": { "204": { "description": "No Content" } } } }, "/video/v1/assets/{ASSET_ID}/tracks": { "post": { "tags": [ "Assets" ], "summary": "Create an asset track", "description": "Adds an asset track (for example, subtitles, or an alternate audio track) to an asset. Assets must be in the `ready` state before tracks can be added.", "operationId": "create-asset-track", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/asset_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTrackRequest" }, "example": { "url": "https://example.com/my-video-en.srt", "type": "text", "text_type": "subtitles", "language_code": "en-US", "name": "English", "closed_captions": true, "passthrough": "English" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTrackResponse" }, "example": { "data": { "type": "text", "text_type": "subtitles", "status": "preparing", "passthrough": "English", "name": "English", "language_code": "en-US", "id": "xBe7u01029ipxBLQhYzZCJ1cke01zCkuUsgnYtH0017nNzbpv2YcsoMDmw", "closed_captions": true } } } } } } } }, "/video/v1/assets/{ASSET_ID}/tracks/{TRACK_ID}": { "delete": { "tags": [ "Assets" ], "summary": "Delete an asset track", "description": "Removes a text or additional audio track from an asset. Neither video nor the primary audio track can be removed.", "operationId": "delete-asset-track", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/asset_id" }, { "$ref": "#/components/parameters/track_id" } ], "responses": { "204": { "description": "No Content" } } }, "patch": { "tags": [ "Assets" ], "summary": "Update an asset track", "description": "Updates the details of an existing Asset Track with the provided Asset ID and Track ID.", "operationId": "update-asset-track", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/asset_id" }, { "$ref": "#/components/parameters/track_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAssetTrackRequest" }, "example": { "language_code": "en-US", "name": "English" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAssetTrackResponse" }, "example": { "data": { "type": "text", "text_type": "subtitles", "status": "ready", "passthrough": "passthrough value", "name": "English", "language_code": "en-US", "id": "xBe7u01029ipxBLQhYzZCJ1cke01zCkuUsgnYtH0017nNzbpv2YcsoMDmw", "closed_captions": true } } } } } } } }, "/video/v1/assets/{ASSET_ID}/tracks/{TRACK_ID}/generate-subtitles": { "post": { "tags": [ "Assets" ], "summary": "Generate track subtitles", "description": "Generates subtitles (captions) for a given audio track. [See docs for more information.](https://mux.com/docs/guides/add-autogenerated-captions-and-use-transcripts#retroactively-enable-auto-generated-captions)", "operationId": "generate-asset-track-subtitles", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/asset_id" }, { "$ref": "#/components/parameters/track_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateTrackSubtitlesRequest" }, "example": { "generated_subtitles": [ { "language_code": "en", "name": "English (generated)", "passthrough": "English (generated)" } ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateTrackSubtitlesResponse" }, "example": { "data": [ { "type": "text", "text_type": "subtitles", "status": "preparing", "passthrough": "English (generated)", "name": "English (generated)", "language_code": "en", "id": "hXhnqUq0054k9SBFB5aczHhj6xMbOTlriTG7gqRn8kikv101lkFUgKNw" } ] } } } } } } }, "/video/v1/assets/{ASSET_ID}/shots": { "get": { "tags": [ "Assets" ], "summary": "Get asset shots", "description": "Retrieves the shot manifest URL containing shot boundaries and shot preview image URLs.", "operationId": "get-asset-shots", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/asset_id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAssetShotsResponse" }, "example": { "data": { "status": "completed", "created_at": "1609937654", "shots_manifest_url": "https://artifacts.mux.com/a/QrgJ00hSt802eYjdclSMdH2vCpHhxBWxgbyLrPFTziJhQ/shots.json?" } } } } } } }, "post": { "tags": [ "Assets" ], "summary": "Generate shots", "description": "Generate shot boundaries and shot preview images.", "operationId": "generate-asset-shots", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/asset_id" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateAssetShotsRequest" }, "example": {} } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateAssetShotsResponse" }, "example": { "data": { "status": "pending", "created_at": "1609937654" } } } } } } }, "delete": { "tags": [ "Assets" ], "summary": "Delete asset shots", "description": "Deletes detected shot boundaries and shot preview images on the asset.", "operationId": "delete-asset-shots", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/asset_id" } ], "responses": { "204": { "description": "No Content" } } } }, "/video/v1/live-streams": { "post": { "tags": [ "Live Streams" ], "summary": "Create a live stream", "description": "Creates a new live stream. Once created, an encoder can connect to Mux via the specified stream key and begin streaming to an audience.", "operationId": "create-live-stream", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLiveStreamRequest" }, "example": { "playback_policies": [ "public" ], "new_asset_settings": { "playback_policies": [ "public" ] } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveStreamResponse" }, "example": { "data": { "stream_key": "abcdefgh", "status": "idle", "reconnect_window": 60, "playback_ids": [ { "policy": "public", "id": "HNRDuwff3K2VjTZZAPuvd2Kx6D01XUQFv02GFBHPUka018" } ], "new_asset_settings": { "playback_policies": [ "public" ] }, "id": "ZEBrNTpHC02iUah025KM3te6ylM7W4S4silsrFtUkn3Ag", "created_at": "1609937654", "latency_mode": "standard", "max_continuous_duration": 43200 } } } } } } }, "get": { "tags": [ "Live Streams" ], "summary": "List live streams", "description": "Lists the live streams that currently exist in the current environment.", "operationId": "list-live-streams", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/stream_key" }, { "name": "status", "in": "query", "description": "Filter response to return live streams with the specified status only", "required": false, "schema": { "$ref": "#/components/schemas/LiveStreamStatus" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListLiveStreamsResponse" }, "example": { "data": [ { "stream_key": "831b5bde-cd8a-5bc4-115d-4ba34b19f481", "status": "idle", "reconnect_window": 60, "playback_ids": [ { "policy": "public", "id": "HNRDuwff3K2VjTZZAPuvd2Kx6D01XUQFv02GFBHPUka018" } ], "new_asset_settings": { "playback_policies": [ "public" ] }, "id": "ZEBrNTpHC02iUah025KM3te6ylM7W4S4silsrFtUkn3Ag", "created_at": "1609937654", "latency_mode": "standard", "max_continuous_duration": 43200 }, { "stream_key": "d273c65e-1fc8-27dc-e9ef-56144cbceb3a", "status": "idle", "reconnect_window": 60, "recent_asset_ids": [ "SZs02xxHgYdkHp00OSCjJiHUHqzVQZNU332XPXRxe341o", "e4J9cwb5tjVxMeeV8201dC00i800ThPKKGT2SEN002dHH2s" ], "playback_ids": [ { "policy": "public", "id": "00zOcribkUmXqXHzBTpflk2771BRTcKATqPjWf7JHpuM" } ], "new_asset_settings": { "playback_policies": [ "public" ] }, "id": "B65hEUWW01ErVKDDGImKcBquYhwEAkjW6Ic3lPY0299Cc", "created_at": "1607587513", "latency_mode": "standard", "max_continuous_duration": 43200 } ] } } } } } } }, "/video/v1/live-streams/{LIVE_STREAM_ID}": { "get": { "tags": [ "Live Streams" ], "summary": "Retrieve a live stream", "description": "Retrieves the details of a live stream that has previously been created. Supply the unique live stream ID that was returned from your previous request, and Mux will return the corresponding live stream information. The same information is returned when creating a live stream.", "operationId": "get-live-stream", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/livestream_id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveStreamResponse" }, "example": { "data": { "stream_key": "831b5bde-cd8a-5bc4-115d-4ba34b19f481", "status": "idle", "reconnect_window": 60, "playback_ids": [ { "policy": "public", "id": "HNRDuwff3K2VjTZZAPuvd2Kx6D01XUQFv02GFBHPUka018" } ], "new_asset_settings": { "playback_policies": [ "public" ] }, "id": "ZEBrNTpHC02iUah025KM3te6ylM7W4S4silsrFtUkn3Ag", "created_at": "1609937654", "latency_mode": "standard", "max_continuous_duration": 43200 } } } } } } }, "delete": { "tags": [ "Live Streams" ], "summary": "Delete a live stream", "description": "Deletes a live stream from the current environment. If the live stream is currently active and being streamed to, ingest will be terminated and the encoder will be disconnected.", "operationId": "delete-live-stream", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/livestream_id" } ], "responses": { "204": { "description": "No Content" } } }, "patch": { "tags": [ "Live Streams" ], "summary": "Update a live stream", "description": "Updates the parameters of a previously-created live stream. This currently supports a subset of variables. Supply the live stream ID and the updated parameters and Mux will return the corresponding live stream information. The information returned will be the same after update as for subsequent get live stream requests.", "operationId": "update-live-stream", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/livestream_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLiveStreamRequest" }, "example": { "latency_mode": "standard", "reconnect_window": 30, "max_continuous_duration": 1200 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveStreamResponse" }, "example": { "data": { "stream_key": "831b5bde-cd8a-5bc4-115d-4ba34b19f481", "status": "idle", "reconnect_window": 30, "playback_ids": [ { "policy": "public", "id": "HNRDuwff3K2VjTZZAPuvd2Kx6D01XUQFv02GFBHPUka018" } ], "new_asset_settings": { "playback_policies": [ "public" ] }, "id": "ZEBrNTpHC02iUah025KM3te6ylM7W4S4silsrFtUkn3Ag", "created_at": "1609937654", "latency_mode": "standard", "max_continuous_duration": 1200 } } } } } } } }, "/video/v1/live-streams/{LIVE_STREAM_ID}/playback-ids": { "post": { "tags": [ "Live Streams" ], "summary": "Create a live stream playback ID", "description": "Create a new playback ID for this live stream, through which a viewer can watch the streamed content of the live stream.", "operationId": "create-live-stream-playback-id", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/livestream_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePlaybackIDRequest" }, "example": { "policy": "signed" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePlaybackIDResponse" }, "example": { "data": { "policy": "public", "id": "4O902oOPU100s7XIQgOeY01U7dHzYlBe26zi3Sq01EJqnxw" } } } } } } } }, "/video/v1/live-streams/{LIVE_STREAM_ID}/playback-ids/{PLAYBACK_ID}": { "get": { "tags": [ "Live Streams" ], "summary": "Retrieve a live stream playback ID", "description": "Fetches information about a live stream's playback ID, through which a viewer can watch the streamed content from this live stream.", "operationId": "get-live-stream-playback-id", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/livestream_id" }, { "$ref": "#/components/parameters/playback_id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetLiveStreamPlaybackIDResponse" }, "example": { "data": { "policy": "public", "id": "4O902oOPU100s7XIQgOeY01U7dHzYlBe26zi3Sq01EJqnxw" } } } } } } }, "delete": { "tags": [ "Live Streams" ], "summary": "Delete a live stream playback ID", "description": "Deletes the playback ID for the live stream. This will not disable ingest (as the live stream still exists). New attempts to play back the live stream will fail immediately. However, current viewers will be able to continue watching the stream for some period of time.", "operationId": "delete-live-stream-playback-id", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/livestream_id" }, { "$ref": "#/components/parameters/playback_id" } ], "responses": { "204": { "description": "No Content" } } } }, "/video/v1/live-streams/{LIVE_STREAM_ID}/reset-stream-key": { "post": { "tags": [ "Live Streams" ], "summary": "Reset a live stream's stream key", "description": "Reset a live stream key if you want to immediately stop the current stream key from working and create a new stream key that can be used for future broadcasts.", "operationId": "reset-stream-key", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/livestream_id" } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveStreamResponse" }, "example": { "data": { "stream_key": "acaf2ca1-ba9c-5ffe-8c9c-a02bbf0009a6", "status": "idle", "reconnect_window": 60, "playback_ids": [ { "policy": "public", "id": "HNRDuwff3K2VjTZZAPuvd2Kx6D01XUQFv02GFBHPUka018" }, { "policy": "public", "id": "4O902oOPU100s7XIQgOeY01U7dHzYlBe26zi3Sq01EJqnxw" } ], "new_asset_settings": { "playback_policies": [ "public" ] }, "id": "ZEBrNTpHC02iUah025KM3te6ylM7W4S4silsrFtUkn3Ag", "created_at": "1609937654", "latency_mode": "standard", "max_continuous_duration": 43200 } } } } } } } }, "/video/v1/live-streams/{LIVE_STREAM_ID}/complete": { "put": { "tags": [ "Live Streams" ], "summary": "Signal a live stream is finished", "description": "(Optional) End the live stream recording immediately instead of waiting for the reconnect_window. `EXT-X-ENDLIST` tag is added to the HLS manifest which notifies the player that this live stream is over.\n\nMux does not close the encoder connection immediately. Encoders are often configured to re-establish connections immediately which would result in a new recorded asset. For this reason, Mux waits for 60s before closing the connection with the encoder. This 60s timeframe is meant to give encoder operators a chance to disconnect from their end.\n", "operationId": "signal-live-stream-complete", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/livestream_id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignalLiveStreamCompleteResponse" }, "example": { "data": {} } } } } } } }, "/video/v1/live-streams/{LIVE_STREAM_ID}/disable": { "put": { "tags": [ "Live Streams" ], "summary": "Disable a live stream", "description": "Disables a live stream, making it reject incoming RTMP streams until re-enabled. The API also ends the live stream recording immediately when active. Ending the live stream recording adds the `EXT-X-ENDLIST` tag to the HLS manifest which notifies the player that this live stream is over.\n\nMux also closes the encoder connection immediately. Any attempt from the encoder to re-establish connection will fail till the live stream is re-enabled.\n", "operationId": "disable-live-stream", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/livestream_id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisableLiveStreamResponse" }, "example": { "data": {} } } } } } } }, "/video/v1/live-streams/{LIVE_STREAM_ID}/enable": { "put": { "tags": [ "Live Streams" ], "summary": "Enable a live stream", "description": "Enables a live stream, allowing it to accept an incoming RTMP stream.", "operationId": "enable-live-stream", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/livestream_id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnableLiveStreamResponse" }, "example": { "data": {} } } } } } } }, "/video/v1/live-streams/{LIVE_STREAM_ID}/embedded-subtitles": { "put": { "tags": [ "Live Streams" ], "summary": "Update a live stream's embedded subtitles", "description": "Configures a live stream to receive embedded closed captions.\nThe resulting Asset's subtitle text track will have `closed_captions: true` set.\n", "operationId": "update-live-stream-embedded-subtitles", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/livestream_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLiveStreamEmbeddedSubtitlesRequest" }, "example": { "embedded_subtitles": [ { "passthrough": "Example" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveStreamResponse" }, "example": { "data": { "stream_key": "acaf2ca1-ba9c-5ffe-8c9c-a02bbf0009a6", "status": "idle", "reconnect_window": 60, "playback_ids": [ { "policy": "public", "id": "HNRDuwff3K2VjTZZAPuvd2Kx6D01XUQFv02GFBHPUka018" }, { "policy": "public", "id": "4O902oOPU100s7XIQgOeY01U7dHzYlBe26zi3Sq01EJqnxw" } ], "new_asset_settings": { "playback_policies": [ "public" ] }, "id": "ZEBrNTpHC02iUah025KM3te6ylM7W4S4silsrFtUkn3Ag", "created_at": "1609937654", "embedded_subtitles": [ { "name": "English CC", "language_code": "en", "language_channel": "cc1", "passthrough": "Example" } ], "latency_mode": "standard", "max_continuous_duration": 43200 } } } } } } } }, "/video/v1/live-streams/{LIVE_STREAM_ID}/generated-subtitles": { "put": { "tags": [ "Live Streams" ], "summary": "Update a live stream's generated subtitles", "description": "Updates a live stream's automatic-speech-recognition-generated subtitle configuration.\nAutomatic speech recognition subtitles can be removed by sending an empty array in the\nrequest payload.\n", "operationId": "update-live-stream-generated-subtitles", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/livestream_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLiveStreamGeneratedSubtitlesRequest" }, "example": { "generated_subtitles": [ { "name": "English CC (ASR)", "language_code": "en", "passthrough": "Example" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveStreamResponse" }, "example": { "data": { "stream_key": "acaf2ca1-ba9c-5ffe-8c9c-a02bbf0009a6", "status": "idle", "reconnect_window": 60, "playback_ids": [ { "policy": "public", "id": "HNRDuwff3K2VjTZZAPuvd2Kx6D01XUQFv02GFBHPUka018" }, { "policy": "public", "id": "4O902oOPU100s7XIQgOeY01U7dHzYlBe26zi3Sq01EJqnxw" } ], "new_asset_settings": { "playback_policies": [ "public" ] }, "id": "ZEBrNTpHC02iUah025KM3te6ylM7W4S4silsrFtUkn3Ag", "created_at": "1609937654", "generated_subtitles": [ { "name": "English CC (ASR)", "language_code": "en", "passthrough": "Example" } ], "latency_mode": "standard", "max_continuous_duration": 43200 } } } } } } } }, "/video/v1/playback-ids/{PLAYBACK_ID}": { "get": { "tags": [ "Playback ID" ], "summary": "Retrieve an asset or live stream ID", "description": "Retrieves the Identifier of the Asset or Live Stream associated with the Playback ID.", "operationId": "get-asset-or-livestream-id", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/playback_id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAssetOrLiveStreamIdResponse" }, "example": { "data": { "id": "a1B2c3D4e5F6g7H8i9", "policy": "public", "object": { "type": "asset", "id": "123456789012345678" } } } } } } } } }, "/video/v1/live-streams/{LIVE_STREAM_ID}/simulcast-targets": { "post": { "tags": [ "Live Streams" ], "summary": "Create a live stream simulcast target", "description": "Create a simulcast target for the parent live stream. Simulcast target can only be created when the parent live stream is in idle state. Only one simulcast target can be created at a time with this API.", "operationId": "create-live-stream-simulcast-target", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/livestream_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSimulcastTargetRequest" }, "example": { "url": "rtmp://live.example.com/app", "stream_key": "abcdefgh", "passthrough": "Example" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulcastTargetResponse" }, "example": { "data": { "url": "rtmp://live.example.com/app", "stream_key": "abcdefgh", "status": "idle", "passthrough": "Example", "id": "le1axfGDc9ETqh6trHNTxGQ9XEhj02fOnX0200aAh24fwlmwzqKCYNJgw" } } } } } } } }, "/video/v1/live-streams/{LIVE_STREAM_ID}/simulcast-targets/{SIMULCAST_TARGET_ID}": { "delete": { "tags": [ "Live Streams" ], "summary": "Delete a live stream simulcast target", "description": "Delete the simulcast target using the simulcast target ID returned when creating the simulcast target. Simulcast Target can only be deleted when the parent live stream is in idle state.", "operationId": "delete-live-stream-simulcast-target", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/livestream_id" }, { "$ref": "#/components/parameters/simulcast_target_id" } ], "responses": { "204": { "description": "No Content" } } }, "get": { "tags": [ "Live Streams" ], "summary": "Retrieve a live stream simulcast target", "description": "Retrieves the details of the simulcast target created for the parent live stream. Supply the unique live stream ID and simulcast target ID that was returned in the response of create simulcast target request, and Mux will return the corresponding information.", "operationId": "get-live-stream-simulcast-target", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/livestream_id" }, { "$ref": "#/components/parameters/simulcast_target_id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulcastTargetResponse" }, "example": { "data": { "url": "rtmp://live.example.com/app", "stream_key": "abcdefgh", "status": "idle", "passthrough": "Example", "id": "02FU00rPq00fC9S6kygrqlxygGMdpW1lk00BkFpCfc2kGregEIr7brt7CQ" } } } } } } } }, "/video/v1/live-streams/{LIVE_STREAM_ID}/new-asset-settings/static-renditions": { "put": { "tags": [ "Live Streams" ], "summary": "Update live stream static renditions for new assets", "description": "Updates a live stream's static renditions settings for new assets. Further assets made via this live stream will create static renditions per the settings provided. You must provide all static renditions desired.", "operationId": "update-live-stream-new-asset-settings-static-renditions", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/livestream_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLiveStreamNewAssetSettingsStaticRenditionsRequest" }, "example": { "static_renditions": [ { "resolution": "audio-only" }, { "resolution": "highest" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveStreamResponse" }, "example": { "data": { "stream_key": "abcdefgh", "status": "idle", "reconnect_window": 60, "playback_ids": [ { "policy": "public", "id": "HNRDuwff3K2VjTZZAPuvd2Kx6D01XUQFv02GFBHPUka018" } ], "new_asset_settings": { "playback_policies": [ "public" ], "static_renditions": [ { "resolution": "audio-only" }, { "resolution": "highest" } ] }, "id": "ZEBrNTpHC02iUah025KM3te6ylM7W4S4silsrFtUkn3Ag", "created_at": "1609937654", "latency_mode": "standard", "max_continuous_duration": 43200 } } } } } } }, "delete": { "tags": [ "Live Streams" ], "summary": "Delete a live stream's static renditions setting for new assets", "description": "Deletes a live stream's static renditions settings for new assets. Further assets made via this live stream will not create static renditions unless re-added.", "operationId": "delete-live-stream-new-asset-settings-static-renditions", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/livestream_id" } ], "responses": { "204": { "description": "No Content" } } } }, "/video/v1/signing-keys": { "post": { "deprecated": true, "tags": [ "URL Signing Keys" ], "summary": "Create a URL signing key", "description": "This route is now deprecated, please use the `Signing Keys` API. Creates a new signing key pair. When creating a new signing key,\nthe API will generate a 2048-bit RSA key-pair and return the private key and\na generated key-id; the public key will be stored at Mux to validate signed\ntokens.\n\nNote: Any new access tokens authenticating this route will be required to have `System` level permissions.\n", "operationId": "create-url-signing-key", "servers": [ { "url": "https://api.mux.com" } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningKeyCreateResponse" }, "example": { "data": { "private_key": "abcd123=", "id": "vI5KTQ78ohYriuvWKHY6COtZWXexHGLllxksOdZuya8", "created_at": "1610108345" } } } } } } }, "get": { "deprecated": true, "tags": [ "URL Signing Keys" ], "summary": "List URL signing keys", "description": "This route is now deprecated, please use the `Signing Keys` API. Returns a list of URL signing keys.\n\nNote: Any new access tokens authenticating this route will be required to have `System` level permissions.\n", "operationId": "list-url-signing-keys", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSigningKeysResponse" }, "example": { "data": [ { "id": "vI5KTQ78ohYriuvWKHY6COtZWXexHGLllxksOdZuya8", "created_at": "1610108345" }, { "id": "jc6lJiCLMjyC202EXtRQ644sShzDv6x5tWJrbvUFpvmo", "created_at": "1608632647" } ] } } } } } } }, "/video/v1/signing-keys/{SIGNING_KEY_ID}": { "get": { "deprecated": true, "tags": [ "URL Signing Keys" ], "summary": "Retrieve a URL signing key", "description": "This route is now deprecated, please use the `Signing Keys` API. Retrieves the details of a URL signing key that has previously\nbeen created. Supply the unique signing key ID that was returned from your\nprevious request, and Mux will return the corresponding signing key information.\n**The private key is not returned in this response.**\n\nNote: Any new access tokens authenticating this route will be required to have `System` level permissions.\n", "operationId": "get-url-signing-key", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/signing_key_id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningKeyResponse" }, "example": { "data": { "id": "jc6lJiCLMjyC202EXtRQ644sShzDv6x5tWJrbvUFpvmo", "created_at": "1608632647" } } } } } } }, "delete": { "deprecated": true, "tags": [ "URL Signing Keys" ], "summary": "Delete a URL signing key", "description": "This route is now deprecated, please use the `Signing Keys` API. Deletes an existing signing key. Use with caution, as this will\ninvalidate any existing signatures and no URLs can be signed using the key\nagain.\n\nNote: Any new access tokens authenticating this route will be required to have `System` level permissions.\n", "operationId": "delete-url-signing-key", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/signing_key_id" } ], "responses": { "204": { "description": "No Content" } } } }, "/video/v1/uploads": { "post": { "operationId": "create-direct-upload", "servers": [ { "url": "https://api.mux.com" } ], "description": "Creates a new direct upload, through which video content can be uploaded for ingest to Mux.", "summary": "Create a new direct upload URL", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUploadRequest" }, "example": { "cors_origin": "https://example.com/", "new_asset_settings": { "playback_policies": [ "public" ] } } } } }, "tags": [ "Direct Uploads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadResponse" }, "example": { "data": { "url": "https://storage.googleapis.com/video-storage-us-east1-uploads/zd01Pe2bNpYhxbrwYABgFE01twZdtv4M00kts2i02GhbGjc?Expires=1610112458&GoogleAccessId=mux-direct-upload%40mux-cloud.iam.gserviceaccount.com&Signature=LCu4PMoKUo%2BJkWQAUwB9WU4bWVVfW3K5bZxSxEptBz3DrjbFxNyGvs0sriyJupZh9Jdb6FxKWFIRbxEetfnAAiesOvSPH%2F1GlIichmGg3YfebfxiX77%2B6ToFF6FMkJucBo284PD90AVLHhKagOea2VsbdO0fh78MAxGH9sEspyQ2uJEfYWjHFqYQ9smJyIuM3CYOmN5HKPgRWy2yUqzV7OTMe%2FivPO4%2FX6XiiN2J4nTmy83252CJUsHIvbiGctfKxcNI6b23UVN4B1tJTVgyxTOZiBQCkMLkD%2FEe5OhoAkvJgkqENRr0q3swO0IChDDWjrh7OTMwqvWGwAoVXEGiHg%3D%3D&upload_id=ABg5-UznTdib1HhOAMjdHhWIYqBbwmSYM6dVKyPe3v33uTeEE8gkN5QzvR3cei6uSZOSrjPn7bdvvDH3nhsrLBq8AjWY2qE4UQ", "timeout": 3600, "status": "waiting", "new_asset_settings": { "playback_policies": [ "public" ], "video_quality": "basic" }, "id": "zd01Pe2bNpYhxbrwYABgFE01twZdtv4M00kts2i02GhbGjc", "cors_origin": "https://example.com/" } } } } } } }, "get": { "operationId": "list-direct-uploads", "servers": [ { "url": "https://api.mux.com" } ], "description": "Lists direct uploads in the current environment.", "summary": "List direct uploads", "tags": [ "Direct Uploads" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUploadsResponse" }, "example": { "data": [ { "url": "https://storage.googleapis.com/video-storage-us-east1-uploads/zd01Pe2bNpYhxbrwYABgFE01twZdtv4M00kts2i02GhbGjc?Expires=1610112458&GoogleAccessId=mux-direct-upload%40mux-cloud.iam.gserviceaccount.com&Signature=LCu4PMoKUo%2BJkWQAUwB9WU4bWVVfW3K5bZxSxEptBz3DrjbFxNyGvs0sriyJupZh9Jdb6FxKWFIRbxEetfnAAiesOvSPH%2F1GlIichmGg3YfebfxiX77%2B6ToFF6FMkJucBo284PD90AVLHhKagOea2VsbdO0fh78MAxGH9sEspyQ2uJEfYWjHFqYQ9smJyIuM3CYOmN5HKPgRWy2yUqzV7OTMe%2FivPO4%2FX6XiiN2J4nTmy83252CJUsHIvbiGctfKxcNI6b23UVN4B1tJTVgyxTOZiBQCkMLkD%2FEe5OhoAkvJgkqENRr0q3swO0IChDDWjrh7OTMwqvWGwAoVXEGiHg%3D%3D&upload_id=ABg5-UznTdib1HhOAMjdHhWIYqBbwmSYM6dVKyPe3v33uTeEE8gkN5QzvR3cei6uSZOSrjPn7bdvvDH3nhsrLBq8AjWY2qE4UQ", "timeout": 3600, "status": "waiting", "new_asset_settings": { "playback_policies": [ "public" ], "video_quality": "basic" }, "id": "zd01Pe2bNpYhxbrwYABgFE01twZdtv4M00kts2i02GhbGjc", "cors_origin": "https://example.com/" }, { "timeout": 3600, "status": "asset_created", "new_asset_settings": { "playback_policies": [ "public" ], "video_quality": "basic" }, "id": "YzoCL01HHOtAVYq4Ds9zekdHJ2XqL9e8ukPWbr01KhtvM", "asset_id": "AnFVqAVXfb7vVL3ypSQDMnJZunnb8nkwe02O00p2gK8P00", "cors_origin": "https://example.com/" }, { "timeout": 10800, "status": "cancelled", "new_asset_settings": { "playback_policies": [ "public" ], "video_quality": "basic" }, "id": "AZcWu0201SqVW01LMdmVxE00m3gEWUFZPItvni1sTqF800dQ", "cors_origin": "https://example.com/" } ] } } } } } } }, "/video/v1/uploads/{UPLOAD_ID}": { "get": { "operationId": "get-direct-upload", "servers": [ { "url": "https://api.mux.com" } ], "description": "Fetches information about a single direct upload in the current environment.", "summary": "Retrieve a single direct upload's info", "tags": [ "Direct Uploads" ], "parameters": [ { "$ref": "#/components/parameters/upload_id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadResponse" }, "example": { "data": { "timeout": 3600, "status": "asset_created", "new_asset_settings": { "playback_policies": [ "public" ], "video_quality": "basic" }, "id": "YzoCL01HHOtAVYq4Ds9zekdHJ2XqL9e8ukPWbr01KhtvM", "asset_id": "AnFVqAVXfb7vVL3ypSQDMnJZunnb8nkwe02O00p2gK8P00", "cors_origin": "https://example.com/" } } } } } } } }, "/video/v1/uploads/{UPLOAD_ID}/cancel": { "put": { "operationId": "cancel-direct-upload", "servers": [ { "url": "https://api.mux.com" } ], "summary": "Cancel a direct upload", "description": "Cancels a direct upload and marks it as cancelled. If a pending upload finishes after this\nrequest, no asset will be created. This request will only succeed if the upload is still in\nthe `waiting` state.\n", "tags": [ "Direct Uploads" ], "parameters": [ { "$ref": "#/components/parameters/upload_id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadResponse" }, "example": { "data": { "timeout": 3600, "status": "cancelled", "new_asset_settings": { "playback_policies": [ "public" ], "video_quality": "basic" }, "id": "zd01Pe2bNpYhxbrwYABgFE01twZdtv4M00kts2i02GhbGjc", "cors_origin": "https://example.com/" } } } } }, "403": { "description": "Cancellation no longer possible" } } } }, "/video/v1/delivery-usage": { "get": { "tags": [ "Delivery Usage" ], "summary": "List Usage", "description": "Returns a list of delivery usage records and their associated Asset IDs or Live Stream IDs.", "operationId": "list-delivery-usage", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/delivery_usage_limit" }, { "$ref": "#/components/parameters/delivery_usage_asset_id" }, { "$ref": "#/components/parameters/delivery_usage_live_stream_id" }, { "$ref": "#/components/parameters/delivery_usage_timeframe" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDeliveryUsageResponse" }, "example": { "total_row_count": 2, "timeframe": [ 1607817600, 1607990400 ], "page": 1, "limit": 100, "data": [ { "live_stream_id": "B65hEUWW01ErVKDDGImKcBquYhwEAkjW6Ic3lPY0299Cc", "delivered_seconds": 206.366667, "delivered_seconds_by_resolution": { "tier_1080p": 100, "tier_720p": 100, "tier_audio_only": 6.366667 }, "deleted_at": "1607945257", "created_at": "1607939184", "asset_state": "deleted", "asset_id": "Ww4v2q2H4MNbHIAM2wApKb3cmrh7eHjGLUjdKohR5wM", "asset_duration": 154.366667, "asset_resolution_tier": "1080p", "asset_encoding_tier": "baseline", "asset_video_quality": "basic" }, { "delivered_seconds": 30, "delivered_seconds_by_resolution": { "tier_1080p": 10, "tier_720p": 10, "tier_audio_only": 10 }, "deleted_at": "1607935288", "created_at": "1607617107", "asset_state": "deleted", "asset_id": "Qlb007on1TwN43XLIG027QJlUxm3jd01v5PRi1aXhnyFZY", "asset_duration": 98.773667, "asset_resolution_tier": "1080p", "asset_encoding_tier": "smart", "asset_video_quality": "plus" } ] } } } } } } }, "/video/v1/playback-restrictions": { "post": { "tags": [ "Playback Restrictions" ], "summary": "Create a Playback Restriction", "description": "Create a new Playback Restriction.", "operationId": "create-playback-restriction", "servers": [ { "url": "https://api.mux.com" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePlaybackRestrictionRequest" }, "example": { "referrer": { "allowed_domains": [ "*.example.com" ], "allow_no_referrer": true }, "user_agent": { "allow_no_user_agent": false, "allow_high_risk_user_agent": false } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaybackRestrictionResponse" }, "example": { "data": { "id": "9dbEg8o00uqQzZbzJT6NXdqNA00SdnSo8O", "updated_at": "1607945257", "created_at": "1607945257", "referrer": { "allowed_domains": [ "*.example.com" ], "allow_no_referrer": true }, "user_agent": { "allow_no_user_agent": false, "allow_high_risk_user_agent": false } } } } } } } }, "get": { "tags": [ "Playback Restrictions" ], "summary": "List Playback Restrictions", "description": "Returns a list of all Playback Restrictions.", "operationId": "list-playback-restrictions", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPlaybackRestrictionsResponse" }, "example": { "total_row_count": 2, "page": 1, "limit": 100, "data": [ { "id": "9dbEg8o00uqQzZbzJT6NXdqNA00SdnSo8O", "updated_at": "1607945257", "created_at": "1607939184", "referrer": { "allowed_domains": [ "*.example.com" ], "allow_no_referrer": false }, "user_agent": { "allow_no_user_agent": false, "allow_high_risk_user_agent": false } }, { "id": "012uTQqPygDYWz3jey8cyOX9n01Bd5SDH1", "updated_at": "1607945980", "created_at": "1607939188", "referrer": { "allowed_domains": [ "a.example.com", "b.example.com" ], "allow_no_referrer": true }, "user_agent": { "allow_no_user_agent": false, "allow_high_risk_user_agent": false } } ] } } } } } } }, "/video/v1/playback-restrictions/{PLAYBACK_RESTRICTION_ID}": { "delete": { "tags": [ "Playback Restrictions" ], "summary": "Delete a Playback Restriction", "description": "Deletes a single Playback Restriction.", "operationId": "delete-playback-restriction", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/playback_restriction_id" } ], "responses": { "204": { "description": "No Content" } } }, "get": { "tags": [ "Playback Restrictions" ], "summary": "Retrieve a Playback Restriction", "description": "Retrieves a Playback Restriction associated with the unique identifier.", "operationId": "get-playback-restriction", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/playback_restriction_id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaybackRestrictionResponse" }, "example": { "data": { "id": "9dbEg8o00uqQzZbzJT6NXdqNA00SdnSo8O", "updated_at": "1607945257", "created_at": "1607939184", "referrer": { "allowed_domains": [ "*.example.com" ], "allow_no_referrer": false }, "user_agent": { "allow_no_user_agent": false, "allow_high_risk_user_agent": false } } } } } } } } }, "/video/v1/playback-restrictions/{PLAYBACK_RESTRICTION_ID}/referrer": { "put": { "tags": [ "Playback Restrictions" ], "summary": "Update the Referrer Playback Restriction", "description": "Allows you to modify the list of domains or change how Mux validates playback requests without the `Referer` HTTP header. The Referrer restriction fully replaces the old list with this new list of domains.", "operationId": "update-referrer-domain-restriction", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/playback_restriction_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateReferrerDomainRestrictionRequest" }, "example": { "allowed_domains": [ "*.example.com" ], "allow_no_referrer": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaybackRestrictionResponse" }, "example": { "data": { "id": "9dbEg8o00uqQzZbzJT6NXdqNA00SdnSo8O", "updated_at": "1607945257", "created_at": "1607939184", "referrer": { "allowed_domains": [ "*.example.com" ], "allow_no_referrer": true }, "user_agent": { "allow_no_user_agent": false, "allow_high_risk_user_agent": false } } } } } } } } }, "/video/v1/playback-restrictions/{PLAYBACK_RESTRICTION_ID}/user_agent": { "put": { "tags": [ "Playback Restrictions" ], "summary": "Update the User Agent Restriction", "description": "Allows you to modify how Mux validates playback requests with different user agents. Please see [Using User-Agent HTTP header for validation](https://docs.mux.com/guides/secure-video-playback#using-user-agent-http-header-for-validation) for more details on this feature.", "operationId": "update-user-agent-restriction", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/playback_restriction_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserAgentRestrictionRequest" }, "example": { "allow_no_user_agent": false, "allow_high_risk_user_agent": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaybackRestrictionResponse" }, "example": { "data": { "id": "9dbEg8o00uqQzZbzJT6NXdqNA00SdnSo8O", "updated_at": "1607945257", "created_at": "1607939184", "referrer": { "allowed_domains": [ "*.example.com" ], "allow_no_referrer": true }, "user_agent": { "allow_no_user_agent": false, "allow_high_risk_user_agent": false } } } } } } } } }, "/video/v1/drm-configurations": { "get": { "tags": [ "DRM Configurations" ], "summary": "List DRM Configurations", "description": "Returns a list of DRM Configurations", "operationId": "list-drm-configurations", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDRMConfigurationsResponse" }, "example": { "total_row_count": 2, "page": 1, "limit": 100, "data": [ { "id": "9dbEg8o00uqQzZbzJT6NXdqNA00SdnSo8O" }, { "id": "012uTQqPygDYWz3jey8cyOX9n01Bd5SDH1" } ] } } } } } } }, "/video/v1/drm-configurations/{DRM_CONFIGURATION_ID}": { "get": { "tags": [ "DRM Configurations" ], "summary": "Retrieve a DRM Configuration", "description": "Retrieves a single DRM Configuration.", "operationId": "get-drm-configuration", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/drm_configuration_id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DRMConfigurationResponse" }, "example": { "data": { "id": "lJ4bGGsp7ZlPf02nMg015W02iHQLN9XnuuLRBsPS00xqd68" } } } } } } } }, "/data/v1/video-views": { "get": { "tags": [ "Video Views" ], "summary": "List Video Views", "description": "Returns a list of video views which match the filters and have a `view_end` within the specified timeframe.", "operationId": "list-video-views", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/viewer_id" }, { "$ref": "#/components/parameters/error_id" }, { "$ref": "#/components/parameters/order_direction" }, { "$ref": "#/components/parameters/filters" }, { "$ref": "#/components/parameters/metric_filters" }, { "$ref": "#/components/parameters/timeframe" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListVideoViewsResponse" }, "example": { "total_row_count": 4, "timeframe": [ 1610025789, 1610112189 ], "data": [ { "viewer_os_family": "OS X", "viewer_application_name": "Chrome", "view_start": "2021-01-07T20:34:06Z", "view_end": "2021-01-07T20:46:04Z", "video_title": "my-title", "total_row_count": 4, "player_error_message": null, "player_error_code": null, "id": "JpA81zBfGaGZ85C6aGF3bptyD4CKwpdNgamr", "error_type_id": 1, "country_code": "US", "viewer_experience_score": 0.8, "watch_time": 1000, "playback_failure": false }, { "viewer_os_family": "OS X", "viewer_application_name": "Chrome", "view_start": "2021-01-07T20:21:53Z", "view_end": "2021-01-07T20:34:03Z", "video_title": "", "total_row_count": 4, "player_error_message": null, "player_error_code": null, "id": "jPVLR5giYMrLYbHM88Tkn3cM3qCRDk0jL114", "error_type_id": 1, "country_code": "US", "viewer_experience_score": 0.8, "watch_time": 1000, "playback_failure": false }, { "viewer_os_family": "OS X", "viewer_application_name": "Chrome", "view_start": "2021-01-07T15:16:06Z", "view_end": "2021-01-07T15:17:06Z", "video_title": "Video Test Title 12.14.20", "total_row_count": 4, "player_error_message": "this is an error message from the player", "player_error_code": "1001", "id": "pdLDVKBuPZJJ9YsPVmtmB9FG9gsWBWMmYar4", "error_type_id": 1, "country_code": "US", "viewer_experience_score": 0.8, "watch_time": 1000, "playback_failure": true }, { "viewer_os_family": "OS X", "viewer_application_name": "Chrome", "view_start": "2021-01-07T15:15:09Z", "view_end": "2021-01-07T15:15:17Z", "video_title": "Video Test Title 12.14.20", "total_row_count": 4, "player_error_message": null, "player_error_code": null, "id": "zbZPowWtD3z54jcGMLCJJpF79zCjB03bV7o8", "error_type_id": 1, "country_code": "US", "viewer_experience_score": 0.8, "watch_time": 1000, "playback_failure": false } ] } } } } } } }, "/data/v1/video-views/{VIDEO_VIEW_ID}": { "get": { "tags": [ "Video Views" ], "summary": "Get a Video View", "description": "Returns the details of a video view.", "operationId": "get-video-view", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/video_view_id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoViewResponse" }, "example": { "total_row_count": null, "timeframe": [ 1643133378, 1643219778 ], "data": { "id": "LOpk9M00bMWgOJ3hcTcCHmz1JjxMFRRI", "ad_attempt_count": null, "ad_break_count": null, "ad_break_error_count": null, "ad_break_error_percentage": null, "ad_error_count": null, "ad_error_percentage": null, "ad_exit_before_start_count": null, "ad_exit_before_start_percentage": null, "ad_impression_count": null, "ad_playback_failure_error_type_id": null, "ad_preroll_startup_time": null, "ad_startup_error_count": null, "ad_startup_error_percentage": null, "asn": 11427, "asn_name": null, "asset_id": "rmp7fvw5lPD01l8PZ2aN74js84XrTWxHy", "audio_codec": null, "audio_codec_initial": null, "buffering_count": null, "buffering_duration": null, "buffering_rate": null, "cdn": null, "city": "Austin", "client_application_name": null, "client_application_version": null, "continent_code": null, "country_code": "US", "country_name": "United States", "custom_1": null, "custom_2": null, "custom_3": null, "custom_4": null, "custom_5": null, "custom_6": null, "custom_7": null, "custom_8": null, "custom_9": null, "custom_10": null, "environment_id": "envid123", "error_type_id": null, "events": [ { "viewer_time": 1643216891851, "playback_time": 0, "name": "playerready", "event_time": 1643216898061, "details": {} }, { "viewer_time": 1643216891853, "playback_time": 0, "name": "viewstart", "event_time": 1643216898101, "details": {} } ], "exit_before_video_start": false, "experiment_name": null, "inserted_at": "2022-01-26T17:08:18Z", "isp": null, "latitude": null, "live_stream_id": null, "live_stream_latency": null, "long_rebuffering": false, "long_resume": false, "longitude": null, "metro": null, "mux_api_version": "v1", "mux_embed": null, "mux_embed_version": null, "mux_viewer_id": "abc123viewerid", "page_load_time": null, "page_type": null, "page_url": null, "platform_description": null, "platform_summary": null, "playback_business_exception_error_type_id": null, "playback_failure": false, "playback_failure_error_type_id": null, "playback_id": null, "playback_score": null, "player_autoplay": false, "player_error_code": "1001", "player_error_context": "error context", "player_error_message": "error from player", "player_height": null, "player_instance_id": null, "player_language": null, "player_load_time": null, "player_mux_plugin_name": "apple-mux", "player_mux_plugin_version": null, "player_name": null, "player_poster": null, "player_preload": false, "player_remote_played": null, "player_software": null, "player_software_version": null, "player_source_domain": null, "player_source_duration": null, "player_source_height": null, "player_source_host_name": "stream.mux.com", "player_source_stream_type": null, "player_source_type": null, "player_source_url": "https://stream.mux.com/ax9qwyTIaUDLdmhesYDKir5kfE4Ve215.m3u8", "player_source_width": null, "player_startup_time": null, "player_version": null, "player_view_count": null, "player_width": null, "preroll_ad_asset_hostname": null, "preroll_ad_tag_hostname": null, "preroll_played": null, "preroll_requested": null, "property_id": 1234, "quality_score": null, "rebuffer_percentage": null, "rebuffering_score": null, "region": null, "rendition_change_count": null, "rendition_downshift_count": null, "rendition_upshift_count": null, "requests_for_first_preroll": null, "session_id": "b97d7b4a-8de7-4b18-8984-1f9ec3d3b5bc", "short_time": "2022-01-26T17:08:18Z", "startup_score": null, "sub_property_id": null, "time_shift_enabled": false, "time_to_first_frame": null, "updated_at": "2022-01-26T17:56:12Z", "used_captions": false, "used_fullscreen": false, "used_pip": false, "video_affiliate": null, "video_brand": null, "video_cdn_trace": [], "video_codec": null, "video_codec_initial": null, "video_content_type": null, "video_creator_id": null, "video_duration": null, "video_dynamic_range_type": null, "video_dynamic_range_type_initial": null, "video_encoding_variant": null, "video_id": "rmp7fvw5lPD01l8PZ2aN74js84XrTWxHy", "video_language": null, "video_producer": null, "video_series": null, "video_source_bitrate": null, "video_source_bitrate_initial": null, "video_source_fps": null, "video_source_fps_initial": null, "video_source_height": null, "video_source_height_initial": null, "video_source_width": null, "video_source_width_initial": null, "video_startup_business_exception_error_type_id": null, "video_startup_failure": false, "video_startup_preroll_load_time": null, "video_startup_preroll_request_time": null, "video_stream_type": null, "video_title": null, "video_variant_id": null, "video_variant_name": null, "view_average_request_latency": null, "view_average_request_throughput": null, "view_cdn_edge_pop": null, "view_cdn_origin": null, "view_content_startup_time": null, "view_drm_level": null, "view_drm_type": null, "view_dropped": false, "view_dropped_frame_count": null, "view_end": "2022-01-26T17:56:12Z", "view_error_id": null, "view_has_ad": false, "view_id": "8d00a0ca-8456-4e55-9ff8-dc501814a6b1", "view_max_downscale_percentage": "0.32222223", "view_max_playhead_position": "41126", "view_max_request_latency": null, "view_max_upscale_percentage": "0", "view_playing_time": "58134", "view_seek_count": null, "view_seek_duration": null, "view_session_id": null, "view_start": "2022-01-26T17:08:18Z", "view_total_content_playback_time": 37521, "view_total_downscaling": null, "view_total_upscaling": null, "viewer_application_engine": null, "viewer_application_name": null, "viewer_application_version": null, "viewer_connection_type": null, "viewer_device_category": null, "viewer_device_manufacturer": null, "viewer_device_model": "iPhone10,4", "viewer_device_name": null, "viewer_experience_score": null, "viewer_os_architecture": null, "viewer_os_family": null, "viewer_os_version": "15.1", "viewer_plan": null, "viewer_plan_category": null, "viewer_plan_status": null, "viewer_user_agent": null, "viewer_user_id": null, "watch_time": null, "watched": true, "weighted_average_bitrate": 697078 } } } } } } } }, "/data/v1/errors": { "get": { "tags": [ "Errors" ], "summary": "List Errors", "description": "Returns a list of errors.", "operationId": "list-errors", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/filters" }, { "$ref": "#/components/parameters/metric_filters" }, { "$ref": "#/components/parameters/timeframe" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListErrorsResponse" }, "example": { "total_row_count": 1, "timeframe": [ 1610027061, 1610113461 ], "data": [ { "percentage": 30, "notes": "a helpful note", "message": "an error message", "last_seen": "2021-01-08T13:42:39Z", "id": 1, "description": "a description for this error", "count": 1, "code": 100, "player_error_code": "100" } ] } } } } } } }, "/data/v1/filters": { "get": { "deprecated": true, "tags": [ "Filters" ], "summary": "List Filters", "description": "The API has been replaced by the list-dimensions API call.\n\nLists all the filters broken out into basic and advanced.\n", "operationId": "list-filters", "servers": [ { "url": "https://api.mux.com" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFiltersResponse" }, "example": { "total_row_count": 1, "timeframe": [ 1610027251, 1610113651 ], "data": { "basic": [ "browser", "operating_system", "player_remote_played", "player_software", "player_software_version", "player_mux_plugin_name", "player_mux_plugin_version", "player_autoplay", "player_preload", "video_title", "video_id", "stream_type", "source_type", "source_hostname", "continent_code", "country", "player_error_code", "asset_id", "live_stream_id", "playback_id", "video_content_type", "page_type", "view_drm_type", "view_has_ad", "custom_1", "custom_2", "custom_3", "custom_4", "custom_5", "custom_6", "custom_7", "custom_8", "custom_9", "custom_10", "view_dropped" ], "advanced": [ "browser_version", "operating_system_version", "viewer_device_name", "viewer_device_model", "viewer_device_category", "viewer_device_manufacturer", "player_name", "player_version", "video_series", "video_encoding_variant", "experiment_name", "sub_property_id", "asn", "cdn", "viewer_connection_type", "view_session_id", "region", "viewer_user_id", "exit_before_video_start", "video_startup_failure", "playback_failure", "preroll_ad_asset_hostname", "preroll_ad_tag_hostname", "preroll_played", "preroll_requested", "playback_business_exception", "video_startup_business_exception", "ad_playback_failure", "content_playback_failure" ] } } } } } } } }, "/data/v1/filters/{FILTER_ID}": { "get": { "deprecated": true, "tags": [ "Filters" ], "summary": "Lists values for a specific filter", "description": "The API has been replaced by the list-dimension-values API call.\n\nLists the values for a filter along with a total count of related views.\n", "operationId": "list-filter-values", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/filter_id" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/filters" }, { "$ref": "#/components/parameters/timeframe" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFilterValuesResponse" }, "example": { "total_row_count": 1, "timeframe": [ 1610028123, 1610114523 ], "data": [ { "value": "Chrome", "total_count": 5 } ] } } } } } } }, "/data/v1/dimensions": { "get": { "tags": [ "Dimensions" ], "summary": "List Dimensions", "description": "List all available dimensions.\n\nNote: This API replaces the list-filters API call.\n", "operationId": "list-dimensions", "servers": [ { "url": "https://api.mux.com" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDimensionsResponse" }, "example": { "data": { "advanced": [ "asn", "audio_codec", "audio_codec_initial", "browser_version", "client_application_name", "client_application_version", "country", "custom_1", "custom_2", "custom_3", "custom_4", "custom_5", "custom_6", "custom_7", "custom_8", "custom_9", "custom_10", "custom_11", "custom_12", "custom_13", "custom_14", "custom_15", "custom_16", "custom_17", "custom_18", "custom_19", "custom_20", "experiment_name", "environment_id", "operating_system_version", "page_type", "page_url", "playback_failure", "playback_business_exception", "player_autoplay", "player_error_code", "player_language", "player_mux_plugin_name", "player_mux_plugin_version", "player_poster", "player_preload", "player_remote_played", "player_software_version", "player_version", "region", "source_hostname", "time_shift_enabled", "used_captions", "used_pip", "video_affiliate", "video_brand", "video_cdn_trace", "video_codec", "video_codec_initial", "video_creator_id", "video_dynamic_range_type", "video_dynamic_range_type_initial", "video_encoding_variant", "video_language", "video_producer", "video_source_bitrate", "video_source_bitrate_initial", "video_source_fps", "video_source_fps_initial", "video_source_height", "video_source_height_initial", "video_source_width", "video_source_width_initial", "video_startup_business_exception", "video_variant_id", "video_variant_name", "view_cdn_edge_pop", "view_cdn_origin", "view_drm_type", "view_dropped", "view_dropped_frame_count", "view_session_id", "viewer_connection_type", "viewer_device_model", "viewer_user_id", "viewer_plan", "viewer_plan_status", "viewer_plan_category", "view_drm_level" ], "basic": [ "asset_id", "browser", "cdn", "continent_code", "exit_before_video_start", "live_stream_id", "operating_system", "playback_id", "player_name", "player_software", "source_type", "stream_type", "sub_property_id", "video_content_type", "video_id", "video_series", "video_startup_failure", "video_title", "view_has_ad", "viewer_device_category", "viewer_device_manufacturer", "viewer_device_name" ] }, "timeframe": [ 1610033879, 1610120279 ], "total_row_count": 1 } } } } } } }, "/data/v1/dimensions/{DIMENSION_ID}": { "get": { "tags": [ "Dimensions" ], "summary": "Lists the values for a specific dimension", "description": "Lists the values for a dimension along with a total count of related views.\n\nNote: This API replaces the list-filter-values API call.\n", "operationId": "list-dimension-values", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/dimension_id" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/filters" }, { "$ref": "#/components/parameters/metric_filters" }, { "$ref": "#/components/parameters/timeframe" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDimensionValuesResponse" }, "example": { "data": [ { "total_count": 10000, "value": "FR" }, { "total_count": 5000, "value": "ES" }, { "total_count": 2000, "value": "PT" }, { "total_count": 100, "value": "DE" }, { "total_count": 1, "value": "BE" } ], "timeframe": [ 1610033976, 1610120376 ], "total_row_count": 5 } } } } } } }, "/data/v1/dimensions/{DIMENSION_ID}/elements": { "get": { "tags": [ "Dimensions" ], "summary": "Lists elements for a trace dimension", "description": "Lists the elements (values) for a trace dimension along with their total counts.\nThis endpoint is specifically designed for trace dimensions like video_cdn_trace\nthat contain arrays of values.\n", "operationId": "list-dimension-elements", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/dimension_id" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/filters" }, { "$ref": "#/components/parameters/metric_filters" }, { "$ref": "#/components/parameters/timeframe" }, { "$ref": "#/components/parameters/order_by" }, { "$ref": "#/components/parameters/order_direction" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDimensionValuesResponse" }, "example": { "total_row_count": 25, "timeframe": [ 1755069000, 1755155999 ], "data": [ { "value": "cdn_a", "total_count": 2640882 }, { "value": "cdn_b", "total_count": 1368812 }, { "value": "cdn_c", "total_count": 154541 } ] } } } } } } }, "/data/v1/exports": { "get": { "deprecated": true, "tags": [ "Exports" ], "summary": "List property video view export links", "description": "The API has been replaced by the list-exports-views API call.\n\nLists the available video view exports along with URLs to retrieve them.\n", "operationId": "list-exports", "servers": [ { "url": "https://api.mux.com" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListExportsResponse" }, "example": { "total_row_count": 10, "timeframe": [ 1610024528, 1610110928 ], "data": [ "https://s3.amazonaws.com/mux-data-exports/1/2021_01_01.csv.gz?...signature...", "https://s3.amazonaws.com/mux-data-exports/1/2021_01_02.csv.gz?...signature...", "https://s3.amazonaws.com/mux-data-exports/1/2021_01_03.csv.gz?...signature..." ] } } } } } } }, "/data/v1/exports/views": { "get": { "tags": [ "Exports" ], "summary": "List available property view exports", "description": "Lists the available video view exports along with URLs to retrieve them.", "operationId": "list-exports-views", "servers": [ { "url": "https://api.mux.com" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListVideoViewExportsResponse" }, "example": { "total_row_count": 7, "timeframe": [ 1626296941, 1626383341 ], "data": [ { "files": [ { "version": 2, "type": "csv", "path": "https://s3.amazonaws.com/mux-data-exports/1/2021_01_03.csv.gz?...signature..." } ], "export_date": "2021-01-03" }, { "files": [ { "version": 2, "type": "csv", "path": "https://s3.amazonaws.com/mux-data-exports/1/2021_01_02.csv.gz?...signature..." } ], "export_date": "2021-01-02" }, { "files": [ { "version": 2, "type": "csv", "path": "https://s3.amazonaws.com/mux-data-exports/1/2021_01_01.csv.gz?...signature..." } ], "export_date": "2021-01-01" } ] } } } } } } }, "/data/v1/metrics/{METRIC_ID}/breakdown": { "get": { "tags": [ "Metrics" ], "summary": "List breakdown values", "description": "List the breakdown values for a specific metric.", "operationId": "list-breakdown-values", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/metric_id" }, { "$ref": "#/components/parameters/group_by" }, { "$ref": "#/components/parameters/measurement" }, { "$ref": "#/components/parameters/filters" }, { "$ref": "#/components/parameters/metric_filters" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/order_by" }, { "$ref": "#/components/parameters/order_direction" }, { "$ref": "#/components/parameters/timeframe" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBreakdownValuesResponse" }, "example": { "total_row_count": 1, "timeframe": [ 1610028298, 1610114698 ], "meta": { "aggregation": "view_end" }, "data": [ { "views": 5, "value": 4, "total_watch_time": 513934, "total_playing_time": 413934, "negative_impact": 1, "field": "US" } ] } } } } } } }, "/data/v1/metrics/{METRIC_ID}/overall": { "get": { "tags": [ "Metrics" ], "summary": "Get Overall values", "description": "Returns the overall value for a specific metric, as well as the total view count and watch time.", "operationId": "get-overall-values", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/metric_id" }, { "$ref": "#/components/parameters/timeframe" }, { "$ref": "#/components/parameters/filters" }, { "$ref": "#/components/parameters/metric_filters" }, { "$ref": "#/components/parameters/measurement" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOverallValuesResponse" }, "example": { "total_row_count": 1, "timeframe": [ 1610029525, 1610115925 ], "meta": { "aggregation": "view_end" }, "data": { "value": 4, "total_watch_time": 513934, "total_playing_time": 413934, "total_views": 5 } } } } } } } }, "/data/v1/metrics/{METRIC_ID}/insights": { "get": { "tags": [ "Metrics" ], "summary": "List Insights", "description": "Returns a list of insights for a metric. These are the worst performing values across all breakdowns sorted by how much they negatively impact a specific metric.", "operationId": "list-insights", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/metric_id" }, { "$ref": "#/components/parameters/measurement" }, { "$ref": "#/components/parameters/order_direction_deprecated" }, { "$ref": "#/components/parameters/timeframe" }, { "$ref": "#/components/parameters/filters" }, { "$ref": "#/components/parameters/metric_filters" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListInsightsResponse" }, "example": { "total_row_count": 18, "timeframe": [ 1610029610, 1610116010 ], "meta": { "aggregation": "view_end" }, "data": [ { "total_watch_time": 351144, "total_playing_time": 341144, "total_views": 1, "negative_impact_score": -5, "metric": 9, "filter_value": "", "filter_column": "video_title" }, { "total_watch_time": 513934, "total_playing_time": 413934, "total_views": 5, "negative_impact_score": 0, "metric": 4, "filter_value": "US", "filter_column": "country" } ] } } } } } } }, "/data/v1/metrics/{METRIC_ID}/timeseries": { "get": { "tags": [ "Metrics" ], "summary": "Get metric timeseries data", "description": "Returns timeseries data for a specific metric.\n\nEach interval represented in the data array contains an array with the following values:\n * the first element is the interval time\n * the second element is the calculated metric value\n * the third element is the number of views in the interval that have a valid metric value\n", "operationId": "get-metric-timeseries-data", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/metric_id" }, { "$ref": "#/components/parameters/timeframe" }, { "$ref": "#/components/parameters/filters" }, { "$ref": "#/components/parameters/metric_filters" }, { "$ref": "#/components/parameters/measurement" }, { "$ref": "#/components/parameters/order_direction" }, { "$ref": "#/components/parameters/timeseries_group_by" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMetricTimeseriesDataResponse" }, "example": { "total_row_count": 2, "timeframe": [ 1610029711, 1610116111 ], "meta": { "aggregation": "view_end" }, "data": [ [ "2021-01-07T14:00:00Z", "0.8743536882994202", "154240" ], [ "2021-01-07T15:00:00Z", "0.8929105055911401", "156056" ] ] } } } } } } }, "/data/v1/metrics/comparison": { "get": { "tags": [ "Metrics" ], "summary": "List all metric values", "description": "List all of the values across every breakdown for a specific metric.", "operationId": "list-all-metric-values", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/timeframe" }, { "$ref": "#/components/parameters/filters" }, { "$ref": "#/components/parameters/metric_filters" }, { "$ref": "#/components/parameters/dimension" }, { "$ref": "#/components/parameters/value" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAllMetricValuesResponse" }, "example": { "total_row_count": 1, "timeframe": [ 1610029906, 1610116306 ], "data": [ { "watch_time": 513934, "view_count": 5, "started_views": 6, "ended_views": 5, "unique_viewers": 6, "total_playing_time": 503934, "name": "totals" }, { "value": 6, "type": "number", "name": "Views", "metric": "views", "items": [ { "value": 6, "type": "number", "name": "Unique Viewers", "metric": "unique_viewers" }, { "value": 503934, "type": "milliseconds", "name": "Playing Time", "metric": "playing_time" }, { "value": 0, "type": "number", "name": "Ad Attempts (total)", "metric": "ad_attempt_count", "measurement": "avg" }, { "value": 0, "type": "number", "name": "Ad Attempts (average)", "metric": "ad_attempt_count", "measurement": "avg" }, { "value": 0, "type": "number", "name": "Ad Breaks (total)", "metric": "ad_break_count", "measurement": "avg" }, { "value": 0, "type": "number", "name": "Ad Breaks (average)", "metric": "ad_break_count", "measurement": "avg" }, { "value": 0, "type": "number", "name": "Ad Impressions (total)", "metric": "ad_impression_count", "measurement": "avg" }, { "value": 0, "type": "number", "name": "Ad Impressions (average)", "metric": "ad_impression_count", "measurement": "avg" } ] }, { "value": 0.7803472280502319, "type": "score", "name": "Overall Score", "metric": "viewer_experience_score" }, { "value": 0.8, "type": "score", "name": "Playback Failure Score", "metric": "playback_failure_score", "items": [ { "value": 0.2, "type": "percentage", "name": "Playback Failure Percentage", "metric": "playback_failure_percentage" }, { "value": 0, "type": "percentage", "name": "Video Startup Failure Percentage", "metric": "video_startup_failure_percentage" }, { "value": 0, "type": "percentage", "name": "Exits Before Video Start", "metric": "exits_before_video_start" }, { "value": 0, "type": "percentage", "name": "View Dropped Percentage", "metric": "view_dropped_percentage" }, { "value": 0, "type": "number", "name": "Ad Errors (total)", "metric": "ad_error_count", "measurement": "sum" }, { "value": 0, "type": "number", "name": "Ad Errors (average)", "metric": "ad_error_count", "measurement": "avg" }, { "value": 0, "type": "percentage", "name": "Ad Error Percentage (average)", "metric": "ad_error_percentage", "measurement": "avg" }, { "value": 0, "type": "number", "name": "Ad Break Errors (total)", "metric": "ad_break_error_count", "measurement": "sum" }, { "value": 0, "type": "number", "name": "Ad Break Errors (average)", "metric": "ad_break_error_count", "measurement": "avg" }, { "value": 0, "type": "percentage", "name": "Ad Break Error Percentage (average)", "metric": "ad_break_error_percentage", "measurement": "avg" }, { "value": 0, "type": "percentage", "name": "Ad Startup Error Percentage (average)", "metric": "ad_startup_error_percentage", "measurement": "avg" }, { "value": 0, "type": "percentage", "name": "Ad Exit Before Start Percentage (average)", "metric": "ad_exit_before_start_percentage", "measurement": "avg" }, { "value": 0, "type": "percentage", "name": "Playback Business Exception Percentage (average)", "metric": "playback_business_exception_percentage", "measurement": "avg" }, { "value": 0, "type": "percentage", "name": "Video Startup Business Exception Percentage (average)", "metric": "video_startup_business_exception_percentage", "measurement": "avg" } ] }, { "value": 0.9991008877754212, "type": "score", "name": "Startup Time Score", "metric": "startup_time_score", "items": [ { "value": 4, "type": "milliseconds", "name": "Video Startup Time (median)", "metric": "video_startup_time", "measurement": "median" }, { "value": 9, "type": "milliseconds", "name": "Video Startup Time (95th %)", "metric": "video_startup_time", "measurement": "95th" }, { "value": 52.5625, "type": "milliseconds", "name": "Player Startup Time (median)", "metric": "player_startup_time", "measurement": "median" }, { "value": 60.0625, "type": "milliseconds", "name": "Player Startup Time (95th %)", "metric": "player_startup_time", "measurement": "95th" }, { "value": 122.37890625, "type": "milliseconds", "name": "Page Load Time (median)", "metric": "page_load_time", "measurement": "median" }, { "value": 264.0625, "type": "milliseconds", "name": "Page Load Time (95th %)", "metric": "page_load_time", "measurement": "95th" }, { "value": 182.25, "type": "milliseconds", "name": "Aggregate Startup Time (median)", "metric": "aggregate_startup_time", "measurement": "median" }, { "value": 319.515625, "type": "milliseconds", "name": "Aggregate Startup Time (95th %)", "metric": "aggregate_startup_time", "measurement": "95th" }, { "value": 3042, "type": "milliseconds", "name": "Seek Latency", "metric": "seek_latency" }, { "value": 1000, "type": "milliseconds", "name": "Content Startup Time (median)", "metric": "view_content_startup_time", "measurement": "median" }, { "value": 1403, "type": "milliseconds", "name": "Content Startup Time (95th %)", "metric": "view_content_startup_time", "measurement": "95th" }, { "value": 800, "type": "milliseconds", "name": "Ad Preroll Startup Time (median)", "metric": "ad_preroll_startup_time", "measurement": "median" }, { "value": 1243, "type": "milliseconds", "name": "Ad Preroll Startup Time (95th %)", "metric": "ad_preroll_startup_time", "measurement": "95th" } ] }, { "value": 0.9523247838020324, "type": "score", "name": "Rebuffer Score", "metric": "rebuffer_score", "items": [ { "value": 0.0005564916895943838, "type": "percentage", "name": "Rebuffer Percentage", "metric": "rebuffer_percentage" }, { "value": 0.11674650830651406, "type": "per_minute", "name": "Rebuffer Frequency", "metric": "rebuffer_frequency" }, { "value": 0, "type": "milliseconds", "name": "Rebuffer Duration (median)", "metric": "rebuffer_duration", "measurement": "median" }, { "value": 256, "type": "milliseconds", "name": "Rebuffer Duration (95th %)", "metric": "rebuffer_duration", "measurement": "95th" }, { "value": 0, "type": "number", "name": "Rebuffer Count (median)", "metric": "rebuffer_count", "measurement": "median" }, { "value": 1, "type": "number", "name": "Rebuffer Count (95th %)", "metric": "rebuffer_count", "measurement": "95th" } ] }, { "value": 1, "type": "score", "name": "Video Quality Score", "metric": "video_quality_score", "items": [ { "value": 0, "type": "percentage", "name": "Upscale Percentage (median)", "metric": "upscale_percentage", "measurement": "median" }, { "value": 0, "type": "percentage", "name": "Upscale Percentage (95th %)", "metric": "upscale_percentage", "measurement": "95th" }, { "value": 0, "type": "percentage", "name": "Upscale Percentage (average)", "metric": "upscale_percentage", "measurement": "avg" }, { "value": 0.007, "type": "percentage", "name": "Downscale Percentage (median)", "metric": "downscale_percentage", "measurement": "median" }, { "value": 0.449, "type": "percentage", "name": "Downscale Percentage (95th %)", "metric": "downscale_percentage", "measurement": "95th" }, { "value": 0.11813909473676262, "type": "percentage", "name": "Downscale Percentage (average)", "metric": "downscale_percentage", "measurement": "avg" }, { "value": 0, "type": "percentage", "name": "Max Upscale Percentage (median)", "metric": "max_upscale_percentage", "measurement": "median" }, { "value": 0, "type": "percentage", "name": "Max Upscale Percentage (95th %)", "metric": "max_upscale_percentage", "measurement": "95th" }, { "value": 0.007, "type": "percentage", "name": "Max Downscale Percentage (median)", "metric": "max_downscale_percentage", "measurement": "median" }, { "value": 0.449, "type": "percentage", "name": "Max Downscale Percentage (95th %)", "metric": "max_downscale_percentage", "measurement": "95th" }, { "value": 851582.91015625, "type": "mbps", "name": "Weighted Average Bitrate (median)", "metric": "weighted_average_bitrate", "measurement": "median" }, { "value": 697016.265625, "type": "mbps", "name": "Weighted Average Bitrate (95th %)", "metric": "weighted_average_bitrate", "measurement": "95th" }, { "value": 2195, "type": "milliseconds", "name": "Live Stream Latency (median)", "metric": "live_stream_latency", "measurement": "median" }, { "value": 3523, "type": "milliseconds", "name": "Live Stream Latency (95th %)", "metric": "live_stream_latency", "measurement": "95th" } ] } ] } } } } } } }, "/data/v1/subview-metrics/{METRIC_ID}/{SUBVIEW_TYPE}/overall": { "get": { "tags": [ "Subview Metrics" ], "summary": "Get Subview Overall Values", "description": "Returns the total subview metric value across all views matching the given filters and timeframe.", "operationId": "get-subview-overall-values", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/subview_metric_id" }, { "$ref": "#/components/parameters/subview_type" }, { "$ref": "#/components/parameters/timeframe" }, { "$ref": "#/components/parameters/subview_filters" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSubviewOverallValuesResponse" }, "example": { "data": { "metric_value": 186400000 }, "meta": { "subview_type": "rendition", "metric": "playing_time", "unit": "ms" }, "total_row_count": null, "timeframe": [ 1617235200, 1617321600 ] } } } } } } }, "/data/v1/subview-metrics/{METRIC_ID}/{SUBVIEW_TYPE}/breakdown": { "get": { "tags": [ "Subview Metrics" ], "summary": "List Subview Breakdown Values", "description": "Returns the metric value broken down by subview attributes, with each row's percentage of the total. By default, groups by all of the subview type's attributes (for example, every rendition attribute for `rendition` subviews) — use `group_by[]` to select a subset.\n", "operationId": "list-subview-breakdown-values", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/subview_metric_id" }, { "$ref": "#/components/parameters/subview_type" }, { "$ref": "#/components/parameters/timeframe" }, { "$ref": "#/components/parameters/subview_filters" }, { "$ref": "#/components/parameters/subview_group_by" }, { "$ref": "#/components/parameters/subview_breakdown_limit" }, { "$ref": "#/components/parameters/page" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSubviewBreakdownValuesResponse" }, "example": { "data": [ { "breakdown_value": "18.5Mb / 3840w / 2160h / 60fps / HEVC / 4k", "metric_value": 56200000 }, { "breakdown_value": "12Mb / 2560w / 1440h / 60fps / HEVC / 2k", "metric_value": 18200000 } ], "meta": { "subview_type": "rendition", "metric": "playing_time", "unit": "ms", "group_by": [ "video_source_bitrate", "video_source_width", "video_source_height", "video_source_fps", "video_source_codec", "video_source_rendition_name" ] }, "total_row_count": 2, "timeframe": [ 1617235200, 1617321600 ] } } } } } } }, "/data/v1/subview-metrics/{METRIC_ID}/{SUBVIEW_TYPE}/comparison": { "get": { "tags": [ "Subview Metrics" ], "summary": "List Subview Comparison Values", "description": "Returns the metric value broken down by subview attributes, for each of up to 4 selected values of a given dimension. Powers side-by-side comparisons across dimension values (for example, comparing the rendition breakdown for the US vs. India).\n", "operationId": "list-subview-comparison-values", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/subview_metric_id" }, { "$ref": "#/components/parameters/subview_type" }, { "$ref": "#/components/parameters/subview_comparison_dimension" }, { "$ref": "#/components/parameters/timeframe" }, { "$ref": "#/components/parameters/subview_filters" }, { "$ref": "#/components/parameters/subview_comparison_values" }, { "$ref": "#/components/parameters/subview_group_by" }, { "$ref": "#/components/parameters/subview_breakdown_value_limit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSubviewComparisonValuesResponse" }, "example": { "data": [ { "dimension_value": "US", "values": [ { "breakdown_value": "18.5Mb / 3840w / 2160h / 60fps / HEVC / 4k", "metric_value": 112000000 }, { "breakdown_value": "5.1Mb / 1920w / 1080h / 60fps / h264 / hi", "metric_value": 56200000 }, { "breakdown_value": "other", "metric_value": 13200000 } ] }, { "dimension_value": "FR", "values": [ { "breakdown_value": "18.5Mb / 3840w / 2160h / 60fps / HEVC / 4k", "metric_value": 41200000 }, { "breakdown_value": "other", "metric_value": 8300000 } ] } ], "meta": { "dimension": "country", "subview_type": "rendition", "metric": "playing_time", "unit": "ms", "group_by": [ "video_source_bitrate", "video_source_width", "video_source_height", "video_source_fps", "video_source_codec", "video_source_rendition_name" ] }, "total_row_count": 2, "timeframe": [ 1617235200, 1617321600 ] } } } } } } }, "/data/v1/subview-metrics/{METRIC_ID}/{SUBVIEW_TYPE}/breakdown-timeseries": { "get": { "tags": [ "Subview Metrics" ], "summary": "Get Subview Breakdown Timeseries", "description": "Returns the metric value broken down by subview attributes over time, bucketed by the requested time granularity. Powers stacked bar chart visualizations.\n\nBuckets the data pipeline has not yet finalized are omitted from `data` entirely, rather than zero-filled. Check each entry's `status` and the response's `meta.complete_through` to tell a genuinely-empty bucket apart from one that's still incomplete.\n", "operationId": "get-subview-breakdown-timeseries", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/subview_metric_id" }, { "$ref": "#/components/parameters/subview_type" }, { "$ref": "#/components/parameters/timeframe" }, { "$ref": "#/components/parameters/subview_filters" }, { "$ref": "#/components/parameters/subview_group_by" }, { "$ref": "#/components/parameters/subview_time_granularity" }, { "$ref": "#/components/parameters/subview_breakdown_value_limit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSubviewBreakdownTimeseriesResponse" }, "example": { "data": [ { "date": "2021-04-01T00:00:00Z", "status": "complete", "values": [ { "breakdown_value": "18.5Mb / 3840w / 2160h / 60fps / HEVC / 4k", "metric_value": 12500000 }, { "breakdown_value": "12Mb / 2560w / 1440h / 60fps / HEVC / 2k", "metric_value": 6300000 }, { "breakdown_value": "other", "metric_value": 4200000 } ] }, { "date": "2021-04-01T01:00:00Z", "status": "partial", "values": [ { "breakdown_value": "18.5Mb / 3840w / 2160h / 60fps / HEVC / 4k", "metric_value": 3800000 } ] } ], "meta": { "subview_type": "rendition", "metric": "playing_time", "unit": "ms", "group_by": [ "video_source_bitrate", "video_source_width", "video_source_height", "video_source_fps", "video_source_codec", "video_source_rendition_name" ], "time_granularity": "hour", "complete_through": "2021-04-01T00:59:59Z" }, "total_row_count": 2, "timeframe": [ 1617235200, 1617321600 ] } } } } } } }, "/data/v1/subview-metrics/{SUBVIEW_TYPE}/dimensions": { "get": { "tags": [ "Subview Metrics" ], "summary": "List Subview Dimensions", "description": "Lists the dimensions available for filtering and breaking down subview metrics for the given subview type. `view` dimensions describe the parent video view; `subview` dimensions are specific to the subview type itself (for example, rendition attributes for `rendition` subviews).\n", "operationId": "list-subview-dimensions", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/subview_type" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSubviewDimensionsResponse" }, "example": { "data": { "view": [ "video_id", "video_title", "video_encoding_variant", "video_variant_name", "player_name", "player_version", "client_application_name", "client_application_version", "mux_embed", "mux_embed_version", "sub_property_id", "player_autoplay", "viewer_device_category", "viewer_device_name", "viewer_device_model", "operating_system", "video_creator_id", "cdn", "continent_code", "country", "region" ], "subview": [ "video_source_bitrate", "video_source_width", "video_source_height", "video_source_fps", "video_source_codec", "video_source_rendition_name" ] }, "total_row_count": null } } } } } } }, "/data/v1/subview-metrics/{SUBVIEW_TYPE}/dimensions/{DIMENSION_NAME}": { "get": { "tags": [ "Subview Metrics" ], "summary": "List Subview Dimension Values", "description": "Returns the distinct values for a dimension, each annotated with the total playing time across all matching values. Sorted by playing time descending by default.\n", "operationId": "list-subview-dimension-values", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/subview_type" }, { "$ref": "#/components/parameters/subview_dimension_name" }, { "$ref": "#/components/parameters/timeframe" }, { "$ref": "#/components/parameters/subview_filters" }, { "$ref": "#/components/parameters/subview_dimension_values_limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/subview_dimension_values_order_by" }, { "$ref": "#/components/parameters/order_direction" }, { "$ref": "#/components/parameters/subview_query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSubviewDimensionValuesResponse" }, "example": { "data": [ { "value": "United States", "playing_time": 86400000 }, { "value": "Great Britain", "playing_time": 24800000 }, { "value": "Germany", "playing_time": 18200000 } ], "meta": { "subview_type": "rendition", "dimension_name": "country", "metric": "playing_time", "unit": "ms" }, "total_row_count": 3, "timeframe": [ 1617235200, 1617321600 ] } } } } } } }, "/data/v1/engagement/assets/{ASSET_ID}/heatmap": { "get": { "tags": [ "Engagement" ], "summary": "Get Engagement Heatmap for an Asset", "description": "Returns the engagement heatmap for an asset. The heatmap is an array of per-bucket engagement values across the content timeline, where the number of buckets scales with the content duration. Each value represents how engaged viewers were with that portion of the content.", "operationId": "get-engagement-heatmap-asset", "x-mux-doc-decorators": [ "public-beta" ], "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/engagement_asset_id" }, { "$ref": "#/components/parameters/timeframe" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEngagementHeatmapResponse" }, "example": { "total_row_count": 1, "timeframe": [ 1610025789, 1610112189 ], "data": { "asset_id": "rmp7fvw5lPD01l8PZ2aN74js84XrTWxHy", "heatmap": [ 0.42, 0.55, 0.61, 0.58, 0.47 ] } } } } } } } }, "/data/v1/engagement/videos/{VIDEO_ID}/heatmap": { "get": { "tags": [ "Engagement" ], "summary": "Get Engagement Heatmap for a Video", "description": "Returns the engagement heatmap for a video. The heatmap is an array of per-bucket engagement values across the content timeline, where the number of buckets scales with the content duration. Each value represents how engaged viewers were with that portion of the content.", "operationId": "get-engagement-heatmap-video", "x-mux-doc-decorators": [ "public-beta" ], "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/engagement_video_id" }, { "$ref": "#/components/parameters/timeframe" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEngagementHeatmapResponse" }, "example": { "total_row_count": 1, "timeframe": [ 1610025789, 1610112189 ], "data": { "video_id": "rmp7fvw5lPD01l8PZ2aN74js84XrTWxHy", "heatmap": [ 0.42, 0.55, 0.61, 0.58, 0.47 ] } } } } } } } }, "/data/v1/engagement/playback-ids/{PLAYBACK_ID}/heatmap": { "get": { "tags": [ "Engagement" ], "summary": "Get Engagement Heatmap for a Playback ID", "description": "Returns the engagement heatmap for a playback ID. The heatmap is an array of per-bucket engagement values across the content timeline, where the number of buckets scales with the content duration. Each value represents how engaged viewers were with that portion of the content. This only covers views for this specific playback ID; to analyze the entire asset across all of its playback IDs, use the asset ID or video ID endpoint instead.", "operationId": "get-engagement-heatmap-playback-id", "x-mux-doc-decorators": [ "public-beta" ], "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/engagement_playback_id" }, { "$ref": "#/components/parameters/timeframe" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEngagementHeatmapResponse" }, "example": { "total_row_count": 1, "timeframe": [ 1610025789, 1610112189 ], "data": { "playback_id": "rmp7fvw5lPD01l8PZ2aN74js84XrTWxHy", "heatmap": [ 0.42, 0.55, 0.61, 0.58, 0.47 ] } } } } } } } }, "/data/v1/engagement/assets/{ASSET_ID}/hotspots": { "get": { "tags": [ "Engagement" ], "summary": "Get Engagement Hotspots for an Asset", "description": "Returns the engagement hotspots for an asset. Hotspots are the most or least engaging moments of the content, each described by a start and end time (in milliseconds) and a score between 0 and 1. Set `order_direction` to `asc` to return the least engaging moments (cold spots).", "operationId": "get-engagement-hotspots-asset", "x-mux-doc-decorators": [ "public-beta" ], "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/engagement_asset_id" }, { "$ref": "#/components/parameters/timeframe" }, { "$ref": "#/components/parameters/hotspots_limit" }, { "$ref": "#/components/parameters/order_direction" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEngagementHotspotsResponse" }, "example": { "total_row_count": 2, "timeframe": [ 1610025789, 1610112189 ], "data": { "asset_id": "rmp7fvw5lPD01l8PZ2aN74js84XrTWxHy", "hotspots": [ { "start_ms": 30000, "end_ms": 45000, "score": 0.842 }, { "start_ms": 120000, "end_ms": 138000, "score": 0.713 } ] } } } } } } } }, "/data/v1/engagement/videos/{VIDEO_ID}/hotspots": { "get": { "tags": [ "Engagement" ], "summary": "Get Engagement Hotspots for a Video", "description": "Returns the engagement hotspots for a video. Hotspots are the most or least engaging moments of the content, each described by a start and end time (in milliseconds) and a score between 0 and 1. Set `order_direction` to `asc` to return the least engaging moments (cold spots).", "operationId": "get-engagement-hotspots-video", "x-mux-doc-decorators": [ "public-beta" ], "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/engagement_video_id" }, { "$ref": "#/components/parameters/timeframe" }, { "$ref": "#/components/parameters/hotspots_limit" }, { "$ref": "#/components/parameters/order_direction" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEngagementHotspotsResponse" }, "example": { "total_row_count": 2, "timeframe": [ 1610025789, 1610112189 ], "data": { "video_id": "rmp7fvw5lPD01l8PZ2aN74js84XrTWxHy", "hotspots": [ { "start_ms": 30000, "end_ms": 45000, "score": 0.842 }, { "start_ms": 120000, "end_ms": 138000, "score": 0.713 } ] } } } } } } } }, "/data/v1/engagement/playback-ids/{PLAYBACK_ID}/hotspots": { "get": { "tags": [ "Engagement" ], "summary": "Get Engagement Hotspots for a Playback ID", "description": "Returns the engagement hotspots for a playback ID. Hotspots are the most or least engaging moments of the content, each described by a start and end time (in milliseconds) and a score between 0 and 1. Set `order_direction` to `asc` to return the least engaging moments (cold spots). This only covers views for this specific playback ID; to analyze the entire asset across all of its playback IDs, use the asset ID or video ID endpoint instead.", "operationId": "get-engagement-hotspots-playback-id", "x-mux-doc-decorators": [ "public-beta" ], "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/engagement_playback_id" }, { "$ref": "#/components/parameters/timeframe" }, { "$ref": "#/components/parameters/hotspots_limit" }, { "$ref": "#/components/parameters/order_direction" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEngagementHotspotsResponse" }, "example": { "total_row_count": 2, "timeframe": [ 1610025789, 1610112189 ], "data": { "playback_id": "rmp7fvw5lPD01l8PZ2aN74js84XrTWxHy", "hotspots": [ { "start_ms": 30000, "end_ms": 45000, "score": 0.842 }, { "start_ms": 120000, "end_ms": 138000, "score": 0.713 } ] } } } } } } } }, "/data/v1/monitoring/dimensions": { "get": { "tags": [ "Monitoring" ], "summary": "List Monitoring Dimensions", "description": "Lists available monitoring dimensions.", "operationId": "list-monitoring-dimensions", "servers": [ { "url": "https://api.mux.com" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMonitoringDimensionsResponse" }, "example": { "data": [ { "display_name": "ASN", "name": "asn" }, { "display_name": "CDN", "name": "cdn" }, { "display_name": "Country", "name": "country" }, { "display_name": "Operating system", "name": "operating_system" }, { "display_name": "Player name", "name": "player_name" }, { "display_name": "Region / State", "name": "region" }, { "display_name": "Stream type", "name": "stream_type" }, { "display_name": "Sub property ID", "name": "sub_property_id" }, { "display_name": "Video series", "name": "video_series" }, { "display_name": "Video title", "name": "video_title" }, { "display_name": "View has ad", "name": "view_has_ad" } ], "timeframe": [ 1610034823, 1610121223 ], "total_row_count": 1 } } } } } } }, "/data/v1/monitoring/metrics": { "get": { "tags": [ "Monitoring" ], "summary": "List Monitoring Metrics", "description": "Lists available monitoring metrics.", "operationId": "list-monitoring-metrics", "servers": [ { "url": "https://api.mux.com" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMonitoringMetricsResponse" }, "example": { "data": [ { "display_name": "Current Average Bitrate", "name": "current-average-bitrate" }, { "display_name": "Current Concurrent Viewers (CCV)", "name": "current-concurrent-viewers" }, { "display_name": "Current Rebuffering Percentage", "name": "current-rebuffering-percentage" }, { "display_name": "Exits Before Video Start", "name": "exits-before-video-start" }, { "display_name": "Playback Failure Percentage", "name": "playback-failure-percentage" }, { "display_name": "Video Startup Failure Percentage", "name": "video-startup-failure-percentage" }, { "display_name": "Video Startup Time", "name": "video-startup-time" } ], "timeframe": [ 1610034858, 1610121258 ], "total_row_count": 1 } } } } } } }, "/data/v1/monitoring/metrics/{MONITORING_METRIC_ID}/breakdown": { "get": { "tags": [ "Monitoring" ], "summary": "Get Monitoring Breakdown", "description": "Gets breakdown information for a specific dimension and metric along with the number of concurrent viewers and negative impact score.", "operationId": "get-monitoring-breakdown", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/monitoring_metric_id" }, { "$ref": "#/components/parameters/monitoring_dimension" }, { "$ref": "#/components/parameters/timestamp" }, { "$ref": "#/components/parameters/monitoring_filters" }, { "$ref": "#/components/parameters/order_by" }, { "$ref": "#/components/parameters/order_direction" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMonitoringBreakdownResponse" }, "example": { "data": [ { "concurrent_viewers": 2680, "metric_value": 0.008195679660675846, "negative_impact": 1, "starting_up_viewers": 10, "value": "FR" }, { "concurrent_viewers": 36, "metric_value": 0.010317417106767573, "negative_impact": 4, "starting_up_viewers": 1, "value": "ES" }, { "concurrent_viewers": 30, "metric_value": 0.06408818534303201, "negative_impact": 2, "starting_up_viewers": 1, "value": "RE" }, { "concurrent_viewers": 26, "metric_value": 0.008232510579858339, "negative_impact": 7, "starting_up_viewers": 1, "value": "GB" }, { "concurrent_viewers": 10, "metric_value": 0, "negative_impact": 26, "starting_up_viewers": 0, "value": "BE" } ], "timeframe": [ 1610121421, 1610121421 ], "total_row_count": 1 } } } } } } }, "/data/v1/monitoring/metrics/{MONITORING_METRIC_ID}/breakdown-timeseries": { "get": { "tags": [ "Monitoring" ], "summary": "Get Monitoring Breakdown Timeseries", "description": "Gets timeseries of breakdown information for a specific dimension and metric. Each datapoint in the response represents 5 seconds worth of data.", "operationId": "get-monitoring-breakdown-timeseries", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/monitoring_metric_id" }, { "$ref": "#/components/parameters/monitoring_dimension" }, { "$ref": "#/components/parameters/monitoring_timeseries_timeframe" }, { "$ref": "#/components/parameters/monitoring_filters" }, { "$ref": "#/components/parameters/monitoring_timeseries_limit" }, { "$ref": "#/components/parameters/order_by" }, { "$ref": "#/components/parameters/order_direction" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMonitoringBreakdownTimeseriesResponse" }, "example": { "data": [ { "values": [ { "value": "FR", "metric_value": 0.008195679660675846, "concurrent_viewers": 2680, "starting_up_viewers": 10 }, { "value": "ES", "metric_value": 0.010317417106767573, "concurrent_viewers": 36, "starting_up_viewers": 1 }, { "value": "GB", "metric_value": 0.008232510579858339, "concurrent_viewers": 26, "starting_up_viewers": 1 } ], "date": "2023-05-18T19:36:30Z" }, { "values": [ { "value": "FR", "metric_value": 0.00724579660675846, "concurrent_viewers": 2690, "starting_up_viewers": 1 }, { "value": "ES", "metric_value": 0.014317417106767573, "concurrent_viewers": 35, "starting_up_viewers": 15 }, { "value": "GB", "metric_value": 0.007232510579851874, "concurrent_viewers": 24, "starting_up_viewers": 1 } ], "date": "2023-05-18T19:36:35Z" } ], "timeframe": [ 1684438590, 1684438600 ], "total_row_count": 2 } } } } } } }, "/data/v1/monitoring/metrics/{MONITORING_HISTOGRAM_METRIC_ID}/histogram-timeseries": { "get": { "tags": [ "Monitoring" ], "summary": "Get Monitoring Histogram Timeseries", "description": "Gets histogram timeseries information for a specific metric.", "operationId": "get-monitoring-histogram-timeseries", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/monitoring_histogram_metric_id" }, { "$ref": "#/components/parameters/monitoring_filters" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMonitoringHistogramTimeseriesResponse" }, "example": { "data": [ { "average": 5298.1612903225805, "bucket_values": [ { "count": 3, "percentage": 0.0967741935483871 }, { "count": 0, "percentage": 0 }, { "count": 0, "percentage": 0 }, { "count": 1, "percentage": 0.03225806451612903 }, { "count": 16, "percentage": 0.5161290322580645 }, { "count": 7, "percentage": 0.22580645161290322 }, { "count": 4, "percentage": 0.12903225806451613 } ], "max_percentage": 0.5161290322580645, "median": 4463, "p95": 14834, "sum": 31, "timestamp": "2021-01-08T15:30:00Z" }, { "average": 3828.4146341463415, "bucket_values": [ { "count": 5, "percentage": 0.12195121951219512 }, { "count": 0, "percentage": 0 }, { "count": 0, "percentage": 0 }, { "count": 4, "percentage": 0.0975609756097561 }, { "count": 18, "percentage": 0.43902439024390244 }, { "count": 12, "percentage": 0.2926829268292683 }, { "count": 2, "percentage": 0.04878048780487805 } ], "max_percentage": 0.43902439024390244, "median": 2625, "p95": 7378, "sum": 41, "timestamp": "2021-01-08T15:31:00Z" } ], "meta": { "bucket_unit": "milliseconds", "buckets": [ { "end": 100, "start": 0 }, { "end": 500, "start": 100 }, { "end": 1000, "start": 500 }, { "end": 2000, "start": 1000 }, { "end": 5000, "start": 2000 }, { "end": 10000, "start": 5000 }, { "end": 15000, "start": 10000 } ] }, "timeframe": [ 1610119800, 1610121540 ], "total_row_count": 1 } } } } } } }, "/data/v1/monitoring/metrics/{MONITORING_METRIC_ID}/timeseries": { "get": { "tags": [ "Monitoring" ], "summary": "Get Monitoring Timeseries", "description": "Gets Time series information for a specific metric along with the number of concurrent viewers.", "operationId": "get-monitoring-timeseries", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/monitoring_metric_id" }, { "$ref": "#/components/parameters/monitoring_filters" }, { "$ref": "#/components/parameters/monitoring_timeseries_timestamp" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMonitoringTimeseriesResponse" }, "example": { "data": [ { "concurrent_viewers": 2790, "date": "2021-01-08T15:31:20Z", "value": 2790 }, { "concurrent_viewers": 2788, "date": "2021-01-08T15:31:25Z", "value": 2788 }, { "concurrent_viewers": 2791, "date": "2021-01-08T15:31:30Z", "value": 2791 }, { "concurrent_viewers": 2791, "date": "2021-01-08T15:31:35Z", "value": 2791 }, { "concurrent_viewers": 2792, "date": "2021-01-08T15:31:40Z", "value": 2792 } ], "timeframe": [ 1610119880, 1610121675 ], "total_row_count": 1 } } } } } } }, "/data/v1/realtime/dimensions": { "get": { "deprecated": true, "tags": [ "Real-Time" ], "summary": "List Real-Time Dimensions", "description": "Lists available real-time dimensions. This API is now deprecated, please use the `List Monitoring Dimensions` API.", "operationId": "list-realtime-dimensions", "servers": [ { "url": "https://api.mux.com" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRealTimeDimensionsResponse" }, "example": { "data": [ { "display_name": "ASN", "name": "asn" }, { "display_name": "CDN", "name": "cdn" }, { "display_name": "Country", "name": "country" }, { "display_name": "Operating system", "name": "operating_system" }, { "display_name": "Player name", "name": "player_name" }, { "display_name": "Region / State", "name": "region" }, { "display_name": "Stream type", "name": "stream_type" }, { "display_name": "Sub property ID", "name": "sub_property_id" }, { "display_name": "Video series", "name": "video_series" }, { "display_name": "Video title", "name": "video_title" } ], "timeframe": [ 1610034823, 1610121223 ], "total_row_count": 1 } } } } } } }, "/data/v1/realtime/metrics": { "get": { "deprecated": true, "tags": [ "Real-Time" ], "summary": "List Real-Time Metrics", "description": "Lists available real-time metrics. This API is now deprecated, please use the `List Monitoring Metrics` API.", "operationId": "list-realtime-metrics", "servers": [ { "url": "https://api.mux.com" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRealTimeMetricsResponse" }, "example": { "data": [ { "display_name": "Current Average Bitrate", "name": "current-average-bitrate" }, { "display_name": "Current Concurrent Viewers (CCV)", "name": "current-concurrent-viewers" }, { "display_name": "Current Rebuffering Percentage", "name": "current-rebuffering-percentage" }, { "display_name": "Exits Before Video Start", "name": "exits-before-video-start" }, { "display_name": "Playback Failure Percentage", "name": "playback-failure-percentage" }, { "display_name": "Video Startup Time", "name": "video-startup-time" } ], "timeframe": [ 1610034858, 1610121258 ], "total_row_count": 1 } } } } } } }, "/data/v1/realtime/metrics/{REALTIME_METRIC_ID}/breakdown": { "get": { "deprecated": true, "tags": [ "Real-Time" ], "summary": "Get Real-Time Breakdown", "description": "Gets breakdown information for a specific dimension and metric along with the number of concurrent viewers and negative impact score. This API is now deprecated, please use the `Get Monitoring Breakdown` API.", "operationId": "get-realtime-breakdown", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/realtime_metric_id" }, { "$ref": "#/components/parameters/realtime_dimension" }, { "$ref": "#/components/parameters/timestamp" }, { "$ref": "#/components/parameters/monitoring_filters" }, { "$ref": "#/components/parameters/order_by" }, { "$ref": "#/components/parameters/order_direction" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRealTimeBreakdownResponse" }, "example": { "data": [ { "concurrent_viewers": 2680, "metric_value": 0.008195679660675846, "negative_impact": 1, "starting_up_viewers": 10, "value": "FR" }, { "concurrent_viewers": 36, "metric_value": 0.010317417106767573, "negative_impact": 4, "starting_up_viewers": 1, "value": "ES" }, { "concurrent_viewers": 30, "metric_value": 0.06408818534303201, "negative_impact": 2, "starting_up_viewers": 1, "value": "RE" }, { "concurrent_viewers": 26, "metric_value": 0.008232510579858339, "negative_impact": 7, "starting_up_viewers": 1, "value": "GB" }, { "concurrent_viewers": 10, "metric_value": 0, "negative_impact": 26, "starting_up_viewers": 0, "value": "BE" } ], "timeframe": [ 1610121421, 1610121421 ], "total_row_count": 1 } } } } } } }, "/data/v1/realtime/metrics/{REALTIME_HISTOGRAM_METRIC_ID}/histogram-timeseries": { "get": { "deprecated": true, "tags": [ "Real-Time" ], "summary": "Get Real-Time Histogram Timeseries", "description": "Gets histogram timeseries information for a specific metric. This API is now deprecated, please use the `Get Monitoring Histogram Timeseries` API.", "operationId": "get-realtime-histogram-timeseries", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/realtime_histogram_metric_id" }, { "$ref": "#/components/parameters/monitoring_filters" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRealTimeHistogramTimeseriesResponse" }, "example": { "data": [ { "average": 5298.1612903225805, "bucket_values": [ { "count": 3, "percentage": 0.0967741935483871 }, { "count": 0, "percentage": 0 }, { "count": 0, "percentage": 0 }, { "count": 1, "percentage": 0.03225806451612903 }, { "count": 16, "percentage": 0.5161290322580645 }, { "count": 7, "percentage": 0.22580645161290322 }, { "count": 4, "percentage": 0.12903225806451613 } ], "max_percentage": 0.5161290322580645, "median": 4463, "p95": 14834, "sum": 31, "timestamp": "2021-01-08T15:30:00Z" }, { "average": 3828.4146341463415, "bucket_values": [ { "count": 5, "percentage": 0.12195121951219512 }, { "count": 0, "percentage": 0 }, { "count": 0, "percentage": 0 }, { "count": 4, "percentage": 0.0975609756097561 }, { "count": 18, "percentage": 0.43902439024390244 }, { "count": 12, "percentage": 0.2926829268292683 }, { "count": 2, "percentage": 0.04878048780487805 } ], "max_percentage": 0.43902439024390244, "median": 2625, "p95": 7378, "sum": 41, "timestamp": "2021-01-08T15:31:00Z" } ], "meta": { "bucket_unit": "milliseconds", "buckets": [ { "end": 100, "start": 0 }, { "end": 500, "start": 100 }, { "end": 1000, "start": 500 }, { "end": 2000, "start": 1000 }, { "end": 5000, "start": 2000 }, { "end": 10000, "start": 5000 }, { "end": 15000, "start": 10000 } ] }, "timeframe": [ 1610119800, 1610121540 ], "total_row_count": 1 } } } } } } }, "/data/v1/realtime/metrics/{REALTIME_METRIC_ID}/timeseries": { "get": { "deprecated": true, "tags": [ "Real-Time" ], "summary": "Get Real-Time Timeseries", "description": "Gets Time series information for a specific metric along with the number of concurrent viewers. This API is now deprecated, please use the `Get Monitoring Timeseries` API.", "operationId": "get-realtime-timeseries", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/realtime_metric_id" }, { "$ref": "#/components/parameters/monitoring_filters" }, { "$ref": "#/components/parameters/monitoring_timeseries_timestamp" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRealTimeTimeseriesResponse" }, "example": { "data": [ { "concurrent_viewers": 2790, "date": "2021-01-08T15:31:20Z", "value": 2790 }, { "concurrent_viewers": 2788, "date": "2021-01-08T15:31:25Z", "value": 2788 }, { "concurrent_viewers": 2791, "date": "2021-01-08T15:31:30Z", "value": 2791 }, { "concurrent_viewers": 2791, "date": "2021-01-08T15:31:35Z", "value": 2791 }, { "concurrent_viewers": 2792, "date": "2021-01-08T15:31:40Z", "value": 2792 } ], "timeframe": [ 1610119880, 1610121675 ], "total_row_count": 1 } } } } } } }, "/data/v1/incidents": { "get": { "tags": [ "Incidents" ], "summary": "List Incidents", "description": "Returns a list of incidents.", "operationId": "list-incidents", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/order_by" }, { "$ref": "#/components/parameters/order_direction" }, { "$ref": "#/components/parameters/incident_status" }, { "$ref": "#/components/parameters/severity" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListIncidentsResponse" }, "example": { "data": [ { "affected_views": 71, "affected_views_per_hour": 29, "affected_views_per_hour_on_open": 75, "breakdowns": [ { "id": "abcdef", "name": "error_type_id", "value": "697070" } ], "description": "Something is broken", "error_description": "No seriously, something is really really broken :(", "id": "4u13td", "impact": "*71 views* were affected at a rate of *29 per hour*", "incident_key": "5312a7c0bbb5d8353bd88602f01fe58eb15e9febac8fd2f0d8ce8f1cb138145c", "measured_value": 5.9, "measured_value_on_close": 0.1, "measurement": "error_rate", "notification_rules": [], "notifications": [ { "attempted_at": "2021-01-05T09:52:15.119040Z", "id": 103014, "queued_at": "2021-01-05T09:52:14.945157Z" }, { "attempted_at": "2021-01-05T11:31:08.244462Z", "id": 102025, "queued_at": "2021-01-05T11:31:08.061924Z" } ], "resolved_at": "2021-01-05T11:31:04.000000Z", "sample_size": 1000, "sample_size_unit": "views", "severity": "alert", "started_at": "2021-01-05T09:04:46.000000Z", "status": "closed", "threshold": 5 }, { "affected_views": 132, "affected_views_per_hour": 11, "affected_views_per_hour_on_open": 65, "breakdowns": [ { "id": "abcdef", "name": "video_title", "value": "Layla the dog video 1337" }, { "id": "abcdef", "name": "error_type_id", "value": "697065" } ], "description": "Something else is broken", "error_description": "Detailed error: On no!", "id": "rd9579", "impact": "*132 views* were affected at a rate of *11 per hour*", "incident_key": "fd9add7a85a013d768f4039f9e726133eddb476c2f16b22ebfe56f18f7c03b27", "measured_value": 97, "measured_value_on_close": 1, "measurement": "error_rate", "notification_rules": [], "notifications": [ { "attempted_at": "2020-12-31T09:26:19.416919Z", "id": 102198, "queued_at": "2020-12-31T09:26:18.987717Z" }, { "attempted_at": "2020-12-31T20:23:57.279325Z", "id": 101269, "queued_at": "2020-12-31T20:23:56.997068Z" } ], "resolved_at": "2020-12-31T20:22:54.000000Z", "sample_size": 100, "sample_size_unit": "views", "severity": "alert", "started_at": "2020-12-31T07:56:22.000000Z", "status": "closed", "threshold": 96 } ], "timeframe": [ 1610035979, 1610122379 ], "total_row_count": 2 } } } } } } }, "/data/v1/incidents/{INCIDENT_ID}": { "get": { "tags": [ "Incidents" ], "summary": "Get an Incident", "description": "Returns the details of an incident.", "operationId": "get-incident", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/incident_id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncidentResponse" }, "example": { "data": { "affected_views": 2026, "affected_views_per_hour": 84, "affected_views_per_hour_on_open": 12857, "breakdowns": [ { "id": "abcdef", "name": "error_type_id", "value": "499680" }, { "id": "abcdef", "name": "video_title", "value": "Cute dogs" } ], "description": "This video is erroring a lot", "error_description": "Error Type ID 499680", "id": "g7q2df", "impact": "*2026 views* were affected at a rate of *84 per hour*", "incident_key": "045dfcbefdb68c6003aaf3bf5ed217493772519f28f14d129f95eaff159ea6d6b", "measured_value": 100, "measured_value_on_close": 8, "measurement": "error_rate", "notification_rules": [], "notifications": [ { "attempted_at": "2020-05-14T17:23:08.034662Z", "id": 63293, "queued_at": "2020-05-14T17:23:07.944457Z" }, { "attempted_at": "2020-05-13T17:22:30.444389Z", "id": 62212, "queued_at": "2020-05-13T17:22:30.354828Z" } ], "resolved_at": "2020-05-14T17:22:30.000000Z", "sample_size": 100, "sample_size_unit": "views", "severity": "alert", "started_at": "2020-05-13T17:21:54.000000Z", "status": "closed", "threshold": 100 }, "timeframe": [ 1610036456, 1610122856 ], "total_row_count": 1 } } } } } } }, "/data/v1/incidents/{INCIDENT_ID}/related": { "get": { "tags": [ "Incidents" ], "summary": "List Related Incidents", "description": "Returns all the incidents that seem related to a specific incident.", "operationId": "list-related-incidents", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/incident_id" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/order_by" }, { "$ref": "#/components/parameters/order_direction" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRelatedIncidentsResponse" }, "example": { "data": [ { "affected_views": 71, "affected_views_per_hour": 29, "affected_views_per_hour_on_open": 75, "breakdowns": [ { "id": "abcdef", "name": "error_type_id", "value": "697070" } ], "description": "Something is broken", "error_description": "No seriously, something is really really broken :(", "id": "4u13td", "impact": "*71 views* were affected at a rate of *29 per hour*", "incident_key": "5312a7c0bbb5d8353bd88602f01fe58eb15e9febac8fd2f0d8ce8f1cb138145c", "measured_value": 5.9, "measured_value_on_close": 0.1, "measurement": "error_rate", "notification_rules": [], "notifications": [ { "attempted_at": "2021-01-05T09:52:15.119040Z", "id": 103014, "queued_at": "2021-01-05T09:52:14.945157Z" }, { "attempted_at": "2021-01-05T11:31:08.244462Z", "id": 102025, "queued_at": "2021-01-05T11:31:08.061924Z" } ], "resolved_at": "2021-01-05T11:31:04.000000Z", "sample_size": 1000, "sample_size_unit": "views", "severity": "alert", "started_at": "2021-01-05T09:04:46.000000Z", "status": "closed", "threshold": 5 }, { "affected_views": 132, "affected_views_per_hour": 11, "affected_views_per_hour_on_open": 65, "breakdowns": [ { "id": "abcdef", "name": "video_title", "value": "Layla the dog video 1337" }, { "id": "abcdef", "name": "error_type_id", "value": "697065" } ], "description": "Something else is broken", "error_description": "Detailed error: On no!", "id": "rd9579", "impact": "*132 views* were affected at a rate of *11 per hour*", "incident_key": "fd9add7a85a013d768f4039f9e726133eddb476c2f16b22ebfe56f18f7c03b27", "measured_value": 97, "measured_value_on_close": 1, "measurement": "error_rate", "notification_rules": [], "notifications": [ { "attempted_at": "2020-12-31T09:26:19.416919Z", "id": 102198, "queued_at": "2020-12-31T09:26:18.987717Z" }, { "attempted_at": "2020-12-31T20:23:57.279325Z", "id": 101269, "queued_at": "2020-12-31T20:23:56.997068Z" } ], "resolved_at": "2020-12-31T20:22:54.000000Z", "sample_size": 100, "sample_size_unit": "views", "severity": "alert", "started_at": "2020-12-31T07:56:22.000000Z", "status": "closed", "threshold": 96 } ], "timeframe": [ 1610035979, 1610122379 ], "total_row_count": 2 } } } } } } }, "/data/v1/annotations": { "get": { "tags": [ "Annotations" ], "summary": "List Annotations", "description": "Returns a list of annotations.", "operationId": "list-annotations", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/order_direction" }, { "$ref": "#/components/parameters/timeframe" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAnnotationsResponse" }, "example": { "data": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "note": "This is one note", "date": "2025-04-23T19:10:00Z", "sub_property_id": "123456" }, { "id": "234e4567-e89b-12d3-a456-426614174000", "note": "This is another note", "date": "2025-04-23T19:20:00Z", "sub_property_id": null } ], "total_row_count": 2, "timeframe": [ 1745434800, 1745438400 ] } } } } } }, "post": { "tags": [ "Annotations" ], "summary": "Create Annotation", "description": "Creates a new annotation.", "operationId": "create-annotation", "servers": [ { "url": "https://api.mux.com" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationInput" }, "example": { "note": "This is a note", "date": 1745438400, "sub_property_id": "123456" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationResponse" }, "example": { "data": { "id": "123e4567-e89b-12d3-a456-426614174000", "note": "This is a note", "date": "2025-04-23T20:00:00Z", "sub_property_id": "123456" }, "total_row_count": 1, "timeframe": [ 1745434800, 1745438400 ] } } } } } } }, "/data/v1/annotations/{ANNOTATION_ID}": { "get": { "tags": [ "Annotations" ], "summary": "Get Annotation", "description": "Returns the details of a specific annotation.", "operationId": "get-annotation", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/annotation_id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationResponse" }, "example": { "data": { "id": "123e4567-e89b-12d3-a456-426614174000", "note": "This is a note", "date": "2025-04-23T19:10:00Z", "sub_property_id": "123456" }, "total_row_count": 1, "timeframe": [ 1745434800, 1745438400 ] } } } } } }, "patch": { "tags": [ "Annotations" ], "summary": "Update Annotation", "description": "Updates an existing annotation.", "operationId": "update-annotation", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/annotation_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationInput" }, "example": { "note": "This is a note", "date": 1745438400, "sub_property_id": "123456" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationResponse" }, "example": { "data": { "id": "123e4567-e89b-12d3-a456-426614174000", "note": "This is a note", "date": "2025-04-23T20:00:00Z", "sub_property_id": "123456" }, "total_row_count": 1, "timeframe": [ 1745434800, 1745438400 ] } } } } } }, "delete": { "tags": [ "Annotations" ], "summary": "Delete Annotation", "description": "Deletes an annotation.", "operationId": "delete-annotation", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/annotation_id" } ], "responses": { "204": { "description": "No Content" } } } }, "/system/v1/whoami": { "get": { "summary": "Retrieve information about your current access token.", "description": "Retrieve information about your current access token, including organization, environment, and permissions. Note that this can only be access with an access token, and _all_ access tokens can access this route, regardless of what permissions they have assigned.", "operationId": "get-whoami", "servers": [ { "url": "https://api.mux.com" } ], "tags": [ "Utilities" ], "responses": { "200": { "description": "Information retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhoAmIResponse" }, "example": { "data": { "permissions": [ "video:read", "data:read" ], "organization_name": "Mux", "organization_id": "orgid123", "environment_type": "development", "environment_name": "Development", "environment_id": "envid123", "access_token_name": "Development access token" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" }, "example": { "error": { "type": "unauthorized", "messages": [ "Unauthorized request" ] } } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedResponse" }, "example": { "errors": [ "Too many requests, retry later." ] } } } } } } }, "/system/v1/usage/exports": { "get": { "tags": [ "Usage Exports" ], "summary": "List usage export CSVs", "description": "Lists available billing usage exports for your organization along with pre-signed download URLs, sorted newest first. CSVs are available for dates between 400 days ago and yesterday.", "operationId": "list-usage-exports", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/timeframe" }, { "name": "download_url_ttl", "in": "query", "description": "Lifetime in seconds for the pre-signed download URL.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 604800, "default": 3600 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUsageExportsResponse" }, "example": { "data": [ { "date": "2026-03-30", "file_size": 1048576, "download_url": "https://storage.mux.com/org_abc123/2026-06-09.csv?X-Amz-Expires=3600&X-Amz-Signature=abc", "download_url_expires_at": 1749513600 }, { "date": "2026-03-29", "file_size": 983040, "download_url": "https://storage.mux.com/org_abc123/2026-06-08.csv?X-Amz-Expires=3600&X-Amz-Signature=def", "download_url_expires_at": 1749513600 } ], "meta": { "page": 1, "pages": 16, "limit": 25, "total": 397 } } } } }, "400": { "description": "Bad Request – an invalid `timeframe` or `download_url_ttl` value was provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" }, "example": { "error": { "type": "bad_request", "messages": [ "timeframe must be either two Unix timestamps or a single duration string (e.g. `7:days`)" ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" }, "example": { "error": { "type": "unauthorized", "messages": [ "Unauthorized request" ] } } } } }, "403": { "description": "Forbidden – the Usage CSV Export feature is not enabled for your organization. Enable it in the Mux Dashboard under **Usage > Exports**.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" }, "example": { "error": { "type": "forbidden", "messages": [ "Usage CSV export is not enabled for your organization. Enable it in the Mux Dashboard under Usage > Exports. This setting cannot be enabled via the API." ] } } } } }, "404": { "description": "Not Found – no usage CSVs exist for the specified `timeframe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" }, "example": { "error": { "type": "not_found", "messages": [ "No usage CSVs found for the requested timeframe. Initiate a backfill for that data in the Mux Dashboard under Usage > Exports" ] } } } } }, "412": { "description": "Precondition Failed – one or more usage CSVs for the specified `timeframe` are still being generated. Retry after a short delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" }, "example": { "error": { "type": "precondition_failed", "messages": [ "One or more usage CSVs for the requested timeframe are currently being processed. Try again later." ] } } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedResponse" }, "example": { "errors": [ "Too many requests, retry later." ] } } } } } } }, "/system/v1/signing-keys": { "post": { "tags": [ "Signing Keys" ], "summary": "Create a signing key", "description": "Creates a new signing key pair. When creating a new signing key, the API will generate a 2048-bit RSA key-pair and return the private key and a generated key-id; the public key will be stored at Mux to validate signed tokens.", "operationId": "create-signing-key", "servers": [ { "url": "https://api.mux.com" } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningKeyResponse" }, "example": { "data": { "private_key": "abcd123=", "id": "vI5KTQ78ohYriuvWKHY6COtZWXexHGLllxksOdZuya8", "created_at": "1610108345" } } } } } } }, "get": { "tags": [ "Signing Keys" ], "summary": "List signing keys", "description": "Returns a list of signing keys.", "operationId": "list-signing-keys", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSigningKeysResponse" }, "example": { "data": [ { "id": "vI5KTQ78ohYriuvWKHY6COtZWXexHGLllxksOdZuya8", "created_at": "1610108345" }, { "id": "jc6lJiCLMjyC202EXtRQ644sShzDv6x5tWJrbvUFpvmo", "created_at": "1608632647" } ] } } } } } } }, "/system/v1/signing-keys/{SIGNING_KEY_ID}": { "get": { "tags": [ "Signing Keys" ], "summary": "Retrieve a signing key", "description": "Retrieves the details of a signing key that has previously\nbeen created. Supply the unique signing key ID that was returned from your\nprevious request, and Mux will return the corresponding signing key information.\n**The private key is not returned in this response.**\n", "operationId": "get-signing-key", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/signing_key_id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningKeyResponse" }, "example": { "data": { "id": "jc6lJiCLMjyC202EXtRQ644sShzDv6x5tWJrbvUFpvmo", "created_at": "1608632647" } } } } } } }, "delete": { "tags": [ "Signing Keys" ], "summary": "Delete a signing key", "description": "Deletes an existing signing key. Use with caution, as this will invalidate any existing signatures and no JWTs can be signed using the key again.", "operationId": "delete-signing-key", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/signing_key_id" } ], "responses": { "204": { "description": "No Content" } } } }, "/system/v1/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List webhooks", "description": "Returns a list of webhooks configured for the current environment, sorted by creation time with the most recently created first. The `signing_secret` is not included; it is only returned once, when a webhook is created.", "operationId": "list-webhooks", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWebhooksResponse" }, "example": { "data": [ { "id": "fjk04c", "address": "https://example.com/webhook2", "enabled": false, "created_at": "2026-07-21T17:05:32.000000Z" }, { "id": "abc12d", "address": "https://example.com/webhook", "enabled": true, "created_at": "2026-07-15T12:00:00.000000Z" } ], "total_row_count": 2, "page": 1, "limit": 25 } } } }, "400": { "description": "Invalid pagination parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemErrorResponse" } } } } } }, "post": { "tags": [ "Webhooks" ], "summary": "Create a webhook", "description": "Creates a new webhook for the current environment. New webhooks start out enabled. The `address` must be unique among the environment's webhooks. **The `signing_secret` is only returned in this response and cannot be retrieved again.** Store it securely and use it to verify that webhook payloads were sent by Mux.", "operationId": "create-webhook", "servers": [ { "url": "https://api.mux.com" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" }, "example": { "address": "https://example.com/webhook" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" }, "example": { "data": { "id": "abc12d", "address": "https://example.com/webhook", "enabled": true, "created_at": "2026-07-15T12:00:00.000000Z", "signing_secret": "9d0hnvbtpk3rfqe0m8s2a71cu5j6l4gd" } } } } }, "400": { "description": "A webhook with this address already exists in this environment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemErrorResponse" } } } } } } }, "/system/v1/webhooks/{WEBHOOK_ID}": { "get": { "tags": [ "Webhooks" ], "summary": "Retrieve a webhook", "description": "Retrieves the details of a webhook that has previously been created. The `signing_secret` is not included; it is only returned once, when the webhook is created.", "operationId": "get-webhook", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/webhook_id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" }, "example": { "data": { "id": "abc12d", "address": "https://example.com/webhook", "enabled": true, "created_at": "2026-07-15T12:00:00.000000Z" } } } } }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemErrorResponse" } } } } } }, "patch": { "tags": [ "Webhooks" ], "summary": "Update a webhook", "description": "Updates the address and/or enabled status of an existing webhook. Omitted fields are left unchanged; at least one of `address` or `enabled` must be provided. The new `address` must be unique among the environment's webhooks.", "operationId": "update-webhook", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/webhook_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequest" }, "example": { "address": "https://example.com/new-webhook", "enabled": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" }, "example": { "data": { "id": "abc12d", "address": "https://example.com/new-webhook", "enabled": false, "created_at": "2026-07-15T12:00:00.000000Z" } } } } }, "400": { "description": "No update fields provided, or a webhook with this address already exists in this environment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemErrorResponse" } } } }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemErrorResponse" } } } } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete a webhook", "description": "Deletes an existing webhook. Mux will no longer send event notifications to the configured address, the webhook no longer appears in list or retrieve responses, and its address becomes available for use by a new webhook (which will have a new ID and signing secret).", "operationId": "delete-webhook", "servers": [ { "url": "https://api.mux.com" } ], "parameters": [ { "$ref": "#/components/parameters/webhook_id" } ], "responses": { "204": { "description": "No Content" }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemErrorResponse" } } } } } } }, "/robots/v0/directives": { "post": { "operationId": "create-directive", "summary": "Create a directive", "description": "Creates a new directive that defines which Robots workflows should run against Mux assets, and under what resource conditions.", "tags": [ "Directives" ], "requestBody": { "description": "Directive configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDirectiveRequest" } } } }, "responses": { "201": { "description": "Directive created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectiveResponse" } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment. Accept the Robots beta terms in the Mux Dashboard to enable access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid directive configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] }, "get": { "operationId": "list-directives", "summary": "List directives", "description": "Returns a paginated list of active directives for the current environment, newest first.", "tags": [ "Directives" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Maximum number of results to return (default 25, max 100)." }, "required": false, "description": "Maximum number of results to return (default 25, max 100).", "name": "limit", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number, 1-indexed (default 1)." }, "required": false, "description": "Page number, 1-indexed (default 1).", "name": "page", "in": "query" } ], "responses": { "200": { "description": "List of directives", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectiveListResponse" } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment. Accept the Robots beta terms in the Mux Dashboard to enable access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v0/directives/{DIRECTIVE_ID}": { "get": { "operationId": "get-directive", "summary": "Get a directive", "description": "Retrieves a directive by ID.", "tags": [ "Directives" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "DIRECTIVE_ID", "in": "path" } ], "responses": { "200": { "description": "Directive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectiveResponse" } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment. Accept the Robots beta terms in the Mux Dashboard to enable access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Directive not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] }, "delete": { "operationId": "delete-directive", "summary": "Delete a directive", "description": "Deletes a directive. After this call, subsequent GET and LIST requests will no longer return it and new directive runs cannot be triggered for it. In-flight runs that have already read the directive config continue to completion.", "tags": [ "Directives" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "DIRECTIVE_ID", "in": "path" } ], "responses": { "204": { "description": "Directive deleted" }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment. Accept the Robots beta terms in the Mux Dashboard to enable access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Directive not found or already deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v0/directives/{DIRECTIVE_ID}/runs": { "get": { "operationId": "list-directive-runs", "summary": "List directive runs", "description": "Returns a paginated list of runs for a directive, newest first. Runs are retained for 30 days.", "tags": [ "Directives" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "DIRECTIVE_ID", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Maximum number of results to return (default 25, max 100)." }, "required": false, "description": "Maximum number of results to return (default 25, max 100).", "name": "limit", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number, 1-indexed (default 1)." }, "required": false, "description": "Page number, 1-indexed (default 1).", "name": "page", "in": "query" } ], "responses": { "200": { "description": "List of directive runs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectiveRunListResponse" } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment. Accept the Robots beta terms in the Mux Dashboard to enable access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Directive not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] }, "post": { "operationId": "run-directive", "summary": "Trigger a directive run", "description": "Starts a directive run against a specific Mux asset. The directive engine dispatches the configured workflows and tracks the run to terminal.", "tags": [ "Directives" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "DIRECTIVE_ID", "in": "path" } ], "requestBody": { "description": "Run parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunDirectiveRequest" } } } }, "responses": { "202": { "description": "Directive run started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectiveRunResponse" } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Free-plan workflow or unit limit prevents the directive run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Directive not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A run for this directive is already in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Asset validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v0/directives/{DIRECTIVE_ID}/runs/{RUN_ID}": { "get": { "operationId": "get-directive-run", "summary": "Get a directive run", "description": "Retrieves the status, node states, and outcome of a specific directive run. Runs are retained for 30 days.", "tags": [ "Directives" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "DIRECTIVE_ID", "in": "path" }, { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "RUN_ID", "in": "path" } ], "responses": { "200": { "description": "Directive run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectiveRunDetailResponse" } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment. Accept the Robots beta terms in the Mux Dashboard to enable access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v0/jobs": { "get": { "operationId": "list-jobs", "summary": "List jobs", "description": "Returns a paginated list of Robots jobs, with optional filters for workflow, status, and asset_id. Jobs are automatically deleted after 30 days.", "tags": [ "Jobs" ], "parameters": [ { "schema": { "type": "string", "enum": [ "summarize", "moderate", "generate-chapters", "find-scenes", "edit-captions", "translate-captions", "translate-audio", "ask-questions", "find-key-moments", "generate-engagement-insights", "generate-premium-captions", "find-best-thumbnails" ], "description": "Filter by workflow name" }, "required": false, "description": "Filter by workflow name", "name": "workflow", "in": "query" }, { "schema": { "allOf": [ { "$ref": "#/components/schemas/JobStatus" }, { "description": "Filter by job status" } ] }, "required": false, "description": "Filter by job status", "name": "status", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Filter by Mux asset ID" }, "required": false, "description": "Filter by Mux asset ID", "name": "asset_id", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Maximum number of jobs to return (default 25, max 100)" }, "required": false, "description": "Maximum number of jobs to return (default 25, max 100)", "name": "limit", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number (default 1)" }, "required": false, "description": "Page number (default 1)", "name": "page", "in": "query" } ], "responses": { "200": { "description": "List of jobs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListJobsResponse" } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment. Accept the Robots beta terms in the Mux Dashboard to enable access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v0/jobs/{JOB_ID}/cancel": { "post": { "operationId": "cancel-job", "summary": "Cancel a job", "description": "Cancels a job that is currently pending or processing.", "tags": [ "Jobs" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "JOB_ID", "in": "path" } ], "responses": { "200": { "description": "Job cancelled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelJobResponse" } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment. Accept the Robots beta terms in the Mux Dashboard to enable access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Job is already in a terminal state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v0/jobs/ask-questions": { "post": { "operationId": "create-ask-questions-job", "summary": "Create an 'ask-questions' job", "description": "Creates a new job that uses AI to answer questions about a Mux Video asset. Optional output steering can restrict execution to a time scope in seconds.", "tags": [ "Ask Questions" ], "requestBody": { "description": "Ask questions parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAskQuestionsJobRequest" }, "example": { "parameters": { "asset_id": "mux_asset_123abc", "questions": [ { "question": "Is this video about glasses?" }, { "question": "What is the primary subject?", "answer_options": [ "glasses", "watches", "shoes", "hats" ] }, { "question": "Describe the primary subject in one sentence.", "free_form_reply": true } ], "max_free_form_answer_length": 300, "output_steering": { "scope": { "start_time": 30, "end_time": 180 } } } } } } }, "responses": { "202": { "description": "Ask questions job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskQuestionsJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "ask-questions", "status": "pending", "units_consumed": 0, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "questions": [ { "question": "Is this video about glasses?" }, { "question": "What is the primary subject?", "answer_options": [ "glasses", "watches", "shoes", "hats" ] }, { "question": "Describe the primary subject in one sentence.", "free_form_reply": true } ], "max_free_form_answer_length": 300, "output_steering": { "scope": { "start_time": 30, "end_time": 180 } } } } } } } }, "401": { "description": "Missing Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment (accept the Robots beta terms in the Mux Dashboard to enable access), or a free-plan limit has prevented job creation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A job with the same workflow and parameters is already pending or processing for this environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Asset not found or missing public or signed playback ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v0/jobs/ask-questions/{JOB_ID}": { "get": { "operationId": "get-ask-questions-job", "summary": "Get an 'ask-questions' job", "description": "Retrieves the current status and results of an 'ask-questions' job. Jobs are automatically deleted after 30 days.", "tags": [ "Ask Questions" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "JOB_ID", "in": "path" } ], "responses": { "200": { "description": "Current status for the requested job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskQuestionsJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "ask-questions", "status": "completed", "units_consumed": 1, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "questions": [ { "question": "Is this video about glasses?" }, { "question": "What is the primary subject?", "answer_options": [ "glasses", "watches", "shoes", "hats" ] }, { "question": "Describe the primary subject in one sentence.", "free_form_reply": true } ], "max_free_form_answer_length": 300, "output_steering": { "scope": { "start_time": 30, "end_time": 180 } } }, "outputs": { "answers": [ { "question": "Is this video about glasses?", "answer": "no", "confidence": 0.92, "reasoning": "No glasses appear on screen and the narration does not mention eyewear.", "skipped": false }, { "question": "What is the primary subject?", "answer": "watches", "confidence": 0.88, "reasoning": "Multiple wristwatches are featured prominently throughout the video.", "skipped": false }, { "question": "Describe the primary subject in one sentence.", "answer": "A close-up showcase of luxury wristwatches arranged on a wooden display.", "confidence": 0.86, "reasoning": "Visual evidence shows several wristwatches displayed against a wooden backdrop with no other competing subjects.", "skipped": false } ] } } } } } }, "401": { "description": "Missing Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment. Accept the Robots beta terms in the Mux Dashboard to enable access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No job exists for the supplied id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v0/jobs/edit-captions": { "post": { "operationId": "create-edit-captions-job", "summary": "Create an 'edit-captions' job", "description": "Creates a new job that edits an existing Mux text track using static replacements, speaker-label replacements, and optional profanity censoring. Provide at least one of `replacements`, `speaker_replacements`, or `auto_censor_profanity`.", "tags": [ "Edit Captions" ], "requestBody": { "description": "Caption editing parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEditCaptionsJobRequest" }, "example": { "parameters": { "asset_id": "mux_asset_123abc", "track_id": "text_track_456def", "replacements": [ { "find": "Mucks", "replace": "Mux", "case_sensitive": true }, { "find": "gonna", "replace": "going to" } ], "speaker_replacements": [ { "find": "speaker_0", "replace": "Alice" } ], "upload_to_mux": true, "replace_existing_tracks": "replace" } } } } }, "responses": { "202": { "description": "Caption editing job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditCaptionsJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "edit-captions", "status": "pending", "units_consumed": 0, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "track_id": "text_track_456def", "replacements": [ { "find": "Mucks", "replace": "Mux", "case_sensitive": true }, { "find": "gonna", "replace": "going to" } ], "speaker_replacements": [ { "find": "speaker_0", "replace": "Alice" } ], "upload_to_mux": true, "replace_existing_tracks": "replace" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment (accept the Robots beta terms in the Mux Dashboard to enable access), or a free-plan limit has prevented job creation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A job with the same workflow and parameters is already pending or processing for this environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Asset not found, no public or signed playback ID, the requested text track is not ready, or another track already has the edited track's name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v0/jobs/edit-captions/{JOB_ID}": { "get": { "operationId": "get-edit-captions-job", "summary": "Get an 'edit-captions' job", "description": "Retrieves the current status and results of an 'edit-captions' job.", "tags": [ "Edit Captions" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "JOB_ID", "in": "path" } ], "responses": { "200": { "description": "Current status for the requested job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditCaptionsJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "edit-captions", "status": "completed", "units_consumed": 1, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "track_id": "text_track_456def", "replacements": [ { "find": "Mucks", "replace": "Mux", "case_sensitive": true }, { "find": "gonna", "replace": "going to" } ], "speaker_replacements": [ { "find": "speaker_0", "replace": "Alice" } ], "upload_to_mux": true, "replace_existing_tracks": "replace" }, "outputs": { "total_replacement_count": 5, "uploaded_track_id": "text_track_789ghi", "temporary_vtt_url": "https://s3.example.com/edited.vtt?sig=abc" } } } } } }, "401": { "description": "Missing Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment. Accept the Robots beta terms in the Mux Dashboard to enable access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No job exists for the supplied id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v0/jobs/find-best-thumbnails": { "post": { "operationId": "create-find-best-thumbnails-job", "summary": "Create a 'find-best-thumbnails' job", "description": "Creates a new job that samples thumbnails from a Mux Video asset, scores them with AI, and selects the best thumbnail candidates. Optional output_steering.scope hard-limits sampling to a time window expressed in seconds while returned timestamps stay absolute to the asset timeline. Other output steering can guide scoring strategy, explicit user intent, audience, and campaign style without changing the response schema.", "tags": [ "Find Best Thumbnails" ], "requestBody": { "description": "Find best thumbnails parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFindBestThumbnailsJobRequest" }, "example": { "parameters": { "asset_id": "mux_asset_123abc", "max_thumbnails": 3, "update_asset_thumbnail": true, "output_steering": { "scope": { "start_time": 30, "end_time": 180 }, "selection_strategy": "campaign_thumbnail", "scoring_priorities": [ "composition", "brand_fit" ] } } } } } }, "responses": { "202": { "description": "Find best thumbnails job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindBestThumbnailsJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "find-best-thumbnails", "status": "pending", "units_consumed": 0, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "max_thumbnails": 3, "update_asset_thumbnail": true, "output_steering": { "scope": { "start_time": 30, "end_time": 180 }, "selection_strategy": "campaign_thumbnail", "scoring_priorities": [ "composition", "brand_fit" ] } } } } } } }, "401": { "description": "Missing Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment (accept the Robots beta terms in the Mux Dashboard to enable access), or a free-plan limit has prevented job creation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A job with the same workflow and parameters is already pending or processing for this environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Asset not found, not a video asset, missing public or signed playback ID, or scope does not contain a whole-millisecond interval within the asset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v0/jobs/find-best-thumbnails/{JOB_ID}": { "get": { "operationId": "get-find-best-thumbnails-job", "summary": "Get a 'find-best-thumbnails' job", "description": "Retrieves the current status and results of a 'find-best-thumbnails' job. Jobs are automatically deleted after 30 days.", "tags": [ "Find Best Thumbnails" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "JOB_ID", "in": "path" } ], "responses": { "200": { "description": "Find best thumbnails job state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindBestThumbnailsJobResponse" } } } }, "401": { "description": "Missing Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment. Accept the Robots beta terms in the Mux Dashboard to enable access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No job exists for the supplied id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v0/jobs/find-key-moments": { "post": { "operationId": "create-find-key-moments-job", "summary": "Create a 'find-key-moments' job", "description": "Creates a new job that uses AI to identify key moments in a Mux Video asset. Set use_shots to true to automatically generate or reuse Mux shots and use visual evidence during selection, with transcript evidence incorporated when available; otherwise selection uses transcript evidence and the asset must have a caption track. Audio-only assets always use transcript evidence and require a caption track. Optional output steering can restrict execution to a time scope in seconds and guide selection strategy, title style, audience, topic taxonomy, and scoring priorities without changing the response schema. Scoped results retain absolute timestamps on the original asset timeline.", "tags": [ "Find Key Moments" ], "requestBody": { "description": "Key moments extraction parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFindKeyMomentsJobRequest" }, "example": { "parameters": { "asset_id": "mux_asset_123abc", "max_moments": 10, "target_duration_ms": { "min": 15000, "max": 45000 }, "output_steering": { "scope": { "start_time": 30, "end_time": 180 }, "selection_strategy": "educational_takeaways", "title_style": "punchy", "audience": "Developer advocates", "rubric_priorities": [ "clarity_in_isolation", "soundbite_quality" ] } } } } } }, "responses": { "202": { "description": "Key moments job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindKeyMomentsJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "find-key-moments", "status": "pending", "units_consumed": 0, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "max_moments": 10, "target_duration_ms": { "min": 15000, "max": 45000 }, "output_steering": { "scope": { "start_time": 30, "end_time": 180 }, "selection_strategy": "educational_takeaways", "title_style": "punchy", "audience": "Developer advocates", "rubric_priorities": [ "clarity_in_isolation", "soundbite_quality" ] } } } } } } }, "401": { "description": "Missing Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment (accept the Robots beta terms in the Mux Dashboard to enable access), or a free-plan limit has prevented job creation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A job with the same workflow and parameters is already pending or processing for this environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Asset not found, missing required media evidence, or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v0/jobs/find-key-moments/{JOB_ID}": { "get": { "operationId": "get-find-key-moments-job", "summary": "Get a 'find-key-moments' job", "description": "Retrieves the current status and results of a 'find-key-moments' job. Jobs are automatically deleted after 30 days.", "tags": [ "Find Key Moments" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "JOB_ID", "in": "path" } ], "responses": { "200": { "description": "Current status for the requested job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindKeyMomentsJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "find-key-moments", "status": "completed", "units_consumed": 1, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "max_moments": 10, "target_duration_ms": { "min": 15000, "max": 45000 }, "output_steering": { "scope": { "start_time": 30, "end_time": 180 }, "selection_strategy": "educational_takeaways", "title_style": "punchy", "audience": "Developer advocates", "rubric_priorities": [ "clarity_in_isolation", "soundbite_quality" ] } }, "outputs": { "moments": [ { "start_ms": 15000, "end_ms": 45000, "cues": [ { "start_ms": 15000, "end_ms": 20000, "text": "This is the moment everything changed." }, { "start_ms": 20000, "end_ms": 30000, "text": "We realized the entire approach was wrong." } ], "overall_score": 0.92, "title": "The Pivotal Realization", "quotable_segment": { "start_ms": 20000, "text": "We realized the entire approach was wrong." }, "audible_narrative": "The speaker describes the turning point that reshaped the project direction.", "notable_audible_concepts": [ "pivotal realization moment", "project direction change" ], "visual_narrative": "The speaker gestures emphatically at a whiteboard diagram while the camera zooms in.", "notable_visual_concepts": [ { "concept": "whiteboard diagram emphasis", "score": 0.88, "rationale": "The diagram directly illustrates the pivotal realization being described." }, { "concept": "speaker emphatic gestures", "score": 0.75, "rationale": "Body language reinforces the emotional weight of the turning point." } ] } ] } } } } } }, "401": { "description": "Missing Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment. Accept the Robots beta terms in the Mux Dashboard to enable access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No job exists for the supplied id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v0/jobs/find-scenes": { "post": { "operationId": "create-find-scenes-job", "summary": "Create a 'find-scenes' job", "description": "Creates a new job that segments a Mux video asset into ordered scenes using storyboard-backed generated shots for shot-level visual evidence, combined with transcript cues when available. If the asset has no generated shots, the job generates them on demand and waits for completion — they do not need to exist beforehand. Optional output steering can restrict execution to a time scope in seconds and guide segmentation strategy, title style, narration detail, audience, brand terms, and topic taxonomy without changing the response schema. Scoped results retain absolute timestamps on the original asset timeline.", "tags": [ "Find Scenes" ], "requestBody": { "description": "Find scenes parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFindScenesJobRequest" }, "example": { "parameters": { "asset_id": "mux_asset_123abc", "language_code": "en", "min_scenes": 4, "min_scene_duration_ms": 15000, "output_steering": { "scope": { "start_time": 30, "end_time": 180 }, "segmentation_strategy": "editorial_beats", "title_style": "descriptive", "narration_detail": "balanced" } } } } } }, "responses": { "202": { "description": "Find scenes job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindScenesJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "find-scenes", "status": "pending", "units_consumed": 0, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "language_code": "en", "min_scenes": 4, "min_scene_duration_ms": 15000, "output_steering": { "scope": { "start_time": 30, "end_time": 180 }, "segmentation_strategy": "editorial_beats", "title_style": "descriptive", "narration_detail": "balanced" } } } } } } }, "401": { "description": "Missing Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment (accept the Robots beta terms in the Mux Dashboard to enable access), or a free-plan limit has prevented job creation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A job with the same workflow and parameters is already pending or processing for this environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Asset not found, not a video asset, or missing public or signed playback ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v0/jobs/find-scenes/{JOB_ID}": { "get": { "operationId": "get-find-scenes-job", "summary": "Get a 'find-scenes' job", "description": "Retrieves the current status and results of a 'find-scenes' job. Jobs are automatically deleted after 30 days.", "tags": [ "Find Scenes" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "JOB_ID", "in": "path" } ], "responses": { "200": { "description": "Current status for the requested job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindScenesJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "find-scenes", "status": "completed", "units_consumed": 1, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "language_code": "en", "min_scenes": 4, "min_scene_duration_ms": 15000, "output_steering": { "scope": { "start_time": 30, "end_time": 180 }, "segmentation_strategy": "editorial_beats", "title_style": "descriptive", "narration_detail": "balanced" } }, "outputs": { "scenes": [ { "start_ms": 0, "end_ms": 15000, "title": "Opening Remarks", "cues": [ { "start_ms": 500, "end_ms": 5000, "text": "Welcome everyone to today's session." } ], "audible_narrative": "The host introduces the topic and welcomes the audience.", "notable_audible_concepts": [ "session introduction overview", "welcome and context" ], "visual_narrative": "A speaker stands at a podium in front of a large screen.", "shot_count": 2 } ] } } } } } }, "401": { "description": "Missing Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment. Accept the Robots beta terms in the Mux Dashboard to enable access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No job exists for the supplied id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v0/jobs/generate-chapters": { "post": { "operationId": "create-generate-chapters-job", "summary": "Create a 'generate-chapters' job", "description": "Creates a new job that uses AI to generate chapters for a Mux Video asset. Optional output steering can guide chapter style, granularity, audience, and brand terms without changing the response schema.", "tags": [ "Generate Chapters" ], "requestBody": { "description": "Chapters parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGenerateChaptersJobRequest" }, "example": { "parameters": { "asset_id": "mux_asset_123abc", "update_asset_chapters": true, "output_steering": { "chapter_style": "descriptive", "chapter_granularity": "balanced", "audience": "Developers" } } } } } }, "responses": { "202": { "description": "Chapters job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateChaptersJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "generate-chapters", "status": "pending", "units_consumed": 0, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "update_asset_chapters": true, "output_steering": { "chapter_style": "descriptive", "chapter_granularity": "balanced", "audience": "Developers" } } } } } } }, "401": { "description": "Missing Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment (accept the Robots beta terms in the Mux Dashboard to enable access), or a free-plan limit has prevented job creation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A job with the same workflow and parameters is already pending or processing for this environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Asset not found, missing public or signed playback ID, or no transcript", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v0/jobs/generate-chapters/{JOB_ID}": { "get": { "operationId": "get-generate-chapters-job", "summary": "Get a 'generate-chapters' job", "description": "Retrieves the current status and results of a 'generate-chapters' job. Jobs are automatically deleted after 30 days.", "tags": [ "Generate Chapters" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "JOB_ID", "in": "path" } ], "responses": { "200": { "description": "Current status for the requested job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateChaptersJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "generate-chapters", "status": "completed", "units_consumed": 1, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "update_asset_chapters": true, "output_steering": { "chapter_style": "descriptive", "chapter_granularity": "balanced", "audience": "Developers" } }, "outputs": { "asset_update": { "status": "created", "track_id": "track_chapters_abc123" }, "chapters": [ { "start_time": 0, "title": "Introduction" }, { "start_time": 45, "title": "Setting Up the Workspace" }, { "start_time": 180, "title": "Core Implementation" }, { "start_time": 420, "title": "Testing and Debugging" }, { "start_time": 600, "title": "Wrap-Up and Next Steps" } ] } } } } } }, "401": { "description": "Missing Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment. Accept the Robots beta terms in the Mux Dashboard to enable access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No job exists for the supplied id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v0/jobs/generate-engagement-insights": { "post": { "operationId": "create-generate-engagement-insights-job", "summary": "Create a 'generate-engagement-insights' job", "description": "Creates a new job that uses AI to analyze viewer engagement patterns and generate insights for a Mux Video asset.", "tags": [ "Generate Engagement Insights" ], "requestBody": { "description": "Engagement insights parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGenerateEngagementInsightsJobRequest" }, "example": { "parameters": { "asset_id": "mux_asset_123abc" } } } } }, "responses": { "202": { "description": "Engagement insights job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateEngagementInsightsJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "generate-engagement-insights", "status": "pending", "units_consumed": 0, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc" } } } } } }, "401": { "description": "Missing Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment (accept the Robots beta terms in the Mux Dashboard to enable access), or a free-plan limit has prevented job creation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A job with the same workflow and parameters is already pending or processing for this environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Asset not found or missing public or signed playback ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v0/jobs/generate-engagement-insights/{JOB_ID}": { "get": { "operationId": "get-generate-engagement-insights-job", "summary": "Get a 'generate-engagement-insights' job", "description": "Retrieves the current status and results of a 'generate-engagement-insights' job. Jobs are automatically deleted after 30 days.", "tags": [ "Generate Engagement Insights" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "JOB_ID", "in": "path" } ], "responses": { "200": { "description": "Current status for the requested job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateEngagementInsightsJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "generate-engagement-insights", "status": "completed", "units_consumed": 1, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc" }, "outputs": { "moment_insights": [ { "start_ms": 30000, "end_ms": 60000, "engagement_score": 0.89, "insight": "Viewers are highly engaged during the product demo, with minimal drop-off." } ], "overall_insight": { "summary": "Engagement peaks during hands-on demonstrations and drops during introductory segments.", "trends": [ "Product demos drive the highest retention", "Viewers skip past the first 15 seconds of intro" ] } } } } } } }, "401": { "description": "Missing Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment. Accept the Robots beta terms in the Mux Dashboard to enable access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No job exists for the supplied id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v0/jobs/generate-premium-captions": { "post": { "operationId": "create-generate-premium-captions-job", "summary": "Create a 'generate-premium-captions' job", "description": "Creates a new job that generates high-quality captions for a Mux Video asset and uploads the resulting VTT as a text track.", "tags": [ "Generate Premium Captions" ], "requestBody": { "description": "Caption generation parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGeneratePremiumCaptionsJobRequest" }, "example": { "parameters": { "asset_id": "mux_asset_123abc", "language_code": "en", "replace_existing_tracks": "fail", "include_speakers": false, "include_words": false, "upload_to_mux": true, "phrases": [ "Mux", "API" ] } } } } }, "responses": { "202": { "description": "Caption generation job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneratePremiumCaptionsJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "generate-premium-captions", "status": "pending", "units_consumed": 0, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "language_code": "en", "replace_existing_tracks": "fail", "include_speakers": false, "include_words": false, "upload_to_mux": true, "phrases": [ "Mux", "API" ] } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment (accept the Robots beta terms in the Mux Dashboard to enable access), or a free-plan limit has prevented job creation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A job with the same workflow and parameters is already pending or processing for this environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Asset not found, missing public or signed playback ID, or a text track for the requested language already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v0/jobs/generate-premium-captions/{JOB_ID}": { "get": { "operationId": "get-generate-premium-captions-job", "summary": "Get a 'generate-premium-captions' job", "description": "Retrieves the current status and results of a 'generate-premium-captions' job. Jobs are automatically deleted after 30 days.", "tags": [ "Generate Premium Captions" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "JOB_ID", "in": "path" } ], "responses": { "200": { "description": "Current status for the requested job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneratePremiumCaptionsJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "generate-premium-captions", "status": "completed", "units_consumed": 1, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "language_code": "en", "replace_existing_tracks": "fail", "include_speakers": false, "include_words": false, "upload_to_mux": true, "phrases": [ "Mux", "API" ] }, "outputs": { "track_id": "track_en_abc123", "language_code": "en", "detected_language": "en", "auto_language_confidence": 0.98, "temporary_srt_url": "https://storage.example.com/captions/en/abc123.srt?token=abc" } } } } } }, "401": { "description": "Missing Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment. Accept the Robots beta terms in the Mux Dashboard to enable access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No job exists for the supplied id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v0/jobs/moderate": { "post": { "operationId": "create-moderate-job", "summary": "Create a 'moderate' job", "description": "Creates a new job that uses AI to analyze a Mux Video asset for inappropriate content. Optional output steering can restrict execution to a time scope in seconds.", "tags": [ "Moderate" ], "requestBody": { "description": "Moderation parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateModerateJobRequest" }, "example": { "parameters": { "asset_id": "mux_asset_123abc", "thresholds": { "sexual": 0.7, "violence": 0.8 }, "output_steering": { "scope": { "start_time": 30, "end_time": 180 } }, "on_flagged": { "action": "delete_playback_ids" } } } } } }, "responses": { "202": { "description": "Moderation job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModerateJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "moderate", "status": "pending", "units_consumed": 0, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "thresholds": { "sexual": 0.7, "violence": 0.8 }, "output_steering": { "scope": { "start_time": 30, "end_time": 180 } }, "on_flagged": { "action": "delete_playback_ids" } } } } } } }, "401": { "description": "Missing Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment (accept the Robots beta terms in the Mux Dashboard to enable access), or a free-plan limit has prevented job creation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A job with the same workflow and parameters is already pending or processing for this environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Asset not found or missing public or signed playback ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v0/jobs/moderate/{JOB_ID}": { "get": { "operationId": "get-moderate-job", "summary": "Get a 'moderate' job", "description": "Retrieves the current status and results of a 'moderate' job. Jobs are automatically deleted after 30 days.", "tags": [ "Moderate" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "JOB_ID", "in": "path" } ], "responses": { "200": { "description": "Current status for the requested job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModerateJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "moderate", "status": "completed", "units_consumed": 1, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "thresholds": { "sexual": 0.7, "violence": 0.8 }, "output_steering": { "scope": { "start_time": 30, "end_time": 180 } }, "on_flagged": { "action": "delete_playback_ids" } }, "outputs": { "thumbnail_scores": [ { "time": 0, "sexual": 0.01, "violence": 0.02 }, { "time": 30, "sexual": 0.03, "violence": 0.15 }, { "time": 60, "sexual": 0.02, "violence": 0.05 } ], "max_scores": { "sexual": 0.03, "violence": 0.15 }, "exceeds_threshold": false } } } } } }, "401": { "description": "Missing Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment. Accept the Robots beta terms in the Mux Dashboard to enable access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No job exists for the supplied id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v0/jobs/summarize": { "post": { "operationId": "create-summarize-job", "summary": "Create a 'summarize' job", "description": "Creates a new job that uses AI to generate a title, description, and tags for a Mux Video asset. Optional output steering can restrict execution to a time scope in seconds and guide summary style, audience, brand terms, and tag taxonomy without changing the response schema.", "tags": [ "Summarize" ], "requestBody": { "description": "Summarization parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSummarizeJobRequest" }, "example": { "parameters": { "asset_id": "mux_asset_123abc", "tone": "neutral", "tag_count": 10, "output_steering": { "scope": { "start_time": 30, "end_time": 180 }, "summary_style": "concise", "audience": "Product marketers", "brand_terms": [ "Mux", "Robots" ] } } } } } }, "responses": { "202": { "description": "Summarize job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummarizeJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "summarize", "status": "pending", "units_consumed": 0, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "tone": "neutral", "tag_count": 10, "output_steering": { "scope": { "start_time": 30, "end_time": 180 }, "summary_style": "concise", "audience": "Product marketers", "brand_terms": [ "Mux", "Robots" ] } } } } } } }, "401": { "description": "Missing Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment (accept the Robots beta terms in the Mux Dashboard to enable access), or a free-plan limit has prevented job creation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A job with the same workflow and parameters is already pending or processing for this environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Asset not found or missing public or signed playback ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v0/jobs/summarize/{JOB_ID}": { "get": { "operationId": "get-summarize-job", "summary": "Get a 'summarize' job", "description": "Retrieves the current status and results of a 'summarize' job. Jobs are automatically deleted after 30 days.", "tags": [ "Summarize" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "JOB_ID", "in": "path" } ], "responses": { "200": { "description": "Current status for the requested job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummarizeJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "summarize", "status": "completed", "units_consumed": 1, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "tone": "neutral", "tag_count": 10, "output_steering": { "scope": { "start_time": 30, "end_time": 180 }, "summary_style": "concise", "audience": "Product marketers", "brand_terms": [ "Mux", "Robots" ] } }, "outputs": { "title": "How to Build a Sustainable Garden in Your Backyard", "description": "This video walks through the step-by-step process of creating a sustainable backyard garden, covering soil preparation, plant selection, and organic pest control methods.", "tags": [ "gardening", "sustainability", "backyard", "organic", "soil preparation", "composting", "pest control", "beginner", "how-to", "plants" ] } } } } } }, "401": { "description": "Missing Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment. Accept the Robots beta terms in the Mux Dashboard to enable access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No job exists for the supplied id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v0/jobs/translate-audio": { "post": { "operationId": "create-translate-audio-job", "summary": "Create a 'translate-audio' job", "description": "Creates a new job that translates the audio track of a Mux Video asset to another language.", "tags": [ "Translate Audio" ], "requestBody": { "description": "Audio translation parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTranslateAudioJobRequest" }, "example": { "parameters": { "asset_id": "mux_asset_123abc", "to_language_code": "es", "upload_to_mux": true, "replace_existing_tracks": "fail" } } } } }, "responses": { "202": { "description": "Audio translation job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslateAudioJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "translate-audio", "status": "pending", "units_consumed": 0, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "to_language_code": "es", "upload_to_mux": true, "replace_existing_tracks": "fail" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment (accept the Robots beta terms in the Mux Dashboard to enable access), or a free-plan limit has prevented job creation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A job with the same workflow and parameters is already pending or processing for this environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Asset not found, missing public or signed playback ID, has no audio track, or an audio track blocks the new one under replace_existing_tracks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v0/jobs/translate-audio/{JOB_ID}": { "get": { "operationId": "get-translate-audio-job", "summary": "Get a 'translate-audio' job", "description": "Retrieves the current status and results of a 'translate-audio' job. Jobs are automatically deleted after 30 days.", "tags": [ "Translate Audio" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "JOB_ID", "in": "path" } ], "responses": { "200": { "description": "Current status for the requested job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslateAudioJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "translate-audio", "status": "completed", "units_consumed": 1, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "to_language_code": "es", "upload_to_mux": true, "replace_existing_tracks": "fail" }, "outputs": { "uploaded_track_id": "track_es_abc123", "temporary_audio_url": "https://storage.example.com/dubs/es/audio.m4a?token=abc123" } } } } } }, "401": { "description": "Missing Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment. Accept the Robots beta terms in the Mux Dashboard to enable access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No job exists for the supplied id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v0/jobs/translate-captions": { "post": { "operationId": "create-translate-captions-job", "summary": "Create a 'translate-captions' job", "description": "Creates a new job that translates captions on a Mux Video asset from one language to another.", "tags": [ "Translate Captions" ], "requestBody": { "description": "Caption translation parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTranslateCaptionsJobRequest" }, "example": { "parameters": { "asset_id": "mux_asset_123abc", "track_id": "track_en_abc123", "to_language_code": "es", "upload_to_mux": true, "never_translate": [ "Mux" ], "replace_existing_tracks": "fail" } } } } }, "responses": { "202": { "description": "Caption translation job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslateCaptionsJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "translate-captions", "status": "pending", "units_consumed": 0, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "track_id": "track_en_abc123", "to_language_code": "es", "upload_to_mux": true, "never_translate": [ "Mux" ], "replace_existing_tracks": "fail" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment (accept the Robots beta terms in the Mux Dashboard to enable access), or a free-plan limit has prevented job creation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A job with the same workflow and parameters is already pending or processing for this environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Asset not found, missing public or signed playback ID, no ready text track matching the provided track ID, or a text track blocks the new one under replace_existing_tracks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v0/jobs/translate-captions/{JOB_ID}": { "get": { "operationId": "get-translate-captions-job", "summary": "Get a 'translate-captions' job", "description": "Retrieves the current status and results of a 'translate-captions' job. Jobs are automatically deleted after 30 days.", "tags": [ "Translate Captions" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "JOB_ID", "in": "path" } ], "responses": { "200": { "description": "Current status for the requested job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslateCaptionsJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "translate-captions", "status": "completed", "units_consumed": 1, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "track_id": "track_en_abc123", "to_language_code": "es", "upload_to_mux": true, "never_translate": [ "Mux" ], "replace_existing_tracks": "fail" }, "outputs": { "uploaded_track_id": "track_es_abc123", "temporary_vtt_url": "https://storage.example.com/translations/es/captions.vtt?token=abc123", "never_translate_terms_preserved": true } } } } } }, "401": { "description": "Missing Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Robots is not enabled for this environment. Accept the Robots beta terms in the Mux Dashboard to enable access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No job exists for the supplied id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } } }, "components": { "securitySchemes": { "accessToken": { "description": "The Mux Video API uses an Access Token and Secret Key for authentication. If you haven't already, [generate a new Access Token](https://dashboard.mux.com/settings/access-tokens) in the Access Token settings of your Mux account dashboard.\n\nOnce you have an Access Token ID and Secret, you can then simply include those as the username (id) and password (secret) in the same way you use traditional basic auth.\n", "scheme": "basic", "type": "http" }, "authorizationToken": { "description": "OAuth authorization token, used as a Bearer Auth header\n", "scheme": "bearer", "type": "http" } }, "schemas": { "CreateTranscriptionVocabularyRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "The user-supplied name of the Transcription Vocabulary." }, "phrases": { "type": "array", "items": { "$ref": "#/components/schemas/TranscriptionVocabularyPhrase" }, "maxItems": 1000, "description": "Phrases, individual words, or proper names to include in the Transcription Vocabulary. When the Transcription Vocabulary is attached to a live stream's `generated_subtitles`, the probability of successful speech recognition for these words or phrases is boosted." }, "passthrough": { "type": "string", "description": "Arbitrary user-supplied metadata set for the Transcription Vocabulary. Max 255 characters." } }, "required": [ "phrases" ] }, "UpdateTranscriptionVocabularyRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "The user-supplied name of the Transcription Vocabulary." }, "phrases": { "type": "array", "items": { "$ref": "#/components/schemas/TranscriptionVocabularyPhrase" }, "maxItems": 1000, "description": "Phrases, individual words, or proper names to include in the Transcription Vocabulary. When the Transcription Vocabulary is attached to a live stream's `generated_subtitles`, the probability of successful speech recognition for these words or phrases is boosted." }, "passthrough": { "type": "string", "description": "Arbitrary user-supplied metadata set for the Transcription Vocabulary. Max 255 characters." } }, "required": [ "phrases" ] }, "TranscriptionVocabularyPhrase": { "type": "string", "description": "A phrase or word belonging to a Transcription Vocabulary.", "minLength": 1, "maxLength": 32 }, "TranscriptionVocabulary": { "type": "object", "required": [ "id", "updated_at", "created_at" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the Transcription Vocabulary" }, "name": { "type": "string", "description": "The user-supplied name of the Transcription Vocabulary." }, "phrases": { "type": "array", "items": { "$ref": "#/components/schemas/TranscriptionVocabularyPhrase" }, "maxItems": 1000, "description": "Phrases, individual words, or proper names to include in the Transcription Vocabulary. When the Transcription Vocabulary is attached to a live stream's `generated_subtitles` configuration, the probability of successful speech recognition for these words or phrases is boosted." }, "passthrough": { "type": "string", "description": "Arbitrary user-supplied metadata set for the Transcription Vocabulary. Max 255 characters." }, "created_at": { "type": "string", "format": "int64", "description": "Time the Transcription Vocabulary was created, defined as a Unix timestamp (seconds since epoch)." }, "updated_at": { "type": "string", "format": "int64", "description": "Time the Transcription Vocabulary was updated, defined as a Unix timestamp (seconds since epoch)." } } }, "TranscriptionVocabularyResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/TranscriptionVocabulary" } } }, "ListTranscriptionVocabulariesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TranscriptionVocabulary" } } } }, "AssetResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Asset" } } }, "AssetMetadata": { "type": "object", "description": "Customer provided metadata about this asset.\n\nNote: This metadata may be publicly available via the video player. Do not include PII or sensitive information.\n", "properties": { "title": { "type": "string", "maxLength": 512, "description": "The asset title. Max 512 code points." }, "creator_id": { "type": "string", "maxLength": 128, "description": "This is an identifier you provide to keep track of the creator of the asset. Max 128 code points." }, "external_id": { "type": "string", "maxLength": 128, "description": "This is an identifier you provide to link the asset to your own data. Max 128 code points." } } }, "AssetProgress": { "type": "object", "description": "Detailed state information about the asset ingest process.", "properties": { "state": { "type": "string", "enum": [ "ingesting", "transcoding", "completed", "live", "errored" ], "description": "The detailed state of the asset ingest process. This field is useful for relaying more granular processing information to end users when a [non-standard input is encountered](https://www.mux.com/docs/guides/minimize-processing-time#non-standard-input).\n\n- `ingesting`: Asset is being ingested (initial processing before or after transcoding). While in this state, the `progress` percentage will be 0.\n- `transcoding`: Asset is undergoing non-standard transcoding.\n- `completed`: Asset processing is complete (`status` is `ready`). While in this state, the `progress` percentage will be 100.\n- `live`: Asset is a live stream currently in progress. While in this state, the `progress` percentage will be -1.\n- `errored`: Asset has encountered an error (`status` is `errored`). While in this state, the `progress` percentage will be -1.\n" }, "progress": { "type": "number", "format": "double", "minimum": -1, "maximum": 100, "description": "Represents the estimated completion percentage. Returns `0 - 100` when in `ingesting`, `transcoding`, or `completed` state, and `-1` when in `live` or `errored` state." } }, "required": [ "state", "progress" ] }, "AssetShots": { "type": "object", "description": "The results of generating shots on the video", "properties": { "status": { "type": "string", "description": "The status of the shot detection process", "enum": [ "pending", "completed", "errored", "skipped", "deleted" ] }, "created_at": { "type": "string", "format": "int64", "description": "Time the shot detection process was created, defined as a Unix timestamp (seconds since epoch)." }, "shots_manifest_url": { "type": "string", "description": "A URL to a JSON manifest describing the shot changes detected in the video along with shot preview images for each shot. This field is only present when `status` is `completed`." }, "errors": { "type": "object", "description": "An object describing any errors encountered during the shot detection process. This field is only present when `status` is `errored`.", "properties": { "type": { "type": "string", "description": "The type of error that occurred" }, "messages": { "type": "array", "description": "A list of error messages describing the errors that occurred in more detail", "items": { "type": "string" } } } } }, "required": [ "status", "created_at" ] }, "AssetOptions": { "type": "object", "properties": { "input": { "type": "array", "title": "AssetOptionsDeprecatedInput", "description": "Deprecated. Use `inputs` instead, which accepts an identical type.", "deprecated": true, "x-stainless-deprecation-message": "Use `inputs` instead.", "x-mux-doc-decorators-hidden-children": "all", "items": { "$ref": "#/components/schemas/InputSettings" } }, "inputs": { "type": "array", "description": "An array of objects that each describe an input file to be used to create the asset. As a shortcut, input can also be a string URL for a file when only one input file is used. See `input[].url` for requirements.", "items": { "$ref": "#/components/schemas/InputSettings" } }, "playback_policy": { "type": "array", "title": "AssetOptionsDeprecatedPlaybackPolicy", "items": { "$ref": "#/components/schemas/PlaybackPolicy" }, "deprecated": true, "x-stainless-deprecation-message": "Use `playback_policies` instead.", "description": "Deprecated. Use `playback_policies` instead, which accepts an identical type.", "x-mux-doc-decorators-hidden-children": "all" }, "playback_policies": { "type": "array", "items": { "$ref": "#/components/schemas/PlaybackPolicy" }, "description": "An array of playback policy names that you want applied to this asset and available through `playback_ids`. Options include:\n\n* `\"public\"` (anyone with the playback URL can stream the asset).\n* `\"signed\"` (an additional access token is required to play the asset).\n\nIf no `playback_policies` are set, the asset will have no playback IDs and will therefore not be playable. For simplicity, a single string name can be used in place of the array in the case of only one playback policy.\n" }, "advanced_playback_policies": { "type": "array", "items": { "$ref": "#/components/schemas/CreatePlaybackIDRequest" }, "description": "An array of playback policy objects that you want applied to this asset and available through `playback_ids`. `advanced_playback_policies` must be used instead of `playback_policies` when creating a DRM playback ID.\n" }, "passthrough": { "type": "string", "description": "You can set this field to anything you want. It will be included in the asset details and related webhooks. If you're looking for more structured metadata, such as `title` or `external_id`, you can use the `meta` object instead. **Max: 255 characters**." }, "mp4_support": { "type": "string", "deprecated": true, "x-stainless-deprecation-message": "See the Static Renditions API (https://www.mux.com/docs/guides/enable-static-mp4-renditions).", "enum": [ "none", "standard", "capped-1080p", "audio-only", "audio-only,capped-1080p" ], "description": "Deprecated. See the [Static Renditions API](https://www.mux.com/docs/guides/enable-static-mp4-renditions) for the updated API.\n\nSpecify what level of support for mp4 playback. You may not enable both `mp4_support` and `static_renditions`.\n\n* The `capped-1080p` option produces a single MP4 file, called `capped-1080p.mp4`, with the video resolution capped at 1080p. This option produces an `audio.m4a` file for an audio-only asset.\n* The `audio-only` option produces a single M4A file, called `audio.m4a` for a video or an audio-only asset. MP4 generation will error when this option is specified for a video-only asset.\n* The `audio-only,capped-1080p` option produces both the `audio.m4a` and `capped-1080p.mp4` files. Only the `capped-1080p.mp4` file is produced for a video-only asset, while only the `audio.m4a` file is produced for an audio-only asset.\n\nThe `standard`(deprecated) option produces up to three MP4 files with different levels of resolution (`high.mp4`, `medium.mp4`, `low.mp4`, or `audio.m4a` for an audio-only asset).\n\nMP4 files are not produced for `none` (default).\n\nIn most cases you should use our default HLS-based streaming playback (`{playback_id}.m3u8`) which can automatically adjust to viewers' connection speeds, but an mp4 can be useful for some legacy devices or downloading for offline playback. See the [Download your videos guide](https://docs.mux.com/guides/enable-static-mp4-renditions) for more information.\n", "x-mux-doc-decorators-deprecated-enum-values": [ "standard" ] }, "normalize_audio": { "type": "boolean", "format": "boolean", "description": "Normalize the audio track loudness level. This parameter is only applicable to on-demand (not live) assets.", "default": false }, "master_access": { "type": "string", "enum": [ "none", "temporary" ], "description": "Specify what level (if any) of support for master access. Master access can be enabled temporarily for your asset to be downloaded. See the [Download your videos guide](https://docs.mux.com/guides/enable-static-mp4-renditions) for more information." }, "test": { "type": "boolean", "format": "boolean", "description": "Marks the asset as a test asset when the value is set to true. A Test asset can help evaluate the Mux Video APIs without incurring any cost. There is no limit on number of test assets created. Test asset are watermarked with the Mux logo, limited to 10 seconds, deleted after 24 hrs." }, "max_resolution_tier": { "type": "string", "enum": [ "1080p", "1440p", "2160p" ], "description": "Max resolution tier can be used to control the maximum `resolution_tier` your asset is encoded, stored, and streamed at. If not set, this defaults to `1080p`." }, "encoding_tier": { "type": "string", "deprecated": true, "x-stainless-deprecation-message": "Use `video_quality` instead.", "enum": [ "smart", "baseline", "premium" ], "description": "This field is deprecated. Please use `video_quality` instead. The encoding tier informs the cost, quality, and available platform features for the asset. The default encoding tier for an account can be set in the Mux Dashboard. [See the video quality guide for more details.](https://docs.mux.com/guides/use-video-quality-levels)" }, "video_quality": { "type": "string", "enum": [ "basic", "plus", "premium" ], "description": "The video quality controls the cost, quality, and available platform features for the asset. The default video quality for an account can be set in the Mux Dashboard. This field replaces the deprecated `encoding_tier` value. [See the video quality guide for more details.](https://docs.mux.com/guides/use-video-quality-levels)" }, "static_renditions": { "type": "array", "items": { "$ref": "#/components/schemas/CreateStaticRenditionRequest" }, "description": "An array of static renditions to create for this asset. You may not enable both `static_renditions` and the deprecated `mp4_support`." }, "meta": { "$ref": "#/components/schemas/AssetMetadata" }, "copy_overlays": { "type": "boolean", "default": true, "description": "If the created asset is a clip, this controls whether overlays are copied from the source asset." }, "directives": { "type": "array", "description": "An array of Mux Robots directives to apply to the asset.", "items": { "$ref": "#/components/schemas/AssetDirective" } }, "generate_shots": { "type": "boolean", "default": false, "description": "Whether to perform shot detection on this asset. Shots are only generated for video assets and will not be generated for audio-only assets." } } }, "UpdateLiveStreamNewAssetSettings": { "type": "object", "description": "Updates the new asset settings to use to generate a new asset for this live stream. Only the `mp4_support`, `master_access`, and `video_quality` settings may be updated.\n", "properties": { "mp4_support": { "type": "string", "deprecated": true, "x-stainless-deprecation-message": "See the Static Renditions API (https://www.mux.com/docs/guides/enable-static-mp4-renditions#during-live-stream-creation).", "enum": [ "none", "standard", "capped-1080p", "audio-only", "audio-only,capped-1080p" ], "description": "Deprecated. See the [Static Renditions API](https://www.mux.com/docs/guides/enable-static-mp4-renditions#during-live-stream-creation) for the updated API.\nSpecify what level of support for mp4 playback should be added to new assets generated from this live stream.\n* The `none` option disables MP4 support for new assets. MP4 files will not be produced for an asset generated from this live stream.\n* The `capped-1080p` option produces a single MP4 file, called `capped-1080p.mp4`, with the video resolution capped at 1080p. This option produces an `audio.m4a` file for an audio-only asset.\n* The `audio-only` option produces a single M4A file, called `audio.m4a` for a video or an audio-only asset. MP4 generation will error when this option is specified for a video-only asset.\n* The `audio-only,capped-1080p` option produces both the `audio.m4a` and `capped-1080p.mp4` files. Only the `capped-1080p.mp4` file is produced for a video-only asset, while only the `audio.m4a` file is produced for an audio-only asset.\n* The `standard`(deprecated) option produces up to three MP4 files with different levels of resolution (`high.mp4`, `medium.mp4`, `low.mp4`, or `audio.m4a` for an audio-only asset).\n", "x-mux-doc-decorators-deprecated-enum-values": [ "standard" ] }, "master_access": { "type": "string", "description": "Add or remove access to the master version of the video.", "enum": [ "temporary", "none" ] }, "video_quality": { "type": "string", "enum": [ "plus", "premium" ], "description": "The video quality controls the cost, quality, and available platform features for the asset. [See the video quality guide for more details.](https://docs.mux.com/guides/use-video-quality-levels)" }, "meta": { "$ref": "#/components/schemas/AssetMetadata" } } }, "CreateAssetRequest": { "allOf": [ { "$ref": "#/components/schemas/AssetOptions" }, { "required": [ "inputs" ] } ] }, "CreateLiveStreamRequest": { "type": "object", "properties": { "playback_policy": { "deprecated": true, "x-stainless-deprecation-message": "Use `playback_policies` instead.", "title": "CreateLiveStreamRequestDeprecatedPlaybackPolicy", "description": "Deprecated. Use `playback_policies` instead, which accepts an identical type.", "x-mux-doc-decorators-hidden-children": "all", "type": "array", "items": { "$ref": "#/components/schemas/PlaybackPolicy" } }, "playback_policies": { "description": "An array of playback policy names that you want applied to this live stream and available through `playback_ids`. Options include:\n\n* `\"public\"` (anyone with the playback URL can stream the live stream).\n* `\"signed\"` (an additional access token is required to play the live stream).\n\nIf no `playback_policies` is set, the live stream will have no playback IDs and will therefore not be playable. For simplicity, a single string name can be used in place of the array in the case of only one playback policy.\n", "type": "array", "items": { "$ref": "#/components/schemas/PlaybackPolicy" } }, "advanced_playback_policies": { "type": "array", "items": { "$ref": "#/components/schemas/CreatePlaybackIDRequest" }, "description": "An array of playback policy objects that you want applied on this live stream and available through `playback_ids`. `advanced_playback_policies` must be used instead of `playback_policies` when creating a DRM playback ID.\n" }, "new_asset_settings": { "$ref": "#/components/schemas/AssetOptions" }, "reconnect_window": { "type": "number", "format": "float", "default": 60, "minimum": 0, "maximum": 1800, "description": "When live streaming software disconnects from Mux, either intentionally or due to a drop in the network, the Reconnect Window is the time in seconds that Mux should wait for the streaming software to reconnect before considering the live stream finished and completing the recorded asset. Defaults to 60 seconds on the API if not specified.\n\nIf not specified directly, Standard Latency streams have a Reconnect Window of 60 seconds; Reduced and Low Latency streams have a default of 0 seconds, or no Reconnect Window. For that reason, we suggest specifying a value other than zero for Reduced and Low Latency streams.\n\nReduced and Low Latency streams with a Reconnect Window greater than zero will insert slate media into the recorded asset while waiting for the streaming software to reconnect or when there are brief interruptions in the live stream media. When using a Reconnect Window setting higher than 60 seconds with a Standard Latency stream, we highly recommend enabling slate with the `use_slate_for_standard_latency` option.\n" }, "use_slate_for_standard_latency": { "type": "boolean", "format": "boolean", "default": false, "description": "By default, Standard Latency live streams do not have slate media inserted while waiting for live streaming software to reconnect to Mux. Setting this to true enables slate insertion on a Standard Latency stream." }, "reconnect_slate_url": { "type": "string", "description": "The URL of the image file that Mux should download and use as slate media during interruptions of the live stream media. This file will be downloaded each time a new recorded asset is created from the live stream. If this is not set, the default slate media will be used." }, "passthrough": { "type": "string" }, "audio_only": { "type": "boolean", "description": "Force the live stream to only process the audio track when the value is set to true. Mux drops the video track if broadcasted." }, "embedded_subtitles": { "type": "array", "items": { "$ref": "#/components/schemas/LiveStreamEmbeddedSubtitleRequest" }, "description": "Describe the embedded closed caption contents of the incoming live stream." }, "generated_subtitles": { "type": "array", "items": { "$ref": "#/components/schemas/LiveStreamGeneratedSubtitleRequest" }, "description": "Configure the incoming live stream to include subtitles created with automatic speech recognition. Each Asset created from a live stream with `generated_subtitles` configured will automatically receive two text tracks. The first of these will have a `text_source` value of `generated_live`, and will be available with `ready` status as soon as the stream is live. The second text track will have a `text_source` value of `generated_live_final` and will contain subtitles with improved accuracy, timing, and formatting. However, `generated_live_final` tracks will not be available in `ready` status until the live stream ends. If an Asset has both `generated_live` and `generated_live_final` tracks that are `ready`, then only the `generated_live_final` track will be included during playback." }, "reduced_latency": { "type": "boolean", "format": "boolean", "deprecated": true, "x-stainless-deprecation-message": "Use `latency_mode` instead.", "x-mux-doc-decorators": [ "hidden" ], "description": "This field is deprecated. Please use `latency_mode` instead. Latency is the time from when the streamer transmits a frame of video to when you see it in the player. Set this if you want lower latency for your live stream. Read more here: https://mux.com/blog/reduced-latency-for-mux-live-streaming-now-available/" }, "low_latency": { "type": "boolean", "format": "boolean", "deprecated": true, "x-stainless-deprecation-message": "Use `latency_mode` instead.", "x-mux-doc-decorators": [ "hidden" ], "description": "This field is deprecated. Please use `latency_mode` instead. Latency is the time from when the streamer transmits a frame of video to when you see it in the player. Setting this option will enable compatibility with the LL-HLS specification for low-latency streaming. This typically has lower latency than Reduced Latency streams, and cannot be combined with Reduced Latency." }, "latency_mode": { "type": "string", "enum": [ "low", "reduced", "standard" ], "description": "Latency is the time from when the streamer transmits a frame of video to when you see it in the player. Set this as an alternative to setting low latency or reduced latency flags." }, "test": { "type": "boolean", "format": "boolean", "description": "Marks the live stream as a test live stream when the value is set to true. A test live stream can help evaluate the Mux Video APIs without incurring any cost. There is no limit on number of test live streams created. Test live streams are watermarked with the Mux logo and limited to 5 minutes. The test live stream is disabled after the stream is active for 5 mins and the recorded asset also deleted after 24 hours." }, "simulcast_targets": { "type": "array", "items": { "$ref": "#/components/schemas/CreateSimulcastTargetRequest" } }, "max_continuous_duration": { "$ref": "#/components/schemas/MaxContinuousDuration" }, "meta": { "$ref": "#/components/schemas/LiveStreamMetadata" } } }, "CreatePlaybackIDRequest": { "type": "object", "properties": { "policy": { "$ref": "#/components/schemas/PlaybackPolicy" }, "drm_configuration_id": { "type": "string", "description": "The DRM configuration used by this playback ID. Must only be set when `policy` is set to `drm`." } } }, "CreatePlaybackIDResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PlaybackID" } } }, "CreateUploadRequest": { "type": "object", "required": [ "cors_origin" ], "properties": { "timeout": { "type": "integer", "format": "int32", "default": 3600, "minimum": 60, "maximum": 604800, "description": "Max time in seconds for the signed upload URL to be valid. If a successful upload has not occurred before the timeout limit, the direct upload is marked `timed_out`" }, "cors_origin": { "type": "string", "description": "If the upload URL will be used in a browser, you must specify the origin in order for the signed URL to have the correct CORS headers." }, "new_asset_settings": { "$ref": "#/components/schemas/AssetOptions" }, "test": { "type": "boolean", "format": "boolean", "description": "Indicates if this is a test Direct Upload, in which case the Asset that gets created will be a `test` Asset." } } }, "GetAssetInputInfoResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InputInfo" } } } }, "GetAssetPlaybackIDResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PlaybackID" } } }, "GetLiveStreamPlaybackIDResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PlaybackID" } } }, "ListAssetsResponse": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "next_cursor": { "type": "string", "description": "If there are more pages of data, this field will contain a string that can be used with the `cursor` querystring parameter to fetch the next page of data.", "nullable": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } } } }, "ListLiveStreamsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LiveStream" } } } }, "ListSigningKeysResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SigningKey" } } } }, "ListUploadsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Upload" } } } }, "LiveStreamResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LiveStream" } } }, "SigningKeyResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SigningKey" } } }, "SigningKeyCreateResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/SigningKey" }, { "required": [ "private_key" ] } ] } } }, "SignalLiveStreamCompleteResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object" } } }, "DisableLiveStreamResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object" } } }, "EnableLiveStreamResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object" } } }, "UpdateAssetRequest": { "type": "object", "properties": { "passthrough": { "type": "string", "description": "You can set this field to anything you want. It will be included in the asset details and related webhooks. If you're looking for more structured metadata, such as `title` or `external_id` , you can use the `meta` object instead. **Max: 255 characters**. In order to clear this value, the field should be included with an empty string value." }, "meta": { "$ref": "#/components/schemas/AssetMetadata" }, "thumbnail_time": { "type": "number", "format": "float", "description": "The media time within the asset used when a thumbnail without an explicit time is requested." } } }, "UpdateAssetMP4SupportRequest": { "type": "object", "deprecated": true, "x-stainless-deprecation-message": "Use the static-renditions endpoint (POST /video/v1/assets/{ASSET_ID}/static-renditions) instead.", "required": [ "mp4_support" ], "properties": { "mp4_support": { "type": "string", "description": "Specify what level of support for mp4 playback.\n\n* The `capped-1080p` option produces a single MP4 file, called `capped-1080p.mp4`, with the video resolution capped at 1080p. This option produces an `audio.m4a` file for an audio-only asset.\n* The `audio-only` option produces a single M4A file, called `audio.m4a` for a video or an audio-only asset. MP4 generation will error when this option is specified for a video-only asset.\n* The `audio-only,capped-1080p` option produces both the `audio.m4a` and `capped-1080p.mp4` files. Only the `capped-1080p.mp4` file is produced for a video-only asset, while only the `audio.m4a` file is produced for an audio-only asset.\n\nThe `standard`(deprecated) option produces up to three MP4 files with different levels of resolution (`high.mp4`, `medium.mp4`, `low.mp4`, or `audio.m4a` for an audio-only asset).\n\n`none` will delete the MP4s from the asset in question.\n", "enum": [ "standard", "none", "capped-1080p", "audio-only", "audio-only,capped-1080p" ], "x-mux-doc-decorators-deprecated-enum-values": [ "standard" ] } } }, "UpdateAssetMasterAccessRequest": { "type": "object", "required": [ "master_access" ], "properties": { "master_access": { "type": "string", "description": "Add or remove access to the master version of the video.", "enum": [ "temporary", "none" ] } } }, "UpdateLiveStreamEmbeddedSubtitlesRequest": { "type": "object", "properties": { "embedded_subtitles": { "type": "array", "items": { "$ref": "#/components/schemas/LiveStreamEmbeddedSubtitleRequest" }, "description": "Describe the embedded closed caption contents of the incoming live stream." } } }, "UpdateLiveStreamGeneratedSubtitlesRequest": { "type": "object", "properties": { "generated_subtitles": { "type": "array", "items": { "$ref": "#/components/schemas/LiveStreamGeneratedSubtitleRequest" }, "description": "Update automated speech recognition subtitle configuration for a live stream. At most one subtitle track is allowed." } }, "x-mux-no-required-properties": true }, "UpdateLiveStreamRequest": { "type": "object", "properties": { "passthrough": { "type": "string", "description": "Arbitrary user-supplied metadata set for the live stream. Max 255 characters. In order to clear this value, the field should be included with an empty-string value." }, "latency_mode": { "type": "string", "enum": [ "low", "reduced", "standard" ], "description": "Latency is the time from when the streamer transmits a frame of video to when you see it in the player. Set this as an alternative to setting low latency or reduced latency flags." }, "reconnect_window": { "type": "number", "format": "float", "default": 60, "minimum": 0, "maximum": 1800, "description": "When live streaming software disconnects from Mux, either intentionally or due to a drop in the network, the Reconnect Window is the time in seconds that Mux should wait for the streaming software to reconnect before considering the live stream finished and completing the recorded asset.\n\nIf not specified directly, Standard Latency streams have a Reconnect Window of 60 seconds; Reduced and Low Latency streams have a default of 0 seconds, or no Reconnect Window. For that reason, we suggest specifying a value other than zero for Reduced and Low Latency streams.\n\nReduced and Low Latency streams with a Reconnect Window greater than zero will insert slate media into the recorded asset while waiting for the streaming software to reconnect or when there are brief interruptions in the live stream media. When using a Reconnect Window setting higher than 60 seconds with a Standard Latency stream, we highly recommend enabling slate with the `use_slate_for_standard_latency` option.\n" }, "use_slate_for_standard_latency": { "type": "boolean", "format": "boolean", "default": false, "description": "By default, Standard Latency live streams do not have slate media inserted while waiting for live streaming software to reconnect to Mux. Setting this to true enables slate insertion on a Standard Latency stream." }, "reconnect_slate_url": { "type": "string", "description": "The URL of the image file that Mux should download and use as slate media during interruptions of the live stream media. This file will be downloaded each time a new recorded asset is created from the live stream. Set this to a blank string to clear the value so that the default slate media will be used." }, "max_continuous_duration": { "$ref": "#/components/schemas/MaxContinuousDuration" }, "new_asset_settings": { "$ref": "#/components/schemas/UpdateLiveStreamNewAssetSettings" }, "meta": { "$ref": "#/components/schemas/LiveStreamMetadata" } } }, "UploadResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Upload" } } }, "CreatePlaybackRestrictionRequest": { "type": "object", "required": [ "referrer", "user_agent" ], "properties": { "referrer": { "$ref": "#/components/schemas/ReferrerDomainRestrictionRequest" }, "user_agent": { "$ref": "#/components/schemas/UserAgentRestrictionRequest" } } }, "PlaybackRestrictionResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PlaybackRestriction" } } }, "ListPlaybackRestrictionsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PlaybackRestriction" } } } }, "UpdateReferrerDomainRestrictionRequest": { "type": "object", "description": "A list of domains allowed to play your videos.", "required": [ "allowed_domains" ], "properties": { "allowed_domains": { "type": "array", "items": { "type": "string" }, "description": "List of domains allowed to play videos. Possible values are\n * `[]` Empty Array indicates deny video playback requests for all domains\n * `[\"*\"]` A Single Wildcard `*` entry means allow video playback requests from any domain\n * `[\"*.example.com\", \"foo.com\"]` A list of up to 10 domains or valid dns-style wildcards\n" }, "allow_no_referrer": { "type": "boolean", "default": false, "description": "A boolean to determine whether to allow or deny HTTP requests without `Referer` HTTP request header. Playback requests coming from non-web/native applications like iOS, Android or smart TVs will not have a `Referer` HTTP header. Set this value to `true` to allow these playback requests." } } }, "UpdateUserAgentRestrictionRequest": { "type": "object", "required": [ "allow_no_user_agent", "allow_high_risk_user_agent" ], "properties": { "allow_no_user_agent": { "type": "boolean", "default": true, "description": "Whether or not to allow views without a `User-Agent` HTTP request header." }, "allow_high_risk_user_agent": { "type": "boolean", "default": true, "description": "Whether or not to allow high risk user agents. The high risk user agents are defined by Mux." } } }, "SimulcastTargetResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SimulcastTarget" } } }, "CreateSimulcastTargetRequest": { "type": "object", "required": [ "url" ], "properties": { "passthrough": { "type": "string", "description": "Arbitrary user-supplied metadata set by you when creating a simulcast target." }, "stream_key": { "type": "string", "description": "Stream Key represents a stream identifier on the third party live streaming service to send the parent live stream to. Only used for RTMP(s) simulcast destinations." }, "url": { "type": "string", "description": "The RTMP(s) or SRT endpoint for a simulcast destination.\n* For RTMP(s) destinations, this should include the application name for the third party live streaming service, for example: `rtmp://live.example.com/app`.\n* For SRT destinations, this should be a fully formed SRT connection string, for example: `srt://srt-live.example.com:1234?streamid={stream_key}&passphrase={srt_passphrase}`.\n\nNote: SRT simulcast targets can only be used when an source is connected over SRT.\n" } } }, "CreateStaticRenditionRequest": { "type": "object", "required": [ "resolution" ], "properties": { "resolution": { "type": "string", "enum": [ "highest", "audio-only", "2160p", "1440p", "1080p", "720p", "540p", "480p", "360p", "270p" ] }, "passthrough": { "type": "string", "description": "Arbitrary user-supplied metadata set for the static rendition. Max 255 characters." } } }, "CreateStaticRenditionResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/StaticRendition" } } }, "UpdateLiveStreamNewAssetSettingsStaticRenditionsRequest": { "type": "object", "required": [ "static_renditions" ], "properties": { "static_renditions": { "type": "array", "items": { "$ref": "#/components/schemas/CreateStaticRenditionRequest" } } } }, "CreateTrackRequest": { "type": "object", "required": [ "url", "type", "language_code" ], "properties": { "url": { "type": "string", "description": "The URL of the file that Mux should download and use.\n* For `audio` tracks, the URL is the location of the audio file for Mux to download, for example an M4A, WAV, or MP3 file. Mux supports most audio file formats and codecs, but for fastest processing, you should [use standard inputs wherever possible](https://docs.mux.com/guides/minimize-processing-time).\n* For `text` tracks, the URL is the location of subtitle/captions file. Mux supports [SubRip Text (SRT)](https://en.wikipedia.org/wiki/SubRip) and [Web Video Text Tracks](https://www.w3.org/TR/webvtt1/) formats for ingesting Subtitles and Closed Captions.\n" }, "type": { "type": "string", "enum": [ "text", "audio" ] }, "text_type": { "type": "string", "enum": [ "subtitles", "chapters" ], "description": "The type of text track. Required when `type` is `text`. Use `subtitles` for subtitles and closed captions, or `chapters` for a chapters track." }, "language_code": { "type": "string", "description": "The language code of this track. The value must be a valid BCP 47 specification compliant value. For example, en for English or en-US for the US version of English." }, "name": { "type": "string", "description": "The name of the track containing a human-readable description. This value must be unique within each group of `text` or `audio` track types. The HLS manifest will associate the `text` or `audio` track with this value. For example, set the value to \"English\" for subtitles text track with `language_code` as en-US. If this parameter is not included, Mux will auto-populate a value based on the `language_code` value." }, "closed_captions": { "type": "boolean", "description": "Indicates the track provides Subtitles for the Deaf or Hard-of-hearing (SDH)." }, "passthrough": { "type": "string", "description": "Arbitrary user-supplied metadata set for the track either when creating the asset or track." } } }, "CreateTrackResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Track" } } }, "GenerateTrackSubtitlesResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Track" } } } }, "UpdateAssetTrackRequest": { "type": "object", "properties": { "language_code": { "type": "string", "description": "The language code of this track. The value must be a valid BCP 47 specification compliant value. For example, en for English or en-US for the US version of English." }, "name": { "type": "string", "description": "The name of the track containing a human-readable description. This value must be unique within each group of `text` or `audio` track types. The HLS manifest will associate the `text` or `audio` track with this value. For example, set the value to \"English\" for subtitles text track with `language_code` as en-US. If this parameter is not included, Mux will auto-populate a value based on the `language_code` value." }, "closed_captions": { "type": "boolean", "description": "Indicates the track provides Subtitles for the Deaf or Hard-of-hearing (SDH)." }, "passthrough": { "type": "string", "description": "Arbitrary user-supplied metadata set for the track either when creating the asset or track." } } }, "UpdateAssetTrackResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Track" } } }, "GenerateTrackSubtitlesRequest": { "type": "object", "required": [ "generated_subtitles" ], "properties": { "generated_subtitles": { "type": "array", "items": { "$ref": "#/components/schemas/AssetGeneratedSubtitleSettings" }, "description": "Generate subtitle tracks using automatic speech recognition with this configuration." } } }, "GetAssetOrLiveStreamIdResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "object", "policy" ], "properties": { "id": { "type": "string", "description": "The Playback ID used to retrieve the corresponding asset or the live stream ID" }, "policy": { "$ref": "#/components/schemas/PlaybackPolicy" }, "object": { "type": "object", "required": [ "id", "type" ], "description": "Describes the Asset or LiveStream object associated with the playback ID.", "properties": { "id": { "type": "string", "description": "The identifier of the object." }, "type": { "type": "string", "enum": [ "asset", "live_stream" ], "description": "Identifies the object type associated with the playback ID." } } } } } } }, "GenerateAssetShotsRequest": { "type": "object", "properties": {} }, "GenerateAssetShotsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AssetShots" } } }, "GetAssetShotsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AssetShots" } } }, "StaticRendition": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "low.mp4", "medium.mp4", "high.mp4", "highest.mp4", "audio.m4a", "capped-1080p.mp4", "2160p.mp4", "1440p.mp4", "1080p.mp4", "720p.mp4", "540p.mp4", "480p.mp4", "360p.mp4", "270p.mp4" ], "description": "Name of the static rendition file" }, "ext": { "type": "string", "description": "Extension of the static rendition file", "enum": [ "mp4", "m4a" ] }, "height": { "type": "integer", "format": "int32", "description": "The height of the static rendition's file in pixels" }, "width": { "type": "integer", "format": "int32", "description": "The width of the static rendition's file in pixels" }, "bitrate": { "type": "integer", "format": "int64", "description": "The bitrate in bits per second" }, "filesize": { "type": "string", "format": "int64", "description": "The file size in bytes" }, "type": { "type": "string", "description": "Indicates the static rendition type of this specific MP4 version of this asset. Only present for static renditions created with the Static Renditions API. Not set for renditions created with the deprecated `mp4_support` option.", "enum": [ "standard", "advanced" ] }, "status": { "type": "string", "description": "Indicates the status of this specific MP4 version of this asset. Only present for static renditions created with the Static Renditions API. Not set for renditions created with the deprecated `mp4_support` option. For `mp4_support` renditions, see the top-level `static_renditions.status` field on the asset instead.\n* `ready` indicates the MP4 has been generated and is ready for download\n* `preparing` indicates the asset has not been ingested or the static rendition is still being generated after an asset is ready\n* `skipped` indicates the static rendition will not be generated because the requested resolution conflicts with the asset attributes after the asset has been ingested\n* `errored` indicates the static rendition cannot be generated. For example, an asset could not be ingested\n", "enum": [ "ready", "preparing", "skipped", "errored" ] }, "resolution_tier": { "type": "string", "description": "Indicates the resolution tier of this specific MP4 version of this asset. Only present for static renditions created with the Static Renditions API. Not set for renditions created with the deprecated `mp4_support` option.", "enum": [ "2160p", "1440p", "1080p", "720p", "audio-only" ] }, "resolution": { "type": "string", "description": "Indicates the resolution of this specific MP4 version of this asset. Only present for static renditions created with the Static Renditions API. Not set for renditions created with the deprecated `mp4_support` option.", "enum": [ "highest", "audio-only", "2160p", "1440p", "1080p", "720p", "540p", "480p", "360p", "270p" ], "x-mux-doc-decorators-hidden-enum-values": [ "2160p", "1440p", "1080p", "720p", "540p", "480p", "360p", "270p" ] }, "id": { "type": "string", "description": "The ID of this static rendition, used in managing this static rendition. Only present for static renditions created with the Static Renditions API. Not set for renditions created with the deprecated `mp4_support` option." }, "passthrough": { "type": "string", "description": "Arbitrary user-supplied metadata set for the static rendition. Max 255 characters." } } }, "Asset": { "type": "object", "required": [ "id", "created_at", "status", "max_resolution_tier", "encoding_tier", "master_access", "progress" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the Asset. Max 255 characters." }, "created_at": { "type": "string", "format": "int64", "description": "Time the Asset was created, defined as a Unix timestamp (seconds since epoch)." }, "status": { "type": "string", "enum": [ "preparing", "ready", "errored" ], "description": "The status of the asset." }, "duration": { "type": "number", "format": "double", "description": "The duration of the asset in seconds (max duration for a single asset is 12 hours)." }, "max_stored_resolution": { "type": "string", "enum": [ "Audio only", "SD", "HD", "FHD", "UHD" ], "description": "This field is deprecated. Please use `resolution_tier` instead. The maximum resolution that has been stored for the asset. The asset may be delivered at lower resolutions depending on the device and bandwidth, however it cannot be delivered at a higher value than is stored.", "deprecated": true, "x-stainless-deprecation-message": "Use `resolution_tier` instead." }, "resolution_tier": { "type": "string", "enum": [ "audio-only", "720p", "1080p", "1440p", "2160p" ], "description": "The resolution tier that the asset was ingested at, affecting billing for ingest & storage. This field also represents the highest resolution tier that the content can be delivered at, however the actual resolution may be lower depending on the device, bandwidth, and exact resolution of the uploaded asset." }, "max_resolution_tier": { "type": "string", "enum": [ "1080p", "1440p", "2160p" ], "description": "Max resolution tier can be used to control the maximum `resolution_tier` your asset is encoded, stored, and streamed at. If not set, this defaults to `1080p`." }, "encoding_tier": { "type": "string", "deprecated": true, "x-stainless-deprecation-message": "Use `video_quality` instead.", "enum": [ "smart", "baseline", "premium" ], "description": "This field is deprecated. Please use `video_quality` instead. The encoding tier informs the cost, quality, and available platform features for the asset. The default encoding tier for an account can be set in the Mux Dashboard. [See the video quality guide for more details.](https://docs.mux.com/guides/use-video-quality-levels)" }, "video_quality": { "type": "string", "enum": [ "basic", "plus", "premium" ], "description": "The video quality controls the cost, quality, and available platform features for the asset. The default video quality for an account can be set in the Mux Dashboard. This field replaces the deprecated `encoding_tier` value. [See the video quality guide for more details.](https://docs.mux.com/guides/use-video-quality-levels)" }, "max_stored_frame_rate": { "type": "number", "format": "double", "description": "The maximum frame rate that has been stored for the asset. The asset may be delivered at lower frame rates depending on the device and bandwidth, however it cannot be delivered at a higher value than is stored. This field may return -1 if the frame rate of the input cannot be reliably determined." }, "aspect_ratio": { "type": "string", "description": "The aspect ratio of the asset in the form of `width:height`, for example `16:9`." }, "playback_ids": { "type": "array", "description": "An array of Playback ID objects. Use these to create HLS playback URLs. See [Play your videos](https://docs.mux.com/guides/play-your-videos) for more details.", "items": { "$ref": "#/components/schemas/PlaybackID" } }, "tracks": { "type": "array", "description": "The individual media tracks that make up an asset.", "items": { "$ref": "#/components/schemas/Track" } }, "errors": { "type": "object", "description": "Object that describes any errors that happened when processing this asset.", "properties": { "type": { "type": "string", "description": "The type of error that occurred for this asset." }, "messages": { "type": "array", "description": "Error messages with more details.", "items": { "type": "string" } } } }, "upload_id": { "type": "string", "description": "Unique identifier for the Direct Upload. This is an optional parameter added when the asset is created from a direct upload." }, "is_live": { "type": "boolean", "format": "boolean", "description": "Indicates whether the live stream that created this asset is currently `active` and not in `idle` state. This is an optional parameter added when the asset is created from a live stream." }, "passthrough": { "type": "string", "description": "You can set this field to anything you want. It will be included in the asset details and related webhooks. If you're looking for more structured metadata, such as `title` or `external_id` , you can use the `meta` object instead. **Max: 255 characters**." }, "live_stream_id": { "type": "string", "description": "Unique identifier for the live stream. This is an optional parameter added when the asset is created from a live stream." }, "master": { "type": "object", "description": "An object containing the current status of Master Access and the link to the Master MP4 file when ready. This object does not exist if `master_access` is set to `none` and when the temporary URL expires.", "properties": { "status": { "enum": [ "ready", "preparing", "errored" ], "type": "string" }, "url": { "type": "string", "description": "The temporary URL to the master version of the video, as an MP4 file. This URL will expire after 24 hours." } } }, "master_access": { "type": "string", "enum": [ "temporary", "none" ], "default": "none" }, "mp4_support": { "type": "string", "deprecated": true, "x-stainless-deprecation-message": "Use the Static Renditions API (https://www.mux.com/docs/guides/enable-static-mp4-renditions) instead. This field remains available only to support migration from `mp4_support` to static renditions.", "description": "Deprecated. The level of MP4 support requested through the legacy `mp4_support` option, or `none` if it was not used. Renditions created this way appear in the `static_renditions` object alongside renditions created with the [Static Renditions API](https://www.mux.com/docs/guides/enable-static-mp4-renditions); see that object for how the two differ. An asset cannot use both mechanisms at the same time.\n", "default": "none", "enum": [ "standard", "none", "capped-1080p", "audio-only", "audio-only,capped-1080p" ], "x-mux-doc-decorators-deprecated-enum-values": [ "standard" ] }, "source_asset_id": { "type": "string", "description": "Asset Identifier of the video used as the source for creating the clip." }, "normalize_audio": { "type": "boolean", "default": false, "description": "Normalize the audio track loudness level. This parameter is only applicable to on-demand (not live) assets." }, "static_renditions": { "type": "object", "description": "An object containing the current status of any static renditions (MP4s) for this asset. The object does not exist if no static renditions have been requested. See [Download your videos](https://docs.mux.com/guides/enable-static-mp4-renditions) for more information.\n\nThis object is populated by both the [Static Renditions API](https://www.mux.com/docs/guides/enable-static-mp4-renditions) and the deprecated `mp4_support` option, and the two report status differently:\n\n* Renditions created with the Static Renditions API each carry their own `id`, `status`, `type`, `resolution`, and `resolution_tier` in `files`. Track progress per rendition using `files[].status`.\n* Renditions created with the deprecated `mp4_support` option share a single aggregate `status` on this object, and their `files` entries do not include the per-rendition fields above.\n", "properties": { "status": { "type": "string", "default": "disabled", "description": "Indicates the aggregate status of MP4 renditions created with the deprecated `mp4_support` option. This field is only meaningful when `mp4_support` is enabled on the asset. For renditions created with the Static Renditions API, use the per-rendition `files[].status` field instead.\n", "enum": [ "ready", "preparing", "disabled", "errored" ] }, "files": { "type": "array", "description": "Array of file objects.", "items": { "$ref": "#/components/schemas/StaticRendition" } } } }, "recording_times": { "type": "array", "description": "An array of individual live stream recording sessions. A recording session is created on each encoder connection during the live stream. Additionally any time slate media is inserted during brief interruptions in the live stream media or times when the live streaming software disconnects, a recording session representing the slate media will be added with a \"slate\" type.", "items": { "type": "object", "properties": { "started_at": { "type": "string", "format": "date-time", "description": "The time at which the recording for the live stream started. The time value is Unix epoch time represented in ISO 8601 format." }, "duration": { "type": "number", "format": "double", "description": "The duration of the live stream recorded. The time value is in seconds." }, "type": { "type": "string", "enum": [ "content", "slate" ], "description": "The type of media represented by the recording session, either `content` for normal stream content or `slate` for slate media inserted during stream interruptions." } } } }, "non_standard_input_reasons": { "type": "object", "description": "An object containing one or more reasons the input file is non-standard. See [the guide on minimizing processing time](https://docs.mux.com/guides/minimize-processing-time) for more information on what a standard input is defined as. This object only exists on on-demand assets that have non-standard inputs, so if missing you can assume the input qualifies as standard.", "properties": { "video_codec": { "type": "string", "description": "The video codec used on the input file. For example, the input file encoded with `av1` video codec is non-standard and the value of this parameter is `av1`." }, "audio_codec": { "type": "string", "description": "The audio codec used on the input file. Non-AAC audio codecs are non-standard." }, "video_gop_size": { "type": "string", "enum": [ "high" ], "description": "The video key frame Interval (also called as Group of Picture or GOP) of the input file is `high`. This parameter is present when the gop is greater than 20 seconds." }, "video_frame_rate": { "type": "string", "description": "The video frame rate of the input file. Video with average frames per second (fps) less than 5 or greater than 120 is non-standard. A `-1` frame rate value indicates Mux could not determine the frame rate of the video track." }, "video_resolution": { "type": "string", "description": "The video resolution of the input file. Video resolution higher than 2048 pixels on any one dimension (height or width) is considered non-standard, The resolution value is presented as `width` x `height` in pixels." }, "video_bitrate": { "type": "string", "enum": [ "high" ], "description": "The video bitrate of the input file is `high`. This parameter is present when the average bitrate of any key frame interval (also known as Group of Pictures or GOP) is higher than what's considered standard which typically is 16 Mbps." }, "pixel_aspect_ratio": { "type": "string", "description": "The video pixel aspect ratio of the input file." }, "video_edit_list": { "type": "string", "enum": [ "non-standard" ], "description": "Video Edit List reason indicates that the input file's video track contains a complex Edit Decision List." }, "audio_edit_list": { "type": "string", "enum": [ "non-standard" ], "description": "Audio Edit List reason indicates that the input file's audio track contains a complex Edit Decision List." }, "unexpected_media_file_parameters": { "type": "string", "enum": [ "non-standard" ], "description": "A catch-all reason when the input file in created with non-standard encoding parameters." }, "unsupported_pixel_format": { "type": "string", "description": "The video pixel format, as a string, returned by libav. Considered non-standard if not one of yuv420p or yuvj420p. HEVC inputs additionally permit yuv420p10le." } } }, "test": { "type": "boolean", "format": "boolean", "description": "True means this live stream is a test asset. A test asset can help evaluate the Mux Video APIs without incurring any cost. There is no limit on number of test assets created. Test assets are watermarked with the Mux logo, limited to 10 seconds, and deleted after 24 hrs." }, "ingest_type": { "type": "string", "enum": [ "on_demand_url", "on_demand_direct_upload", "on_demand_clip", "live_rtmp", "live_srt" ], "description": "The type of ingest used to create the asset." }, "meta": { "$ref": "#/components/schemas/AssetMetadata" }, "progress": { "$ref": "#/components/schemas/AssetProgress" }, "directives": { "type": "array", "description": "The Mux Robots directives applied to the asset.", "items": { "$ref": "#/components/schemas/AssetDirective" } }, "generate_shots": { "type": "boolean", "default": false, "description": "Whether to perform shot detection on this asset. Shots are only generated for video assets and will not be generated for audio-only assets." }, "shots": { "$ref": "#/components/schemas/AssetShots" }, "thumbnail_time": { "type": "number", "format": "float", "description": "The media time within the asset used when a thumbnail without an explicit time is requested." } } }, "InputSettings": { "type": "object", "description": "An array of objects that each describe an input file to be used to create the asset. As a shortcut, `input` can also be a string URL for a file when only one input file is used. See `input[].url` for requirements.", "properties": { "url": { "type": "string", "description": "The URL of the file that Mux should download and use.\n* For the main input file, this should be the URL to the muxed file for Mux to download, for example an MP4, MOV, MKV, or TS file. Mux supports most audio/video file formats and codecs, but for fastest processing, you should [use standard inputs wherever possible](https://docs.mux.com/guides/minimize-processing-time).\n* For `audio` tracks, the URL is the location of the audio file for Mux to download, for example an M4A, WAV, or MP3 file. Mux supports most audio file formats and codecs, but for fastest processing, you should [use standard inputs wherever possible](https://docs.mux.com/guides/minimize-processing-time).\n* For `text` tracks, the URL is the location of subtitle/captions file. Mux supports [SubRip Text (SRT)](https://en.wikipedia.org/wiki/SubRip) and [Web Video Text Tracks](https://www.w3.org/TR/webvtt1/) formats for ingesting Subtitles and Closed Captions.\n* For Watermarking or Overlay, the URL is the location of the watermark image. The maximum size is 4096x4096.\n* When creating clips from existing Mux assets, the URL is defined with `mux://assets/{asset_id}` template where `asset_id` is the Asset Identifier for creating the clip from.\nThe url property may be omitted on the first input object when providing asset settings for LiveStream and Upload objects, in order to configure settings related to the primary (live stream or direct upload) input.\n" }, "overlay_settings": { "type": "object", "description": "An object that describes how the image file referenced in URL should be placed over the video (i.e. watermarking). Ensure that the URL is active and persists the entire lifespan of the video object.", "properties": { "vertical_align": { "type": "string", "enum": [ "top", "middle", "bottom" ], "description": "Where the vertical positioning of the overlay/watermark should begin from. Defaults to `\"top\"`" }, "vertical_margin": { "type": "string", "description": "The distance from the vertical_align starting point and the image's closest edge. Can be expressed as a percent (\"10%\") or as a pixel value (\"100px\"). Negative values will move the overlay offscreen. In the case of 'middle', a positive value will shift the overlay towards the bottom and and a negative value will shift it towards the top." }, "horizontal_align": { "type": "string", "enum": [ "left", "center", "right" ], "description": "Where the horizontal positioning of the overlay/watermark should begin from." }, "horizontal_margin": { "type": "string", "description": "The distance from the horizontal_align starting point and the image's closest edge. Can be expressed as a percent (\"10%\") or as a pixel value (\"100px\"). Negative values will move the overlay offscreen. In the case of 'center', a positive value will shift the image towards the right and and a negative value will shift it towards the left." }, "width": { "type": "string", "description": "How wide the overlay should appear. Can be expressed as a percent (\"10%\") or as a pixel value (\"100px\"). If both width and height are left blank the width will be the true pixels of the image, applied as if the video has been scaled to fit a 1920x1080 frame. If height is supplied with no width, the width will scale proportionally to the height." }, "height": { "type": "string", "description": "How tall the overlay should appear. Can be expressed as a percent (\"10%\") or as a pixel value (\"100px\"). If both width and height are left blank the height will be the true pixels of the image, applied as if the video has been scaled to fit a 1920x1080 frame. If width is supplied with no height, the height will scale proportionally to the width." }, "opacity": { "type": "string", "description": "How opaque the overlay should appear, expressed as a percent. (Default 100%)" } } }, "generated_subtitles": { "type": "array", "items": { "$ref": "#/components/schemas/AssetGeneratedSubtitleSettings" }, "description": "Generate subtitle tracks using automatic speech recognition with this configuration. Subtitles are generated using the audio of the input they are nested within. For direct uploads, this first input should omit the url parameter, as the main input file is provided via the direct upload. Note that subtitle generation happens after initial ingest, so the generated tracks will be in the `preparing` state when the asset transitions to `ready`." }, "start_time": { "type": "number", "format": "double", "description": "The time offset in seconds from the beginning of the video indicating the clip's starting marker. The default value is 0 when not included. This parameter is only applicable for creating clips when `input.url` has `mux://assets/{asset_id}` format." }, "end_time": { "type": "number", "format": "double", "description": "The time offset in seconds from the beginning of the video, indicating the clip's ending marker. The default value is the duration of the video when not included. This parameter is only applicable for creating clips when `input.url` has `mux://assets/{asset_id}` format." }, "type": { "type": "string", "enum": [ "video", "audio", "text" ], "description": "This parameter is required for `text` type tracks." }, "text_type": { "type": "string", "enum": [ "subtitles", "chapters" ], "description": "Type of text track. Use `subtitles` for subtitles and closed captions, or `chapters` for a chapters track. For more information on Subtitles / Closed Captions, [see this blog post](https://mux.com/blog/subtitles-captions-webvtt-hls-and-those-magic-flags/). This parameter is required for `text` type tracks." }, "language_code": { "type": "string", "description": "The language code value must be a valid [BCP 47](https://tools.ietf.org/html/bcp47) specification compliant value. For example, `en` for English or `en-US` for the US version of English. This parameter is required for `text` and `audio` track types." }, "name": { "type": "string", "description": "The name of the track containing a human-readable description. This value must be unique within each group of `text` or `audio` track types. The HLS manifest will associate a subtitle text track with this value. For example, the value should be \"English\" for a subtitle text track with `language_code` set to `en`. This optional parameter should be used only for `text` and `audio` type tracks. This parameter can be optionally provided for the first video input to denote the name of the muxed audio track if present. If this parameter is not included, Mux will auto-populate based on the `input[].language_code` value." }, "closed_captions": { "type": "boolean", "description": "Indicates the track provides Subtitles for the Deaf or Hard-of-hearing (SDH). This optional parameter should be used for tracks with `type` of `text` and `text_type` set to `subtitles`." }, "passthrough": { "type": "string", "description": "This optional parameter should be used for tracks with `type` of `text` and `text_type` set to `subtitles`." } } }, "InputTrack": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string" }, "duration": { "type": "number", "format": "double" }, "encoding": { "type": "string" }, "width": { "type": "integer", "format": "int64" }, "height": { "type": "integer", "format": "int64" }, "frame_rate": { "type": "number", "format": "double" }, "sample_rate": { "type": "integer", "format": "int64" }, "sample_size": { "type": "integer", "format": "int64" }, "channels": { "type": "integer", "format": "int64" } } }, "InputFile": { "type": "object", "properties": { "container_format": { "type": "string" }, "tracks": { "type": "array", "items": { "$ref": "#/components/schemas/InputTrack" } } } }, "InputInfo": { "type": "object", "properties": { "settings": { "$ref": "#/components/schemas/InputSettings" }, "file": { "$ref": "#/components/schemas/InputFile" } } }, "LiveStreamEmbeddedSubtitleSettings": { "type": "object", "required": [ "name", "language_code", "language_channel" ], "properties": { "name": { "type": "string", "description": "A name for this live stream closed caption track." }, "passthrough": { "type": "string", "description": "Arbitrary user-supplied metadata set for the live stream closed caption track. Max 255 characters." }, "language_code": { "type": "string", "description": "The language of the closed caption stream. Value must be BCP 47 compliant.", "default": "en" }, "language_channel": { "type": "string", "description": "CEA-608 caption channel to read data from.", "default": "cc1", "enum": [ "cc1", "cc2", "cc3", "cc4" ] } } }, "LiveStreamEmbeddedSubtitleRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "A name for this live stream closed caption track." }, "passthrough": { "type": "string", "description": "Arbitrary user-supplied metadata set for the live stream closed caption track. Max 255 characters." }, "language_code": { "type": "string", "description": "The language of the closed caption stream. Value must be BCP 47 compliant.", "default": "en" }, "language_channel": { "type": "string", "description": "CEA-608 caption channel to read data from.", "default": "cc1", "enum": [ "cc1", "cc2", "cc3", "cc4" ] } } }, "LiveStreamGeneratedSubtitleSettings": { "type": "object", "required": [ "name", "language_code" ], "properties": { "name": { "type": "string", "description": "A name for this live stream subtitle track." }, "passthrough": { "type": "string", "description": "Arbitrary metadata set for the live stream subtitle track. Max 255 characters." }, "language_code": { "type": "string", "description": "The language of the audio from which subtitles are generated.", "default": "en", "enum": [ "en", "en-US", "es", "fr", "de", "pt", "it" ] }, "transcription_vocabulary_ids": { "type": "array", "items": { "type": "string" }, "description": "Unique identifiers for existing Transcription Vocabularies to use while generating subtitles for the live stream. If the Transcription Vocabularies provided collectively have more than 1000 phrases, only the first 1000 phrases will be included." } } }, "LiveStreamGeneratedSubtitleRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "A name for this live stream subtitle track." }, "passthrough": { "type": "string", "description": "Arbitrary metadata set for the live stream subtitle track. Max 255 characters." }, "language_code": { "type": "string", "description": "The language of the audio from which subtitles are generated.", "default": "en", "enum": [ "en", "en-US", "es", "fr", "de", "pt", "it" ] }, "transcription_vocabulary_ids": { "type": "array", "items": { "type": "string" }, "description": "Unique identifiers for existing Transcription Vocabularies to use while generating subtitles for the live stream. If the Transcription Vocabularies provided collectively have more than 1000 phrases, only the first 1000 phrases will be included." } } }, "AssetGeneratedSubtitleSettings": { "type": "object", "properties": { "name": { "type": "string", "description": "A name for this subtitle track." }, "passthrough": { "type": "string", "description": "Arbitrary metadata set for the subtitle track. Max 255 characters." }, "language_code": { "type": "string", "description": "The language of the audio from which subtitles are generated. Selecting a language of \"auto\" will allow language detection to set the language code automatically.", "default": "en", "enum": [ "en", "es", "it", "pt", "de", "fr", "pl", "ru", "nl", "ca", "tr", "sv", "uk", "no", "fi", "sk", "el", "cs", "hr", "da", "ro", "bg", "auto" ] } } }, "LiveStreamStatus": { "type": "string", "enum": [ "active", "idle", "disabled" ], "description": "`idle` indicates that there is no active broadcast. `active` indicates that there is an active broadcast and `disabled` status indicates that no future RTMP streams can be published." }, "LiveStream": { "type": "object", "required": [ "id", "created_at", "latency_mode", "max_continuous_duration", "status", "stream_key" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the Live Stream. Max 255 characters." }, "created_at": { "type": "string", "format": "int64", "description": "Time the Live Stream was created, defined as a Unix timestamp (seconds since epoch)." }, "stream_key": { "type": "string", "description": "Unique key used for streaming to a Mux RTMP endpoint. This should be considered as sensitive as credentials, anyone with this stream key can begin streaming. Max 64 characters." }, "active_asset_id": { "type": "string", "description": "The Asset that is currently being created if there is an active broadcast." }, "recent_asset_ids": { "type": "array", "description": "An array of strings with the most recent Asset IDs that were created from this Live Stream. The most recently generated Asset ID is the last entry in the list.", "items": { "type": "string" } }, "status": { "$ref": "#/components/schemas/LiveStreamStatus" }, "playback_ids": { "type": "array", "description": "An array of Playback ID objects. Use these to create HLS playback URLs. See [Play your videos](https://docs.mux.com/guides/play-your-videos) for more details.", "items": { "$ref": "#/components/schemas/PlaybackID" } }, "new_asset_settings": { "$ref": "#/components/schemas/AssetOptions" }, "passthrough": { "type": "string", "description": "Arbitrary user-supplied metadata set for the asset. Max 255 characters." }, "audio_only": { "type": "boolean", "description": "The live stream only processes the audio track if the value is set to true. Mux drops the video track if broadcasted." }, "embedded_subtitles": { "type": "array", "items": { "$ref": "#/components/schemas/LiveStreamEmbeddedSubtitleSettings" }, "description": "Describes the embedded closed caption configuration of the incoming live stream." }, "generated_subtitles": { "type": "array", "items": { "$ref": "#/components/schemas/LiveStreamGeneratedSubtitleSettings" }, "description": "Configure the incoming live stream to include subtitles created with automatic speech recognition. Each Asset created from a live stream with `generated_subtitles` configured will automatically receive two text tracks. The first of these will have a `text_source` value of `generated_live`, and will be available with `ready` status as soon as the stream is live. The second text track will have a `text_source` value of `generated_live_final` and will contain subtitles with improved accuracy, timing, and formatting. However, `generated_live_final` tracks will not be available in `ready` status until the live stream ends. If an Asset has both `generated_live` and `generated_live_final` tracks that are `ready`, then only the `generated_live_final` track will be included during playback." }, "reconnect_window": { "type": "number", "format": "float", "default": 60, "minimum": 0, "maximum": 1800, "description": "When live streaming software disconnects from Mux, either intentionally or due to a drop in the network, the Reconnect Window is the time in seconds that Mux should wait for the streaming software to reconnect before considering the live stream finished and completing the recorded asset. **Max**: 1800s (30 minutes).\n\nIf not specified directly, Standard Latency streams have a Reconnect Window of 60 seconds; Reduced and Low Latency streams have a default of 0 seconds, or no Reconnect Window. For that reason, we suggest specifying a value other than zero for Reduced and Low Latency streams.\n\nReduced and Low Latency streams with a Reconnect Window greater than zero will insert slate media into the recorded asset while waiting for the streaming software to reconnect or when there are brief interruptions in the live stream media. When using a Reconnect Window setting higher than 60 seconds with a Standard Latency stream, we highly recommend enabling slate with the `use_slate_for_standard_latency` option.\n" }, "use_slate_for_standard_latency": { "type": "boolean", "format": "boolean", "default": false, "description": "By default, Standard Latency live streams do not have slate media inserted while waiting for live streaming software to reconnect to Mux. Setting this to true enables slate insertion on a Standard Latency stream." }, "reconnect_slate_url": { "type": "string", "description": "The URL of the image file that Mux should download and use as slate media during interruptions of the live stream media. This file will be downloaded each time a new recorded asset is created from the live stream. If this is not set, the default slate media will be used." }, "reduced_latency": { "type": "boolean", "format": "boolean", "deprecated": true, "x-stainless-deprecation-message": "Use `latency_mode` instead.", "x-mux-doc-decorators": [ "hidden" ], "description": "This field is deprecated. Please use `latency_mode` instead. Latency is the time from when the streamer transmits a frame of video to when you see it in the player. Set this if you want lower latency for your live stream. See the [Reduce live stream latency guide](https://docs.mux.com/guides/reduce-live-stream-latency) to understand the tradeoffs." }, "low_latency": { "type": "boolean", "format": "boolean", "deprecated": true, "x-stainless-deprecation-message": "Use `latency_mode` instead.", "x-mux-doc-decorators": [ "hidden" ], "description": "This field is deprecated. Please use `latency_mode` instead. Latency is the time from when the streamer transmits a frame of video to when you see it in the player. Setting this option will enable compatibility with the LL-HLS specification for low-latency streaming. This typically has lower latency than Reduced Latency streams, and cannot be combined with Reduced Latency." }, "simulcast_targets": { "type": "array", "description": "Each Simulcast Target contains configuration details to broadcast (or \"restream\") a live stream to a third-party streaming service. [See the Stream live to 3rd party platforms guide](https://docs.mux.com/guides/stream-live-to-3rd-party-platforms).", "items": { "$ref": "#/components/schemas/SimulcastTarget" } }, "latency_mode": { "type": "string", "enum": [ "low", "reduced", "standard" ], "description": "Latency is the time from when the streamer transmits a frame of video to when you see it in the player. Set this as an alternative to setting low latency or reduced latency flags." }, "test": { "type": "boolean", "format": "boolean", "description": "True means this live stream is a test live stream. Test live streams can be used to help evaluate the Mux Video APIs for free. There is no limit on the number of test live streams, but they are watermarked with the Mux logo, and limited to 5 minutes. The test live stream is disabled after the stream is active for 5 mins and the recorded asset also deleted after 24 hours." }, "max_continuous_duration": { "$ref": "#/components/schemas/MaxContinuousDuration" }, "srt_passphrase": { "type": "string", "description": "Unique key used for encrypting a stream to a Mux SRT endpoint. Max 64 characters." }, "active_ingest_protocol": { "type": "string", "enum": [ "rtmp", "srt" ], "description": "The protocol used for the active ingest stream. This is only set when the live stream is active." }, "meta": { "$ref": "#/components/schemas/LiveStreamMetadata" } } }, "SigningKey": { "type": "object", "required": [ "id", "created_at" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the Signing Key." }, "created_at": { "type": "string", "format": "int64", "description": "Time at which the object was created. Measured in seconds since the Unix epoch." }, "private_key": { "type": "string", "format": "byte", "description": "A Base64 encoded private key that can be used with the RS256 algorithm when creating a [JWT](https://jwt.io/). **Note that this value is only returned once when creating a URL signing key.**" } } }, "Track": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the Track" }, "type": { "type": "string", "description": "The type of track", "enum": [ "video", "audio", "text" ] }, "duration": { "type": "number", "format": "double", "description": "The duration in seconds of the track media. This parameter is not set for `text` type tracks. This field is optional and may not be set. The top level `duration` field of an asset will always be set." }, "max_width": { "type": "integer", "format": "int64", "description": "The maximum width in pixels available for the track. Only set for the `video` type track." }, "max_height": { "type": "integer", "format": "int64", "description": "The maximum height in pixels available for the track. Only set for the `video` type track." }, "max_frame_rate": { "type": "number", "format": "double", "description": "The maximum frame rate available for the track. Only set for the `video` type track. This field may return `-1` if the frame rate of the input cannot be reliably determined." }, "max_channels": { "type": "integer", "format": "int64", "description": "The maximum number of audio channels the track supports. Only set for the `audio` type track." }, "text_type": { "type": "string", "enum": [ "subtitles", "chapters" ], "description": "This parameter is only set for `text` type tracks." }, "text_source": { "type": "string", "description": "The source of the text contained in a Track of type `text`. Valid `text_source`\nvalues are listed below.\n* `uploaded`: Tracks uploaded to Mux as caption or subtitle files using the Create Asset Track API.\n* `embedded`: Tracks extracted from an embedded stream of CEA-608 closed captions.\n* `generated_vod`: Tracks generated by automatic speech recognition on an on-demand asset.\n* `generated_live`: Tracks generated by automatic speech recognition on a live stream configured with `generated_subtitles`. If an Asset has both `generated_live` and `generated_live_final` tracks that are `ready`, then only the `generated_live_final` track will be included during playback.\n* `generated_live_final`: Tracks generated by automatic speech recognition on a live stream using `generated_subtitles`. The accuracy, timing, and formatting of these subtitles is improved compared to the corresponding `generated_live` tracks. However, `generated_live_final` tracks will not be available in `ready` status until the live stream ends. If an Asset has both `generated_live` and `generated_live_final` tracks that are `ready`, then only the `generated_live_final` track will be included during playback.\n", "enum": [ "uploaded", "embedded", "generated_live", "generated_live_final", "generated_vod" ] }, "language_code": { "type": "string", "description": "The language code value represents [BCP 47](https://tools.ietf.org/html/bcp47) specification compliant value, or 'auto'. For example, `en` for English or `en-US` for the US version of English. This parameter is only set for `text` and `audio` track types. During automatic language detection for generated subtitles, this value will be set to `auto` until the language is determined." }, "name": { "type": "string", "description": "The name of the track containing a human-readable description. The HLS manifest will associate a subtitle `text` or `audio` track with this value. For example, the value should be \"English\" for a subtitle text track for the `language_code` value of `en-US`. This parameter is only set for `text` and `audio` track types." }, "closed_captions": { "type": "boolean", "description": "Indicates the track provides Subtitles for the Deaf or Hard-of-hearing (SDH). This parameter is only set tracks where `type` is `text` and `text_type` is `subtitles`." }, "passthrough": { "type": "string", "description": "Arbitrary user-supplied metadata set for the track either when creating the asset or track. This parameter is only set for `text` type tracks. Max 255 characters." }, "status": { "type": "string", "enum": [ "preparing", "ready", "errored", "deleted" ], "description": "The status of the track." }, "primary": { "type": "boolean", "description": "For an audio track, indicates that this is the primary audio track, ingested from the main input for this asset. The primary audio track cannot be deleted." }, "auto_language_confidence": { "type": "number", "format": "double", "description": "The confidence value (0-1) of the determined language. This value only is available when automatic language detection is utilized in generated subtitles." } } }, "PlaybackID": { "type": "object", "required": [ "id", "policy" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the PlaybackID" }, "policy": { "$ref": "#/components/schemas/PlaybackPolicy" }, "drm_configuration_id": { "type": "string", "description": "The DRM configuration used by this playback ID. Must only be set when `policy` is set to `drm`." } } }, "PlaybackPolicy": { "type": "string", "enum": [ "public", "signed", "drm" ], "description": "* `public` playback IDs are accessible by constructing an HLS URL like `https://stream.mux.com/${PLAYBACK_ID}`\n\n* `signed` playback IDs should be used with tokens `https://stream.mux.com/${PLAYBACK_ID}?token={TOKEN}`. See [Secure video playback](https://docs.mux.com/guides/secure-video-playback) for details about creating tokens.\n\n* `drm` playback IDs are protected with DRM technologies. [See DRM documentation for more details](https://docs.mux.com/guides/protect-videos-with-drm).\n" }, "Upload": { "type": "object", "required": [ "id", "timeout", "status", "cors_origin" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the Direct Upload." }, "timeout": { "type": "integer", "format": "int32", "default": 3600, "minimum": 60, "maximum": 604800, "description": "Max time in seconds for the signed upload URL to be valid. If a successful upload has not occurred before the timeout limit, the direct upload is marked `timed_out`" }, "status": { "type": "string", "enum": [ "waiting", "asset_created", "errored", "cancelled", "timed_out" ] }, "new_asset_settings": { "$ref": "#/components/schemas/AssetOptions" }, "asset_id": { "type": "string", "description": "Only set once the upload is in the `asset_created` state." }, "error": { "type": "object", "description": "Only set if an error occurred during asset creation.", "properties": { "type": { "type": "string", "description": "Label for the specific error" }, "message": { "type": "string", "description": "Human readable error message" } } }, "cors_origin": { "type": "string", "description": "If the upload URL will be used in a browser, you must specify the origin in order for the signed URL to have the correct CORS headers." }, "url": { "type": "string", "description": "The URL to upload the associated source media to." }, "test": { "type": "boolean", "format": "boolean", "description": "Indicates if this is a test Direct Upload, in which case the Asset that gets created will be a `test` Asset." } } }, "SimulcastTarget": { "type": "object", "required": [ "id", "url", "status" ], "properties": { "id": { "type": "string", "description": "ID of the Simulcast Target" }, "passthrough": { "type": "string", "description": "Arbitrary user-supplied metadata set when creating a simulcast target." }, "status": { "type": "string", "enum": [ "idle", "starting", "broadcasting", "errored" ], "description": "The current status of the simulcast target. See Statuses below for detailed description.\n * `idle`: Default status. When the parent live stream is in disconnected status, simulcast targets will be idle state.\n * `starting`: The simulcast target transitions into this state when the parent live stream transition into connected state.\n * `broadcasting`: The simulcast target has successfully connected to the third party live streaming service and is pushing video to that service.\n * `errored`: The simulcast target encountered an error either while attempting to connect to the third party live streaming service, or mid-broadcasting. When a simulcast target has this status it will have an `error_severity` field with more details about the error.\n" }, "stream_key": { "type": "string", "description": "Stream Key represents a stream identifier on the third party live streaming service to send the parent live stream to. Only used for RTMP(s) simulcast destinations." }, "url": { "type": "string", "description": "The RTMP(s) or SRT endpoint for a simulcast destination.\n* For RTMP(s) destinations, this should include the application name for the third party live streaming service, for example: `rtmp://live.example.com/app`.\n* For SRT destinations, this should be a fully formed SRT connection string, for example: `srt://srt-live.example.com:1234?streamid={stream_key}&passphrase={srt_passphrase}`.\n\nNote: SRT simulcast targets can only be used when an source is connected over SRT.\n" }, "error_severity": { "type": "string", "enum": [ "normal", "fatal" ], "description": "The severity of the error encountered by the simulcast target.\nThis field is only set when the simulcast target is in the `errored` status.\nSee the values of severities below and their descriptions.\n * `normal`: The simulcast target encountered an error either while attempting to connect to the third party live streaming service, or mid-broadcasting. A simulcast may transition back into the broadcasting state if a connection with the service can be re-established.\n * `fatal`: The simulcast target is incompatible with the current input to the parent live stream. No further attempts to this simulcast target will be made for the current live stream asset.\n" } } }, "PlaybackRestriction": { "type": "object", "required": [ "id", "referrer", "user_agent", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the Playback Restriction. Max 255 characters." }, "created_at": { "type": "string", "format": "int64", "description": "Time the Playback Restriction was created, defined as a Unix timestamp (seconds since epoch)." }, "updated_at": { "type": "string", "format": "int64", "description": "Time the Playback Restriction was last updated, defined as a Unix timestamp (seconds since epoch)." }, "referrer": { "$ref": "#/components/schemas/ReferrerDomainRestrictionSettings" }, "user_agent": { "$ref": "#/components/schemas/UserAgentRestrictionSettings" } } }, "ReferrerDomainRestrictionSettings": { "type": "object", "description": "A list of domains allowed to play your videos.", "properties": { "allowed_domains": { "type": "array", "items": { "type": "string" }, "description": "List of domains allowed to play videos. Possible values are\n * `[]` Empty Array indicates deny video playback requests for all domains\n * `[\"*\"]` A Single Wildcard `*` entry means allow video playback requests from any domain\n * `[\"*.example.com\", \"foo.com\"]` A list of up to 10 domains or valid dns-style wildcards\n" }, "allow_no_referrer": { "type": "boolean", "default": false, "description": "A boolean to determine whether to allow or deny HTTP requests without `Referer` HTTP request header. Playback requests coming from non-web/native applications like iOS, Android or smart TVs will not have a `Referer` HTTP header. Set this value to `true` to allow these playback requests." } } }, "UserAgentRestrictionSettings": { "type": "object", "description": "Rules that control what user agents are allowed to play your videos. Please see [Using User-Agent HTTP header for validation](https://docs.mux.com/guides/secure-video-playback#using-user-agent-http-header-for-validation) for more details on this feature.", "properties": { "allow_no_user_agent": { "type": "boolean", "default": true, "description": "Whether or not to allow views without a `User-Agent` HTTP request header." }, "allow_high_risk_user_agent": { "type": "boolean", "default": true, "description": "Whether or not to allow high risk user agents. The high risk user agents are defined by Mux." } } }, "ReferrerDomainRestrictionRequest": { "type": "object", "description": "A list of domains allowed to play your videos.", "required": [ "allowed_domains" ], "properties": { "allowed_domains": { "type": "array", "items": { "type": "string" }, "description": "List of domains allowed to play videos. Possible values are\n * `[]` Empty Array indicates deny video playback requests for all domains\n * `[\"*\"]` A Single Wildcard `*` entry means allow video playback requests from any domain\n * `[\"*.example.com\", \"foo.com\"]` A list of up to 10 domains or valid dns-style wildcards\n" }, "allow_no_referrer": { "type": "boolean", "default": false, "description": "A boolean to determine whether to allow or deny HTTP requests without `Referer` HTTP request header. Playback requests coming from non-web/native applications like iOS, Android or smart TVs will not have a `Referer` HTTP header. Set this value to `true` to allow these playback requests." } } }, "UserAgentRestrictionRequest": { "type": "object", "description": "Rules that control what user agents are allowed to play your videos. Please see [Using User-Agent HTTP header for validation](https://docs.mux.com/guides/secure-video-playback#using-user-agent-http-header-for-validation) for more details on this feature.", "properties": { "allow_no_user_agent": { "type": "boolean", "default": true, "description": "Whether or not to allow views without a `User-Agent` HTTP request header." }, "allow_high_risk_user_agent": { "type": "boolean", "default": true, "description": "Whether or not to allow high risk user agents. The high risk user agents are defined by Mux." } } }, "ListDeliveryUsageResponse": { "type": "object", "required": [ "data", "timeframe", "page", "limit" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DeliveryReport" } }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } }, "limit": { "type": "integer", "format": "int64", "description": "Number of assets returned in this response. Default value is 100." }, "page": { "type": "integer", "format": "int32", "description": "Offset by this many pages, of the size of `limit`." } } }, "DeliveryReport": { "type": "object", "required": [ "asset_id", "asset_state", "asset_resolution_tier", "asset_encoding_tier", "asset_duration", "created_at", "delivered_seconds", "delivered_seconds_by_resolution" ], "properties": { "live_stream_id": { "type": "string", "description": "Unique identifier for the live stream that created the asset." }, "asset_id": { "type": "string", "description": "Unique identifier for the asset." }, "passthrough": { "type": "string", "description": "The `passthrough` value for the asset." }, "created_at": { "type": "string", "description": "Time at which the asset was created. Measured in seconds since the Unix epoch." }, "deleted_at": { "type": "string", "description": "If exists, time at which the asset was deleted. Measured in seconds since the Unix epoch." }, "asset_state": { "type": "string", "enum": [ "ready", "errored", "deleted" ], "description": "The state of the asset." }, "asset_duration": { "type": "number", "format": "double", "description": "The duration of the asset in seconds." }, "asset_resolution_tier": { "type": "string", "enum": [ "audio-only", "720p", "1080p", "1440p", "2160p" ], "description": "The resolution tier that the asset was ingested at, affecting billing for ingest & storage" }, "asset_encoding_tier": { "type": "string", "deprecated": true, "x-stainless-deprecation-message": "Use `asset_video_quality` instead.", "enum": [ "smart", "baseline", "premium" ], "description": "This field is deprecated. Please use `asset_video_quality` instead. The encoding tier that the asset was ingested at. [See the video quality guide for more details.](https://docs.mux.com/guides/use-video-quality-levels)" }, "asset_video_quality": { "type": "string", "enum": [ "basic", "plus", "premium" ], "description": "The video quality that the asset was ingested at. This field replaces `asset_encoding_tier`. [See the video quality guide for more details.](https://docs.mux.com/guides/use-video-quality-levels)" }, "delivered_seconds": { "type": "number", "format": "double", "description": "Total number of delivered seconds during this time window." }, "delivered_seconds_by_resolution": { "type": "object", "description": "Seconds delivered broken into resolution tiers. Each tier will only be displayed if there was content delivered in the tier.", "properties": { "tier_2160p": { "type": "number", "format": "double", "description": "Total number of delivered seconds during this time window that had a resolution larger than the 1440p tier (over 4,194,304 pixels total)." }, "tier_1440p": { "type": "number", "format": "double", "description": "Total number of delivered seconds during this time window that had a resolution larger than the 1080p tier but less than or equal to the 2160p tier (over 2,073,600 and <= 4,194,304 pixels total)." }, "tier_1080p": { "type": "number", "format": "double", "description": "Total number of delivered seconds during this time window that had a resolution larger than the 720p tier but less than or equal to the 1440p tier (over 921,600 and <= 2,073,600 pixels total)." }, "tier_720p": { "type": "number", "format": "double", "description": "Total number of delivered seconds during this time window that had a resolution within the 720p tier (up to 921,600 pixels total, based on typical 1280x720)." }, "tier_audio_only": { "type": "number", "format": "double", "description": "Total number of delivered seconds during this time window that had a resolution of audio only." } } } } }, "ListDRMConfigurationsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DRMConfiguration" } } } }, "DRMConfigurationResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DRMConfiguration" } } }, "DRMConfiguration": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the DRM Configuration. Max 255 characters." } } }, "MaxContinuousDuration": { "type": "integer", "format": "int32", "default": 43200, "minimum": 60, "maximum": 43200, "description": "The time in seconds a live stream may be continuously active before being disconnected. Defaults to 12 hours." }, "LiveStreamMetadata": { "type": "object", "description": "Customer provided metadata about this live stream.\n\nNote: This metadata may be publicly available via the video player. Do not include PII or sensitive information.\n", "properties": { "title": { "type": "string", "maxLength": 512, "description": "The live stream title. Max 512 code points." } } }, "AssetDirective": { "type": "object", "description": "A Mux Robots directive to apply to the asset.", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The Mux Robots directive identifier." } } }, "ListVideoViewsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AbridgedVideoView" } }, "total_row_count": { "type": "integer", "format": "int64", "nullable": true }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "required": [ "data", "total_row_count", "timeframe" ] }, "VideoViewResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VideoView" }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } }, "total_row_count": { "type": "integer", "format": "int64", "nullable": true } }, "required": [ "data", "timeframe", "total_row_count" ] }, "ListErrorsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Error" } }, "total_row_count": { "type": "integer", "format": "int64", "nullable": true }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "required": [ "data", "total_row_count", "timeframe" ] }, "Error": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "A unique identifier for this error." }, "percentage": { "type": "number", "format": "double", "description": "The percentage of views that experienced this error." }, "notes": { "type": "string", "description": "Notes that are attached to this error.", "nullable": true }, "message": { "type": "string", "description": "The error message.", "nullable": true }, "last_seen": { "type": "string", "description": "The last time this error was seen (ISO 8601 timestamp)." }, "description": { "type": "string", "description": "Description of the error.", "nullable": true }, "count": { "type": "integer", "format": "int64", "description": "The total number of views that experienced this error." }, "code": { "type": "integer", "format": "int64", "description": "The error code", "nullable": true }, "player_error_code": { "type": "string", "nullable": true, "description": "The string version of the error code" } }, "required": [ "id", "percentage", "notes", "message", "last_seen", "description", "count", "code", "player_error_code" ] }, "ListFiltersResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "basic": { "type": "array", "items": { "type": "string" } }, "advanced": { "type": "array", "items": { "type": "string" } } }, "required": [ "basic", "advanced" ] }, "total_row_count": { "type": "integer", "format": "int64", "nullable": true }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "required": [ "data", "total_row_count", "timeframe" ] }, "ListFilterValuesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FilterValue" } }, "total_row_count": { "type": "integer", "format": "int64" }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "required": [ "data", "total_row_count", "timeframe" ] }, "FilterValue": { "type": "object", "properties": { "value": { "type": "string", "nullable": true }, "total_count": { "type": "integer", "format": "int64" } }, "required": [ "value", "total_count" ] }, "ListDimensionsResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "basic": { "type": "array", "items": { "type": "string" } }, "advanced": { "type": "array", "items": { "type": "string" } } }, "required": [ "basic", "advanced" ] }, "total_row_count": { "type": "integer", "format": "int64", "nullable": true }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "required": [ "data", "total_row_count", "timeframe" ] }, "ListDimensionValuesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DimensionValue" } }, "total_row_count": { "type": "integer", "format": "int64" }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "required": [ "data", "total_row_count", "timeframe" ] }, "DimensionValue": { "type": "object", "properties": { "value": { "type": "string", "nullable": true }, "total_count": { "type": "integer", "format": "int64" } }, "required": [ "value", "total_count" ] }, "ListExportsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string" } }, "total_row_count": { "type": "integer", "format": "int64", "nullable": true }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "required": [ "data", "total_row_count", "timeframe" ] }, "ListVideoViewExportsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExportDate" } }, "total_row_count": { "type": "integer", "format": "int32", "nullable": true }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int32" } } }, "required": [ "data", "total_row_count", "timeframe" ] }, "ExportDate": { "type": "object", "properties": { "export_date": { "type": "string", "format": "date" }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/ExportFile" } } }, "required": [ "export_date", "files" ] }, "ExportFile": { "type": "object", "properties": { "version": { "type": "integer", "format": "int32" }, "type": { "type": "string" }, "path": { "type": "string" } }, "required": [ "version", "type", "path" ] }, "ListBreakdownValuesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BreakdownValue" } }, "total_row_count": { "type": "integer", "format": "int64" }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } }, "meta": { "type": "object", "properties": { "granularity": { "type": "string" }, "aggregation": { "type": "string" } } } }, "required": [ "data", "total_row_count", "timeframe", "meta" ] }, "BreakdownValue": { "type": "object", "properties": { "views": { "type": "integer", "format": "int64" }, "value": { "type": "number", "format": "double" }, "total_watch_time": { "type": "integer", "format": "int64", "nullable": true }, "total_playing_time": { "type": "integer", "format": "int64", "nullable": true }, "negative_impact": { "type": "integer", "format": "int32" }, "field": { "type": "string", "nullable": true } }, "required": [ "field", "value", "views", "negative_impact", "total_watch_time", "total_playing_time" ] }, "GetOverallValuesResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OverallValues" }, "total_row_count": { "type": "integer", "format": "int64", "nullable": true }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } }, "meta": { "type": "object", "properties": { "granularity": { "type": "string" }, "aggregation": { "type": "string" } } } }, "required": [ "data", "timeframe", "total_row_count", "meta" ] }, "OverallValues": { "type": "object", "properties": { "value": { "type": "number", "format": "double" }, "total_watch_time": { "type": "integer", "format": "int64", "nullable": true }, "total_views": { "type": "integer", "format": "int64" }, "total_playing_time": { "type": "integer", "format": "int64", "nullable": true }, "global_value": { "type": "number", "format": "double", "nullable": true, "deprecated": true, "x-stainless-deprecation-message": "No longer updated; do not use." } }, "required": [ "value", "total_watch_time", "total_views", "total_playing_time" ] }, "ListInsightsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Insight" } }, "total_row_count": { "type": "integer", "format": "int64" }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } }, "meta": { "type": "object", "properties": { "granularity": { "type": "string" }, "aggregation": { "type": "string" } } } }, "required": [ "data", "timeframe", "total_row_count", "meta" ] }, "Insight": { "type": "object", "properties": { "total_watch_time": { "type": "integer", "format": "int64", "nullable": true }, "total_playing_time": { "type": "integer", "format": "int64", "nullable": true }, "total_views": { "type": "integer", "format": "int64" }, "negative_impact_score": { "type": "number", "format": "float" }, "metric": { "type": "number", "format": "double" }, "filter_value": { "type": "string", "nullable": true }, "filter_column": { "type": "string" } }, "required": [ "total_watch_time", "total_playing_time", "total_views", "negative_impact_score", "metric", "filter_value", "filter_column" ] }, "GetMetricTimeseriesDataResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "integer", "format": "int64", "nullable": true }, { "type": "number", "format": "double", "nullable": true } ] } } }, "total_row_count": { "type": "integer", "format": "int64" }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } }, "meta": { "type": "object", "properties": { "granularity": { "type": "string" }, "aggregation": { "type": "string" } } } }, "required": [ "data", "timeframe", "total_row_count", "meta" ] }, "ListAllMetricValuesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Score" } }, "total_row_count": { "type": "integer", "format": "int64", "nullable": true }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "required": [ "data", "timeframe", "total_row_count" ] }, "Score": { "type": "object", "properties": { "watch_time": { "type": "integer", "format": "int64", "nullable": true }, "view_count": { "type": "integer", "format": "int64" }, "unique_viewers": { "type": "integer", "format": "int64" }, "started_views": { "type": "integer", "format": "int64" }, "total_playing_time": { "type": "integer", "format": "int64", "nullable": true }, "name": { "type": "string" }, "ended_views": { "type": "integer", "format": "int64" }, "value": { "type": "number", "format": "double" }, "type": { "type": "string" }, "metric": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Metric" } } }, "required": [ "name" ] }, "Metric": { "type": "object", "properties": { "value": { "type": "number", "format": "double", "nullable": true }, "type": { "type": "string" }, "name": { "type": "string" }, "metric": { "type": "string" }, "measurement": { "type": "string" } }, "required": [ "name", "value", "type", "metric" ] }, "SubviewMetricsMeta": { "type": "object", "properties": { "subview_type": { "type": "string" }, "metric": { "type": "string" }, "unit": { "type": "string" } }, "required": [ "subview_type", "metric", "unit" ] }, "GetSubviewOverallValuesResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "metric_value": { "type": "number", "format": "double" } }, "required": [ "metric_value" ] }, "meta": { "$ref": "#/components/schemas/SubviewMetricsMeta" }, "total_row_count": { "type": "integer", "format": "int64", "nullable": true, "description": "Always `null` for this endpoint — a single aggregate value has no row count." }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "required": [ "data", "meta", "total_row_count", "timeframe" ] }, "SubviewBreakdownValue": { "type": "object", "properties": { "breakdown_value": { "type": "string" }, "metric_value": { "type": "number", "format": "double" } }, "required": [ "breakdown_value", "metric_value" ] }, "ListSubviewBreakdownValuesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SubviewBreakdownValue" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/SubviewMetricsMeta" }, { "type": "object", "properties": { "group_by": { "type": "array", "items": { "type": "string" } } }, "required": [ "group_by" ] } ] }, "total_row_count": { "type": "integer", "format": "int64" }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "required": [ "data", "meta", "total_row_count", "timeframe" ] }, "SubviewComparisonGroup": { "type": "object", "properties": { "dimension_value": { "type": "string" }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/SubviewBreakdownValue" } } }, "required": [ "dimension_value", "values" ] }, "ListSubviewComparisonValuesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SubviewComparisonGroup" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/SubviewMetricsMeta" }, { "type": "object", "properties": { "dimension": { "type": "string" }, "group_by": { "type": "array", "items": { "type": "string" } } }, "required": [ "dimension", "group_by" ] } ] }, "total_row_count": { "type": "integer", "format": "int64", "description": "Number of dimension-value groups in `data`." }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "required": [ "data", "meta", "total_row_count", "timeframe" ] }, "SubviewBreakdownTimeseriesDatapoint": { "type": "object", "properties": { "date": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "complete", "partial" ] }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/SubviewBreakdownValue" } } }, "required": [ "date", "status", "values" ] }, "GetSubviewBreakdownTimeseriesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SubviewBreakdownTimeseriesDatapoint" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/SubviewMetricsMeta" }, { "type": "object", "properties": { "group_by": { "type": "array", "items": { "type": "string" } }, "time_granularity": { "type": "string", "enum": [ "hour", "day" ] }, "complete_through": { "type": "string", "format": "date-time" } }, "required": [ "group_by", "time_granularity", "complete_through" ] } ] }, "total_row_count": { "type": "integer", "format": "int64", "description": "Number of time buckets in `data`." }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "required": [ "data", "meta", "total_row_count", "timeframe" ] }, "ListSubviewDimensionsResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "view": { "type": "array", "items": { "type": "string" } }, "subview": { "type": "array", "items": { "type": "string" } } }, "required": [ "view", "subview" ] }, "total_row_count": { "type": "integer", "format": "int64", "nullable": true, "description": "Always `null` for this endpoint, matching `GET /data/v1/dimensions`, which also never computes a row count." } }, "required": [ "data", "total_row_count" ] }, "SubviewDimensionValue": { "type": "object", "properties": { "value": { "type": "string" }, "playing_time": { "type": "number", "format": "double" } }, "required": [ "value", "playing_time" ] }, "ListSubviewDimensionValuesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SubviewDimensionValue" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/SubviewMetricsMeta" }, { "type": "object", "properties": { "dimension_name": { "type": "string" } }, "required": [ "dimension_name" ] } ] }, "total_row_count": { "type": "integer", "format": "int64" }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "required": [ "data", "meta", "total_row_count", "timeframe" ] }, "ListMonitoringDimensionsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "display_name": { "type": "string" } }, "required": [ "name", "display_name" ] } }, "total_row_count": { "type": "integer", "format": "int64", "nullable": true }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "required": [ "data", "timeframe", "total_row_count" ] }, "ListMonitoringMetricsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "display_name": { "type": "string" } }, "required": [ "name", "display_name" ] } }, "total_row_count": { "type": "integer", "format": "int64", "nullable": true }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "required": [ "data", "timeframe", "total_row_count" ] }, "GetMonitoringBreakdownResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MonitoringBreakdownValue" } }, "total_row_count": { "type": "integer", "format": "int64", "nullable": true }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "required": [ "data", "timeframe", "total_row_count" ] }, "MonitoringBreakdownValue": { "type": "object", "properties": { "value": { "type": "string", "nullable": true }, "negative_impact": { "type": "integer", "format": "int64" }, "metric_value": { "type": "number", "format": "double", "nullable": true }, "display_value": { "type": "string" }, "concurrent_viewers": { "type": "integer", "format": "int64" }, "starting_up_viewers": { "type": "integer", "format": "int64" } }, "required": [ "value", "negative_impact", "metric_value", "concurrent_viewers", "starting_up_viewers" ] }, "GetMonitoringBreakdownTimeseriesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MonitoringBreakdownTimeseriesValues" } }, "total_row_count": { "type": "integer", "format": "int64", "nullable": true }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "required": [ "data", "timeframe", "total_row_count" ] }, "MonitoringBreakdownTimeseriesValues": { "type": "object", "properties": { "values": { "type": "array", "items": { "$ref": "#/components/schemas/MonitoringBreakdownTimeseriesDatapoint" } }, "date": { "type": "string" } }, "required": [ "values", "date" ] }, "MonitoringBreakdownTimeseriesDatapoint": { "type": "object", "properties": { "value": { "type": "string", "nullable": true }, "metric_value": { "type": "number", "format": "double", "nullable": true }, "concurrent_viewers": { "type": "integer", "format": "int64" }, "starting_up_viewers": { "type": "integer", "format": "int64" } }, "required": [ "value", "metric_value", "concurrent_viewers", "starting_up_viewers" ] }, "GetMonitoringHistogramTimeseriesResponse": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "bucket_unit": { "type": "string" }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/MonitoringHistogramTimeseriesBucket" } } }, "required": [ "bucket_unit", "buckets" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MonitoringHistogramTimeseriesDatapoint" } }, "total_row_count": { "type": "integer", "format": "int64", "nullable": true }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "required": [ "meta", "data", "timeframe", "total_row_count" ] }, "MonitoringHistogramTimeseriesDatapoint": { "type": "object", "properties": { "timestamp": { "type": "string" }, "sum": { "type": "integer", "format": "int64" }, "p95": { "type": "number", "format": "double", "nullable": true }, "median": { "type": "number", "format": "double", "nullable": true }, "max_percentage": { "type": "number", "format": "double" }, "bucket_values": { "type": "array", "items": { "$ref": "#/components/schemas/MonitoringHistogramTimeseriesBucketValues" } }, "average": { "type": "number", "format": "double", "nullable": true } }, "required": [ "timestamp", "sum", "p95", "median", "max_percentage", "bucket_values", "average" ] }, "MonitoringHistogramTimeseriesBucket": { "type": "object", "properties": { "start": { "type": "integer", "format": "int64" }, "end": { "type": "integer", "format": "int64", "nullable": true } }, "required": [ "start", "end" ] }, "MonitoringHistogramTimeseriesBucketValues": { "type": "object", "properties": { "percentage": { "type": "number", "format": "double" }, "count": { "type": "integer", "format": "int64" } }, "required": [ "percentage", "count" ] }, "GetMonitoringTimeseriesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MonitoringTimeseriesDatapoint" } }, "total_row_count": { "type": "integer", "format": "int64", "nullable": true }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "required": [ "data", "timeframe", "total_row_count" ] }, "MonitoringTimeseriesDatapoint": { "type": "object", "properties": { "value": { "type": "number", "format": "double", "nullable": true }, "date": { "type": "string" }, "concurrent_viewers": { "type": "integer", "format": "int64" } }, "required": [ "value", "date", "concurrent_viewers" ] }, "ListRealTimeDimensionsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "display_name": { "type": "string" } }, "required": [ "name", "display_name" ] } }, "total_row_count": { "type": "integer", "format": "int64", "nullable": true }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "required": [ "data", "timeframe", "total_row_count" ] }, "ListRealTimeMetricsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "display_name": { "type": "string" } }, "required": [ "name", "display_name" ] } }, "total_row_count": { "type": "integer", "format": "int64", "nullable": true }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "required": [ "data", "timeframe", "total_row_count" ] }, "GetRealTimeBreakdownResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RealTimeBreakdownValue" } }, "total_row_count": { "type": "integer", "format": "int64", "nullable": true }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "required": [ "data", "timeframe", "total_row_count" ] }, "RealTimeBreakdownValue": { "type": "object", "properties": { "value": { "type": "string", "nullable": true }, "negative_impact": { "type": "integer", "format": "int64" }, "metric_value": { "type": "number", "format": "double", "nullable": true }, "display_value": { "type": "string" }, "concurrent_viewers": { "type": "integer", "format": "int64" }, "starting_up_viewers": { "type": "integer", "format": "int64" } }, "required": [ "value", "negative_impact", "metric_value", "concurrent_viewers", "starting_up_viewers" ] }, "GetRealTimeHistogramTimeseriesResponse": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "bucket_unit": { "type": "string" }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/RealTimeHistogramTimeseriesBucket" } } }, "required": [ "bucket_unit", "buckets" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/RealTimeHistogramTimeseriesDatapoint" } }, "total_row_count": { "type": "integer", "format": "int64", "nullable": true }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "required": [ "meta", "data", "timeframe", "total_row_count" ] }, "RealTimeHistogramTimeseriesDatapoint": { "type": "object", "properties": { "timestamp": { "type": "string" }, "sum": { "type": "integer", "format": "int64" }, "p95": { "type": "number", "format": "double", "nullable": true }, "median": { "type": "number", "format": "double", "nullable": true }, "max_percentage": { "type": "number", "format": "double" }, "bucket_values": { "type": "array", "items": { "$ref": "#/components/schemas/RealTimeHistogramTimeseriesBucketValues" } }, "average": { "type": "number", "format": "double", "nullable": true } }, "required": [ "timestamp", "sum", "p95", "median", "max_percentage", "bucket_values", "average" ] }, "RealTimeHistogramTimeseriesBucket": { "type": "object", "properties": { "start": { "type": "integer", "format": "int64" }, "end": { "type": "integer", "format": "int64", "nullable": true } }, "required": [ "start", "end" ] }, "RealTimeHistogramTimeseriesBucketValues": { "type": "object", "properties": { "percentage": { "type": "number", "format": "double" }, "count": { "type": "integer", "format": "int64" } }, "required": [ "percentage", "count" ] }, "GetRealTimeTimeseriesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RealTimeTimeseriesDatapoint" } }, "total_row_count": { "type": "integer", "format": "int64", "nullable": true }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "required": [ "data", "timeframe", "total_row_count" ] }, "RealTimeTimeseriesDatapoint": { "type": "object", "properties": { "value": { "type": "number", "format": "double", "nullable": true }, "date": { "type": "string" }, "concurrent_viewers": { "type": "integer", "format": "int64" } }, "required": [ "value", "date", "concurrent_viewers" ] }, "ListIncidentsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Incident" } }, "total_row_count": { "type": "integer", "format": "int64", "nullable": true }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "required": [ "data", "timeframe", "total_row_count" ] }, "ListRelatedIncidentsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Incident" } }, "total_row_count": { "type": "integer", "format": "int64", "nullable": true }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "required": [ "data", "timeframe", "total_row_count" ] }, "IncidentResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Incident" }, "total_row_count": { "type": "integer", "format": "int64", "nullable": true }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "required": [ "data", "timeframe", "total_row_count" ] }, "Incident": { "type": "object", "properties": { "threshold": { "type": "number", "format": "double" }, "status": { "type": "string" }, "started_at": { "type": "string" }, "severity": { "type": "string" }, "sample_size_unit": { "type": "string" }, "sample_size": { "type": "integer", "format": "int64" }, "resolved_at": { "type": "string", "nullable": true }, "notifications": { "type": "array", "items": { "$ref": "#/components/schemas/IncidentNotification" } }, "notification_rules": { "type": "array", "items": { "$ref": "#/components/schemas/IncidentNotificationRule" } }, "measurement": { "type": "string" }, "measured_value_on_close": { "type": "number", "format": "double", "nullable": true }, "measured_value": { "type": "number", "format": "double", "nullable": true }, "incident_key": { "type": "string" }, "impact": { "type": "string" }, "id": { "type": "string" }, "error_description": { "type": "string" }, "description": { "type": "string" }, "breakdowns": { "type": "array", "items": { "$ref": "#/components/schemas/IncidentBreakdown" } }, "affected_views_per_hour_on_open": { "type": "integer", "format": "int64" }, "affected_views_per_hour": { "type": "integer", "format": "int64" }, "affected_views": { "type": "integer", "format": "int64" } }, "required": [ "id", "started_at", "resolved_at", "incident_key", "measurement", "measured_value", "measured_value_on_close", "sample_size", "sample_size_unit", "breakdowns", "severity", "description", "impact", "affected_views", "affected_views_per_hour", "affected_views_per_hour_on_open", "threshold", "notifications", "notification_rules", "error_description", "status" ] }, "IncidentBreakdown": { "type": "object", "properties": { "value": { "type": "string" }, "name": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "name", "value" ] }, "IncidentNotification": { "type": "object", "properties": { "queued_at": { "type": "string" }, "id": { "type": "integer", "format": "int64" }, "attempted_at": { "type": "string" } }, "required": [ "queued_at", "id", "attempted_at" ] }, "IncidentNotificationRule": { "type": "object", "properties": { "status": { "type": "string" }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationRule" } }, "property_id": { "type": "string" }, "id": { "type": "string" }, "action": { "type": "string" } }, "required": [ "status", "rules", "property_id", "id", "action" ] }, "NotificationRule": { "type": "object", "properties": { "value": { "type": "string" }, "name": { "type": "string" }, "id": { "type": "string" } }, "required": [ "value", "name", "id" ] }, "VideoView": { "type": "object", "properties": { "view_total_upscaling": { "type": "string", "nullable": true }, "preroll_ad_asset_hostname": { "type": "string", "nullable": true }, "player_source_domain": { "type": "string", "nullable": true }, "region": { "type": "string", "nullable": true }, "viewer_user_agent": { "type": "string", "nullable": true }, "preroll_requested": { "type": "boolean", "nullable": true }, "page_type": { "type": "string", "nullable": true }, "startup_score": { "type": "string", "nullable": true }, "view_seek_duration": { "type": "integer", "format": "int64", "nullable": true }, "country_name": { "type": "string", "nullable": true }, "player_source_height": { "type": "integer", "format": "int32", "nullable": true }, "longitude": { "type": "string", "nullable": true }, "buffering_count": { "type": "integer", "format": "int64", "nullable": true }, "video_duration": { "type": "integer", "format": "int64", "nullable": true }, "player_source_type": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "view_id": { "type": "string" }, "platform_description": { "type": "string", "nullable": true }, "video_startup_preroll_request_time": { "type": "integer", "format": "int64", "nullable": true }, "viewer_device_name": { "type": "string", "nullable": true }, "video_series": { "type": "string", "nullable": true }, "viewer_application_name": { "type": "string", "nullable": true }, "updated_at": { "type": "string" }, "view_total_content_playback_time": { "type": "integer", "format": "int64", "nullable": true }, "cdn": { "type": "string", "nullable": true }, "player_instance_id": { "type": "string", "nullable": true }, "video_language": { "type": "string", "nullable": true }, "player_source_width": { "type": "integer", "format": "int32", "nullable": true }, "player_error_message": { "type": "string", "nullable": true }, "player_mux_plugin_version": { "type": "string", "nullable": true }, "watched": { "type": "boolean" }, "playback_score": { "type": "string", "nullable": true }, "page_url": { "type": "string", "nullable": true }, "metro": { "type": "string", "nullable": true }, "view_max_request_latency": { "type": "integer", "format": "int64", "nullable": true }, "requests_for_first_preroll": { "type": "integer", "format": "int64", "nullable": true }, "view_total_downscaling": { "type": "string", "nullable": true }, "latitude": { "type": "string", "nullable": true }, "player_source_host_name": { "type": "string", "nullable": true }, "inserted_at": { "type": "string" }, "view_end": { "type": "string" }, "mux_embed_version": { "type": "string", "nullable": true }, "player_language": { "type": "string", "nullable": true }, "page_load_time": { "type": "integer", "format": "int64", "nullable": true }, "viewer_device_category": { "type": "string", "nullable": true }, "video_startup_preroll_load_time": { "type": "integer", "format": "int64", "nullable": true }, "player_version": { "type": "string", "nullable": true }, "watch_time": { "type": "integer", "format": "int64", "nullable": true }, "player_source_stream_type": { "type": "string", "nullable": true }, "preroll_ad_tag_hostname": { "type": "string", "nullable": true }, "viewer_device_manufacturer": { "type": "string", "nullable": true }, "rebuffering_score": { "type": "string", "nullable": true }, "experiment_name": { "type": "string", "nullable": true }, "viewer_os_version": { "type": "string", "nullable": true }, "player_preload": { "type": "boolean" }, "buffering_duration": { "type": "integer", "format": "int64", "nullable": true }, "player_view_count": { "type": "integer", "format": "int64", "nullable": true }, "player_software": { "type": "string", "nullable": true }, "player_load_time": { "type": "integer", "format": "int64", "nullable": true }, "platform_summary": { "type": "string", "nullable": true }, "video_encoding_variant": { "type": "string", "nullable": true }, "player_width": { "type": "integer", "format": "int32", "nullable": true }, "view_seek_count": { "type": "integer", "format": "int64", "nullable": true }, "viewer_experience_score": { "type": "string", "nullable": true }, "view_error_id": { "type": "integer", "format": "int32", "nullable": true }, "video_variant_name": { "type": "string", "nullable": true }, "preroll_played": { "type": "boolean", "nullable": true }, "viewer_application_engine": { "type": "string", "nullable": true }, "viewer_os_architecture": { "type": "string", "nullable": true }, "player_error_code": { "type": "string", "nullable": true }, "buffering_rate": { "type": "string", "nullable": true }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/VideoViewEvent" } }, "player_name": { "type": "string", "nullable": true }, "view_start": { "type": "string" }, "view_average_request_throughput": { "type": "integer", "format": "int64", "nullable": true }, "video_producer": { "type": "string", "nullable": true }, "error_type_id": { "type": "integer", "format": "int32", "nullable": true }, "mux_viewer_id": { "type": "string" }, "video_id": { "type": "string", "nullable": true }, "continent_code": { "type": "string", "nullable": true }, "session_id": { "type": "string" }, "exit_before_video_start": { "type": "boolean" }, "video_content_type": { "type": "string", "nullable": true }, "viewer_os_family": { "type": "string", "nullable": true }, "player_poster": { "type": "string", "nullable": true }, "view_average_request_latency": { "type": "integer", "format": "int64", "nullable": true }, "video_variant_id": { "type": "string", "nullable": true }, "player_source_duration": { "type": "integer", "format": "int64", "nullable": true }, "player_source_url": { "type": "string", "nullable": true }, "mux_api_version": { "type": "string" }, "video_title": { "type": "string", "nullable": true }, "id": { "type": "string" }, "short_time": { "type": "string" }, "rebuffer_percentage": { "type": "string", "nullable": true }, "time_to_first_frame": { "type": "integer", "format": "int64", "nullable": true }, "viewer_user_id": { "type": "string", "nullable": true }, "video_stream_type": { "type": "string", "nullable": true }, "player_startup_time": { "type": "integer", "format": "int64", "nullable": true }, "viewer_application_version": { "type": "string", "nullable": true }, "view_max_downscale_percentage": { "type": "string", "nullable": true }, "view_max_upscale_percentage": { "type": "string", "nullable": true }, "country_code": { "type": "string", "nullable": true }, "used_fullscreen": { "type": "boolean" }, "isp": { "type": "string", "nullable": true }, "property_id": { "type": "integer", "format": "int64" }, "player_autoplay": { "type": "boolean" }, "player_height": { "type": "integer", "format": "int32", "nullable": true }, "asn": { "type": "integer", "format": "int64", "nullable": true }, "asn_name": { "type": "string", "nullable": true }, "quality_score": { "type": "string", "nullable": true }, "player_software_version": { "type": "string", "nullable": true }, "player_mux_plugin_name": { "type": "string", "nullable": true }, "sub_property_id": { "type": "string", "nullable": true }, "player_remote_played": { "type": "boolean", "nullable": true }, "view_max_playhead_position": { "type": "string", "nullable": true }, "view_playing_time": { "type": "string", "nullable": true }, "view_session_id": { "type": "string", "nullable": true }, "viewer_connection_type": { "type": "string", "nullable": true }, "viewer_device_model": { "type": "string", "nullable": true }, "weighted_average_bitrate": { "type": "number", "format": "double", "nullable": true }, "custom_1": { "type": "string", "nullable": true }, "custom_2": { "type": "string", "nullable": true }, "custom_3": { "type": "string", "nullable": true }, "custom_4": { "type": "string", "nullable": true }, "custom_5": { "type": "string", "nullable": true }, "custom_6": { "type": "string", "nullable": true }, "custom_7": { "type": "string", "nullable": true }, "custom_8": { "type": "string", "nullable": true }, "custom_9": { "type": "string", "nullable": true }, "custom_10": { "type": "string", "nullable": true }, "live_stream_latency": { "type": "integer", "format": "int64", "nullable": true }, "asset_id": { "type": "string", "nullable": true }, "environment_id": { "type": "string" }, "live_stream_id": { "type": "string", "nullable": true }, "mux_embed": { "type": "string", "nullable": true }, "playback_id": { "type": "string", "nullable": true }, "player_error_context": { "type": "string", "nullable": true }, "view_drm_type": { "type": "string", "nullable": true }, "view_dropped_frame_count": { "type": "integer", "format": "int64", "nullable": true }, "view_has_ad": { "type": "boolean" }, "video_startup_failure": { "type": "boolean" }, "ad_attempt_count": { "type": "integer", "format": "int32", "nullable": true }, "ad_break_count": { "type": "integer", "format": "int32", "nullable": true }, "ad_break_error_count": { "type": "integer", "format": "int32", "nullable": true }, "ad_break_error_percentage": { "type": "string", "nullable": true }, "ad_error_count": { "type": "integer", "format": "int32", "nullable": true }, "ad_error_percentage": { "type": "string", "nullable": true }, "ad_impression_count": { "type": "integer", "format": "int32", "nullable": true }, "ad_startup_error_count": { "type": "integer", "format": "int32", "nullable": true }, "ad_startup_error_percentage": { "type": "string", "nullable": true }, "ad_exit_before_start_count": { "type": "integer", "format": "int32", "nullable": true }, "ad_exit_before_start_percentage": { "type": "string", "nullable": true }, "rendition_change_count": { "type": "integer", "format": "int32", "nullable": true }, "rendition_upshift_count": { "type": "integer", "format": "int32", "nullable": true }, "rendition_downshift_count": { "type": "integer", "format": "int32", "nullable": true }, "long_resume": { "type": "boolean" }, "long_rebuffering": { "type": "boolean" }, "playback_failure_error_type_id": { "type": "integer", "format": "int32", "nullable": true }, "playback_business_exception_error_type_id": { "type": "integer", "format": "int32", "nullable": true }, "video_startup_business_exception_error_type_id": { "type": "integer", "format": "int32", "nullable": true }, "playback_failure": { "type": "boolean" }, "ad_playback_failure_error_type_id": { "type": "integer", "format": "int32", "nullable": true }, "view_content_startup_time": { "type": "integer", "format": "int32", "nullable": true }, "ad_preroll_startup_time": { "type": "integer", "format": "int32", "nullable": true }, "view_dropped": { "type": "boolean" }, "client_application_name": { "type": "string", "nullable": true }, "client_application_version": { "type": "string", "nullable": true }, "video_affiliate": { "type": "string", "nullable": true }, "viewer_plan": { "type": "string", "nullable": true }, "viewer_plan_status": { "type": "string", "nullable": true }, "viewer_plan_category": { "type": "string", "nullable": true }, "view_drm_level": { "type": "string", "nullable": true }, "video_brand": { "type": "string", "nullable": true }, "used_pip": { "type": "boolean" }, "time_shift_enabled": { "type": "boolean" }, "used_captions": { "type": "boolean" }, "video_codec": { "type": "string", "nullable": true }, "audio_codec": { "type": "string", "nullable": true }, "video_dynamic_range_type": { "type": "string", "nullable": true }, "video_source_height_initial": { "type": "integer", "format": "int32", "nullable": true }, "video_source_width_initial": { "type": "integer", "format": "int32", "nullable": true }, "video_source_bitrate_initial": { "type": "integer", "format": "int64", "nullable": true }, "video_codec_initial": { "type": "string", "nullable": true }, "audio_codec_initial": { "type": "string", "nullable": true }, "video_source_fps_initial": { "type": "number", "format": "double", "nullable": true }, "video_dynamic_range_type_initial": { "type": "string", "nullable": true }, "video_source_fps": { "type": "number", "format": "double", "nullable": true }, "video_source_bitrate": { "type": "integer", "format": "int64", "nullable": true }, "video_source_height": { "type": "integer", "format": "int32", "nullable": true }, "video_source_width": { "type": "integer", "format": "int32", "nullable": true }, "view_cdn_edge_pop": { "type": "string", "nullable": true }, "view_cdn_origin": { "type": "string", "nullable": true }, "video_creator_id": { "type": "string", "nullable": true }, "video_cdn_trace": { "type": "array", "items": { "type": "string" } } }, "required": [ "ad_attempt_count", "ad_break_count", "ad_break_error_count", "ad_break_error_percentage", "ad_error_count", "ad_error_percentage", "ad_exit_before_start_count", "ad_exit_before_start_percentage", "ad_impression_count", "ad_startup_error_count", "ad_startup_error_percentage", "rendition_change_count", "rendition_upshift_count", "rendition_downshift_count", "asn", "asn_name", "asset_id", "audio_codec", "buffering_count", "buffering_duration", "buffering_rate", "cdn", "city", "client_application_name", "client_application_version", "continent_code", "country_code", "country_name", "custom_1", "custom_10", "custom_2", "custom_3", "custom_4", "custom_5", "custom_6", "custom_7", "custom_8", "custom_9", "environment_id", "error_type_id", "events", "exit_before_video_start", "experiment_name", "id", "inserted_at", "isp", "latitude", "live_stream_id", "live_stream_latency", "long_rebuffering", "long_resume", "longitude", "metro", "mux_api_version", "mux_embed", "mux_embed_version", "mux_viewer_id", "page_load_time", "page_type", "page_url", "platform_description", "platform_summary", "playback_id", "playback_score", "player_autoplay", "player_error_code", "player_error_message", "player_height", "player_instance_id", "player_language", "player_load_time", "player_mux_plugin_name", "player_mux_plugin_version", "player_name", "player_poster", "player_preload", "player_remote_played", "player_software", "player_software_version", "player_source_domain", "player_source_duration", "player_source_height", "player_source_host_name", "player_source_stream_type", "player_source_type", "player_source_url", "player_source_width", "player_startup_time", "player_version", "player_view_count", "player_width", "preroll_ad_asset_hostname", "preroll_ad_tag_hostname", "preroll_played", "preroll_requested", "property_id", "quality_score", "rebuffer_percentage", "rebuffering_score", "region", "requests_for_first_preroll", "session_id", "short_time", "startup_score", "sub_property_id", "time_shift_enabled", "time_to_first_frame", "updated_at", "used_captions", "used_fullscreen", "used_pip", "video_affiliate", "video_brand", "video_cdn_trace", "video_codec", "video_content_type", "video_creator_id", "video_duration", "video_dynamic_range_type", "video_source_height_initial", "video_source_width_initial", "video_source_bitrate_initial", "video_codec_initial", "audio_codec_initial", "video_source_fps_initial", "video_dynamic_range_type_initial", "video_source_fps", "video_source_bitrate", "video_source_height", "video_source_width", "video_encoding_variant", "video_id", "video_language", "video_producer", "video_series", "video_startup_failure", "video_startup_preroll_load_time", "video_startup_preroll_request_time", "video_stream_type", "video_title", "video_variant_id", "video_variant_name", "view_average_request_latency", "view_average_request_throughput", "view_cdn_edge_pop", "view_cdn_origin", "view_drm_level", "view_drm_type", "view_dropped", "view_dropped_frame_count", "view_end", "view_error_id", "view_has_ad", "view_id", "view_max_downscale_percentage", "view_max_playhead_position", "view_max_request_latency", "view_max_upscale_percentage", "view_playing_time", "view_seek_count", "view_seek_duration", "view_session_id", "view_start", "view_total_content_playback_time", "view_total_downscaling", "view_total_upscaling", "viewer_application_engine", "viewer_application_name", "viewer_application_version", "viewer_connection_type", "viewer_device_category", "viewer_device_manufacturer", "viewer_device_model", "viewer_device_name", "viewer_experience_score", "viewer_os_architecture", "viewer_os_family", "viewer_os_version", "viewer_plan", "viewer_plan_status", "viewer_plan_category", "viewer_user_agent", "viewer_user_id", "watch_time", "watched", "weighted_average_bitrate", "playback_failure_error_type_id", "playback_business_exception_error_type_id", "video_startup_business_exception_error_type_id", "playback_failure", "ad_playback_failure_error_type_id", "view_content_startup_time", "ad_preroll_startup_time" ] }, "AbridgedVideoView": { "type": "object", "properties": { "id": { "type": "string" }, "viewer_os_family": { "type": "string", "nullable": true }, "viewer_application_name": { "type": "string", "nullable": true }, "video_title": { "type": "string", "nullable": true }, "total_row_count": { "type": "integer", "format": "int64" }, "player_error_message": { "type": "string", "nullable": true }, "player_error_code": { "type": "string", "nullable": true }, "error_type_id": { "type": "integer", "format": "int32", "nullable": true }, "country_code": { "type": "string", "nullable": true }, "view_start": { "type": "string" }, "view_end": { "type": "string" }, "viewer_experience_score": { "type": "number", "format": "float", "nullable": true }, "watch_time": { "type": "integer", "format": "int32", "nullable": true }, "playback_failure": { "type": "boolean" } }, "required": [ "id", "viewer_os_family", "viewer_application_name", "video_title", "total_row_count", "player_error_message", "player_error_code", "error_type_id", "country_code", "view_start", "view_end", "viewer_experience_score", "watch_time", "playback_failure" ] }, "VideoViewEvent": { "type": "object", "properties": { "viewer_time": { "type": "integer", "format": "int64" }, "playback_time": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "event_time": { "type": "integer", "format": "int64" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "viewer_time", "playback_time", "name", "event_time", "details" ] }, "Annotation": { "type": "object", "required": [ "id", "note", "date" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the annotation" }, "note": { "type": "string", "description": "The annotation note content" }, "date": { "type": "string", "format": "date-time", "description": "Datetime when the annotation applies" }, "sub_property_id": { "type": "string", "nullable": true, "description": "Customer-defined sub-property identifier" } } }, "AnnotationResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Annotation" } } }, "AnnotationInput": { "type": "object", "required": [ "note", "date" ], "properties": { "note": { "type": "string", "description": "The annotation note content" }, "date": { "type": "integer", "format": "int64", "description": "Datetime when the annotation applies (Unix timestamp)" }, "sub_property_id": { "type": "string", "description": "Customer-defined sub-property identifier" } } }, "ListAnnotationsResponse": { "type": "object", "required": [ "data", "total_row_count" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Annotation" } }, "total_row_count": { "type": "integer", "description": "Total number of annotations available" }, "timeframe": { "type": "array", "items": { "type": "integer" }, "minItems": 2, "maxItems": 2, "description": "Start and end unix timestamps for the data range" } } }, "GetEngagementHeatmapResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EngagementHeatmap" }, "total_row_count": { "type": "integer", "format": "int64", "nullable": true }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "required": [ "data", "timeframe", "total_row_count" ] }, "EngagementHeatmap": { "type": "object", "properties": { "heatmap": { "type": "array", "description": "Per-bucket engagement values across the content timeline, ordered from the start to the end of the content. The number of buckets is dynamic (between 10 and 1000) and scales with the content duration.", "items": { "type": "number", "format": "double" } }, "asset_id": { "type": "string", "description": "The asset ID for which the heatmap was calculated. Omitted if the heatmap is associated with a video_id or playback_id.", "nullable": true }, "playback_id": { "type": "string", "description": "The playback ID for which the heatmap was calculated. Omitted if the heatmap is associated with a video_id or asset_id.", "nullable": true }, "video_id": { "type": "string", "description": "The video ID for which the heatmap was calculated. Omitted if the heatmap is associated with a playback_id or asset_id.", "nullable": true } }, "required": [ "heatmap" ] }, "GetEngagementHotspotsResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EngagementHotspots" }, "total_row_count": { "type": "integer", "format": "int64", "nullable": true }, "timeframe": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "required": [ "data", "timeframe", "total_row_count" ] }, "EngagementHotspots": { "type": "object", "properties": { "hotspots": { "type": "array", "items": { "$ref": "#/components/schemas/Hotspot" } }, "asset_id": { "type": "string", "description": "The asset ID for which the hotspots were calculated. Omitted if the hotspots are associated with a video_id or playback_id.", "nullable": true }, "playback_id": { "type": "string", "description": "The playback ID for which the hotspots were calculated. Omitted if the hotspots are associated with a video_id or asset_id.", "nullable": true }, "video_id": { "type": "string", "description": "The video ID for which the hotspots were calculated. Omitted if the hotspots are associated with a playback_id or asset_id.", "nullable": true } }, "required": [ "hotspots" ] }, "Hotspot": { "type": "object", "properties": { "start_ms": { "type": "integer", "format": "int64", "description": "Start of the hotspot, in milliseconds from the beginning of the content." }, "end_ms": { "type": "integer", "format": "int64", "description": "End of the hotspot (exclusive), in milliseconds from the beginning of the content." }, "score": { "type": "number", "format": "double", "description": "Engagement score for the hotspot, between 0 and 1. Higher scores indicate more engaging moments; lower scores indicate less engaging moments (cold spots)." } }, "required": [ "start_ms", "end_ms", "score" ] }, "UsageExport": { "type": "object", "required": [ "date", "file_size", "download_url", "download_url_expires_at" ], "properties": { "date": { "type": "string", "format": "date", "description": "The calendar date this CSV covers, in `YYYY-MM-DD` format." }, "file_size": { "type": "integer", "nullable": true, "description": "Uncompressed size of the CSV file in bytes. May be `null` if the size is unavailable." }, "download_url": { "type": "string", "description": "A pre-signed URL to download the CSV. Valid until `download_url_expires_at`." }, "download_url_expires_at": { "type": "integer", "description": "Unix timestamp (seconds since epoch) at which `download_url` expires." } } }, "UsageExportsMeta": { "type": "object", "required": [ "page", "pages", "limit", "total" ], "properties": { "page": { "type": "integer", "description": "Current page number (1-based)." }, "pages": { "type": "integer", "description": "Total number of pages." }, "limit": { "type": "integer", "description": "Maximum number of items per page." }, "total": { "type": "integer", "description": "Total number of available export files matching the query." } } }, "ListUsageExportsResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UsageExport" } }, "meta": { "$ref": "#/components/schemas/UsageExportsMeta" } } }, "SystemErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "messages" ], "properties": { "type": { "type": "string", "description": "The type of the error" }, "messages": { "type": "array", "items": { "type": "string" }, "description": "Friendly messages of errors encountered" } } } } }, "Webhook": { "type": "object", "required": [ "id", "address", "enabled", "created_at" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the webhook." }, "address": { "type": "string", "description": "The URL where Mux sends webhook notifications." }, "enabled": { "type": "boolean", "description": "Whether Mux attempts to deliver notifications to this webhook." }, "created_at": { "type": "string", "format": "date-time", "description": "Time at which the webhook was created, as an ISO 8601 UTC datetime." }, "signing_secret": { "type": "string", "description": "Secret used to verify that webhook payloads were sent by Mux. **Note that this value is only returned once when creating a webhook.**" } } }, "ListWebhooksResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "total_row_count": { "type": "integer", "format": "int64", "description": "Total number of webhooks in the environment (not the number of items on this page)." }, "page": { "type": "integer", "format": "int32", "description": "The current page number." }, "limit": { "type": "integer", "format": "int32", "description": "The maximum number of items per page." } } }, "WebhookResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Webhook" } } }, "CreateWebhookRequest": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string", "description": "The URL where Mux should send webhook notifications. Must be unique among the environment's webhooks." } } }, "UpdateWebhookRequest": { "type": "object", "properties": { "address": { "type": "string", "description": "The URL where Mux should send webhook notifications. Must be unique among the environment's webhooks." }, "enabled": { "type": "boolean", "description": "Whether Mux attempts to deliver notifications to this webhook." } } }, "WhoAmIResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "permissions", "organization_name", "organization_id", "environment_type", "environment_name", "environment_id", "access_token_name" ], "properties": { "permissions": { "type": "array", "items": { "type": "string" } }, "organization_name": { "type": "string" }, "organization_id": { "type": "string" }, "environment_type": { "type": "string" }, "environment_name": { "type": "string" }, "environment_id": { "type": "string" }, "access_token_name": { "type": "string" } } } } }, "ActionOnFlagged": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "delete_playback_ids" ], "description": "Action to take when exceeds_threshold is true. \"delete_playback_ids\" deletes every playback ID on the asset, making it unplayable while preserving the underlying asset so it can be re-published or reviewed." } }, "required": [ "action" ], "description": "Optional action taken automatically when exceeds_threshold is true. When omitted, the job only reports scores and takes no action. Note: in a directive run that targets the same asset with other workflows, deleting playback IDs can break sibling workflows that need a playback ID.", "example": { "action": "delete_playback_ids" } }, "AskQuestionsBinding": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Customer-chosen identifier, unique within the directive. Resource `source.binding` refs point at this handle." }, "workflow": { "type": "string", "enum": [ "ask-questions" ], "description": "The Robots workflow to dispatch — the same identifier as POST /jobs/{workflow}.", "x-stainless-const": true }, "inputs": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "reference_ids of declared resources this workflow depends on. Each entry is a hard dependency: the workflow is not dispatched until the referenced resource is ready." }, "params": { "$ref": "#/components/schemas/AskQuestionsBindingParameters" } }, "required": [ "reference_id", "workflow", "params" ], "title": "AskQuestionsBinding" }, "AskQuestionsBindingParameters": { "type": "object", "properties": { "questions": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string", "minLength": 1, "maxLength": 600, "description": "The question to ask about the video content. Maximum 600 characters." }, "answer_options": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 150 }, "minItems": 1, "description": "Allowed answer values for this question. Defaults to [\"yes\", \"no\"] when omitted and free_form_reply is not true. Mutually exclusive with free_form_reply. Each option is a short label of at most 150 characters." }, "free_form_reply": { "type": "boolean", "description": "When true, the model replies with free-form prose instead of selecting from answer_options. Mutually exclusive with answer_options. Treat the answer as untrusted model output." } }, "required": [ "question" ] }, "minItems": 1, "maxItems": 50, "description": "One or more questions to ask about the video, up to 50. Each question can either select from answer_options (defaults to yes/no) or, by setting free_form_reply: true, receive a free-form prose answer." }, "language_code": { "type": "string", "minLength": 1, "description": "BCP 47 language code of the caption track to analyze (e.g. \"en\", \"fr\"). When omitted, the SDK uses the default track." }, "max_free_form_answer_length": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 500, "description": "Max character length for free-form answers, between 1 and 1000. Ignored unless at least one question sets free_form_reply: true." }, "output_steering": { "$ref": "#/components/schemas/AskQuestionsOutputSteering" } }, "required": [ "questions" ], "description": "Parameters for the ask-questions workflow — the same fields accepted by POST /jobs/ask-questions, minus engine-supplied fields such as asset_id." }, "AskQuestionsJob": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique job identifier." }, "passthrough": { "type": "string", "description": "Arbitrary string supplied at creation, returned as-is." }, "units_consumed": { "type": "integer", "minimum": 0, "description": "Number of Mux AI units consumed by this job." }, "directive": { "$ref": "#/components/schemas/JobDirectiveContext" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) when the job was created." }, "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state)." }, "workflow": { "type": "string", "enum": [ "ask-questions" ] }, "parameters": { "$ref": "#/components/schemas/AskQuestionsJobParameters" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JobError" }, "description": "Error details. Present when status is 'errored'." }, "resources": { "$ref": "#/components/schemas/Resources" }, "outputs": { "$ref": "#/components/schemas/AskQuestionsJobOutputs" } }, "required": [ "id", "units_consumed", "created_at", "updated_at", "workflow", "parameters", "status" ] }, "AskQuestionsJobOutputs": { "type": "object", "properties": { "answers": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string", "minLength": 1, "description": "The original question that was asked." }, "answer": { "type": [ "string", "null" ], "minLength": 1, "description": "For enum questions, constrained to one of the provided answer_options. For free-form questions, responds with prose up to max_free_form_answer_length characters - treat as untrusted model output. Null when the question was skipped." }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Confidence score from 0.0 to 1.0. Values above 0.9 indicate clear, unambiguous evidence; 0.7-0.9 strong evidence with minor ambiguity; 0.5-0.7 moderate evidence; below 0.5 weak or uncertain evidence. Always 0 when skipped." }, "reasoning": { "type": "string", "minLength": 1, "description": "Explanation citing specific visual or audio evidence from the video, or why the question was skipped." }, "skipped": { "type": "boolean", "description": "Whether the question was skipped due to irrelevance to the video content." } }, "required": [ "question", "answer", "confidence", "reasoning", "skipped" ] }, "minItems": 1, "description": "One answer per question, in the same order as the input questions." } }, "required": [ "answers" ], "example": { "answers": [ { "question": "Is this video about glasses?", "answer": "no", "confidence": 0.92, "reasoning": "No glasses appear on screen and the narration does not mention eyewear.", "skipped": false }, { "question": "What is the primary subject?", "answer": "watches", "confidence": 0.88, "reasoning": "Multiple wristwatches are featured prominently throughout the video.", "skipped": false }, { "question": "Describe the primary subject in one sentence.", "answer": "A close-up showcase of luxury wristwatches arranged on a wooden display.", "confidence": 0.86, "reasoning": "Visual evidence shows several wristwatches displayed against a wooden backdrop with no other competing subjects.", "skipped": false } ] }, "description": "Workflow results. Present when status is 'completed'." }, "AskQuestionsJobParameters": { "type": "object", "properties": { "asset_id": { "type": "string", "minLength": 1, "description": "The Mux asset ID of the video to analyze." }, "questions": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string", "minLength": 1, "maxLength": 600, "description": "The question to ask about the video content. Maximum 600 characters." }, "answer_options": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 150 }, "minItems": 1, "description": "Allowed answer values for this question. Defaults to [\"yes\", \"no\"] when omitted and free_form_reply is not true. Mutually exclusive with free_form_reply. Each option is a short label of at most 150 characters." }, "free_form_reply": { "type": "boolean", "description": "When true, the model replies with free-form prose instead of selecting from answer_options. Mutually exclusive with answer_options. Treat the answer as untrusted model output." } }, "required": [ "question" ] }, "minItems": 1, "maxItems": 50, "description": "One or more questions to ask about the video, up to 50. Each question can either select from answer_options (defaults to yes/no) or, by setting free_form_reply: true, receive a free-form prose answer." }, "language_code": { "type": "string", "minLength": 1, "description": "BCP 47 language code of the caption track to analyze (e.g. \"en\", \"fr\"). When omitted, the SDK uses the default track." }, "max_free_form_answer_length": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 500, "description": "Max character length for free-form answers, between 1 and 1000. Ignored unless at least one question sets free_form_reply: true." }, "output_steering": { "$ref": "#/components/schemas/AskQuestionsOutputSteering" } }, "required": [ "asset_id", "questions" ], "example": { "asset_id": "mux_asset_123abc", "questions": [ { "question": "Is this video about glasses?" }, { "question": "What is the primary subject?", "answer_options": [ "glasses", "watches", "shoes", "hats" ] }, { "question": "Describe the primary subject in one sentence.", "free_form_reply": true } ], "max_free_form_answer_length": 300, "output_steering": { "scope": { "start_time": 30, "end_time": 180 } } } }, "AskQuestionsJobResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AskQuestionsJob" } }, "required": [ "data" ] }, "AskQuestionsOutputSteering": { "type": "object", "properties": { "scope": { "allOf": [ { "$ref": "#/components/schemas/OutputSteeringScope" }, { "description": "Optional execution window in seconds on the original asset timeline. Omit start_time to begin at the asset start and omit end_time to continue through the asset end. Answers are generated only from media within this window, while returned timestamps remain absolute asset timestamps." } ] } }, "description": "Curated controls that optionally restrict question answering to an asset time range." }, "CancelJobResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/JobSummary" } }, "required": [ "data" ] }, "ChapterGranularity": { "type": "string", "enum": [ "coarse", "balanced", "fine" ], "description": "Best-effort guidance for how coarse or fine chapter boundaries should be." }, "ChapterStyle": { "type": "string", "enum": [ "descriptive", "punchy", "educational", "seo", "platform_neutral" ], "description": "Best-effort style guidance for generated chapter titles." }, "CreateAskQuestionsJobRequest": { "type": "object", "properties": { "passthrough": { "type": "string", "description": "Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems." }, "parameters": { "$ref": "#/components/schemas/AskQuestionsJobParameters" } }, "required": [ "parameters" ] }, "CreateDirectiveRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Human-readable directive name." }, "subject": { "$ref": "#/components/schemas/DirectiveSubject" }, "resources": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/TrackResourceDeclaration" }, { "$ref": "#/components/schemas/ShotsResourceDeclaration" } ], "discriminator": { "propertyName": "type", "mapping": { "video.asset.track": "#/components/schemas/TrackResourceDeclaration", "video.asset.shots": "#/components/schemas/ShotsResourceDeclaration" } } }, "maxItems": 50, "description": "Resources the engine ensures on the asset before dependent workflows run. May be omitted for workflows-only directives." }, "workflows": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowBinding" }, "minItems": 1, "maxItems": 150, "description": "The Robots workflows to dispatch on each run." } }, "required": [ "name", "subject", "workflows" ], "example": { "name": "Generate captions, then translate", "subject": { "type": "video.asset" }, "resources": [ { "reference_id": "captions_en", "type": "video.asset.track", "kind": "caption", "language": "en", "source": { "via": "workflow", "binding": "premium_captions" } } ], "workflows": [ { "reference_id": "premium_captions", "workflow": "generate-premium-captions", "params": { "language_code": "en" } }, { "reference_id": "translate_es", "workflow": "translate-captions", "inputs": [ "captions_en" ], "params": { "to_language_code": "es" } } ] } }, "CreateEditCaptionsJobRequest": { "type": "object", "properties": { "passthrough": { "type": "string", "description": "Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems." }, "parameters": { "$ref": "#/components/schemas/EditCaptionsJobParameters" } }, "required": [ "parameters" ] }, "CreateFindBestThumbnailsJobRequest": { "type": "object", "properties": { "passthrough": { "type": "string", "description": "Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems." }, "parameters": { "$ref": "#/components/schemas/FindBestThumbnailsJobParameters" } }, "required": [ "parameters" ] }, "CreateFindKeyMomentsJobRequest": { "type": "object", "properties": { "passthrough": { "type": "string", "description": "Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems." }, "parameters": { "$ref": "#/components/schemas/FindKeyMomentsJobParameters" } }, "required": [ "parameters" ] }, "CreateFindScenesJobRequest": { "type": "object", "properties": { "passthrough": { "type": "string", "description": "Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems." }, "parameters": { "$ref": "#/components/schemas/FindScenesJobParameters" } }, "required": [ "parameters" ] }, "CreateGenerateChaptersJobRequest": { "type": "object", "properties": { "passthrough": { "type": "string", "description": "Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems." }, "parameters": { "$ref": "#/components/schemas/GenerateChaptersJobParameters" } }, "required": [ "parameters" ] }, "CreateGenerateEngagementInsightsJobRequest": { "type": "object", "properties": { "passthrough": { "type": "string", "description": "Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems." }, "parameters": { "$ref": "#/components/schemas/GenerateEngagementInsightsJobParameters" } }, "required": [ "parameters" ] }, "CreateGeneratePremiumCaptionsJobRequest": { "type": "object", "properties": { "passthrough": { "type": "string", "description": "Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems." }, "parameters": { "$ref": "#/components/schemas/GeneratePremiumCaptionsJobParameters" } }, "required": [ "parameters" ] }, "CreateModerateJobRequest": { "type": "object", "properties": { "passthrough": { "type": "string", "description": "Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems." }, "parameters": { "$ref": "#/components/schemas/ModerateJobParameters" } }, "required": [ "parameters" ] }, "CreateSummarizeJobRequest": { "type": "object", "properties": { "passthrough": { "type": "string", "description": "Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems." }, "parameters": { "$ref": "#/components/schemas/SummarizeJobParameters" } }, "required": [ "parameters" ] }, "CreateTranslateAudioJobRequest": { "type": "object", "properties": { "passthrough": { "type": "string", "description": "Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems." }, "parameters": { "$ref": "#/components/schemas/TranslateAudioJobParameters" } }, "required": [ "parameters" ] }, "CreateTranslateCaptionsJobRequest": { "type": "object", "properties": { "passthrough": { "type": "string", "description": "Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems." }, "parameters": { "$ref": "#/components/schemas/TranslateCaptionsJobParameters" } }, "required": [ "parameters" ] }, "Directive": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable directive identifier (drv_...)." }, "name": { "type": "string", "description": "Human-readable directive name." }, "subject": { "$ref": "#/components/schemas/DirectiveSubject" }, "resources": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/TrackResourceDeclaration" }, { "$ref": "#/components/schemas/ShotsResourceDeclaration" } ], "discriminator": { "propertyName": "type", "mapping": { "video.asset.track": "#/components/schemas/TrackResourceDeclaration", "video.asset.shots": "#/components/schemas/ShotsResourceDeclaration" } } }, "description": "Resource declarations." }, "workflows": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowBinding" }, "description": "Workflow bindings." }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) when the directive was created." }, "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) when the directive was last updated." } }, "required": [ "id", "name", "subject", "resources", "workflows", "created_at", "updated_at" ] }, "DirectiveListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Directive" } }, "total_row_count": { "type": "integer", "minimum": 0, "description": "Total number of directives matching the query, across all pages.", "example": 42 } }, "required": [ "data", "total_row_count" ] }, "DirectiveResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Directive" } }, "required": [ "data" ] }, "DirectiveRun": { "type": "object", "properties": { "run_id": { "type": "string", "description": "Unique run identifier (drvrun_...)." }, "subject_id": { "type": "string", "description": "The bare Mux asset ID the directive is running against." }, "status": { "type": "string", "enum": [ "pending" ], "description": "The run has been queued." } }, "required": [ "run_id", "subject_id", "status" ] }, "DirectiveRunDetail": { "type": "object", "properties": { "run_id": { "type": "string", "description": "Unique run identifier (drvrun_...)." }, "subject_id": { "type": "string", "description": "The bare Mux asset ID this run targeted." }, "status": { "type": "string", "enum": [ "pending", "dispatching", "running", "waiting", "completed", "partial", "errored" ], "description": "Current run status." }, "node_states": { "type": "array", "items": { "$ref": "#/components/schemas/NodeState" }, "maxItems": 150, "description": "Per-binding status entries, one per binding, in the order the bindings appear in `directive.workflows[]`." }, "started_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) when the run started." }, "completed_at": { "type": [ "integer", "null" ], "minimum": 0, "description": "Unix timestamp (seconds) when the run reached terminal state. Null if still in progress." } }, "required": [ "run_id", "subject_id", "status", "node_states", "started_at", "completed_at" ] }, "DirectiveRunDetailResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DirectiveRunDetail" } }, "required": [ "data" ] }, "DirectiveRunListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DirectiveRunDetail" } }, "total_row_count": { "type": "integer", "minimum": 0, "description": "Total number of runs for this directive (within the 30-day retention window).", "example": 42 } }, "required": [ "data", "total_row_count" ] }, "DirectiveRunResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DirectiveRun" } }, "required": [ "data" ] }, "DirectiveSubject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "video.asset", "video.live_stream" ], "description": "The entity type each run targets. V1 accepts \"video.asset\" only; \"video.live_stream\" is reserved and rejected at save time." } }, "required": [ "type" ] }, "EditCaptionsBinding": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Customer-chosen identifier, unique within the directive. Resource `source.binding` refs point at this handle." }, "workflow": { "type": "string", "enum": [ "edit-captions" ], "description": "The Robots workflow to dispatch — the same identifier as POST /jobs/{workflow}.", "x-stainless-const": true }, "inputs": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "reference_ids of declared resources this workflow depends on. Each entry is a hard dependency: the workflow is not dispatched until the referenced resource is ready." }, "params": { "$ref": "#/components/schemas/EditCaptionsBindingParameters" } }, "required": [ "reference_id", "workflow" ], "title": "EditCaptionsBinding" }, "EditCaptionsBindingParameters": { "type": "object", "properties": { "auto_censor_profanity": { "type": "object", "properties": { "detection_method": { "type": "string", "enum": [ "llm" ], "default": "llm", "description": "How profanity is detected. Currently only `llm` is supported, which uses an LLM to identify profanity in cue text." }, "mode": { "type": "string", "enum": [ "blank", "remove", "mask" ], "default": "blank", "description": "Replacement strategy for detected profanity: blank inserts bracketed underscores, remove drops the match, and mask replaces characters with question marks. Defaults to \"blank\"." }, "always_censor": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Additional words or short phrases that should always be censored even if the model does not detect them." }, "never_censor": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Words or short phrases that should never be censored even if the model flags them." } }, "description": "Optional LLM-driven profanity detection and censorship rules applied to the selected caption track." }, "replacements": { "type": "array", "items": { "type": "object", "properties": { "find": { "type": "string", "minLength": 1, "description": "Exact word or phrase to replace in cue text." }, "replace": { "type": "string", "description": "Replacement text to insert when a match is found." }, "case_sensitive": { "type": "boolean", "default": false, "description": "When true, `find` is matched only with exact case. Defaults to false (case-insensitive matching), so \"gonna\" also matches \"Gonna\" and \"GONNA\"." } }, "required": [ "find", "replace" ] }, "description": "Optional static word or phrase replacements applied directly to cue text." }, "speaker_replacements": { "type": "array", "items": { "$ref": "#/components/schemas/EditCaptionsSpeakerReplacement" }, "description": "Optional replacements for bracketed speaker labels at the start of caption cues. Values omit the surrounding square brackets, and matching spoken text is not changed." }, "upload_to_mux": { "type": "boolean", "default": true, "description": "Whether to upload the edited VTT back to the Mux asset as a text track. Defaults to true." }, "replace_existing_tracks": { "$ref": "#/components/schemas/EditCaptionsReplaceExistingTracks" }, "track_name": { "type": "string", "minLength": 1, "description": "Name for the edited Mux text track. Defaults to the source track's name. Required and must differ from the source's name when `replace_existing_tracks` is `fail`. Mux requires text track names to be unique on an asset." }, "delete_original_track": { "type": "boolean", "description": "Deprecated: use `replace_existing_tracks`. When set, the previous behavior applies: the edited track is added as ` ()`, then the source is deleted if this is true. Cannot be combined with `replace_existing_tracks` or `track_name`.", "deprecated": true, "x-stainless-deprecation-message": "Use `replace_existing_tracks` instead." }, "track_name_suffix": { "type": "string", "minLength": 1, "description": "Deprecated: use `track_name`. Selects the previous naming scheme, appending this suffix to the source track's name (default \"edited\"). Cannot be combined with `replace_existing_tracks` or `track_name`.", "deprecated": true, "x-stainless-deprecation-message": "Use `track_name` instead." } }, "description": "Parameters for the edit-captions workflow — the same fields accepted by POST /jobs/edit-captions, minus engine-supplied fields such as asset_id." }, "EditCaptionsJob": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique job identifier." }, "passthrough": { "type": "string", "description": "Arbitrary string supplied at creation, returned as-is." }, "units_consumed": { "type": "integer", "minimum": 0, "description": "Number of Mux AI units consumed by this job." }, "directive": { "$ref": "#/components/schemas/JobDirectiveContext" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) when the job was created." }, "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state)." }, "workflow": { "type": "string", "enum": [ "edit-captions" ] }, "parameters": { "$ref": "#/components/schemas/EditCaptionsJobParameters" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JobError" }, "description": "Error details. Present when status is 'errored'." }, "resources": { "$ref": "#/components/schemas/Resources" }, "outputs": { "$ref": "#/components/schemas/EditCaptionsJobOutputs" } }, "required": [ "id", "units_consumed", "created_at", "updated_at", "workflow", "parameters", "status" ] }, "EditCaptionsJobOutputs": { "type": "object", "properties": { "total_replacement_count": { "type": "integer", "minimum": 0, "description": "Total count of cue text replacements applied across all edit operations." }, "uploaded_track_id": { "type": "string", "minLength": 1, "description": "Mux text track ID for the uploaded edited captions. Present when upload_to_mux is true and the upload succeeds." }, "temporary_vtt_url": { "type": "string", "minLength": 1, "description": "Temporary pre-signed URL for downloading the edited VTT file. Expires 7 days after the job completes." }, "replaced_tracks": { "$ref": "#/components/schemas/ReplacedTracks" } }, "required": [ "total_replacement_count" ], "example": { "total_replacement_count": 5, "uploaded_track_id": "text_track_789ghi", "temporary_vtt_url": "https://s3.example.com/edited.vtt?sig=abc" }, "description": "Workflow results. Present when status is 'completed'." }, "EditCaptionsJobParameters": { "type": "object", "properties": { "asset_id": { "type": "string", "minLength": 1, "description": "The Mux asset ID whose existing text track should be edited." }, "track_id": { "type": "string", "minLength": 1, "description": "The existing ready Mux text track ID to edit and optionally replace." }, "auto_censor_profanity": { "type": "object", "properties": { "detection_method": { "type": "string", "enum": [ "llm" ], "default": "llm", "description": "How profanity is detected. Currently only `llm` is supported, which uses an LLM to identify profanity in cue text." }, "mode": { "type": "string", "enum": [ "blank", "remove", "mask" ], "default": "blank", "description": "Replacement strategy for detected profanity: blank inserts bracketed underscores, remove drops the match, and mask replaces characters with question marks. Defaults to \"blank\"." }, "always_censor": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Additional words or short phrases that should always be censored even if the model does not detect them." }, "never_censor": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Words or short phrases that should never be censored even if the model flags them." } }, "description": "Optional LLM-driven profanity detection and censorship rules applied to the selected caption track." }, "replacements": { "type": "array", "items": { "type": "object", "properties": { "find": { "type": "string", "minLength": 1, "description": "Exact word or phrase to replace in cue text." }, "replace": { "type": "string", "description": "Replacement text to insert when a match is found." }, "case_sensitive": { "type": "boolean", "default": false, "description": "When true, `find` is matched only with exact case. Defaults to false (case-insensitive matching), so \"gonna\" also matches \"Gonna\" and \"GONNA\"." } }, "required": [ "find", "replace" ] }, "description": "Optional static word or phrase replacements applied directly to cue text." }, "speaker_replacements": { "type": "array", "items": { "$ref": "#/components/schemas/EditCaptionsSpeakerReplacement" }, "description": "Optional replacements for bracketed speaker labels at the start of caption cues. Values omit the surrounding square brackets, and matching spoken text is not changed." }, "upload_to_mux": { "type": "boolean", "default": true, "description": "Whether to upload the edited VTT back to the Mux asset as a text track. Defaults to true." }, "replace_existing_tracks": { "$ref": "#/components/schemas/EditCaptionsReplaceExistingTracks" }, "track_name": { "type": "string", "minLength": 1, "description": "Name for the edited Mux text track. Defaults to the source track's name. Required and must differ from the source's name when `replace_existing_tracks` is `fail`. Mux requires text track names to be unique on an asset." }, "delete_original_track": { "type": "boolean", "description": "Deprecated: use `replace_existing_tracks`. When set, the previous behavior applies: the edited track is added as ` ()`, then the source is deleted if this is true. Cannot be combined with `replace_existing_tracks` or `track_name`.", "deprecated": true, "x-stainless-deprecation-message": "Use `replace_existing_tracks` instead." }, "track_name_suffix": { "type": "string", "minLength": 1, "description": "Deprecated: use `track_name`. Selects the previous naming scheme, appending this suffix to the source track's name (default \"edited\"). Cannot be combined with `replace_existing_tracks` or `track_name`.", "deprecated": true, "x-stainless-deprecation-message": "Use `track_name` instead." } }, "required": [ "asset_id", "track_id" ], "example": { "asset_id": "mux_asset_123abc", "track_id": "text_track_456def", "replacements": [ { "find": "Mucks", "replace": "Mux", "case_sensitive": true }, { "find": "gonna", "replace": "going to" } ], "speaker_replacements": [ { "find": "speaker_0", "replace": "Alice" } ], "upload_to_mux": true, "replace_existing_tracks": "replace" } }, "EditCaptionsJobResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EditCaptionsJob" } }, "required": [ "data" ] }, "EditCaptionsReplaceExistingTracks": { "type": "string", "enum": [ "replace", "fail" ], "description": "What to do with the source track. Defaults to `replace`: the source is deleted and the edited track takes its place under the same name, language and closed-captions setting; no other track is touched, and the source is restored if the edited track can't be added. `fail` deletes nothing and adds the edited track alongside the source, so it requires a `track_name` different from the source's. Either way the request is rejected if a track other than the source already has the edited track's name. `replace` requires `upload_to_mux` to be true." }, "EditCaptionsSpeakerReplacement": { "type": "object", "properties": { "find": { "type": "string", "minLength": 1, "description": "Existing speaker label without the surrounding square brackets." }, "replace": { "type": "string", "minLength": 1, "description": "New speaker label without the surrounding square brackets." } }, "required": [ "find", "replace" ] }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Machine-readable error type." }, "message": { "type": "string", "description": "Human-readable error message describing what went wrong." } }, "required": [ "type", "message" ] } }, "required": [ "error" ] }, "FindBestThumbnailsBinding": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Customer-chosen identifier, unique within the directive. Resource `source.binding` refs point at this handle." }, "workflow": { "type": "string", "enum": [ "find-best-thumbnails" ], "description": "The Robots workflow to dispatch — the same identifier as POST /jobs/{workflow}.", "x-stainless-const": true }, "inputs": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "reference_ids of declared resources this workflow depends on. Each entry is a hard dependency: the workflow is not dispatched until the referenced resource is ready." }, "params": { "$ref": "#/components/schemas/FindBestThumbnailsBindingParameters" } }, "required": [ "reference_id", "workflow" ], "title": "FindBestThumbnailsBinding" }, "FindBestThumbnailsBindingParameters": { "type": "object", "properties": { "max_thumbnails": { "type": "integer", "minimum": 1, "maximum": 5, "description": "Maximum number of candidate thumbnails to return (1-5). Defaults to 1." }, "output_steering": { "$ref": "#/components/schemas/FindBestThumbnailsOutputSteering" }, "update_asset_thumbnail": { "type": "boolean", "description": "When true, the highest-scoring thumbnail's timestamp is written to the Mux asset's thumbnail_time once the job completes, making that frame the asset's default poster image. The new thumbnail will appear for some clients sooner than others, depending on local cache settings." } }, "description": "Parameters for the find-best-thumbnails workflow — the same fields accepted by POST /jobs/find-best-thumbnails, minus engine-supplied fields such as asset_id." }, "FindBestThumbnailsJob": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique job identifier." }, "passthrough": { "type": "string", "description": "Arbitrary string supplied at creation, returned as-is." }, "units_consumed": { "type": "integer", "minimum": 0, "description": "Number of Mux AI units consumed by this job." }, "directive": { "$ref": "#/components/schemas/JobDirectiveContext" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) when the job was created." }, "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state)." }, "workflow": { "type": "string", "enum": [ "find-best-thumbnails" ] }, "parameters": { "$ref": "#/components/schemas/FindBestThumbnailsJobParameters" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JobError" }, "description": "Error details. Present when status is 'errored'." }, "resources": { "$ref": "#/components/schemas/Resources" }, "outputs": { "$ref": "#/components/schemas/FindBestThumbnailsJobOutputs" } }, "required": [ "id", "units_consumed", "created_at", "updated_at", "workflow", "parameters", "status" ] }, "FindBestThumbnailsJobOutputs": { "type": "object", "properties": { "best_thumbnails": { "type": "array", "items": { "type": "object", "properties": { "timestamp_ms": { "type": "integer", "minimum": 0, "description": "Absolute frame timestamp in whole milliseconds on the original asset timeline." }, "subscores": { "type": "object", "properties": { "focus": { "type": "number", "minimum": 0, "maximum": 1, "description": "Sharpness and focus quality score (0-1)." }, "face_or_action": { "type": "number", "minimum": 0, "maximum": 1, "description": "Presence of faces or dynamic action score (0-1)." }, "composition": { "type": "number", "minimum": 0, "maximum": 1, "description": "Visual composition and framing quality score (0-1)." }, "contrast_color": { "type": "number", "minimum": 0, "maximum": 1, "description": "Color contrast and vibrancy score (0-1)." }, "brand_fit": { "type": "number", "minimum": 0, "maximum": 1, "description": "Alignment with brand guidelines score (0-1)." } }, "required": [ "focus", "face_or_action", "composition", "contrast_color", "brand_fit" ], "description": "Per-category quality scores." }, "overall": { "type": "number", "minimum": 0, "maximum": 1, "description": "Overall quality score from 0 to 1." }, "description": { "type": "string", "description": "AI-generated description of the frame content." }, "alt_text": { "type": "string", "minLength": 1, "maxLength": 250, "description": "Suggested alternative text for the candidate thumbnail image, suitable for use with the thumbnail URL in an accessible UI." } }, "required": [ "timestamp_ms", "subscores", "overall", "description" ] }, "description": "Selected candidate thumbnails from the original asset timeline, ordered best to worst by overall quality score." } }, "required": [ "best_thumbnails" ], "description": "Workflow results. Present when status is 'completed'." }, "FindBestThumbnailsJobParameters": { "type": "object", "properties": { "asset_id": { "type": "string", "description": "Mux asset ID." }, "max_thumbnails": { "type": "integer", "minimum": 1, "maximum": 5, "description": "Maximum number of candidate thumbnails to return (1-5). Defaults to 1." }, "output_steering": { "$ref": "#/components/schemas/FindBestThumbnailsOutputSteering" }, "update_asset_thumbnail": { "type": "boolean", "description": "When true, the highest-scoring thumbnail's timestamp is written to the Mux asset's thumbnail_time once the job completes, making that frame the asset's default poster image. The new thumbnail will appear for some clients sooner than others, depending on local cache settings." } }, "required": [ "asset_id" ], "example": { "asset_id": "mux_asset_123abc", "max_thumbnails": 3, "update_asset_thumbnail": true, "output_steering": { "scope": { "start_time": 30, "end_time": 180 }, "selection_strategy": "campaign_thumbnail", "scoring_priorities": [ "composition", "brand_fit" ] } } }, "FindBestThumbnailsJobResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FindBestThumbnailsJob" } }, "required": [ "data" ] }, "FindBestThumbnailsOutputSteering": { "type": "object", "properties": { "scope": { "allOf": [ { "$ref": "#/components/schemas/OutputSteeringScope" }, { "description": "Optional sampling window in seconds on the original asset timeline, normalized inward to whole-millisecond half-open bounds. The range must contain a video frame at the asset frame rate. Omit start_time to begin at the asset start and omit end_time to continue through the asset end. Returned thumbnail timestamps remain absolute asset timestamps." } ] }, "selection_strategy": { "$ref": "#/components/schemas/FindBestThumbnailsSelectionStrategy" }, "looking_for": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Open-ended description of what the user is explicitly looking for in candidate thumbnails. Best-effort guidance only." }, "audience": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Intended audience used as best-effort scoring guidance. Does not change the output schema." }, "campaign_style": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Short description of the campaign/channel thumbnail style to prefer when supported by the frame." }, "scoring_priorities": { "type": "array", "items": { "$ref": "#/components/schemas/FindBestThumbnailsScoringPriority" }, "minItems": 1, "maxItems": 5, "description": "Rubric criteria to emphasize in close calls. Best-effort guidance only." } }, "description": "Curated output_steering controls for execution scope, thumbnail scoring strategy, explicit user intent, audience, campaign style, and scoring priorities. Scope is enforced; other controls guide model behavior but do not guarantee exact output." }, "FindBestThumbnailsScoringPriority": { "type": "string", "enum": [ "focus", "face_or_action", "composition", "contrast_color", "brand_fit" ] }, "FindBestThumbnailsSelectionStrategy": { "type": "string", "enum": [ "face_or_action", "clean_composition", "high_contrast", "brand_safe", "campaign_thumbnail" ], "description": "Best-effort guidance for what kind of thumbnail candidate should score highest." }, "FindKeyMomentsBinding": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Customer-chosen identifier, unique within the directive. Resource `source.binding` refs point at this handle." }, "workflow": { "type": "string", "enum": [ "find-key-moments" ], "description": "The Robots workflow to dispatch — the same identifier as POST /jobs/{workflow}.", "x-stainless-const": true }, "inputs": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "reference_ids of declared resources this workflow depends on. Each entry is a hard dependency: the workflow is not dispatched until the referenced resource is ready." }, "params": { "$ref": "#/components/schemas/FindKeyMomentsBindingParameters" } }, "required": [ "reference_id", "workflow" ], "title": "FindKeyMomentsBinding" }, "FindKeyMomentsBindingParameters": { "type": "object", "properties": { "max_moments": { "type": "integer", "minimum": 1, "maximum": 25, "description": "Maximum number of key moments to extract. When omitted, defaults to 10 for assets up to one hour and 25 for longer assets." }, "target_duration_ms": { "type": "object", "properties": { "min": { "type": "integer", "exclusiveMinimum": 0, "description": "Preferred minimum highlight duration in milliseconds." }, "max": { "type": "integer", "exclusiveMinimum": 0, "description": "Preferred maximum highlight duration in milliseconds." } }, "required": [ "min", "max" ], "description": "Preferred highlight duration range in milliseconds. When provided, the model will aim to select moments within this range." }, "use_shots": { "type": "boolean", "description": "Controls whether video assets are analyzed using Mux shots. When true, shots are generated or reused and visual evidence drives selection. When false or omitted, selection uses transcript evidence and the asset must have a caption track. Not supported for audio-only assets." }, "output_steering": { "$ref": "#/components/schemas/FindKeyMomentsOutputSteering" } }, "description": "Parameters for the find-key-moments workflow — the same fields accepted by POST /jobs/find-key-moments, minus engine-supplied fields such as asset_id." }, "FindKeyMomentsJob": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique job identifier." }, "passthrough": { "type": "string", "description": "Arbitrary string supplied at creation, returned as-is." }, "units_consumed": { "type": "integer", "minimum": 0, "description": "Number of Mux AI units consumed by this job." }, "directive": { "$ref": "#/components/schemas/JobDirectiveContext" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) when the job was created." }, "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state)." }, "workflow": { "type": "string", "enum": [ "find-key-moments" ] }, "parameters": { "$ref": "#/components/schemas/FindKeyMomentsJobParameters" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JobError" }, "description": "Error details. Present when status is 'errored'." }, "resources": { "$ref": "#/components/schemas/Resources" }, "outputs": { "$ref": "#/components/schemas/FindKeyMomentsJobOutputs" } }, "required": [ "id", "units_consumed", "created_at", "updated_at", "workflow", "parameters", "status" ] }, "FindKeyMomentsJobOutputs": { "type": "object", "properties": { "moments": { "type": "array", "items": { "type": "object", "properties": { "start_ms": { "type": "number", "minimum": 0, "description": "Moment start time in milliseconds." }, "end_ms": { "type": "number", "minimum": 0, "description": "Moment end time in milliseconds." }, "cues": { "type": "array", "items": { "type": "object", "properties": { "start_ms": { "type": "number", "minimum": 0, "description": "Cue start time in milliseconds." }, "end_ms": { "type": "number", "minimum": 0, "description": "Cue end time in milliseconds." }, "text": { "type": "string", "minLength": 1, "description": "Transcript text for this cue." } }, "required": [ "start_ms", "end_ms", "text" ] }, "description": "Contiguous transcript segments that comprise this moment. Empty when video selection identifies the moment without transcript evidence." }, "overall_score": { "type": "number", "minimum": 0, "maximum": 1, "description": "Weighted quality score from 0.0 to 1.0 based on the audible and/or visual evidence available to the selected analysis mode." }, "title": { "type": "string", "minLength": 1, "description": "Short catchy title for the moment (3-8 words)." }, "quotable_segment": { "$ref": "#/components/schemas/KeyMomentQuotableSegment" }, "audible_narrative": { "type": "string", "description": "One-sentence summary of what is being said during the moment. Empty when no transcript evidence is available." }, "notable_audible_concepts": { "type": "array", "items": { "type": "string", "minLength": 3 }, "description": "Multi-word descriptive phrases (2-5 words each) capturing key audible concepts. Empty when no transcript evidence is available." }, "visual_narrative": { "type": "string", "minLength": 1, "description": "One-sentence summary of what is visually happening. Present for video assets only." }, "notable_visual_concepts": { "type": "array", "items": { "type": "object", "properties": { "concept": { "type": "string", "minLength": 3, "description": "Multi-word visual concept (2-5 words)." }, "score": { "type": "number", "minimum": 0, "maximum": 1, "description": "Relevance score from 0.0 to 1.0 measuring how important the visual concept is to the moment's available evidence." }, "rationale": { "type": "string", "minLength": 1, "description": "Brief explanation of the relevance score." } }, "required": [ "concept", "score", "rationale" ] }, "minItems": 1, "description": "Scored visual concepts extracted from sampled frames. Present for video assets only." } }, "required": [ "start_ms", "end_ms", "cues", "overall_score", "title", "audible_narrative", "notable_audible_concepts" ] }, "description": "Extracted key moments, ordered by their absolute position on the original asset timeline." } }, "required": [ "moments" ], "example": { "moments": [ { "start_ms": 15000, "end_ms": 45000, "cues": [ { "start_ms": 15000, "end_ms": 20000, "text": "This is the moment everything changed." }, { "start_ms": 20000, "end_ms": 30000, "text": "We realized the entire approach was wrong." } ], "overall_score": 0.92, "title": "The Pivotal Realization", "quotable_segment": { "start_ms": 20000, "text": "We realized the entire approach was wrong." }, "audible_narrative": "The speaker describes the turning point that reshaped the project direction.", "notable_audible_concepts": [ "pivotal realization moment", "project direction change" ], "visual_narrative": "The speaker gestures emphatically at a whiteboard diagram while the camera zooms in.", "notable_visual_concepts": [ { "concept": "whiteboard diagram emphasis", "score": 0.88, "rationale": "The diagram directly illustrates the pivotal realization being described." }, { "concept": "speaker emphatic gestures", "score": 0.75, "rationale": "Body language reinforces the emotional weight of the turning point." } ] } ] }, "description": "Workflow results. Present when status is 'completed'." }, "FindKeyMomentsJobParameters": { "type": "object", "properties": { "asset_id": { "type": "string", "minLength": 1, "description": "The Mux asset ID of the video to analyze." }, "max_moments": { "type": "integer", "minimum": 1, "maximum": 25, "description": "Maximum number of key moments to extract. When omitted, defaults to 10 for assets up to one hour and 25 for longer assets." }, "target_duration_ms": { "type": "object", "properties": { "min": { "type": "integer", "exclusiveMinimum": 0, "description": "Preferred minimum highlight duration in milliseconds." }, "max": { "type": "integer", "exclusiveMinimum": 0, "description": "Preferred maximum highlight duration in milliseconds." } }, "required": [ "min", "max" ], "description": "Preferred highlight duration range in milliseconds. When provided, the model will aim to select moments within this range." }, "use_shots": { "type": "boolean", "description": "Controls whether video assets are analyzed using Mux shots. When true, shots are generated or reused and visual evidence drives selection. When false or omitted, selection uses transcript evidence and the asset must have a caption track. Not supported for audio-only assets." }, "output_steering": { "$ref": "#/components/schemas/FindKeyMomentsOutputSteering" } }, "required": [ "asset_id" ], "example": { "asset_id": "mux_asset_123abc", "max_moments": 10, "target_duration_ms": { "min": 15000, "max": 45000 }, "output_steering": { "scope": { "start_time": 30, "end_time": 180 }, "selection_strategy": "educational_takeaways", "title_style": "punchy", "audience": "Developer advocates", "rubric_priorities": [ "clarity_in_isolation", "soundbite_quality" ] } } }, "FindKeyMomentsJobResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FindKeyMomentsJob" } }, "required": [ "data" ] }, "FindKeyMomentsOutputSteering": { "type": "object", "properties": { "scope": { "allOf": [ { "$ref": "#/components/schemas/OutputSteeringScope" }, { "description": "Optional execution window in seconds on the original asset timeline. Omit start_time to begin at the asset start and omit end_time to continue through the asset end. Returned moment timestamps remain absolute asset timestamps." } ] }, "selection_strategy": { "$ref": "#/components/schemas/KeyMomentsSelectionStrategy" }, "title_style": { "$ref": "#/components/schemas/KeyMomentsTitleStyle" }, "audience": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Intended audience used as best-effort model guidance. Does not change the output schema." }, "brand_terms": { "$ref": "#/components/schemas/OutputSteeringBrandTerms" }, "topic_taxonomy": { "allOf": [ { "$ref": "#/components/schemas/OutputSteeringTaxonomy" }, { "description": "Controlled vocabulary used to steer notable audible concepts without changing the response schema." } ] }, "rubric_priorities": { "type": "array", "items": { "$ref": "#/components/schemas/KeyMomentsRubricPriority" }, "minItems": 1, "maxItems": 4, "description": "Rubric dimensions to use as tie-breakers after applying selection strategy. Best-effort guidance only." } }, "description": "Curated output_steering controls for execution scope, selection strategy, title style, audience, taxonomy, and rubric tie-breakers. Scope is enforced; other controls guide model behavior but do not guarantee exact output." }, "FindScenesBinding": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Customer-chosen identifier, unique within the directive. Resource `source.binding` refs point at this handle." }, "workflow": { "type": "string", "enum": [ "find-scenes" ], "description": "The Robots workflow to dispatch — the same identifier as POST /jobs/{workflow}.", "x-stainless-const": true }, "inputs": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "reference_ids of declared resources this workflow depends on. Each entry is a hard dependency: the workflow is not dispatched until the referenced resource is ready." }, "params": { "$ref": "#/components/schemas/FindScenesBindingParameters" } }, "required": [ "reference_id", "workflow" ], "title": "FindScenesBinding" }, "FindScenesBindingParameters": { "type": "object", "properties": { "language_code": { "type": "string", "minLength": 1, "description": "Preferred transcript language code to analyze when a matching transcript track is available. Defaults to the first ready transcript track on the asset." }, "min_scenes": { "type": "integer", "exclusiveMinimum": 0, "description": "Optional lower-bound hint for scene segmentation. When provided, the model should avoid collapsing clearly distinct beats below this count when the content supports more granular scene boundaries." }, "min_scene_duration_ms": { "type": "integer", "minimum": 1000, "description": "Preferred minimum scene duration in milliseconds for scaffolded transcript chunking. Defaults to 15000." }, "output_steering": { "$ref": "#/components/schemas/FindScenesOutputSteering" } }, "description": "Parameters for the find-scenes workflow — the same fields accepted by POST /jobs/find-scenes, minus engine-supplied fields such as asset_id." }, "FindScenesJob": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique job identifier." }, "passthrough": { "type": "string", "description": "Arbitrary string supplied at creation, returned as-is." }, "units_consumed": { "type": "integer", "minimum": 0, "description": "Number of Mux AI units consumed by this job." }, "directive": { "$ref": "#/components/schemas/JobDirectiveContext" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) when the job was created." }, "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state)." }, "workflow": { "type": "string", "enum": [ "find-scenes" ] }, "parameters": { "$ref": "#/components/schemas/FindScenesJobParameters" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JobError" }, "description": "Error details. Present when status is 'errored'." }, "resources": { "$ref": "#/components/schemas/Resources" }, "outputs": { "$ref": "#/components/schemas/FindScenesJobOutputs" } }, "required": [ "id", "units_consumed", "created_at", "updated_at", "workflow", "parameters", "status" ] }, "FindScenesJobOutputs": { "type": "object", "properties": { "scenes": { "type": "array", "items": { "type": "object", "properties": { "start_ms": { "type": "number", "minimum": 0, "description": "Scene start time in milliseconds." }, "end_ms": { "type": "number", "minimum": 0, "description": "Scene end time in milliseconds." }, "title": { "type": "string", "minLength": 1, "description": "Short human-readable title for the scene." }, "cues": { "type": "array", "items": { "type": "object", "properties": { "start_ms": { "type": "number", "minimum": 0, "description": "Cue start time in milliseconds." }, "end_ms": { "type": "number", "minimum": 0, "description": "Cue end time in milliseconds." }, "text": { "type": "string", "minLength": 1, "description": "Transcript text for this cue." } }, "required": [ "start_ms", "end_ms", "text" ] }, "description": "Transcript cues that overlap the scene. Can be empty when no usable transcript is available." }, "audible_narrative": { "type": "string", "minLength": 1, "description": "One-sentence summary of what is being said during the scene. Present only when transcript cues are available." }, "blended_narrative": { "type": "string", "minLength": 1, "description": "Combined audible and visual narrative for the scene when both signals are meaningfully available. Omit when no transcript-backed audible signal exists." }, "notable_audible_concepts": { "type": "array", "items": { "type": "string", "minLength": 3 }, "minItems": 1, "description": "Multi-word descriptive phrases capturing key audible concepts in the scene. Present only when transcript cues are available." }, "visual_narrative": { "type": "string", "minLength": 1, "description": "One-sentence summary of what is visually happening during the scene. Present for video assets when visual enrichment succeeds." }, "notable_visual_concepts": { "type": "array", "items": { "type": "object", "properties": { "concept": { "type": "string", "minLength": 3, "description": "Multi-word visual concept (2-5 words)." }, "score": { "type": "number", "minimum": 0, "maximum": 1, "description": "Salience score from 0.0 to 1.0 measuring how visually important the concept is within the scene." }, "rationale": { "type": "string", "minLength": 1, "description": "Brief explanation of why the concept is visually important for the scene." } }, "required": [ "concept", "score", "rationale" ] }, "minItems": 1, "description": "Scored visual concepts extracted from sampled scene frames. Present for video assets when visual enrichment succeeds." }, "shots": { "type": "array", "items": { "type": "object", "properties": { "start_ms": { "type": "number", "minimum": 0, "description": "Shot or beat start time in milliseconds within the scene." }, "end_ms": { "type": "number", "minimum": 0, "description": "Shot or beat end time in milliseconds within the scene." }, "visual_description": { "type": "string", "minLength": 1, "description": "Short visual description of what happens during this shot or beat." } }, "required": [ "start_ms", "end_ms", "visual_description" ] }, "minItems": 1, "description": "Optional ordered shot or beat breakdown within the scene, including timings and short visual descriptions." }, "shot_count": { "type": "integer", "exclusiveMinimum": 0, "description": "How many timed shot or beat entries make up the scene. When shots is present, this equals shots.length." } }, "required": [ "start_ms", "end_ms", "title", "cues", "shot_count" ] }, "description": "Ordered scene segments extracted from the original asset timeline using shot boundaries plus any available transcript context." } }, "required": [ "scenes" ], "example": { "scenes": [ { "start_ms": 0, "end_ms": 15000, "title": "Opening Remarks", "cues": [ { "start_ms": 500, "end_ms": 5000, "text": "Welcome everyone to today's session." } ], "audible_narrative": "The host introduces the topic and welcomes the audience.", "notable_audible_concepts": [ "session introduction overview", "welcome and context" ], "visual_narrative": "A speaker stands at a podium in front of a large screen.", "shot_count": 2 } ] }, "description": "Workflow results. Present when status is 'completed'." }, "FindScenesJobParameters": { "type": "object", "properties": { "asset_id": { "type": "string", "minLength": 1, "description": "The Mux asset ID of the video asset to segment into scenes. Audio-only assets are not supported." }, "language_code": { "type": "string", "minLength": 1, "description": "Preferred transcript language code to analyze when a matching transcript track is available. Defaults to the first ready transcript track on the asset." }, "min_scenes": { "type": "integer", "exclusiveMinimum": 0, "description": "Optional lower-bound hint for scene segmentation. When provided, the model should avoid collapsing clearly distinct beats below this count when the content supports more granular scene boundaries." }, "min_scene_duration_ms": { "type": "integer", "minimum": 1000, "description": "Preferred minimum scene duration in milliseconds for scaffolded transcript chunking. Defaults to 15000." }, "output_steering": { "$ref": "#/components/schemas/FindScenesOutputSteering" } }, "required": [ "asset_id" ], "example": { "asset_id": "mux_asset_123abc", "language_code": "en", "min_scenes": 4, "min_scene_duration_ms": 15000, "output_steering": { "scope": { "start_time": 30, "end_time": 180 }, "segmentation_strategy": "editorial_beats", "title_style": "descriptive", "narration_detail": "balanced" } } }, "FindScenesJobResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FindScenesJob" } }, "required": [ "data" ] }, "FindScenesNarrationDetail": { "type": "string", "enum": [ "concise", "balanced", "detailed" ], "description": "Best-effort guidance for how much detail scene narratives should include." }, "FindScenesOutputSteering": { "type": "object", "properties": { "scope": { "allOf": [ { "$ref": "#/components/schemas/OutputSteeringScope" }, { "description": "Optional execution window in seconds on the original asset timeline. The range must contain a video frame at the asset frame rate. Omit start_time to begin at the asset start and omit end_time to continue through the asset end. Returned scene timestamps remain absolute asset timestamps." } ] }, "segmentation_strategy": { "$ref": "#/components/schemas/FindScenesSegmentationStrategy" }, "title_style": { "$ref": "#/components/schemas/FindScenesTitleStyle" }, "narration_detail": { "$ref": "#/components/schemas/FindScenesNarrationDetail" }, "audience": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Intended audience used as best-effort model guidance. Does not change the output schema." }, "brand_terms": { "allOf": [ { "$ref": "#/components/schemas/OutputSteeringBrandTerms" }, { "description": "Preferred brand or domain terms to use when supported by source evidence." } ] }, "topic_taxonomy": { "allOf": [ { "$ref": "#/components/schemas/OutputSteeringTaxonomy" }, { "description": "Controlled vocabulary used to steer scene concepts without changing the response schema." } ] } }, "description": "Curated output_steering controls for execution scope, segmentation strategy, title style, narration detail, audience, brand terms, and topic taxonomy. Scope is enforced; other controls guide model behavior but do not guarantee exact output." }, "FindScenesSegmentationStrategy": { "type": "string", "enum": [ "editorial_beats", "topic_changes", "visual_transitions", "action_progression", "instructional_steps" ], "description": "Best-effort guidance for the kinds of boundaries the scene finder should prefer." }, "FindScenesTitleStyle": { "type": "string", "enum": [ "descriptive", "editorial", "search_optimized", "accessibility" ], "description": "Best-effort title style guidance for generated scene titles." }, "GenerateChaptersAssetUpdate": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/GenerateChaptersAssetUpdateStatus" }, "track_id": { "type": "string", "minLength": 1, "description": "Mux text track ID of the chapters track created on the asset. Present when status is `created`." }, "replaced_track_id": { "type": "string", "minLength": 1, "description": "Mux text track ID of the chapters track that was deleted to make room for the new one. Absent when the asset had no chapters track. On a `failed` status it means the delete succeeded but the create did not, leaving the asset with no chapters track." } }, "required": [ "status" ], "description": "What happened when the generated chapters were written back to the Mux asset. Present only when update_asset_chapters was true." }, "GenerateChaptersAssetUpdateStatus": { "type": "string", "enum": [ "created", "failed" ], "description": "Outcome of the chapters track write. `created` means the asset now carries these chapters. `failed` means the write was attempted and errored; the chapters in this response are still valid and can be applied manually." }, "GenerateChaptersBinding": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Customer-chosen identifier, unique within the directive. Resource `source.binding` refs point at this handle." }, "workflow": { "type": "string", "enum": [ "generate-chapters" ], "description": "The Robots workflow to dispatch — the same identifier as POST /jobs/{workflow}.", "x-stainless-const": true }, "inputs": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "reference_ids of declared resources this workflow depends on. Each entry is a hard dependency: the workflow is not dispatched until the referenced resource is ready." }, "params": { "$ref": "#/components/schemas/GenerateChaptersBindingParameters" } }, "required": [ "reference_id", "workflow" ], "title": "GenerateChaptersBinding" }, "GenerateChaptersBindingParameters": { "type": "object", "properties": { "language_code": { "type": "string", "minLength": 1, "description": "BCP 47 language code of the caption track to analyze (e.g. \"en\", \"fr\"). When omitted, the SDK prefers English if available." }, "output_language_code": { "type": "string", "minLength": 1, "description": "BCP 47 language code for the output chapter titles. Auto-detected from the transcript if omitted." }, "output_steering": { "$ref": "#/components/schemas/GenerateChaptersOutputSteering" }, "prompt_overrides": { "type": "object", "properties": { "task": { "type": "string", "minLength": 1, "description": "Override the core task instruction for chapter generation." }, "output_format": { "type": "string", "minLength": 1, "description": "Override the JSON output format instructions." }, "chapter_guidelines": { "type": "string", "minLength": 1, "description": "Override the chapter density and timing constraints." }, "title_guidelines": { "type": "string", "minLength": 1, "description": "Override the chapter title style requirements." } }, "description": "Deprecated: use `output_steering`. Raw prompt-section overrides; any section supplied here takes precedence over the equivalent `output_steering` guidance.", "deprecated": true, "x-stainless-deprecation-message": "Use `output_steering` instead." }, "update_asset_chapters": { "type": "boolean", "description": "When true, the generated chapters are written back to the Mux asset as a chapters text track once the job completes, making them deliverable with the asset. Overwrites existing chapters: an asset holds a single chapters track, so any chapters track already on the asset is deleted and replaced — including one in a different language, and one you created yourself. Best-effort — a failed write does not fail the job — so check `asset_update` in the job outputs for the outcome." } }, "description": "Parameters for the generate-chapters workflow — the same fields accepted by POST /jobs/generate-chapters, minus engine-supplied fields such as asset_id." }, "GenerateChaptersJob": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique job identifier." }, "passthrough": { "type": "string", "description": "Arbitrary string supplied at creation, returned as-is." }, "units_consumed": { "type": "integer", "minimum": 0, "description": "Number of Mux AI units consumed by this job." }, "directive": { "$ref": "#/components/schemas/JobDirectiveContext" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) when the job was created." }, "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state)." }, "workflow": { "type": "string", "enum": [ "generate-chapters" ] }, "parameters": { "$ref": "#/components/schemas/GenerateChaptersJobParameters" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JobError" }, "description": "Error details. Present when status is 'errored'." }, "resources": { "$ref": "#/components/schemas/Resources" }, "outputs": { "$ref": "#/components/schemas/GenerateChaptersJobOutputs" } }, "required": [ "id", "units_consumed", "created_at", "updated_at", "workflow", "parameters", "status" ] }, "GenerateChaptersJobOutputs": { "type": "object", "properties": { "chapters": { "type": "array", "items": { "type": "object", "properties": { "start_time": { "type": "number", "minimum": 0, "description": "Chapter start time in seconds. The first chapter always starts at 0." }, "title": { "type": "string", "minLength": 1, "description": "Concise chapter title." } }, "required": [ "start_time", "title" ] }, "minItems": 1, "description": "Generated chapters, ordered by start time." }, "asset_update": { "$ref": "#/components/schemas/GenerateChaptersAssetUpdate" } }, "required": [ "chapters" ], "example": { "asset_update": { "status": "created", "track_id": "track_chapters_abc123" }, "chapters": [ { "start_time": 0, "title": "Introduction" }, { "start_time": 45, "title": "Setting Up the Workspace" }, { "start_time": 180, "title": "Core Implementation" }, { "start_time": 420, "title": "Testing and Debugging" }, { "start_time": 600, "title": "Wrap-Up and Next Steps" } ] }, "description": "Workflow results. Present when status is 'completed'." }, "GenerateChaptersJobParameters": { "type": "object", "properties": { "asset_id": { "type": "string", "minLength": 1, "description": "The Mux asset ID of the video to generate chapters for." }, "language_code": { "type": "string", "minLength": 1, "description": "BCP 47 language code of the caption track to analyze (e.g. \"en\", \"fr\"). When omitted, the SDK prefers English if available." }, "output_language_code": { "type": "string", "minLength": 1, "description": "BCP 47 language code for the output chapter titles. Auto-detected from the transcript if omitted." }, "output_steering": { "$ref": "#/components/schemas/GenerateChaptersOutputSteering" }, "prompt_overrides": { "type": "object", "properties": { "task": { "type": "string", "minLength": 1, "description": "Override the core task instruction for chapter generation." }, "output_format": { "type": "string", "minLength": 1, "description": "Override the JSON output format instructions." }, "chapter_guidelines": { "type": "string", "minLength": 1, "description": "Override the chapter density and timing constraints." }, "title_guidelines": { "type": "string", "minLength": 1, "description": "Override the chapter title style requirements." } }, "description": "Deprecated: use `output_steering`. Raw prompt-section overrides; any section supplied here takes precedence over the equivalent `output_steering` guidance.", "deprecated": true, "x-stainless-deprecation-message": "Use `output_steering` instead." }, "update_asset_chapters": { "type": "boolean", "description": "When true, the generated chapters are written back to the Mux asset as a chapters text track once the job completes, making them deliverable with the asset. Overwrites existing chapters: an asset holds a single chapters track, so any chapters track already on the asset is deleted and replaced — including one in a different language, and one you created yourself. Best-effort — a failed write does not fail the job — so check `asset_update` in the job outputs for the outcome." } }, "required": [ "asset_id" ], "example": { "asset_id": "mux_asset_123abc", "update_asset_chapters": true, "output_steering": { "chapter_style": "descriptive", "chapter_granularity": "balanced", "audience": "Developers" } } }, "GenerateChaptersJobResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GenerateChaptersJob" } }, "required": [ "data" ] }, "GenerateChaptersOutputSteering": { "type": "object", "properties": { "chapter_style": { "$ref": "#/components/schemas/ChapterStyle" }, "chapter_granularity": { "$ref": "#/components/schemas/ChapterGranularity" }, "audience": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Intended audience used as best-effort model guidance. Does not change the output schema." }, "brand_terms": { "$ref": "#/components/schemas/OutputSteeringBrandTerms" } }, "description": "Curated output_steering controls for chapter style, granularity, audience, and brand terminology. These controls guide model behavior but do not guarantee exact output." }, "GenerateEngagementInsightsBinding": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Customer-chosen identifier, unique within the directive. Resource `source.binding` refs point at this handle." }, "workflow": { "type": "string", "enum": [ "generate-engagement-insights" ], "description": "The Robots workflow to dispatch — the same identifier as POST /jobs/{workflow}.", "x-stainless-const": true }, "inputs": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "reference_ids of declared resources this workflow depends on. Each entry is a hard dependency: the workflow is not dispatched until the referenced resource is ready." }, "params": { "$ref": "#/components/schemas/GenerateEngagementInsightsBindingParameters" } }, "required": [ "reference_id", "workflow" ], "title": "GenerateEngagementInsightsBinding" }, "GenerateEngagementInsightsBindingParameters": { "type": "object", "properties": {}, "description": "Parameters for the generate-engagement-insights workflow — the same fields accepted by POST /jobs/generate-engagement-insights, minus engine-supplied fields such as asset_id." }, "GenerateEngagementInsightsJob": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique job identifier." }, "passthrough": { "type": "string", "description": "Arbitrary string supplied at creation, returned as-is." }, "units_consumed": { "type": "integer", "minimum": 0, "description": "Number of Mux AI units consumed by this job." }, "directive": { "$ref": "#/components/schemas/JobDirectiveContext" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) when the job was created." }, "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state)." }, "workflow": { "type": "string", "enum": [ "generate-engagement-insights" ] }, "parameters": { "$ref": "#/components/schemas/GenerateEngagementInsightsJobParameters" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JobError" }, "description": "Error details. Present when status is 'errored'." }, "resources": { "$ref": "#/components/schemas/Resources" }, "outputs": { "$ref": "#/components/schemas/GenerateEngagementInsightsJobOutputs" } }, "required": [ "id", "units_consumed", "created_at", "updated_at", "workflow", "parameters", "status" ] }, "GenerateEngagementInsightsJobOutputs": { "type": "object", "properties": { "moment_insights": { "type": "array", "items": { "type": "object", "properties": { "start_ms": { "type": "number", "minimum": 0, "description": "Start time in milliseconds." }, "end_ms": { "type": "number", "minimum": 0, "description": "End time in milliseconds." }, "engagement_score": { "type": "number", "minimum": 0, "maximum": 1, "description": "Normalized engagement score (0-1)." }, "insight": { "type": "string", "description": "Primary insight explaining the engagement pattern." } }, "required": [ "start_ms", "end_ms", "engagement_score", "insight" ] }, "description": "Per-moment engagement insights for identified hotspots." }, "overall_insight": { "type": "object", "properties": { "summary": { "type": "string", "description": "Summary of overall engagement patterns." }, "trends": { "type": "array", "items": { "type": "string" }, "description": "Key trends identified across the video." } }, "required": [ "summary", "trends" ], "description": "Overall engagement analysis across the video." } }, "required": [ "moment_insights", "overall_insight" ], "example": { "moment_insights": [ { "start_ms": 30000, "end_ms": 60000, "engagement_score": 0.89, "insight": "Viewers are highly engaged during the product demo, with minimal drop-off." } ], "overall_insight": { "summary": "Engagement peaks during hands-on demonstrations and drops during introductory segments.", "trends": [ "Product demos drive the highest retention", "Viewers skip past the first 15 seconds of intro" ] } }, "description": "Workflow results. Present when status is 'completed'." }, "GenerateEngagementInsightsJobParameters": { "type": "object", "properties": { "asset_id": { "type": "string", "minLength": 1, "description": "The Mux asset ID of the video to analyze engagement for." } }, "required": [ "asset_id" ], "example": { "asset_id": "mux_asset_123abc" } }, "GenerateEngagementInsightsJobResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GenerateEngagementInsightsJob" } }, "required": [ "data" ] }, "GeneratePremiumCaptionsBinding": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Customer-chosen identifier, unique within the directive. Resource `source.binding` refs point at this handle." }, "workflow": { "type": "string", "enum": [ "generate-premium-captions" ], "description": "The Robots workflow to dispatch — the same identifier as POST /jobs/{workflow}.", "x-stainless-const": true }, "inputs": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "reference_ids of declared resources this workflow depends on. Each entry is a hard dependency: the workflow is not dispatched until the referenced resource is ready." }, "params": { "$ref": "#/components/schemas/GeneratePremiumCaptionsBindingParameters" } }, "required": [ "reference_id", "workflow" ], "title": "GeneratePremiumCaptionsBinding" }, "GeneratePremiumCaptionsBindingParameters": { "type": "object", "properties": { "language_code": { "type": "string", "minLength": 1, "description": "BCP 47 language code of the audio (e.g. \"en\", \"es\"). A best-effort hint that biases transcription toward this language — it is not verified against the audio and does not guarantee the output language. When supplied, language detection is skipped and the captions are labeled with this code. The language will be auto-detected when omitted; existing tracks are then checked against `replace_existing_tracks` after transcription, so a same-language conflict errors the job at track creation instead of being rejected up front, and a deleting policy only applies when the detection is confident." }, "replace_existing_tracks": { "$ref": "#/components/schemas/GeneratePremiumCaptionsReplaceExistingTracks" }, "replace_existing": { "type": "boolean", "description": "Deprecated: use `replace_existing_tracks`. `true` behaves as `replace_all` and `false` as `fail`. `true` cannot be combined with `replace_existing_tracks`; `false` is ignored when both are present.", "deprecated": true, "x-stainless-deprecation-message": "Use `replace_existing_tracks` instead." }, "track_name": { "type": "string", "minLength": 1, "description": "Custom name for the uploaded Mux text track. Defaults to \"{Language} (Generated)\", e.g. \"English (Generated)\". Mux requires text track names to be unique on an asset." }, "include_speakers": { "type": "boolean", "default": false, "description": "When true, speaker labels are identified and added to each caption cue. Useful for interviews, podcasts, and multi-speaker content." }, "include_words": { "type": "boolean", "default": false, "description": "When true, word-level timestamps are exported as a JSON file accessible via temporary_words_url in the job outputs. The URL expires 7 days after the job completes. Billed at a higher unit rate." }, "upload_to_mux": { "type": "boolean", "default": true, "description": "Whether to upload the generated VTT to the Mux asset as a new text track. Defaults to true. When false, no track is created and `replace_existing_tracks` must be `fail`; the generated SRT remains available via `temporary_srt_url`." }, "phrases": { "$ref": "#/components/schemas/GeneratePremiumCaptionsPhrases" } }, "description": "Parameters for the generate-premium-captions workflow — the same fields accepted by POST /jobs/generate-premium-captions, minus engine-supplied fields such as asset_id." }, "GeneratePremiumCaptionsJob": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique job identifier." }, "passthrough": { "type": "string", "description": "Arbitrary string supplied at creation, returned as-is." }, "units_consumed": { "type": "integer", "minimum": 0, "description": "Number of Mux AI units consumed by this job." }, "directive": { "$ref": "#/components/schemas/JobDirectiveContext" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) when the job was created." }, "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state)." }, "workflow": { "type": "string", "enum": [ "generate-premium-captions" ] }, "parameters": { "$ref": "#/components/schemas/GeneratePremiumCaptionsJobParameters" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JobError" }, "description": "Error details. Present when status is 'errored'." }, "resources": { "$ref": "#/components/schemas/Resources" }, "outputs": { "$ref": "#/components/schemas/GeneratePremiumCaptionsJobOutputs" } }, "required": [ "id", "units_consumed", "created_at", "updated_at", "workflow", "parameters", "status" ] }, "GeneratePremiumCaptionsJobOutputs": { "type": "object", "properties": { "track_id": { "type": "string", "minLength": 1, "description": "Mux text track ID of the newly uploaded caption track. Omitted when upload_to_mux is false." }, "language_code": { "type": "string", "minLength": 1, "description": "Resolved language code of the generated captions (may differ from the requested code when auto-detected)." }, "detected_language": { "type": "string", "minLength": 1, "description": "Language code reported by the transcription model. Only a genuine detection when language_code was omitted from the request; when a language_code hint was supplied, detection is skipped and this echoes the requested language." }, "auto_language_confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "The transcription model's confidence in its automatic language detection, from 0 to 1. Always 1 when language_code was supplied in the request, since detection is skipped." }, "temporary_srt_url": { "type": "string", "minLength": 1, "description": "Temporary pre-signed URL to download the generated SRT file. Expires 7 days after the job completes." }, "temporary_words_url": { "type": "string", "minLength": 1, "description": "Temporary pre-signed URL to download the word-level timestamp JSON. Present when include_words is true. Expires 7 days after the job completes. Download and store this file for long-term access." }, "replaced_track_id": { "type": "string", "minLength": 1, "description": "Deprecated: use `replaced_tracks`. The ID of the first entry in `replaced_tracks`, kept for compatibility.", "deprecated": true, "x-stainless-deprecation-message": "Use `replaced_tracks` instead." }, "replaced_tracks": { "$ref": "#/components/schemas/ReplacedTracks" } }, "required": [ "language_code" ], "example": { "track_id": "track_en_abc123", "language_code": "en", "detected_language": "en", "auto_language_confidence": 0.98, "temporary_srt_url": "https://storage.example.com/captions/en/abc123.srt?token=abc" }, "description": "Workflow results. Present when status is 'completed'." }, "GeneratePremiumCaptionsJobParameters": { "type": "object", "properties": { "asset_id": { "type": "string", "minLength": 1, "description": "The Mux asset ID of the video to caption." }, "language_code": { "type": "string", "minLength": 1, "description": "BCP 47 language code of the audio (e.g. \"en\", \"es\"). A best-effort hint that biases transcription toward this language — it is not verified against the audio and does not guarantee the output language. When supplied, language detection is skipped and the captions are labeled with this code. The language will be auto-detected when omitted; existing tracks are then checked against `replace_existing_tracks` after transcription, so a same-language conflict errors the job at track creation instead of being rejected up front, and a deleting policy only applies when the detection is confident." }, "replace_existing_tracks": { "$ref": "#/components/schemas/GeneratePremiumCaptionsReplaceExistingTracks" }, "replace_existing": { "type": "boolean", "description": "Deprecated: use `replace_existing_tracks`. `true` behaves as `replace_all` and `false` as `fail`. `true` cannot be combined with `replace_existing_tracks`; `false` is ignored when both are present.", "deprecated": true, "x-stainless-deprecation-message": "Use `replace_existing_tracks` instead." }, "track_name": { "type": "string", "minLength": 1, "description": "Custom name for the uploaded Mux text track. Defaults to \"{Language} (Generated)\", e.g. \"English (Generated)\". Mux requires text track names to be unique on an asset." }, "include_speakers": { "type": "boolean", "default": false, "description": "When true, speaker labels are identified and added to each caption cue. Useful for interviews, podcasts, and multi-speaker content." }, "include_words": { "type": "boolean", "default": false, "description": "When true, word-level timestamps are exported as a JSON file accessible via temporary_words_url in the job outputs. The URL expires 7 days after the job completes. Billed at a higher unit rate." }, "upload_to_mux": { "type": "boolean", "default": true, "description": "Whether to upload the generated VTT to the Mux asset as a new text track. Defaults to true. When false, no track is created and `replace_existing_tracks` must be `fail`; the generated SRT remains available via `temporary_srt_url`." }, "phrases": { "$ref": "#/components/schemas/GeneratePremiumCaptionsPhrases" } }, "required": [ "asset_id" ], "example": { "asset_id": "mux_asset_123abc", "language_code": "en", "replace_existing_tracks": "fail", "include_speakers": false, "include_words": false, "upload_to_mux": true, "phrases": [ "Mux", "API" ] } }, "GeneratePremiumCaptionsJobResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GeneratePremiumCaptionsJob" } }, "required": [ "data" ] }, "GeneratePremiumCaptionsPhrases": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 49 }, "minItems": 1, "maxItems": 1000, "description": "Best-effort list of words or short phrases (proper nouns, product names, jargon) likely to appear in the audio, used to bias recognition toward correct spellings. Does not guarantee exact output. Each phrase may contain at most 49 characters and 5 words, and must not contain the characters <, >, {, }, [, ], or \\.", "example": [ "Mux", "API" ] }, "GeneratePremiumCaptionsReplaceExistingTracks": { "type": "string", "enum": [ "fail", "replace_all", "replace_generated" ], "description": "What to do when the asset already has a text track in the same language as, or with the same name as, the new caption track. Defaults to `fail`, which rejects the request before any work is billed. `replace_all` deletes every such track first. `replace_generated` deletes only Mux Video auto-generated tracks and rejects if an uploaded track is in the way. Existing tracks are matched by language ignoring region subtags, and by name ignoring case, in any status. When `language_code` is omitted the detected language is used, and tracks are only deleted when the detection is confident; otherwise the job behaves as `fail`." }, "JobDirectiveContext": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the directive that dispatched this job." }, "run_id": { "type": "string", "description": "ID of the specific directive run that dispatched this job." } }, "required": [ "id", "run_id" ], "description": "The directive run that dispatched this job. Absent for jobs created via direct API POST." }, "JobError": { "type": "object", "properties": { "type": { "type": "string", "description": "Stable public error category identifier." }, "message": { "type": "string", "description": "Human-readable public error message." }, "retryable": { "type": "boolean", "description": "Whether retrying this job may resolve the error." } }, "required": [ "type", "message" ] }, "JobStatus": { "type": "string", "enum": [ "pending", "processing", "completed", "errored", "cancelled" ], "description": "Current job status." }, "JobSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique job identifier." }, "workflow": { "type": "string", "enum": [ "summarize", "moderate", "generate-chapters", "find-scenes", "edit-captions", "translate-captions", "translate-audio", "ask-questions", "find-key-moments", "generate-engagement-insights", "generate-premium-captions", "find-best-thumbnails" ], "description": "Workflow type that created this job." }, "status": { "$ref": "#/components/schemas/JobStatus" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) when the job was created." }, "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state)." }, "_links": { "type": "object", "properties": { "self": { "type": "object", "properties": { "href": { "type": "string", "description": "URL to this resource." } }, "required": [ "href" ] } }, "required": [ "self" ], "description": "Hypermedia links for this job." } }, "required": [ "id", "workflow", "status", "created_at", "updated_at", "_links" ] }, "KeyMomentQuotableSegment": { "type": "object", "properties": { "start_ms": { "type": "number", "minimum": 0, "description": "Quote segment start time in milliseconds." }, "text": { "type": "string", "minLength": 1, "description": "Verbatim transcript quote selected from within the key moment." } }, "required": [ "start_ms", "text" ], "example": { "start_ms": 20000, "text": "We realized the entire approach was wrong." }, "description": "Best short, verbatim quote from within this moment. Omitted when the selected video moment has no source-grounded transcript quote." }, "KeyMomentsRubricPriority": { "type": "string", "enum": [ "clarity_in_isolation", "emotional_intensity", "novelty", "soundbite_quality" ] }, "KeyMomentsSelectionStrategy": { "type": "string", "enum": [ "standalone_hooks", "educational_takeaways", "story_beats", "product_moments", "speaker_highlights" ], "description": "Best-effort guidance for what qualifies as a strong standalone key moment." }, "KeyMomentsTitleStyle": { "type": "string", "enum": [ "descriptive", "punchy", "educational", "social" ], "description": "Best-effort title style guidance for generated moment titles." }, "ListJobsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/JobSummary" } }, "total_row_count": { "type": "integer", "description": "Total number of jobs matching the query filters", "example": 42 } }, "required": [ "data", "total_row_count" ] }, "ModerateBinding": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Customer-chosen identifier, unique within the directive. Resource `source.binding` refs point at this handle." }, "workflow": { "type": "string", "enum": [ "moderate" ], "description": "The Robots workflow to dispatch — the same identifier as POST /jobs/{workflow}.", "x-stainless-const": true }, "inputs": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "reference_ids of declared resources this workflow depends on. Each entry is a hard dependency: the workflow is not dispatched until the referenced resource is ready." }, "params": { "$ref": "#/components/schemas/ModerateBindingParameters" } }, "required": [ "reference_id", "workflow" ], "title": "ModerateBinding" }, "ModerateBindingParameters": { "type": "object", "properties": { "language_code": { "type": "string", "minLength": 1, "default": "en", "description": "BCP 47 language code for transcript analysis. Used only for audio-only assets; ignored for video assets with visual content. If omitted for audio-only assets, the first ready text track is used. Defaults to \"en\"." }, "thresholds": { "type": "object", "properties": { "sexual": { "type": "number", "minimum": 0, "maximum": 1, "description": "Score threshold for sexual content. Content scoring above this value triggers exceeds_threshold." }, "violence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Score threshold for violent content. Content scoring above this value triggers exceeds_threshold." } }, "default": { "sexual": 0.7, "violence": 0.8 }, "description": "Score thresholds that determine whether content is flagged. When combined with sampling_interval or max_samples, the exceeds_threshold flag reflects whether any category's highest observed score exceeds its configured threshold. Defaults to {sexual: 0.7, violence: 0.8}." }, "sampling_interval": { "type": "integer", "minimum": 5, "description": "Interval, in seconds, between sampled thumbnails. Minimum 5 seconds. When max_samples is also set, the actual sampling density is the more restrictive of the two constraints." }, "max_samples": { "type": "integer", "minimum": 1, "description": "Maximum number of thumbnails to sample. Acts as a cap — if sampling_interval produces fewer samples than this limit, the interval is respected; otherwise samples are evenly distributed with first and last frames pinned." }, "output_steering": { "$ref": "#/components/schemas/ModerateOutputSteering" }, "on_flagged": { "$ref": "#/components/schemas/ActionOnFlagged" } }, "description": "Parameters for the moderate workflow — the same fields accepted by POST /jobs/moderate, minus engine-supplied fields such as asset_id." }, "ModerateJob": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique job identifier." }, "passthrough": { "type": "string", "description": "Arbitrary string supplied at creation, returned as-is." }, "units_consumed": { "type": "integer", "minimum": 0, "description": "Number of Mux AI units consumed by this job." }, "directive": { "$ref": "#/components/schemas/JobDirectiveContext" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) when the job was created." }, "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state)." }, "workflow": { "type": "string", "enum": [ "moderate" ] }, "parameters": { "$ref": "#/components/schemas/ModerateJobParameters" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JobError" }, "description": "Error details. Present when status is 'errored'." }, "resources": { "$ref": "#/components/schemas/Resources" }, "outputs": { "$ref": "#/components/schemas/ModerateJobOutputs" } }, "required": [ "id", "units_consumed", "created_at", "updated_at", "workflow", "parameters", "status" ] }, "ModerateJobOutputs": { "type": "object", "properties": { "thumbnail_scores": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "number", "minimum": 0, "description": "Time in seconds of the thumbnail within the video. Absent for transcript moderation." }, "sexual": { "type": "number", "minimum": 0, "maximum": 1, "description": "Sexual content score from 0.0 to 1.0." }, "violence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Violence content score from 0.0 to 1.0." } }, "required": [ "sexual", "violence" ] }, "description": "Per-thumbnail moderation scores." }, "max_scores": { "type": "object", "properties": { "sexual": { "type": "number", "minimum": 0, "maximum": 1 }, "violence": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "sexual", "violence" ], "description": "Highest scores across all thumbnails for each category." }, "exceeds_threshold": { "type": "boolean", "description": "True if any category's max score exceeds its configured threshold." }, "flagged_action": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "delete_playback_ids" ] }, "deleted_playback_ids": { "type": "array", "items": { "type": "string" }, "description": "Playback IDs that were deleted from the asset because it exceeded the threshold." } }, "required": [ "action", "deleted_playback_ids" ], "description": "Present only when on_flagged was set and exceeds_threshold was true. Records the action taken and which playback IDs were deleted." } }, "required": [ "thumbnail_scores", "max_scores", "exceeds_threshold" ], "example": { "thumbnail_scores": [ { "time": 0, "sexual": 0.01, "violence": 0.02 }, { "time": 30, "sexual": 0.03, "violence": 0.15 }, { "time": 60, "sexual": 0.02, "violence": 0.05 } ], "max_scores": { "sexual": 0.03, "violence": 0.15 }, "exceeds_threshold": false }, "description": "Workflow results. Present when status is 'completed'." }, "ModerateJobParameters": { "type": "object", "properties": { "asset_id": { "type": "string", "minLength": 1, "description": "The Mux asset ID of the video to moderate." }, "language_code": { "type": "string", "minLength": 1, "default": "en", "description": "BCP 47 language code for transcript analysis. Used only for audio-only assets; ignored for video assets with visual content. If omitted for audio-only assets, the first ready text track is used. Defaults to \"en\"." }, "thresholds": { "type": "object", "properties": { "sexual": { "type": "number", "minimum": 0, "maximum": 1, "description": "Score threshold for sexual content. Content scoring above this value triggers exceeds_threshold." }, "violence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Score threshold for violent content. Content scoring above this value triggers exceeds_threshold." } }, "default": { "sexual": 0.7, "violence": 0.8 }, "description": "Score thresholds that determine whether content is flagged. When combined with sampling_interval or max_samples, the exceeds_threshold flag reflects whether any category's highest observed score exceeds its configured threshold. Defaults to {sexual: 0.7, violence: 0.8}." }, "sampling_interval": { "type": "integer", "minimum": 5, "description": "Interval, in seconds, between sampled thumbnails. Minimum 5 seconds. When max_samples is also set, the actual sampling density is the more restrictive of the two constraints." }, "max_samples": { "type": "integer", "minimum": 1, "description": "Maximum number of thumbnails to sample. Acts as a cap — if sampling_interval produces fewer samples than this limit, the interval is respected; otherwise samples are evenly distributed with first and last frames pinned." }, "output_steering": { "$ref": "#/components/schemas/ModerateOutputSteering" }, "on_flagged": { "$ref": "#/components/schemas/ActionOnFlagged" } }, "required": [ "asset_id" ], "example": { "asset_id": "mux_asset_123abc", "thresholds": { "sexual": 0.7, "violence": 0.8 }, "output_steering": { "scope": { "start_time": 30, "end_time": 180 } }, "on_flagged": { "action": "delete_playback_ids" } } }, "ModerateJobResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ModerateJob" } }, "required": [ "data" ] }, "ModerateOutputSteering": { "type": "object", "properties": { "scope": { "allOf": [ { "$ref": "#/components/schemas/OutputSteeringScope" }, { "description": "Optional execution window in seconds on the original asset timeline. Omit start_time to begin at the asset start and omit end_time to continue through the asset end. Moderation is restricted to media within this window, while returned timestamps remain absolute asset timestamps." } ] } }, "description": "Curated controls that optionally restrict moderation to an asset time range." }, "NodeState": { "oneOf": [ { "$ref": "#/components/schemas/NodeStateDispatched" }, { "$ref": "#/components/schemas/NodeStateFailed" }, { "$ref": "#/components/schemas/NodeStateWaitingForResources" }, { "$ref": "#/components/schemas/NodeStateWaitingForSourceWorkflow" } ], "discriminator": { "propertyName": "status", "mapping": { "dispatched": "#/components/schemas/NodeStateDispatched", "failed": "#/components/schemas/NodeStateFailed", "waiting_for_resources": "#/components/schemas/NodeStateWaitingForResources", "waiting_for_source_workflow": "#/components/schemas/NodeStateWaitingForSourceWorkflow" } }, "description": "The state of one workflow binding within a directive run." }, "NodeStateDispatched": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "description": "Declared binding id from `directive.workflows[]`." }, "status": { "type": "string", "enum": [ "dispatched" ], "x-stainless-const": true }, "workflow_name": { "type": "string", "enum": [ "summarize", "moderate", "generate-chapters", "find-scenes", "edit-captions", "translate-captions", "translate-audio", "ask-questions", "find-key-moments", "generate-engagement-insights", "generate-premium-captions", "find-best-thumbnails" ], "description": "The Robots workflow for this binding.", "title": "WorkflowName" }, "job_id": { "type": "string", "description": "Encoded workflow job identifier (rjob_...)." } }, "required": [ "reference_id", "status", "workflow_name", "job_id" ], "title": "NodeStateDispatched" }, "NodeStateFailed": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "description": "Declared binding id from `directive.workflows[]`." }, "status": { "type": "string", "enum": [ "failed" ], "x-stainless-const": true }, "reason": { "type": "string", "description": "Human-readable diagnostic explaining why the binding didn't dispatch." } }, "required": [ "reference_id", "status", "reason" ], "title": "NodeStateFailed" }, "NodeStateWaitingForResources": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "description": "Declared binding id from `directive.workflows[]`." }, "status": { "type": "string", "enum": [ "waiting_for_resources" ], "x-stainless-const": true }, "workflow_name": { "type": "string", "enum": [ "summarize", "moderate", "generate-chapters", "find-scenes", "edit-captions", "translate-captions", "translate-audio", "ask-questions", "find-key-moments", "generate-engagement-insights", "generate-premium-captions", "find-best-thumbnails" ], "description": "The Robots workflow for this binding.", "title": "WorkflowName" } }, "required": [ "reference_id", "status", "workflow_name" ], "title": "NodeStateWaitingForResources" }, "NodeStateWaitingForSourceWorkflow": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "description": "Declared binding id from `directive.workflows[]`." }, "status": { "type": "string", "enum": [ "waiting_for_source_workflow" ], "x-stainless-const": true }, "workflow_name": { "type": "string", "enum": [ "summarize", "moderate", "generate-chapters", "find-scenes", "edit-captions", "translate-captions", "translate-audio", "ask-questions", "find-key-moments", "generate-engagement-insights", "generate-premium-captions", "find-best-thumbnails" ], "description": "The Robots workflow for this binding.", "title": "WorkflowName" }, "source_workflows": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "reference_ids of producer bindings within this directive that must complete before this binding can dispatch." } }, "required": [ "reference_id", "status", "workflow_name", "source_workflows" ], "title": "NodeStateWaitingForSourceWorkflow" }, "OutputSteeringBrandTerms": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40 }, "minItems": 1, "maxItems": 10, "description": "Preferred brand or domain terms to use when supported by the source content." }, "OutputSteeringScope": { "type": "object", "properties": { "start_time": { "type": "number", "minimum": 0, "description": "Start of the execution window in seconds from the beginning of the media. When omitted, the window starts at the beginning." }, "end_time": { "type": "number", "exclusiveMinimum": 0, "description": "End of the execution window in seconds from the beginning of the media. When omitted, the window extends to the end." } }, "description": "Optional media execution window. Results remain timestamped against the original media timeline." }, "OutputSteeringTaxonomy": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Optional customer-facing name for the taxonomy." }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/OutputSteeringTaxonomyValue" }, "minItems": 1, "maxItems": 50, "description": "Controlled vocabulary values used as best-effort model guidance." }, "allow_other": { "type": "boolean", "description": "When false, the model should prefer values from the taxonomy. When true, non-taxonomy values may be used when no taxonomy value applies." } }, "required": [ "values", "allow_other" ], "description": "Controlled vocabulary used as best-effort guidance for generated labels and concepts." }, "OutputSteeringTaxonomyValue": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Canonical taxonomy value to prefer when supported by the source content." }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Short explanation of when this value applies." }, "aliases": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "maxItems": 10, "description": "Accepted alternate names that should normalize to the canonical label." } }, "required": [ "label" ] }, "ReplacedTrack": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Mux track ID of the deleted track." }, "type": { "type": "string", "enum": [ "text", "audio" ], "description": "Mux track type of the deleted track." }, "name": { "type": "string", "description": "Name of the deleted track." }, "language_code": { "type": "string", "description": "Language code of the deleted track." }, "text_source": { "type": "string", "description": "Mux `text_source` of the deleted track, e.g. `uploaded` or `generated_vod`. Absent for audio tracks." }, "passthrough": { "type": "string", "description": "`passthrough` value the deleted track carried, if any." } }, "required": [ "id" ] }, "ReplacedTracks": { "type": "array", "items": { "$ref": "#/components/schemas/ReplacedTrack" }, "description": "Every track deleted before the new track was created. Present when `replace_existing_tracks` was a deleting policy and at least one track was removed." }, "Resources": { "type": "object", "properties": { "assets": { "type": "array", "items": { "$ref": "#/components/schemas/SlimlineAsset" }, "description": "Mux assets associated with this job." } }, "required": [ "assets" ], "example": { "assets": [ { "id": "abc123asset", "meta": { "title": "My Video", "creator_id": "user123", "external_id": "ext456" }, "_links": { "self": { "href": "https://api.mux.com/video/v1/assets/abc123asset" } } } ] }, "description": "Related Mux resources linked to this job." }, "RunDirectiveRequest": { "type": "object", "properties": { "asset_id": { "type": "string", "minLength": 1, "description": "The bare Mux asset ID to run the directive against, as returned by the Mux Video API." } }, "required": [ "asset_id" ], "example": { "asset_id": "abc123def456" } }, "ShotsResourceDeclaration": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Customer-chosen identifier, unique within the directive. Workflow `inputs` entries reference this handle." }, "type": { "type": "string", "enum": [ "video.asset.shots" ], "description": "The asset's shot-detection output." }, "source": { "$ref": "#/components/schemas/Source" } }, "required": [ "reference_id", "type" ], "example": { "reference_id": "shots", "type": "video.asset.shots", "source": { "via": "mux_api", "action": "request_shots" } } }, "SlimlineAsset": { "type": "object", "properties": { "id": { "type": "string", "description": "Mux asset ID." }, "meta": { "type": "object", "properties": { "title": { "type": "string", "description": "Asset title from Mux metadata." }, "creator_id": { "type": "string", "description": "Creator identifier from Mux metadata." }, "external_id": { "type": "string", "description": "External identifier from Mux metadata." } }, "description": "Mux asset metadata, if available." }, "passthrough": { "type": "string", "description": "Passthrough string from the Mux asset." }, "_links": { "type": "object", "properties": { "self": { "type": "object", "properties": { "href": { "type": "string", "description": "URL to the Mux asset resource." } }, "required": [ "href" ] } }, "required": [ "self" ], "description": "Hypermedia links for the asset." } }, "required": [ "id", "_links" ] }, "Source": { "oneOf": [ { "$ref": "#/components/schemas/SourceExternal" }, { "$ref": "#/components/schemas/SourceRequired" }, { "$ref": "#/components/schemas/SourceWorkflow" }, { "$ref": "#/components/schemas/SourceMuxApi" } ], "discriminator": { "propertyName": "via", "mapping": { "external": "#/components/schemas/SourceExternal", "required": "#/components/schemas/SourceRequired", "workflow": "#/components/schemas/SourceWorkflow", "mux_api": "#/components/schemas/SourceMuxApi" } }, "default": { "via": "external" }, "description": "How the resource is materialized on the asset. Defaults to `{ \"via\": \"external\" }`." }, "SourceExternal": { "type": "object", "properties": { "via": { "type": "string", "enum": [ "external" ] } }, "required": [ "via" ], "title": "SourceExternal", "description": "The resource is produced out-of-band (e.g. a track uploaded directly to the asset). The engine waits for it to appear and become ready." }, "SourceMuxApi": { "oneOf": [ { "$ref": "#/components/schemas/SourceMuxApiGenerateSubtitles" }, { "$ref": "#/components/schemas/SourceMuxApiCreateTrack" }, { "$ref": "#/components/schemas/SourceMuxApiRequestShots" } ], "discriminator": { "propertyName": "action", "mapping": { "generate_subtitles": "#/components/schemas/SourceMuxApiGenerateSubtitles", "create_track": "#/components/schemas/SourceMuxApiCreateTrack", "request_shots": "#/components/schemas/SourceMuxApiRequestShots" } }, "description": "The engine creates the resource by calling the Mux Video API when the resource is absent at run start." }, "SourceMuxApiCreateTrack": { "type": "object", "properties": { "via": { "type": "string", "enum": [ "mux_api" ] }, "action": { "type": "string", "enum": [ "create_track" ], "description": "The Mux Video API call the engine fires to create the resource.", "x-stainless-const": true }, "params": { "$ref": "#/components/schemas/SourceMuxApiCreateTrackParams" } }, "required": [ "via", "action", "params" ], "title": "SourceMuxApiCreateTrack", "description": "Ingest a track file onto the asset from a URL. Text tracks are ingested as subtitles." }, "SourceMuxApiCreateTrackParams": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "description": "Publicly reachable URL of the track file to ingest." }, "language_code": { "type": "string", "minLength": 1, "description": "BCP 47 language code of the track (e.g. \"en\")." }, "type": { "type": "string", "enum": [ "text", "audio" ], "description": "The kind of track to create. \"text\" tracks are ingested as subtitles." } }, "required": [ "url", "language_code", "type" ], "description": "Parameters for the create_track engine action." }, "SourceMuxApiGenerateSubtitles": { "type": "object", "properties": { "via": { "type": "string", "enum": [ "mux_api" ] }, "action": { "type": "string", "enum": [ "generate_subtitles" ], "description": "The Mux Video API call the engine fires to create the resource.", "x-stainless-const": true }, "params": { "$ref": "#/components/schemas/SourceMuxApiGenerateSubtitlesParams" } }, "required": [ "via", "action" ], "title": "SourceMuxApiGenerateSubtitles", "description": "Generate subtitles from the asset's audio using Mux auto-generated captions." }, "SourceMuxApiGenerateSubtitlesParams": { "type": "object", "properties": { "language_code": { "type": "string", "minLength": 1, "description": "BCP 47 language code for the generated subtitles (e.g. \"en\"). Defaults to \"auto\", which detects the language from the audio." }, "source_audio_language": { "type": "string", "minLength": 1, "description": "BCP 47 language code of the audio track to transcribe. When omitted, the first audio track on the asset is used." } }, "description": "Parameters for the generate_subtitles engine action." }, "SourceMuxApiRequestShots": { "type": "object", "properties": { "via": { "type": "string", "enum": [ "mux_api" ] }, "action": { "type": "string", "enum": [ "request_shots" ], "description": "The Mux Video API call the engine fires to create the resource.", "x-stainless-const": true }, "params": { "$ref": "#/components/schemas/SourceMuxApiRequestShotsParams" } }, "required": [ "via", "action" ], "title": "SourceMuxApiRequestShots", "description": "Request the asset's shot-detection output." }, "SourceMuxApiRequestShotsParams": { "type": "object", "properties": { "image_source": { "type": "string", "enum": [ "create_storyboards", "use_shot_midpoint" ], "description": "How shot images are derived. Defaults to \"create_storyboards\"." } }, "description": "Parameters for the request_shots engine action." }, "SourceRequired": { "type": "object", "properties": { "via": { "type": "string", "enum": [ "required" ] } }, "required": [ "via" ], "title": "SourceRequired", "description": "The resource must already be ready on the asset when the run starts. If it is absent, the dependency workflow fails immediately." }, "SourceWorkflow": { "type": "object", "properties": { "via": { "type": "string", "enum": [ "workflow" ] }, "binding": { "type": "string", "minLength": 1, "description": "The reference_id of the workflow binding in this directive that produces the resource." } }, "required": [ "via", "binding" ], "title": "SourceWorkflow", "description": "The resource is produced by another workflow binding in this directive. Dependent workflows wait for that binding to complete and the resource to become ready." }, "SummarizeBinding": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Customer-chosen identifier, unique within the directive. Resource `source.binding` refs point at this handle." }, "workflow": { "type": "string", "enum": [ "summarize" ], "description": "The Robots workflow to dispatch — the same identifier as POST /jobs/{workflow}.", "x-stainless-const": true }, "inputs": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "reference_ids of declared resources this workflow depends on. Each entry is a hard dependency: the workflow is not dispatched until the referenced resource is ready." }, "params": { "$ref": "#/components/schemas/SummarizeBindingParameters" } }, "required": [ "reference_id", "workflow" ], "title": "SummarizeBinding" }, "SummarizeBindingParameters": { "type": "object", "properties": { "tone": { "type": "string", "enum": [ "neutral", "playful", "professional" ], "description": "Tone for the generated summary. \"neutral\" for straightforward analysis, \"playful\" for witty and conversational, \"professional\" for executive-level reporting." }, "output_steering": { "$ref": "#/components/schemas/SummarizeOutputSteering" }, "prompt_overrides": { "type": "object", "properties": { "task": { "type": "string", "minLength": 1, "description": "Override the core task instruction for summarization." }, "title": { "type": "string", "minLength": 1, "description": "Override the title generation requirements." }, "description": { "type": "string", "minLength": 1, "description": "Override the description generation requirements." }, "keywords": { "type": "string", "minLength": 1, "description": "Override the keyword/tag extraction requirements." }, "quality_guidelines": { "type": "string", "minLength": 1, "description": "Override the quality standards for analysis." } }, "description": "Deprecated: use `output_steering`. Raw prompt-section overrides; any section supplied here takes precedence over the equivalent `output_steering` guidance.", "deprecated": true, "x-stainless-deprecation-message": "Use `output_steering` instead." }, "title_length": { "type": "integer", "minimum": 1, "description": "Maximum title length in words." }, "description_length": { "type": "integer", "minimum": 1, "description": "Maximum description length in words." }, "tag_count": { "type": "integer", "minimum": 1, "description": "Maximum number of tags to include in the generated output. Defaults to 10." }, "language_code": { "type": "string", "minLength": 1, "description": "BCP 47 language code of the caption track to analyze (e.g. \"en\", \"fr\"). When omitted, the SDK uses the default track." }, "output_language_code": { "type": "string", "minLength": 1, "description": "BCP 47 language code for the generated summary output (e.g. \"en\", \"fr\", \"ja\"). Auto-detected from the transcript if omitted." }, "update_asset_meta": { "type": "boolean", "description": "When true, the generated title is written to the Mux asset's metadata (asset.meta.title) once the summary completes. Best-effort: a metadata-write failure does not fail the summary." } }, "description": "Parameters for the summarize workflow — the same fields accepted by POST /jobs/summarize, minus engine-supplied fields such as asset_id." }, "SummarizeJob": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique job identifier." }, "passthrough": { "type": "string", "description": "Arbitrary string supplied at creation, returned as-is." }, "units_consumed": { "type": "integer", "minimum": 0, "description": "Number of Mux AI units consumed by this job." }, "directive": { "$ref": "#/components/schemas/JobDirectiveContext" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) when the job was created." }, "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state)." }, "workflow": { "type": "string", "enum": [ "summarize" ] }, "parameters": { "$ref": "#/components/schemas/SummarizeJobParameters" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JobError" }, "description": "Error details. Present when status is 'errored'." }, "resources": { "$ref": "#/components/schemas/Resources" }, "outputs": { "$ref": "#/components/schemas/SummarizeJobOutputs" } }, "required": [ "id", "units_consumed", "created_at", "updated_at", "workflow", "parameters", "status" ] }, "SummarizeJobOutputs": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "description": "Generated title capturing the essence of the video." }, "description": { "type": "string", "minLength": 1, "description": "Generated description of the video content (typically 2-4 sentences)." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Generated keyword tags for the video." } }, "required": [ "title", "description", "tags" ], "example": { "title": "How to Build a Sustainable Garden in Your Backyard", "description": "This video walks through the step-by-step process of creating a sustainable backyard garden, covering soil preparation, plant selection, and organic pest control methods.", "tags": [ "gardening", "sustainability", "backyard", "organic", "soil preparation", "composting", "pest control", "beginner", "how-to", "plants" ] }, "description": "Workflow results. Present when status is 'completed'." }, "SummarizeJobParameters": { "type": "object", "properties": { "asset_id": { "type": "string", "minLength": 1, "description": "The Mux asset ID of the video to summarize." }, "tone": { "type": "string", "enum": [ "neutral", "playful", "professional" ], "description": "Tone for the generated summary. \"neutral\" for straightforward analysis, \"playful\" for witty and conversational, \"professional\" for executive-level reporting." }, "output_steering": { "$ref": "#/components/schemas/SummarizeOutputSteering" }, "prompt_overrides": { "type": "object", "properties": { "task": { "type": "string", "minLength": 1, "description": "Override the core task instruction for summarization." }, "title": { "type": "string", "minLength": 1, "description": "Override the title generation requirements." }, "description": { "type": "string", "minLength": 1, "description": "Override the description generation requirements." }, "keywords": { "type": "string", "minLength": 1, "description": "Override the keyword/tag extraction requirements." }, "quality_guidelines": { "type": "string", "minLength": 1, "description": "Override the quality standards for analysis." } }, "description": "Deprecated: use `output_steering`. Raw prompt-section overrides; any section supplied here takes precedence over the equivalent `output_steering` guidance.", "deprecated": true, "x-stainless-deprecation-message": "Use `output_steering` instead." }, "title_length": { "type": "integer", "minimum": 1, "description": "Maximum title length in words." }, "description_length": { "type": "integer", "minimum": 1, "description": "Maximum description length in words." }, "tag_count": { "type": "integer", "minimum": 1, "description": "Maximum number of tags to include in the generated output. Defaults to 10." }, "language_code": { "type": "string", "minLength": 1, "description": "BCP 47 language code of the caption track to analyze (e.g. \"en\", \"fr\"). When omitted, the SDK uses the default track." }, "output_language_code": { "type": "string", "minLength": 1, "description": "BCP 47 language code for the generated summary output (e.g. \"en\", \"fr\", \"ja\"). Auto-detected from the transcript if omitted." }, "update_asset_meta": { "type": "boolean", "description": "When true, the generated title is written to the Mux asset's metadata (asset.meta.title) once the summary completes. Best-effort: a metadata-write failure does not fail the summary." } }, "required": [ "asset_id" ], "example": { "asset_id": "mux_asset_123abc", "tone": "neutral", "tag_count": 10, "output_steering": { "scope": { "start_time": 30, "end_time": 180 }, "summary_style": "concise", "audience": "Product marketers", "brand_terms": [ "Mux", "Robots" ] } } }, "SummarizeJobResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SummarizeJob" } }, "required": [ "data" ] }, "SummarizeOutputSteering": { "type": "object", "properties": { "scope": { "allOf": [ { "$ref": "#/components/schemas/OutputSteeringScope" }, { "description": "Optional execution window in seconds on the original asset timeline. Omit start_time to begin at the asset start and omit end_time to continue through the asset end. The summary and tags are generated only from media within this window." } ] }, "tag_taxonomy": { "$ref": "#/components/schemas/SummaryTagTaxonomy" }, "summary_style": { "$ref": "#/components/schemas/SummaryStyle" }, "audience": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Intended audience used as best-effort model guidance. Does not change the output schema." }, "brand_terms": { "$ref": "#/components/schemas/OutputSteeringBrandTerms" } }, "description": "Curated output_steering controls for execution scope, summary style, audience, brand terminology, and tag taxonomy. Scope is enforced; other controls guide model behavior but do not guarantee exact output." }, "SummaryStyle": { "type": "string", "enum": [ "concise", "detailed", "editorial" ], "description": "Best-effort style guidance for the generated title and description." }, "SummaryTagTaxonomy": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Optional customer-facing name for the taxonomy, up to 100 characters." }, "values": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Canonical tag value to prefer in generated tags, up to 100 characters." }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Short explanation of when this tag applies, up to 300 characters." }, "aliases": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "maxItems": 10, "description": "Accepted alternate names that should normalize to the canonical label. Up to 10 aliases, each up to 100 characters." } }, "required": [ "label" ] }, "minItems": 1, "maxItems": 50, "description": "Controlled vocabulary values for generated tags. Supports 1-50 values." }, "allow_other": { "type": "boolean", "description": "When false, generated tags are filtered to taxonomy labels and aliases. When true, unmatched tags may remain." } }, "required": [ "values", "allow_other" ], "description": "Controlled vocabulary for tag generation. This steers tags and may be deterministically filtered after generation. Supports up to 50 values and 2000 serialized characters." }, "TrackResourceDeclaration": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Customer-chosen identifier that must be unique within the directive. Workflow `inputs` reference this identifier." }, "type": { "type": "string", "enum": [ "video.asset.track" ], "description": "A caption or audio track on the asset." }, "kind": { "type": "string", "enum": [ "caption", "audio" ], "description": "The track flavor to match: \"caption\" for text tracks, \"audio\" for audio tracks." }, "language": { "type": "string", "minLength": 1, "description": "BCP 47 language code the track must match (e.g. \"en\"). When omitted, any language of the declared kind matches." }, "source": { "$ref": "#/components/schemas/Source" } }, "required": [ "reference_id", "type", "kind" ], "example": { "reference_id": "captions_en", "type": "video.asset.track", "kind": "caption", "language": "en", "source": { "via": "external" } } }, "TranslateAudioBinding": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Customer-chosen identifier, unique within the directive. Resource `source.binding` refs point at this handle." }, "workflow": { "type": "string", "enum": [ "translate-audio" ], "description": "The Robots workflow to dispatch — the same identifier as POST /jobs/{workflow}.", "x-stainless-const": true }, "inputs": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "reference_ids of declared resources this workflow depends on. Each entry is a hard dependency: the workflow is not dispatched until the referenced resource is ready." }, "params": { "$ref": "#/components/schemas/TranslateAudioBindingParameters" } }, "required": [ "reference_id", "workflow", "params" ], "title": "TranslateAudioBinding" }, "TranslateAudioBindingParameters": { "type": "object", "properties": { "to_language_code": { "type": "string", "minLength": 1, "description": "BCP 47 language code for the target translation language (e.g. \"es\", \"fr\", \"ja\")." }, "track_name": { "type": "string", "minLength": 1, "description": "Name for the dubbed Mux audio track. Defaults to \"{Language} (Auto-dubbed)\", e.g. \"Spanish (Auto-dubbed)\". Mux requires audio track names to be unique on an asset, and an existing track with this name is handled according to `replace_existing_tracks`." }, "upload_to_mux": { "type": "boolean", "default": true, "description": "Whether to automatically upload the translated audio track to the Mux asset. Defaults to true." }, "replace_existing_tracks": { "$ref": "#/components/schemas/TranslateAudioReplaceExistingTracks" } }, "required": [ "to_language_code" ], "description": "Parameters for the translate-audio workflow — the same fields accepted by POST /jobs/translate-audio, minus engine-supplied fields such as asset_id." }, "TranslateAudioJob": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique job identifier." }, "passthrough": { "type": "string", "description": "Arbitrary string supplied at creation, returned as-is." }, "units_consumed": { "type": "integer", "minimum": 0, "description": "Number of Mux AI units consumed by this job." }, "directive": { "$ref": "#/components/schemas/JobDirectiveContext" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) when the job was created." }, "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state)." }, "workflow": { "type": "string", "enum": [ "translate-audio" ] }, "parameters": { "$ref": "#/components/schemas/TranslateAudioJobParameters" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JobError" }, "description": "Error details. Present when status is 'errored'." }, "resources": { "$ref": "#/components/schemas/Resources" }, "outputs": { "$ref": "#/components/schemas/TranslateAudioJobOutputs" } }, "required": [ "id", "units_consumed", "created_at", "updated_at", "workflow", "parameters", "status" ] }, "TranslateAudioJobOutputs": { "type": "object", "properties": { "uploaded_track_id": { "type": "string", "minLength": 1, "description": "Mux audio track ID, present when upload_to_mux is true." }, "temporary_audio_url": { "type": "string", "minLength": 1, "description": "Temporary pre-signed URL to download the dubbed audio file. Expires 7 days after the job completes." }, "replaced_tracks": { "$ref": "#/components/schemas/ReplacedTracks" } }, "example": { "uploaded_track_id": "track_es_abc123", "temporary_audio_url": "https://storage.example.com/dubs/es/audio.m4a?token=abc123" }, "description": "Workflow results. Present when status is 'completed'." }, "TranslateAudioJobParameters": { "type": "object", "properties": { "asset_id": { "type": "string", "minLength": 1, "description": "The Mux asset ID of the video to translate." }, "to_language_code": { "type": "string", "minLength": 1, "description": "BCP 47 language code for the target translation language (e.g. \"es\", \"fr\", \"ja\")." }, "track_name": { "type": "string", "minLength": 1, "description": "Name for the dubbed Mux audio track. Defaults to \"{Language} (Auto-dubbed)\", e.g. \"Spanish (Auto-dubbed)\". Mux requires audio track names to be unique on an asset, and an existing track with this name is handled according to `replace_existing_tracks`." }, "upload_to_mux": { "type": "boolean", "default": true, "description": "Whether to automatically upload the translated audio track to the Mux asset. Defaults to true." }, "replace_existing_tracks": { "$ref": "#/components/schemas/TranslateAudioReplaceExistingTracks" } }, "required": [ "asset_id", "to_language_code" ], "example": { "asset_id": "mux_asset_123abc", "to_language_code": "es", "upload_to_mux": true, "replace_existing_tracks": "fail" } }, "TranslateAudioJobResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TranslateAudioJob" } }, "required": [ "data" ] }, "TranslateAudioReplaceExistingTracks": { "type": "string", "enum": [ "fail", "replace_all", "replace_generated" ], "description": "What to do when the asset already has an audio track in the same language as, or with the same name as, the new dubbed track. Defaults to `fail`, which rejects the request before any dubbing is billed. `replace_all` deletes every such track first. Audio tracks are never auto-generated by Mux Video, so `replace_generated` behaves as `fail` here. The asset's primary audio track is never deleted. Any value other than `fail` requires `upload_to_mux` to be true. Existing tracks are matched by language ignoring region subtags, and by name ignoring case, in any status." }, "TranslateCaptionsBinding": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Customer-chosen identifier, unique within the directive. Resource `source.binding` refs point at this handle." }, "workflow": { "type": "string", "enum": [ "translate-captions" ], "description": "The Robots workflow to dispatch — the same identifier as POST /jobs/{workflow}.", "x-stainless-const": true }, "inputs": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "reference_ids of declared resources this workflow depends on. Each entry is a hard dependency: the workflow is not dispatched until the referenced resource is ready." }, "params": { "$ref": "#/components/schemas/TranslateCaptionsBindingParameters" } }, "required": [ "reference_id", "workflow", "params" ], "title": "TranslateCaptionsBinding" }, "TranslateCaptionsBindingParameters": { "type": "object", "properties": { "to_language_code": { "type": "string", "minLength": 1, "description": "BCP 47 language code for the translated output (e.g. \"es\", \"ja\"). Unless replace_existing_tracks allows replacement, the asset must not already have a text track for this language." }, "track_name": { "type": "string", "minLength": 1, "description": "Name for the translated Mux text track. Defaults to \"{Language} (Auto-translated)\", e.g. \"Spanish (Auto-translated)\". Mux requires text track names to be unique on an asset, and an existing track with this name is handled according to `replace_existing_tracks`." }, "upload_to_mux": { "type": "boolean", "default": true, "description": "Whether to upload the translated VTT and attach it as a text track on the Mux asset. Defaults to true." }, "never_translate": { "$ref": "#/components/schemas/TranslateCaptionsNeverTranslateTerms" }, "replace_existing_tracks": { "$ref": "#/components/schemas/TranslateCaptionsReplaceExistingTracks" } }, "required": [ "to_language_code" ], "description": "Parameters for the translate-captions workflow — the same fields accepted by POST /jobs/translate-captions, minus engine-supplied fields such as asset_id." }, "TranslateCaptionsJob": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique job identifier." }, "passthrough": { "type": "string", "description": "Arbitrary string supplied at creation, returned as-is." }, "units_consumed": { "type": "integer", "minimum": 0, "description": "Number of Mux AI units consumed by this job." }, "directive": { "$ref": "#/components/schemas/JobDirectiveContext" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) when the job was created." }, "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state)." }, "workflow": { "type": "string", "enum": [ "translate-captions" ] }, "parameters": { "$ref": "#/components/schemas/TranslateCaptionsJobParameters" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JobError" }, "description": "Error details. Present when status is 'errored'." }, "resources": { "$ref": "#/components/schemas/Resources" }, "outputs": { "$ref": "#/components/schemas/TranslateCaptionsJobOutputs" } }, "required": [ "id", "units_consumed", "created_at", "updated_at", "workflow", "parameters", "status" ] }, "TranslateCaptionsJobOutputs": { "type": "object", "properties": { "uploaded_track_id": { "type": "string", "minLength": 1, "description": "Mux text track ID of the uploaded translated captions. Present when upload_to_mux is true." }, "temporary_vtt_url": { "type": "string", "minLength": 1, "description": "Temporary pre-signed URL to download the translated VTT file. Present when upload_to_mux is true. Expires 7 days after the job completes." }, "never_translate_terms_preserved": { "type": "boolean", "description": "Present when never_translate terms were supplied. False when at least one term was not preserved verbatim in the translated captions. Preservation is best-effort: verified, not guaranteed." }, "replaced_tracks": { "$ref": "#/components/schemas/ReplacedTracks" } }, "example": { "uploaded_track_id": "track_es_abc123", "temporary_vtt_url": "https://storage.example.com/translations/es/captions.vtt?token=abc123", "never_translate_terms_preserved": true }, "description": "Workflow results. Present when status is 'completed'." }, "TranslateCaptionsJobParameters": { "type": "object", "properties": { "asset_id": { "type": "string", "minLength": 1, "description": "The Mux asset ID of the video whose captions will be translated." }, "track_id": { "type": "string", "minLength": 1, "description": "The Mux text track ID of the source caption track to translate. The asset must have a ready text track matching this ID or the request will be rejected." }, "to_language_code": { "type": "string", "minLength": 1, "description": "BCP 47 language code for the translated output (e.g. \"es\", \"ja\"). Unless replace_existing_tracks allows replacement, the asset must not already have a text track for this language." }, "track_name": { "type": "string", "minLength": 1, "description": "Name for the translated Mux text track. Defaults to \"{Language} (Auto-translated)\", e.g. \"Spanish (Auto-translated)\". Mux requires text track names to be unique on an asset, and an existing track with this name is handled according to `replace_existing_tracks`." }, "upload_to_mux": { "type": "boolean", "default": true, "description": "Whether to upload the translated VTT and attach it as a text track on the Mux asset. Defaults to true." }, "never_translate": { "$ref": "#/components/schemas/TranslateCaptionsNeverTranslateTerms" }, "replace_existing_tracks": { "$ref": "#/components/schemas/TranslateCaptionsReplaceExistingTracks" } }, "required": [ "asset_id", "track_id", "to_language_code" ], "example": { "asset_id": "mux_asset_123abc", "track_id": "track_en_abc123", "to_language_code": "es", "upload_to_mux": true, "never_translate": [ "Mux" ], "replace_existing_tracks": "fail" } }, "TranslateCaptionsJobResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TranslateCaptionsJob" } }, "required": [ "data" ] }, "TranslateCaptionsNeverTranslateTerms": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "minItems": 1, "maxItems": 100, "description": "Best-effort list of terms (brand names, proper nouns) to preserve verbatim in the translated captions. Does not guarantee exact output. Terms must not contain '<' or '>', invisible characters, or characters altered by Unicode normalization.", "example": [ "Mux", "Springfield" ] }, "TranslateCaptionsReplaceExistingTracks": { "type": "string", "enum": [ "fail", "replace_all", "replace_generated" ], "description": "What to do when the asset already has a text track in the same language as, or with the same name as, the translated track. Defaults to `fail`, which rejects the request before any translation is billed. `replace_all` deletes every such track first. `replace_generated` deletes only Mux Video auto-generated tracks and rejects if an uploaded track is in the way. Any value other than `fail` requires `upload_to_mux` to be true. Existing tracks are matched by language ignoring region subtags, and by name ignoring case, in any status." }, "WorkflowBinding": { "oneOf": [ { "$ref": "#/components/schemas/SummarizeBinding" }, { "$ref": "#/components/schemas/ModerateBinding" }, { "$ref": "#/components/schemas/GenerateChaptersBinding" }, { "$ref": "#/components/schemas/FindScenesBinding" }, { "$ref": "#/components/schemas/EditCaptionsBinding" }, { "$ref": "#/components/schemas/TranslateCaptionsBinding" }, { "$ref": "#/components/schemas/TranslateAudioBinding" }, { "$ref": "#/components/schemas/AskQuestionsBinding" }, { "$ref": "#/components/schemas/FindKeyMomentsBinding" }, { "$ref": "#/components/schemas/GenerateEngagementInsightsBinding" }, { "$ref": "#/components/schemas/GeneratePremiumCaptionsBinding" }, { "$ref": "#/components/schemas/FindBestThumbnailsBinding" } ], "discriminator": { "propertyName": "workflow", "mapping": { "summarize": "#/components/schemas/SummarizeBinding", "moderate": "#/components/schemas/ModerateBinding", "generate-chapters": "#/components/schemas/GenerateChaptersBinding", "find-scenes": "#/components/schemas/FindScenesBinding", "edit-captions": "#/components/schemas/EditCaptionsBinding", "translate-captions": "#/components/schemas/TranslateCaptionsBinding", "translate-audio": "#/components/schemas/TranslateAudioBinding", "ask-questions": "#/components/schemas/AskQuestionsBinding", "find-key-moments": "#/components/schemas/FindKeyMomentsBinding", "generate-engagement-insights": "#/components/schemas/GenerateEngagementInsightsBinding", "generate-premium-captions": "#/components/schemas/GeneratePremiumCaptionsBinding", "find-best-thumbnails": "#/components/schemas/FindBestThumbnailsBinding" } } }, "RateLimitedResponse": { "type": "object", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "type": "string" }, "description": "Description of the error" } } }, "UnauthorizedResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "messages" ], "properties": { "type": { "type": "string", "description": "The type of the error" }, "messages": { "type": "array", "items": { "type": "string" }, "description": "Friendly messages of errors encountered" } } } } } }, "parameters": { "transcription_vocabulary_id": { "name": "TRANSCRIPTION_VOCABULARY_ID", "in": "path", "description": "The ID of the Transcription Vocabulary.", "required": true, "schema": { "type": "string" } }, "stream_key": { "name": "stream_key", "in": "query", "description": "Filter response to return live stream for this stream key only", "required": false, "schema": { "type": "string" } }, "delivery_usage_asset_id": { "name": "asset_id", "in": "query", "description": "Filter response to return delivery usage for this asset only. You cannot specify both the `asset_id` and `live_stream_id` parameters together.", "required": false, "schema": { "type": "string" } }, "delivery_usage_live_stream_id": { "name": "live_stream_id", "in": "query", "description": "Filter response to return delivery usage for assets for this live stream. You cannot specify both the `asset_id` and `live_stream_id` parameters together.", "required": false, "schema": { "type": "string" } }, "delivery_usage_timeframe": { "name": "timeframe[]", "in": "query", "description": "Time window to get delivery usage information. timeframe[0] indicates the start time, timeframe[1] indicates the end time in seconds since the Unix epoch. Default time window is 1 hour representing usage from 13th to 12th hour from when the request is made.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, "delivery_usage_limit": { "name": "limit", "in": "query", "description": "Number of items to include in the response", "required": false, "schema": { "type": "integer", "format": "int32", "default": 100 } }, "asset_id": { "name": "ASSET_ID", "in": "path", "description": "The asset ID.", "required": true, "schema": { "type": "string" } }, "static_rendition_id": { "name": "STATIC_RENDITION_ID", "in": "path", "description": "The static rendition ID.", "required": true, "schema": { "type": "string" } }, "livestream_id": { "name": "LIVE_STREAM_ID", "in": "path", "description": "The live stream ID", "required": true, "schema": { "type": "string" } }, "playback_id": { "name": "PLAYBACK_ID", "in": "path", "description": "The asset or live stream's playback ID.", "required": true, "schema": { "type": "string" } }, "signing_key_id": { "name": "SIGNING_KEY_ID", "in": "path", "description": "The ID of the signing key.", "required": true, "schema": { "type": "string" } }, "upload_id": { "name": "UPLOAD_ID", "in": "path", "description": "ID of the Upload", "required": true, "example": "abcd1234", "schema": { "type": "string" } }, "playback_restriction_id": { "name": "PLAYBACK_RESTRICTION_ID", "in": "path", "description": "ID of the Playback Restriction.", "required": true, "schema": { "type": "string" } }, "simulcast_target_id": { "name": "SIMULCAST_TARGET_ID", "in": "path", "description": "The ID of the simulcast target.", "required": true, "schema": { "type": "string" } }, "track_id": { "name": "TRACK_ID", "in": "path", "description": "The ID of the track for an asset.", "required": true, "schema": { "type": "string" } }, "list_asset_upload_id": { "name": "upload_id", "in": "query", "description": "Filter response to return an asset created from this direct upload only", "required": false, "schema": { "type": "string" } }, "list_asset_live_stream_id": { "name": "live_stream_id", "in": "query", "description": "Filter response to return all the assets for this live stream only", "required": false, "schema": { "type": "string" } }, "drm_configuration_id": { "name": "DRM_CONFIGURATION_ID", "in": "path", "description": "The DRM Configuration ID.", "required": true, "schema": { "type": "string" } }, "annotation_id": { "name": "ANNOTATION_ID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The annotation ID" }, "incident_id": { "name": "INCIDENT_ID", "in": "path", "description": "ID of the Incident", "required": true, "example": "abcd1234", "schema": { "type": "string" } }, "monitoring_metric_id": { "name": "MONITORING_METRIC_ID", "in": "path", "description": "ID of the Monitoring Metric", "required": true, "example": "current-concurrent-viewers", "schema": { "type": "string", "enum": [ "current-concurrent-viewers", "current-rebuffering-percentage", "exits-before-video-start", "playback-failure-percentage", "current-average-bitrate", "video-startup-failure-percentage" ] } }, "monitoring_histogram_metric_id": { "name": "MONITORING_HISTOGRAM_METRIC_ID", "in": "path", "description": "ID of the Monitoring Histogram Metric", "required": true, "example": "video-startup-time", "schema": { "type": "string", "enum": [ "video-startup-time" ] } }, "monitoring_dimension": { "name": "dimension", "in": "query", "description": "Dimension the specified value belongs to", "required": false, "schema": { "type": "string", "enum": [ "asn", "cdn", "country", "operating_system", "player_name", "region", "stream_type", "sub_property_id", "video_series", "video_title", "view_has_ad" ] } }, "realtime_metric_id": { "name": "REALTIME_METRIC_ID", "in": "path", "description": "ID of the Realtime Metric", "required": true, "example": "current-concurrent-viewers", "schema": { "type": "string", "enum": [ "current-concurrent-viewers", "current-rebuffering-percentage", "exits-before-video-start", "playback-failure-percentage", "current-average-bitrate" ] } }, "realtime_histogram_metric_id": { "name": "REALTIME_HISTOGRAM_METRIC_ID", "in": "path", "description": "ID of the Realtime Histogram Metric", "required": true, "example": "video-startup-time", "schema": { "type": "string", "enum": [ "video-startup-time" ] } }, "realtime_dimension": { "name": "dimension", "in": "query", "description": "Dimension the specified value belongs to", "required": false, "schema": { "type": "string", "enum": [ "asn", "cdn", "country", "operating_system", "player_name", "region", "stream_type", "sub_property_id", "video_series", "video_title" ] } }, "incident_status": { "name": "status", "in": "query", "description": "Status to filter incidents by", "required": false, "schema": { "type": "string", "enum": [ "open", "closed", "expired" ] } }, "severity": { "name": "severity", "in": "query", "description": "Severity to filter incidents by", "required": false, "schema": { "type": "string", "enum": [ "warning", "alert" ] } }, "video_view_id": { "name": "VIDEO_VIEW_ID", "in": "path", "description": "ID of the Video View", "required": true, "example": "abcd1234", "schema": { "type": "string" } }, "engagement_asset_id": { "name": "ASSET_ID", "in": "path", "description": "ID of the Asset", "required": true, "example": "rmp7fvw5lPD01l8PZ2aN74js84XrTWxHy", "schema": { "type": "string" } }, "engagement_video_id": { "name": "VIDEO_ID", "in": "path", "description": "ID of the Video, as provided in the `video_id` metadata field when configuring the player.", "required": true, "example": "abcd1234", "schema": { "type": "string" } }, "engagement_playback_id": { "name": "PLAYBACK_ID", "in": "path", "description": "A Playback ID for the asset.", "required": true, "example": "nLp01dgPzELHV6101iHGXmS3Og7lEU01TUDb02kg2Z6mPRs", "schema": { "type": "string" } }, "hotspots_limit": { "name": "limit", "in": "query", "description": "Maximum number of hotspots to return. If omitted, all hotspots are returned.", "required": false, "schema": { "type": "integer", "format": "int32" } }, "filter_id": { "name": "FILTER_ID", "in": "path", "description": "ID of the Filter", "required": true, "example": "abcd1234", "schema": { "type": "string" } }, "dimension_id": { "name": "DIMENSION_ID", "in": "path", "description": "ID of the Dimension", "required": true, "example": "abcd1234", "schema": { "type": "string" } }, "metric_id": { "name": "METRIC_ID", "in": "path", "description": "ID of the Metric", "required": true, "example": "video_startup_time", "schema": { "type": "string", "enum": [ "aggregate_startup_time", "downscale_percentage", "exits_before_video_start", "live_stream_latency", "max_downscale_percentage", "max_request_latency", "max_upscale_percentage", "page_load_time", "playback_failure_percentage", "playback_success_score", "player_startup_time", "playing_time", "rebuffer_count", "rebuffer_duration", "rebuffer_frequency", "rebuffer_percentage", "request_latency", "request_throughput", "rebuffer_score", "requests_for_first_preroll", "seek_latency", "startup_time_score", "unique_viewers", "upscale_percentage", "video_quality_score", "video_startup_preroll_load_time", "video_startup_preroll_request_time", "video_startup_time", "viewer_experience_score", "views", "weighted_average_bitrate", "video_startup_failure_percentage", "ad_attempt_count", "ad_break_count", "ad_break_error_count", "ad_break_error_percentage", "ad_error_count", "ad_error_percentage", "ad_exit_before_start_count", "ad_exit_before_start_percentage", "ad_impression_count", "ad_startup_error_count", "ad_startup_error_percentage", "playback_business_exception_percentage", "video_startup_business_exception_percentage", "view_content_startup_time", "ad_preroll_startup_time", "view_dropped_percentage", "rendition_change_count", "rendition_upshift_count", "rendition_downshift_count" ] } }, "viewer_id": { "name": "viewer_id", "in": "query", "description": "Viewer ID to filter results by. This value may be provided by the integration, or may be created by Mux.", "required": false, "schema": { "type": "string" } }, "error_id": { "name": "error_id", "in": "query", "description": "Filter video views by the provided error ID (as returned in the error_type_id field in the list video views endpoint). If you provide any as the error ID, this will filter the results to those with any error.", "required": false, "schema": { "type": "integer", "format": "int32" } }, "order_direction": { "name": "order_direction", "in": "query", "description": "Sort order.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, "order_direction_deprecated": { "name": "order_direction", "in": "query", "description": "Sort order.", "deprecated": true, "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, "measurement": { "name": "measurement", "in": "query", "description": "Measurement for the provided metric. If omitted, the default for the metric will be used.\nThe default measurement for each metric is:\n\"sum\" : `ad_attempt_count`, `ad_break_count`, `ad_break_error_count`, `ad_error_count`, `ad_impression_count`, `playing_time`\n\"median\" : `ad_preroll_startup_time`, `aggregate_startup_time`, `content_startup_time`, `max_downscale_percentage`, `max_upscale_percentage`, `page_load_time`, `player_average_live_latency`, `player_startup_time`, `rebuffer_count`, `rebuffer_duration`, `requests_for_first_preroll`, `video_startup_preroll_load_time`, `video_startup_preroll_request_time`, `video_startup_time`, `view_average_request_latency`, `view_average_request_throughput`, `view_max_request_latency`, `weighted_average_bitrate`\n\"avg\" : `ad_break_error_percentage`, `ad_error_percentage`, `ad_exit_before_start_count`, `ad_exit_before_start_percentage`, `ad_playback_failure_percentage`, `ad_startup_error_count`, `ad_startup_error_percentage`, `content_playback_failure_percentage`, `downscale_percentage`, `exits_before_video_start`, `playback_business_exception_percentage`, `playback_failure_percentage`, `playback_success_score`, `rebuffer_frequency`, `rebuffer_percentage`, `seek_latency`, `smoothness_score`, `startup_time_score`, `upscale_percentage`, `video_quality_score`, `video_startup_business_exception_percentage`, `video_startup_failure_percentage`, `view_dropped_percentage`, `viewer_experience_score`\n\"count\" : `started_views`, `unique_viewers`\n", "required": false, "schema": { "type": "string", "enum": [ "95th", "median", "avg", "count", "sum" ] } }, "order_by": { "name": "order_by", "in": "query", "description": "Value to order the results by", "required": false, "schema": { "type": "string", "enum": [ "negative_impact", "value", "views", "field" ] } }, "group_by": { "name": "group_by", "in": "query", "description": "Breakdown value to group the results by", "required": false, "schema": { "type": "string", "enum": [ "asn", "asset_id", "browser", "browser_version", "cdn", "continent_code", "country", "custom_1", "custom_2", "custom_3", "custom_4", "custom_5", "custom_6", "custom_7", "custom_8", "custom_9", "custom_10", "exit_before_video_start", "experiment_name", "live_stream_id", "operating_system", "operating_system_version", "page_type", "page_url", "playback_failure", "playback_business_exception", "playback_id", "player_autoplay", "player_error_code", "player_mux_plugin_name", "player_mux_plugin_version", "player_name", "player_preload", "player_remote_played", "player_software", "player_software_version", "player_version", "preroll_ad_asset_hostname", "preroll_ad_tag_hostname", "preroll_played", "preroll_requested", "region", "source_hostname", "source_type", "stream_type", "sub_property_id", "video_content_type", "video_encoding_variant", "video_id", "video_series", "video_startup_business_exception", "video_startup_failure", "video_title", "view_drm_type", "view_has_ad", "view_session_id", "viewer_connection_type", "viewer_device_category", "viewer_device_manufacturer", "viewer_device_model", "viewer_device_name", "viewer_user_id", "ad_playback_failure", "content_playback_failure", "view_dropped", "client_application_name", "client_application_version", "video_affiliate", "viewer_plan", "viewer_plan_status", "viewer_plan_category", "view_drm_level", "video_brand", "used_pip", "time_shift_enabled", "used_captions", "video_codec", "audio_codec", "video_dynamic_range_type", "view_cdn_edge_pop", "view_cdn_origin", "video_creator_id", "video_cdn_trace", "video_source_height_initial", "video_source_width_initial", "video_source_bitrate_initial", "video_codec_initial", "audio_codec_initial", "video_source_fps_initial", "video_dynamic_range_type_initial", "video_source_fps", "video_source_bitrate", "video_source_height", "video_source_width" ] } }, "filters": { "name": "filters[]", "in": "query", "description": "Filter results using key:value pairs. Must be provided as an array query string parameter.\n\n**Basic filtering:**\n* `filters[]=dimension:value` - Include rows where dimension equals value\n* `filters[]=!dimension:value` - Exclude rows where dimension equals value\n\n**For trace dimensions (like video_cdn_trace):**\n* `filters[]=+dimension:value` - Include rows where trace contains value\n* `filters[]=-dimension:value` - Exclude rows where trace contains value\n* `filters[]=dimension:[value1,value2]` - Exact trace match\n\n**Examples:**\n* `filters[]=country:US` - US views only\n* `filters[]=+video_cdn_trace:fastly` - Views using Fastly CDN\n", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, "monitoring_filters": { "name": "filters[]", "in": "query", "description": "Limit the results to rows that match conditions from provided key:value pairs. Must be provided as an array query string parameter.\n\nTo exclude rows that match a certain condition, prepend a `!` character to the dimension.\n\nPossible filter names are the same as returned by the List Monitoring Dimensions endpoint.\n\nExample:\n\n * `filters[]=operating_system:windows&filters[]=!country:US`\n", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, "metric_filters": { "name": "metric_filters[]", "in": "query", "description": "Limit the results to rows that match inequality conditions from provided metric comparison clauses. Must be provided as an array query string parameter.\n\nPossible filterable metrics are the same as the set of metric ids, with the exceptions of `exits_before_video_start`, `unique_viewers`, `video_startup_failure_percentage`, `view_dropped_percentage`, and `views`.\n\nExample:\n\n * `metric_filters[]=aggregate_startup_time>=1000`\n", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, "timeframe": { "name": "timeframe[]", "in": "query", "description": "Timeframe window to limit results by. Must be provided as an array query string parameter (e.g. timeframe[]=).\n\nAccepted formats are...\n\n * array of epoch timestamps e.g. `timeframe[]=1498867200&timeframe[]=1498953600`\n * duration string e.g. `timeframe[]=24:hours or timeframe[]=7:days`\n", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, "monitoring_timeseries_timeframe": { "name": "timeframe[]", "in": "query", "description": "Timeframe window to limit results by. Must be provided as an array query string parameter (e.g. timeframe[]=).\n\nThe default for this is the last 60 seconds of available data. Timeframes larger than 10 minutes are not allowed, and must be within the last 24 hours.\n", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, "timeseries_group_by": { "name": "group_by", "in": "query", "description": "Time granularity to group results by. If this value is omitted, a default granularity is chosen based on the timeframe.\n\nFor timeframes of less than 90 minutes, the default granularity is `minute`. Between 90 minutes and 6 hours, the default granularity is `ten_minutes`. Between 6 hours and 15 days inclusive, the default granularity is `hour`. The granularity of timeframes that exceed 15 days is `day`. This default behavior is subject to change; it is strongly suggested that you explicitly specify the granularity.\n", "required": false, "schema": { "type": "string", "enum": [ "minute", "ten_minutes", "hour", "day" ] } }, "monitoring_timeseries_limit": { "name": "limit", "in": "query", "description": "Number of items to include in each timestamp's `value` list.\n\nThe default is 10, and the maximum is 100.\n", "required": false, "schema": { "type": "integer", "format": "int32", "default": 10 } }, "dimension": { "name": "dimension", "in": "query", "description": "Dimension the specified value belongs to", "required": false, "schema": { "type": "string", "enum": [ "asn", "asset_id", "browser", "browser_version", "cdn", "continent_code", "country", "custom_1", "custom_2", "custom_3", "custom_4", "custom_5", "custom_6", "custom_7", "custom_8", "custom_9", "custom_10", "exit_before_video_start", "experiment_name", "live_stream_id", "operating_system", "operating_system_version", "page_type", "page_url", "playback_failure", "playback_business_exception", "playback_id", "player_autoplay", "player_error_code", "player_mux_plugin_name", "player_mux_plugin_version", "player_name", "player_preload", "player_remote_played", "player_software", "player_software_version", "player_version", "preroll_ad_asset_hostname", "preroll_ad_tag_hostname", "preroll_played", "preroll_requested", "region", "source_hostname", "source_type", "stream_type", "sub_property_id", "video_content_type", "video_encoding_variant", "video_id", "video_series", "video_startup_failure", "video_startup_business_exception", "video_title", "view_drm_type", "view_has_ad", "view_session_id", "viewer_connection_type", "viewer_device_category", "viewer_device_manufacturer", "viewer_device_model", "viewer_device_name", "viewer_user_id", "ad_playback_failure", "content_playback_failure", "view_dropped", "client_application_name", "client_application_version", "video_affiliate", "viewer_plan", "viewer_plan_status", "viewer_plan_category", "view_drm_level", "video_brand", "used_pip", "time_shift_enabled", "used_captions", "video_codec", "audio_codec", "video_dynamic_range_type", "view_cdn_edge_pop", "view_cdn_origin", "video_creator_id", "video_cdn_trace" ] } }, "value": { "name": "value", "in": "query", "description": "Value to show all available metrics for", "required": false, "schema": { "type": "string" } }, "timestamp": { "name": "timestamp", "in": "query", "description": "Timestamp to limit results by. This value must be provided as a unix timestamp. Defaults to the current unix timestamp.", "required": false, "schema": { "type": "integer", "format": "int32" } }, "monitoring_timeseries_timestamp": { "name": "timestamp", "in": "query", "description": "Timestamp to use as the start of the timeseries data. This value must be provided as a unix timestamp. Defaults to 30 minutes ago.", "required": false, "schema": { "type": "integer", "format": "int32" } }, "subview_metric_id": { "name": "METRIC_ID", "in": "path", "description": "ID of the metric to compute over subviews. Additional metrics may be added over time.", "required": true, "example": "playing_time", "schema": { "type": "string", "enum": [ "playing_time" ] } }, "subview_type": { "name": "SUBVIEW_TYPE", "in": "path", "description": "The subview type to query.", "required": true, "example": "rendition", "schema": { "type": "string", "enum": [ "rendition", "playback_mode" ] } }, "subview_dimension_name": { "name": "DIMENSION_NAME", "in": "path", "description": "Name of the dimension. See the List Subview Dimensions endpoint for the valid values for a given subview type.", "required": true, "example": "country", "schema": { "type": "string" } }, "subview_filters": { "name": "filters[]", "in": "query", "description": "Filter results using key:value pairs. Must be provided as an array query string parameter.\n\nThe set of filterable dimensions is distinct from the main Data API's dimensions, and depends on the subview type — see the List Subview Dimensions endpoint for the valid names.\n\n* `filters[]=dimension:value` - Include rows where dimension equals value\n* `filters[]=!dimension:value` - Exclude rows where dimension equals value\n* `filters[]=dimension:__empty__` - Include rows where the dimension has no value\n\nExample: `filters[]=country:US`\n", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, "subview_group_by": { "name": "group_by[]", "in": "query", "description": "Subview attributes to group the results by. Must be provided as an array query string parameter. Currently only supported for the `rendition` subview type, as any combination of the 6 enum values below.\n\nIf omitted, defaults to grouping by every attribute available for the subview type.\n", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "video_source_bitrate", "video_source_width", "video_source_height", "video_source_fps", "video_source_codec", "video_source_rendition_name" ] } } }, "subview_comparison_dimension": { "name": "dimension", "in": "query", "description": "Name of the dimension to compare across. See the List Subview Dimensions endpoint for the valid values for a given subview type.", "required": true, "example": "country", "schema": { "type": "string" } }, "subview_comparison_values": { "name": "values[]", "in": "query", "description": "The dimension values to compare, up to 4. Must be provided as an array query string parameter. Use `__empty__` to select subviews where the dimension has no value.\n\nExample: `values[]=US&values[]=FR`\n", "required": true, "style": "form", "explode": true, "example": [ "US", "FR" ], "schema": { "type": "array", "maxItems": 4, "items": { "type": "string" } } }, "subview_breakdown_limit": { "name": "limit", "in": "query", "description": "Number of breakdown rows to include in the response.", "required": false, "schema": { "type": "integer", "format": "int32", "default": 25, "maximum": 100 } }, "subview_breakdown_value_limit": { "name": "breakdown_value_limit", "in": "query", "description": "Number of breakdown rows to include per selected dimension value.", "required": false, "schema": { "type": "integer", "format": "int32", "default": 10, "maximum": 100 } }, "subview_time_granularity": { "name": "time_granularity", "in": "query", "description": "Time bucket size for the timeseries.", "required": false, "schema": { "type": "string", "default": "hour", "enum": [ "hour", "day" ] } }, "subview_dimension_values_limit": { "name": "limit", "in": "query", "description": "Number of items to include in the response.", "required": false, "schema": { "type": "integer", "format": "int32", "default": 25, "maximum": 250 } }, "subview_dimension_values_order_by": { "name": "order_by", "in": "query", "description": "Value to order the results by.", "required": false, "schema": { "type": "string", "default": "playing_time", "enum": [ "playing_time", "value" ] } }, "subview_query": { "name": "query", "in": "query", "description": "Only return dimension values containing this substring.", "required": false, "schema": { "type": "string" } }, "webhook_id": { "name": "WEBHOOK_ID", "in": "path", "description": "The ID of the webhook.", "required": true, "schema": { "type": "string" } }, "cursor": { "name": "cursor", "in": "query", "description": "This parameter is used to request pages beyond the first. You can find the cursor value in the `next_cursor` field of paginated responses.", "required": false, "schema": { "type": "string" } }, "limit": { "name": "limit", "in": "query", "description": "Number of items to include in the response", "required": false, "schema": { "type": "integer", "format": "int32", "default": 25 } }, "page": { "name": "page", "in": "query", "description": "Offset by this many pages, of the size of `limit`", "required": false, "schema": { "type": "integer", "format": "int32", "default": 1 } } } }, "x-tagGroups": [ { "name": "Video", "tags": [ "Assets", "Live Streams", "Playback ID", "URL Signing Keys", "Direct Uploads", "Delivery Usage", "Playback Restrictions", "DRM Configurations", "Transcription Vocabularies" ] }, { "name": "Data", "tags": [ "Video Views", "Errors", "Filters", "Exports", "Metrics", "Subview Metrics", "Engagement", "Monitoring", "Real-Time", "Dimensions", "Incidents", "Annotations" ] }, { "name": "System", "tags": [ "Signing Keys", "Usage Exports", "Utilities", "Webhooks" ] }, { "name": "Robots", "tags": [ "Jobs", "Ask Questions", "Edit Captions", "Find Best Thumbnails", "Find Key Moments", "Find Scenes", "Generate Chapters", "Generate Engagement Insights", "Generate Premium Captions", "Moderate", "Summarize", "Translate Audio", "Translate Captions", "Directives" ] } ] }