# Media Jay Playout API 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 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](https://docs.jay-metadata.com/) or contact Transfermedia . Version: 2025-09-02 ## Servers Production server ``` https://live.playout.api.jay-metadata.com/v1 ``` ## Download OpenAPI description [Media Jay Playout API](https://docs.jay-metadata.com/_spec/apis/playout/@latest/openapi.yaml) ## 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. ### Retrieve current tracking session - [GET /playouts/{playout_id}/tracking/session](https://docs.jay-metadata.com/apis/playout/latest/openapi/session-tracking/getactivetrackingsession.md): 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 2. Header with name 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. ### Initiate a new tracking session - [POST /playouts/{playout_id}/tracking/session](https://docs.jay-metadata.com/apis/playout/latest/openapi/session-tracking/createnewtrackingsession.md): 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. ### Delete tracking session - [DELETE /playouts/{playout_id}/tracking/session](https://docs.jay-metadata.com/apis/playout/latest/openapi/session-tracking/deletetrackingsession.md): 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 ## Formats Access to formats metadata (aka movie collections or series). ### List all available formats (aka movie collections or series) - [GET /playouts/{playoutId}/formats](https://docs.jay-metadata.com/apis/playout/latest/openapi/formats/listavailableformats.md): List all available formats (aka movie collections or series) for the specified playout. Note that due to paging (since X-API-Version 2025-08-27) a format may appear in multiple responses. ## Episodes Access to episode metadata and general information. ### List all available episodes - [GET /playouts/{playoutId}/episodes](https://docs.jay-metadata.com/apis/playout/latest/openapi/episodes/listavailableepisodes.md): Collects all episodes from the specified tenant's content library with optional filtering. This endpoint retrieves episodes from the content repository based on the provided tenant ID and applies any specified filters. It performs a search against the playout exporter configurations to find matching episodes and verifies their availability in the storage. The filtering system supports both exact matching and case-insensitive partial matching when the filter value is prefixed with a tilde (~). ### Get episode details - [GET /playouts/{playoutId}/episodes/{episodeId}](https://docs.jay-metadata.com/apis/playout/latest/openapi/episodes/getepisodedetails.md): Get comprehensive details about a specific episode including title, description, duration, and associated group information. This endpoint provides the foundation data needed to present an episode to viewers and provides access to its interactive components. Args: request: the complete request. playout_id: The playout identifier (aka tenant identifier). episode_id: The episode identifier inline_level: The number of levels to expand inner object inline. Returns: ResultResponse[PlayoutEpisode]: The Result response which contains the episode details. Raises: HTTPException: If the episode is not found (404) or descriptions are not available. ## Episode items Information about episode items. ### List all chapters in the episode - [GET /playouts/{playoutId}/episodes/{episodeId}/chapters](https://docs.jay-metadata.com/apis/playout/latest/openapi/episode-items/listchapters.md) ### Get chapter details. - [GET /playouts/{playoutId}/episodes/{episodeId}/chapters/{chapterId}](https://docs.jay-metadata.com/apis/playout/latest/openapi/episode-items/getchapter.md) ### List all products in the episode - [GET /playouts/{playoutId}/episodes/{episodeId}/products](https://docs.jay-metadata.com/apis/playout/latest/openapi/episode-items/listproducts.md) ### Get product details. - [GET /playouts/{playoutId}/episodes/{episodeId}/products/{productId}](https://docs.jay-metadata.com/apis/playout/latest/openapi/episode-items/getproduct.md) ### List all characters in the episode - [GET /playouts/{playoutId}/episodes/{episodeId}/characters](https://docs.jay-metadata.com/apis/playout/latest/openapi/episode-items/listcharacters.md) ### Get character details. - [GET /playouts/{playoutId}/episodes/{episodeId}/characters/{characterId}](https://docs.jay-metadata.com/apis/playout/latest/openapi/episode-items/getcharacter.md) ### List all actors in the episode - [GET /playouts/{playoutId}/episodes/{episodeId}/actors](https://docs.jay-metadata.com/apis/playout/latest/openapi/episode-items/listactors.md) ### Get actor details. - [GET /playouts/{playoutId}/episodes/{episodeId}/actors/{actorId}](https://docs.jay-metadata.com/apis/playout/latest/openapi/episode-items/getactor.md) ### List all locations in the episode - [GET /playouts/{playoutId}/episodes/{episodeId}/locations](https://docs.jay-metadata.com/apis/playout/latest/openapi/episode-items/listlocations.md) ### Get location details. - [GET /playouts/{playoutId}/episodes/{episodeId}/locations/{locationId}](https://docs.jay-metadata.com/apis/playout/latest/openapi/episode-items/getlocation.md) ### List all costumes in the episode - [GET /playouts/{playoutId}/episodes/{episodeId}/costumes](https://docs.jay-metadata.com/apis/playout/latest/openapi/episode-items/listcostumes.md) ### Get costume details. - [GET /playouts/{playoutId}/episodes/{episodeId}/costumes/{costumeId}](https://docs.jay-metadata.com/apis/playout/latest/openapi/episode-items/getcostume.md) ### List all props in the episode - [GET /playouts/{playoutId}/episodes/{episodeId}/props](https://docs.jay-metadata.com/apis/playout/latest/openapi/episode-items/listprops.md) ### Get prop details. - [GET /playouts/{playoutId}/episodes/{episodeId}/props/{propId}](https://docs.jay-metadata.com/apis/playout/latest/openapi/episode-items/getprop.md) ### List all musics in the episode - [GET /playouts/{playoutId}/episodes/{episodeId}/musics](https://docs.jay-metadata.com/apis/playout/latest/openapi/episode-items/listmusics.md) ### Get music details. - [GET /playouts/{playoutId}/episodes/{episodeId}/musics/{musicId}](https://docs.jay-metadata.com/apis/playout/latest/openapi/episode-items/getmusic.md) ### List all tickets in the episode - [GET /playouts/{playoutId}/episodes/{episodeId}/tickets](https://docs.jay-metadata.com/apis/playout/latest/openapi/episode-items/listtickets.md) ### Get ticket details. - [GET /playouts/{playoutId}/episodes/{episodeId}/tickets/{ticketId}](https://docs.jay-metadata.com/apis/playout/latest/openapi/episode-items/getticket.md) ### List all themes in the episode - [GET /playouts/{playoutId}/episodes/{episodeId}/themes](https://docs.jay-metadata.com/apis/playout/latest/openapi/episode-items/listthemes.md) ### Get theme details. - [GET /playouts/{playoutId}/episodes/{episodeId}/themes/{themeId}](https://docs.jay-metadata.com/apis/playout/latest/openapi/episode-items/gettheme.md) ### List all basics in the episode - [GET /playouts/{playoutId}/episodes/{episodeId}/basics](https://docs.jay-metadata.com/apis/playout/latest/openapi/episode-items/listbasics.md) ### Get basic details. - [GET /playouts/{playoutId}/episodes/{episodeId}/basics/{basicId}](https://docs.jay-metadata.com/apis/playout/latest/openapi/episode-items/getbasic.md) ## Episode timeline Information about timeline events with complete timing information. ### Retrieve all timeline events for an episode - [GET /playouts/{playoutId}/episodes/{episodeId}/timeline/events](https://docs.jay-metadata.com/apis/playout/latest/openapi/episode-timeline/listtimelineevents.md): Retrieves all timeline events from an episode with optional time filtering. Timeline events represent time-based points or ranges within the content where interactive elements, metadata, or other content enhancements are available. These events are the foundation for interactive video experiences and synchronized metadata display. Timeline events enable precisely timed interactions, product placements, character information, and other contextual content to appear at appropriate moments during playback. The timeline events system supports two types of time filtering: 1. Millisecond-based filtering: Using the absolute time in milliseconds from the start 2. Timecode filtering: Using industry-standard SMPTE timecode (hh:mm:ss:ff) Each event has a kind that indicates what type of content it represents (scene, product, character, etc.) and contains references or inline data about that content. ## Episode groups Information about existing groups. ### List all groups in the episode - [GET /playouts/{playoutId}/episodes/{episodeId}/groups](https://docs.jay-metadata.com/apis/playout/latest/openapi/episode-groups/listgroups.md) ### Get group details. - [GET /playouts/{playoutId}/episodes/{episodeId}/groups/{groupId}](https://docs.jay-metadata.com/apis/playout/latest/openapi/episode-groups/getgroup.md) ## Episode scenes Information about the scenes. ### List all scenes in an episode - [GET /playouts/{playoutId}/episodes/{episodeId}/scenes](https://docs.jay-metadata.com/apis/playout/latest/openapi/episode-scenes/listscenes.md): Retrieves all scenes from an episode's timeline with optional time-based filtering. Scenes are sequential segments of the episode that may contain interactive elements, products, or other metadata. They provide a time-based structure for the content and can be used for navigation and interaction points. Scenes form the narrative structure of the content and help viewers understand the context for interactive elements that appear during playback. The scenes can be filtered by a specific timestamp (in milliseconds or timecode format) to find which scene is active at a particular moment in the playback. When inline=true is specified, referenced objects within scenes (such as products, characters, or locations) will be expanded with their full data rather than just providing references. ### Get scene details - [GET /playouts/{playoutId}/episodes/{episodeId}/scenes/{sceneId}](https://docs.jay-metadata.com/apis/playout/latest/openapi/episode-scenes/getscene.md): Get the detailed information about a specific scene in the episode. This endpoint returns timing information, associated products, characters, and other relevant metadata for a specific scene. Scenes are fundamental narrative units that provide context for interactive elements and help organize the viewing experience. Args: request: the complete request. playout_id: The playout identifier (aka tenant identifier). episode_id: The episode identifier scene_id: The data identifier inline_level: The number of levels to expand inner object inline. Returns: ResultResponse[PlayoutScene]: Result Response contains the requested scene details. Raises: HTTPException: If the episode, descriptions, timeline, or specific scene are not found (404). ## Episode companies involved Information about the involved companies. ### Get detailed information about the streaming platform provider - [GET /playouts/{playoutId}/episodes/{episodeId}/companies/affiliate](https://docs.jay-metadata.com/apis/playout/latest/openapi/episode-companies-involved/getaffiliate.md): Retrieves comprehensive information about the streaming platform (affiliate) serving this content. This includes branding assets, website URLs, and other metadata needed to properly attribute and integrate with the streaming service in client applications. This endpoint provides client applications with the necessary branding assets, URLs, and metadata about the streaming platform to properly attribute content and maintain consistent branding in the user interface. The affiliate information includes: - Platform name and branding assets (logos, colors) - Website URLs for the main site, terms of service, and privacy policy - Contact information for support or partnership inquiries - Other platform-specific metadata This data should be used to ensure proper attribution and brand consistency in any client applications that integrate with this content. Args: request: the complete request. playout_id: The playout identifier (aka tenant identifier) for authentication and affiliate identification. episode_id: The episode identifier, used to access the episode's data. Returns: ResultResponse[PlayoutAffiliate]: Result response contains Comprehensive information about the streaming platform, including name, URLs, branding assets, and contact information. Raises: ApiHttpException: When the episode data cannot be found or when affiliate information is unavailable or malformed. ### List retailer/e-commerce platforms (merchants) involved. - [GET /playouts/{playoutId}/episodes/{episodeId}/companies/merchants](https://docs.jay-metadata.com/apis/playout/latest/openapi/episode-companies-involved/listmerchants.md): Get information about the retailer/e-commerce platforms (merchants) involved. ### Details about a retailer/e-commerce platform (merchant). - [GET /playouts/{playoutId}/episodes/{episodeId}/companies/merchants/{merchantId}](https://docs.jay-metadata.com/apis/playout/latest/openapi/episode-companies-involved/getmerchant.md): Get information about a specific retailer/e-commerce platform (merchant). Args: request: the complete request. playout_id: The playout identifier (aka tenant identifier). episode_id: The episode identifier merchant_id: The merchant identifier (shop source). Returns: ResultResponse[PlayoutMerchant]: Result response contains the merchant details. Raises: ApiHttpException: If the episode, merchant list, or specific merchant are not found (404). ## API information ### Api Version - [GET /version](https://docs.jay-metadata.com/apis/playout/latest/openapi/api-information/api_version_version_get.md)