Distribute a now-playing track

POST/events/de.ard.eventhub.v1.radio.track.playing

Authorization

AuthorizationBearer token (JWT) · headerrequired

Request body

requiredapplication/json

New event to be distributed to subscribers. The Eventhub format validation expects only a subset of these variables as minimum set. All other fields are technically optional, but **highly encouraged** to be included, so a best-possible metadata exchange is possible. The subset is defined in the list of required fields of Schemas `eventV1PostBody`, resulting in this body: ```json { "type": "music", "start": "2020-01-19T06:00:00+01:00", "title": "Song name", "services": [ { ... } ], "playlistItemId": "swr3-5678" } ``` Required fields not specified in the Schema, will cause your request to fail. The `id` is inserted by Eventhub as string-formatted number, but might be a true string in the future, do not expect this string to remain numbers only!

eventstring

If set, it needs to match the URL event parameter

Allowed:de.ard.eventhub.v1.radio.track.playingde.ard.eventhub.v1.radio.track.next

typestringrequired

The type of the element that triggered this event. See additional file in docs for details.

Allowed:audiocommercialjinglelivemusicnewstrafficweather

startstringrequired

ISO8601 compliant timestamp

lengthnumberrequired

Estimated length of the element in seconds. Must be set to a positive number (not 0 or null). The end of the current element is defined by the start of the next element.

titlestringrequired

Representative title for external use

artiststring | null

Pre-formatted artist information

contributorscontributor[] | null

Full details about involved artists if available

Show properties

Array of contributor

namestringrequired

rolestringrequired

Allowed:artistauthorcomposerperformerconductorchoirleaderensembleorchestrasoloistproducerengineer

normDbobject | null

Reference to an entity in ARD's Norm-DB catalog

Show properties

typestringrequired

idstringrequired

isnistring | null

ISNI ID if available

urlstring | null

Can link to external reference

servicesservices[]required

The playing stations unique Service-IDs. Do not include the Service-Type suffix.

Show properties

Array of services

typestringrequired

Allowed:EventLivestreamPermanentLivestream

externalIdstringrequired

publisherIdstringrequired

External ID or globally unique identifier (Core ID) for the associated publisher. When no Core ID is provided, the External ID will be converted by Eventhub.

idstring

Globally unique identifier, created by Eventhub

referencesreference[] | null

related external entities

Show properties

Array of reference

typestringrequired

Allowed:EpisodeSectionPublicationBroadcastShowSeasonArticle

idstring

matches ^urn:ard:[a-z0-9-]+:[a-z0-9-]+$

externalIdstringrequired

matches ^(c|b)rid:\/\/.+$

titlestring

urlstring<uri>

alternateIdsstring[]

playlistItemIdstringrequired

Unique identifier (within a publisher) to connect next and playing items if needed

hfdbIdsstring[] | null

Can reference all available tracks in ARD HFDB instances. Should ideally at least include the common ZSK instance.

externalIdstring | null

Can reference the original ID in the publisher's system

isrcstring | null

Appropriate ISRC code if track is a music element

upcstring | null

Corresponding reference to an album where such ISRC was published

mpnstring | null

If available the reference to the original delivery from MPN

mediamediaItem[] | null

Can contain an array of media files like cover, artist, etc.

Show properties

Array of mediaItem

typestringrequired

Allowed:coverartistanchoraudiovideo

urlstringrequired

templateUrlstring | null

descriptionstringrequired

attributionstring | null

isFallbackboolean

Optional flag to mark media as fallback data that subscribers can filter out

pluginseventPlugin[] | null

Highly optional field for future third-party metadata distribution or other connected services

Show properties

Array of eventPlugin

typestring

idstring

ID gets inserted by Eventhub as string-formatted number, but might be a true string in the future, do not expect this string to remain numbers only!

Responses

201 Event created *Note:* The first request of an event for an externalId that is not registered yet, will return the status `failed: 1`. This indicates that a new topic for the externalId has been created, and the request needs to be repeated: ```json "statuses": { "published": 0, "blocked": 0, "failed": 1 } ``` If the request returns the status `blocked: 1`, it indicates that you are not allowed to publish events under the given publisherId.

statusesobjectrequired

Show properties

publishedintegerrequired

min -9007199254740991 · max 9007199254740991

blockedintegerrequired

min -9007199254740991 · max 9007199254740991

failedintegerrequired

min -9007199254740991 · max 9007199254740991

eventeventV1PostBodyrequired

**Please also note the details in the `POST /events/v1` endpoint above!**

Show properties

eventstring

If set, it needs to match the URL event parameter

Allowed:de.ard.eventhub.v1.radio.track.playingde.ard.eventhub.v1.radio.track.next

typestringrequired

The type of the element that triggered this event. See additional file in docs for details.

Allowed:audiocommercialjinglelivemusicnewstrafficweather

startstringrequired

ISO8601 compliant timestamp

