Revelator API Documentation

[DEPRECATED] Create new account endpoint

Tue, 26 Sep 2023 00:00:00 GMT

POST /account/createnewaccount' - endpoint is now deprecated. This is done to mitigate confusion for creating new accounts.

[DEPRECATED] External URL for track/release files no longer supported

Sat, 11 Nov 2023 00:00:00 GMT

Using an externalUrl to associate files with a track/release is no longer recommended! Files referenced like this are not being downloaded by our system until distribution, leading to unexpected behavior. Use the endpoints mentioned above for all file uploading needs.

[NEW] Uploading files

Sat, 11 Nov 2023 00:00:00 GMT

Newly documented endpoints for uploading files

POST /media/audio/upload/wav - Upload a file in wav format to the Revelator servers
POST /media/image/upload - Upload an image file to the Revelator servers
POST /media/audio/pullexternal/wav - Pull a file in wav format from an external url to the Revalator servers

[DOCS] New API documentation

Wed, 24 Jan 2024 00:00:00 GMT

New look and feel
New URL api-docs.revelator.com
Ability to search through the documentation (CTRL + K)

[NEW] Enterprise Information Endpoints

Tue, 26 Sep 2023 00:00:00 GMT

Enterprise information endpoints:

GET /enterprise/clients/{id} - Retrieves basic information about a single enterprise
GET /enterprise/clients/all - Retrieves basic information about all enterprises associated with the account

[NEW] Tipalti integration

Mon, 29 Jan 2024 00:00:00 GMT

Tipalti integration added to Revelator. By completing the following flows you will be able to pay your payees using this feature:

Payor Flow - Connect your Tipalti Account with your Revelator Parent Account
Payee Flow - Set up a payee to receive money via Tipalty

[DOCS] Examples

Thu, 14 Mar 2024 00:00:00 GMT

The endpoint examples are now back after the documentation migration.

[BREAKING] Distribution statuses updated

Wed, 20 Mar 2024 00:00:00 GMT

Distribution statuses updated.

New statuses for takedowns (72, 75, 76, 79)
Old statuses updated (8, 10, 11)

[DOCS] Glossary page

Fri, 12 Apr 2024 00:00:00 GMT

Added a Glossary page containing most used terms.

[BREAKING] Only active stores

Wed, 22 May 2024 00:00:00 GMT

Attemnts to distribute to stores containing the isActive == false will now fail.

[BREAKING] Track Types and Properties

Thu, 20 Jun 2024 00:00:00 GMT

New fields/changes introduced to reflect TikTok’s Monetization Changes

trackProperties is a new and required field on the Track Object.
trackType is now a required field on the Track Object. This field also accepts a new value: 2 - Cover song

[CHANGE] Monetization Policy Changes

Mon, 24 Jun 2024 00:00:00 GMT

New Monetization Policy changes introduced to reflect TikTok's Monetization Changes

Added monetization policies for TikTok. (NoTikTokScanning, Monetize, BlockAccess)
A new field trackMonetizationPolicyIds available during Setting Distribution Options for track-level policies.

[DOCS] Common resources

Wed, 10 Jul 2024 00:00:00 GMT

Added the Common Resources section in order to provide easy-access and overview of this type of data.

[DOCS] Artist Image field

Tue, 30 Jul 2024 00:00:00 GMT

Added this previously undocumented field to the Artist Object.

[DOCS] Documented Takedown

Tue, 30 Jul 2024 00:00:00 GMT

Newly documented Takedowns section.

[BREAKING] Token security

Mon, 05 Aug 2024 00:00:00 GMT

As part of our security hygiene and access protocol work, we’ve moved to a more secure token protocol and updated the related documentation accordingly.

The access token can only be provided in the Authorization header, and must be prefixed with the word “Bearer”. (Bearer token)

[NEW] Dolby atmos

Thu, 12 Sep 2024 00:00:00 GMT

Dolby atmos is officially supported and ready to be distributed.

To supported this change, the Track Object has been updated. Explore the new changes directly on the Track Object and refer to the New track recording model section for more information.

Make sure you understand the limitations and cost associated with Dolby Atmos recordings before creating tracks. Read our Dolby Atmos Guide for more information.

[NEW] User invites

Wed, 15 May 2024 00:00:00 GMT

Added the (Beta) API support for user invites.

[BREAKING] First and last name for Composer/Writer required

Wed, 15 May 2024 00:00:00 GMT

Composer/Writer details on tracks missing either a valid first and last artist name are no longer allowed for distribution.

[BREAKING] No short tracks

Wed, 15 May 2024 00:00:00 GMT

Tracks that are less than 2 seconds long are no longer allowed for distribution. Any attempt at distributing or uploading these tracks will fail.

[NEW] Royalty tokens

Mon, 01 Apr 2024 00:00:00 GMT

Royalty tokens are now supported and documented.

[CHANGE] Staging environment no longer supported

Wed, 05 Feb 2025 00:00:00 GMT

We no longer support testing on the staging environment. All of the examples and documentation were updated to reflect this change.

Please contact us to create a dedicated Sandbox account.

[DEPRECATED] V1 Web inerface no longer supported

Wed, 05 Feb 2025 00:00:00 GMT

We are removing support for redirecting to, and generally using, the outdated V1 Web Interface.

[CHANGE] Updated the production URL

Wed, 05 Feb 2025 00:00:00 GMT

From this point forward the only supported url will be api.revelator.com

This is currently not a breaking change, but we recommend updating your code to use the primary url, as others might become deprecated in the future.

[BREAKING] Streamlined Artist External IDs Handling

Tue, 11 Mar 2025 00:00:00 GMT

A profileId of 0, null, or an absent entry in the artistExternalIds array will now be treated the same. The specific behavior of this empty state will differ depending on the store.

Any endpoints responding with an Artist Object will have its artistExternalIds array contain only existing external IDs. Values that were previously had "profileId": 0 will no longer appear in the array.

[BREAKING] Deezer Metadata Requirements Update

