API docs by Redocly

M2A Connect (2.0)

Download OpenAPI specification:Download

E-mail: connect@m2ameda.tv License: Proprietary License

Specification for the M2A Connect API.

organisations

Organisations are the top of the M2A Cloud resource hierarchy. They represent the encompassing notion of ownership - a single Organisation can span multiple Target Accounts. User permissions are scoped first and foremost at an Organisation level. The first step to getting started with M2A Cloud is by having your Organisation created. This Organisation will act as the unifying construct for every resource M2A Cloud manages on your behalf.

Get a list of organisations.

Get a list of organisations.

Authorizations:
bearerAuth

Responses

Create an organisation.

Create an organisation.

Authorizations:
bearerAuth
Request Body schema: application/json
required
required
object (organisation-config)

Organization-specific configuration settings

required
object (standard_metadata)

Metadata labels for organizing and identifying resources

Responses

Request samples

Content type
application/json
{
  • "config": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "config": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "metadata": {
    }
}

Get an Organisation.

Get an Organisation.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

Responses

Response samples

Content type
application/json
{
  • "config": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "metadata": {
    }
}

Delete an Organisation.

Delete an Organisation.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

Responses

Response samples

Content type
application/json
{
  • "message": "Success"
}

target-accounts

Target Accounts sit immediately beneath Organisations in the resource hierarchy, with all other resources beneath them. A single Target Account represents an AWS account that is managed by one or more M2A Cloud products. Any Cloud resources that are underpinned by real AWS resources will ultimately need to be bound to or parented by a Target Account. Target Accounts can take different roles in the distribution of media with Connect, generally "providers" will have logins to the M2A Cloud console and/or clients for the M2A Connect APIs, while "subscribers" will be Target Accounts at which configuration can be pointed (especially) entitlements. Target Accounts provide a mechanism by which an Organisation can provide permission scoped access to subset of their resources. For example: a broadcaster, Skii Sports, has configured M2A Connect to carry their live content. They have a number of customers, many of which recieve some specific subset of that content depending on preconfigured rules. Connect manages those rules for them, ensuring the content arrives on time and in the correct format. Skii Sports has a special arrangement with a partner, Board Watchers, in which Board Watchers can choose to take a specific subset of Skii Sport content but according to Board Watchers whim - they might want "Murder on Mont Blanc" as long as Avalanche Anderson is racing, but as soon as he finishes they'll want to switch over to "Snowbody Knows Me". Skii Sports has a Target Account provisioned for their friends at Board Watchers, granting Board Watchers a restricted access to their Organisation. Board Watchers can use their Target Account to perform their own content management, on behalf of Skii Sports and in-line with their agreement.

Get a list of Target Accounts.

Get a list of Target Accounts.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

Responses

Create a new Target Account.

Create a new Target Account.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

Request Body schema: application/json
required
Array of objects or objects (action-notifications)
aws-account-number
required
string (aws-account-number)

The AWS account number.

required
object (standard_metadata)

Metadata labels for organizing and identifying resources

proxy-whitelist
required
Array of strings (proxy-whitelist) [^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\...]

A list of CIDR blocks which will have permission to view the proxy streams for all sources created under this target account.

setup-run-iac-process
boolean (setup-run-iac-process)

If true, the CF IAC processes will be run on this target account.

Responses

Request samples

Content type
application/json
{
  • "action-notifications": [
    ],
  • "aws-account-number": "string",
  • "metadata": {
    },
  • "proxy-whitelist": [
    ],
  • "setup-run-iac-process": false
}

Response samples

Content type
application/json
{
  • "action-notifications": [
    ],
  • "aws-account-number": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "metadata": {
    },
  • "proxy-whitelist": [
    ],
  • "setup-run-iac-process": false
}

Get a Target Account.

Get a Target Account.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

Responses

Response samples

Content type
application/json
{
  • "action-notifications": [
    ],
  • "aws-account-number": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "metadata": {
    },
  • "proxy-whitelist": [
    ],
  • "setup-run-iac-process": false
}

Delete a Target Account.

Delete a Target Account.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

Responses

Response samples

Content type
application/json
{
  • "message": "Success"
}

networks

The network endpoint provides clients of the M2A Connect API to interact with the network configuration of the specified Target Account, especially with reference to VPC interfaces. This is particularly useful for establishing the options available when creating resources that require VPC interfaces.

Get a list of networks VPCs for a target account.

Get a list of networks VPCs for a target account.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

Responses

Response samples

Content type
application/json
{
  • "vpcs": [
    ]
}

events

Events are the mechanism by which a user of Connect can enable their video workflow, how ever its been configured, to come to life. Scheduled Events must target at least one Source. Once scheduled, the targeted Source will be orchestrated according to the life-cycle of the event, ensuring video is made available. For example: Skii Sports have loaded their Event schedule in to Connect via the Events API endpoint for the coming season. Some of those Events target a single Source, the different slopes of Mont Blanc, but other Events, such as the opening day ceremony, are scheduled across every Source. Each Source is live for only as long as it needs to be to ensure the Event that is running has all the correct video.

Get a events for a target account.

Get events for a target account.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

query Parameters
inline
boolean

Whether to inline the event data in the response. Default is false

interval
string
Example: interval=2020-08-01T00:00:00Z/P1D

