openapi: 3.0.1
info:
  title: Partner Content Assets Sound effects 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: Sound effects
  description: Endpoints to get sound effect specific information. These endpoints allow you to build a UI to browse and search for sound effects.
paths:
  /v0/sound-effects/collections:
    get:
      tags:
      - Sound effects
      summary: List sound-effect collections
      description: 'Returns the sound-effect collections active for your application.


        Sound-effect collections are managed via the developer portal: an admin imports an EMS

        playlist into a collection, and end users see only Active collections through this endpoint.


        Every application has access to every sound effect, so there is no per-tier cap and no

        paid/free distinction. Up to 20 sound effects per collection are included by default;

        pass `excludeField=soundEffects` to omit them, or paginate the full set via

        `/sound-effects/collections/{collectionId}`.'
      operationId: GET_Sound_Effect_Collections
      parameters:
      - name: excludeField
        in: query
        description: Pass `soundEffects` to omit sound-effect data from the response and return only collection metadata.
        required: false
        schema:
          type: string
          enum:
          - soundEffects
      - name: limit
        in: query
        description: Max number of collections returned in the response, default 10 and max 20
        required: false
        schema:
          type: integer
          format: int32
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Sound-effect collections response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SoundEffectCollectionsPaginatedResponse'
              example:
                collections:
                - id: 4caef099-43bd-4653-8203-3086fa01d3b7
                  name: Crowd & Applause
                  soundEffects:
                  - id: 4bd22142-d121-4bab-89d7-bd0945fd3b24
                    title: Applause
                    added: '2026-05-11T07:45:47.571914418Z'
                    length: 10
                    images:
                      default: https://image.url?w=300&h=300&fit=fill&q=90&fm=jpg
                      L: https://image.url?w=1050&h=1050&fit=fill&q=90&fm=jpg
                      M: https://image.url?w=600&h=600&fit=fill&q=90&fm=jpg
                      S: https://image.url?w=300&h=300&fit=fill&q=90&fm=jpg
                      XS: https://image.url?w=128&h=128&fit=fill&q=90&fm=jpg
                  availableSoundEffects: 1
                pagination:
                  page: 1
                  limit: 10
                  offset: 0
                links:
                  next: /v0/sound-effects/collections?limit=10&offset=10
        '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
      security:
      - UserAuth: []
      - EpidemicSoundConnectAuth: []
      - ApiKeyAuth: []
  /v0/sound-effects/collections/{collectionId}:
    get:
      tags:
      - Sound effects
      summary: Sound-effect collection details
      description: Returns a single sound-effect collection along with a paginated set of its sound effects. Use `limit` and `offset` to page through the collection.
      operationId: GET_Sound_Effect_Collection
      parameters:
      - $ref: '#/components/parameters/collectionId'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Sound-effect collection response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SoundEffectCollectionPaginatedResponse'
              example:
                id: f10e65eb-9998-4c41-9777-ac9183ab85dd
                name: Crowd & Applause
                soundEffects:
                - id: a66c413e-7d9d-4916-9d69-993ac782cf79
                  title: Applause
                  added: '2026-05-11T07:45:47.573735118Z'
                  length: 10
                  images:
                    default: https://image.url?w=300&h=300&fit=fill&q=90&fm=jpg
                    L: https://image.url?w=1050&h=1050&fit=fill&q=90&fm=jpg
                    M: https://image.url?w=600&h=600&fit=fill&q=90&fm=jpg
                    S: https://image.url?w=300&h=300&fit=fill&q=90&fm=jpg
                    XS: https://image.url?w=128&h=128&fit=fill&q=90&fm=jpg
                availableSoundEffects: 1
                pagination:
                  page: 1
                  limit: 50
                  offset: 0
                links: {}
        '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: Sound-effect collection was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              example:
                message: Collection was not found
      security:
      - UserAuth: []
      - EpidemicSoundConnectAuth: []
      - ApiKeyAuth: []
  /v0/sound-effects/categories:
    get:
      tags:
      - Sound effects
      summary: List SFX categories
      description: 'The sound effects categories endpoint allows you to get a list of all sound effects categories.


        You can then browse the sound effects catalog based on categories like "Applause" or "Crowds".


        Some sound effect categories have cover art that you can use in your interface. You can choose to display all categories, or choose type "featured" to only show the categories that are chosen by our curation team.'
      operationId: GET_Sound_Effect_Categories
      parameters:
      - name: type
        in: query
        description: Category type
        required: false
        schema:
          type: string
          enum:
          - all
          - featured
          default: all
      - $ref: '#/components/parameters/offset'
      - name: limit
        in: query
        description: Max number of entries returned in the response, default 50
        required: false
      responses:
        '200':
          description: Sound effects category list with related parent category. You can see the parent-child relationship in the response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SoundEffectCategoriesResponse'
              example:
                categories:
                - id: 00f328a4-3526-43de-9cd6-87a991e6f5ec
                  name: Applause
                  images:
                    default: https://image.url?w=300&h=300&fit=fill&q=90&fm=jpg
                    L: https://image.url?w=1050&h=1050&fit=fill&q=90&fm=jpg
                    M: https://image.url?w=600&h=600&fit=fill&q=90&fm=jpg
                    S: https://image.url?w=300&h=300&fit=fill&q=90&fm=jpg
                    XS: https://image.url?w=128&h=128&fit=fill&q=90&fm=jpg
                  parent:
                    id: 26d2325c-7642-4f52-9d98-478046b050d6
                    name: Crowds
                pagination:
                  page: 2
                  limit: 10
                  offset: 10
                links:
                  next: /sound-effects/categories?limit=10&offset=20
                  prev: /sound-effects/categories?limit=10&offset=0
        '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/sound-effects/categories/{categoryId}:
    get:
      tags:
      - Sound effects
      summary: SFX category details
      description: 'The category details endpoint contains info on the requested sound effects category.


        The purpose of this endpoint is to be able to validate that an individual object exists in the API if it was cached by the client.'
      operationId: GET_Sound_Effect_Category
      parameters:
      - $ref: '#/components/parameters/categoryId'
      responses:
        '200':
          description: Category with related parent and children categories
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SoundEffectCategoryWithRelativesResponse'
              example:
                id: df41740b-62a5-4e96-882f-769698ae89b7
                name: Applause
                images:
                  default: https://image.url?w=300&h=300&fit=fill&q=90&fm=jpg
                  L: https://image.url?w=1050&h=1050&fit=fill&q=90&fm=jpg
                  M: https://image.url?w=600&h=600&fit=fill&q=90&fm=jpg
                  S: https://image.url?w=300&h=300&fit=fill&q=90&fm=jpg
                  XS: https://image.url?w=128&h=128&fit=fill&q=90&fm=jpg
                parent:
                  id: 8d1464ae-6b26-4727-9013-f5ef413648ed
                  name: Crowds
                children:
                - id: 9e54ce9e-9033-4808-ba51-0993485d3318
                  name: Claps
        '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: Category was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              example:
                message: Category was not found
      security:
      - UserAuth: []
      - EpidemicSoundConnectAuth: []
      - ApiKeyAuth: []
  /v0/sound-effects/categories/{categoryId}/tracks:
    get:
      tags:
      - Sound effects
      summary: List SFX by category
      description: Use the sound effects details endpoint to display all sound effects for a given category.
      operationId: GET_Sound_Effect_Category_Tracks
      parameters:
      - $ref: '#/components/parameters/categoryId'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/limit'
      - name: sort
        in: query
        description: Sort
        required: false
        schema:
          type: string
          enum:
          - title
          - newest
          - length
          default: newest
      - name: order
        in: query
        description: Order
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
      - name: includeExplicit
        in: query
        description: Whether to include sound effects tagged as explicit in the results. Defaults to false, meaning explicit content is excluded by default.
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: List of sound effects for a given category
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedSoundEffectsResponse'
              example:
                soundEffects:
                - id: 4b162c28-197f-4e3b-b1b4-0d96fd211322
                  title: Applause
                  added: '2026-05-11T07:45:47.626987847Z'
                  length: 10
                  images:
                    default: https://image.url?w=300&h=300&fit=fill&q=90&fm=jpg
                    L: https://image.url?w=1050&h=1050&fit=fill&q=90&fm=jpg
                    M: https://image.url?w=600&h=600&fit=fill&q=90&fm=jpg
                    S: https://image.url?w=300&h=300&fit=fill&q=90&fm=jpg
                    XS: https://image.url?w=128&h=128&fit=fill&q=90&fm=jpg
                pagination:
                  page: 2
                  limit: 10
                  offset: 10
                links:
                  next: /sound-effects/categories?limit=10&offset=20
                  prev: /sound-effects/categories?limit=10&offset=0
        '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: Category was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              example:
                message: Category was not found
      security:
      - UserAuth: []
      - EpidemicSoundConnectAuth: []
      - ApiKeyAuth: []
  /v0/sound-effects/{trackId}/download:
    get:
      tags:
      - Sound effects
      summary: Download sound effect
      description: 'The download endpoint allows you to download an MP3 file of the sound effect.


        We offer MP3 files in two qualities; normal (128kbps) and high (320kbps).


        The high quality files can be used in content when needed, but normal quality is sufficient for most use cases.


        The download links expire after 24 hours (normal quality) or 1 hour (high quality files). The expiration time is stated in the response.'
      operationId: GET_Sound_Effect_Download
      parameters:
      - $ref: '#/components/parameters/trackId'
      - $ref: '#/components/parameters/format'
      - $ref: '#/components/parameters/quality'
      responses:
        '200':
          description: Information about download url
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadResponse'
              example:
                url: https://pdn.epidemicsound.com/ES_ITUNES/Happy_Song/ES_Happy_Song.mp3
                expires: '2022-12-22T11:01:48Z'
        '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/sound-effects/search:
    get:
      tags:
      - Sound effects
      summary: Search SFX
      description: 'Use the sound effects search endpoint to allow users to search within the sound effects library.

        '
      operationId: GET_Sound_Effect_Search
      parameters:
      - $ref: '#/components/parameters/offset'
      - name: limit
        in: query
        description: Max number of entries returned in the response, default 50 and max 60
        required: false
      - required: true
        $ref: '#/components/parameters/term'
      - name: sort
        in: query
        description: Sort for search
        required: false
        schema:
          type: string
          enum:
          - best-match
          - newest
          - popular
          - length
          - title
          default: best-match
      - name: order
        in: query
        description: Order
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
      - name: includeExplicit
        in: query
        description: Whether to include sound effects tagged as explicit in the results. Defaults to false, meaning explicit content is excluded by default.
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '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
        '200':
          description: List of sound effect search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedSoundEffectsResponse'
              example:
                soundEffects:
                - id: 0e875aa3-56d7-4252-8b93-b51bd1b3bab3
                  title: Applause
                  added: '2026-05-11T07:45:47.632385297Z'
                  length: 10
                  images:
                    default: https://image.url?w=300&h=300&fit=fill&q=90&fm=jpg
                    L: https://image.url?w=1050&h=1050&fit=fill&q=90&fm=jpg
                    M: https://image.url?w=600&h=600&fit=fill&q=90&fm=jpg
                    S: https://image.url?w=300&h=300&fit=fill&q=90&fm=jpg
                    XS: https://image.url?w=128&h=128&fit=fill&q=90&fm=jpg
                pagination:
                  page: 2
                  limit: 10
                  offset: 10
                links:
                  next: /sound-effects/categories?limit=10&offset=20
                  prev: /sound-effects/categories?limit=10&offset=0
      security:
      - UserAuth: []
      - EpidemicSoundConnectAuth: []
      - ApiKeyAuth: []