Tue, 18 Mar 2025 00:00:00 GMT

Deezer is enforcing new contributor metadata requirements starting Q2 2025. Tracks missing required roles will be removed, along with associated albums.

Instrumental Tracks must include:
- Composer (RoleId: 2)
Non-Instrumental Tracks must include either:
- Composer (RoleId: 2) + Lyricist (RoleId: 4)
- or Composer Lyricist (RoleId: 65)

[DOCS] New Changelog

Sat, 22 Mar 2025 00:00:00 GMT

API documentation Release Notes have been updated and renamed to Changelog.

[CHANGE] Required Metadata + Rights Updates for TTS

Wed, 26 Mar 2025 00:00:00 GMT

Last June, we introduced support for TikTok’s new Scanning service (TTS)— and it’s officially going live. This feature lets users set Monetize or BlockAccess policies on tracks used in UGC videos.

To comply with TikTok’s scanning policies, the following fields must be included per track:

Track Origin – Composition Rights
Track Properties – Recording Rights
Monetization Policy:
- Monetize – Allow monetized UGC usage
- BlockAccess – Prevent UGC use entirely

Tracks without updates after the deadline will be excluded from scanning and monetization

[NEW] New DSP support for artist external IDs

Tue, 11 Mar 2025 00:00:00 GMT

Added support for additional DSPs when it comes to providing Artist External IDs.

Soundcloud (68)
Meta (309)

[DEPRECATED] Validation error fields

Fri, 04 Apr 2025 00:00:00 GMT

As part of an internal revamp of our validation architecture, we will remove these fields since they are no longer relevant. This change enables the creation of newer and more accurate validations while also allowing us to introduce new validations into production more quickly.

validationErrors.field
validationErrors.value
validationErrors.errorCode

[BREAKING] Duplicate UPC restrictions

Tue, 08 Apr 2025 00:00:00 GMT

To enhance data integrity and streamline operations, we will implement validation to prevent UPC re-use, ensuring unique identification across releases.

[BREAKING] Mandatory Production & Engineering Credits Contributor

Thu, 08 May 2025 00:00:00 GMT

To enhance data quality and ensure proper crediting, we are introducing a new requirement: at least one contributor from the "Production & Engineering Credits" contributor group (contributorRoleGroupId = 3) is now mandatory for all releases submitted or updated via the affected endpoints.

The contributorRoleGroupId for different contributors types can be checked on /common/lookup/contributorRoles.

[DOCS] Retrieving Client Information

Tue, 03 Jun 2025 00:00:00 GMT

Documentation has been updated for client information retrieval. Details can be found in the Retrieving Client Information section.

[BREAKING] Removal of WarningCount field

Thu, 08 May 2025 00:00:00 GMT

The WarningCount field is being removed from the responses of the specified content release endpoints. Please update your integrations to no longer expect or utilize this field to avoid any disruptions.

[DOCS] New audio upload endpoints documented

Tue, 03 Jun 2025 00:00:00 GMT

Documentation has been added for audio upload endpoints. Details can be found in the Uploading Files section.

[DOCS] Newly documented contacts section

Wed, 04 Jun 2025 00:00:00 GMT

Documentation has been updated for contacts management. Details can be found in the Adding/Editing Contacts section.

[CHANGE] Enhanced Artist Activity Tracking

Wed, 25 Jun 2025 00:00:00 GMT

We're improving how active periods are tracked for Artist object by adding new fields.

ActiveFromDate (datetime, optional): The specific date when the artist began their activity
ActiveToDate (datetime, optional): The specific date when the artist ended their activity (or null if still active)

[CHANGE] Additional Contacts for Artists, Composers, and Publishers

Wed, 25 Jun 2025 00:00:00 GMT

We've enhanced our data models to allow associating multiple contacts with Artists, Composers, and Publishers. This improvement enables more comprehensive contact management and better role-specific communications.

The additionalContacts field has been added to:

Artist objects
Composer objects
Publisher objects

This array field allows you to associate multiple contacts with each entity, each with their own role designation.

[CHANGE] Artist Model Enhanced with New Fields

Wed, 25 Jun 2025 00:00:00 GMT

The Artist object has been significantly enhanced with new fields for more comprehensive data management, including identity details, label associations, and contribution categorizations.

Please refer to the updated Artist documentation for full details:

[DOCS] Documentation Clarification for ComposerContentDTO Role IDs

Wed, 25 Jun 2025 00:00:00 GMT

The documentation for the composerContentsDTO.roleId (used when adding composer information to tracks) has been updated to clarify selection criteria. Relevant roles for composers are those with either Priority = 5 OR belonging to contributorRoleGroupId = 4.

See the updated guidance in Adding/Editing Releases.

[NEW] New Endpoints for Direct Composer Management

Wed, 25 Jun 2025 00:00:00 GMT

We've introduced new dedicated endpoints for creating, retrieving, and managing Composer information directly. This allows for more comprehensive and standalone composer data management.

The Composer object, accessible via these new endpoints, now includes a richer set of fields:

Identity and affiliation details like isni, ipiCae, countryOfResidenceId, and proAffiliations.
Derived information such as worksCount (number of associated tracks/releases), publishersCount, contributorRoleIds (based on their contributions), and creationDate.

Full details on the Composer model and these endpoints can be found in the new documentation:

[NEW] New 'composerImageId' Field in ComposerContentsDTO Response

Wed, 25 Jun 2025 00:00:00 GMT

The ComposerContentsDTO object returned in API responses now includes a new composerImageId field. This ID is derived from the image associated with the linked composer (composerId) and provides a direct way to access the composer's image.

[CHANGE] Contact model extended

Wed, 25 Jun 2025 00:00:00 GMT

This change affects any endpoint that returns or accepts a Contact object in its request or response body.

contactRoleId (integer, optional): An identifier linking to the specific role of the contact (e.g., Billing Contact, Technical Contact).

[CHANGE] Contributor model extended

Wed, 25 Jun 2025 00:00:00 GMT

