Revelator Logo API
v1

Tracks

A track is an individual audio recording. Tracks are referenced by digital and physical releases through their assets array (see GET /catalog/v1/releases/{releaseId}/assets) and can be associated with contributing artists, composers, and publishers.

To validate a track on its own—before it is added to a release, or while you are still working on it—call

GET /supply-chain/v1/tracks/{trackId}/validate. It checks the track’s own metadata without release context. Release-level checks, such as prices and artwork, are performed by GET /supply-chain/v1/releases/{releaseId}/deliver/validate. See Validations.

Recording Versions

The recordingVersions array contains the audio recordings for a track and must include:

  • A stereo version (recordingVersionType: stereo).
  • An optional Dolby Atmos version (recordingVersionType: dolbyAtmos).

Dolby Atmos versions must meet the following requirements:

  • Sample rate: 48000 Hz
  • At least 3 audio channels
  • File size below 2 GB
  • Same total duration as the stereo version
  • Different ISRC from the stereo version

Each recording version’s files array should contain a single wav or flac audio file. Files must be uploaded through the Files API before they can be associated with a recording version.

Audio properties such as duration, bitDepth, sampleRate, bitrate, channels, and size are extracted automatically after the file is processed. Do not provide these values when creating or updating a track.

If your workflow also uses the Revelator dashboard, prefer wav files. The dashboard fully supports WAV, while FLAC files uploaded through the API may not work correctly when later opened there.

Allow time for audio processing before validation or pricing. Audio properties are extracted asynchronously and are required by some downstream operations, including price tiers and delivery validation. If GET /supply-chain/v1/releases/{releaseId}/pricing-tiers/options or GET /supply-chain/v1/releases/{releaseId}/deliver/validate fails immediately after creating a track, retry after the audio has finished processing.

The isrc for a recording version can be null, in which case an ISRC is generated automatically during distribution. Do not generate a new ISRC for a track that already has one.

Track Composers & Publishing

The composers array credits the publishing contributors for a track, such as songwriters, lyricists, and arrangers. Each entry references an existing POST /catalog/v1/composers record through composerId.

FieldDescription
roleIdThe contributor role, such as Composer or Lyricist.
rightsIdThe publishing type: 1 for self-published/copyright control, 2 for publisher-managed rights, or 3 for public domain.
publisherIdThe existing POST /catalog/v1/publishers record. Required when rightsId is 2; otherwise ignored.
shareThe contributor’s percentage share of the composition.

When rightsId is 2, publisherId must be provided.

Composer shares must be configured consistently across the track:

  • Either every composer has a share and the total is exactly 100.
  • Or every composer has share: null.

Partial shares, totals other than 100, or a mixture of values and null are not valid.

Composer publishing shares are separate from royalty contract splits. Publisher royalties are not paid through the Revelator platform.

Because composers and contributors contain IDs rather than complete records, use the following endpoints when you need the full credited entities:

Track Locking

A track inherits the most restrictive lockLevel of any release it appears on:

Release lock stateTrack lockLevel
Any release is fullyLockedfullyLocked
Otherwise, any release is partiallyLockedpartiallyLocked
Otherwiseunlocked

See Lock Levels for details on what makes a release partially or fully locked.

Dolby Atmos Read-Only

isDolbyAtmosReadOnly is a separate lock that applies only to the Dolby Atmos recording version. It is true when any release containing the track has a live Dolby Atmos package on a store.

When isDolbyAtmosReadOnly is true, you cannot:

  • Add a Dolby Atmos version if the track does not already have one.
  • Remove the existing Dolby Atmos version.
  • Change its ISRC.
  • Change its associated audio files.

The comparison uses the ISRC and file IDs. ISRC comparison is case-insensitive, and the order of files does not matter. Resubmitting the Dolby Atmos version exactly as returned by

GET /catalog/v1/tracks/{trackId} is therefore safe.

isDolbyAtmosReadOnly is independent of lockLevel. A track can be unlocked while its Dolby Atmos version is read-only; in that case, the stereo version and other track metadata remain editable.

A fullyLocked track cannot be edited regardless of the Dolby Atmos read-only state.

Parental Advisory

parentalAdvisory is a required field describing the content of the recording:

ValueMeaning
notExplicitNo explicit content and not an edited version of an explicit original.
cleanAn edited version of an explicit original with explicit language removed. The explicit version must exist and be linked.
explicitContains explicit lyrics or language.

Make sure this value accurately reflects the recording. Incorrect explicit-content metadata can result in distribution being disabled.

Archiving Tracks

A track can be archived only when it is not associated with any active (unarchived) release.

Before archiving a track, all associated releases must therefore be either:

  • Unlinked from the track, or
  • Taken down from all stores and archived.

Data Deletion Warning: Six months after a track is archived, its audio files are permanently deleted. You will receive an email notification two weeks before deletion.

Deleted audio files cannot be restored, and the track cannot be unarchived after deletion. Archived tracks cannot be edited.

Create Track

POST /catalog/v1/tracks

Creates a new track.

Request Body *

