Endpoints to get sound effect specific information. These endpoints allow you to build a UI to browse and search for sound effects.
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: {}