This change affects any endpoint that returns or accepts a Contributor object in its request or response. The Contributor model has been extended with a new field:

contributorRoleGroupId (integer, optional): An identifier linking to the specific group role of the contributor.

[DEPRECATED] Deprecated Endpoints

Wed, 25 Jun 2025 00:00:00 GMT

Endpoint was replaced with /whitelabel/check-email-domain.

[CHANGE] Description can now be saved after distribution

Wed, 25 Jun 2025 00:00:00 GMT

Description now can be changed after release is distributed. Before changes to that field were ignored.

[CHANGE] New Response Fields for `/content/artist/all` Endpoint

Wed, 25 Jun 2025 00:00:00 GMT

The /content/artist/all endpoint response now includes additional fields for richer artist information, such as releasesCount, musicStyles, and creationDate. This endpoint and its complete response structure are detailed in the updated documentation.

See Retrieving artists for full information.

[NEW] New endpoints

Wed, 25 Jun 2025 00:00:00 GMT

We are introducing two new lookup endpoints to provide easier access to lists of Contributor Role Groups and Contact Roles.

[CHANGE] Improved Enterprise Association for Implicitly Created Composers & Publishers

Wed, 25 Jun 2025 00:00:00 GMT

When a new Composer or Publisher is created implicitly during the process of saving a Release or Track (i.e., by providing new composer/publisher details within the release/track save payload), its enterpriseId will now automatically be set to match the enterpriseId of that Release or Track.

Previously, such implicitly created Composers/Publishers would inherit the enterpriseId of the currently authenticated user's session. This update ensures more accurate and contextually correct enterprise association for these entities from their point of creation within an asset.

For more details, see the updated notes in the Composer and Publisher documentation sections.

[CHANGE] New query parameters

Wed, 25 Jun 2025 00:00:00 GMT

We've added new query parameters to artist endpoints:

options.isni (string, optional): Filter results by a specific ISNI
options.contributorGroupId (integer, optional): Filter results by a specific Contributor Group ID

[CHANGE] Enhanced Permissions Object

Wed, 25 Jun 2025 00:00:00 GMT

We've improved the permissions object with new properties that provide better control over enterprise access and account type specification. These enhancements will improve the user experience for accounts with access to multiple enterprises.

isDefault (boolean): This property determines the default enterprise when a user has access to multiple enterprises under the same account type. When true, this enterprise will be selected by default upon login
accountType (integer): This property specifies the type of account these permissions apply to.

[DOCS] Publisher Management Endpoints Now Documented & Enhanced

Wed, 25 Jun 2025 00:00:00 GMT

Endpoints for managing Publishers are now officially documented. The Publisher model has also been enhanced with new fields for richer data.

Please refer to the new documentation sections:

[BREAKING] Removal of `ContractTypeId` from Contract Save Endpoint

Wed, 25 Jun 2025 00:00:00 GMT

The ContractTypeId field is being removed from both the request body and the response body of the POST /accounting/contract/save endpoint. This field was identified as unused and is being removed to simplify the contract management process.

[NEW] New Parameter for Parent Account Analytics

Wed, 25 Jun 2025 00:00:00 GMT

Parent enterprise users can now retrieve analytics data specifically for their child enterprises using the new optional targetEnterpriseId query parameter.

Please refer to the updated Analytics documentation for more details on usage. Comprehensivee Analytics and Keymetrics

[CHANGE] Royalty Token Object Changes

Wed, 25 Jun 2025 00:00:00 GMT

We've updated the royaltyToken object structure to better represent digital asset information and streamline the data model.

Added Fields

assetName (string): The name of the digital asset represented by the token
assetVersion (string): The version identifier for the digital asset

Removed Fields

track (object): This nested object has been removed and its relevant data has been moved to the new fields

[CHANGE] New 'payoutRate' Parameter for Royalty Tokens

Wed, 25 Jun 2025 00:00:00 GMT

Added an optional payoutRate parameter (integer, 1-100, defaults to 100) to the Royalty Token creation process. This field defines the percentage of royalties that will be transferred to the token.

[DOCS] Documentation Update: Running API Requests in Child Accounts

Wed, 25 Jun 2025 00:00:00 GMT

The documentation section for "Running Requests in Child Accounts" has been updated for clarity. It now includes a list of currently supported endpoints for this feature and notes that we plan to expand this capability in the future.

Please review the updated guidance here: Running Requests in Child Accounts

[CHANGE] New Payout-Related Fields in Sale Report Responses

Wed, 25 Jun 2025 00:00:00 GMT

New fields include:

isCrypto (boolean | null): Indicates if the report/statement is to be paid in cryptocurrency to an enterprise Royalty Pool balance (a balance reserved exclusively for payments related to Royalty Tokens).
isSmartWalletPayee (boolean): Indicates the payee is to be paid directly to their enterprise Smart Wallet 0x address.

[CHANGE] New Recommended Method for Selecting Contributor Roles

Mon, 30 Jun 2025 00:00:00 GMT

We are introducing a new, more robust method for selecting specific contributor roles, particularly for composerContentsDTO and contributors, by using the contributorRoleGroupId system.

While the old method of filtering roles by priority will continue to work for now, we strongly recommend that you update your integrations to use the new contributorRoleGroupId system. This new method is more reliable and will be the standard going forward.

The documentation has been updated to reflect this new recommendation. For more details, please see Adding/Editing Releases.

[DOCS] New Filtering Options for Sale Reports Endpoint

Tue, 01 Jul 2025 00:00:00 GMT

The documentation for the /finance/salereport/all endpoint has been updated to include new query parameters for more granular filtering.

You can now filter sale reports by releaseId, releaseIds, trackId, and trackIds.

Please see the updated Sale Reports documentation for details.

[DOCS] Enhanced Documentation for Release Retrieval Endpoints

Tue, 01 Jul 2025 00:00:00 GMT

The documentation for endpoints used to retrieve release information has been significantly updated. This includes adding comprehensive details for previously undocumented query parameters for filtering, sorting, and pagination on the /content/release/all and /content/release/all/summary endpoints.