Optional time range to list events for. Only events whose duration intersect or overlap the given range will be returned. Both lower and upper bounds are inclusive. If no events intersect or overlap the range, then the list of events will be empty. Time range to search for is given as an ISO 8601 interval.

last-evaluated-key
string <byte>

The last evaluated key returned from the response. To be used to request the next page of results.

page-size
integer

The maximum number of events that may be returned. A request may return fewer than the value of page-size.

Responses

Create a new Event for a Target Account.

Create a new Event for a Target Cccount.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

Request Body schema: application/json
required
end-time
required
string <date-time> (end-time)

The time at which all streaming processes should end. This cannot be before the scheduled on-air-end-time of an event has passed.

required
object (standard_metadata)

Metadata labels for organizing and identifying resources

on-air-end-time
required
string <date-time> (on-air-end-time)

The on-air-start-time and on-air-end-time allow a client of the API to define an arbitrary time window within the event's start-time and end-time. This window might be used by the client, for example, to distinguish between the line up and show time. The on-air-end-time must not follow the events end-time.

on-air-start-time
required
string <date-time> (on-air-start-time)

The on-air-start-time and on-air-end-time allow a client of the API to define an arbitrary time window within the event's start-time and end-time. This window might be used by the client, for example, to distinguish between the line up and show time. The on-air-start-time must not precede the events start-time.

resource-ids
required
Array of strings <uuid> (resource-ids) [ items <uuid > ]

The resource-ids property is an array of unique identifiers for resources that are associated with the event. The resources will be of M2A Connect sources.

start-time
required
string <date-time> (start-time)

The time at which all streaming processes should begin. This must not be after the scheduled on-air-start-time of an event. This might be used, for example, to send bars and tone to check the readiness of the system.

Responses

Request samples

Content type
application/json
{
  • "end-time": "2019-01-01T00:00:00Z",
  • "metadata": {
    },
  • "on-air-end-time": "2019-01-01T00:00:00Z",
  • "on-air-start-time": "2019-01-01T00:00:00Z",
  • "resource-ids": [
    ],
  • "start-time": "2019-01-01T00:00:00Z"
}

Response samples

Content type
application/json
{
  • "end-time": "2019-01-01T00:00:00Z",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "metadata": {
    },
  • "on-air-end-time": "2019-01-01T00:00:00Z",
  • "on-air-start-time": "2019-01-01T00:00:00Z",
  • "resource-ids": [
    ],
  • "start-time": "2019-01-01T00:00:00Z"
}

Get an event by its unique ID.

Get a event by its unique ID.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

event-id
required
string <uuid>

The ID of the event.

Responses

Response samples

Content type
application/json
{
  • "end-time": "2019-01-01T00:00:00Z",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "metadata": {
    },
  • "on-air-end-time": "2019-01-01T00:00:00Z",
  • "on-air-start-time": "2019-01-01T00:00:00Z",
  • "resource-ids": [
    ],
  • "start-time": "2019-01-01T00:00:00Z"
}

Update a event for a target account.

Update a event for a target account.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

event-id
required
string <uuid>

The ID of the event.

Request Body schema: application/json
required

The event update payload.

end-time
string <date-time> (end-time)

The time at which all streaming processes should end. This cannot be before the scheduled on-air-end-time of an event has passed.

object (standard_metadata)

Metadata labels for organizing and identifying resources

on-air-end-time
string <date-time> (on-air-end-time)

The on-air-start-time and on-air-end-time allow a client of the API to define an arbitrary time window within the event's start-time and end-time. This window might be used by the client, for example, to distinguish between the line up and show time. The on-air-end-time must not follow the events end-time.

on-air-start-time
string <date-time> (on-air-start-time)

The on-air-start-time and on-air-end-time allow a client of the API to define an arbitrary time window within the event's start-time and end-time. This window might be used by the client, for example, to distinguish between the line up and show time. The on-air-start-time must not precede the events start-time.

resource-ids
Array of strings <uuid> (resource-ids) [ items <uuid > ]

The resource-ids property is an array of unique identifiers for resources that are associated with the event. The resources will be of M2A Connect sources.

start-time
string <date-time> (start-time)

The time at which all streaming processes should begin. This must not be after the scheduled on-air-start-time of an event. This might be used, for example, to send bars and tone to check the readiness of the system.

Responses

Request samples

Content type
application/json
{
  • "end-time": "2019-01-01T00:00:00Z",
  • "metadata": {
    },
  • "on-air-end-time": "2019-01-01T00:00:00Z",
  • "on-air-start-time": "2019-01-01T00:00:00Z",
  • "resource-ids": [
    ],
  • "start-time": "2019-01-01T00:00:00Z"
}

Response samples

Content type
application/json
{
  • "end-time": "2019-01-01T00:00:00Z",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "metadata": {
    },
  • "on-air-end-time": "2019-01-01T00:00:00Z",
  • "on-air-start-time": "2019-01-01T00:00:00Z",
  • "resource-ids": [
    ],
  • "start-time": "2019-01-01T00:00:00Z"
}

Delete a event for a target account.

Delete a event for a target account.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

event-id
required
string <uuid>

The ID of the event.

Responses

Response samples

Content type
application/json
{
  • "message": "Success"
}

sources