object
enterpriseId integer
The client under which the track will be created. Defaults to the caller's client when using client permissions. Required when using organization permissions.
name * string
Title of the track. Do not include additional information such as "Remix" or "Live"—use version instead. Emoji are supported and preserved internally, but are automatically stripped when delivering to DSPs that don't support them (for example, Apple Music).
version string
Version of the track (e.g., "Remix", "Acoustic", "Bonus Track").
phoneticName string
Phonetic pronunciation of the title, used for voice assistant delivery.
phoneticVersion string
Phonetic pronunciation of the version.
languageAndScriptCode string
Language and script code for the track's phonetic name/version (phoneticName/phoneticVersion), not the main title (e.g., en-Latn). Available values can be retrieved from GET /common/lookup/languageAndScriptCodes on the V1.0 API.
artistId * integer
ID of an existing artist to assign as the primary artist for the track. Required—a track cannot be created without a primary artist, and omitting it is rejected with Artist ID is required.
metadataLanguageId * integer
Language the track's title and other text fields are written in. Retrieved from GET /common/lookup/languages on the V1.0 API.
audioLanguageId * integer
Language of the track's lyrics or spoken content. Retrieved from GET /common/lookup/languages on the V1.0 API. English is 1. Required—omitting it is rejected with Audio language ID is required.
primaryMusicStyleId integer
Primary genre/music style ID for the track. Retrieved from GET /common/lookup/musicstyles on the V1.0 API.
secondaryMusicStyleId integer
Secondary genre/music style ID for the track. Retrieved from GET /common/lookup/musicstyles on the V1.0 API.
copyrightP string
Sound recording copyright for this specific track. Primarily used for compilation releases where different entities own rights to individual tracks. If omitted, the release-level copyright is used. Format: [Year] [Rights Holder] (e.g., "2024 Acme Inc.").
trackVendorId string
External vendor identifier for the track, if sourced from a third-party vendor or distributor.
lyrics string
Lyrics for the track. Note that not all stores accept lyrics.
previewStartSeconds integer
Preview/clip start time, in seconds. If omitted or set to null, the preview clip start time defaults to whatever value the DSP uses.
recordingType * RecordingTypes
Origin of the recording. See Track Origin & Track Properties for details.
Examples: original, cover, publicDomain, undeclared
parentalAdvisory * ParentalAdvisories
Advisory label for the track content. See the Parental Advisory section above. Ensure this is accurately identified—misidentifying explicit content can result in your distribution being disabled.
Examples: notExplicit, clean, explicit
recordingProperties TrackPropertyType[]
Additional properties describing the recording. See Track Origin & Track Properties for details.
Examples: none, remix, sampleStock, mixCompilation, altVersion, specialGenre, nonMusic, ai, noise, undeclared
posterImageId string
File ID (GUID) of the track's cover artwork, uploaded via the Files API. Optional—used for tracks distributed independently of a release's artwork (e.g., YouTube Content ID).
isrc string
ISRC code for this recording version. Leave null to have one generated automatically during distribution. If a Dolby Atmos version exists, its ISRC must differ from the stereo version's.
recordingVersionType * TrackRecordingVersionTypes
Type of recording version.
Examples: stereo, dolbyAtmos
fileId * string
File ID (GUID) of the previously uploaded audio file, generated by the Files API.
format * WellKnownFileFormat
Audio file format. Prefer wav if your users may also work in the Revelator dashboard, which fully supports WAV only.
Examples: wav, flac
filename string
Name of the uploaded file, including the extension.
duration integer
Duration of the audio file, in seconds. Computed automatically after processing.
bitDepth integer
Bit depth of the audio file. Computed automatically after processing.
sampleRate integer
Sample rate of the audio file, in Hz. Computed automatically after processing.
bitrate integer
Bitrate of the audio file. Computed automatically after processing.
channels integer
Number of audio channels. Must be at least 3 for Dolby Atmos versions. Computed automatically after processing.
size integer
File size, in bytes. Computed automatically after processing.
artistId * integer
ID of an existing artist to credit as a contributor.
roleId * integer
Contributor role ID. Look up available roles using GET /common/lookup/contributorRoles on the V1.0 API. Using the Primary Artist role (roleId 49) here counts toward the release's "Various Artists" compilation determination—see the Compilations section on the Releases page.
composerId integer
ID of an existing composer to credit on this track.
roleId * integer
Publishing role ID for the composer (e.g., Composer, Lyricist). Look up available roles using GET /common/lookup/contributorRoles on the V1.0 API.
rightsId * integer
Publishing type for this composer credit: 1 (copyright control / self-published), 2 (published, managed by a publisher), or 3 (public domain).
Examples: 1, 2, 3
publisherId integer
ID of an existing publisher to associate with this composer credit. Required when rightsId is 2 (omitting it is rejected with Publisher is required for managed rights.) and ignored for any other rightsId.
share number
Share percentage for the composer. Either every composer on the track has a share and they sum to exactly 100, or every composer leaves this null. A partial total, or a mix of values and nulls, is rejected with Composer shares must sum to 100 or all be null.
iswc string
International Standard Musical Work Code (ISWC) for the underlying composition. Format: T followed by 10 digits (e.g., T1234567890).
languageId * integer
Language ID for this localization entry. Each language can be used only once in the array. Retrieved from GET /common/lookup/languages on the V1.0 API.
name * string
Track title in the specified language.
version string
Version subtitle in the specified language.
phoneticName string
Phonetic pronunciation of the title in the specified language.
phoneticVersion string
Phonetic pronunciation of the version in the specified language.
languageAndScriptCode string
Language and script code for this entry's phonetic name/version, not the localized title (e.g., en-Latn). Retrieved from GET /common/lookup/languageAndScriptCodes on the V1.0 API.

Responses