We've also added explanations for system-derived fields like releaseTypeId and additionalCounters.

Please review the updated Retrieving Releases section for full details.

[DOCS] Documented missing properties on Release and Track

Thu, 10 Jul 2025 00:00:00 GMT

Documented missing properties on:

Release: primaryMusicStyleId, secondaryMusicStyleId
Track: primaryMusicStyleId, secondaryMusicStyleId, previewStartSeconds

For more details see Adding/Editing Releases

[BREAKING] Removal of Unused Fields from Payee Object

Mon, 14 Jul 2025 00:00:00 GMT

The following unused fields are being removed from the Payee object wherever it appears in requests or responses on the affected endpoints:

Role
CompanyOrIndividualID

If your integration interacts with any of the affected endpoints and sends or expects to receive these fields, please update your code to remove dependency on them before the deadline.

[BREAKING] Removal of ContributorRoles.Priority

Mon, 14 Jul 2025 00:00:00 GMT

1. Removal from Lookup Endpoints: The Priority field will no longer be returned for role objects from /common/lookup/contributorRoles or /common/lookup/all. Please remove any dependency on this field.

2. Updated Logic for composerContentsDTO Roles: The requirement for selecting roles for composerContentsDTO is changing from priority = 5 to using the new grouping system.

New Rule: You must now use roles that belong to contributorRoleGroupId = 4.
Related Rule: As before, roles from this specific group (contributorRoleGroupId = 4) should not be included in the main contributors array of a release and track, with the exception of the "Composer" role (roleId 2) for classical music.

Please update your implementation to use contributorRoleGroupId for identifying these specific roles. For more details, refer to the Adding/Editing Releases documentation.

[DOCS] External Audio Uploads

Tue, 15 Jul 2025 00:00:00 GMT

The documentation for the /media/audio/pullexternal/wav endpoint has been updated.

To ensure proper processing, the filename parameter in the request body must include the file extension.

Please see the updated documentation for POST /media/audio/pullexternal/wav for full details.

[DOCS] Track Compositions and Copyright Fields

Mon, 21 Jul 2025 00:00:00 GMT

Documentation has been added for the compositions array and related fields on the Track object, which represent underlying musical works. This includes details on how to set compositions and important behavioral notes when changing trackType.

Additionally, the copyrightP and copyrightC fields on the Track object are now documented.

Please see the updated Track Object section for full details.

[DOCS] Release Distribution Country Options

Mon, 21 Jul 2025 00:00:00 GMT

The documentation for setting release distribution options has been updated. You can now define specific countries for distribution using the new countriesIncluded and countriesExcluded parameters. You can also define specific price tiers using priceTierIds.

Important details on how these parameters interact (e.g., when both are provided) and other related warnings have been added.

Please refer to the updated Setting Distribution Options documentation for full details.

[CHANGE] Analytics API Extended for Engagement and Consumption

Wed, 23 Jul 2025 00:00:00 GMT

New query parameters and metrics have been introduced for the Analytics API to enhance data filtering and expand reporting for User-Generated Content (UGC) platforms:

New Parameter for /analytics/engagement/{aggregation}:
- isSkipRate (boolean): Filters out items where skipRate is 0.
New Parameter for both Consumption and Engagement endpoints:
- isUgc (boolean): Filters metrics based on User-Generated Content (UGC) platforms.
New UGC-specific Metrics:
- creationsCount, likesCount, sharesCount, commentsCount, watchTime, viewsCount are now available in responses.

For full details on usage and metric applicability, please see the documentation: V3 Analytics

[NEW] New Endpoint for Unprompted Authentication Workflows

Wed, 23 Jul 2025 00:00:00 GMT

We have introduced a new administrative endpoint, GET /partner/users, to support unprompted authentication workflows.

This endpoint allows partners who manage their own user credentials to look up a user's partnerUserId using their email address.

For full details on usage, please see the documentation: Retrieving Client Information

[DEPRECATED] Deprecation of DSP ID fields in Track in favor of ReleaseTracks

Wed, 23 Jul 2025 00:00:00 GMT

We are deprecating the SpotifyId, AppleId, and RdioId fields from the Track object. These fields are now considered obsolete and will be removed in a future version of the API.

As a replacement, a new ReleaseTracks field has been introduced on the Track object. This provides a more consistent and scalable way to associate tracks with external DSP identifiers across releases.

Note: This is not a breaking change — the deprecated fields will remain available for now, but we recommend migrating to the new structure as soon as possible.

For full details, including an example of the new ReleaseTracks structure, please see the Retrieving Releases.

[DOCS] Request/Response Examples Now Collapsible

Mon, 04 Aug 2025 00:00:00 GMT

Updated request/response examples across the documentation. They are now inside collapsible sections to make it easier to read and navigate the docs.

[DOCS] Enhanced contract management

Wed, 30 Jul 2025 00:00:00 GMT

The documentation for the POST /accounting/contract/save endpoint has been updated to provide clearer and more precise guidance on creating and updating contracts.

Please refer to the updated Adding/Editing Contracts documentation for full details on constructing valid contract payloads.

[DOCS] Distribution Statuses Reordered and Refined

Thu, 07 Aug 2025 00:00:00 GMT

The documentation for distribution statuses has been updated. The statuses in the /distribution/store/all response are now ordered by their processing flow, and their Status Text and Query String Text values have been refined for improved clarity and accuracy.

Please see the updated Retrieving Distribution Status documentation for full details.

[DEPRECATED] New way of handling artist external IDs

Mon, 11 Aug 2025 00:00:00 GMT

We have updated our documentation to clarify the correct and supported method for managing DSP artist profile IDs, and are officially deprecating the legacy artistAppleId and artistSpotifyId fields.

The official, supported method is to use the structured artistExternalIds array. Our updated documentation now clarifies that this array should be used in the following locations:

On the Release object for the main primary artist.
On the Track object for the main primary artist.
On the nested Artist object for each individual contributor.