Sources are the natural ingest point for video in to Connect. Once provisioned, a Source presents an interface to which any upstream process can send video. Sources can be configured in a variety of ways to suit the specific needs of the video distribution system. They can reliably move video accross large distances, offering flexibility, security, reliability, and "just in time" costs. When a Source has a running Event that targets it, the Source is said to be active. Video can be moved back out of a Source by routing the Source in to one or more Outputs. This routing can be managed automatically, based on the configuration of the Outputs and Sources, or as a manual process. For example: Skii Sports have 82 Sources configured, two for each of the slopes on Mont Blanc. Connect turns the Sources on or off every day according to the schedule. While active, the video moving through the Source is routed to any downstream system.

Get a list of Sources for a target account.

Get a list of Sources for a target account.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

query Parameters
include-deleted
boolean

Option to return sources that have been marked as deleted.

include-hidden
boolean

Option to return sources that have been marked as hidden.

inline
boolean

Whether to inline the event data in the response. Default is false

last-evaluated-key
string <byte>

The last evaluated key returned from the response. To be used to request the next page of results.

page-size
integer

The maximum number of events that may be returned. A request may return fewer than the value of page-size.

Responses

Create a new Source for a Target Account.

Create a new Source for a Target Cccount.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

Request Body schema: application/json
required
object (alarm)

Alarm configuration and status for monitoring source health

egress-regions
required
Array of strings (egress-region)

AWS regions where egress flows will be created for content distribution

entitlement-prefix
required
string (entitlement-prefix) ^[a-zA-Z1-9_-]{1,42}$

A custom name to be attached as a prefix to all entitlements created for this source. NOTE: Changing this field after the creation of entitlements will require all subscribers to update their subscriptions, and should be done with caution.

required
Array of objects = 1 items

A list of flow sources to use in source creation.

ingress-region
required
string (ingress-region)

The name of the region where video will be ingested.

hidden
boolean

Source visibility. Toggle attribute to hide source from batch queries.

required
object (standard_metadata)

Metadata labels for organizing and identifying resources

Responses

Request samples

Content type
application/json
{
  • "alarm": {
    },
  • "egress-regions": [
    ],
  • "entitlement-prefix": "string",
  • "ingress-flows": [
    ],
  • "ingress-region": "string",
  • "hidden": true,
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "alarm": {
    },
  • "egress-flow-arns": [
    ],
  • "egress-regions": [
    ],
  • "entitlement-prefix": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "desired-state": "creating",
  • "ingress-flows": [
    ],
  • "ingress-region": "string",
  • "metadata": {
    },
  • "proxies": {},
  • "proxy-enabled": true,
  • "provisioned-flows": {
    },
  • "provisioning-error-reason": "string",
  • "provisioning-status": "creation-pending",
  • "provisioning-status-timestamp": "2019-08-24T14:15:22Z"
}

Get a Source by its unique ID.

Get a Source by its unique ID.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

source-id
required
string <uuid>

The ID of the Source.

Responses

Response samples

Content type
application/json
{
  • "alarm": {
    },
  • "egress-flow-arns": [
    ],
  • "egress-regions": [
    ],
  • "entitlement-prefix": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "desired-state": "creating",
  • "ingress-flows": [
    ],
  • "ingress-region": "string",
  • "metadata": {
    },
  • "proxies": {},
  • "proxy-enabled": true,
  • "provisioned-flows": {
    },
  • "provisioning-error-reason": "string",
  • "provisioning-status": "creation-pending",
  • "provisioning-status-timestamp": "2019-08-24T14:15:22Z"
}

Update a Source for a target account.

Update a Source for a target account.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

source-id
required
string <uuid>

The ID of the Source.

Request Body schema: application/json
required

The Source update payload.

object (alarm)

Alarm configuration and status for monitoring source health

egress-regions
Array of strings (egress-region)

AWS regions where egress flows will be created for content distribution

entitlement-prefix
string (entitlement-prefix) ^[a-zA-Z1-9_-]{1,42}$

A custom name to be attached as a prefix to all entitlements created for this source. NOTE: Changing this field after the creation of entitlements will require all subscribers to update their subscriptions, and should be done with caution.

Array of objects = 1 items

A list of flow sources to use in source creation.

ingress-region
string (ingress-region)

The name of the region where video will be ingested.

object (standard_metadata)

Metadata labels for organizing and identifying resources

Responses

Request samples

Content type
application/json
{
  • "alarm": {
    },
  • "egress-regions": [
    ],
  • "entitlement-prefix": "string",
  • "ingress-flows": [
    ],
  • "ingress-region": "string",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "alarm": {
    },
  • "egress-flow-arns": [
    ],
  • "egress-regions": [
    ],
  • "entitlement-prefix": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "desired-state": "creating",
  • "ingress-flows": [
    ],
  • "ingress-region": "string",
  • "metadata": {
    },
  • "proxies": {},
  • "proxy-enabled": true,
  • "provisioned-flows": {
    },
  • "provisioning-error-reason": "string",
  • "provisioning-status": "creation-pending",
  • "provisioning-status-timestamp": "2019-08-24T14:15:22Z"
}

Delete a Source for a target account.

Delete a Source for a target account.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

source-id
required
string <uuid>

The ID of the Source.

Responses

Response samples

Content type
application/json
{
  • "message": "Success"
}

