{ "openapi": "3.0.3", "info": { "title": "Conductor ms", "description": "Conductor microservice configuration API.", "version": "8.0.0", "x-auth": { "prefix": "conductor", "label": "Conductor micro-service API" } }, "paths": { "/versions": { "get": { "tags": [ "Versions" ], "summary": "Get Service Versions.", "description": "Get conductor microservice versions.", "operationId": "getVersions", "x-scopes": [ "administrator", "engineer", "operator", "monitoring", "guest" ], "responses": { "200": { "description": "Returns the conductor microservice versions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Versions" } } } } } } }, "/definition": { "get": { "tags": [ "Definition" ], "summary": "Get Definition.", "description": "Get Conductor microservice configuration API definition.", "operationId": "getDefinition", "x-scopes": [ "administrator", "engineer", "operator", "monitoring", "guest" ], "responses": { "200": { "description": "Returns the Conductor microservice configuration API JSON definition." } } } }, "/documentation": { "get": { "tags": [ "Documentation" ], "summary": "Get Documentation.", "description": "Get Conductor microservice configuration API documentation.", "operationId": "getDocumentation", "x-scopes": [ "administrator", "engineer", "operator", "monitoring", "guest" ], "responses": { "200": { "description": "Returns the Conductor microservice configuration API HTML documentation." } } } }, "/documentation/env": { "get": { "tags": [ "Documentation" ], "summary": "Get Environment Documentation.", "description": "Get Conductor micro-service environment variables documentation.", "operationId": "getEnvDocumentation", "x-scopes": [ "administrator", "engineer", "operator", "monitoring", "guest" ], "responses": { "200": { "description": "Conductor micro-service environment variables HTML documentation." } } } }, "/channels": { "get": { "tags": [ "Channels" ], "summary": "Get channels.", "description": "Get all channel configurations.", "operationId": "getChannels", "x-scopes": [ "administrator", "engineer", "operator", "monitoring", "guest" ], "responses": { "200": { "description": "Returns the list of all channel configurations.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "$ref": "#/components/schemas/ChannelsResponse" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "tags": [ "Channels" ], "summary": "Create or update channels.", "description": "Create or update a list of channel configurations.", "operationId": "createOrUpdateChannels", "x-scopes": [ "administrator", "engineer" ], "parameters": [ { "in": "query", "name": "force", "schema": { "type": "boolean" }, "description": "If true, force the creation of the channel configuration." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Channels" } } } }, "responses": { "200": { "description": "Returns the list of inserted and updated channels.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "$ref": "#/components/schemas/ChannelsResponse" } ] } } } }, "207": { "description": "Returns the list of inserted and updated channels and errors.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "$ref": "#/components/schemas/ChannelsWithFailuresResponse" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "tags": [ "Channels" ], "summary": "Delete channels by ids.", "description": "Delete all targeted channel configurations.", "operationId": "deleteChannels", "x-scopes": [ "administrator", "engineer" ], "parameters": [ { "in": "query", "name": "ids", "schema": { "type": "array", "items": { "type": "string" } }, "required": true, "description": "List of channel ids to delete." } ], "responses": { "204": { "description": "Targeted channel configuration have been deleted." }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/channels/{channel_id}": { "get": { "tags": [ "Channels" ], "summary": "Get channel by id.", "description": "Get targeted channel configuration.", "operationId": "getChannel", "x-scopes": [ "administrator", "engineer", "operator", "monitoring", "guest" ], "parameters": [ { "$ref": "#/components/parameters/ChannelID" } ], "responses": { "200": { "description": "Returns the targeted channel configuration.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "$ref": "#/components/schemas/Channel" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/livez": { "get": { "tags": [ "Monitoring" ], "summary": "Liveness.", "description": "Liveness probe.", "operationId": "Liveness", "x-scopes": [ "administrator", "engineer", "operator", "monitoring", "guest" ], "responses": { "200": { "description": "OK" } } } }, "/readyz": { "get": { "tags": [ "Monitoring" ], "summary": "Readiness.", "description": "Readiness probe.", "operationId": "Readiness", "x-scopes": [ "administrator", "engineer", "operator", "monitoring", "guest" ], "responses": { "204": { "description": "Service is ready." }, "503": { "description": "Service is not ready.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadinessMap" } } } } } } }, "/maintenance": { "get": { "tags": [ "Maintenance" ], "summary": "Get maintenance state", "description": "Get maintenance state of the service.", "operationId": "getMaintenance", "x-scopes": [ "administrator", "engineer", "operator", "monitoring", "guest" ], "responses": { "200": { "description": "Maintenance state.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ResponseGetMaintenance" }, { "$ref": "#/components/schemas/Meta" } ] } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Maintenance" ], "summary": "Set maintenance", "operationId": "setMaintenance", "description": "Set maintenance mode for the service.", "x-scopes": [ "administrator", "engineer" ], "parameters": [ { "in": "query", "name": "keep_on_air", "schema": { "type": "boolean" }, "description": "If true keeps the channels running." } ], "responses": { "204": { "description": "No Content" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "tags": [ "Maintenance" ], "summary": "Unset maintenance", "x-scopes": [ "administrator", "engineer" ], "operationId": "unsetMaintenance", "description": "Unset maintenance mode for the service.", "responses": { "204": { "description": "No Content" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } } }, "components": { "schemas": { "Versions": { "type": "object", "required": [ "chart_version", "image_tag", "api_version" ], "properties": { "chart_version": { "type": "string" }, "image_tag": { "type": "string" }, "api_version": { "type": "string" } } }, "MetaProperties": { "type": "object", "title": "Metadata Properties", "description": "Metadata properties.", "required": [ "api_version" ], "properties": { "api_version": { "type": "string" } } }, "Meta": { "type": "object", "title": "Metadata", "description": "Metadata.", "required": [ "meta" ], "properties": { "meta": { "$ref": "#/components/schemas/MetaProperties" } } }, "Error": { "type": "object", "title": "Error Message", "required": [ "message" ], "properties": { "message": { "type": "string" } } }, "ResponseGetMaintenance": { "type": "object", "title": "Response Get Maintenance", "description": "Get maintenance state response.", "properties": { "results": { "$ref": "#/components/schemas/Maintenance" } }, "required": [ "results" ] }, "Maintenance": { "type": "object", "title": "Maintenance", "description": "Maintenance state.", "required": [ "state" ], "properties": { "state": { "type": "string", "description": "Maintenance state of the service.", "enum": [ "Running", "In Maintenance Running", "In Maintenance Stopped" ] } } }, "ChannelsResponse": { "title": "Channels Response", "description": "Channels Response.", "type": "object", "required": [ "results" ], "properties": { "results": { "$ref": "#/components/schemas/Channels" } } }, "ChannelsWithFailuresResponse": { "type": "object", "title": "Channels With Failures Response", "description": "Mixed channels and channels with failures.", "required": [ "results", "failures" ], "properties": { "results": { "$ref": "#/components/schemas/Channels" }, "failures": { "$ref": "#/components/schemas/ChannelsWithFailures" } } }, "Channels": { "type": "array", "items": { "$ref": "#/components/schemas/Channel" } }, "ChannelsWithFailures": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelWithFailure" } }, "ChannelWithFailure": { "type": "object", "required": [ "channel", "error" ], "properties": { "channel": { "$ref": "#/components/schemas/Channel" }, "error": { "type": "string", "title": "Error", "description": "Error message." } } }, "Channel": { "title": "Channel Configuration", "type": "object", "properties": { "id": { "title": "Channel Configuration ID", "description": "Channel configuration unique id. At creation, if not provided it will be generated.", "type": "string", "format": "uuid" }, "name": { "title": "Channel Configuration Name", "description": "Channel configuration unique name. At creation, if not provided it will be generated.", "type": "string", "minLength": 3, "maxLength": 50 }, "on_air": { "title": "Channel Configuration On Air", "description": "If enabled, channel is available for end-users.", "type": "boolean", "default": false, "x-go-type-skip-optional-pointer": true }, "dash_input": { "$ref": "#/components/schemas/DASHInput" }, "hls_input": { "$ref": "#/components/schemas/HLSInput" } } }, "ReadinessMap": { "type": "object", "additionalProperties": { "type": "boolean" } }, "OriginURL": { "title": "Origin URL", "description": "Origin URL of the input.", "type": "string", "format": "uri", "pattern": "^(((http[s]?://).+)?$|scheduler://[0-9a-f-]+)$" }, "DASHInput": { "title": "DASH Channel Input", "description": "DASH Input of the channel.", "allOf": [ { "$ref": "#/components/schemas/CommonChannelInputFields" }, { "type": "object", "required": [ "origin_url" ], "properties": { "origin_url": { "$ref": "#/components/schemas/OriginURL" }, "dai": { "$ref": "#/components/schemas/DASHDAIConfiguration" } } } ] }, "HLSInput": { "title": "HLS Channel Input", "description": "HLS Input of the channel.", "allOf": [ { "$ref": "#/components/schemas/CommonChannelInputFields" }, { "type": "object", "required": [ "origin_url" ], "properties": { "origin_url": { "$ref": "#/components/schemas/OriginURL" }, "dai": { "$ref": "#/components/schemas/HLSDAIConfiguration" } } } ] }, "CommonChannelInputFields": { "type": "object", "properties": { "output_url": { "$ref": "#/components/schemas/OutputUrl" }, "status": { "$ref": "#/components/schemas/ChannelInputStatus" }, "latency": { "title": "Output latency", "description": "Latency of the output stream in seconds.", "type": "integer", "minimum": 0, "maximum": 30, "default": 0, "x-go-type-skip-optional-pointer": true }, "origin_custom_headers": { "title": "Origin Custom Headers", "description": "Custom headers to add to the origin request.", "type": "object", "additionalProperties": { "type": "string" }, "example": { "X-Custom-Header": "Custom-Value" } } } }, "DASHDAIConfiguration": { "allOf": [ { "$ref": "#/components/schemas/CommonChannelDAIConfigurationFields" }, { "properties": { "midroll": { "$ref": "#/components/schemas/ChannelInputDAIMidroll" }, "preroll": { "$ref": "#/components/schemas/DASHChannelInputDAIPreroll" } } } ] }, "DASHChannelInputDAIPreroll": { "allOf": [ { "$ref": "#/components/schemas/ChannelInputDAIPreroll" }, { "properties": { "start_offset": { "description": "Offset applied on the first DASH period of the preroll Dynamic Ad Insertion (DAI). Slate duration must be >= start_offset.\n", "type": "string", "default": "15s", "x-go-type-skip-optional-pointer": true } } } ] }, "HLSDAIConfiguration": { "allOf": [ { "$ref": "#/components/schemas/CommonChannelDAIConfigurationFields" }, { "properties": { "midroll": { "$ref": "#/components/schemas/HLSChannelInputDAIMidroll" }, "preroll": { "$ref": "#/components/schemas/ChannelInputDAIPreroll" } } } ] }, "HLSChannelInputDAIMidroll": { "allOf": [ { "$ref": "#/components/schemas/ChannelInputDAIMidroll" }, { "properties": { "type": { "$ref": "#/components/schemas/HLSMidrollDAIConfigurationType" } } } ] }, "CommonChannelDAIConfigurationFields": { "title": "Channel DAI Configuration", "description": "Dynamic Ad Insertion configuration of the channel.", "type": "object", "properties": { "enabled": { "title": "DAI Enabled", "description": "If true, Dynamic Ad Insertion (DAI) is enabled for this channel input.", "type": "boolean", "default": false, "x-go-type-skip-optional-pointer": true }, "beaconing": { "$ref": "#/components/schemas/ChannelInputBeaconingMode" }, "sessions": { "$ref": "#/components/schemas/SessionConfiguration" }, "ingest_params": { "$ref": "#/components/schemas/IngestParams" } }, "required": [ "ingest_params" ] }, "MidrollMode": { "title": "Channel Input DAI midroll mode", "description": "DAI midroll mode for the channel input. Fulfill: replace ad break by custom ads and fill the rest with slates. Return To Live: replace ad break by custom ads and return to live. Ad Spot To Live: replace ad break by custom ads and return to live at the end of an ad spot (fulfill until ad spot end if needed).\n", "type": "string", "enum": [ "fulfill", "return_to_live", "ad_spot_to_live" ], "default": "fulfill", "x-go-type-skip-optional-pointer": true }, "OpportunityTrigger": { "title": "Opportunity Trigger", "description": "The trigger used to detect a DAI opportunity. Defaults to trigger on Time Signal splice commands containing a Provider Placement Opportunity Start.\n", "type": "object", "discriminator": { "propertyName": "splice_command_type", "mapping": { "time_signal": "#/components/schemas/TimeSignalCommand", "splice_insert": "#/components/schemas/SpliceInsertCommand" } }, "oneOf": [ { "$ref": "#/components/schemas/TimeSignalCommand" }, { "$ref": "#/components/schemas/SpliceInsertCommand" } ], "default": { "splice_command_type": "time_signal" }, "x-go-type-skip-optional-pointer": true }, "TimeSignalCommand": { "title": "Time Signal Command", "description": "SCTE-35 Time Signal command configuration for DAI opportunity triggering.", "type": "object", "properties": { "splice_command_type": { "title": "Splice Command Type", "description": "The SCTE-35 splice command type for Time Signal.", "type": "string", "enum": [ "time_signal" ], "default": "time_signal", "x-go-type-skip-optional-pointer": true }, "segmentation_type_id": { "$ref": "#/components/schemas/SegmentationTypeID" } } }, "SegmentationTypeID": { "title": "Segmentation Type ID", "description": "The Segmentation type ID that should trigger a DAI opportunity when detected.", "type": "string", "enum": [ "provider_placement_opportunity_start", "break_start" ], "default": "provider_placement_opportunity_start", "x-go-type-skip-optional-pointer": true, "x-enum-descriptions": [ "Provider Placement Opportunity Start (segmentation_type_id: 0x34)", "Break Start (segmentation_type_id: 0x22)" ] }, "SpliceInsertCommand": { "title": "Splice Insert Command", "description": "SCTE-35 Splice Insert command configuration for DAI opportunity triggering.", "type": "object", "properties": { "splice_command_type": { "title": "Splice Command Type", "description": "The SCTE-35 splice command type for Splice Insert.", "type": "string", "enum": [ "splice_insert" ], "default": "splice_insert", "x-go-type-skip-optional-pointer": true } } }, "ChannelInputBeaconingMode": { "type": "string", "title": "Tracking Mode", "description": "Type of tracking mode. Either ClientSide beaconing or ServerSide beaconing.", "enum": [ "ClientSide", "ServerSide" ], "default": "ClientSide", "x-go-type-skip-optional-pointer": true }, "HLSMidrollDAIConfigurationType": { "type": "string", "title": "DAI Type", "description": "Type of the HLS opportunity.", "enum": [ "Interstitial", "Discontinuity" ], "default": "Interstitial", "x-go-type-skip-optional-pointer": true }, "SessionConfiguration": { "title": "Session Configuration", "description": "Session configuration of the channel.", "type": "object", "default": { "ttl": "600s", "keys": { "headers": [ "User-Agent", "X-Forwarded-For" ] } }, "x-go-type-skip-optional-pointer": true, "properties": { "ttl": { "title": "Session Time To Live", "description": "Time to live as duration string. When NEA-Composer does not receive any user request relative to a session for this time to live duration, it automatically deletes the session. Valid time units are \"ns\", \"us\" (or \"µs\"), \"ms\", \"s\", \"m\", \"h\". The minimum value is 1m.\n", "type": "string", "format": "duration", "default": "600s", "x-go-type-skip-optional-pointer": true }, "keys": { "$ref": "#/components/schemas/SessionKeys" } } }, "SessionKeys": { "title": "Session Keys", "description": "NEA-Composer allows specifying the attributes from the end-user request (coming from the CDN), which trigger the creation of a new user session (session keys). This could be some query parameters, or some HTTP headers, or both.\n", "type": "object", "default": { "headers": [ "User-Agent", "X-Forwarded-For" ] }, "x-go-type-skip-optional-pointer": true, "properties": { "headers": { "title": "Session Header Keys", "description": "Session Header keys used for new session creation.", "type": "array", "default": [ "User-Agent", "X-Forwarded-For" ], "x-go-type-skip-optional-pointer": true, "items": { "title": "Header Key", "description": "Header parameter key.", "type": "string" } } } }, "IngestParams": { "title": "Ingest Service Configuration", "description": "Ingest service configuration of the channel input.", "type": "object", "required": [ "ingest_service_id", "encoding_preset", "packaging_preset" ], "properties": { "ingest_service_id": { "title": "Ingest Service Configuration ID", "description": "Unique ID of the Ingest service configuration.", "type": "string", "format": "uuid" }, "encoding_preset": { "title": "Encoding Preset", "description": "The name of the preset, which the external file encoder will use to transcode the content.", "type": "string" }, "packaging_preset": { "title": "Packaging Preset", "description": "the name of the preset, which the external Packager/Origin Server will use to package and ingest the content.", "type": "string" } } }, "ChannelInputDAIMidroll": { "title": "Channel Midroll DAI Configuration", "description": "Midroll Dynamic Ad Insertion configuration of the channel.", "type": "object", "properties": { "enabled": { "title": "Midroll DAI Enabled", "description": "If true, midroll Dynamic Ad Insertion (DAI) is enabled for this channel input. Warning, an ad server and a slate shall be configured.\n", "type": "boolean", "default": false, "x-go-type-skip-optional-pointer": true }, "ad_server_id": { "$ref": "#/components/schemas/AdServerConfigurationId" }, "slate_id": { "$ref": "#/components/schemas/SlateId" }, "mode": { "$ref": "#/components/schemas/MidrollMode" }, "opportunity_trigger": { "$ref": "#/components/schemas/OpportunityTrigger" }, "max_unfilled_duration": { "title": "Max Unfilled Duration", "description": "Defines the maximum allowable difference between the original ad break duration and the replacement ads' durations. A value of 0 seconds allows ad replacement regardless of the replacement ads' durations.", "type": "string", "default": "0s", "x-go-type-skip-optional-pointer": true } }, "required": [ "ad_server_id", "slate_id" ] }, "ChannelInputDAIPreroll": { "title": "Channel Preroll DAI Configuration", "description": "Preroll Dynamic Ad Insertion configuration of the channel input.", "type": "object", "properties": { "enabled": { "title": "Preroll DAI Enabled", "description": "If true, preroll Dynamic Ad Insertion (DAI) is enabled for this channel input. Warning, an ad server and a slate shall be configured.\n", "type": "boolean", "default": false, "x-go-type-skip-optional-pointer": true }, "ad_server_id": { "$ref": "#/components/schemas/AdServerConfigurationId" }, "slate_id": { "$ref": "#/components/schemas/SlateId" }, "duration": { "title": "Ad Break Duration", "description": "Duration of the preroll ad break as duration string.", "type": "string", "default": "60s", "x-go-type-skip-optional-pointer": true } }, "required": [ "ad_server_id", "slate_id" ] }, "SlateId": { "title": "Slate ID", "description": "Unique ID of the slate used in the DAI. This field is mandatory as soon as DAI is enabled.", "type": "string", "format": "uuid" }, "AdServerConfigurationId": { "title": "Ad Server Configuration ID", "description": "Unique ID of the ad server configuration. This field is mandatory as soon as DAI is enabled.", "type": "string", "format": "uuid" }, "OutputUrl": { "title": "Output URL", "description": "URL of the output.", "type": "string", "readOnly": true }, "ChannelInputStatus": { "title": "Channel Input Status", "description": "Status of the Channel input. OK if the NEA-Composer is able to fetch source stream. Error if the NEA-Composer is not able to fetch source stream. Inactive if the origin server has not been fetched yet or channel is stopped.\n", "type": "string", "enum": [ "OK", "Error", "Inactive" ], "default": "Inactive", "readOnly": true } }, "parameters": { "ChannelID": { "name": "channel_id", "in": "path", "description": "Channel unique identifier.", "required": true, "schema": { "type": "string", "format": "uuid" } } }, "responses": { "BadRequest": { "description": "Bad Request.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "$ref": "#/components/schemas/Error" } ] } } } }, "NotFound": { "description": "Not Found.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "$ref": "#/components/schemas/Error" } ] } } } }, "InternalServerError": { "description": "Internal Server Error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "$ref": "#/components/schemas/Error" } ] } } } }, "ServiceUnavailable": { "description": "Service Unavailable.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }