Skip to content
Playout API
/
/
Initiate a new tracking s...

Media Jay Playout API (2025-09-02)

The playout API of the Media Jay application provides access to the playout data and orchestrates extended queries.

Authentication

To access the endpoints you require a X-API-Key in the header. Partners, please contact Transfermedia support@transfermedia.de to retrieve one.

Versioning

To use a specific implementation version of this API place it to the request header X-API-Version. If the header is missed the latest implementation version 2025-09-02 is used. The response header X-API-Version returns the implementation version the request was processed with.

Further documentation

For further details please visit the documentation or contact Transfermedia support@transfermedia.de.

Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
Production server

https://live.playout.api.jay-metadata.com/v1/

Session Tracking

APIs for managing user tracking sessions. These endpoints allow clients to create, retrieve, and delete tracking sessions which are used for analytics and user behavior tracking.

Operations

Retrieve current tracking session

Request

Retrieves the tracking session from the header or cookie sent by the client.

The tracking session contains information about the user's session including a unique identifier, creation timestamp, and optional user ID for cross-session tracking. This endpoint allows clients to verify if they have an active valid session.

Tries to retrieve the tracking session in this order:

  1. Cookie with name __Secure-jay_tracking
  2. Header with name X-JAY-TRACKING

Args:

request: The incoming HTTP request containing potential session data in cookies or headers

Raises:

HTTPException: If the session is invalid or not found (400 Bad Request).

Returns:

ResultResponse[TrackingSession]: The active tracking session.

Path
playout_idstring(Playout Id)required
Headers
X-API-Keystring(X-Api-Key)required

Required. API access key for authorized use of the checkout endpoints. Partners, please contact Transfermedia to retrieve a valid key.

X-JAY-TRACKINGstring(X-Jay-Tracking)

Tracking session header for user tracking and analytics. This is set by the /playouts/{playout_id}/tracking/session endpoint.

Example: eyJzZXNzaW9uX2lkIjoiZXhhbXBsZS1zZXNzaW9uLWlkLTEyMzQiLCJzdGFydF90aW1lIjoiMjAyNS0wMS0wMVQxMjowMDowMC4wMDAwMDAiLCJzb3VyY2UiOiJqYXkuYXBpLnBsYXlvdXQuZXhhbXBsZSJ9
curl -i -X GET \
  'https://live.playout.api.jay-metadata.com/v1/playouts/{playout_id}/tracking/session' \
  -H 'X-API-Key: string' \
  -H 'X-JAY-TRACKING: eyJzZXNzaW9uX2lkIjoiZXhhbXBsZS1zZXNzaW9uLWlkLTEyMzQiLCJzdGFydF90aW1lIjoiMjAyNS0wMS0wMVQxMjowMDowMC4wMDAwMDAiLCJzb3VyY2UiOiJqYXkuYXBpLnBsYXlvdXQuZXhhbXBsZSJ9'

Responses

Successfully retrieved the tracking session

Bodyapplication/json
dataobject(The response data)

The response data.

Example: {"sessionId":"550e8400-e29b-41d4-a716-446655440000","startTime":"2023-01-15T14:30:24.123456","source":"jay.api.playout.1.0.0","userId":"user-123456","providerName":"netflix"}
nextTokenstring(Next token)

The token, which can be used to retrieve the next page of data.

errorobject(The error response)

Details of the error that occurred during the API request, including error code and message. This field is only present when the request results in an error.

Response
application/json
{
  "session_id": "b69d5c78-a2e9-4a7d-b3f8-c96c3a43d207",
  "start_time": "2023-04-21T14:32:17.123456",
  "source": "jay.api.playout.1.0.0",
  "user_id": "user-123456"
}

Initiate a new tracking session

Request

Initiates a new tracking session for analytics and user behavior tracking.

Creates a new tracking session with a unique ID and current timestamp, and sets it as both a cookie and header in the response. The session data is base64-encoded JSON that contains the session ID, start timestamp, and source information.

The tracking session is used to correlate user actions across different API requests and provides analytics capabilities for understanding user behavior.

If the client can't process cookies or uses a library that doesn't support set-cookie headers, the client should extract the returned session value and manually add it as a header in subsequent requests.

Args:

response: The HTTP response object to which the cookie and header will be added user_id: Optional user identifier to track users across multiple sessions

Returns:

ResultResponse[TrackingSession]: The newly created tracking session object with session ID, timestamp, and source.

Path
playout_idstring(Playout Id)required
Query
user_idstring(User Id)

Optional user ID to track users across sessions

Headers
X-API-Keystring(X-Api-Key)required

Required. API access key for authorized use of the checkout endpoints. Partners, please contact Transfermedia to retrieve a valid key.

X-JAY-TRACKINGstring(X-Jay-Tracking)

Tracking session header for user tracking and analytics. This is set by the /playouts/{playout_id}/tracking/session endpoint.