Get high-level description of the status for a Source.

Get high-level description of the status for a Source.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

source-id
required
string <uuid>

The ID of the Source.

Responses

Response samples

Content type
application/json
{
  • "health": {
    },
  • "running-status": "running"
}

Get metrics for a Source.

Get metrics for a Source.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

source-id
required
string <uuid>

The ID of the Source.

query Parameters
desired,
string

A comma-seperated list of keys for desired metrics. Unknown keys are ignored.,

end-time
string <date-time>

The latest time in the desired time series. If not provided, the current time is used.

start-time
string <date-time>

The earliest time in the desired time series. If not provided, a sensible default is selected.

Responses

Response samples

Content type
application/json
{
  • "series": [
    ]
}

destinations

Destinations allow a user to define the configuration of a down stream system. Having configured a Destination, the user can attach the Destination to an Output and, provided the Output has an active Source routed in to it, video will flow to that configured reciever. Destinations can be attached to none or more Outputs, and any subsequent changes to the Destination will be reflected in the configuration of those Outputs. For example: Skii Sports have configured a number of Destinations, one for each of their UK based partners, all of whom take RTMP. They have configured another set of Destinations, this time for the German partners, all of whom take RTP. When one of their German partners wants to recieve content on a different port, a Skii Sports operator can update the respective Destination and all Outputs using that Destination will be reconfigured to reflect the change.

Get a list of Destinations for a Target Account.

Get a list of Destinations for a Target Account.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

Responses

Response samples

Content type
application/json
Example

Create a new Destination for a Target Account.

Create a new Destination for a Target Cccount.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

Request Body schema: application/json
required
One of
availability-zone
string (availability-zone)
Enum: "us-east-2a" "us-east-2b" "us-east-2c" "us-east-1a" "us-east-1b" "us-east-1c" "us-east-1d" "us-east-1e" "us-east-1f" "us-west-1a" "us-west-1c" "us-west-2a" "us-west-2b" "us-west-2c" "us-west-2d" "af-south-1a" "af-south-1b" "af-south-1c" "ap-east-1a" "ap-east-1b" "ap-east-1c" "ap-south-1a" "ap-south-1b" "ap-south-1c" "ap-northeast-3a" "ap-northeast-3b" "ap-northeast-3c" "ap-northeast-2a" "ap-northeast-2b" "ap-northeast-2c" "ap-northeast-2d" "ap-southeast-1a" "ap-southeast-1b" "ap-southeast-1c" "ap-southeast-2a" "ap-southeast-2b" "ap-southeast-2c" "ap-northeast-1a" "ap-northeast-1c" "ap-northeast-1d" "ca-central-1a" "ca-central-1b" "ca-central-1d" "eu-central-1a" "eu-central-1b" "eu-central-1c" "eu-west-1a" "eu-west-1b" "eu-west-1c" "eu-west-2a" "eu-west-2b" "eu-west-2c" "eu-south-1a" "eu-south-1b" "eu-south-1c" "eu-west-3a" "eu-west-3b" "eu-west-3c" "eu-north-1a" "eu-north-1b" "eu-north-1c" "me-south-1a" "me-south-1b" "me-south-1c" "sa-east-1a" "sa-east-1b" "sa-east-1c"

AWS Availability zone for which the configuration applies.

destination-ip
required
string (destination-ip)

IP address of the destination.

enabled
required
boolean (enabled)

Whether the configuration is enabled, making media routed into the output available in the given region. If enabling the configuration would exceed the limit set by the distributor's offer or an attempt is made to enable a region that is not permitted by the distributor's offer, then the request will be rejected.

object (standard_metadata)

Metadata labels for organizing and identifying resources

Array of objects
name
required
string (name) [A-Za-z0-9-_]{1,64}

Name of the AWS MediaConnect output/entitlement as it will appear in the MediaConnect Flow. Must be Unique for the M2A Output.

port
required
integer (port)

Port used by the destination, must be unique for all destinations of this destination's type that are attached to the same Output.

region
required
string (region)

The AWS region name to put the resource in

vpc-interface-name
required
string (vpc-interface-name)

Name of vpc interface to select from those configured for a Source's ingress flow or attached Output

destination-type
required
string (type-cdi)
Value: "cdi"

The type of output.

Responses

Request samples

Content type
application/json
Example
{
  • "destination-type": "entitlement",
  • "enabled": true,
  • "encryption-settings": {
    },
  • "entitled-target-account-id": "dfd2fe01-44e4-484f-88b6-dcc7af8b3ca1",
  • "metadata": {
    },
  • "name": "ent1",
  • "region": "eu-west-1"
}

Response samples

Content type
application/json
Example
{
  • "destination-type": "entitlement",
  • "enabled": true,
  • "encryption-algorithm": "aes128",
  • "encryption-secret-arn": "arn:aws:secretsmanager:eu-west-1:452147389173:secret:m2a/connect/destination/002-LWTxfI",
  • "encryption-settings": {
    },
  • "entitled-target-account-id": "dfd2fe01-44e4-484f-88b6-dcc7af8b3ca1",
  • "id": "1fce5dea-4d3f-43a0-991b-48821712ffbb",
  • "metadata": {
    },
  • "name": "ent1",
  • "owner-id": "d27988cf-47fb-444f-a89e-ea051be360c0",
  • "region": "eu-west-1"
}