object
trackId integer
Unique identifier for the track.
assetId integer
Universal asset ID for this track, used in archive, unarchive, and rights operations.
tenantId integer
ID of the organization that owns this track.
enterpriseId integer
ID of the client that owns this track.
name string | null
Title of the track.
version string | null
Version of the track (e.g., "Remix", "Acoustic").
phoneticName string | null
Phonetic pronunciation of the title.
phoneticVersion string | null
Phonetic pronunciation of the version.
languageAndScriptCode string | null
Language and script code for the track's phonetic name/version, not the main title.
artistId integer | null
ID of the primary artist. null if the track has no distinct primary artist.
metadataLanguageId integer | null
Language the track's title and other text fields are written in.
audioLanguageId integer | null
Language of the track's lyrics or spoken content.
primaryMusicStyleId integer | null
Primary genre/music style ID for the track.
secondaryMusicStyleId integer | null
Secondary genre/music style ID for the track.
copyrightP string | null
Sound recording copyright for this specific track. Falls back to the release-level copyright when not set.
trackVendorId string | null
External vendor identifier for the track, if sourced from a third-party vendor or distributor.
youTubeVideoId string | null
ID of the YouTube video associated with this track, if any.
youTubeCIDAssetId string | null
YouTube Content ID asset ID associated with this track, if any.
lyrics string | null
Lyrics for the track.
previewStartSeconds integer | null
Preview/clip start time, in seconds.
recordingType RecordingTypes
Origin of the recording. See Track Origin & Track Properties for details.
Examples: original, cover, publicDomain, undeclared
parentalAdvisory ParentalAdvisories
Advisory label for the track content.
Examples: notExplicit, clean, explicit
recordingProperties TrackPropertyType[] | null
Additional properties describing the recording.
Examples: none, remix, sampleStock, mixCompilation, altVersion, specialGenre, nonMusic, ai, noise, undeclared
posterImageId string | null
File ID of the track's cover artwork.
isrc string | null
ISRC code for this recording version.
recordingVersionType TrackRecordingVersionTypes
Type of recording version.
Examples: stereo, dolbyAtmos
fileId string
File ID of the uploaded audio file.
format WellKnownFileFormat
Audio file format.
Examples: wav, flac
filename string | null
Name of the uploaded file, including the extension.
duration integer | null
Duration of the audio file, in seconds.
bitDepth integer | null
Bit depth of the audio file.
sampleRate integer | null
Sample rate of the audio file, in Hz.
bitrate integer | null
Bitrate of the audio file.
channels integer | null
Number of audio channels.
size integer | null
File size, in bytes.
artistId * integer
ID of the contributing artist.
roleId * integer
Contributor role ID.
composerId integer
ID of the composer.
roleId integer
Publishing role ID for the composer.
rightsId integer
Publishing type for this composer credit: 1 (copyright control / self-published), 2 (published, managed by a publisher), or 3 (public domain).
Examples: 1, 2, 3
publisherId integer | null
ID of the publisher associated with this composer credit. Always set when rightsId is 2; null otherwise.
share number | null
Share percentage for the composer. Either all composers on the track carry a share summing to 100, or all are null.
iswc string | null
International Standard Musical Work Code (ISWC) for the underlying composition.
languageId * integer
Language ID for this localization entry.
name * string
Track title in the specified language.
version string | null
Version subtitle in the specified language.
phoneticName string | null
Phonetic pronunciation of the title in the specified language.
phoneticVersion string | null
Phonetic pronunciation of the version in the specified language.
languageAndScriptCode string | null
Language and script code for this entry's phonetic name/version, not the localized title.
fileId string
File ID of the audio file that was scanned.
acrId string | null
ACRCloud's identifier for this scan. null until the scan completes.
status AcrCloudScanStatus
Scan status.
Examples: inProcessing, complete, error
creationDate string (date-time)
UTC timestamp when the scan record was created.
timestampUtc string (date-time) | null
UTC timestamp reported by ACRCloud for the scan result. null until the scan completes.
musicDetected integer | null
Amount of music detected by the scan.
duration integer | null
Duration analyzed by the scan, in seconds.
error string | null
Error message if the scan failed. null on success.
isrc string | null
ISRC reported by the scan for the matched recording. null if the scan produced no match.
scans object[] | null
Individual fingerprint scan passes run against the file.
coverSongs object[] | null
Cover-song matches detected by the scan.
derivativeWorks object[] | null
Derivative-work matches detected by the scan.
speechDetection object[] | null
Speech segments detected in the file.
aiDetection object[] | null
AI-generated-content detection results for the file.
creationDate string (date-time) | null
UTC timestamp when the track was created.
createdBy string | null
ID of the user who created the track.
lastUpdateDate string (date-time) | null
UTC timestamp of the most recent update. null if the track has never been updated.
lastUpdatedBy string | null
ID of the user who last updated the track. null if the track has never been updated.
archivedAt string (date-time) | null
UTC timestamp when the track was archived. null if the track is active.
archivedBy string | null
ID of the user who archived the track. null if the track is active.
lockLevel AssetLockLevels
Edit permission level for this track. See the Track Locking section above for details.
Examples: unlocked, partiallyLocked, fullyLocked
isDolbyAtmosReadOnly boolean
Set to true when a release this track appears on has a live Dolby Atmos package on a store. While true, the Dolby Atmos recording version cannot be added, removed, or altered. See the Dolby Atmos Read-Only section above.
POST /catalog/v1/tracks 
curl -X POST "https://platform.revelator.com/catalog/v1/tracks" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "name": "Night Lights",
  "artistId": 4402,
  "audioLanguageId": 1,
  "metadataLanguageId": 1,
  "primaryMusicStyleId": 17,
  "copyrightP": "2024 Northline Records",
  "lyrics": null,
  "previewStartSeconds": null,
  "recordingType": "original",
  "parentalAdvisory": "notExplicit",
  "recordingProperties": ["none"],
  "posterImageId": null,
  "recordingVersions": [
    {
      "isrc": "QZ8AB2400011",
      "recordingVersionType": "stereo",
      "files": [
        { "fileId": "d12fd57a-e739-44fd-9246-31f50d4ee5f6", "format": "wav" }
      ]
    }
  ],
  "contributors": [],
  "composers": [
    { "composerId": 6601, "roleId": 2, "rightsId": 2, "publisherId": 3301, "share": 100 }
  ],
  "compositions": [],
  "locals": []
}'
Example response 200 
{
"trackId": 7701,
"assetId": 4419835,
"tenantId": 2001,
"enterpriseId": 3001,
"name": "Night Lights",
"version": null,
"phoneticName": null,
"phoneticVersion": null,
"languageAndScriptCode": null,
"artistId": 4402,
"metadataLanguageId": 1,
"audioLanguageId": 1,
"primaryMusicStyleId": 17,
"secondaryMusicStyleId": null,
"copyrightP": "2024 Northline Records",
"trackVendorId": null,
"youTubeVideoId": null,
"youTubeCIDAssetId": null,
"lyrics": null,
"previewStartSeconds": null,
"recordingType": "original",
"parentalAdvisory": "notExplicit",
"recordingProperties": ["none"],
"posterImageId": null,
"recordingVersions": [
  {
    "isrc": "QZ8AB2400011",
    "recordingVersionType": "stereo",
    "files": [
      {
        "fileId": "d12fd57a-e739-44fd-9246-31f50d4ee5f6",
        "format": "wav",
        "filename": "night-lights.wav",
        "duration": 223,
        "bitDepth": 24,
        "sampleRate": 48000,
        "bitrate": 2304000,
        "channels": 2,
        "size": 42102300
      }
    ]
  }
],
"contributors": [],
"composers": [
  { "composerId": 6601, "roleId": 2, "rightsId": 2, "publisherId": 3301, "share": 100 }
],
"compositions": [],
"locals": [],
"acrCloud": null,
"creationDate": "2024-05-01T11:45:00Z",
"createdBy": "b3f1a2c4-1111-4e5f-a678-426614174000",
"lastUpdateDate": null,
"lastUpdatedBy": null,
"archivedAt": null,
"archivedBy": null,
"isDolbyAtmosReadOnly": false,
"lockLevel": "unlocked"
}

Get Track

GET /catalog/v1/tracks/{trackId}

Retrieves a track by its ID.

Path Parameters

Parameter Description
trackId * integer

The ID of the track.

Responses

