Download OpenAPI specification:Download
The M2A Schedule API replaces the Events API (see https://cloud.m2amedia.tv/docs/html/connect/events.html) to allow for additional resource types to be scheduled.
event
is a period of time during which resources need to be activated.
An event has a start and an end time, and, an On Air start and end timeenrolment
is an M2A resource that can be managed by the schedule.
Current supported resource types are source
and workflow
. Additonal
resource types will be added in the future as they are deployed. One or
more resources may be enrolled in an event.mediainput
identifies logical media input to the event and is used to order
the events on the vertical axis of the schedule view. Currently only a M2A
Connect Source is supported, and the values for mediainput
will be the same
as the list of enrolments
. In the future, the console view will be updated
to allow different resource types to be modelled as the media input - ie
an M2A Connect output.API users can perform CRUD operations to manage events in the schedule.
The API is modelled on JSONAPI (https://jsonapi.org/format/). Where possible related resources are modelled as Relationships. ie:
Owner can be only of type target-account
.
Each mediainput and enrolment must be of type source
or workflow
.
Each mediainput and enrolment must exist for this owner
otherwise
resource not found error will occur.
The following headers are required for all requests -
{
'Accept': 'application/vnd.api+json',
'Content-Type': 'application/vnd.api+json'
}
The following structure is used for schedule event object:
{
'data': {
'type': 'event',
'attributes': {...},
'relationships': {
'enrolments': {
'data': [
{
'id': ...,
'type': ...
}
]
},
'mediainputs': {
'data': [
{
'id': ...,
'type': ...
}
]
}
'owner': {
'data': {
'id': ...,
'type': 'target-account'
}
}
}
}
}
Schedule event attributes are described in more detail below.
This endpoint supports listing all events for the specific owner. The following query parameters can be used to filter events:
filter[interval]
: list events which fall within specified time
intervalfilter[end-time]
: list events which end after the specified end
timefilter[enrolment]
: list events linked to the enrolment with a
specified type and with a specified idfilter[mediainput]
: list events linked to the mediainput with a
specified type and with a specified idQuery parameter fields[event]
allows to specify which event
attributes or relationships to include along with type
and id
in
each event object in the list.
You can find more details about query parameters below.
The schedule events list is paginated. Each page contains up to 50 events.
The following structure is used for the response where data
contains
a list of event objects and next
contains an url of the next page of
events:
{
'data': [...],
'links': {
'next': ...
}
}
owner required | string <uuid> (Resource identifier) Example: owner=c49c499b-4e7e-4acb-ae83-f528b6ed194d The id of the target account |
object Event list filters | |
object Sparse fields |
Content-Type required | string (JSON API) Value: "application/vnd.api+json" The original media type of the resource. |
Accept required | string (JSON API) Value: "application/vnd.api+json" Content type (expressed as MIME types) the client is able to understand. |
{- "links": {
- "next": "/api/schedule/v1/events/?next=eyJwayI6IHsiUyI6ICIwOThjNzM0NC05N jQ5LTQyYWUtYTA5Ny0xMzJjN2ZiYWZjNTMjYTM3OWIzYmYtNGFmMi00ZThkLWE4N mEtZGY0MjRmNGY3YmUwIn0sICJzayI6IHsiUyI6ICJvd25lciMwOThjNzM0NC05N jQ5LTQyYWUtYTA5Ny0xMzJjN2ZiYWZjNTMifSwgImVuZF90aW1lIjogeyJTIjogI jIwMjItMDktMTNUMTg6MTQ6MTUuMzMwNDUzKzAwMDAifX0%3D&owner=098c7344 -9649-42ae-a097-132c7fbafc53"
}, - "data": [
- {
- "attributes": {
- "name": "Example name",
- "description": "This is event description.",
- "start-time": "2023-06-14T14:00:00+00:00",
- "on-air-start-time": "2023-06-14T14:15:00+00:00",
- "on-air-end-time": "2023-06-14T15:15:00+00:00",
- "end-time": "2023-06-14T15:30:00+00:00",
- "state": "CONFIRMED",
- "metadata": {
- "labels": [
- {
- "key": "m2amedia.tv:organisation-id",
- "value": "25fb8cc0-d04d-4b2e-955b-055d4888f2ea"
}, - {
- "key": "m2amedia.tv:target-account-name",
- "value": "Example account name"
}
]
}, - "created": "2023-06-13T15:09:44.912038+00:00",
- "updated": "2023-06-14T13:51:19.068152+00:00",
- "last-modified-by": "d1af38c6-f980-4830-b75d-bf9452c69c1a",
- "event-policies": { }
}, - "relationships": {
- "owner": {
- "data": {
- "id": "7e2f2cf8-5ca3-4b66-b4e6-89633ef85fac",
- "type": "target-account"
}
}, - "mediainputs": {
- "data": [
- {
- "id": "6863be6d-2392-4a69-9841-e6356b63607c",
- "type": "source"
}
]
}
}, - "type": "event",
- "id": "c49c499b-4e7e-4acb-ae83-f528b6ed194d"
}
]
}
The endpoint for creating a schedule event.
Type must be specified as event
.
Attributes name
, start-time
, on-air-start-time
,
on-air-end-time
, end-time
, metadata
must be included in payload.
Event time value requirements:
start-time
must be earlier than on-air-start-time
value,on-air-start-time
value must be earlier than on-air-end-time
value,on_air_end_time
value must be earlier than end-time
valueOwner and at least one mediainput must be specified in payload relationships.
The default state for created event is CONFIRMED
. Alternatively,
DRAFT
state can be specified in payload.
Content-Type required | string (JSON API) Value: "application/vnd.api+json" The original media type of the resource. |
Accept required | string (JSON API) Value: "application/vnd.api+json" Content type (expressed as MIME types) the client is able to understand. |
object (Primary data) Primary data with an event request body. |
{- "data": {
- "attributes": {
- "state": "CONFIRMED",
- "metadata": {
- "labels": [
- {
- "key": "dazn.com:content:oaid",
- "value": "rnhzn7w1jn7g1l4ec862ewxjs"
}
]
}, - "name": "Example name",
- "description": "This is event description.",
- "start-time": "2023-06-14T14:00:00+00:00",
- "on-air-start-time": "2023-06-14T14:15:00+00:00",
- "on-air-end-time": "2023-06-14T15:15:00+00:00",
- "end-time": "2023-06-14T15:30:00+00:00"
}, - "relationships": {
- "enrolments": {
- "data": [
- {
- "type": "source",
- "id": "6863be6d-2392-4a69-9841-e6356b63607c"
}
]
}, - "mediainputs": {
- "data": [
- {
- "type": "source",
- "id": "6863be6d-2392-4a69-9841-e6356b63607c"
}
]
}, - "owner": {
- "data": {
- "type": "target-account",
- "id": "7e2f2cf8-5ca3-4b66-b4e6-89633ef85fac"
}
}
}, - "type": "event"
}
}
{- "data": {
- "attributes": {
- "state": "CONFIRMED",
- "metadata": {
- "labels": [
- {
- "key": "m2amedia.tv:organisation-id",
- "value": "25fb8cc0-d04d-4b2e-955b-055d4888f2ea"
}, - {
- "key": "m2amedia.tv:target-account-name",
- "value": "Example account name"
}
]
}, - "name": "Example name",
- "description": "This is event description.",
- "start-time": "2023-06-14T14:00:00+00:00",
- "on-air-start-time": "2023-06-14T14:15:00+00:00",
- "on-air-end-time": "2023-06-14T15:15:00+00:00",
- "end-time": "2023-06-14T15:30:00+00:00",
- "created": "2023-06-13T15:09:44.912038+00:00",
- "updated": "2023-06-14T13:51:19.068152+00:00",
- "last-modified-by": "d1af38c6-f980-4830-b75d-bf9452c69c1a",
- "event-policies": { }
}, - "relationships": {
- "enrolments": {
- "data": [
- {
- "type": "source",
- "id": "6863be6d-2392-4a69-9841-e6356b63607c"
}
]
}, - "mediainputs": {
- "data": [
- {
- "type": "source",
- "id": "6863be6d-2392-4a69-9841-e6356b63607c"
}
]
}, - "owner": {
- "data": {
- "type": "target-account",
- "id": "7e2f2cf8-5ca3-4b66-b4e6-89633ef85fac"
}
}
}, - "type": "event",
- "id": "c49c499b-4e7e-4acb-ae83-f528b6ed194d"
}
}
The endpoint for retrieving information about existing schedule event linked to a specific owner. Event id is required in path parameters and owner id is required in query parameters.
eventId required | string <uuid> (Resource identifier) Example: c49c499b-4e7e-4acb-ae83-f528b6ed194d The id of the event to retrieve |
owner required | string <uuid> (Resource identifier) Example: owner=c49c499b-4e7e-4acb-ae83-f528b6ed194d The id of the target account |
Content-Type required | string (JSON API) Value: "application/vnd.api+json" The original media type of the resource. |
Accept required | string (JSON API) Value: "application/vnd.api+json" Content type (expressed as MIME types) the client is able to understand. |
{- "data": {
- "attributes": {
- "state": "CONFIRMED",
- "metadata": {
- "labels": [
- {
- "key": "m2amedia.tv:organisation-id",
- "value": "25fb8cc0-d04d-4b2e-955b-055d4888f2ea"
}, - {
- "key": "m2amedia.tv:target-account-name",
- "value": "Example account name"
}
]
}, - "name": "Example name",
- "description": "This is event description.",
- "start-time": "2023-06-14T14:00:00+00:00",
- "on-air-start-time": "2023-06-14T14:15:00+00:00",
- "on-air-end-time": "2023-06-14T15:15:00+00:00",
- "end-time": "2023-06-14T15:30:00+00:00",
- "created": "2023-06-13T15:09:44.912038+00:00",
- "updated": "2023-06-14T13:51:19.068152+00:00",
- "last-modified-by": "d1af38c6-f980-4830-b75d-bf9452c69c1a",
- "event-policies": { }
}, - "relationships": {
- "enrolments": {
- "data": [
- {
- "type": "source",
- "id": "6863be6d-2392-4a69-9841-e6356b63607c"
}
]
}, - "mediainputs": {
- "data": [
- {
- "type": "source",
- "id": "6863be6d-2392-4a69-9841-e6356b63607c"
}
]
}, - "owner": {
- "data": {
- "type": "target-account",
- "id": "7e2f2cf8-5ca3-4b66-b4e6-89633ef85fac"
}
}
}, - "type": "event",
- "id": "c49c499b-4e7e-4acb-ae83-f528b6ed194d"
}
}
The endpoint for updating existing schedule event linked to a specific owner. Event id is required in path parameters and owner id is required in query parameters.
If-Match HTTP request header can be used to make a request conditional.
The minimum required data in request body is
{
'data': {
'id': 'c49c499b-4e7e-4acb-ae83-f528b6ed194d',
'type': 'event'
}
}
Event id parameter in path and event id in request body must match.
The payload above won't change anything about the event. To change
any event attribute value, it needs to be added to payload as part of
event attributes. E.g., for changing just event's name
:
{
'data': {
'id': 'c49c499b-4e7e-4acb-ae83-f528b6ed194d',
'type': 'event'
'attributes': {
'name': 'New name'
}
}
}
In the case above all the other event attribute values will stay unchanged.
For updating event's enrolment or mediainput list, the full list must be provided in the payload (with old and/or new enrolments/mediainputs):
{
'data': {
'id': 'c49c499b-4e7e-4acb-ae83-f528b6ed194d',
'type': 'event'
'relationships': {
'enrolments': {
'data': [
{
'id': '7b465202-498d-4617-8212-607ead208b76',
'type': 'source'
}
]
}
}
}
}
For removing all event's enrolments, the empty list must be provided in the payload:
{
'data': {
'id': 'c49c499b-4e7e-4acb-ae83-f528b6ed194d',
'type': 'event'
'relationships': {
'enrolments': {
'data': []
}
}
}
}
Mediainput list must have at least one mediainput linked to the event. It is not possible to update event's owner.
It is not possible to update an event with a current state
CANCELLED
or ABORTED
If event's current state
is ENDED
, it is possible to update only
values for attributes:
name
description
metadata
If changing event's state
, valid transitions are:
CONFIRMED
--> DRAFT
DRAFT
--> CONFIRMED
CONFIRMED
--> CANCELLED
DRAFT
--> CANCELLED
PRE_TX
--> ABORTED
TX
--> ABORTED
POST_TX
--> ABORTED
if changing event's start-time
, event's current state
must be
DRAFT
OR current event's start-time
must be in the future.
if changing event's end-time
, event's current state
must be
DRAFT
OR current event's end-time
must be in the future.
Event time value requirements:
start-time
must be earlier than on-air-start-time
value,on-air-start-time
value must be earlier than on-air-end-time
value,on_air_end_time
value must be earlier than end-time
valueeventId required | string <uuid> (Resource identifier) Example: c49c499b-4e7e-4acb-ae83-f528b6ed194d The id of the event to retrieve |
owner required | string <uuid> (Resource identifier) Example: owner=c49c499b-4e7e-4acb-ae83-f528b6ed194d The id of the target account |
If-Match | string <uuid> (Resource identifier) Example: c49c499b-4e7e-4acb-ae83-f528b6ed194d Event ETag |
Content-Type required | string (JSON API) Value: "application/vnd.api+json" The original media type of the resource. |
Accept required | string (JSON API) Value: "application/vnd.api+json" Content type (expressed as MIME types) the client is able to understand. |
required | object (Primary data) Primary data with an event request body. |
{- "data": {
- "id": "c49c499b-4e7e-4acb-ae83-f528b6ed194d",
- "type": "event",
- "attributes": {
- "name": "New name"
}
}
}
{- "data": {
- "attributes": {
- "state": "CONFIRMED",
- "metadata": {
- "labels": [
- {
- "key": "m2amedia.tv:organisation-id",
- "value": "25fb8cc0-d04d-4b2e-955b-055d4888f2ea"
}, - {
- "key": "m2amedia.tv:target-account-name",
- "value": "Example account name"
}
]
}, - "name": "Example name",
- "description": "This is event description.",
- "start-time": "2023-06-14T14:00:00+00:00",
- "on-air-start-time": "2023-06-14T14:15:00+00:00",
- "on-air-end-time": "2023-06-14T15:15:00+00:00",
- "end-time": "2023-06-14T15:30:00+00:00",
- "created": "2023-06-13T15:09:44.912038+00:00",
- "updated": "2023-06-14T13:51:19.068152+00:00",
- "last-modified-by": "d1af38c6-f980-4830-b75d-bf9452c69c1a",
- "event-policies": { }
}, - "relationships": {
- "enrolments": {
- "data": [
- {
- "type": "source",
- "id": "6863be6d-2392-4a69-9841-e6356b63607c"
}
]
}, - "mediainputs": {
- "data": [
- {
- "type": "source",
- "id": "6863be6d-2392-4a69-9841-e6356b63607c"
}
]
}, - "owner": {
- "data": {
- "type": "target-account",
- "id": "7e2f2cf8-5ca3-4b66-b4e6-89633ef85fac"
}
}
}, - "type": "event",
- "id": "c49c499b-4e7e-4acb-ae83-f528b6ed194d"
}
}
Deletes a specific event by setting event's state to ABORTED
or
CANCELLED
.
Possible state transitions:
DRAFT
--> CANCELLED
CONFIRMED
--> CANCELLED
PRE_TX
--> ABORTED
TX
--> ABORTED
POST_TX
--> ABORTED
It is not possible to delete an event with current state ABORTED
,
CANCELLED
or ENDED
.
If-Match HTTP request header can be used to make a request conditional.
eventId required | string <uuid> (Resource identifier) Example: c49c499b-4e7e-4acb-ae83-f528b6ed194d The id of the event to retrieve |
owner required | string <uuid> (Resource identifier) Example: owner=c49c499b-4e7e-4acb-ae83-f528b6ed194d The id of the target account |
Content-Type required | string (JSON API) Value: "application/vnd.api+json" The original media type of the resource. |
Accept required | string (JSON API) Value: "application/vnd.api+json" Content type (expressed as MIME types) the client is able to understand. |
{- "errors": [
- {
- "status": "400",
- "title": "Bad Request",
- "detail": "Missing parameter required: owner"
}
]
}