Example: eyJzZXNzaW9uX2lkIjoiZXhhbXBsZS1zZXNzaW9uLWlkLTEyMzQiLCJzdGFydF90aW1lIjoiMjAyNS0wMS0wMVQxMjowMDowMC4wMDAwMDAiLCJzb3VyY2UiOiJqYXkuYXBpLnBsYXlvdXQuZXhhbXBsZSJ9
curl -i -X POST \
  'https://live.playout.api.jay-metadata.com/v1/playouts/{playout_id}/tracking/session?user_id=string' \
  -H 'X-API-Key: string' \
  -H 'X-JAY-TRACKING: eyJzZXNzaW9uX2lkIjoiZXhhbXBsZS1zZXNzaW9uLWlkLTEyMzQiLCJzdGFydF90aW1lIjoiMjAyNS0wMS0wMVQxMjowMDowMC4wMDAwMDAiLCJzb3VyY2UiOiJqYXkuYXBpLnBsYXlvdXQuZXhhbXBsZSJ9'

Responses

Successfully created a new tracking session

Headers
Set-Cookiestring

Tracking session cookie with encoded session data

Example: "__Secure-jay_tracking=eyJzZXNz; Domain=jay-metadata.com; Path=/; Max-Age=86400; SameSite=Lax; Secure"
X-JAY-TRACKINGstring

Tracking session data in header format for clients that don't support cookies

Example: "eyJzZXNzaW9uX2lkIjoiZXhhbXBsZS1zZXNzaW9uLWlkLTEyMzQiLCJzdGFydF90aW1lIjoiMjAyNS0wMS0wMVQxMjowMDowMC4wMDAwMDAiLCJzb3VyY2UiOiJqYXkuYXBpLnBsYXlvdXQuZXhhbXBsZSJ9"
Bodyapplication/json
dataobject(The response data)

The response data.

Example: {"sessionId":"550e8400-e29b-41d4-a716-446655440000","startTime":"2023-01-15T14:30:24.123456","source":"jay.api.playout.1.0.0","userId":"user-123456","providerName":"netflix"}
nextTokenstring(Next token)

The token, which can be used to retrieve the next page of data.

errorobject(The error response)

Details of the error that occurred during the API request, including error code and message. This field is only present when the request results in an error.

Response
application/json
{
  "session_id": "b69d5c78-a2e9-4a7d-b3f8-c96c3a43d207",
  "start_time": "2023-04-21T14:32:17.123456",
  "source": "jay.api.playout.1.0.0",
  "user_id": "user-123456"
}

Delete tracking session

Request

Deletes the tracking session.

Removes the tracking session cookie from the client by sending appropriate cookie deletion headers. This effectively ends the tracking session and stops the correlation of user actions across different API requests.

Note that this only affects the cookie, not any header values the client might be storing independently. Clients using header-based tracking should stop sending the tracking header after calling this endpoint.

Args:

response: The HTTP response object to which cookie deletion headers will be added

request: The incoming HTTP request containing the session to be deleted

Returns:

ResultResponse[Dict[str, str]]: A message confirming the session was deleted

Path
playout_idstring(Playout Id)required
Headers
X-API-Keystring(X-Api-Key)required

Required. API access key for authorized use of the checkout endpoints. Partners, please contact Transfermedia to retrieve a valid key.

X-JAY-TRACKINGstring(X-Jay-Tracking)

Tracking session header for user tracking and analytics. This is set by the /playouts/{playout_id}/tracking/session endpoint.

Example: eyJzZXNzaW9uX2lkIjoiZXhhbXBsZS1zZXNzaW9uLWlkLTEyMzQiLCJzdGFydF90aW1lIjoiMjAyNS0wMS0wMVQxMjowMDowMC4wMDAwMDAiLCJzb3VyY2UiOiJqYXkuYXBpLnBsYXlvdXQuZXhhbXBsZSJ9
curl -i -X DELETE \
  'https://live.playout.api.jay-metadata.com/v1/playouts/{playout_id}/tracking/session' \
  -H 'X-API-Key: string' \
  -H 'X-JAY-TRACKING: eyJzZXNzaW9uX2lkIjoiZXhhbXBsZS1zZXNzaW9uLWlkLTEyMzQiLCJzdGFydF90aW1lIjoiMjAyNS0wMS0wMVQxMjowMDowMC4wMDAwMDAiLCJzb3VyY2UiOiJqYXkuYXBpLnBsYXlvdXQuZXhhbXBsZSJ9'

Responses

Tracking session successfully deleted

Headers
Set-Cookiestring

Cookie deletion header with immediate expiration

Example: "__Secure-jay_tracking=; Domain=jay-metadata.com; Path=/; expires=Thu, 01 Jan 1970 00:00:00 GMT; SameSite=Lax; Secure"
Bodyapplication/json
dataany(The response data)

The response data.

nextTokenstring(Next token)

The token, which can be used to retrieve the next page of data.

errorobject(The error response)

Details of the error that occurred during the API request, including error code and message. This field is only present when the request results in an error.

Response
application/json
{
  "message": "Tracking session deleted"
}

Formats

Access to formats metadata (aka movie collections or series).

Operations

Episodes

Access to episode metadata and general information.

Operations

Episode items

Information about episode items.

Operations

Episode timeline

Information about timeline events with complete timing information.

Operations

Episode groups

Information about existing groups.

Operations

Episode scenes

Information about the scenes.

Operations

Episode companies involved

Information about the involved companies.

Operations

API information

Operations