{
  "swagger": "2.0",
  "info": {
    "description": "The Media Collection API is a server-side, RESTful equivalent of the client-side Media SDK for tracking streaming audio and video in Adobe Analytics. A media session is composed on Adobe's servers from a `sessions` call followed by a series of `events` calls, which are aggregated into media metrics. \n\n **Endpoint host:** The host is a provisioned endpoint of the form `<company>.hb-api.omtrdc.net`. Obtain your host from your Adobe representative. The `example.hb-api.omtrdc.net` host shown here is a placeholder. \n\n **Content type:** All request bodies must be JSON. Set the `Content-Type: application/json` request header on every call. \n\n Note: Adobe can add optional fields to API requests and responses at any time, without notice or a version change. Build your integration to ignore fields it doesn't recognize so that these additions don't break it. Adobe doesn't remove fields or add required fields without first announcing the change in release notes.",
    "version": "1.0",
    "title": "Media Collection API"
  },
  "host": "example.hb-api.omtrdc.net",
  "basePath": "/api/v1",
  "tags": [
    {
      "name": "Sessions",
      "description": "Start a media tracking session."
    },
    {
      "name": "Events",
      "description": "Send playback events to an active session."
    },
    {
      "name": "Schemas",
      "description": "Retrieve the JSON validation schema for an event type."
    }
  ],
  "schemes": [
    "https"
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "parameters": {
    "content-type": {
      "name": "Content-Type",
      "in": "header",
      "description": "Must be `application/json`.",
      "required": true,
      "type": "string",
      "default": "application/json"
    }
  },
  "paths": {
    "/sessions": {
      "post": {
        "tags": [
          "Sessions"
        ],
        "summary": "Start a media session",
        "description": "Starts a new media tracking session with a `sessionStart` event. On success the response returns `201 Created` with the session path in the `Location` header. Parse the trailing session ID from that header and use it in all subsequent events calls. Your app calls this once at the start of a tracking session.",
        "operationId": "createSession",
        "parameters": [
          {
            "$ref": "#/parameters/content-type"
          },
          {
            "name": "body",
            "in": "body",
            "description": "A `sessionStart` event. The `params` object carries the required Analytics, visitor, and media parameters.",
            "required": true,
            "schema": {
              "$ref": "#/definitions/MediaEvent"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Session created. The session ID is returned in the `Location` response header.",
            "headers": {
              "Location": {
                "type": "string",
                "description": "The relative path of the created session, in the form `/api/v1/sessions/{sid}`. Parse the `{sid}` segment and use it for events requests."
              }
            }
          },
          "400": {
            "description": "Bad request. The request body did not pass validation for the event type. See the JSON validation schema for the event type.",
            "schema": {
              "$ref": "#/definitions/ApiError"
            }
          },
          "500": {
            "description": "Server error.",
            "schema": {
              "$ref": "#/definitions/ApiError"
            }
          }
        }
      }
    },
    "/sessions/{sid}/events": {
      "post": {
        "tags": [
          "Events"
        ],
        "summary": "Send an event",
        "description": "Sends a playback event (such as `play`, `ping`, `pauseStart`, `bufferStart`, `bitrateChange`, `chapterStart`, or an ad event) to an active session. The request body has the same structure as a sessions request. A successful call returns `204 No Content`; the endpoint does not return a body.",
        "operationId": "sendEvent",
        "parameters": [
          {
            "name": "sid",
            "in": "path",
            "description": "The session ID returned in the `Location` header of the sessions request.",
            "required": true,
            "type": "string"
          },
          {
            "$ref": "#/parameters/content-type"
          },
          {
            "name": "body",
            "in": "body",
            "description": "A media tracking event.",
            "required": true,
            "schema": {
              "$ref": "#/definitions/MediaEvent"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "No content. The event was accepted successfully."
          },
          "400": {
            "description": "Bad request. The request had an improper format. Check the JSON validation schema for the event type.",
            "schema": {
              "$ref": "#/definitions/ApiError"
            }
          },
          "404": {
            "description": "Not found. The session ID was not found. Start a new session with the sessions endpoint.",
            "schema": {
              "$ref": "#/definitions/ApiError"
            }
          },
          "410": {
            "description": "Gone. The session is closed and can no longer report activity. Start a new session with the sessions endpoint.",
            "schema": {
              "$ref": "#/definitions/ApiError"
            }
          },
          "500": {
            "description": "Server error.",
            "schema": {
              "$ref": "#/definitions/ApiError"
            }
          }
        }
      }
    },
    "/schemas/{eventType}": {
      "get": {
        "tags": [
          "Schemas"
        ],
        "summary": "Get a validation schema",
        "description": "Returns the publicly accessible JSON validation schema that the back end uses to validate the request body for a given event type. These schemas are the authority for which parameters are required or optional, and their data types.",
        "operationId": "getSchema",
        "parameters": [
          {
            "name": "eventType",
            "in": "path",
            "description": "The event type to retrieve the schema for, for example `sessionStart` or `ping`.",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "The JSON validation schema for the requested event type.",
            "schema": {
              "type": "object"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "ApiError": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string",
          "example": "Request had improper format.",
          "description": "A description of the error."
        }
      }
    },
    "EventType": {
      "type": "string",
      "description": "The media tracking event type sent on the wire.",
      "enum": [
        "sessionStart",
        "sessionComplete",
        "sessionEnd",
        "adBreakStart",
        "adBreakComplete",
        "adStart",
        "adComplete",
        "adSkip",
        "chapterStart",
        "chapterComplete",
        "chapterSkip",
        "play",
        "ping",
        "bufferStart",
        "pauseStart",
        "bitrateChange",
        "error",
        "stateStart",
        "stateEnd"
      ]
    },
    "PlayerTime": {
      "type": "object",
      "description": "The playhead position and timestamp of the event. Required on every request.",
      "required": [
        "playhead",
        "ts"
      ],
      "properties": {
        "playhead": {
          "type": "number",
          "example": 0,
          "description": "The playhead position, in seconds."
        },
        "ts": {
          "type": "integer",
          "format": "int64",
          "example": 1731672000000,
          "description": "The client-side timestamp of the event, in milliseconds since the Unix epoch."
        }
      }
    },
    "Params": {
      "type": "object",
      "description": "Analytics, visitor, and media parameters. The required members depend on the event type; see the request parameters reference and the JSON validation schema for each event type.",
      "properties": {
        "analytics.trackingServer": {
          "type": "string",
          "example": "example.data.adobedc.net",
          "description": "The Analytics tracking server."
        },
        "analytics.reportSuite": {
          "type": "string",
          "example": "example-rsid",
          "description": "The Analytics report suite ID that receives the data."
        },
        "analytics.enableSSL": {
          "type": "boolean",
          "example": true,
          "description": "Whether to send Analytics data over HTTPS."
        },
        "analytics.visitorId": {
          "type": "string",
          "description": "The Analytics visitor ID."
        },
        "analytics.aid": {
          "type": "string",
          "description": "The Analytics legacy user ID (aid)."
        },
        "visitor.marketingCloudOrgId": {
          "type": "string",
          "example": "0123456789ABCDEF0123456789@AdobeOrg",
          "description": "The IMS organization ID."
        },
        "visitor.marketingCloudUserId": {
          "type": "string",
          "description": "The ECID of the visitor."
        },
        "visitor.aamLocationHint": {
          "type": "integer",
          "description": "The Audience Manager location hint (region) for the visitor."
        },
        "media.id": {
          "type": "string",
          "example": "sample-video-id",
          "description": "The unique content ID for the media item."
        },
        "media.name": {
          "type": "string",
          "example": "Sample video",
          "description": "The human-friendly name of the media item."
        },
        "media.length": {
          "type": "number",
          "example": 3600,
          "description": "The length of the content, in seconds."
        },
        "media.contentType": {
          "type": "string",
          "example": "vod",
          "description": "The content type, for example `vod` or `live`."
        },
        "media.playerName": {
          "type": "string",
          "example": "sample-html5-player",
          "description": "The name of the media player in use."
        },
        "media.channel": {
          "type": "string",
          "example": "sample-channel",
          "description": "The channel or property the content plays on."
        }
      }
    },
    "QoeData": {
      "type": "object",
      "description": "Optional quality-of-experience data. May be sent with any event.",
      "properties": {
        "media.qoe.bitrate": {
          "type": "integer",
          "description": "The current bitrate, in bits per second."
        },
        "media.qoe.droppedFrames": {
          "type": "integer",
          "description": "The number of dropped frames."
        },
        "media.qoe.framesPerSecond": {
          "type": "integer",
          "description": "The current frame rate."
        },
        "media.qoe.timeToStart": {
          "type": "integer",
          "description": "The time, in milliseconds, from the play request until playback started."
        },
        "media.qoe.errorID": {
          "type": "string",
          "description": "An identifier for a player error."
        },
        "media.qoe.errorSource": {
          "type": "string",
          "description": "The source of the error, for example `player`."
        }
      }
    },
    "CustomMetadata": {
      "type": "object",
      "description": "Free-form string key-value pairs. Sent only with the `sessionStart`, `adStart`, and `chapterStart` event types. All values must be strings.",
      "additionalProperties": {
        "type": "string"
      }
    },
    "MediaEvent": {
      "type": "object",
      "required": [
        "eventType",
        "playerTime"
      ],
      "properties": {
        "eventType": {
          "$ref": "#/definitions/EventType"
        },
        "playerTime": {
          "$ref": "#/definitions/PlayerTime"
        },
        "params": {
          "$ref": "#/definitions/Params"
        },
        "qoeData": {
          "$ref": "#/definitions/QoeData"
        },
        "customMetadata": {
          "$ref": "#/definitions/CustomMetadata"
        }
      },
      "example": {
        "playerTime": {
          "playhead": 0,
          "ts": 1731672000000
        },
        "eventType": "sessionStart",
        "params": {
          "analytics.trackingServer": "example.data.adobedc.net",
          "analytics.reportSuite": "example-rsid",
          "analytics.enableSSL": true,
          "visitor.marketingCloudOrgId": "0123456789ABCDEF0123456789@AdobeOrg",
          "media.id": "sample-video-id",
          "media.name": "Sample video",
          "media.length": 3600,
          "media.contentType": "vod",
          "media.playerName": "sample-html5-player",
          "media.channel": "sample-channel"
        }
      }
    }
  }
}