openapi: 3.0.1
info:
  title: Partner Content Assets 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: Assets
  description: These endpoints allows your application to upload assets such as images or audio.
paths:
  /v0/uploads/audio/{checksum}:
    get:
      tags:
      - Assets
      summary: Get audio by checksum
      description: Will return the audio id of an audio file uploaded by the partner, matched by checksum. Should be used to avoid duplicate uploads
      operationId: GET_Partner_Audio_By_Checksum
      parameters:
      - $ref: '#/components/parameters/checksum'
      responses:
        '200':
          description: Partner audio response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerAudioResponse'
              example:
                audioUploadId: d99319b0-5b28-445a-a337-baa82df25394
                length: 10.0
                expires: '2026-06-10T07:45:47.611686848Z'
        '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
        '404':
          description: Audio file was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              example:
                message: Audio was not found
      security:
      - UserAuth: []
      - EpidemicSoundConnectAuth: []
      - ApiKeyAuth: []
      - PartnerAuth: []
  /v0/uploads/audio/{audioIdOrChecksum}:
    delete:
      tags:
      - Assets
      summary: Delete audio
      description: Use the delete audio endpoint to delete an audio file.
      operationId: DELETE_Partner_audio
      parameters:
      - $ref: '#/components/parameters/audioIdOrChecksum'
      responses:
        '200':
          description: List of deleted audio ids
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerAudioDeleteResponse'
              example:
                audioFilesRemoved:
                - a9acf7c6-5d1f-4e9c-8f74-14390c3f3bbe
        '202':
          description: List of audio files marked for deletion
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerAudioDeleteResponse'
              example:
                audioFilesRemoved:
                - 7e1745a6-5ac9-4716-a362-7f9e430c4df8
        '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
      security:
      - PartnerAuth: []
      - ApiKeyAuth: []
  /v0/uploads/audio:
    post:
      tags:
      - Assets
      summary: Upload audio
      description: "Upload an audio file to get recommendations of similar tracks in the Epidemic Sound library. When you post the audio file to this endpoint, you will receive an AudioID in return. Use this AudioID in a request to the similar tracks endpoint to get track recommendations.\n \n We currently support the formats: mp3, mpeg, ogg and vorbis. Maximum file size is 3.5MB. You can only upload music with the partner token, since we currently do not allow end users to use this feature."
      operationId: POST_Upload_Partner_Audio
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Returns the id of the uploaded audio, as well as the expiration date for the audio.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadUserImageResponse'
              example:
                imageId: 2f0f5883-5b03-4663-a703-9142a531443d
                expirationDate: '2026-05-12T07:45:47.615665317Z'
        '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/uploads/images/{imageId}:
    delete:
      tags:
      - Assets
      summary: Delete single image
      description: Use the delete image endpoint to delete a single image uploaded by a user
      operationId: DELETE_User_Image
      parameters:
      - $ref: '#/components/parameters/imageId'
      responses:
        '204':
          description: Image was deleted
        '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
        '404':
          description: Image was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              example:
                message: Image was not found
      security:
      - UserAuth: []
      - EpidemicSoundConnectAuth: []
      - ApiKeyAuth: []
  /v0/uploads/images:
    post:
      tags:
      - Assets
      summary: Upload image
      description: "Upload an image from the user's video to get recommendations of tracks in the Epidemic Sound library that would work for the video. When you post the image to this endpoint, you will receive an ImageID in return. Use this ImageID in a request to the matching image endpoint to get track recommendations.\n \n We currently support jpeg format and maximum file size is 2MB."
      operationId: POST_Upload_User_Image
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Contains id to be used for endpoints requiring an image id, as well as the expiration date for the image.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadUserImageResponse'
              example:
                imageId: be4f3072-62f8-49c2-9904-0c99fb87a111
                expirationDate: '2026-05-12T07:45:47.618440808Z'
        '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: []
    delete:
      tags:
      - Assets
      summary: Delete all the uploaded images by the user
      description: Deletes all images uploaded by the user
      operationId: DELETE_User_Images
      responses:
        '202':
          description: Images were marked for deletion
        '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
      security:
      - UserAuth: []
      - EpidemicSoundConnectAuth: []
      - ApiKeyAuth: []
components:
  schemas:
    PartnerAudioResponse:
      required:
      - audioUploadId
      - expires
      - length
      type: object
      properties:
        audioUploadId:
          type: string
          format: uuid
        length:
          type: number
          format: double
        expires:
          type: string
          format: date-time
    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'
    PartnerAudioDeleteResponse:
      required:
      - audioFilesRemoved
      type: object
      properties:
        audioFilesRemoved:
          type: array
          items:
            type: string
            format: uuid
    UploadUserImageResponse:
      required:
      - expirationDate
      - imageId
      type: object
      properties:
        imageId:
          type: string
          format: uuid
        expirationDate:
          type: string
          format: date-time
  parameters:
    checksum:
      name: checksum
      in: path
      description: File checksum
      required: true
      schema:
        type: string
    audioIdOrChecksum:
      name: audioIdOrChecksum
      in: path
      description: Audio upload id or checksum of audio file
      required: true
      schema:
        type: string
    imageId:
      name: imageId
      in: path
      description: Image 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: {}