Action Required: While some integrations may already be using artistExternalIds on contributors, please review your implementation to ensure you are using it in all three locations as needed. We strongly recommend migrating away from the deprecated artistAppleId and artistSpotifyId fields, as they will be removed in a future.

We have published a comprehensive guide consolidating all information on this topic. Please review it carefully for details on the structure of artistExternalIds and how to handle different DSPs.

See the full guide here: Managing External Artist IDs

[DOCS] Clarified Rules for UPCs and Compilations

Thu, 21 Aug 2025 00:00:00 GMT

The documentation for adding and editing releases has been updated with important clarifications on two key topics:

Global UPC Uniqueness: New details on how UPCs must be unique across both sandbox and production environments.
Compilation Release Logic: A clear explanation of the validation rules for creating compilation releases, based on the number of primary artists.

These clarifications are crucial for preventing common validation errors when creating releases.

Please review the new "Important Considerations for Creating Releases" section for full details: Adding/Editing Releases

[DOCS] Expanded Data Access and Filtering in Comprehensive Analytics

Fri, 22 Aug 2025 00:00:00 GMT

The documentation for our Comprehensive Analytics section has been extensively updated to reflect newly available data segmentation and filtering options.

Key updates include:

New Aggregation Dimensions: Documentation has been added for new grouping options, including byRelease, byArtist, byLabel, byFormat, byYouTubeChannel, and byYouTubeVideo. (Note: Several new dimensions are relevant for revenue data only.)
Expanded Filtering: The "Filter" component documentation is now complete, detailing supported parameters such as releaseIds, trackIds, countryIds, and distributorIds, along with precise instructions on how to format array parameters in the query string.
New Examples: Comprehensive request and response examples have been added for all aggregation types.

Please review the updated Comprehensive Analytics section for full details on leveraging these new segmentation capabilities.

[DOCS] Clarified Track Association Rules

Fri, 22 Aug 2025 00:00:00 GMT

The documentation for adding and editing releases has been updated to clarify an important rule regarding track association.

Currently, a single trackId can only be associated with one release. We have added a dedicated section explaining this limitation and the correct procedure for including the same recording (ISRC) on multiple releases.

Please review the new "Track Association and Uniqueness" section for full details: Adding/Editing Releases

[DOCS] Keymetrics section updated

Mon, 25 Aug 2025 00:00:00 GMT

A documentation section for Keymetrics has been updated. This section now provides details about returned responses and clarification of query parameters.

Please see the updated Keymetrics section for full details and examples.

[DEPRECATED] Deprecation of 'trends' Data Set from Analytics API

Tue, 26 Aug 2025 00:00:00 GMT

The trends data set, accessible via the /analytics/trends/{/analytics/trends/{aggregationDimension}} endpoint, is now deprecated. All of its functionality has been migrated to the more comprehensive consumption data set in our V3 Analytics API.

Deprecation Timeline:

Effective September 26, 2025, the trends data set will be considered unsupported.
After this date, the endpoint will no longer be updated with new data, and its continued availability is not guaranteed.
The endpoint will be removed without further notice at some point after the deprecation date.

Action Required: All integrations must be updated to use the /analytics/consumption/{aggregation} endpoint before September 26, 2025. Any usage of the trends endpoint after this date is at your own risk and may result in receiving stale data or encountering errors as the endpoint is fully decommissioned.

For details on the replacement endpoint, please see the V3 Analytics documentation.

[DOCS] Enhanced Documentation for V3 Analytics API

Tue, 26 Aug 2025 00:00:00 GMT

The documentation for our V3 Analytics API (/analytics/{metric}/{aggregation}) has been extensively updated to provide a clearer and more comprehensive guide.

Key improvements include:

Numerous Examples: We've added request and response examples for every combination of metric and aggregation, including specific use cases for the isUgc parameter.
Clearer Explanations: Descriptions for query parameters have been refined, especially for complex array-based filters and the unique behavior of the byDate aggregation.

We encourage you to review the updated V3 Analytics section.

[CHANGE] New hasPortal Indicator for Artists and Labels

Wed, 27 Aug 2025 00:00:00 GMT

A new boolean field, hasPortal, has been added to Artist and Label responses. This field indicates whether the artist or label has an active portal account.

[CHANGE] New parameter to filter releases by UPC

Wed, 27 Aug 2025 00:00:00 GMT

A new query parameter, upc, has been added to several release retrieval endpoints, allowing you to filter for a release by its UPC (exact match only).

Please see the Retrieving Releases documentation for details.

[CHANGE] Added Terms and Conditions Indicator

Wed, 27 Aug 2025 00:00:00 GMT

A new boolean field, hasAcceptedTermsAndConditions, has been added to the client response. It indicates if the client has accepted the terms and conditions within the Revelator PRO app.

[DOCS] Clarified Request Body for Editing Partner Users

Fri, 29 Aug 2025 00:00:00 GMT

Clarified documentation regarding the request body for updating users in the user invites flow. This update also documents the required partnerApiKey parameter for authentication on this administrative endpoint.

[CHANGE] Excluded Sandbox Accounts from UPC Uniqueness Validation

Fri, 29 Aug 2025 00:00:00 GMT

Constrain preventing you from reusing UPC that was used for tests in sandbox accounts no longer applies. You can test with UPC on sandbox and freely use it in production account.

[DOCS] Update for Downloading Revenue Reports

Thu, 18 Sep 2025 00:00:00 GMT

The documentation for downloading revenue reports has been updated to provide a clearer distinction between different report types.

Key updates include:

Clarification that GET /finance/salereport/download/summary and .../details are for downloading reports generated during royalty run.
Newly documented endpoint POST /finance/salereport/post-download for bulk downloading reports from DSPs.

Please review the updated Downloading Revenue Reports section for full details on how to use these endpoints correctly.

[DOCS] Enhanced Documentation for Sale Reports Endpoint

Thu, 18 Sep 2025 00:00:00 GMT

The documentation for the /finance/salereport/all endpoint has been significantly updated to provide crucial context on its behavior.