lengthnumberrequired

Estimated length of the element in seconds. Must be set to a positive number (not 0 or null). The end of the current element is defined by the start of the next element.

titlestringrequired

Representative title for external use

artiststring | null

Pre-formatted artist information

contributorscontributor[] | null

Full details about involved artists if available

Show properties

Array of contributor

namestringrequired

rolestringrequired

Allowed:artistauthorcomposerperformerconductorchoirleaderensembleorchestrasoloistproducerengineer

normDbobject | null

Reference to an entity in ARD's Norm-DB catalog

Show properties

typestringrequired

idstringrequired

isnistring | null

ISNI ID if available

urlstring | null

Can link to external reference

servicesservices[]required

The playing stations unique Service-IDs. Do not include the Service-Type suffix.

Show properties

Array of services

typestringrequired

Allowed:EventLivestreamPermanentLivestream

externalIdstringrequired

publisherIdstringrequired

External ID or globally unique identifier (Core ID) for the associated publisher. When no Core ID is provided, the External ID will be converted by Eventhub.

idstring

Globally unique identifier, created by Eventhub

referencesreference[] | null

related external entities

Show properties

Array of reference

typestringrequired

Allowed:EpisodeSectionPublicationBroadcastShowSeasonArticle

idstring

matches ^urn:ard:[a-z0-9-]+:[a-z0-9-]+$

externalIdstringrequired

matches ^(c|b)rid:\/\/.+$

titlestring

urlstring<uri>

alternateIdsstring[]

playlistItemIdstringrequired

Unique identifier (within a publisher) to connect next and playing items if needed

hfdbIdsstring[] | null

Can reference all available tracks in ARD HFDB instances. Should ideally at least include the common ZSK instance.

externalIdstring | null

Can reference the original ID in the publisher's system

isrcstring | null

Appropriate ISRC code if track is a music element

upcstring | null

Corresponding reference to an album where such ISRC was published

mpnstring | null

If available the reference to the original delivery from MPN

mediamediaItem[] | null

Can contain an array of media files like cover, artist, etc.

Show properties

Array of mediaItem

typestringrequired

Allowed:coverartistanchoraudiovideo

urlstringrequired

templateUrlstring | null

descriptionstringrequired

attributionstring | null

isFallbackboolean

Optional flag to mark media as fallback data that subscribers can filter out

pluginseventPlugin[] | null

Highly optional field for future third-party metadata distribution or other connected services

Show properties

Array of eventPlugin

typestring

idstring

ID gets inserted by Eventhub as string-formatted number, but might be a true string in the future, do not expect this string to remain numbers only!

tracestring | nullrequireddeprecated

Always null. Deprecated; may be removed in a future release.

400Bad Request (invalid input)

messagestringrequired

errorsopenApiErrorItem[]required

min items 1

Show properties

Array of openApiErrorItem

pathstringrequired

messagestringrequired

errorCodestringrequired

tracestring | nullrequireddeprecated

Always null. Deprecated; may be removed in a future release.

401Missing authentication

messagestringrequired

errorsopenApiErrorItem[]required

min items 1

Show properties

Array of openApiErrorItem

pathstringrequired

messagestringrequired

errorCodestringrequired

tracestring | nullrequireddeprecated

Always null. Deprecated; may be removed in a future release.

403Invalid authorization

messagestringrequired

errorsopenApiErrorItem[]required

min items 1

Show properties

Array of openApiErrorItem

pathstringrequired

messagestringrequired

errorCodestringrequired

tracestring | nullrequireddeprecated

Always null. Deprecated; may be removed in a future release.

413Payload Too Large (JSON body exceeds 400kb limit)

messagestringrequired

errorsopenApiErrorItem[]required

Show properties

Array of openApiErrorItem

pathstringrequired

messagestringrequired

errorCodestringrequired

tracestring | nullrequireddeprecated

Always null. Deprecated; may be removed in a future release.

500Internal server error

messagestringrequired

tracestring | nullrequireddeprecated

Always null. Deprecated; may be removed in a future release.

Request

