API docs by Redocly

M2A Stream Endpoint Discovery External API (v1)

Download OpenAPI specification:Download

URL: https://m2amedia.tv/docs License: MIT

Endpoints to perform CRUD (create, read, update, delete) operations on stream-endpoints.

Stream Endpoints

The Stream Endpoints API will allow users of m2a product like workflow to retrieve stream playback endpoints to be used for streaming. Terminology

  • An endpoint will contain the streaming protocol and the url that is needed to playback a video stream.
  • An endpoint has a publication state that indicates the last publication change that applied to the endpoint
    • Published means that the endpoint is now available, although this does not guarantee that media is flowing through the pipeline, so it is possible that attempting to stream from a published endpoint still results in errors e.g. if the source feed into the video pipeline is down
    • Unpublished means that the endpoint is no longer available, and attempting to stream from it my result in errors
  • A change feed is provided to indicate which endpoints have been subject to recent publication changes

Retrieve list of stream endpoints

This endpoint will return a changed feed of all the latest changes made to endpoints, including changes to publication state.

This API should be called periodically to discover new endpoints. It should not be called more than once every 60 seconds for any given customer account.

This list notes which records have changed along with each record's last-updated timestamp and metadata labels (such as the endpoint name). It does not include the full record detail like the endpoint URLs or streaming protocol. The full record details for changed records should be retrieved using the get endpoints API. The change feed does not include the endpoint details to avoid any misinterpretation due to processing changes in the wrong order - by doing a separate lookup for each endpoint record the calling application will always see up-to-date data.

By default the API will return the recent changes made in the last 24 hours.

The response may be split across multiple 'pages' if there are lots of results. The 'next' link should be followed if present to retrieve more results, and this process should be repeated until the response does not have a next URI

Use the filter[last_updated] query string parameter to get a smaller set of changes. The API will get all the endpoints changed after the supplied last_updated query parameter. The calling application can use this to optimise the number of records that need to be processed over successive calls to this API by remembering the largest last-updated value seen on any record processed so far, and supplying that value on subsequent API calls. This will avoid returning all endpoints changed in the last 24 hours on every invocation.

Authorizations:
BearerAuth
query Parameters
owner
required
string <uuid>
Example: owner=7845419f-ca72-4cb1-b769-1bed5d8700b0

Target account ID

filter[last_updated]
string <date-time>
Example: filter[last_updated]=2023-06-14T14:00:00.000+00:00

This field is optional and can be used to filter the response by specifying results that were last updated after a given time. If this field is not present, the result set will include only those that have been updated in the last 24 hours. If the provided value is more than 24 hours in the past, the service will still only return results from the past 24 hours. It is not possible to extend the time window for events beyond 24 hours.

next
string
Example: next=UHl0aG9uIGlzIGF3ZXNvbWUh

A base64 encoded key to the next page of stream-endpoints

header Parameters
Accept
required
string
Example: application/vnd.api+json

Content type (expressed as MIME types)the client is able to understand.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "links": {
    },
  • "data": [
    ]
}

Retrieve list of stream endpoints

Retrieve the list of stream endpoints for an owner.

The owner query parameter is required. The result set may then be refined with these optional filters:

  • publication-state — filter by publication state.
  • at most one relationship[...] parameter — relationship[event], relationship[workflow-instance], relationship[encoder] or relationship[packager].

The relationship filters are mutually exclusive: supplying more than one in a single request is rejected with a 400 Bad Request. The supported filter combinations are:

Filters Supported
owner only yes
owner + publication-state yes
owner + one relationship[...] yes
owner + one relationship[...] + publication-state yes
owner + more than one relationship[...] no — 400 Bad Request

The response may be split across multiple 'pages' if there are lots of results. The 'next' link should be followed if present to retrieve more results.

Authorizations:
BearerAuth
query Parameters
owner
required
string <uuid>
Example: owner=7845419f-ca72-4cb1-b769-1bed5d8700b0

Target account ID

relationship[event]
string <uuid>
Example: relationship[event]=4875419f-ca72-4cb1-b769-1bed5d8700b0

Related event id

relationship[workflow-instance]
string <uuid>
Example: relationship[workflow-instance]=1235419f-ca72-4cb1-b769-1bed5d8700b0

Related workflow instance id

relationship[encoder]
string <uuid>
Example: relationship[encoder]=9c2e1f4a-7b3d-4e8a-9f10-2c5d6e7a8b9c

Related MediaLive encoder id

relationship[packager]
string <uuid>
Example: relationship[packager]=5a8b3c2d-1e9f-4a7b-8c6d-3e2f1a0b9c8d

Related MediaPackage packager id

publication-state
string
Enum: "PUBLISHED" "UNPUBLISHED" "PRETX"
Example: publication-state=PUBLISHED

This field is optional and can be used to filter out the endpoints by publication state

next
string
Example: next=UHl0aG9uIGlzIGF3ZXNvbWUh

A base64 encoded key to the next page of stream-endpoints

header Parameters
Accept
required
string
Example: application/vnd.api+json

Content type (expressed as MIME types)the client is able to understand.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "links": {
    }
}

Retrieve Information for a Specific Stream Endpoint

This endpoint allows retrieval of detailed information for a specific stream endpoint, identified by its unique ID. It provides key attributes such as streaming protocol, URL, last updated timestamp, publication state, and associated metadata.

This API will no longer allow retrieval of the endpoint record more than 48 hours after its publication-state changes to UNPUBLISHED.

Authorizations:
BearerAuth
path Parameters
endpoint_id
required
string
query Parameters
owner
required
string <uuid>
Example: owner=7845419f-ca72-4cb1-b769-1bed5d8700b0

Target account ID

header Parameters
Accept
required
string
Example: application/vnd.api+json

Content type (expressed as MIME types)the client is able to understand.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}