object
trackId integer
Unique identifier for the track.
assetId integer
Universal asset ID for this track, used in archive, unarchive, and rights operations.
tenantId integer
ID of the organization that owns this track.
enterpriseId integer
ID of the client that owns this track.
name string | null
Title of the track.
version string | null
Version of the track (e.g., "Remix", "Acoustic").
phoneticName string | null
Phonetic pronunciation of the title.
phoneticVersion string | null
Phonetic pronunciation of the version.
languageAndScriptCode string | null
Language and script code for the track's phonetic name/version, not the main title.
artistId integer | null
ID of the primary artist. null if the track has no distinct primary artist.
metadataLanguageId integer | null
Language the track's title and other text fields are written in.
audioLanguageId integer | null
Language of the track's lyrics or spoken content.
primaryMusicStyleId integer | null
Primary genre/music style ID for the track.
secondaryMusicStyleId integer | null
Secondary genre/music style ID for the track.
copyrightP string | null
Sound recording copyright for this specific track. Falls back to the release-level copyright when not set.
trackVendorId string | null
External vendor identifier for the track, if sourced from a third-party vendor or distributor.
youTubeVideoId string | null
ID of the YouTube video associated with this track, if any.
youTubeCIDAssetId string | null
YouTube Content ID asset ID associated with this track, if any.
lyrics string | null
Lyrics for the track.
previewStartSeconds integer | null
Preview/clip start time, in seconds.
recordingType RecordingTypes
Origin of the recording. See Track Origin & Track Properties for details.
Examples: original, cover, publicDomain, undeclared
parentalAdvisory ParentalAdvisories
Advisory label for the track content.
Examples: notExplicit, clean, explicit
recordingProperties TrackPropertyType[] | null
Additional properties describing the recording.
Examples: none, remix, sampleStock, mixCompilation, altVersion, specialGenre, nonMusic, ai, noise, undeclared
posterImageId string | null
File ID of the track's cover artwork.
isrc string | null
ISRC code for this recording version.
recordingVersionType TrackRecordingVersionTypes
Type of recording version.
Examples: stereo, dolbyAtmos
fileId string
File ID of the uploaded audio file.
format WellKnownFileFormat
Audio file format.
Examples: wav, flac
filename string | null
Name of the uploaded file, including the extension.
duration integer | null
Duration of the audio file, in seconds.
bitDepth integer | null
Bit depth of the audio file.
sampleRate integer | null
Sample rate of the audio file, in Hz.
bitrate integer | null
Bitrate of the audio file.
channels integer | null
Number of audio channels.
size integer | null
File size, in bytes.
artistId * integer
ID of the contributing artist.
roleId * integer
Contributor role ID.
composerId integer
ID of the composer.
roleId integer
Publishing role ID for the composer.
rightsId integer
Publishing type for this composer credit: 1 (copyright control / self-published), 2 (published, managed by a publisher), or 3 (public domain).
Examples: 1, 2, 3
publisherId integer | null
ID of the publisher associated with this composer credit. Always set when rightsId is 2; null otherwise.
share number | null
Share percentage for the composer. Either all composers on the track carry a share summing to 100, or all are null.
iswc string | null
International Standard Musical Work Code (ISWC) for the underlying composition.
languageId * integer
Language ID for this localization entry.
name * string
Track title in the specified language.
version string | null
Version subtitle in the specified language.
phoneticName string | null
Phonetic pronunciation of the title in the specified language.
phoneticVersion string | null
Phonetic pronunciation of the version in the specified language.
languageAndScriptCode string | null
Language and script code for this entry's phonetic name/version, not the localized title.
fileId string
File ID of the audio file that was scanned.
acrId string | null
ACRCloud's identifier for this scan. null until the scan completes.
status AcrCloudScanStatus
Scan status.
Examples: inProcessing, complete, error
creationDate string (date-time)
UTC timestamp when the scan record was created.
timestampUtc string (date-time) | null
UTC timestamp reported by ACRCloud for the scan result. null until the scan completes.
musicDetected integer | null
Amount of music detected by the scan.
duration integer | null
Duration analyzed by the scan, in seconds.
error string | null
Error message if the scan failed. null on success.
isrc string | null
ISRC reported by the scan for the matched recording. null if the scan produced no match.
scans object[] | null
Individual fingerprint scan passes run against the file.
coverSongs object[] | null
Cover-song matches detected by the scan.
derivativeWorks object[] | null
Derivative-work matches detected by the scan.
speechDetection object[] | null
Speech segments detected in the file.
aiDetection object[] | null
AI-generated-content detection results for the file.
creationDate string (date-time) | null
UTC timestamp when the track was created.
createdBy string | null
ID of the user who created the track.
lastUpdateDate string (date-time) | null
UTC timestamp of the most recent update. null if the track has never been updated.
lastUpdatedBy string | null
ID of the user who last updated the track. null if the track has never been updated.
archivedAt string (date-time) | null
UTC timestamp when the track was archived. null if the track is active.
archivedBy string | null
ID of the user who archived the track. null if the track is active.
lockLevel AssetLockLevels
Edit permission level for this track. See the Track Locking section above.
Examples: unlocked, partiallyLocked, fullyLocked
isDolbyAtmosReadOnly boolean
Set to true when a release this track appears on has a live Dolby Atmos package on a store. While true, the Dolby Atmos recording version cannot be added, removed, or altered. See the Dolby Atmos Read-Only section above.
GET /catalog/v1/tracks/{trackId} 
curl -X GET "https://platform.revelator.com/catalog/v1/tracks/7701" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Example response 200 
{
"trackId": 7701,
"assetId": 4419835,
"tenantId": 2001,
"enterpriseId": 3001,
"name": "Night Lights",
"version": null,
"phoneticName": null,
"phoneticVersion": null,
"languageAndScriptCode": null,
"artistId": 4402,
"metadataLanguageId": 1,
"audioLanguageId": 1,
"primaryMusicStyleId": 17,
"secondaryMusicStyleId": null,
"copyrightP": "2024 Northline Records",
"trackVendorId": null,
"youTubeVideoId": null,
"youTubeCIDAssetId": null,
"lyrics": null,
"previewStartSeconds": null,
"recordingType": "original",
"parentalAdvisory": "notExplicit",
"recordingProperties": ["none"],
"posterImageId": null,
"recordingVersions": [
  {
    "isrc": "QZ8AB2400011",
    "recordingVersionType": "stereo",
    "files": [
      {
        "fileId": "d12fd57a-e739-44fd-9246-31f50d4ee5f6",
        "format": "wav",
        "filename": "night-lights.wav",
        "duration": 223,
        "bitDepth": 24,
        "sampleRate": 48000,
        "bitrate": 2304000,
        "channels": 2,
        "size": 42102300
      }
    ]
  }
],
"contributors": [],
"composers": [
  { "composerId": 6601, "roleId": 2, "rightsId": 2, "publisherId": 3301, "share": 100 }
],
"compositions": [],
"locals": [],
"acrCloud": {
  "fileId": "d12fd57a-e739-44fd-9246-31f50d4ee5f6",
  "acrId": "9f1e2a3b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
  "status": "complete",
  "creationDate": "2024-05-01T12:05:00Z",
  "timestampUtc": "2024-05-01T12:06:12Z",
  "musicDetected": 100,
  "duration": 223,
  "error": null,
  "isrc": "USRC17607839",
  "scans": [],
  "coverSongs": [],
  "derivativeWorks": [],
  "speechDetection": [],
  "aiDetection": []
},
"creationDate": "2024-05-01T11:45:00Z",
"createdBy": "b3f1a2c4-1111-4e5f-a678-426614174000",
"lastUpdateDate": "2024-05-15T08:30:00Z",
"lastUpdatedBy": "b3f1a2c4-1111-4e5f-a678-426614174000",
"archivedAt": null,
"archivedBy": null,
"isDolbyAtmosReadOnly": false,
"lockLevel": "unlocked"
}

List Tracks

GET /catalog/v1/tracks

Returns a paginated list of tracks based on filters and sorting options.

Query Parameters

Parameter Description
searchText string

Free-text search applied to track name and other supported fields.
orderByProperty string

Property name used for sorting.

Examples: creationDate, name, artistName, trackId, trackLength
orderByDescending boolean

Set to true for descending order, false for ascending.
pageNumber integer

Page number for paginated results.
pageSize integer

Number of items per page.
creationDateFrom string (date-time)

Include tracks created on or after this UTC date-time.
creationDateTo string (date-time)

Include tracks created on or before this UTC date-time.
lastUpdateDateFrom string (date-time)

Include tracks updated on or after this UTC date-time.
lastUpdateDateTo string (date-time)

Include tracks updated on or before this UTC date-time.
archived boolean

Filter by archive state (true for archived, false for active).
archivedDateFrom string (date-time)

Include tracks archived on or after this UTC date-time.
archivedDateTo string (date-time)

Include tracks archived on or before this UTC date-time.
parentalAdvisory string

Filter by advisory label. See the Parental Advisory section above.

Examples: notExplicit, clean, explicit
missingAudioFile boolean

Filter to tracks missing an audio file (true) or having one (false).
isHighResolution boolean

Filter to high-resolution audio tracks (true) or standard-resolution tracks (false).
recordingVersionType string

Filter to tracks that have a recording version of this type.

Examples: stereo, dolbyAtmos
lockLevel string

Filter by edit permission level. See the Track Locking section above.

Examples: unlocked, partiallyLocked, fullyLocked
isrcs string[]

Filter by one or more ISRC codes. Maximum 100 per request.
upcs string[]

Filter to tracks belonging to releases with the given UPC codes. Maximum 100 per request.
musicStyleIds integer[]

Filter by one or more primary music style IDs. Retrieved from GET /common/lookup/musicstyles on the V1.0 API. Maximum 100 IDs per request.
metadataLanguageIds integer[]

