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.

Hybrid Workflow Note: We are currently transitioning our infrastructure to a V2.0 API architecture. To perform a complete workflow (e.g., authenticating, creating a release, and then setting advanced monetization policies), you will need to interact with endpoints from both the V1.0 API and the V2.0 API.

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>

Security Note: Your API credentials are effectively client secrets. Never expose them in client-side code (browsers or mobile apps). All API interactions should be performed server-to-server.

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.

Best Practice: To avoid being blocked, we strongly recommend implementing rate-limiting logic on your client side and using exponential backoff if you are running bulk data migrations or heavy concurrent scripts.

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:

Log into the web portal.
Open your browser’s Developer Tools (Network Tab).
Perform the action manually in the UI.
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:

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

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.