Get a Destination by its unique ID.

Get a Destination by its unique ID.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

destination-id
required
string <uuid>

The ID of the destination.

query Parameters
label
string <byte>

Find any resource with matching label and key. The label is a key-value pair with a comman acting as the delimiter. For example, to find all resources with a key of foo and a value of bar, the query would be label=foo,bar. Where multiple labels are provided, they are ANDed together. For example, label=foo,bar&label=spam,eggs would only match resources that have both foo=bar and spam=eggs.

Responses

Response samples

Content type
application/json
Example
{
  • "destination-type": "entitlement",
  • "enabled": true,
  • "encryption-algorithm": "aes128",
  • "encryption-secret-arn": "arn:aws:secretsmanager:eu-west-1:452147389173:secret:m2a/connect/destination/002-LWTxfI",
  • "encryption-settings": {
    },
  • "entitled-target-account-id": "dfd2fe01-44e4-484f-88b6-dcc7af8b3ca1",
  • "id": "1fce5dea-4d3f-43a0-991b-48821712ffbb",
  • "metadata": {
    },
  • "name": "ent1",
  • "owner-id": "d27988cf-47fb-444f-a89e-ea051be360c0",
  • "region": "eu-west-1"
}

Delete a Destination for a target account.

Delete a Destination for a target account.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

destination-id
required
string <uuid>

The ID of the destination.

Responses

Response samples

Content type
application/json
{
  • "message": "Success"
}

Update a Destination for a target account.

Update a Destination for a target account.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

destination-id
required
string <uuid>

The ID of the destination.

Request Body schema: application/json
required

The Destination update payload.

One of
availability-zone
string (availability-zone)
Enum: "us-east-2a" "us-east-2b" "us-east-2c" "us-east-1a" "us-east-1b" "us-east-1c" "us-east-1d" "us-east-1e" "us-east-1f" "us-west-1a" "us-west-1c" "us-west-2a" "us-west-2b" "us-west-2c" "us-west-2d" "af-south-1a" "af-south-1b" "af-south-1c" "ap-east-1a" "ap-east-1b" "ap-east-1c" "ap-south-1a" "ap-south-1b" "ap-south-1c" "ap-northeast-3a" "ap-northeast-3b" "ap-northeast-3c" "ap-northeast-2a" "ap-northeast-2b" "ap-northeast-2c" "ap-northeast-2d" "ap-southeast-1a" "ap-southeast-1b" "ap-southeast-1c" "ap-southeast-2a" "ap-southeast-2b" "ap-southeast-2c" "ap-northeast-1a" "ap-northeast-1c" "ap-northeast-1d" "ca-central-1a" "ca-central-1b" "ca-central-1d" "eu-central-1a" "eu-central-1b" "eu-central-1c" "eu-west-1a" "eu-west-1b" "eu-west-1c" "eu-west-2a" "eu-west-2b" "eu-west-2c" "eu-south-1a" "eu-south-1b" "eu-south-1c" "eu-west-3a" "eu-west-3b" "eu-west-3c" "eu-north-1a" "eu-north-1b" "eu-north-1c" "me-south-1a" "me-south-1b" "me-south-1c" "sa-east-1a" "sa-east-1b" "sa-east-1c"

AWS Availability zone for which the configuration applies.

destination-ip
required
string (destination-ip)

IP address of the destination.

enabled
required
boolean (enabled)

Whether the configuration is enabled, making media routed into the output available in the given region. If enabling the configuration would exceed the limit set by the distributor's offer or an attempt is made to enable a region that is not permitted by the distributor's offer, then the request will be rejected.

object (standard_metadata)

Metadata labels for organizing and identifying resources

Array of objects
name
required
string (name) [A-Za-z0-9-_]{1,64}

Name of the AWS MediaConnect output/entitlement as it will appear in the MediaConnect Flow. Must be Unique for the M2A Output.

port
required
integer (port)

Port used by the destination, must be unique for all destinations of this destination's type that are attached to the same Output.

region
required
string (region)

The AWS region name to put the resource in

vpc-interface-name
required
string (vpc-interface-name)

Name of vpc interface to select from those configured for a Source's ingress flow or attached Output

destination-type
required
string (type-cdi)
Value: "cdi"

The type of output.

Responses

Request samples

Content type
application/json
Example
{
  • "destination-type": "entitlement",
  • "enabled": true,
  • "encryption-settings": {
    },
  • "entitled-target-account-id": "dfd2fe01-44e4-484f-88b6-dcc7af8b3ca1",
  • "metadata": {
    },
  • "name": "ent1",
  • "region": "eu-west-1"
}

Response samples

Content type
application/json
Example
{
  • "availability-zone": "us-east-2a",
  • "destination-ip": "string",
  • "enabled": true,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "metadata": {
    },
  • "media-stream-output-configurations": [
    ],
  • "name": "string",
  • "owner-id": "50a713e3-a276-45c1-a171-9cd4e179c533",
  • "port": 0,
  • "region": "string",
  • "vpc-interface-name": "string",
  • "destination-type": "cdi"
}

attachments