Filter by one or more language IDs. Maximum 100 IDs per request. Retrieved from GET /common/lookup/languages on the V1.0 API.
audioLanguageIds integer[]

Filter by one or more audio language IDs. Maximum 100 IDs per request. Retrieved from GET /common/lookup/languages on the V1.0 API.
releaseAssetIds integer[]

Filter to tracks that belong to a release with one of the given asset IDs. Pass the release's assetId, not the track's—this returns every track on those releases. Maximum 100 IDs per request.
physicalReleaseAssetIds integer[]

Filter to tracks that belong to a physical release with one of the given asset IDs. Pass the physical release's assetId, not the track's. Maximum 100 IDs per request.
assetIds integer[]

Filter by the tracks' own asset IDs—the assetId returned on each track. Use this when you hold a track asset ID and want that track back. Maximum 100 IDs per request.
trackIds integer[]

Filter by one or more track IDs. Maximum 100 IDs per request.
artistIds integer[]

Filter by one or more primary artist IDs. Maximum 100 IDs per request.
labelIds integer[]

Filter by one or more label IDs associated with releases that include the track. Maximum 100 IDs per request.
enterpriseIds integer[]

Filter by one or more client IDs. Maximum 100 IDs per request.
payeeIds integer[]

Filter by one or more payee IDs associated with the track. Maximum 100 IDs per request.

Responses

object
pageNumber integer
Current page number.
pageSize integer
Number of items per page.
totalItemsCount integer
Total number of tracks matching the filters.
totalPagesCount number
Total number of pages.
trackId integer
Unique identifier for the track.
assetId integer
Universal asset ID for this track.
tenantId integer
ID of the organization that owns this track.
name string | null
Title of the track.
version string | null
Version of the track.
artistId integer
ID of the primary artist.
artistName string | null
Display name of the primary artist.
enterpriseId integer
ID of the client that owns this track.
enterpriseName string | null
Name of the client.
trackLength integer | null
Total duration of the track, in seconds, computed from the stereo recording version.
isHighResolution boolean
Whether the stereo audio file qualifies as high resolution.
recordingType RecordingTypes
Origin of the recording.
Examples: original, cover, publicDomain, undeclared
parentalAdvisory ParentalAdvisories
Advisory label for the track content.
Examples: notExplicit, clean, explicit
iswc string | null
International Standard Musical Work Code (ISWC) for the underlying composition.
trackVendorId string | null
External vendor identifier for the track, if sourced from a third-party vendor or distributor.
copyrightP string | null
Sound recording copyright for this specific track. Falls back to the release-level copyright when not set.
metadataLanguageId integer | null
Language the track's title and other text fields are written in.
metadataLanguageName string | null
Metadata language name.
audioLanguageId integer | null
Language of the track's lyrics or spoken content.
audioLanguageName string | null
Audio language name.
languageAndScriptCode string | null
Language and script code for the track's phonetic name/version, not the main title.
primaryMusicStyleId integer | null
Primary genre/music style ID.
primaryMusicStyleName string | null
Primary genre/music style name.
secondaryMusicStyleId integer | null
Secondary genre/music style ID.
secondaryMusicStyleName string | null
Secondary genre/music style name.
releasesCount integer
Number of releases this track is currently assigned to.
posterImageId string | null
File ID of the track's cover artwork.
fileId string
File ID of the audio file that was scanned.
acrId string | null
ACRCloud's identifier for this scan. null until the scan completes.
status AcrCloudScanStatus
Scan status.
Examples: inProcessing, complete, error
creationDate string (date-time)
UTC timestamp when the scan record was created.
timestampUtc string (date-time) | null
UTC timestamp reported by ACRCloud for the scan result. null until the scan completes.
musicDetected integer | null
Amount of music detected by the scan.
duration integer | null
Duration analyzed by the scan, in seconds.
error string | null
Error message if the scan failed. null on success.
isrc string | null
ISRC reported by the scan for the matched recording. null if the scan produced no match.
scans object[] | null
Individual fingerprint scan passes run against the file.
coverSongs object[] | null
Cover-song matches detected by the scan.
derivativeWorks object[] | null
Derivative-work matches detected by the scan.
speechDetection object[] | null
Speech segments detected in the file.
aiDetection object[] | null
AI-generated-content detection results for the file.
lockLevel AssetLockLevels
Edit permission level for this track.
Examples: unlocked, partiallyLocked, fullyLocked
isDolbyAtmosReadOnly boolean
Set to true when a release this track appears on has a live Dolby Atmos package on a store. While true, the Dolby Atmos recording version cannot be added, removed, or altered. See the Dolby Atmos Read-Only section above.
isrc string | null
ISRC code for this recording version.
recordingVersionType TrackRecordingVersionTypes
Type of recording version.
Examples: stereo, dolbyAtmos
fileId string
File ID of the uploaded audio file.
format WellKnownFileFormat
Audio file format.
Examples: wav, flac
filename string | null
Name of the uploaded file, including the extension.
duration integer | null
Duration of the audio file, in seconds.
bitDepth integer | null
Bit depth of the audio file.
sampleRate integer | null
Sample rate of the audio file, in Hz.
bitrate integer | null
Bitrate of the audio file.
channels integer | null
Number of audio channels.
size integer | null
File size, in bytes.
artistId integer
ID of the contributing artist.
roleId integer
Contributor role ID.
artistName string | null
Display name of the contributing artist.
composerId integer
ID of the composer.
composerName string | null
Composer's full legal name.
composerImageId string | null
File ID of the composer's photo or logo image.
roleId integer
Publishing role ID for the composer.
publisherId integer | null
ID of the publisher associated with this composer credit. null if none.
publisherName string | null
Name of the publisher associated with this composer credit.
publisherImageId string | null
File ID of the publisher's logo image.
creationDate string (date-time)
UTC timestamp when the track was created.
archivedAt string (date-time) | null
UTC timestamp when the track was archived. null if the track is active.
GET /catalog/v1/tracks 
curl -X GET "https://platform.revelator.com/catalog/v1/tracks?pageNumber=1&pageSize=20&artistIds=4402&orderByProperty=creationDate&orderByDescending=true" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Example response 200 
{
"pageNumber": 1,
"pageSize": 20,
"totalItemsCount": 1,
"totalPagesCount": 1,
"items": [
  {
    "trackId": 7701,
    "assetId": 4419835,
    "tenantId": 2001,
    "name": "Night Lights",
    "version": null,
    "artistId": 4402,
    "artistName": "Nova Days",
    "enterpriseId": 3001,
    "enterpriseName": "Client Name",
    "trackLength": 223,
    "isHighResolution": true,
    "recordingType": "original",
    "parentalAdvisory": "notExplicit",
    "compositions": [],
    "trackVendorId": null,
    "copyrightP": "2024 Northline Records",
    "metadataLanguageId": null,
    "metadataLanguageName": null,
    "audioLanguageId": 1,
    "audioLanguageName": "English",
    "languageAndScriptCode": null,
    "primaryMusicStyleId": 17,
    "primaryMusicStyleName": "Electronic",
    "secondaryMusicStyleId": null,
    "secondaryMusicStyleName": null,
    "releasesCount": 1,
    "posterImageId": null,
    "acrCloud": null,
    "isDolbyAtmosReadOnly": false,
    "lockLevel": "unlocked",
    "recordingVersions": [
      {
        "isrc": "QZ8AB2400011",
        "recordingVersionType": "stereo",
        "files": [
          {
            "fileId": "d12fd57a-e739-44fd-9246-31f50d4ee5f6",
            "format": "wav",
            "filename": "night-lights.wav",
            "duration": 223,
            "bitDepth": 24,
            "sampleRate": 48000,
            "bitrate": 2304000,
            "channels": 2,
            "size": 42102300
          }
        ]
      }
    ],
    "contributors": [],
    "composers": [
      {
        "composerId": 6601,
        "composerName": "Example Composer",
        "composerImageId": null,
        "roleId": 2,
        "publisherId": 3301,
        "publisherName": "Example Publisher",
        "publisherImageId": null
      }
    ],
    "creationDate": "2024-05-01T11:45:00Z",
    "archivedAt": null
  }
]
}

