Skip to main content

Overview

Epidemic Sound API​

Get access to a carefully curated catalog of high quality music created by world-class artists, producers and bands.

To use the API, you'll need access to the Epidemic Sound Developer Portal. See Getting Started Prerequisites for details.

For a quick start with the API, checkout our Getting Started guide.

OpenAPI Specification​

The complete API specification is available in OpenAPI 3.0 format, which can be accessed programmatically for use with code generators, testing tools, and AI assistants.

Direct access to the spec:

You can use this JSON file to:

  • Generate client libraries using tools like OpenAPI Generator
  • Import into API testing tools like Postman or Insomnia
  • Provide to LLMs and AI coding assistants for context-aware development
  • Automate API documentation and integration testing

Example usage:

# Download the spec
curl https://partner-content-api.epidemicsound.com/docs/spec.json > api-spec.json

# Generate a client library (example with openapi-generator)
openapi-generator generate -i api-spec.json -g javascript -o ./client

The interactive Swagger UI documentation is also available at https://partner-content-api.epidemicsound.com/swagger.

API Reference: Complete endpoint documentation is available in the API Reference with detailed information about all parameters, request/response schemas, and usage examples.

API specifics​

Both request and response bodies expect application/json as the Content-Type.

Versioning​

This API is versioned with a path prefix. Any existing endpoint or resource field will remain unchanged within a given version. New endpoints or resource fields can be added without notice and within an already published version. If a given API version is deprecated, users will be notified well before it is taken out of service.

CORS restrictions​

The API applies Cross-Origin Resource Sharing (CORS) restrictions in the production environment. If you are using the API in the context of a web app, you might need to whitelist your domain in the developer portal. You’ll be able to add domains for your app under “Authentication settings” and “Web Origins”.

Rate limiting​

The API implements multiple layers of rate limiting to ensure fair usage and service stability:

1. Request Rate Limits​

All requests are subject to per-second rate limits to protect against traffic spikes. These limits vary based on endpoint type and authentication status. If you consistently hit these limits, consider implementing request batching or caching strategies.

2. Daily App Limits​

Each partner application has a daily request quota with two thresholds:

  • Soft Limit - When reached, requests continue but response headers will indicate the limit has been exceeded. You can view your app's soft limit in the Developer Portal under your app settings.
  • Hard Limit - When reached, requests are blocked with HTTP 429 responses. You can view your app's hard limit in the Developer Portal under your app settings.

Notifications:

  • At 90% of soft limit: Warning notification sent
  • At soft limit: Notification sent, but requests continue
  • At hard limit: Requests blocked until daily reset (midnight UTC)

The daily limits reset at midnight UTC. If you need higher limits, contact your Epidemic Sound partner manager.

3. Per-User Limits​

To ensure fair usage across end users, individual users are limited to 350 requests per week per app. This applies to authenticated user requests and resets weekly.

Rate Limiting Response Headers​

When rate limits are encountered, the API returns the following headers:

Daily App Limits:

  • X-RateLimit-Reached: Set to "true" when soft or hard limit is reached
  • X-RateLimit-Reset: Timestamp when the limit resets (midnight UTC)

Per-User Limits:

  • x-user-ratelimit-count: Current request count for the user
  • x-user-ratelimit-limit: Maximum allowed requests (350)
  • X-User-Rate-Limit-Reset: Time until the limit resets

HTTP 429 Response: When the hard limit is reached, the API responds with HTTP 429 (Too Many Requests). Implement exponential backoff and retry logic to handle this gracefully.

Best Practices​

To stay within rate limits:

  • Use batch requests where possible
  • Monitor the rate limit headers in responses
  • Set up alerts at 80-90% of your daily quota

Retries, DDoS attacks, and friendly fire​

To ensure the stability of the API, we use web application firewall solutions that protect against malicious attacks. In many cases, this allows us to mitigate attacks without affecting users. However, it is sometimes hard to distinguish between an attack and an unintentional request overload from well-intended clients, sometimes referred to as friendly fire.

You can decrease the risk that your client gets mistaken for a malicious actor by implementing delays for any request retries, for example, by using an exponential backoff. This helps to ensure that any failure in the communication between the clients and the API doesn't result in unnecessarily large problems.

DDoS mitigation responses​

When the web application firewall denies requests in order to mitigate an ongoing DDoS attack, it may respond with 502 Bad Gateway and an empty response body. We do our best to ensure this does not affect requests from legitimate clients, but unfortunately, this can not always be avoided, and therefore we advise you to handle this case in your clients.