curl -X POST "/events/de.ard.eventhub.v1.radio.track.playing" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "event": "de.ard.eventhub.v1.radio.track.playing",
  "type": "music",
  "start": "2020-01-19T06:00:00+01:00",
  "length": 240,
  "title": "Song name",
  "artist": "Sam Feldt feat. Someone Else",
  "contributors": [
    {
      "name": "Sam Feldt",
      "role": "artist",
      "normDb": {
        "type": "Person",
        "id": "1641010"
      },
      "isni": "string",
      "url": "string"
    }
  ],
  "services": [
    {
      "type": "PermanentLivestream",
      "externalId": "crid://swr.de/123450",
      "publisherId": "248000",
      "id": "urn:ard:permanent-livestream:49267f7d67be180d"
    }
  ],
  "references": [
    {
      "type": "Episode",
      "id": "urn:ard:show:49267f7d67be180d",
      "externalId": "crid://swr.de/123450",
      "title": "string",
      "url": "<uri>",
      "alternateIds": [
        "https://normdb.ivz.cn.ard.de/sendereihe/427"
      ]
    }
  ],
  "playlistItemId": "swr3-5678",
  "hfdbIds": [
    "swrhfdb1.KONF.12345",
    "zskhfdb1.KONF.12345"
  ],
  "externalId": "M012345.001",
  "isrc": "DE012345678",
  "upc": "string",
  "mpn": "string",
  "media": [
    {
      "type": "cover",
      "url": "https://example.com/cover.jpg",
      "templateUrl": "https://example.com/cover.jpg?width={width}",
      "description": "Cover Demo Artist",
      "attribution": "Photographer XYZ",
      "isFallback": false
    }
  ],
  "plugins": [
    {
      "type": "postToThirdPartyPlatformXYZ"
    }
  ],
  "id": "1234567890"
}'

const response = await fetch("/events/de.ard.eventhub.v1.radio.track.playing", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "event": "de.ard.eventhub.v1.radio.track.playing",
  "type": "music",
  "start": "2020-01-19T06:00:00+01:00",
  "length": 240,
  "title": "Song name",
  "artist": "Sam Feldt feat. Someone Else",
  "contributors": [
    {
      "name": "Sam Feldt",
      "role": "artist",
      "normDb": {
        "type": "Person",
        "id": "1641010"
      },
      "isni": "string",
      "url": "string"
    }
  ],
  "services": [
    {
      "type": "PermanentLivestream",
      "externalId": "crid://swr.de/123450",
      "publisherId": "248000",
      "id": "urn:ard:permanent-livestream:49267f7d67be180d"
    }
  ],
  "references": [
    {
      "type": "Episode",
      "id": "urn:ard:show:49267f7d67be180d",
      "externalId": "crid://swr.de/123450",
      "title": "string",
      "url": "<uri>",
      "alternateIds": [
        "https://normdb.ivz.cn.ard.de/sendereihe/427"
      ]
    }
  ],
  "playlistItemId": "swr3-5678",
  "hfdbIds": [
    "swrhfdb1.KONF.12345",
    "zskhfdb1.KONF.12345"
  ],
  "externalId": "M012345.001",
  "isrc": "DE012345678",
  "upc": "string",
  "mpn": "string",
  "media": [
    {
      "type": "cover",
      "url": "https://example.com/cover.jpg",
      "templateUrl": "https://example.com/cover.jpg?width={width}",
      "description": "Cover Demo Artist",
      "attribution": "Photographer XYZ",
      "isFallback": false
    }
  ],
  "plugins": [
    {
      "type": "postToThirdPartyPlatformXYZ"
    }
  ],
  "id": "1234567890"
})
});

Response

{
  "statuses": {
    "published": 1,
    "blocked": 0,
    "failed": 0
  },
  "event": {
    "event": "de.ard.eventhub.v1.radio.track.playing",
    "type": "music",
    "start": "2020-01-19T06:00:00+01:00",
    "length": 240,
    "title": "Song name",
    "artist": "Sam Feldt feat. Someone Else",
    "contributors": [
      {
        "name": "Sam Feldt",
        "role": "artist",
        "normDb": {
          "type": "Person",
          "id": "1641010"
        },
        "isni": "string",
        "url": "string"
      }
    ],
    "services": [
      {
        "type": "PermanentLivestream",
        "externalId": "crid://swr.de/123450",
        "publisherId": "248000",
        "id": "urn:ard:permanent-livestream:49267f7d67be180d"
      }
    ],
    "references": [
      {
        "type": "Episode",
        "id": "urn:ard:show:49267f7d67be180d",
        "externalId": "crid://swr.de/123450",
        "title": "string",
        "url": "<uri>",
        "alternateIds": [
          "https://normdb.ivz.cn.ard.de/sendereihe/427"
        ]
      }
    ],
    "playlistItemId": "swr3-5678",
    "hfdbIds": [
      "swrhfdb1.KONF.12345",
      "zskhfdb1.KONF.12345"
    ],
    "externalId": "M012345.001",
    "isrc": "DE012345678",
    "upc": "string",
    "mpn": "string",
    "media": [
      {
        "type": "cover",
        "url": "https://example.com/cover.jpg",
        "templateUrl": "https://example.com/cover.jpg?width={width}",
        "description": "Cover Demo Artist",
        "attribution": "Photographer XYZ",
        "isFallback": false
      }
    ],
    "plugins": [
      {
        "type": "postToThirdPartyPlatformXYZ"
      }
    ],
    "id": "1234567890"
  },
  "trace": null
}

{
  "message": "request.headers should have required property 'Authorization'",
  "errors": [
    {
      "path": "string",
      "message": "string",
      "errorCode": "string"
    }
  ],
  "trace": null
}