Update Track

PUT /catalog/v1/tracks/{trackId}

Updates an existing track by its ID.

Path Parameters

Parameter Description
trackId * integer

The ID of the track to update.

Request Body *

object
enterpriseId integer
Ignored when updating an existing track; the update always targets the track identified by trackId regardless of client.
name * string
Title of the track. Emoji are supported and preserved internally, but are automatically stripped when delivering to DSPs that don't support them (for example, Apple Music).
version string
Version of the track (e.g., "Remix", "Acoustic", "Bonus Track").
phoneticName string
Phonetic pronunciation of the title, used for voice assistant delivery.
phoneticVersion string
Phonetic pronunciation of the version.
languageAndScriptCode string
Language and script code for the track's phonetic name/version (phoneticName/phoneticVersion), not the main title (e.g., en-Latn). Available values can be retrieved from GET /common/lookup/languageAndScriptCodes on the V1.0 API.
artistId integer
ID of an existing artist to assign as the primary artist for the track. Omit or set to null if the track has no distinct primary artist.
metadataLanguageId * integer
Language the track's title and other text fields are written in. Retrieved from GET /common/lookup/languages on the V1.0 API.
audioLanguageId integer
Language of the track's lyrics or spoken content. Retrieved from GET /common/lookup/languages on the V1.0 API.
primaryMusicStyleId integer
Primary genre/music style ID for the track. Retrieved from GET /common/lookup/musicstyles on the V1.0 API.
secondaryMusicStyleId integer
Secondary genre/music style ID for the track. Retrieved from GET /common/lookup/musicstyles on the V1.0 API.
copyrightP string
Sound recording copyright for this specific track. If omitted, the release-level copyright is used.
trackVendorId string
External vendor identifier for the track, if sourced from a third-party vendor or distributor.
lyrics string
Lyrics for the track. Note that not all stores accept lyrics.
previewStartSeconds integer
Preview/clip start time, in seconds.
recordingType * RecordingTypes
Origin of the recording. See Track Origin & Track Properties for details.
Examples: original, cover, publicDomain, undeclared
parentalAdvisory * ParentalAdvisories
Advisory label for the track content. See the Parental Advisory section above. Ensure this is accurately identified—misidentifying explicit content can result in your distribution being disabled.
Examples: notExplicit, clean, explicit
recordingProperties TrackPropertyType[]
Additional properties describing the recording.
Examples: none, remix, sampleStock, mixCompilation, altVersion, specialGenre, nonMusic, ai, noise, undeclared
posterImageId string
File ID (GUID) of the track's cover artwork, uploaded via the Files API.
isrc string
ISRC code for this recording version. If a Dolby Atmos version exists, its ISRC must differ from the stereo version's.
recordingVersionType TrackRecordingVersionTypes
Type of recording version.
Examples: stereo, dolbyAtmos
fileId string
File ID (GUID) of the previously uploaded audio file, generated by the Files API.
format WellKnownFileFormat
Audio file format. Prefer wav if your users may also work in the Revelator dashboard, which fully supports WAV only.
Examples: wav, flac
filename string
Name of the uploaded file, including the extension.
duration integer
Duration of the audio file, in seconds. Computed automatically after processing.
bitDepth integer
Bit depth of the audio file. Computed automatically after processing.
sampleRate integer
Sample rate of the audio file, in Hz. Computed automatically after processing.
bitrate integer
Bitrate of the audio file. Computed automatically after processing.
channels integer
Number of audio channels. Computed automatically after processing.
size integer
File size, in bytes. Computed automatically after processing.
artistId * integer
ID of an existing artist to credit as a contributor.
roleId * integer
Contributor role ID. Using the Primary Artist role (roleId 49) here counts toward the release's "Various Artists" compilation determination—see the Compilations section on the Releases page. Retrieved from GET /common/lookup/contributorRoles on the V1.0 API.
composerId integer
ID of an existing composer to credit on this track.
roleId integer
Publishing role ID for the composer. Retrieved from GET /common/lookup/contributorRoles on the V1.0 API.
rightsId integer
Publishing type for this composer credit: 1 (copyright control / self-published), 2 (published, managed by a publisher), or 3 (public domain).
Examples: 1, 2, 3
publisherId integer
ID of an existing publisher to associate with this composer credit. Required when rightsId is 2 (omitting it is rejected with Publisher is required for managed rights.) and ignored for any other rightsId.
share number
Share percentage for the composer. Either every composer on the track has a share and they sum to exactly 100, or every composer leaves this null. A partial total, or a mix of values and nulls, is rejected with Composer shares must sum to 100 or all be null.
iswc string
International Standard Musical Work Code (ISWC) for the underlying composition.
languageId * integer
Language ID for this localization entry. Each language can be used only once in the array. Retrieved from GET /common/lookup/languages on the V1.0 API.
name * string
Track title in the specified language.
version string
Version subtitle in the specified language.
phoneticName string
Phonetic pronunciation of the title in the specified language.
phoneticVersion string
Phonetic pronunciation of the version in the specified language.
languageAndScriptCode string
Language and script code for this entry's phonetic name/version, not the localized title (e.g., en-Latn). Retrieved from GET /common/lookup/languageAndScriptCodes on the V1.0 API.

Responses