components:
  schemas:
    SoundEffectCategoryWithParentResponse:
      required:
      - id
      - name
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        images:
          $ref: '#/components/schemas/ImagesResponse'
        parent:
          $ref: '#/components/schemas/RelatedSoundEffectCategoryResponse'
    DownloadResponse:
      required:
      - expires
      - url
      type: object
      properties:
        url:
          type: string
        expires:
          type: string
    SoundEffectCategoriesResponse:
      required:
      - categories
      - links
      - pagination
      type: object
      properties:
        categories:
          type: array
          items:
            $ref: '#/components/schemas/SoundEffectCategoryWithParentResponse'
        pagination:
          $ref: '#/components/schemas/Pagination'
        links:
          $ref: '#/components/schemas/PaginationLinks'
    ImagesResponse:
      type: object
      properties:
        default:
          type: string
          nullable: true
        L:
          type: string
          nullable: true
        M:
          type: string
          nullable: true
        S:
          type: string
          nullable: true
        XS:
          type: string
          nullable: true
    Pagination:
      required:
      - limit
      - page
      type: object
      properties:
        page:
          type: integer
          format: int32
        limit:
          type: integer
          format: int32
        offset:
          type: integer
          format: int32
    PaginatedSoundEffectsResponse:
      required:
      - links
      - pagination
      - soundEffects
      type: object
      properties:
        soundEffects:
          type: array
          items:
            $ref: '#/components/schemas/SoundEffectResponse'
        pagination:
          $ref: '#/components/schemas/Pagination'
        links:
          $ref: '#/components/schemas/PaginationLinks'
    SoundEffectCategoryWithRelativesResponse:
      required:
      - id
      - name
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        images:
          $ref: '#/components/schemas/ImagesResponse'
        parent:
          $ref: '#/components/schemas/RelatedSoundEffectCategoryResponse'
        children:
          type: array
          items:
            $ref: '#/components/schemas/RelatedSoundEffectCategoryResponse'
    SoundEffectCollectionResponse:
      required:
      - id
      - name
      - soundEffects
      type: object
      properties:
        id:
          type: string
          description: Unique ID of the sound-effect collection.
          format: uuid
        name:
          type: string
          description: Name of the collection
        soundEffects:
          type: array
          items:
            $ref: '#/components/schemas/SoundEffectResponse'
        availableSoundEffects:
          type: integer
          description: Total number of sound effects available in the collection
          format: int32
          nullable: true
    PaginationLinks:
      type: object
      properties:
        next:
          type: string
          nullable: true
        prev:
          type: string
          nullable: true
    SoundEffectCollectionsPaginatedResponse:
      required:
      - collections
      - links
      - pagination
      type: object
      properties:
        collections:
          type: array
          items:
            $ref: '#/components/schemas/SoundEffectCollectionResponse'
        pagination:
          $ref: '#/components/schemas/Pagination'
        links:
          $ref: '#/components/schemas/PaginationLinks'
    RelatedSoundEffectCategoryResponse:
      required:
      - id
      - name
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
    SoundEffectResponse:
      required:
      - added
      - id
      - length
      - title
      type: object
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        added:
          type: string
          format: date-time
        length:
          type: integer
          format: int32
        images:
          $ref: '#/components/schemas/ImagesResponse'
    SoundEffectCollectionPaginatedResponse:
      required:
      - id
      - links
      - name
      - pagination
      - soundEffects
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        soundEffects:
          type: array
          items:
            $ref: '#/components/schemas/SoundEffectResponse'
        availableSoundEffects:
          type: integer
          format: int32
          nullable: true
        pagination:
          $ref: '#/components/schemas/Pagination'
        links:
          $ref: '#/components/schemas/PaginationLinks'
    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'
  parameters:
    categoryId:
      name: categoryId
      in: path
      description: Category id
      required: true
      schema:
        type: string
        format: uuid
    collectionId:
      name: collectionId
      in: path
      description: Collection id
      required: true
      schema:
        type: string
    format:
      name: format
      in: query
      description: Track format
      required: false
      schema:
        type: string
        enum:
        - mp3
    limit:
      name: limit
      in: query
      description: Max number of entries returned in the response, default 50 and max 100
      required: false
      schema:
        type: integer
        format: int32
    term:
      name: term
      in: query
      description: Term for search
      required: false
      schema:
        type: string
    quality:
      name: quality
      in: query
      description: Track quality, normal is used as the default if not specified
      required: false
      schema:
        type: string
        enum:
        - normal
        - high
        default: normal
    trackId:
      name: trackId
      in: path
      description: Track id
      required: true
      schema:
        type: string
    offset:
      name: offset
      in: query
      description: Index of the entry track in the response
      required: false
      schema:
        type: integer
        format: int32
  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: {}