openapi: 3.0.1
info:
  title: Partner Content Assets Beta 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: Beta
  description: These endpoints are in beta.
paths:
  /v0/tracks/{trackId}/beats:
    get:
      tags:
      - Beta
      summary: Beats
      description: "The beats endpoint provides information about the timestamps of beats in a track. You can use this endpoint to simplify the process to cut the video in sync with the music.\n\nUnlike BPM which is a single number for the entire track, beats can change dynamically across a music piece. This is particularly valuable for capturing variations in tempo, such as a slower intro, a build-up with faster beats, or changes in rhythm throughout the composition.\n\nThe response includes two types of metadata:  `time` and `value`. \n\n`time` represents the timestamp of the beat in seconds. `value` indicates the beat's position in a bar (or measure in the US), where 1 corresponds to the first beat (downbeat).\n\nExamples:\n\nMost pop songs have four beats in a bar. For example, if we looked at the beats data for Coolio's `1, 2, 3, 4` it would look something like:  1-2-3-4, 1-2-3-4\n\nHowever, a waltz has three beats in a bar, and the data would look something like: 1-2-3, 1-2-3\n\nUsage Scenarios:\n\n* Automatically cut a video in sync with the beat\n\n* Adding snap markers aligned with beat timestamps in the UI."
      operationId: GET_Track_Beats
      parameters:
      - $ref: '#/components/parameters/trackId'
      responses:
        '200':
          description: Beats response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackBeatsResponse'
              example:
                beats:
                - time: 0.0
                  value: 1.0
                - time: 0.62
                  value: 2.0
                - time: 1.2
                  value: 3.0
                - time: 1.8
                  value: 4.0
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              example:
                message: Bad request
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              example:
                message: Rate limit exceeded
        '401':
          description: Unauthorized. Most likely your access token has expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              example:
                message: Invalid credentials
        '404':
          description: Track was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              example:
                message: Track was not found
        '403':
          description: User does not have access to download the track.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              example:
                message: User does not have access to download the track
      security:
      - UserAuth: []
      - EpidemicSoundConnectAuth: []
      - ApiKeyAuth: []
  /v0/tracks/versions:
    post:
      tags:
      - Beta
      summary: Start a track versions generation job
      description: "This endpoint allows you to start a job to generate edited versions of a track.\nThe job will be processed asynchronously and you can check the status using the\nGET /tracks/versions/{jobId} endpoint. Note that the url expires in 24 hours. \n\n**Duration limits:**\n- The duration must be between 1 second and 5 minutes. \n- Longer durations result in increased processing time, as latency scales with the desired duration."
      operationId: POST_Track_Versions
      requestBody:
        description: Track edit request configuration
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrackEditsJobRequest'
      responses:
        '200':
          description: Track edit job response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackEditsResponse'
              example:
                status: PENDING
                results: []
                message: Job is still processing
                jobId: f854c9cf-bf6d-4345-b94c-c5a5c7d1979e
        '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: []
  /v0/tracks/versions/{jobId}:
    get:
      tags:
      - Beta
      summary: Get track versions job status
      description: 'This endpoint allows you to check the status of a track versions job.

        When the job is complete, it will return the URLs to the generated tracks.


        **Waveform Data:**

        - By default, waveform data is excluded to reduce payload size

        - Use `expand=waveform` to include waveform data in the response'
      operationId: GET_Track_Versions_Job
      parameters:
      - name: jobId
        in: path
        description: The ID of the job to check
        required: true
      - name: expand
        in: query
        description: Include additional data in response. Use 'waveform' to include waveform data.
        required: false
      responses:
        '200':
          description: Track edit job response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackEditsResponse'
              example:
                status: COMPLETED
                results:
                - previewUrl: https://cdn.epidemicsound.com/edited-tracks/12345.mp3
                  highQualityUrl: https://cdn.epidemicsound.com/edited-tracks/12345.wav
                message: Job completed successfully
                jobId: 10887737-61a9-4a75-8ea1-cd0e4630670f
        '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:
    TrackEditsJobRequest:
      required:
      - durationMs
      - trackId
      type: object
      properties:
        durationMs:
          type: integer
          format: int32
        trackId:
          type: string
          format: uuid
    TrackBeatsResponse:
      type: object
      properties:
        beats:
          type: array
          items:
            $ref: '#/components/schemas/TrackBeat'
    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'
    TrackBeat:
      type: object
      properties:
        time:
          type: number
          format: double
        value:
          type: number
          format: double
    TrackEditResultResponse:
      type: object
      properties:
        previewUrl:
          type: string
        waveform:
          $ref: '#/components/schemas/TrackEditWaveform'
        highQualityUrl:
          type: string
    TrackEditWaveform:
      type: object
      properties:
        version:
          type: integer
          format: int32
        channels:
          type: integer
          format: int32
        sampleRate:
          type: integer
          format: int32
        samplesPerPixel:
          type: integer
          format: int32
        bits:
          type: integer
          format: int32
        length:
          type: integer
          format: int32
        data:
          type: array
          items:
            type: integer
            format: int32
    TrackEditsResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - PENDING
          - PROCESSING
          - COMPLETED
          - FAILED
        results:
          type: array
          items:
            $ref: '#/components/schemas/TrackEditResultResponse'
        message:
          type: string
        jobId:
          type: string
          format: uuid
  parameters:
    trackId:
      name: trackId
      in: path
      description: Track id
      required: true
      schema:
        type: string
  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: {}