Attachments are how Outputs can be configured depending on what has been defined in the Destination. Each Attachment links exactly one Output to one Destination. When the Output has an active Source routed to it, the system configuration necessary for the down stream taker of the Destination will be advertised in the corresponding Attachment. Deleting an Attachment removes the link between an Output and a Destination. For example: Skii Sports have created Attachments for their even numbered Outputs and their RTMP Destinations, and their odd numbered Outputs and their RTP Destinations. These Attachments ensure changes to any Destination are reflected in the Output, and that the resources provisioned to enable streaming are made available to the user.

Get a list of Output Attachments for a Target Account.

Get a list of Output Attachments for a Target Account.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

query Parameters
destination-id
required
string <uuid>

The ID of the destination.

output-id
required
string <uuid>

The ID of the Output.

Responses

Response samples

Content type
application/json
{
  • "destination-id": "0f3e31cc-cbaf-4d2c-8c48-805f1b67bbd0",
  • "output-id": "ae61e643-3cc5-42aa-ad48-ed13c97d39d2"
}

Create a new Output Attachment for a Target Account.

Create a new Output Attachment for a Target Cccount.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

Request Body schema: application/json
required
destination-id
required
string <uuid> (resource-id)

The unique identifier of the resource. This is a UUID.

output-id
required
string <uuid> (resource-id)

The unique identifier of the resource. This is a UUID.

Responses

Request samples

Content type
application/json
{
  • "destination-id": "0f3e31cc-cbaf-4d2c-8c48-805f1b67bbd0",
  • "output-id": "ae61e643-3cc5-42aa-ad48-ed13c97d39d2"
}

Response samples

Content type
application/json
{
  • "destination-id": "0f3e31cc-cbaf-4d2c-8c48-805f1b67bbd0",
  • "output-id": "ae61e643-3cc5-42aa-ad48-ed13c97d39d2"
}

output-offers

Output Offers define the rules and configuration for how video content should be made available through Outputs. When an Output Offer is created, it specifies what kind of content should flow through an Output and how that content should be configured for downstream receivers.

Get a list of Output Offers for a Target Account.

Get a list of Output Offers for a Target Account.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

query Parameters
inline
boolean

Whether to inline the event data in the response. Default is false

page-size
integer

The maximum number of events that may be returned. A request may return fewer than the value of page-size.

Responses

Create a new Output Offer for a Target Account.

Create a new Output Offer for a Target Cccount.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

Request Body schema: application/json
required
address-durability
string (address-durability)
Enum: "ephemeral" "persistent"

Determines whether the resulting output will offer persistent or potentially ephemeral addressing. Persistent addressing implies that an endpoint address should never change for the lifetime of the output. Ephemeral does not give such a guarantee. For example, any user-requested change in the routing into the output could cause an address change. Additionally, the service may trigger a reconfiguration for operational or any other reason as it sees fit. Whilst changes should be infrequent and should not occur during events, users in ephemeral mode should always confirm the current address before use. The actual type of addressing used is dependent on the type of the output (eg, ARN for Entitlements). Persistent addressing may be useful where there are downstream workflow elements which are dependent on static configuration. For example equipment behind a firewall may require a fixed output source IP address for ACL configuration, or a consumer of Entitlements may require that the Entitlement ARN does not change regardless of the Source received via that Entitlement. Persistent addressing requires additional underlying infrastructure and, as such, attracts a higher running cost during active use. Address durability cannot be changed after the creation of the output.

cross-region-routing
boolean (cross-region-routing)

Whether or not outputs can be routed cross-region. When enabled, Connect inputs and outputs may exist in different AWS regions.

required
object (_destinations_config)

This is configuration of destination media protocols enforced by the distributor.

enabled
required
boolean (offer-enabled)

Whether or not the output is enabled. When disabled, no media will be routed to the output.

failover-switching
boolean
Default: false

Whether failover switching is enabled for this output offer.

event-query
required
string (event-query)

Which events to route into the output expressed as a selector. A selector can be either the value of an event key metadata or an event value metadata. It needs to match strictly with either of one. If empty, then all active events are taken as candidates for routing into the output. See source selector. Also note that the subscriber may further refine the set of events with their own, similar selector.

required
object (standard_metadata)

Metadata labels for organizing and identifying resources

required
object (regions)
source-query
required
string (source-query)

Which sources to route into the output expressed as a selector. A selector can be either the value of an event key metadata or an event value metadata. It needs to match strictly with either of one. Restricts the set of sources as yielded by the active event selector down to, ideally, a single source. Only the sources for events that were previously matched are considered. If the combination of selectors would result in more than one source being routed into the output then no sources are routed to the output. Also note that the subscriber may further refine the set of sources with their own, similar selector.

Array of objects
Default: []

List of VPC interfaces for the output offer.

Responses

Request samples

Content type
application/json
{
  • "address-durability": "ephemeral",
  • "cross-region-routing": true,
  • "destinations-config": {
    },
  • "enabled": true,
  • "failover-switching": false,
  • "event-query": "string",
  • "metadata": {
    },
  • "regions": {
    },
  • "source-query": "string",
  • "vpc-interfaces": [ ]
}

Response samples

Content type
application/json
{
  • "active-source": "string",
  • "address-durability": "ephemeral",
  • "cross-region-routing": true,
  • "destinations-config": {
    },
  • "enabled": true,
  • "event-query": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "metadata": {
    },
  • "regions": {
    },
  • "selection": "string",
  • "source-query": "string"
}

