openapi: 3.2.0 info: title: Media Edge Session API description: The OpenAPI specification for Media Edge API version: 0.1.0 servers: - url: https://edge.adobedc.net/ee/va/v1 tags: - name: Session paths: /sessionStart: post: summary: Session start description: Signals the start of a new session. When the response returns, the "sessionId" must be extracted and sent for all subsequent event calls to the Edge API server tags: - Session operationId: sessionStart parameters: - name: configId in: query description: The datastream id schema: type: string required: true requestBody: content: application/json: schema: type: object properties: events: type: array description: '' items: type: object properties: xdm: type: object description: '' properties: mediaCollection: type: object description: '' properties: playhead: type: integer description: The Playhead represents the current playback position within the media content sessionDetails: type: object description: '' properties: adLoad: type: string description: The type of ad loaded as defined by each customer’s internal representation appVersion: type: string description: The SDK version used by the player artist: type: string description: The name of the album artist or group performing the music recording or video rating: type: string description: The rating as defined by TV Parental Guidelines show: type: string description: The Program/Series Name channel: type: string description: The Content Channel is the distribution channel from where the content was played episode: type: string description: The number of the episode originator: type: string description: The name of the content creator firstAirDate: type: string description: 'The date when the content first aired on television. Any date format is acceptable, but Adobe recommends: YYYY-MM-DD' streamType: type: string description: The type of the media stream enum: - audio - video authorized: type: string description: Confirms whether the user has been authorized via Adobe authentication hasResume: type: boolean description: Marks each playback that was resumed after more than 30 minutes of buffer, pause, or stall period streamFormat: type: string description: The format of the stream (HD, SD) station: type: string description: The radio station name on which the audio is played genre: type: string description: The type or grouping of content as defined by the content producer season: type: string description: The Season Number that the show belongs to showType: type: string description: The type of content contentType: type: string description: The Broadcast Content Type of the stream delivery friendlyName: type: string description: The Content Name is the “friendly” (human-readable) name of the content playerName: type: string description: The name of the content player author: type: string description: The name of the media author album: type: string description: The name of the album that the music recording or video belongs to length: type: integer description: The Media Content Length contains the clip length/runtime dayPart: type: string description: A property that defines the time of the day when the content was broadcast or played label: type: string description: The name of the record label mvpd: type: string description: The Multi-channel Video Programming Distributor (MVPD) identifier that was provided via Adobe authentication feed: type: string description: The type of feed, which can either represent actual feed-related data such as EAST HD or SD, or the source of the feed like a URL assetID: type: string description: The Asset ID is the unique identifier for the content of the media asset name: type: string description: The Content ID is a unique identifier of the content publisher: type: string description: The name of the audio content publisher firstDigitalDate: type: string description: 'The date when the content first aired on any digital channel or platform. Any date format is acceptable but Adobe recommends: YYYY-MM-DD' network: type: string description: The network/channel name isDownloaded: type: boolean description: Specifies if this is a previously recorded session required: - name - playerName - length - channel - contentType customMetadata: type: array description: Custom data set by the client in the form of key->value pairs items: type: object properties: name: type: string description: The name of the custom property preceded by _{tenantName} value: type: string description: The value of the custom property qoeDataDetails: type: object description: QoE (Quality of Experience) Data Details capture performance-related metrics and user experience data properties: bitrate: type: integer format: int32 description: The bitrate value (in kbps) droppedFrames: type: integer format: int32 description: The total count of frames dropped during playback framesPerSecond: type: integer format: int32 description: The current stream frame-rate (in frames per second) timeToStart: type: integer format: int32 description: Duration (in seconds) between video load and start required: - playhead - sessionDetails identityMap: type: object description: Specifies the list of identities properties: FPID: type: array description: '' items: type: object properties: id: type: string description: '' authenticatedState: type: string description: '' default: ambiguous enum: - ambiguous - authenticated - loggedOut primary: type: boolean description: '' eventType: type: string default: media.sessionStart description: The media event type timestamp: type: string format: date-time description: The time when a media event occurred required: - mediaCollection - timestamp - eventType required: - xdm examples: '0': value: events: - xdm: mediaCollection: sessionDetails: dayPart: dayPart mvpd: test-mvpd authorized: 'true' label: test-label station: test-station publisher: test-media-publisher author: test-author name: Friends friendlyName: FriendlyName assetID: /uri-reference originator: David Crane and Marta Kauffman episode: '4933' genre: Comedy rating: 4.8/5 season: '1521' show: Friends Series length: 100 firstDigitalDate: releaseDate artist: test-artist hasResume: false album: test-album firstAirDate: firstAirDate showType: sitcom streamFormat: streamFormat streamType: video adLoad: adLoadType channel: broadcastChannel contentType: VOD playerName: HTML5 player appVersion: sdk-1.0 feed: sourceFeed network: test-network playhead: 0 customMetadata: - name: _{tenantName}.myCustomValue3 value: c3 - name: _{tenantName}.myCustomValue2 value: c2 - name: _{tenantName}.myCustomValue1 value: c1 timestamp: '2023-04-04T11:35:16Z' identityMap: FPID: - id: CHANGEME authenticatedState: ambiguous primary: true eventType: media.sessionStart responses: '200': description: OK content: application/json: schema: type: object properties: requestId: type: string description: Id that uniquely identifies a request handle: type: array description: The data returned by the backend items: type: object properties: payload: type: array description: '' items: type: object properties: sessionId: type: string description: The unique id for the session that must be sent on all the future requests of this session type: type: string description: Identifies the type of the received payload eventIndex: type: integer format: int32 description: '' examples: '0': value: requestId: dd850e05-8c3e-4ae4-9ea8-506490978004 handle: - payload: - sessionId: bfba9a5f2986d69a9a9424f6a99702562512eb244f2b65c4f1c1553e7fe9997f type: media-analytics:new-session eventIndex: 0 - payload: - scope: Target hint: '34' ttlSeconds: 1800 - scope: AAM hint: '7' ttlSeconds: 1800 - scope: EdgeNetwork hint: va6 ttlSeconds: 1800 type: locationHint:result - payload: - key: kndctr_EA0C49475E8AE1870A494023_AdobeOrg_cluster value: va6 maxAge: 1800 - key: kndctr_EA0C49475E8AE1870A494023_AdobeOrg_identity value: CiY0Mzg5NTEyNzMzNTUxMDc5MzgzMzU2MjU5NDY5MTY3Mzc3MTc2OFIOCJ-YppX6MBgBKgNWQTbwAZ-YppX6MA== maxAge: 34128000 type: state:store '207': description: Multi-Status content: application/json: schema: type: object properties: requestId: type: string description: Id that uniquely identifies a request handle: type: array description: The data returned by the backend items: type: object properties: payload: type: array description: '' items: type: object type: type: string description: Identifies the type of the received payload eventIndex: type: integer format: int32 description: '' errors: type: array description: The list of errors for the data sent in this request items: type: object properties: type: type: string description: Link containing a more detailed description of the error status: type: integer description: The status code title: type: string description: The category of the error report: type: object description: '' properties: eventIndex: type: integer format: int32 description: '' report: type: array description: '' items: type: object properties: name: type: string description: The path in the request body to the property that contains the error reason: type: string description: The error details examples: '0': value: requestId: e3d87437-5054-4bc2-8953-be4be8d0b900 handle: - payload: - scope: Target hint: '34' ttlSeconds: 1800 - scope: AAM hint: '7' ttlSeconds: 1800 - scope: EdgeNetwork hint: va6 ttlSeconds: 1800 type: locationHint:result - payload: - key: kndctr_EA0C49475E8AE1870A494023_AdobeOrg_cluster value: va6 maxAge: 1800 - key: kndctr_EA0C49475E8AE1870A494023_AdobeOrg_identity value: CiY0Mzg5NTEyNzMzNTUxMDc5MzgzMzU2MjU5NDY5MTY3Mzc3MTc2OFIOCI-qtpf6MBgBKgNWQTbwAY-qtpf6MA== maxAge: 34128000 type: state:store errors: - type: https://ns.adobe.com/aep/errors/va-edge-0400-400 status: 400 title: Invalid request report: eventIndex: 0 details: - name: $.xdm.mediaCollection.sessionDetails.name reason: Missing required field '400': description: Bad request content: application/json: schema: type: object description: '' properties: type: type: string description: Link containing a more detailed description of the error status: type: integer default: 400 description: The status code title: type: string description: The category of the error detail: type: string description: The error details report: type: object description: '' properties: requestId: type: string description: Id that uniquely identifies a request details: type: string description: The error details examples: '0': value: type: https://ns.adobe.com/aep/errors/EXEG-0003-400 status: 400 title: Invalid datastream ID detail: The datastream ID '66b64400-e418-4184-8fed-b57636d09' referenced in your request does not exist. Update the request with a valid datastream ID and try again. report: requestId: 75af7733-9c8a-45a9-b2a1-bb570c58a0da /sessionComplete: post: summary: Session complete description: Signals when the end of the main content was reached tags: - Session operationId: sessionComplete parameters: [] requestBody: content: application/json: schema: type: object properties: events: type: array description: '' items: type: object properties: xdm: type: object description: '' properties: mediaCollection: type: object description: '' properties: playhead: type: integer description: The Playhead represents the current playback position within the media content sessionID: type: string description: The Media Session ID uniquely identifies an instance of a content stream during an individual playback session qoeDataDetails: type: object description: QoE (Quality of Experience) Data Details capture performance-related metrics and user experience data properties: bitrate: type: integer format: int32 description: The bitrate value (in kbps) droppedFrames: type: integer format: int32 description: The total count of frames dropped during playback framesPerSecond: type: integer format: int32 description: The current stream frame-rate (in frames per second) timeToStart: type: integer format: int32 description: Duration (in seconds) between video load and start required: - playhead - sessionID eventType: type: string default: media.sessionComplete description: The media event type timestamp: type: string format: date-time description: The time when a media event occurred required: - mediaCollection - timestamp - eventType required: - xdm examples: '0': value: events: - xdm: eventType: media.sessionComplete mediaCollection: sessionID: 5c32e1a6ef6b58be5136ba8db2f79f1d251d3121a898bc8fb60123b8fdb9aa1c playhead: 25 timestamp: '2022-03-04T13:39:00+00:00' responses: '204': description: No content '400': description: Bad request content: application/json: schema: type: object description: '' properties: type: type: string description: Link containing a more detailed description of the error status: type: integer default: 400 description: The status code title: type: string description: The category of the error detail: type: string description: The error details report: type: object description: '' properties: requestId: type: string description: Id that uniquely identifies a request details: type: array description: '' items: type: object description: '' properties: name: type: string description: The path to the invalid property reason: type: string description: The reason why the property is invalid examples: '0': value: type: https://ns.adobe.com/aep/errors/va-edge-0400-400 status: 400 title: Bad Request detail: Invalid request. Please check your input and try again. report: details: - name: $.events[0].xdm.mediaCollection.playhead reason: Missing required field requestId: e3d87437-5054-4bc2-8953-be4be8d0b900 '404': description: Not found content: application/json: schema: type: object description: '' properties: type: type: string description: Link containing a more detailed description of the error status: type: integer default: 404 description: The status code title: type: string description: The category of the error detail: type: string description: The error details report: type: object description: '' properties: requestId: type: string description: Id that uniquely identifies a request details: type: string description: The error details examples: '0': value: type: https://ns.adobe.com/aep/errors/va-edge-0404-404 status: 404 title: Not Found detail: The requested resource could not be found but may be available again in the future. report: details: Error processing request. If the session is longer than 24h, please start a new one. Returning Not Found requestId: e3d87437-5054-4bc2-8953-be4be8d0b900 /sessionEnd: post: summary: Session end description: Notifies Adobe to immediately close the session. Used when the user has abandoned their viewing of the content and they are unlikely to return. If you don't use this endpoint, an abandoned session times out normally (after no events are received for 10 minutes, or when no playhead movement occurs for 30 minutes), ending the session. tags: - Session operationId: sessionEnd parameters: [] requestBody: content: application/json: schema: type: object properties: events: type: array description: '' items: type: object properties: xdm: type: object description: '' properties: mediaCollection: type: object description: '' properties: playhead: type: integer description: The Playhead represents the current playback position within the media content sessionID: type: string description: The Media Session ID uniquely identifies an instance of a content stream during an individual playback session qoeDataDetails: type: object description: QoE (Quality of Experience) Data Details capture performance-related metrics and user experience data properties: bitrate: type: integer format: int32 description: The bitrate value (in kbps) droppedFrames: type: integer format: int32 description: The total count of frames dropped during playback framesPerSecond: type: integer format: int32 description: The current stream frame-rate (in frames per second) timeToStart: type: integer format: int32 description: Duration (in seconds) between video load and start required: - playhead - sessionID eventType: type: string default: media.sessionEnd description: The media event type timestamp: type: string format: date-time description: The time when a media event occurred required: - mediaCollection - timestamp - eventType required: - xdm examples: '0': value: events: - xdm: eventType: media.sessionEnd mediaCollection: sessionID: 5c32e1a6ef6b58be5136ba8db2f79f1d251d3121a898bc8fb60123b8fdb9aa1c playhead: 25 timestamp: '2022-03-04T13:39:00+00:00' responses: '204': description: No content '400': description: Bad request content: application/json: schema: type: object description: '' properties: type: type: string description: Link containing a more detailed description of the error status: type: integer default: 400 description: The status code title: type: string description: The category of the error detail: type: string description: The error details report: type: object description: '' properties: requestId: type: string description: Id that uniquely identifies a request details: type: array description: '' items: type: object description: '' properties: name: type: string description: The path to the invalid property reason: type: string description: The reason why the property is invalid examples: '0': value: type: https://ns.adobe.com/aep/errors/va-edge-0400-400 status: 400 title: Bad Request detail: Invalid request. Please check your input and try again. report: details: - name: $.events[0].xdm.mediaCollection.playhead reason: Missing required field requestId: e3d87437-5054-4bc2-8953-be4be8d0b900 '404': description: Not found content: application/json: schema: type: object description: '' properties: type: type: string description: Link containing a more detailed description of the error status: type: integer default: 404 description: The status code title: type: string description: The category of the error detail: type: string description: The error details report: type: object description: '' properties: requestId: type: string description: Id that uniquely identifies a request details: type: string description: The error details examples: '0': value: type: https://ns.adobe.com/aep/errors/va-edge-0404-404 status: 404 title: Not Found detail: The requested resource could not be found but may be available again in the future. report: details: Error processing request. If the session is longer than 24h, please start a new one. Returning Not Found requestId: e3d87437-5054-4bc2-8953-be4be8d0b900