openapi: 3.0.1
info:
  title: Partner Content Assets Reporting API
  version: 0.1.17
  description: These endpoints allows your application to upload assets such as images or audio.
servers:
- url: https://partner-content-api.epidemicsound.com
  description: Epidemic Sound Content API
tags:
- name: Reporting
  description: These endpoints will allow you to report how tracks are used in your application.
paths:
  /v0/analytics/report:
    post:
      tags:
      - Reporting
      summary: Report usage in bulk
      description: "This endpoint should be used when you want to bulk report events to Epidemic Sound. We currently support the following events:\ntrackPreviewed, trackDownloaded and tracksExported. Note that the limit for number of events per request is limited to 100.\n Also note that for events containing the field trackIds, the limit for number of trackIds per event is 50. \n Events may not contain a timestamp older than 7 days ago."
      operationId: POST_Analytics_Report
      requestBody:
        description: Analytics report
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyticsReportRequest'
            example:
              events:
              - userId: '123'
                timestamp: '2026-05-11T07:45:47.634091607Z'
                userConnected: false
                analyticsEvent:
                  trackId: '12345'
                  type: trackPreviewed
              - userId: '456'
                timestamp: '2026-05-11T07:45:47.634810417Z'
                userConnected: true
                analyticsEvent:
                  trackId: '12345'
                  format: mp3
                  quality: normal
                  type: trackDownloaded
              - userId: '456'
                timestamp: '2026-05-11T07:45:47.635468127Z'
                analyticsEvent:
                  trackIds:
                  - '12345'
                  platform: YOUTUBE
                  type: tracksExported
      responses:
        '200':
          description: Usage report response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsReportResponse'
              example:
                batchId: '12345'
                eventsCount: 10
        '401':
          description: Unauthorized. Most likely your access token has expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              example:
                message: Invalid credentials
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              example:
                message: Rate limit exceeded
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              example:
                message: Bad request
      security:
      - PartnerAuth: []
      - ApiKeyAuth: []
  /v0/usage:
    post:
      tags:
      - Reporting
      summary: Report usage
      description: 'The usage endpoint lets you report when a user exports their content to social media or downloads the content file to their device.

        You can specify which platform (YouTube, Twitch, Instagram, Facebook, TikTok, Twitter or Other) they export the file to. Use the platform `local` if the user downloads the content to their device.

        This data is used for attribution and analytics purposes as well as to improve personalization.'
      operationId: POST_Use
      requestBody:
        description: Usage report
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrackUsageRequest'
            example:
              eventType: EXPORTED
              platform: OTHER
              trackIds:
              - trackid1
              - trackid2
              other: OptionalValueForWhenNoMatchingPlatformEnum
      responses:
        '200':
          description: Usage report response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              example:
                message: Ok
        '401':
          description: Unauthorized. Most likely your access token has expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              example:
                message: Invalid credentials
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              example:
                message: Rate limit exceeded
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              example:
                message: Bad request
      security:
      - UserAuth: []
      - EpidemicSoundConnectAuth: []
      - ApiKeyAuth: []
components:
  schemas:
    TracksExportedEvent:
      type: object
      properties:
        trackIds:
          type: array
          items:
            type: string
        platform:
          type: string
          enum:
          - YOUTUBE
          - TWITTER
          - TWITCH
          - FACEBOOK
          - INSTAGRAM
          - TIKTOK
          - OTHER
          - LOCAL
        type:
          type: string
          enum:
          - tracksExported
    AnalyticsReportResponse:
      required:
      - batchId
      - eventsCount
      type: object
      properties:
        batchId:
          type: string
        eventsCount:
          type: integer
          format: int32
    AnalyticsReportEvent:
      type: object
      properties:
        userId:
          type: string
        timestamp:
          type: string
          format: date-time
        userConnected:
          type: boolean
          nullable: true
        analyticsEvent:
          $ref: '#/components/schemas/AnalyticsEvent'
    Error:
      required:
      - key
      - messages
      type: object
      properties:
        key:
          type: string
          description: Error key
        messages:
          type: array
          description: Error messages
          items:
            type: string
            description: Error messages
    MessageResponse:
      required:
      - message
      type: object
      properties:
        message:
          type: string
          description: Human readable message
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    AnalyticsEvent:
      type: object
      oneOf:
      - $ref: '#/components/schemas/TrackPreviewedEvent'
      - $ref: '#/components/schemas/TrackDownloadedEvent'
      - $ref: '#/components/schemas/TracksExportedEvent'
    TrackUsageRequest:
      required:
      - platform
      - trackIds
      type: object
      properties:
        eventType:
          type: string
          enum:
          - EXPORTED
        platform:
          type: string
          enum:
          - YOUTUBE
          - TWITTER
          - TWITCH
          - FACEBOOK
          - INSTAGRAM
          - TIKTOK
          - OTHER
          - LOCAL
        trackIds:
          type: array
          items:
            type: string
        other:
          type: string
          nullable: true
    TrackDownloadedEvent:
      type: object
      properties:
        trackId:
          type: string
        format:
          type: string
          enum:
          - mp3
          - hls
          - hls_with_cookie
        quality:
          type: string
          enum:
          - normal
          - high
        type:
          type: string
          enum:
          - trackDownloaded
    TrackPreviewedEvent:
      type: object
      properties:
        trackId:
          type: string
        type:
          type: string
          enum:
          - trackPreviewed
    AnalyticsReportRequest:
      required:
      - events
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/AnalyticsReportEvent'
  securitySchemes:
    ApiKeyAuth:
      type: http
      description: 'API key authentication for server-to-server communication.

        Pass your API key as a Bearer token in the Authorization header.

        API keys are prefixed with `epidemic_live_`.


        > **Example Header:** `Authorization: Bearer epidemic_live_your-api-key`'
      scheme: bearer
    PartnerAuth:
      type: http
      description: 'Partner authentication is handled with short lived partner access tokens.

        Use your api credentials to request these tokens.

        The access token is of JWT format and should be passed in a header with your API requests:


        > **Example Header:** `Authorization: Bearer your-partner-token`'
      scheme: Bearer
    UserAuth:
      type: http
      description: "User authentication is handled with short lived user access tokens.\n Use a partner token to request these tokens.\n The access token is of JWT format and should be passed in a header with your API requests:\n\n > **Example Header:** `Authorization: Bearer a-user-token`"
      scheme: Bearer
    EpidemicSoundConnectAuth:
      type: oauth2
      description: 'For users signing in with an Epidemic Sound account, user authentication is

        handled with OpenID Connect, which is a layer on top of OAuth 2.0.


        > **Example Header:** `Authorization: Bearer es-connect-token`'
      flows:
        authorizationCode:
          authorizationUrl: https://login.epidemicsound.com/auth/realms/accounts/protocol/openid-connect/auth
          tokenUrl: https://login.epidemicsound.com/auth/realms/accounts/protocol/openid-connect/token
          scopes: {}