Get an Output Offer by its unique ID.

Get an Output Offer by its unique ID.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

offer-id
required
string <uuid>

The ID of the offer.

Responses

Response samples

Content type
application/json
{
  • "active-source": "string",
  • "address-durability": "ephemeral",
  • "cross-region-routing": true,
  • "destinations-config": {
    },
  • "enabled": true,
  • "event-query": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "metadata": {
    },
  • "regions": {
    },
  • "selection": "string",
  • "source-query": "string"
}

Update an Output Offer for a target account.

Update an Output Offer for a target account.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

offer-id
required
string <uuid>

The ID of the offer.

Request Body schema: application/json
required

The Output Offer update payload.

address-durability
string (address-durability)
Enum: "ephemeral" "persistent"

Determines whether the resulting output will offer persistent or potentially ephemeral addressing. Persistent addressing implies that an endpoint address should never change for the lifetime of the output. Ephemeral does not give such a guarantee. For example, any user-requested change in the routing into the output could cause an address change. Additionally, the service may trigger a reconfiguration for operational or any other reason as it sees fit. Whilst changes should be infrequent and should not occur during events, users in ephemeral mode should always confirm the current address before use. The actual type of addressing used is dependent on the type of the output (eg, ARN for Entitlements). Persistent addressing may be useful where there are downstream workflow elements which are dependent on static configuration. For example equipment behind a firewall may require a fixed output source IP address for ACL configuration, or a consumer of Entitlements may require that the Entitlement ARN does not change regardless of the Source received via that Entitlement. Persistent addressing requires additional underlying infrastructure and, as such, attracts a higher running cost during active use. Address durability cannot be changed after the creation of the output.

cross-region-routing
boolean (cross-region-routing)

Whether or not outputs can be routed cross-region. When enabled, Connect inputs and outputs may exist in different AWS regions.

object (_destinations_config)

This is configuration of destination media protocols enforced by the distributor.

enabled
boolean (offer-enabled)

Whether or not the output is enabled. When disabled, no media will be routed to the output.

encrypted-routing
boolean

Whether encrypted routing is enabled for this output offer.

failover-switching
boolean
Default: false

Whether failover switching is enabled for this output offer.

event-query
string (event-query)

Which events to route into the output expressed as a selector. A selector can be either the value of an event key metadata or an event value metadata. It needs to match strictly with either of one. If empty, then all active events are taken as candidates for routing into the output. See source selector. Also note that the subscriber may further refine the set of events with their own, similar selector.

object (standard_metadata)

Metadata labels for organizing and identifying resources

object (regions)
source-query
string (source-query)

Which sources to route into the output expressed as a selector. A selector can be either the value of an event key metadata or an event value metadata. It needs to match strictly with either of one. Restricts the set of sources as yielded by the active event selector down to, ideally, a single source. Only the sources for events that were previously matched are considered. If the combination of selectors would result in more than one source being routed into the output then no sources are routed to the output. Also note that the subscriber may further refine the set of sources with their own, similar selector.

Array of objects

List of VPC interfaces for the output offer.

Responses

Request samples

Content type
application/json
{
  • "address-durability": "ephemeral",
  • "cross-region-routing": true,
  • "destinations-config": {
    },
  • "enabled": true,
  • "encrypted-routing": true,
  • "failover-switching": false,
  • "event-query": "string",
  • "metadata": {
    },
  • "regions": {
    },
  • "source-query": "string",
  • "vpc-interfaces": [
    ]
}

Response samples

Content type
application/json
{
  • "active-source": "string",
  • "address-durability": "ephemeral",
  • "cross-region-routing": true,
  • "destinations-config": {
    },
  • "enabled": true,
  • "event-query": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "metadata": {
    },
  • "regions": {
    },
  • "selection": "string",
  • "source-query": "string"
}

Delete an Output Offer for a target account.

Delete an Output Offer for a target account.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

offer-id
required
string <uuid>

The ID of the offer.

Responses

Response samples

Content type
application/json
{
  • "message": "Success"
}

output-selections

Output Selections represent the actual routing decisions that connect Sources to Outputs. When a Selection is made, it determines which Source's video will flow through which Output based on the configured rules.

Get a list of Output Selections for a Target Account.

Get a list of Output Selections for a Target Account. If inline is passed will retrieve full Output Selection records instead of resource URLs. The status field will reflect the actual provisioning state of the selection (AVAILABLE if provisioned with an ARN, UNAVAILABLE otherwise)

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

query Parameters
include-deleted
boolean

Option to return sources that have been marked as deleted.

inline
boolean

Whether to inline the event data in the response. Default is false

last-evaluated-key
string <byte>

The last evaluated key returned from the response. To be used to request the next page of results.

page-size
integer

The maximum number of events that may be returned. A request may return fewer than the value of page-size.

active-only
boolean

When true, only return selections that have a source currently routed to it. Default is false.

Responses

Response samples

Content type
application/json
Example
{
  • "items": [
    ],
  • "last-evaluated-key": null
}

Get an output selection by ID.

Get an output selection by ID.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

selection-id
required
string <uuid>

The ID of the Selection.

Responses

Response samples

