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 new 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 Old API and the New 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
New API	`https://platform.revelator.com`	Modern Features. Used for advanced distribution settings, monetization policies, territory clearances, and new modules.
Old API	`https://api.revelator.com`	Core & Legacy. Currently used for Authentication, creating basic release metadata, and 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.

Step 1: Get Access Token (Old API)

Use your partner credentials to obtain a token from the legacy 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 (New API)

Include the returned token in the Authorization header of your requests to the New 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.

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.

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.
`404`	Not Found	The requested resource (Release, Asset, User, etc.) does not exist.
`500`	Server Error	An internal error occurred. Please contact support if this persists.