object
trackId integer
Unique identifier for the track.
assetId integer
Universal asset ID for this track.
tenantId integer
ID of the organization that owns this track.
enterpriseId integer
ID of the client that owns this track.
name string | null
Title of the track.
version string | null
Version of the track (e.g., "Remix", "Acoustic").
phoneticName string | null
Phonetic pronunciation of the title.
phoneticVersion string | null
Phonetic pronunciation of the version.
languageAndScriptCode string | null
Language and script code for the track's phonetic name/version, not the main title.
artistId integer | null
ID of the primary artist. null if the track has no distinct primary artist.
metadataLanguageId integer | null
Language the track's title and other text fields are written in.
audioLanguageId integer | null
Language of the track's lyrics or spoken content.
primaryMusicStyleId integer | null
Primary genre/music style ID for the track.
secondaryMusicStyleId integer | null
Secondary genre/music style ID for the track.
copyrightP string | null
Sound recording copyright for this specific track. Falls back to the release-level copyright when not set.
trackVendorId string | null
External vendor identifier for the track, if sourced from a third-party vendor or distributor.
youTubeVideoId string | null
ID of the YouTube video associated with this track, if any.
youTubeCIDAssetId string | null
YouTube Content ID asset ID associated with this track, if any.
lyrics string | null
Lyrics for the track.
previewStartSeconds integer | null
Preview/clip start time, in seconds.
recordingType RecordingTypes
Origin of the recording. See Track Origin & Track Properties for details.
Examples: original, cover, publicDomain, undeclared
parentalAdvisory ParentalAdvisories
Advisory label for the track content.
Examples: notExplicit, clean, explicit
recordingProperties TrackPropertyType[] | null
Additional properties describing the recording.
Examples: none, remix, sampleStock, mixCompilation, altVersion, specialGenre, nonMusic, ai, noise, undeclared
posterImageId string | null
File ID of the track's cover artwork.
isrc string | null
ISRC code for this recording version.
recordingVersionType TrackRecordingVersionTypes
Type of recording version.
Examples: stereo, dolbyAtmos
fileId string
File ID of the uploaded audio file.
format WellKnownFileFormat
Audio file format.
Examples: wav, flac
filename string | null
Name of the uploaded file, including the extension.
duration integer | null
Duration of the audio file, in seconds.
bitDepth integer | null
Bit depth of the audio file.
sampleRate integer | null
Sample rate of the audio file, in Hz.
bitrate integer | null
Bitrate of the audio file.
channels integer | null
Number of audio channels.
size integer | null
File size, in bytes.
artistId * integer
ID of the contributing artist.
roleId * integer
Contributor role ID.
composerId integer
ID of the composer.
roleId integer
Publishing role ID for the composer.
rightsId integer
Publishing type for this composer credit: 1 (copyright control / self-published), 2 (published, managed by a publisher), or 3 (public domain).
Examples: 1, 2, 3
publisherId integer | null
ID of the publisher associated with this composer credit. Always set when rightsId is 2; null otherwise.
share number | null
Share percentage for the composer. Either all composers on the track carry a share summing to 100, or all are null.
iswc string | null
International Standard Musical Work Code (ISWC) for the underlying composition.
languageId * integer
Language ID for this localization entry.
name * string
Track title in the specified language.
version string | null
Version subtitle in the specified language.
phoneticName string | null
Phonetic pronunciation of the title in the specified language.
phoneticVersion string | null
Phonetic pronunciation of the version in the specified language.
languageAndScriptCode string | null
Language and script code for this entry's phonetic name/version, not the localized title.
fileId string
File ID of the audio file that was scanned.
acrId string | null
ACRCloud's identifier for this scan. null until the scan completes.
status AcrCloudScanStatus
Scan status.
Examples: inProcessing, complete, error
creationDate string (date-time)
UTC timestamp when the scan record was created.
timestampUtc string (date-time) | null
UTC timestamp reported by ACRCloud for the scan result. null until the scan completes.
musicDetected integer | null
Amount of music detected by the scan.
duration integer | null
Duration analyzed by the scan, in seconds.
error string | null
Error message if the scan failed. null on success.
isrc string | null
ISRC reported by the scan for the matched recording. null if the scan produced no match.
scans object[] | null
Individual fingerprint scan passes run against the file.
coverSongs object[] | null
Cover-song matches detected by the scan.
derivativeWorks object[] | null
Derivative-work matches detected by the scan.
speechDetection object[] | null
Speech segments detected in the file.
aiDetection object[] | null
AI-generated-content detection results for the file.
creationDate string (date-time) | null
UTC timestamp when the track was created.
createdBy string | null
ID of the user who created the track.
lastUpdateDate string (date-time) | null
UTC timestamp of the most recent update.
lastUpdatedBy string | null
ID of the user who last updated the track.
archivedAt string (date-time) | null
UTC timestamp when the track was archived. null if the track is active.
archivedBy string | null
ID of the user who archived the track. null if the track is active.
lockLevel AssetLockLevels
Edit permission level for this track. See the Track Locking section above.
Examples: unlocked, partiallyLocked, fullyLocked
isDolbyAtmosReadOnly boolean
Set to true when a release this track appears on has a live Dolby Atmos package on a store. While true, the Dolby Atmos recording version cannot be added, removed, or altered. See the Dolby Atmos Read-Only section above.
PUT /catalog/v1/tracks/{trackId} 
curl -X PUT "https://platform.revelator.com/catalog/v1/tracks/7701" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "name": "Night Lights",
  "version": "Remastered",
  "artistId": 4402,
  "audioLanguageId": 1,
  "metadataLanguageId": 1,
  "primaryMusicStyleId": 17,
  "copyrightP": "2024 Northline Records",
  "recordingType": "original",
  "parentalAdvisory": "notExplicit",
  "recordingProperties": ["none"],
  "recordingVersions": [
    {
      "isrc": "QZ8AB2400011",
      "recordingVersionType": "stereo",
      "files": [
        { "fileId": "d12fd57a-e739-44fd-9246-31f50d4ee5f6", "format": "wav" }
      ]
    }
  ],
  "contributors": [],
  "composers": [
    { "composerId": 6601, "roleId": 2, "rightsId": 2, "publisherId": 3301, "share": 100 }
  ],
  "compositions": [],
  "locals": []
}'
Example response 200 
{
"trackId": 7701,
"assetId": 4419835,
"tenantId": 2001,
"enterpriseId": 3001,
"name": "Night Lights",
"version": "Remastered",
"phoneticName": null,
"phoneticVersion": null,
"languageAndScriptCode": null,
"artistId": 4402,
"metadataLanguageId": 1,
"audioLanguageId": 1,
"primaryMusicStyleId": 17,
"secondaryMusicStyleId": null,
"copyrightP": "2024 Northline Records",
"trackVendorId": null,
"youTubeVideoId": null,
"youTubeCIDAssetId": null,
"lyrics": null,
"previewStartSeconds": null,
"recordingType": "original",
"parentalAdvisory": "notExplicit",
"recordingProperties": ["none"],
"posterImageId": null,
"recordingVersions": [
  {
    "isrc": "QZ8AB2400011",
    "recordingVersionType": "stereo",
    "files": [
      {
        "fileId": "d12fd57a-e739-44fd-9246-31f50d4ee5f6",
        "format": "wav",
        "filename": "night-lights.wav",
        "duration": 223,
        "bitDepth": 24,
        "sampleRate": 48000,
        "bitrate": 2304000,
        "channels": 2,
        "size": 42102300
      }
    ]
  }
],
"contributors": [],
"composers": [
  { "composerId": 6601, "roleId": 2, "rightsId": 2, "publisherId": 3301, "share": 100 }
],
"compositions": [],
"locals": [],
"acrCloud": null,
"creationDate": "2024-05-01T11:45:00Z",
"createdBy": "b3f1a2c4-1111-4e5f-a678-426614174000",
"lastUpdateDate": "2024-05-15T08:30:00Z",
"lastUpdatedBy": "b3f1a2c4-1111-4e5f-a678-426614174000",
"archivedAt": null,
"archivedBy": null,
"isDolbyAtmosReadOnly": false,
"lockLevel": "unlocked"
}

List Track Contributors

GET /catalog/v1/tracks/{trackId}/contributors

Retrieves the full artist records for every contributing artist credited on the track.

Path Parameters

Parameter Description
trackId * integer

The ID of the track.

Responses