Content type
application/json
Example
{
  • "active-source": "36d5666c-b3cf-4927-81cd-276fed2fc0eb",
  • "destinations": {
    },
  • "event-query": "",
  • "id": "33df0ede-83a4-47a9-ba1c-76e7e5cf8711",
  • "metadata": {
    },
  • "offer": {
    },
  • "routing-evaluation": {
    },
  • "source-query": "36d5666c-b3cf-4927-81cd-276fed2fc0eb"
}

Update an output with a selection by its ID.

Update an output with a selection by its ID.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

selection-id
required
string <uuid>

The ID of the Selection.

Request Body schema: application/json
required

The Output Selection update payload.

required
object

Destination configurations for the output, each key of this object represents a list of destinations of that type.

required
object (standard_metadata)

Metadata labels for organizing and identifying resources

event-query
required
string (event-query)

Which events to route into the output expressed as a selector. A selector can be either the value of an event key metadata or an event value metadata. It needs to match strictly with either of one. If empty, then all active events are taken as candidates for routing into the output. See source selector. Also note that the subscriber may further refine the set of events with their own, similar selector.

source-query
required
string (source-query)

Which sources to route into the output expressed as a selector. A selector can be either the value of an event key metadata or an event value metadata. It needs to match strictly with either of one. Restricts the set of sources as yielded by the active event selector down to, ideally, a single source. Only the sources for events that were previously matched are considered. If the combination of selectors would result in more than one source being routed into the output then no sources are routed to the output. Also note that the subscriber may further refine the set of sources with their own, similar selector.

address-durability
string (address-durability)
Enum: "ephemeral" "persistent"

Determines whether the resulting output will offer persistent or potentially ephemeral addressing. Persistent addressing implies that an endpoint address should never change for the lifetime of the output. Ephemeral does not give such a guarantee. For example, any user-requested change in the routing into the output could cause an address change. Additionally, the service may trigger a reconfiguration for operational or any other reason as it sees fit. Whilst changes should be infrequent and should not occur during events, users in ephemeral mode should always confirm the current address before use. The actual type of addressing used is dependent on the type of the output (eg, ARN for Entitlements). Persistent addressing may be useful where there are downstream workflow elements which are dependent on static configuration. For example equipment behind a firewall may require a fixed output source IP address for ACL configuration, or a consumer of Entitlements may require that the Entitlement ARN does not change regardless of the Source received via that Entitlement. Persistent addressing requires additional underlying infrastructure and, as such, attracts a higher running cost during active use. Address durability cannot be changed after the creation of the output.

Responses

Request samples

Content type
application/json
Example
{
  • "destinations": {
    },
  • "event-query": "",
  • "metadata": {
    },
  • "source-query": "36d5666c-b3cf-4927-81cd-276fed2fc0eb"
}

Response samples

Content type
application/json
Example
{
  • "active-source": "36d5666c-b3cf-4927-81cd-276fed2fc0eb",
  • "destinations": {
    },
  • "event-query": "",
  • "id": "33df0ede-83a4-47a9-ba1c-76e7e5cf8711",
  • "metadata": {
    },
  • "offer": {
    },
  • "routing-evaluation": {
    },
  • "source-query": "36d5666c-b3cf-4927-81cd-276fed2fc0eb"
}

Create a new destination for an output selection.

Create a new destination for an output selection. Destinations can be configured with encryption settings, including passphrases for SRT protocols or AES keys for Zixi and Entitlement protocols. The encryption settings support algorithm and protocol validation to ensure compatibility.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

selection-id
required
string <uuid>

The ID of the Selection.

Request Body schema: application/json
required

The destination to create with optional encryption settings.

One of
required
object

Responses

Request samples

Content type
application/json
Example
{
  • "entitlement": {
    }
}

Response samples

Content type
application/json
Example
{
  • "selection-id": "33df0ede-83a4-47a9-ba1c-76e7e5cf8711",
  • "entitlement": {
    }
}

Get a destination by its unique ID.

Retrieve full destination properties including decrypted encryption settings. The passphrase or key will be returned in the response for authorized clients.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

selection-id
required
string <uuid>

The ID of the Selection.

destination-id
required
string <uuid>

The ID of the destination.

Responses

Response samples

Content type
application/json
Example
{
  • "selection-id": "33df0ede-83a4-47a9-ba1c-76e7e5cf8711",
  • "entitlement": {
    }
}

Update a destination for an output selection.

Update an existing destination including its encryption settings. The encryption-settings object will be completely replaced if provided. Attempts to update while encryption status is PENDING will be rejected with 409 Conflict. Valid algorithm/protocol combinations must be maintained.

Authorizations:
bearerAuth
path Parameters
organisation-id
required
string <uuid>

The ID of the owning Organistion.

target-account-id
required
string <uuid>

The ID of the owning Target Account.

selection-id
required
string <uuid>

The ID of the Selection.

destination-id
required
string <uuid>

The ID of the destination.

Request Body schema: application/json
required

The updated destination payload. Encryption-settings can be modified, added, or removed by omitting the property.

One of
required
object

Responses

Request samples

Content type
application/json
Example
{
  • "entitlement": {
    }
}

Response samples

Content type
application/json
Example
{
  • "selection-id": "33df0ede-83a4-47a9-ba1c-76e7e5cf8711",
  • "entitlement": {
    }
}