Key updates include:

A detailed explanation of the two different report types returned by this endpoint: Reports generated during royalty run and Reports retrieved from DSP.
Clarification on which query parameters apply to each report type.
New, distinct examples for retrieving both report types.

This new information is essential for correctly filtering and interpreting the data from this endpoint. Please review the updated documentation for full details: Sale Reports Documentation.

[CHANGE] Archive assets are excluded from asset counts

Mon, 29 Sep 2025 00:00:00 GMT

TracksCount, ReleasesCount, WorksCount and PublishersCount now exclude archived assets.

[NEW] Archiving and Unarchiving Content

Mon, 29 Sep 2025 00:00:00 GMT

We've introduced a powerful new suite of endpoints for Archiving and Unarchiving various content types (Releases, Tracks, Artists, Labels, Composers, and Publishers).

This feature allows you to effectively manage the lifecycle of your content by:

Removing assets from active use while retaining their records.
Controlling content visibility (archived content is hidden by default).
Restoring content when needed.

Please be aware of the 6-month data deletion policy for associated files after archiving.

For full details on how to use these new endpoints, their prerequisites, and specific behaviors, please refer to the new documentation sections:

[NEW] Artificial Streaming Analytics

Mon, 29 Sep 2025 00:00:00 GMT

We have introduced a completely new API section dedicated to Artificial Streaming Analytics.

This section includes two new endpoints:

GET /analytics/artificialStreams/{aggregation}: Allows you to verify if streams come from automation processes, aggregated by various dimensions like track, release, artist, or client.
GET /analytics/artificialStreams/dashboard/byClient: Provides a comparative view of artificial streaming changes over time for your clients.

Full documentation, including available aggregation dimensions, query parameters, response structures, and comprehensive examples, is now available.

Please see the new Artificial Streaming section for full details.

[CHANGE] Added discNumber to Tracks for Disc Organization

Mon, 29 Sep 2025 00:00:00 GMT

We have introduced the track.discNumber property, allowing you to define disc releases.

This field enables you to assign tracks to specific discs within a release, with detailed validation rules covering disc count, sequencing, and immutability on distributed releases.

Please refer to the Adding/Editing Releases documentation for full details on how to use discNumber and its associated validation rules.

[CHANGE] No UPC Uniqueness Rules for Sandbox Accounts

Mon, 29 Sep 2025 00:00:00 GMT

The UPC uniqueness validation has been disabled for sandbox accounts.

UPCs used in your sandbox account can be freely reused in your production account, and can also be duplicated across multiple releases within the sandbox environment for easier testing.

[CHANGE] Retrieving archived content

Mon, 29 Sep 2025 00:00:00 GMT

We've enhanced several content retrieval endpoints to provide better visibility and filtering for archived content.

archived Query Parameter (boolean, optional): Allows you to filter results to include only archived content (true) or only active content (false). If omitted, returns both.
archivedAt Response Property (datetime): A new read-only property returned for archived items, indicating the date and time the content was archived.

Please refer to the updated documentation for each respective endpoint for full details.

[CHANGE] Identify Compilation Releases with isCompilation Flag

Mon, 29 Sep 2025 00:00:00 GMT

We have introduced a new isCompilation boolean flag to streamline the management and identification of compilation releases.

Release Creation/Update: You can now explicitly set isCompilation to true (defaults to false) when saving a release. Setting this flag will automatically assign the releaseTypeId 6 (Compilation).
Release Retrieval: GET endpoints that return Release objects (/content/release/all, /content/release/{id}) now include the isCompilation flag in their responses. A new query parameter isCompilation (boolean) is also available to filter releases that are or are not compilations.

Please refer to the Adding/Editing Releases documentation for more details.

[DOCS] Additional Filters for Sale Reports

Thu, 09 Oct 2025 00:00:00 GMT

Documented missing query parameters on /finance/salereport/all:

payeeId
searchText

Check out Retrieving Revenue Report Information for more details.

[CHANGE] New Parameter for Custom Revenue Share on Partner Signup

Wed, 15 Oct 2025 00:00:00 GMT

Added the optional parameter defaultContractTermsRate to the /partner/account/signup endpoint.

This allows to specify a custom default revenue share rate for the new partner account during creation, overriding the default.

Check out Signing Up New Users for more details.

[BREAKING] Deprecation of Zero (0) as Sentinel Value for New Profile Creation

Wed, 15 Oct 2025 00:00:00 GMT

Passing "0" as a value in artistExternalIds to trigger creation of a new DSP profile is being deprecated across content-related endpoints.

Previously, the system interpreted "0" as an instruction to generate a new profile. After November 15, 2025, this will result in a validation error, as "0" will be treated as an invalid ID.

Required Change: To create a new external artist profile, you must now:

Omit the field entirely, or
Set its value to null

For full implementation details, see: Managing External Artist IDs.

[CHANGE] Optional Redirect URL for White Label Authorization

Wed, 15 Oct 2025 00:00:00 GMT

