Release notes 2025
2025r7
Changes to commercial API
From this version, the external system can using the interstitial integration.
Since the commercial API is used by the external system to send updates to the interstitial schedule, it has also been changed.
API developers
The YAML has been updated for these changes. The latest version can be retrieved by using the GET /api call.
Since a lot of changes were done, for easier viewing, the YAMLs can be compared here: TextCompare
Additional attributes for GET /breakSchedule call in commercial API
Since the commercial API is used by the external system to send updates to the interstitial schedule, it has also been changed. The following changes were done to the GET /breakSchedule call.
To provide more context to the external system and include new functionalities, the following attributes were added to the GET /breakSchedule call. In the
-
transmissionsarray:-
segmentationDuration:
This contains the sum of the duration of the program segments (in metric format) of a transmission in HH:MM:SS.MS format. This was added to provide a more frame-accurate duration of the transmission segments. -
contentCollectionId:
This contains the external reference of the content collection linked to the transmission. -
contentCollectionTitle:
This contains the title of the content collection. -
parentSeriesId:
This contains the external reference of the parent series content collection or the parent series of the content collection linked to the transmission. -
parentSeriesTitle:
This contains the title of the parent series or parent series content collection.
-
-
timeAllocations array:
-
blockSyncId:
This contains the value of the new Block sync ID property of the time allocation if the mapping method has been set to use the block sync ID.
-
Additionally, previously, the value of the readOnly attribute on time allocation level was determined by the Editable by external system property of the interstitial integration definition.
Since this was replaced by the Can be scheduled by external system property, from this version, the value is determined by the Owner property on the time allocation.
If that is set to MGX, the readOnly attribute will be true. If it is set to External, it will be false. Note that if program segments are included in the interstitial integration definition, the attribute will always be set to true.
An example of a part of the response:
{
"channelId": "MGX",
"startDate": "2025-11-12",
"scheduleVersion": "Active",
"dayStatus": null,
"definitionId": "ComUUID",
"transmissions": [
{
"transmissionId": "9502111474",
"startTime": "06:00:00",
"startTimeUTC": "05:00:00",
"announcedStartTime": "06:00",
"lockedStartTime": false,
"duration": "01:53:30",
"productId": "9501369409",
"parentalRating": null,
"txTitle": "The Room Next Door",
"segmentationDuration": "01:50:00.000",
"productType": "program",
"productCode": "RND",
"productTitle": "The Room Next Door",
"seriesTitle": null,
"episodeNumber": null,
"nature": null,
"genre": null,
"clashCodes": [],
"rerun": true,
"premiere": false,
"contractNumber": null,
"contentCollectionId": "9501367759",
"contentCollectionTitle": "FFG 2024",
"parentSeriesId": null,
"parentSeriesTitle": null,
"timeAllocations": [
{
"breakId": "9502111474/1",
"externalBreakId": null,
"blockSyncId": null,
"startTime": "06:00:00",
"duration": "00:40:00",
"type": "programSegment",
"position": null,
"startTimeUTC": "05:00:00",
"readOnly": true,
"title": "The Room Next Door - 1/3",
"sequenceNumber": 1,
"regional": false,
"masterBreakId": null,
"kind": "Primary",
"predictedRatings": []
},
{
"breakId": null,
"externalBreakId": null,
"blockSyncId": "aaaaaaaaaaa",
"startTime": "06:00:00",
"duration": "00:01:00",
"type": "commercial",
"position": null,
"startTimeUTC": "05:00:00",
"readOnly": false,
"title": "The Room Next Door - - Commercial",
"sequenceNumber": 1,
"regional": false,
"masterBreakId": null,
"kind": "Secondary",
"predictedRatings": []
},
{
"breakId": null,
"externalBreakId": null,
"blockSyncId": "af5c900b-2ea7-444e-8ebb-cb09d50f2693",
"startTime": "06:40:00",
"duration": "00:01:00",
"type": "commercial",
"position": "Middle",
"startTimeUTC": "05:40:00",
"readOnly": false,
"title": "The Room Next Door - - Commercial",
"sequenceNumber": 2,
"regional": false,
"masterBreakId": null,
"kind": "Primary",
"predictedRatings": []
},Additional attributes in POST and PUT calls of commercial API
From this version, the external system can create time allocations using the interstitial integration.
Since the commercial API is used by the external system to send updates to the interstitial schedule, it has also been changed. The following changes were done to the POST and PUT calls:
Duration
Since the calculation of the duration has changed, the duration attribute has been added to the timeAllocations array in the POST /commercialPlaylist and PUT /commercialBreak calls. It needs the HH:MM:SS format.
Block sync ID
Because a new mapping method has been added to the interstitial integration definitions, the blockSyncId attribute has also been added to timeAllocations array in the body of the POST /commercialPlaylist, PUT /commercialBreak and PUT/ commercialBreakDuration calls.
Its value will be entered in the Block sync ID of the interstitial block that is created for synchronisation, or on the time allocation itself.
It has also been added to the response of the PUT /commercialBreak and PUT/ commercialBreakDuration calls, since it already contained attributes for the other mapping methods as well.
For example:
[
{
"statusCode": "200",
"message": "Commercial break has been modified",
"concept": "CommercialBreak",
"breakId": null,
"externalBreakId": null,
"blockSyncId": "7a5a41ac-1ee1-4f9b-868f-bbc1011f3413",
"timestamp": "2025-04-17T11:04:03Z"
}
]Transmission ID
It is now possible to configure time allocation types that can be created by an external system. To be able to create the time allocation correctly using the command in the interstitial schedule assistant, it is important to know to which transmission a time allocation belongs.
The transmissionId was already part of the response of the GET /breakSchedule call. Therefore, it has also been added to the timeAllocations array of the POST /commercialPlaylist and PUT /commercialBreak calls. It maps to the external reference of a transmission block and is only required when creating time allocations.
When a call is sent, it is checked if a time allocation of the specified type can be scheduled and/or created by an external system. If not, it is ignored. If so, it is checked whether a time allocation with the provided mapping method already exists in the schedule on the specified channel, date, and schedule version.
If there is none yet, and the transmissionID is
-
present, it is checked if a transmission with that ID exists.
-
If not, an error is returned that the provided transmission could not be found.
-
If so, the transmission ID will be stored on the interstitial block, and the time allocation will be created in that transmission block.
-
-
not present, the following 422 error is returned because it will not be possible to create the new time allocation in the correct place:
{
"statusCode": "422",
"message": "Operation cannot be completed due to violations",
"timestamp": "2025-09-08T14:14:20Z",
"concept": "Commercial playlist",
"id": null,
"errors": [
{
"errorCode": "COMMERCIAL-00007",
"description": "$_Please provide transmissionId on TimeAllocation for mapping method blockSyncId",
"data": [
"transmissionId",
"TimeAllocation",
"blockSyncId"
]
}
]
}Secondary time allocations
Since secondary time allocations can also be created or updated using the POST /commercialPlaylist and PUT /commercialBreak calls, additional attributes have been added in the timeAllocations array:
-
offsetPosition:
This maps to the Time offset strategy of a secondary event, but only the following values are allowed:startAndDurationorendAndDuration. This attribute is optional. If not provided, the property of the secondary event prototype in the definition is used. -
offsetPrimaryEvent:
This maps to the Offset to primary event, its value can be negative and should have the format HH:MM:SS.ff. This attribute is optional. If not provided, the property of the secondary event prototype in the definition is used. -
linkedPrimaryType:
A secondary time allocation is always linked to a primary time allocation. This contains the time allocation type of the primary time allocation to which the secondary time allocation should be linked. The possible values can be retrieved using theGET /timeAllocationTypescall. This will be used for matching in the interstitial schedule assistant and is mandatory. -
linkedPrimaryTimeAllocationId:
The ID of the primary time allocation to which the secondary time allocation should be linked. It is mandatory.-
If program segments are included, this is the
breakId. -
For other time allocation types, this is the field used as the block mapping method, meaning
breakId,externalBreakIdorblockSyncId.
-
When
-
the Can be created by external system property is set to Yes for a certain time allocation type;
-
secondary time allocations are included in the definition;
-
and a secondary time allocation is sent using the API, meaning a time allocation with
“kind”: “Secondary”,
but the linkedPrimaryType and/or linkedPrimaryTimeAllocationId are missing, the following error will be returned:
{
"statusCode": "422",
"message": "Operation cannot be completed due to violations",
"timestamp": "2025-09-12T07:12:49Z",
"concept": "Commercial playlist",
"id": null,
"errors": [
{
"errorCode": "COMMERCIAL-00001",
"description": "$_Please provide linkedPrimaryType, linkedPrimaryTimeAllocationId on TimeAllocation",
"data": [
"linkedPrimaryType, linkedPrimaryTimeAllocationId",
"TimeAllocation"
]
}
]
}Example
An example of the POST /commercialPlaylist call with the new attributes:
{
"channelId": "string",
"startDate": "2025-09-15",
"scheduleVersion": "Active",
"dayStatus": "string",
"definitionId": "Commercial",
"timeAllocations": [
{
"breakId": "string",
"externalBreakId": "string",
"transmissionId": "12345678",
"blockSyncId": "string",
"startTime": "14:15:00",
"startTimeUTC": "13:15:00",
"duration": "00:05:00",
"kind": "Primary",
"type": "Commercial break",
"title": "string",
"remarks": "string",
"offsetPosition": "startAndDuration",
"offsetPrimaryEvent": "14:15:00.00",
"linkedPrimaryType": "programSegment, commercialBreak, promotion",
"linkedPrimaryTimeAllocationId": "f161f67c-49ee-476c-b67f-084040dbedd6",
"events": [
...
}Error messages for creating or filling time allocations in commercial API
From this version, the external system can create time allocations using the interstitial integration.
Since the commercial API is used by the external system to send updates to the interstitial schedule, it has also been changed. The following changes were made to the error messages in the POST and PUT calls related to the configuration of interstitial integration definitions.
Cannot be scheduled
Previously, when a time allocation type was read-only, meaning the Editable by external system property of the interstitial integration definition was set to No, and a time allocation of that type was included in the POST or PUT calls with an events array, a 422 error would be returned with the message: The time allocation type [type] is not editable by the external system.
Since the property has been replaced by the Can be scheduled by external system property, when it is set to No, the existing message has also been renamed:
{
"statusCode": "422",
"message": "Operation cannot be completed due to violations",
"timestamp": "2025-04-08T14:47:01Z",
"concept": "Commercial playlist",
"id": null,
"errors": [
{
"errorCode": "COMMERCIAL-00009",
"description": "$_The time allocation type filler is not allowed to have events planned by the external system",
"data": [
"filler"
]
}
]
} When secondary time allocations are not included in the definition, but a time allocation with kind Secondary is sent anyway, an error is still returned as before, see Secondary time allocations in commercial API.
Cannot be created
In this version, the Can be created by external system property was added to the interstitial integration definition for each time allocation type.
When it is set to Yes, the POST /commercialPlaylist call can be used to create time allocations of that type. If it is set to No, and a call is sent with that type, it is checked if a time allocation with the same ID for the mapping method and time allocation type exists already. If not, the following error will be returned:
{
"statusCode": "422",
"message": "Operation cannot be completed due to violations",
"timestamp": "2025-05-15T08:23:00Z",
"concept": "Commercial playlist",
"id": null,
"errors": [
{
"errorCode": "COMMERCIAL-00015",
"description": "$_The time allocation type: commercial is not allowed to be created by the external system",
"data": [
"time allocation type: commercial",
"time allocation ID: 1d86df50-3f1a-457d-98ac-f06ecad639453"
]
}
]
}When
-
the Can be created by external system property is set to No;
-
secondary time allocations are included in the interstitial integration definition;
-
and a secondary time allocation is sent using the API, meaning a time allocation with
“kind”: “Secondary”,
the following error will be returned:
{
"statusCode": "422",
"message": "Operation cannot be completed due to violations",
"timestamp": "2025-09-12T07:02:17Z",
"concept": "Commercial playlist",
"id": null,
"errors": [
{
"errorCode": "COMMERCIAL-00017",
"description": "$_The secondary time allocation type: Sponsoring is not allowed to be created by the external system",
"data": [
"secondary time allocation type: Sponsoring",
"time allocation ID: af5cc265-179f-4027-af94-5ece2a1a02bc"
]
}
]
}When a time allocation type can be created but cannot be scheduled by the external system, the call is accepted, but any events included for that type are created for the interstitial block but not synchronised later.
Program segments
When read-only program segments are included in the interstitial integration definition, they can be sent in the POST /commercialPlaylist call, and an interstitial block is created for them. When creating new time allocations, it is recommended to send to also send the program segments in the POST call for easier sequencing.
When they are not included in the definition, and a time allocation with the Program segment type is provided in the call, the following 422 error is returned:
{
"statusCode": "422",
"message": "Operation cannot be completed due to violations",
"timestamp": "2025-09-08T15:11:17Z",
"concept": "Commercial playlist",
"id": null,
"errors": [
{
"errorCode": "COMMERCIAL-00016",
"description": "$_The time allocation type programSegment cannot be included",
"data": [
"programSegment"
]
}
]
}When they are included in the PUT /commercialBreak call, the program segment time allocations are ignored.
2025r6
Secondary time allocations in commercial API
From this version, it is possible to include secondary time allocations when publishing an interstitial schedule to an external system. That system can use the commercial API to retrieve the schedule via the interstitial schedule outbox and send updates back to Mediagenix Base. Therefore, the commercial API has been adapted to support secondary time allocations.
GET /breakSchedule call
This call returns all transmissions and its time allocations for a specified broadcast day based on the interstitial schedule outbox that was last published.
If secondary time allocations were also exported, the response of the GET /breakSchedules call returns them as well with the same attributes as the regular time allocations. Note that the title of secondary time allocations will be based on the title of the time allocation type, which can be seen in the calculated title of the STA in the secondary time allocation assistant.
The Time allocation kind property has been added as the kind attribute to the properties of the time allocation. Even when there are no secondary time allocations in the response, the kind attribute is present.
The time allocations in the timeAllocations array are now sorted on startTime and then by the kind, instead of OID. This means that if a primary time allocation and a secondary time allocation start at the same time, the primary time allocation is listed first.
For example, the timeAllocations array of the call:
"timeAllocations": [
{
"breakId": "string",
"externalBreakId": "string",
"startTime": "14:15:00",
"startTimeUTC": "13:15:00",
"duration": "00:05:00",
"kind": "Primary"
"type": "Commercial break, promotion, sponsorship,...",
"readOnly": false,
"title": "string",
"sequenceNumber": 0,
"position": "Start",
"regional": true,
"masterBreakId": "string",
...
},
{
"breakId": "string",
"externalBreakId": "string",
"startTime": "14:15:00",
"startTimeUTC": "13:15:00",
"duration": "00:05:00",
"kind": "Secondary"
"type": "Commercial break, promotion, sponsorship,...",
"readOnly": false,
"title": "string",
"sequenceNumber": 0,
"position": "Start",
"regional": true,
"masterBreakId": "string",
...
},POST /commercialPlaylist
This call allows to send the time allocations, transmission events and commercials with media assets that should be used to fill the broadcast day. They will be created as interstitial blocks and clips for the interstitial integration.
This call can now create interstitial blocks and clips for secondary time allocations as well. The kind attribute has also been added to the timeAllocations array of the body of the call to be able to assign a type to the interstitial block, so it is easier for matching:
{
...
"timeAllocations": [
{
"breakId": "string",
"externalBreakId": "string",
"startTime": "14:15:00",
"startTimeUTC": "13:15:00",
"kind": "Primary",
"type": "Commercial break",
"title": "string",
"remarks": "string",
"events": [
...When the attribute is not included in the call, the kind of the interstitial block will be empty. It is not mandatory because it is more for informational purposes and can still be overruled when matching.
When a time allocation with kind Secondary is sent for a certain time allocation type, but the Include secondary time allocations column of the interstitial integration is set to No for that type, a 422 error is returned with the following message:
{
"statusCode": "422",
"message": "Operation cannot be completed due to violations",
"timestamp": "2025-05-19T08:15:32Z",
"concept": "Commercial playlist",
"id": null,
"errors": [
{
"errorCode": "COMMERCIAL-00015",
"description": "Secondary time allocations are not included in the block definition for type commercial.",
"data": [
"commercial"
]
}
]
}This check is done after the check for COMMERCIAL-00010, which checks if the time allocation type that is provided is part of the interstitial integration definition. This message has been renamed for clarity from Time allocation block defnition not found to No block definitions exist for the provided time allocation type.
PUT /commercialBreak
This call updates the interstitial blocks and clips for the specified time allocations and can only be executed after a POST /commercialPlaylist call has been done first. It uses the same properties as the POST /commercialPlaylist call, so it has the same changes as above.
PUT /commercialBreakDuration
This call allows to update the duration of the time allocations in the schedule and can now update secondary time allocations as well by providing their breakLabel or externalBreakId.
It does not update or create the interstitial inbox but directly impacts the time allocation itself, so the kind attribute was not added here. The checks described for the PUT and POST call are also not done when using this call.
API developers
The YAML has been updated for these changes. The latest version can be retrieved by using the GET /api call.
At line 677, the kind was added to the properties of the time allocations in the BreakSchedule schema.
At line 924, the kind was added to the properties of the TimeAllocationForPlaylist schema.
For easier viewing, the YAMLs can also be compared here: TextCompare
2025r5
Fix for transmissions under embargo
When a transmission is marked as under embargo, certain product attributes are returned as null. Previously, the txTitle attribute in the commercial API was still returned even when the transmission was under embargo. This issue has been fixed in this version.
2025r4
Prevent or allow update of media assets using commercial API
In a previous version, it became possible to update media assets using the commercial API. However, this caused the API to become backwards incompatible.
From this version, by default, it is not possible anymore to update media assets using the API, but only create them. When using the POST /commercialPlaylist, POST /commercial and PUT /commercialBreak calls, it is checked if the media asset referenced in the mediaAssetId already exists:
-
If so, the media asset information in the payload is ignored, and the BAPI service will log: Media asset information was ignored. The commercial API can only create media assets.
-
If it does not exist, the media asset is created.
We would recommend not changing this behaviour; however, if this is absolutely required, an option can be activated to allow updating. Contact Mediagenix to activate this for you.
Drop-down list call for target groups of predicted ratings in commercial API
In a previous version, the predictedRatings array was added to the GET /breakSchedules of the commercial API. The YAML mentioned that the values of the targetGroup attribute could be retrieved with the GET /targetGroups call. However, this call was not part of the API.
From this version, the GET /targetGroups call has been added to the commercial API.
When the call is sent, it returns the API references and descriptions of the values of the TMCampaignTargetGroup drop-down list.
[
{
"id": "Adults",
"name": "Adults"
},
{
"id": "Kids",
"name": "Kids"
},
{
"id": "Teens",
"name": "Teens"
},
{
"id": "60+",
"name": "60+"
}
]It can already be used, but will be added to the YAML in a future version.
Transmission title added to commercial API YAML
This information is mostly relevant for API developers.
In the previous version, the txTitle attribute was added to the GET /breakSchedule call of the commercial API, but it was not yet added to the YAML.
In this version, the txTitle was added to the properties of the Transmission schema of the YAML at line 734. The latest version can be retrieved by using the GET /api call.
2025r3
Transmission title in GET /breakSchedule call of commercial API
The commercial API contains a GET /breakSchedule call, which is used by the external system after publishing an interstitial schedule for interstitial integration. The call retrieves all transmissions and time allocations of the type specified in the interstitial integration definition for a channel on a specific date.
Previously, the transmissions array contained the productTitle and the seriesTitle, but not the title of the transmission itself, which can be different.
From this version, the txTitle attribute has been added to the response body of the GET /breakSchedule call. It maps to the head title of the transmission.
An example of the response:
{
"channelId": "MGX",
"startDate": "2025-11-01",
"scheduleVersion": "Active",
"dayStatus": "closed",
"definitionId": "Comm",
"transmissions": [
{
"transmissionId": "9501555641",
"startTime": "09:33:00",
"startTimeUTC": "08:33:00",
"announcedStartTime": "09:25",
"lockedStartTime": false,
"duration": "01:28:30",
"productId": "9501369293",
"parentalRating": null,
"txTitle": "FFG 2024 - Presence",
"productType": "program",
"productCode": null,
"productTitle": "Presence",
"seriesTitle": null,
...
"timeAllocations": [
{
"breakId": "000025",
"externalBreakId": null,
"startTime": "10:03:30",
"duration": "00:01:00",
"type": "commercial",
"position": "Middle",
"startTimeUTC": "09:03:30",
"readOnly": false,
"title": "Presence - - Commercial",
"sequenceNumber": 4,
"regional": false,
"masterBreakId": null,
"predictedRatings": []
}
]
}
]
}