Getting started

The Revelator API enables partners to programmatically manage their entire music business operations, including content ingestion, user management, accounting, and distribution, directly from their own applications.

Organizations & Clients

Revelator accounts have two levels of scope: organizations and clients.

Term	What it is
Organization	The top-level account representing your organization. It manages one or more clients and performs administrative operations such as release inspection and DSP configuration.
Client	An account managed by an organization. Catalog entities such as releases, tracks, artists, and labels are created and managed under a client. A client can represent an artist, a label, a customer, or an internal division.

An organization can manage multiple clients, while each client belongs to exactly one organization. Catalog entities are always created under a client; they are not created directly under an organization.

An organization may use a single client to manage its own catalog, or multiple clients to manage separate catalogs.

Base URLs

You will interact with two different base URLs depending on the specific functionality you are accessing:

API Version	Base URL	Primary Usage
V2.0 API	https://platform.revelator.com	Modern Features. Used for advanced distribution settings, monetization policies, territory clearances, and new modules.
V1.0 API	https://api.revelator.com	Core Operations. Currently used for Authentication, creating basic release metadata, and legacy file uploads.

---

Authentication

All requests to the New API require a standard Bearer Access Token. Currently, this token must be retrieved via the Old API.

Authentication

All requests to the V2.0 API require a standard Bearer Access Token. Currently, this token must be retrieved via the V1.0 API.

Step 1: Get Access Token (V1.0 API)

Use your partner credentials to obtain a token from the V1.0 login endpoint.

curl -X POST "https://api.revelator.com/partner/account/login" \
     -H "Content-Type: application/json" \
     -d '{
           "partnerApiKey": "YOUR_API_KEY",
           "partnerUserId": "YOUR_PARTNER_USER_ID"
         }'

Step 2: Use Token (V2.0 API)

Include the returned token in the Authorization header of your requests to the V2.0 API.

Authorization: Bearer <YOUR_ACCESS_TOKEN>

---

Rate Limiting

To ensure the stability and performance of the platform for all users, the Revelator V2.0 API enforces rate limits on all incoming requests.

• Limit: 200 requests per minute per IP address.
• Window Type: Rolling window (the limit is calculated continuously based on your activity over the last 60 seconds).
• Penalty: If you exceed the 200 request limit within a 60-second window, your IP address will be temporarily blocked for 10 minutes.

If your IP is blocked, all subsequent API requests during that 1-hour ban will automatically fail and return a standard HTTP 429 Too Many Requests response.

---

Sandbox & Environment

All API development and testing should be performed in the Production Environment using a dedicated Sandbox Account.

• Sandbox Account: If you do not have a dedicated Sandbox Account to test safely without affecting live data, please contact [email protected].

---

Developer Tips

Inspect the Web UI for Logic: The Revelator Web Interface is a great way to understand how data entities relate to each other (e.g., contributors on a release/track). If you are unsure about a workflow:

1. Log into the web portal.
2. Open your browser’s Developer Tools (Network Tab).
3. Perform the action manually in the UI.
4. Inspect the payload to understand the data structure.

Important: Do not copy endpoints directly from the browser to your code. The Web Interface often uses internal or specialized endpoints that differ from the public API. Always cross-reference your findings with the official documentation to ensure you are using the supported public endpoint.

---

Understanding Assets & IDs

In the Revelator V2.0 API, many core entities (like tracks, releases, and videos) belong to a broader category called Assets.

Because of this architecture, these entities actually have two identifiers:

1. Entity ID: A specific identifier for that exact type of object (e.g., releaseId, physicalReleaseId, trackId).
2. Asset ID (assetId): A universal identifier shared across the entire asset management system.

Addressing an Entity by Asset ID

A handful of endpoints accept the assetId in place of the entity ID. These live under a parallel /catalog/v1/assets/{type}/{assetId} path and return exactly the same payload as their entity-ID counterpart—they are an alternate key, not a different resource. Use them when your system stores assetId and you would otherwise have to resolve the entity ID first.

Where such an alternate exists, it is noted on the endpoint it applies to rather than documented separately. Rights are the exception: they are managed entirely by assetId, so the asset path is the primary one there. See Rights.

Supported Asset Types

When interacting with endpoints that use assetId, you will often see or need to provide an assetType. The system supports the following types:

Asset Type	Description
release	A container for tracks (Album, EP, or Single).
track	A standard audio song on a release.
releaseTrack	The specific relationship/link between a release and a track.
physicalRelease	A release formatted for physical distribution (Vinyl, CD, etc.).
video	A music video formatted for delivery to DSPs.
youTubeChannel	A YouTube Channel imported into the system.
youTubeVideo	A specific video imported from a YouTube channel.
musicalWork	An underlying composition (melody and lyrics).

---

Request Formatting

Array Query Parameters

When interacting with GET endpoints that accept array filters (e.g., filtering by multiple trackIds or countryIds), you must provide the parameter key multiple times in the query string.

Correct Example:

?trackIds=123&trackIds=456&trackIds=789

---

Response Format

All responses are returned in JSON format.

Common Status Codes

Code	Status	Description
200	OK	The request was successful.
400	Bad Request	Validation failed. Check the errors object in the response body for details.
401	Unauthorized	Your Bearer token is missing, invalid, or expired.
403	Forbidden	You do not have permission to access this resource.
404	Not Found	The requested resource (Release, Asset, User, etc.) does not exist.
429	Too Many Requests	You have exceeded the rate limit of 200 requests per minute.
500	Server Error	An internal error occurred. Please contact support if this persists.