Added the optional query parameter redirectUrl to the White Label authorization URL (https://<custom_v2_url>/authorize).

Check out Redirecting Authenticated Users to the Web Interface for more details.

[DOCS] New Section for Track Retrieval Endpoints

Thu, 16 Oct 2025 00:00:00 GMT

A new dedicated documentation section, Retrieving Tracks, has been added to cover the usage of the track retrieval endpoints.

The new section provides detailed query parameter definitions, request/response examples, and context for filtering and permissions.

Check out Retrieving Tracks for more details.

[DOCS] Correction of Returned Datatypes and Descriptions

Mon, 20 Oct 2025 00:00:00 GMT

Corrected returned data types and clarified descriptions for artificial streaming analytics endpoints.

[CHANGE] ACR Audio Validation Triggered on Audio Replacement During Inspection

Wed, 29 Oct 2025 00:00:00 GMT

ACR validation is now automatically triggered when a parent account user replaces an audio file on a track that belongs to a release currently undergoing inspection.

[DOCS] Clarification on Access Token Expiration

Thu, 23 Oct 2025 00:00:00 GMT

Added a note to the authentication documentation to explicitly state that all generated access tokens are valid for 8 hours.

Check out Authenticating for more details.

[DOCS] Clarification on Publisher Update Behavior in Release Save

Wed, 29 Oct 2025 00:00:00 GMT

Clarified the behavior of publisherName and publisherId during relese save.

[CHANGE] New Distribution Statuses - Owner Inspection

Wed, 29 Oct 2025 00:00:00 GMT

Two new distribution statuses have been added to support an additional layer of quality control for releases distributed via Revelator Deals:

-20 (Pending Owner Inspection): The release is pending final review by the Revelator based on specific quality control criteria.
-21 (Failed Owner Inspection): The release was rejected by the Revelator and requires action from the parent account's inspector.

These statuses ensure that releases pass a final inspection before distribution, primarily triggered by conditions like denied artists or matching audio content.

Check out Distribution Statuses for updated information.

[CHANGE] Phonetic Support for Names and Titles

Wed, 29 Oct 2025 00:00:00 GMT

Added support for phonetic localizations. You can now provide:

phoneticName for artists names, composers names, tracks titles, and releases titles.
phoneticVersion for tracks and releases.

[DOCS] New Filtering Options for Release Retrieval

Fri, 31 Oct 2025 00:00:00 GMT

Documented two optional query parameters available on the /content/release/all endpoint for filtering the list of releases:

distributionStatus: Allows filtering releases by their current distribution status.
isLocked: Allows filtering releases based on whether the release has been distributed to DSPs.

Check out Retrieving Releases for more details.

[BREAKING] UPC Data Type Conversion (Number to String)

Mon, 03 Nov 2025 00:00:00 GMT

Effective December 17, 2025, the data type for the upc property will be updated from a number type to a string type across all relevant API endpoints.

This change is being implemented to align with industry best practices and improve consistency, particularly for UPCs that may contain leading zeros, which are typically truncated when handled as numerical values.

After the deadline, attempting to send or receive upc as a numerical value may result in validation errors or incorrect data parsing. Integrators must update their systems to handle this field as a string.

[DOCS] Clarification on Compilation Logic and isCompilation Flag

Wed, 05 Nov 2025 00:00:00 GMT

Updated documentation regarding compilation releases to clearly define difference between the "Various Artists" compilations and the isCompilation flag.

Check out Creating Compilation Releases for more details.

[DOCS] Documentation Refinements and Structural Improvements

Wed, 12 Nov 2025 00:00:00 GMT

General documentation refinements and clarifications have been made across multiple sections to improve consistency, readability, and structure. These updates include clearer explanations, standardized formatting, and removal of redundant or outdated information.

[DOCS] Removal of Deprecated Trends Endpoints

Wed, 12 Nov 2025 00:00:00 GMT

All Trends endpoints have been removed from the documentation following their deprecation and replacement by the V3 Analytics consumption endpoints. This update aligns the documentation with the current API behavior and prevents confusion between legacy and active analytics versions.

[DOCS] New docs UI

Mon, 17 Nov 2025 00:00:00 GMT

Full redesign of the API docs website.

New features include:

Complete redesign from the ground up to match the Revelator brand
Performance improvements
Improved responsiveness
Ability to copy entire pages as Markdown (LLM support)
Light/dark mode
Various UX enhancements, such as easier code block copying, improved table of contents, new visual elements, and more

[CHANGE] Archive Date Filters Added

Wed, 26 Nov 2025 00:00:00 GMT

Added archivedFrom and archivedTo filters to the specified endpoints.

[CHANGE] Artist Legal Name Can Have Multiple Words

Wed, 26 Nov 2025 00:00:00 GMT

Artist firstName and lastName fields now support multiple words.

[CHANGE] Support for Filtering by Multiple UPCs and ISRCs

Wed, 26 Nov 2025 00:00:00 GMT

The following enhancements introduce support for bulk-identifier filtering:

GET /content/track/all now supports the isrcs filter, allowing queries by multiple ISRCs.
GET /content/release/all and GET /content/release/all/summary now support the upcs filter, allowing queries by multiple UPCs.

[CHANGE] Same track on multiple releases

Wed, 26 Nov 2025 00:00:00 GMT

A single track (trackId) can now be reused across multiple releases. If a release contains a track that is part of any fully locked release, any attempted modifications to that track will be ignored during the save operation.

For detailed behavior, see Track Association and Reuse under Important Considerations for Creating Releases.

[NEW] Playlist analytics

Thu, 18 Dec 2025 00:00:00 GMT

Playlist analytics are now available, providing insights into playlist-driven performance and playlist movements.

The new endpoints include:

/analytics/playlists/byMetadata — aggregated playlist performance metrics such as streams, playlist counts, and catalog coverage, with support for metadata grouping, date granularity, filtering, pagination, and ordering.
/analytics/playlists/movements — playlist movement analytics showing tracks that were added, removed, or active on playlists within a specified time period.

For details, see Playlists Analytics.

[CHANGE] Composer Metadata Handling Updated

Tue, 13 Jan 2026 00:00:00 GMT

Composer metadata (composerContentsDTO) is now optional when saving releases and tracks.

Composer data is no longer required at save time.
Providing an empty composerContentsDTO array clears all existing composer data.
Composer metadata validation has been moved to the distribution stage and may block delivery only to DSPs that require this information.

[DOCS] Retrieving Releases with Distribution Statuses

Tue, 13 Jan 2026 00:00:00 GMT

Added documentation for the GET /distribution/release/all endpoint, which returns a paginated list of releases enriched with store-level distribution status information.

This endpoint can be used to filter, search, and page through releases while inspecting their current distribution state across DSPs.

For details, see Retrieving Distribution Status.

[CHANGE] Composer Validation Enforced During Distribution

Wed, 28 Jan 2026 00:00:00 GMT

Composer metadata is no longer required when saving a release, but is now validated during distribution process.

Releases can be created and saved without composer information.
Composer metadata is now required for distribution and validated via POST /distribution/release/{releaseId}/validate.
Validation errors will block distribution for all DSPs until composer data is provided.

This change allows more flexible release creation while ensuring required publishing metadata is present before delivery.

[CHANGE] Emoji Support in Release Metadata

Wed, 28 Jan 2026 00:00:00 GMT

Emoji characters are now allowed in release and track metadata (such as titles and artist names) at save time.

During distribution, emojis are automatically stripped for DSPs that do not support them (e.g. Apple Music), while the original metadata is preserved internally and for compatible stores.

For detailed behavior, see Emoji Usage in Metadata under Important Considerations for Creating Releases.

[BREAKING] UPC Data Type Conversion (Number to String) - Deadline Update

Wed, 28 Jan 2026 00:00:00 GMT

The enforcement deadline for converting the upc property from a number to a string has been moved to February 25, 2026.

The API already accepts upc values provided as strings.
No changes are required for integrations that already treat upc as a string.

[DOCS] Retrieving Contracts

Mon, 09 Feb 2026 00:00:00 GMT

Added documentation for retrieving contracts.

The new section describes:

How to retrieve a paginated list of contracts with filtering, searching, and sorting options.
How to retrieve details for a specific contract by contractId.
Authentication requirements and supported query parameters.

For details, see Retrieving Contracts.

[DOCS] Artist Social Links and Social Sources Lookup

Fri, 13 Feb 2026 00:00:00 GMT

Added documentation for managing artist social links and introduced a new lookup endpoint for social sources.

These fields are used to enrich artist profiles within the platform and are not included in DSP delivery.

[BREAKING] API Base URL Deprecation

Tue, 17 Feb 2026 00:00:00 GMT

The app-api.revelator.com base URL is being deprecated. All API integrations should use api.revelator.com as the supported base URL. Requests to the legacy endpoint will not work after the deprecation date.

[CHANGE] Distribution and Reporting Country Flags

Wed, 18 Feb 2026 00:00:00 GMT

Added isDistributionCountry and isReportingCountry flags to the GET /common/lookup/countries response.

These flags indicate whether a country can be used in:

distribution settings (e.g. selecting delivery territories), and/or
reporting context.

The lookup endpoint now also supports filtering by these flags via query parameters.

Release distribution settings (POST /content/release/retail/save) have been clarified to explicitly state that only countries with isDistributionCountry = true are valid for inclusion or exclusion.

[CHANGE] Enterprise Filter Added to Asset Listing Endpoints

Wed, 25 Feb 2026 00:00:00 GMT

Added optional enterpriseId query parameter to selected asset listing endpoints.

When executed from a parent account, this parameter filters results to assets owned (created) by the specified child enterprise.

If omitted, the endpoints return assets according to the default account scope.

[CHANGE] Distribution and Reporting Country Flags

Wed, 25 Feb 2026 00:00:00 GMT

Added isDistributionCountry and isReportingCountry flags to the GET /common/lookup/countries response.

These flags indicate whether a country can be used in:

distribution settings (e.g. selecting delivery territories), and/or
reporting and analytics contexts.

The lookup endpoint now also supports filtering by these flags via query parameters.

[CHANGE] Pagination and Sorting Added to Release Summary Endpoint

Wed, 25 Feb 2026 00:00:00 GMT

Added support for pageNumber, pageSize, and orderByProperty query parameters to the GET /content/release/all/summary endpoint.

This endpoint now supports pagination and configurable sorting to allow better control over large result sets.

[CHANGE] Text Whitespace Normalization for Metadata Fields

Wed, 25 Feb 2026 00:00:00 GMT

Text fields submitted to the listed endpoints are now automatically normalized before being stored.

This includes:

Trimming leading and trailing whitespace
Replacing all whitespace character variants (e.g. non-breaking spaces) with a standard space character (U+0020)
Collapsing multiple consecutive spaces into a single space

This change ensures consistent formatting and prevents issues caused by invisible or irregular whitespace characters.

[FIX] Archived Releases Removed from Track Listing Response

Wed, 25 Feb 2026 00:00:00 GMT

Updated the GET /content/track/all endpoint so that archived releases are no longer included in the items[].releases[] array.

Each track in the paginated result set will now reference only active (non-archived) releases.

[DOCS] Switching Authentication Context

Fri, 10 Apr 2026 00:00:00 GMT

A new dedicated section, Switching Authentication Context, has been added to the Getting Started guide. This section details how to handle users who have access to multiple enterprises or portals.

Check out the Switching Authentication Context section for more details.

[BREAKING] Breaking Changes to Label Behavior and Track Object Cleanup

Tue, 14 Apr 2026 00:00:00 GMT

Effective May 27, 2026, we are rolling out a series of breaking changes to how labels are handled across the API to improve data clarity, eliminate implicit behaviors, and align with DSP expectations.

1. Track Object Cleanup The labelId and labelName properties are being permanently removed from the Track object. Labels are managed at the Release level, making these track-level fields redundant. Affects: /content/release/save, /content/release/{releaseId}, and /content/track/{trackId}.

2. Label Behavior Update for Releases The label field on a release will become explicitly optional. Crucially, when passing hasRecordLabel: false during release creation, the system will no longer use the artist name as a fallback label, and no label entity will be implicitly created. Instead, the label will remain null, and the value "Independent" will be standardized and sent to DSPs. Affects: /content/release/save.

3. Filter Removal Because labels are being decoupled from tracks, the labels filter will be removed from track retrieval endpoints. Affects: /content/track/all.

Integrators must update their systems prior to the deadline to avoid validation errors and parsing issues.

[NEW] New V3 Analytics metric

Thu, 16 Jan 2025 00:00:00 GMT

Added support for Engagement Analytics to the V3 Analytics. 📊

Access by using the new engagement metric
Track listener behavior with skip rates, completion rates, saves, and short-stream metrics
Compatible with all existing filters and aggregation dimensions in the
Part of our continuing effort to provide deeper streaming insights