object[]
artistId integer
Unique identifier for the artist.
name string | null
Artist display name (stage name or act name).
firstName string | null
Legal first name of the artist.
middleName string | null
Legal middle name of the artist.
lastName string | null
Legal last name of the artist.
logoImageId string | null
File ID of the artist's profile image.
tenantId integer
ID of the organization that owns this artist.
enterpriseId integer
ID of the client that owns this artist.
enterpriseName string | null
Name of the client.
hasPortal boolean
Whether this artist has an associated artist portal account.
isni string | null
International Standard Name Identifier for the artist.
languageAndScriptCode string | null
Language and script code for the artist name.
creationDate string (date-time)
UTC timestamp when the artist was created.
lastUpdateDate string (date-time)
UTC timestamp of the most recent update.
archivedAt string (date-time) | null
UTC timestamp when the artist was archived. null if the artist is active.
profileId string | null
The artist's profile ID on the external platform.
distributorStoreId integer | null
Identifies the distributor store. Use the lookup endpoints to resolve store names.
musicStyleIds integer[] | null
Primary music style IDs associated with this artist.
GET /catalog/v1/tracks/{trackId}/contributors 
curl -X GET "https://platform.revelator.com/catalog/v1/tracks/7701/contributors" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Example response 200 
[
{
  "artistId": 4410,
  "name": "DJ Prism",
  "firstName": null,
  "middleName": null,
  "lastName": null,
  "logoImageId": null,
  "tenantId": 2001,
  "enterpriseId": 3001,
  "enterpriseName": "Client Name",
  "hasPortal": false,
  "isni": null,
  "creationDate": "2023-11-01T09:00:00Z",
  "lastUpdateDate": "2024-03-10T14:20:00Z",
  "archivedAt": null,
  "externalIds": [
    { "profileId": "5NHQUkpP4tlGGBDNhrE7xx", "distributorStoreId": 9 }
  ],
  "musicStyleIds": [17]
}
]

List Track Composers

GET /catalog/v1/tracks/{trackId}/composers

Retrieves the full composer records for every composer credited on the track.

Path Parameters

Parameter Description
trackId * integer

The ID of the track.

Responses

object[]
composerId integer
Unique identifier for the composer.
tenantId integer
ID of the organization that owns this composer.
enterpriseId integer
ID of the client that owns this composer.
name string | null
Composer's full legal name.
logoImageId string | null
File ID of the composer's photo or logo image.
isni string | null
International Standard Name Identifier (ISNI) for the composer.
ipiCae string | null
IPI or CAE number for the composer.
countryOfResidenceId integer | null
The country in which this composer officially resides.
creationDate string (date-time)
UTC timestamp when the composer was created.
createdBy string | null
ID of the user who created the composer.
lastUpdateDate string (date-time) | null
UTC timestamp of the most recent update. null if the composer has never been updated.
lastUpdatedBy string | null
ID of the user who last updated the composer. null if the composer has never been updated.
archivedAt string (date-time) | null
UTC timestamp when the composer was archived. null if the composer is active.
archivedBy string | null
ID of the user who archived the composer. null if the composer is active.
roleId integer
Contributor role ID.
name string | null
Contributor role name.
GET /catalog/v1/tracks/{trackId}/composers 
curl -X GET "https://platform.revelator.com/catalog/v1/tracks/7701/composers" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Example response 200 
[
{
  "composerId": 6601,
  "tenantId": 2001,
  "enterpriseId": 3001,
  "name": "Example Composer",
  "logoImageId": "a1b2c3d4-0000-4e5f-a678-426614174000",
  "isni": "123456789098765X",
  "ipiCae": "00000001111",
  "countryOfResidenceId": 244,
  "roles": [
    { "roleId": 2, "name": "Composer" }
  ],
  "creationDate": "2026-01-10T12:03:43Z",
  "createdBy": "b3f1a2c4-1111-4e5f-a678-426614174000",
  "lastUpdateDate": "2026-02-01T08:20:10Z",
  "lastUpdatedBy": "b3f1a2c4-1111-4e5f-a678-426614174000",
  "archivedAt": null,
  "archivedBy": null
}
]

List Track Publishers

GET /catalog/v1/tracks/{trackId}/publishers

Retrieves the full publisher records for every publisher associated with the track's composer credits.

Path Parameters

Parameter Description
trackId * integer

The ID of the track.

Responses

object[]
publisherId integer
Unique identifier for the publisher.
tenantId integer
ID of the organization that owns this publisher.
enterpriseId integer
ID of the client that owns this publisher.
name string | null
Full name of the publisher.
logoImageId string | null
File ID of the publisher's logo image.
ipiCae string | null
IPI or CAE number for the publisher.
countryId integer | null
Country where this publisher administers publishing rights and collects royalties.
creationDate string (date-time)
UTC timestamp when the publisher was created.
lastUpdateDate string (date-time) | null
UTC timestamp of the most recent update. null if the publisher has never been updated.
archivedAt string (date-time) | null
UTC timestamp when the publisher was archived. null if the publisher is active.
archivedBy string | null
ID of the user who archived the publisher. null if the publisher is active.
GET /catalog/v1/tracks/{trackId}/publishers 
curl -X GET "https://platform.revelator.com/catalog/v1/tracks/7701/publishers" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Example response 200 
[
{
  "publisherId": 3301,
  "tenantId": 2001,
  "enterpriseId": 3001,
  "name": "Example Publisher",
  "logoImageId": "a1b2c3d4-0000-4e5f-a678-426614174000",
  "ipiCae": "00000000111",
  "countryId": 875,
  "creationDate": "2026-01-10T12:03:43Z",
  "lastUpdateDate": "2026-02-01T08:20:10Z",
  "archivedAt": null,
  "archivedBy": null
}
]

Archive Tracks

POST /catalog/v1/tracks/archive

Archives tracks in batch by their universal asset IDs.

Request Body *

object
Batch archive request payload.
assetIds * integer[]
List of track asset IDs to archive. Maximum 100 IDs per request.

Responses

object
id integer
Track asset ID from the request.
succeeded boolean
Whether the archive operation succeeded for this track.
code string
Error code.
message string
Human-readable error message.
POST /catalog/v1/tracks/archive 
curl -X POST "https://platform.revelator.com/catalog/v1/tracks/archive" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "assetIds": [4419835, 4419836]
}'
Example response 200 
{
"results": [
  {
    "id": 4419835,
    "succeeded": true,
    "errors": null
  },
  {
    "id": 4419836,
    "succeeded": true,
    "errors": null
  }
]
}

Unarchive Tracks

POST /catalog/v1/tracks/unarchive

Unarchives tracks in batch by their universal asset IDs.

Request Body *

object
Batch unarchive request payload.
assetIds * integer[]
List of track asset IDs to unarchive. Maximum 100 IDs per request.

Responses

object
id integer
Track asset ID from the request.
succeeded boolean
Whether the unarchive operation succeeded for this track.
code string
Error code.
message string
Human-readable error message.
POST /catalog/v1/tracks/unarchive 
curl -X POST "https://platform.revelator.com/catalog/v1/tracks/unarchive" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "assetIds": [4419835, 4419836]
}'
Example response 200 
{
"results": [
  {
    "id": 4419835,
    "succeeded": true,
    "errors": null
  },
  {
    "id": 4419836,
    "succeeded": true,
    "errors": null
  }
]
}