Videos
A video is an individual video recording—an official music video, a performance capture, a lyric video, and so on. Videos are catalog assets in their own right: they carry their own metadata, credits, and rights, and they are distributed by assigning them to a release, exactly like tracks.
Video Type & Tags
videoType classifies the recording and is required:
| Value | Description |
|---|---|
officialVideo | The official music video released alongside the recording. |
performance | A performance capture—live, session, or studio. |
other | Anything else, such as lyric videos, visualizers, and remix videos. |
tags further describes the video and accepts any combination of officialMusicVideo, remix, lyric, live,
nonStandard, soundtrack, vertical, visualizer, and closedCaptioned.
When videoType is officialVideo, the tags array must include officialMusicVideo. For performance and other,
tags are optional.
Recording Versions
The recordingVersions array holds the video itself. Unlike tracks, a video has only one version type—standard—so the
array should contain at most one entry, whose files array holds a single video file.
The fileId is the uploadId returned by the Files API, and format must be mp4 or mov.
Technical properties (duration, bitDepth, sampleRate, bitrate, size, channels) are extracted from the file
during processing and should not be supplied by the caller.
A video file belongs to exactly one video. Referencing a file that another video already uses fails with “One or more
video file IDs are already assigned to a different video.”, and referencing a fileId that was never uploaded fails
with “One or more video files were not found.” Detaching a file—by updating the video without it—releases it for use
elsewhere.
The isrc for a version can be left null to have one generated automatically during distribution. You should never
generate a new ISRC for a video that already has one.
Video File Requirements
Uploads are validated when you call POST /files/v1/uploads/complete, not when the
session is created—so a file that fails these checks is rejected only after its bytes have been transferred.
| Requirement | Rule |
|---|---|
| Container | MP4 or MOV. Upload with content type video/mp4, video/quicktime, or video/mov. |
| Video codec | MP4 must carry H.264 or HEVC. MOV must carry ProRes. |
| Minimum resolution | 1280 × 720 (HD). |
| Minimum audio bitrate | 256,000 bps, when the file has an audio stream. |
| Minimum sample rate | 48,000 Hz, when the file has an audio stream. |
| Maximum file size | 30 GB. |
A file that violates one of these returns a 400 from Complete Upload.Files without an audio stream skip the audio
checks entirely.
Once a video file is accepted, it is transcoded asynchronously into a streamable MP4 rendition, regardless of the source
container. Renditions appear in the video’s encodedVideos array, and GET /catalog/v1/video-files/{videoFileId}/encoded-versions returns them for a source file directly.
Transcoding is tied to the file, not the video, and may still be in progress when you first retrieve the video. If
encodedVideos is empty, the encoding process may not have finished yet. Poll the video or the encoded-versions
endpoint when you need to wait for a rendition to become available.
Poster Images
A video carries two independent poster slots, both optional and both holding a fileId uploaded with the PosterImage
purpose:
framePosterImageId— a still lifted from the video itself. Required for distribution.customPosterImageId— artwork designed separately for the video. Optional.
The two are not interchangeable. framePosterImageId is the required distribution thumbnail, while
customPosterImageId is optional and may be supported differently by destinations.
Neither poster is generated for you. Poster images must be JPEG or PNG (PNG is converted to JPEG on upload, so the
stored file becomes image/jpeg with a .jpg extension), no larger than 10 MB, at least 1280 × 720, and within 2% of a
16:9 aspect ratio. A square image is rejected with “Poster image resolution 1400x1400 does not match the required 16:9
aspect ratio. Please upload a 16:9 image.”
Captions
Captions are uploaded with the VideoCaption purpose and attached through the captions array. Each entry requires a
fileId, the original fileName, and a languageId.
Supported formats are SCC (text/scc) and TTML (application/ttml+xml), both UTF-8 encoded only, up to 5 MB
per file. Apple Music expects SCC at 29.97 fps with a timecode format matching the source video.
Linked Audio Track
linkedTrackId links the video to an existing audio asset, associating streaming and royalty data across the two
formats so the same recording can be reconciled wherever it appears.
It is optional at the catalog level. Some destinations may require the link for distribution; for example, Spotify requires it for official music videos. See Validations. For managing the audio side, see Tracks.
Parental Advisory & Age Restriction
Two independent required fields describe advisory status. parentalAdvisory describes the content itself:
| Value | Meaning |
|---|---|
notExplicit | No explicit content, and not an edited version of an explicit original. |
clean | An edited version of an explicit original, with explicit language or visuals removed. The explicit version must exist and be linked. |
explicit | Contains explicit lyrics, language, or visuals. |
isAgeRestricted is a separate boolean marking the video as 18+. Set it to true when the video prominently features
any of the following in a prolonged or intense manner:
- Graphic, shocking, or violent content
- Sexual content or nudity
- Substance use, misuse, or abuse
- Suicide or self-harm, including disordered eating
- Repeated or prolonged visual profanity
The two fields are independent: a video can be notExplicit and still be age restricted, or explicit without being.
Ensure these are accurately identified. Misidentifying explicit content can result in your distribution being disabled.
Video Locking
A video inherits the most restrictive lockLevel across the releases it appears on:
fullyLockedif any of its releases is fully locked.- Otherwise,
partiallyLockedif any of its releases is partially locked. - Otherwise,
unlocked.
See the Lock Levels section on the Releases page for what makes a release partially or fully locked.
Distributing a Video
A video is distributed by assigning it to a release. Add its assetId (not its videoId) to the release’s assets
array with assetType set to video:
{
"assets": [{ "assetId": 4419901, "assetType": "video" }]
}Videos and tracks can be mixed within the same assets array, and the array order determines the running order
delivered to DSPs. See Create Release for the full release payload.
To check this video on its own—before it joins a release, or while you are still working on it—call GET /supply-chain/v1/videos/{videoId}/validate. It checks the video’s own metadata without release context. To validate the video as part of a release, including requirements that depend on the release or its asset relationships, use GET /supply-chain/v1/releases/{releaseId}/deliver/validate. See Validations.
Archiving Videos
A video can be archived only when it is not associated with any active (unarchived) release.
Before archiving a video, all associated releases must therefore be either:
- Unlinked from the video, or
- Taken down from all stores and archived.
Data Deletion Warning: Six months after a video is archived, its video files are permanently deleted. You will receive an email notification two weeks before deletion.
Deleted video files cannot be restored, and the track cannot be unarchived after deletion. Archived tracks cannot be edited.
Create Video
POST
/catalog/v1/videos Creates a new video asset.
Request Body *
object enterpriseId integer The client under which the video will be created. Defaults to the caller's client when using client permissions. Required when using organization permissions.
name * string Title of the video. Do not include additional information such as "Live" or "Remix"—use
version instead. version string Version of the video (e.g., "Live", "Remix", "Extended Cut").
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 video's phonetic name/version (
phoneticName/phoneticVersion), not the main title (e.g., ja-Latn). Available values can be retrieved from GET /common/lookup/languageAndScriptCodes on the V1.0 API. Each code is paired with a specific language in that lookup—supply a code that matches the audioLanguageId you set on the video. framePosterImageId string File ID (GUID) of a poster image taken as a still from the video, uploaded via the Files API with the
PosterImage purpose. Required for distribution—this is the thumbnail DSPs receive. See the Poster Images section above for the resolution and aspect ratio rules. customPosterImageId string File ID (GUID) of a poster image designed separately from the video, uploaded via the Files API with the
PosterImage purpose. Optional—it is delivered, but not every DSP accepts it, so it does not substitute for framePosterImageId. See the Poster Images section above for the resolution and aspect ratio rules. 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.
videoType * VideoTypes Classification of the video. See the Video Type & Tags section above.
Examples:
officialVideo, performance, other recordingType * RecordingTypes Origin of the recording. See Track Origin & Track Properties for details.
Examples:
original, cover, publicDomain, undeclared parentalAdvisory * ParentalAdvisories Advisory label for the video content. See the Parental Advisory & Age Restriction section above.
Examples:
notExplicit, clean, explicit isAgeRestricted * boolean Whether the video is restricted to adult viewers. Independent of
parentalAdvisory. recordingProperties * TrackPropertyType[] Additional properties describing the recording. At least one entry is required—use
none when no property applies. See Track Origin & Track Properties for details. Examples:
none, remix, sampleStock, mixCompilation, altVersion, specialGenre, nonMusic, ai, noise, undeclared artistId * integer ID of an existing artist to assign as the primary artist for the video. Apple Music does not allow the artist name or artist ID to change after the first submission, so confirm both are correct before saving.
primaryMusicStyleId integer Primary genre/music style ID for the video. Retrieved from GET /common/lookup/musicstyles on the V1.0 API.
secondaryMusicStyleId integer Secondary genre/music style ID for the video. Retrieved from GET /common/lookup/musicstyles on the V1.0 API.
catalog string Internal catalog reference number for the video.
copyrightP string Sound recording copyright (℗) for the video. Format:
[Year] [Rights Holder] (e.g., "2026 Acme Inc."). copyrightC string Composition/artwork copyright (©) for the video. Format:
[Year] [Rights Holder] (e.g., "2026 Acme Inc."). metadataLanguageId * integer Language the video'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 performance—what is sung or spoken in the video. Retrieved from GET /common/lookup/languages on the V1.0 API. Not required to save the video, but required for distribution.
linkedTrackId integer ID of an existing audio asset to link this video to, associating streaming and royalty data across formats. See the Linked Audio Track section above.
locals VideoLocalRequest[] Localized title and version strings for additional metadata languages.
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 Video 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. Retrieved from GET /common/lookup/languageAndScriptCodes on the V1.0 API.
recordingVersions VideoRecordingItemModel[] The video recording. Provide at most one entry. See the Recording Versions section above.
isrc string ISRC code for this recording version. Leave
null to have one generated automatically during distribution. recordingVersionType * VideoRecordingVersionTypes Type of recording version. Videos support a single type.
Example:
standard files VideoFileModel[] Video files for this recording version. Provide a single file.
fileId * string File ID (GUID) of the previously uploaded video file, generated by the Files API. A file can be attached to only one video.
format * VideoFileFormats Video container format.
Examples:
mp4, mov filename string Name of the uploaded file, including the extension. Derived from the upload.
duration integer Duration of the video, in seconds. Computed automatically after processing.
bitDepth integer Audio bit depth of the embedded audio stream. Computed automatically after processing.
sampleRate integer Audio sample rate, in Hz. Computed automatically after processing.
bitrate integer Audio bitrate, in bps. Computed automatically after processing.
resolution string Video resolution label. Populated on encoded renditions rather than on the source file.
frameRate number Frames per second. Populated on encoded renditions rather than on the source file.
size integer File size, in bytes. Computed automatically after processing.
channels integer Number of audio channels. Computed automatically after processing.
tags VideoTags[] Descriptive tags for the video. Must include
officialMusicVideo when videoType is officialVideo; otherwise optional. Examples:
officialMusicVideo, remix, lyric, live, nonStandard, soundtrack, vertical, visualizer, closedCaptioned captions VideoCaptionRequest[] Caption files for the video. See the Captions section above.
videoCaptionId integer ID of an existing caption entry. Omit when adding a new caption.
languageId * integer Language of the caption file. Retrieved from GET /common/lookup/languages on the V1.0 API.
fileId * string File ID (GUID) of the uploaded caption file, generated by the Files API using the
VideoCaption purpose. fileName * string Original caption file name, including the extension (e.g.,
captions.scc). contributors ContributorItemModel[] Contributing artists credited on this video (e.g., Featuring, Remixer, Producer).
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.
composers ComposerItemModel[] Publishing contributors (composers) for this video. Mirrors the track model—see Track Composers & Publishing Splits.
composerId integer ID of an existing composer to credit on this video.
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. Only relevant when
rightsId is 2. share number Optional share percentage for the composer. Shares must be either omitted on every composer or supplied on every composer summing to exactly 100—any other combination is rejected. Shares do not affect royalty payments.
compositions CompositionItemModel[] The underlying musical work(s) this video represents.
iswc string International Standard Musical Work Code (ISWC) for the underlying composition. Format:
T followed by 10 digits (e.g., T1234567890). ISWCs are issued by your national or regional ISWC agency, usually through your local copyright or performing rights organisation—once a work is registered there you receive an ISWC for each composition.Responses
object videoId integer Unique identifier for the video.
assetId integer Universal asset ID for this video, used when assigning it to a release and in archive, unarchive, and rights operations.
name string | null Title of the video.
version string | null Version of the video.
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 video's phonetic name/version, not the main title.
framePosterImageId string | null File ID of a poster image taken as a still from the video. Required for distribution.
customPosterImageId string | null File ID of a poster image designed separately from the video. Optional.
previewStartSeconds integer | null Preview/clip start time, in seconds. If omitted or set to null, the preview clip start time defaults to whatever value the DSP uses.
videoType VideoTypes Classification of the video.
Examples:
officialVideo, performance, other recordingType RecordingTypes Origin of the recording.
Examples:
original, cover, publicDomain, undeclared parentalAdvisory ParentalAdvisories Advisory label for the video content.
Examples:
notExplicit, clean, explicit catalog string | null Internal catalog reference number for the video.
copyrightP string | null Sound recording copyright (℗) for the video.
copyrightC string | null Composition/artwork copyright (©) for the video.
metadataLanguageId integer | null Language the video's title and other text fields are written in.
audioLanguageId integer | null Language of the performance—what is sung or spoken in the video.
artistId integer | null ID of the primary artist credited on the video.
primaryMusicStyleId integer | null Primary genre/music style ID for the video.
secondaryMusicStyleId integer | null Secondary genre/music style ID for the video.
linkedTrackId integer | null ID of the audio track this video presents.
null if the video is not linked to a track. tenantId integer ID of the organization that owns this video.
enterpriseId integer ID of the client that owns this video.
creationDate string (date-time) | null UTC timestamp when the video was created.
lastUpdateDate string (date-time) | null UTC timestamp of the most recent update.
archivedAt string (date-time) | null UTC timestamp when the video was archived.
null if the video is active. locals VideoLocalItemModel[] | null Localized title and version strings.
languageId integer Language ID for this localization entry.
name string | null Video 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.
creationDate string (date-time) | null UTC timestamp when the localization entry was created.
createdBy string | null ID of the user who created the localization entry.
recordingVersions VideoRecordingItemModel[] | null The video recording and its source file.
isrc string | null ISRC code for this recording version.
recordingVersionType VideoRecordingVersionTypes Type of recording version.
Example:
standard files VideoFileModel[] The source video file.
fileId string File ID of the uploaded video file.
format VideoFileFormats Video container format.
Examples:
mp4, mov filename string | null Name of the uploaded file, including the extension.
duration integer | null Duration of the video, in seconds.
bitDepth integer | null Audio bit depth of the embedded audio stream.
sampleRate integer | null Audio sample rate, in Hz.
bitrate integer | null Audio bitrate, in bps.
resolution string | null Video resolution label (e.g.,
1080p), extracted from the file during processing. frameRate number Frames per second, extracted from the file during processing.
size integer | null File size, in bytes.
channels integer | null Number of audio channels.
tags VideoTags[] | null Descriptive tags for the video.
isAgeRestricted boolean Whether the video is restricted to adult viewers.
recordingProperties TrackPropertyType[] | null Additional properties describing the recording.
captions VideoCaptionItemModel[] | null Caption files attached to this video.
videoCaptionId integer Unique identifier for this caption entry.
languageId integer Language of the caption file.
fileId string File ID of the uploaded caption file.
fileName string | null Original caption file name, including the extension.
creationDate string (date-time) | null UTC timestamp when the caption was attached.
createdBy string | null ID of the user who attached the caption.
encodedVideos VideoFileModel[] | null Streamable renditions generated from the source video file. Transcoding runs asynchronously, so this is always empty in the create response and fills in shortly afterwards. Poll Get Video or the encoded-versions endpoint to pick it up.
fileId string File ID of the source video file this rendition was generated from.
format VideoFileFormats Container format of the rendition. Always
mp4, regardless of the source container. filename string | null Generated file name of the rendition.
duration integer | null Duration of the rendition, in seconds.
bitDepth integer | null Audio bit depth of the rendition.
sampleRate integer | null Audio sample rate of the rendition, in Hz.
bitrate integer | null Bitrate of the rendition.
resolution string | null Resolution label of the rendition (e.g.,
1080p). frameRate number Frames per second of the rendition.
size integer | null Size of the rendition, in bytes.
channels integer | null Number of audio channels in the rendition.
contributors ContributorItemModel[] | null Contributing artists credited on this video. Use List Video Contributors to resolve the full artist records.
artistId * integer ID of the contributing artist.
roleId * integer Contributor role ID.
composers ComposerItemModel[] | null Publishing contributors (composers) for this video. Use List Video Composers to resolve the full composer records.
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 video carry a share summing to 100, or all are
null. compositions CompositionItemModel[] | null The underlying musical work(s) this video represents.
iswc string | null International Standard Musical Work Code (ISWC) for the underlying composition.
acrCloud AcrCloudModel Automatic Content Recognition (ACR) scan results for this video's audio, used for fingerprinting and rights matching. Populated automatically once the file has been processed;
null if no scan has run yet. fileId string File ID of the video 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 video. See the Video Locking section above for details.
Examples:
unlocked, partiallyLocked, fullyLocked POST
/catalog/v1/videos curl -X POST "https://platform.revelator.com/catalog/v1/videos" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Night Lights",
"version": "Official Video",
"videoType": "officialVideo",
"tags": ["officialMusicVideo", "closedCaptioned"],
"recordingType": "original",
"recordingProperties": ["none"],
"parentalAdvisory": "notExplicit",
"isAgeRestricted": false,
"artistId": 4402,
"primaryMusicStyleId": 17,
"metadataLanguageId": 1,
"audioLanguageId": 1,
"catalog": "NR-2026-014",
"copyrightP": "2026 Northline Records",
"copyrightC": "2026 Northline Records",
"linkedTrackId": 7701,
"previewStartSeconds": 10,
"customPosterImageId": "3b7e9a1c-4d5f-4a2b-8c6e-1d0f2a4b6c88",
"recordingVersions": [
{
"isrc": "QZ8AB2600011",
"recordingVersionType": "standard",
"files": [
{ "fileId": "8f3c1d2e-5a7b-4c9d-b0e1-2f4a6c8d0e13", "format": "mp4" }
]
}
],
"captions": [
{
"languageId": 1,
"fileId": "c5a1e703-9b24-4f68-a1d7-83e5f0b2c419",
"fileName": "night-lights.scc"
}
],
"contributors": [
{ "artistId": 4410, "roleId": 5 }
],
"composers": [
{ "composerId": 6601, "roleId": 2, "rightsId": 2, "publisherId": 3301, "share": 100 }
],
"compositions": [],
"locals": []
}'curl -X POST "https://platform.revelator.com/catalog/v1/videos" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Night Lights",
"version": "Official Video",
"videoType": "officialVideo",
"tags": ["officialMusicVideo", "closedCaptioned"],
"recordingType": "original",
"recordingProperties": ["none"],
"parentalAdvisory": "notExplicit",
"isAgeRestricted": false,
"artistId": 4402,
"primaryMusicStyleId": 17,
"metadataLanguageId": 1,
"audioLanguageId": 1,
"catalog": "NR-2026-014",
"copyrightP": "2026 Northline Records",
"copyrightC": "2026 Northline Records",
"linkedTrackId": 7701,
"previewStartSeconds": 10,
"customPosterImageId": "3b7e9a1c-4d5f-4a2b-8c6e-1d0f2a4b6c88",
"recordingVersions": [
{
"isrc": "QZ8AB2600011",
"recordingVersionType": "standard",
"files": [
{ "fileId": "8f3c1d2e-5a7b-4c9d-b0e1-2f4a6c8d0e13", "format": "mp4" }
]
}
],
"captions": [
{
"languageId": 1,
"fileId": "c5a1e703-9b24-4f68-a1d7-83e5f0b2c419",
"fileName": "night-lights.scc"
}
],
"contributors": [
{ "artistId": 4410, "roleId": 5 }
],
"composers": [
{ "composerId": 6601, "roleId": 2, "rightsId": 2, "publisherId": 3301, "share": 100 }
],
"compositions": [],
"locals": []
}' Example response 200
{
"videoId": 4501,
"assetId": 4419901,
"name": "Night Lights",
"version": "Official Video",
"phoneticName": null,
"phoneticVersion": null,
"languageAndScriptCode": null,
"framePosterImageId": null,
"customPosterImageId": "3b7e9a1c-4d5f-4a2b-8c6e-1d0f2a4b6c88",
"previewStartSeconds": 10,
"videoType": "officialVideo",
"recordingType": "original",
"parentalAdvisory": "notExplicit",
"catalog": "NR-2026-014",
"copyrightP": "2026 Northline Records",
"copyrightC": "2026 Northline Records",
"metadataLanguageId": 1,
"audioLanguageId": 1,
"artistId": 4402,
"primaryMusicStyleId": 17,
"secondaryMusicStyleId": null,
"linkedTrackId": 7701,
"tenantId": 2001,
"enterpriseId": 3001,
"creationDate": "2026-08-11T09:11:47.334Z",
"lastUpdateDate": "2026-08-11T09:11:47.334Z",
"archivedAt": null,
"locals": [],
"recordingVersions": [
{
"isrc": "QZ8AB2600011",
"recordingVersionType": "standard",
"files": [
{
"fileId": "8f3c1d2e-5a7b-4c9d-b0e1-2f4a6c8d0e13",
"format": "mp4",
"filename": "night-lights.mp4",
"duration": 30,
"bitDepth": null,
"sampleRate": 48000,
"bitrate": 256000,
"resolution": null,
"frameRate": 0,
"size": 17839845,
"channels": 2
}
]
}
],
"tags": ["officialMusicVideo", "closedCaptioned"],
"isAgeRestricted": false,
"recordingProperties": ["none"],
"captions": [
{
"videoCaptionId": 184,
"languageId": 1,
"fileId": "c5a1e703-9b24-4f68-a1d7-83e5f0b2c419",
"fileName": "night-lights.scc",
"creationDate": "2026-08-11T09:11:47.373Z",
"createdBy": "b3f1a2c4-1111-4e5f-a678-426614174000"
}
],
"encodedVideos": [],
"contributors": [
{ "artistId": 4410, "roleId": 5 }
],
"composers": [
{ "composerId": 6601, "roleId": 2, "rightsId": 2, "publisherId": 3301, "share": 100 }
],
"compositions": [],
"acrCloud": null,
"lockLevel": "unlocked"
}{
"videoId": 4501,
"assetId": 4419901,
"name": "Night Lights",
"version": "Official Video",
"phoneticName": null,
"phoneticVersion": null,
"languageAndScriptCode": null,
"framePosterImageId": null,
"customPosterImageId": "3b7e9a1c-4d5f-4a2b-8c6e-1d0f2a4b6c88",
"previewStartSeconds": 10,
"videoType": "officialVideo",
"recordingType": "original",
"parentalAdvisory": "notExplicit",
"catalog": "NR-2026-014",
"copyrightP": "2026 Northline Records",
"copyrightC": "2026 Northline Records",
"metadataLanguageId": 1,
"audioLanguageId": 1,
"artistId": 4402,
"primaryMusicStyleId": 17,
"secondaryMusicStyleId": null,
"linkedTrackId": 7701,
"tenantId": 2001,
"enterpriseId": 3001,
"creationDate": "2026-08-11T09:11:47.334Z",
"lastUpdateDate": "2026-08-11T09:11:47.334Z",
"archivedAt": null,
"locals": [],
"recordingVersions": [
{
"isrc": "QZ8AB2600011",
"recordingVersionType": "standard",
"files": [
{
"fileId": "8f3c1d2e-5a7b-4c9d-b0e1-2f4a6c8d0e13",
"format": "mp4",
"filename": "night-lights.mp4",
"duration": 30,
"bitDepth": null,
"sampleRate": 48000,
"bitrate": 256000,
"resolution": null,
"frameRate": 0,
"size": 17839845,
"channels": 2
}
]
}
],
"tags": ["officialMusicVideo", "closedCaptioned"],
"isAgeRestricted": false,
"recordingProperties": ["none"],
"captions": [
{
"videoCaptionId": 184,
"languageId": 1,
"fileId": "c5a1e703-9b24-4f68-a1d7-83e5f0b2c419",
"fileName": "night-lights.scc",
"creationDate": "2026-08-11T09:11:47.373Z",
"createdBy": "b3f1a2c4-1111-4e5f-a678-426614174000"
}
],
"encodedVideos": [],
"contributors": [
{ "artistId": 4410, "roleId": 5 }
],
"composers": [
{ "composerId": 6601, "roleId": 2, "rightsId": 2, "publisherId": 3301, "share": 100 }
],
"compositions": [],
"acrCloud": null,
"lockLevel": "unlocked"
}Get Video
Also available by asset ID. GET /catalog/v1/assets/videos/{assetId} returns this exact payload, keyed by the
video’s assetId instead of its videoId. See
Understanding Assets & IDs.
GET
/catalog/v1/videos/{videoId} Retrieves a single video by its ID.
Path Parameters
| Parameter | Description |
|---|---|
videoId * integer | The ID of the video to retrieve. |
Responses
object videoId integer Unique identifier for the video.
assetId integer Universal asset ID for this video, used when assigning it to a release and in archive, unarchive, and rights operations.
name string | null Title of the video.
version string | null Version of the video.
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 video's phonetic name/version, not the main title.
framePosterImageId string | null File ID of a poster image taken as a still from the video. Required for distribution.
customPosterImageId string | null File ID of a poster image designed separately from the video. Optional.
previewStartSeconds integer | null Preview/clip start time, in seconds. If omitted or set to null, the preview clip start time defaults to whatever value the DSP uses.
videoType VideoTypes Classification of the video.
Examples:
officialVideo, performance, other recordingType RecordingTypes Origin of the recording.
Examples:
original, cover, publicDomain, undeclared parentalAdvisory ParentalAdvisories Advisory label for the video content.
Examples:
notExplicit, clean, explicit catalog string | null Internal catalog reference number for the video.
copyrightP string | null Sound recording copyright (℗) for the video.
copyrightC string | null Composition/artwork copyright (©) for the video.
metadataLanguageId integer | null Language the video's title and other text fields are written in.
audioLanguageId integer | null Language of the performance—what is sung or spoken in the video.
artistId integer | null ID of the primary artist credited on the video.
primaryMusicStyleId integer | null Primary genre/music style ID for the video.
secondaryMusicStyleId integer | null Secondary genre/music style ID for the video.
linkedTrackId integer | null ID of the audio track this video presents.
null if the video is not linked to a track. tenantId integer ID of the organization that owns this video.
enterpriseId integer ID of the client that owns this video.
creationDate string (date-time) | null UTC timestamp when the video was created.
lastUpdateDate string (date-time) | null UTC timestamp of the most recent update.
archivedAt string (date-time) | null UTC timestamp when the video was archived.
null if the video is active. locals VideoLocalItemModel[] | null Localized title and version strings.
languageId integer Language ID for this localization entry.
name string | null Video 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.
creationDate string (date-time) | null UTC timestamp when the localization entry was created.
createdBy string | null ID of the user who created the localization entry.
recordingVersions VideoRecordingItemModel[] | null The video recording and its source file.
isrc string | null ISRC code for this recording version.
recordingVersionType VideoRecordingVersionTypes Type of recording version.
Example:
standard files VideoFileModel[] The source video file.
fileId string File ID of the uploaded video file.
format VideoFileFormats Video container format.
Examples:
mp4, mov filename string | null Name of the uploaded file, including the extension.
duration integer | null Duration of the video, in seconds.
bitDepth integer | null Audio bit depth of the embedded audio stream.
sampleRate integer | null Audio sample rate, in Hz.
bitrate integer | null Audio bitrate, in bps.
resolution string | null Video resolution label (e.g.,
1080p), extracted from the file during processing. frameRate number Frames per second, extracted from the file during processing.
size integer | null File size, in bytes.
channels integer | null Number of audio channels.
tags VideoTags[] | null Descriptive tags for the video.
isAgeRestricted boolean Whether the video is restricted to adult viewers.
recordingProperties TrackPropertyType[] | null Additional properties describing the recording.
captions VideoCaptionItemModel[] | null Caption files attached to this video.
videoCaptionId integer Unique identifier for this caption entry.
languageId integer Language of the caption file.
fileId string File ID of the uploaded caption file.
fileName string | null Original caption file name, including the extension.
creationDate string (date-time) | null UTC timestamp when the caption was attached.
createdBy string | null ID of the user who attached the caption.
encodedVideos VideoFileModel[] | null Streamable renditions generated from the source video file. Empty until encoding completes.
fileId string File ID of the source video file this rendition was generated from.
format VideoFileFormats Container format of the rendition. Always
mp4. filename string | null Generated file name of the rendition.
duration integer | null Duration of the rendition, in seconds.
bitDepth integer | null Audio bit depth of the rendition's audio stream.
sampleRate integer | null Audio sample rate of the rendition, in Hz.
bitrate integer | null Audio bitrate of the rendition, in bps.
resolution string | null Resolution label of the rendition (e.g.,
1080p). frameRate number Frames per second of the rendition.
size integer | null Size of the rendition, in bytes.
channels integer | null Number of audio channels in the rendition.
contributors ContributorItemModel[] | null Contributing artists credited on this video. Use List Video Contributors to resolve the full artist records.
artistId * integer ID of the contributing artist.
roleId * integer Contributor role ID.
composers ComposerItemModel[] | null Publishing contributors (composers) for this video. Use List Video Composers to resolve the full composer records.
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 video carry a share summing to 100, or all are
null. compositions CompositionItemModel[] | null The underlying musical work(s) this video represents.
iswc string | null International Standard Musical Work Code (ISWC) for the underlying composition.
acrCloud AcrCloudModel Automatic Content Recognition (ACR) scan results for this video's audio.
null if no scan has run yet. fileId string File ID of the video 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 video. See the Video Locking section above.
Examples:
unlocked, partiallyLocked, fullyLocked GET
/catalog/v1/videos/{videoId} curl -X GET "https://platform.revelator.com/catalog/v1/videos/4501" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"curl -X GET "https://platform.revelator.com/catalog/v1/videos/4501" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" Example response 200
{
"videoId": 4501,
"assetId": 4419901,
"name": "Night Lights",
"version": "Official Video",
"phoneticName": null,
"phoneticVersion": null,
"languageAndScriptCode": null,
"framePosterImageId": null,
"customPosterImageId": "3b7e9a1c-4d5f-4a2b-8c6e-1d0f2a4b6c88",
"previewStartSeconds": 10,
"videoType": "officialVideo",
"recordingType": "original",
"parentalAdvisory": "notExplicit",
"catalog": "NR-2026-014",
"copyrightP": "2026 Northline Records",
"copyrightC": "2026 Northline Records",
"metadataLanguageId": 1,
"audioLanguageId": 1,
"artistId": 4402,
"primaryMusicStyleId": 17,
"secondaryMusicStyleId": null,
"linkedTrackId": 7701,
"tenantId": 2001,
"enterpriseId": 3001,
"creationDate": "2026-08-11T09:11:47.334Z",
"lastUpdateDate": "2026-08-11T09:11:47.334Z",
"archivedAt": null,
"locals": [],
"recordingVersions": [
{
"isrc": "QZ8AB2600011",
"recordingVersionType": "standard",
"files": [
{
"fileId": "8f3c1d2e-5a7b-4c9d-b0e1-2f4a6c8d0e13",
"format": "mp4",
"filename": "night-lights.mp4",
"duration": 30,
"bitDepth": null,
"sampleRate": 48000,
"bitrate": 256000,
"resolution": null,
"frameRate": 0,
"size": 17839845,
"channels": 2
}
]
}
],
"tags": ["officialMusicVideo", "closedCaptioned"],
"isAgeRestricted": false,
"recordingProperties": ["none"],
"captions": [
{
"videoCaptionId": 184,
"languageId": 1,
"fileId": "c5a1e703-9b24-4f68-a1d7-83e5f0b2c419",
"fileName": "night-lights.scc",
"creationDate": "2026-08-11T09:11:47.373Z",
"createdBy": "b3f1a2c4-1111-4e5f-a678-426614174000"
}
],
"encodedVideos": [
{
"fileId": "8f3c1d2e-5a7b-4c9d-b0e1-2f4a6c8d0e13",
"format": "mp4",
"filename": "8f3c1d2e-5a7b-4c9d-b0e1-2f4a6c8d0e13_streamable.mp4",
"duration": 30,
"bitDepth": null,
"sampleRate": 48000,
"bitrate": 2276,
"resolution": "1080p",
"frameRate": 24,
"size": 3422218,
"channels": 2
}
],
"contributors": [
{ "artistId": 4410, "roleId": 5 }
],
"composers": [
{ "composerId": 6601, "roleId": 2, "rightsId": 2, "publisherId": 3301, "share": 100 }
],
"compositions": [],
"acrCloud": null,
"lockLevel": "unlocked"
}{
"videoId": 4501,
"assetId": 4419901,
"name": "Night Lights",
"version": "Official Video",
"phoneticName": null,
"phoneticVersion": null,
"languageAndScriptCode": null,
"framePosterImageId": null,
"customPosterImageId": "3b7e9a1c-4d5f-4a2b-8c6e-1d0f2a4b6c88",
"previewStartSeconds": 10,
"videoType": "officialVideo",
"recordingType": "original",
"parentalAdvisory": "notExplicit",
"catalog": "NR-2026-014",
"copyrightP": "2026 Northline Records",
"copyrightC": "2026 Northline Records",
"metadataLanguageId": 1,
"audioLanguageId": 1,
"artistId": 4402,
"primaryMusicStyleId": 17,
"secondaryMusicStyleId": null,
"linkedTrackId": 7701,
"tenantId": 2001,
"enterpriseId": 3001,
"creationDate": "2026-08-11T09:11:47.334Z",
"lastUpdateDate": "2026-08-11T09:11:47.334Z",
"archivedAt": null,
"locals": [],
"recordingVersions": [
{
"isrc": "QZ8AB2600011",
"recordingVersionType": "standard",
"files": [
{
"fileId": "8f3c1d2e-5a7b-4c9d-b0e1-2f4a6c8d0e13",
"format": "mp4",
"filename": "night-lights.mp4",
"duration": 30,
"bitDepth": null,
"sampleRate": 48000,
"bitrate": 256000,
"resolution": null,
"frameRate": 0,
"size": 17839845,
"channels": 2
}
]
}
],
"tags": ["officialMusicVideo", "closedCaptioned"],
"isAgeRestricted": false,
"recordingProperties": ["none"],
"captions": [
{
"videoCaptionId": 184,
"languageId": 1,
"fileId": "c5a1e703-9b24-4f68-a1d7-83e5f0b2c419",
"fileName": "night-lights.scc",
"creationDate": "2026-08-11T09:11:47.373Z",
"createdBy": "b3f1a2c4-1111-4e5f-a678-426614174000"
}
],
"encodedVideos": [
{
"fileId": "8f3c1d2e-5a7b-4c9d-b0e1-2f4a6c8d0e13",
"format": "mp4",
"filename": "8f3c1d2e-5a7b-4c9d-b0e1-2f4a6c8d0e13_streamable.mp4",
"duration": 30,
"bitDepth": null,
"sampleRate": 48000,
"bitrate": 2276,
"resolution": "1080p",
"frameRate": 24,
"size": 3422218,
"channels": 2
}
],
"contributors": [
{ "artistId": 4410, "roleId": 5 }
],
"composers": [
{ "composerId": 6601, "roleId": 2, "rightsId": 2, "publisherId": 3301, "share": 100 }
],
"compositions": [],
"acrCloud": null,
"lockLevel": "unlocked"
}List Videos
GET
/catalog/v1/videos Returns a paginated list of videos based on filters and sorting options.
Query Parameters
| Parameter | Description |
|---|---|
videoType string | Filter by video classification. Examples: officialVideo, performance, other |
archived boolean | Filter by archive state ( |
artistIds integer[] | Filter by one or more primary artist IDs. Maximum 100 IDs per request. |
creationDateFrom string (date-time) | Include videos created on or after this UTC date-time. |
creationDateTo string (date-time) | Include videos created on or before this UTC date-time. |
lastUpdateDateFrom string (date-time) | Include videos updated on or after this UTC date-time. |
lastUpdateDateTo string (date-time) | Include videos updated on or before this UTC date-time. |
isrcs string[] | Filter by one or more ISRC codes. Maximum 100 per request. |
upcs string[] | Filter to videos 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. |
linkedTrackIds integer[] | Filter to videos linked to the given track IDs. Maximum 100 IDs per request. |
releaseAssetIds integer[] | Filter to videos that belong to a release with one of the given asset IDs. Pass the release's |
physicalReleaseAssetIds integer[] | Filter to videos that belong to a physical release with one of the given asset IDs. Pass the physical release's |
assetIds integer[] | Filter by the videos' own asset IDs—the |
videoIds integer[] | Filter by one or more video IDs. |
archivedDateFrom string (date-time) | Include videos archived on or after this UTC date-time. |
archivedDateTo string (date-time) | Include videos archived on or before this UTC date-time. |
enterpriseIds integer[] | Filter by one or more client IDs. Maximum 100 IDs per request. |
labelIds integer[] | Filter by one or more label IDs. Maximum 100 IDs per request. |
lockLevel string | Filter by edit permission level. See the Video Locking section above. Examples: unlocked, partiallyLocked, fullyLocked |
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. |
missingVideoFile boolean | Filter to videos missing a source video file ( |
parentalAdvisory string | Filter by advisory label. See the Parental Advisory & Age Restriction section above. Examples: notExplicit, clean, explicit |
searchText string | Free-text search applied to video name and other supported fields. |
pageNumber integer | Page number for paginated results. |
pageSize integer | Number of items per page. |
orderByProperty string | Property name used for sorting. Must be one of the listed values. Examples: videoId, name, artistName, enterpriseName, creationDate, lastUpdateDate, archivedAt |
orderByDescending boolean | Set to |
Responses
object pageNumber integer Current page number.
pageSize integer Number of items per page.
totalItemsCount integer Total number of videos matching the filters.
totalPagesCount number Total number of pages.
items VideoListModel[] Array of videos for the current page.
videoId integer Unique identifier for the video.
assetId integer Universal asset ID for this video.
name string | null Title of the video.
version string | null Version of the video.
phoneticName string | null Phonetic pronunciation of the title.
metadataLanguageId integer | null Language the video's title and other text fields are written in.
metadataLanguageName string | null Metadata language name.
audioLanguageId integer | null Language of the performance—what is sung or spoken in the video.
audioLanguageName string | null Audio language name.
languageAndScriptCode string | null Language and script code for the video's phonetic name/version.
videoType VideoTypes Classification of the video.
Examples:
officialVideo, performance, other recordingType RecordingTypes Origin of the recording.
Examples:
original, cover, publicDomain, undeclared parentalAdvisory ParentalAdvisories Advisory label for the video content. See the Parental Advisory & Age Restriction section above.
Examples:
notExplicit, clean, explicit catalog string | null Internal catalog reference number for the video.
copyrightP string | null Sound recording copyright (℗) for the video.
copyrightC string | null Composition/artwork copyright (©) for the video.
artistName string | null Display name of the primary artist.
artistId integer | null ID of the primary artist.
tenantId integer ID of the organization that owns this video.
enterpriseId integer ID of the client that owns this video.
enterpriseName string | null Name of the client.
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.
linkedTrackId integer | null ID of the audio track this video presents.
linkedTrackName string | null Title of the linked audio track.
posterImageId string | null File ID of the video's poster image.
createdBy string | null ID of the user who created the video.
recordingVersions VideoRecordingItemModel[] | null The video recording and its source file.
isrc string | null ISRC code for this recording version.
recordingVersionType VideoRecordingVersionTypes Type of recording version.
Example:
standard files VideoFileModel[] The source video file.
fileId string File ID of the uploaded video file.
format VideoFileFormats Video container format.
Examples:
mp4, mov filename string | null Name of the uploaded file, including the extension.
duration integer | null Duration of the video, in seconds.
bitDepth integer | null Audio bit depth of the embedded audio stream.
sampleRate integer | null Audio sample rate, in Hz.
bitrate integer | null Audio bitrate, in bps.
resolution string | null Video resolution label (e.g.,
1080p), extracted from the file during processing. frameRate number Frames per second, extracted from the file during processing.
size integer | null File size, in bytes.
channels integer | null Number of audio channels.
isAgeRestricted boolean Whether the video is restricted to adult viewers.
creationDate string (date-time) | null UTC timestamp when the video was created.
lastUpdateDate string (date-time) | null UTC timestamp of the most recent update.
archivedAt string (date-time) | null UTC timestamp when the video was archived.
null if the video is active. releasesCount integer Number of releases this video is currently assigned to.
acrCloud AcrCloudModel Automatic Content Recognition (ACR) scan results.
null if no scan has run yet. fileId string File ID of the video 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 video.
Examples:
unlocked, partiallyLocked, fullyLocked contributors ContributorListModel[] | null Contributing artists credited on this video. Use List Video Contributors to resolve the full artist records.
artistId integer ID of the contributing artist.
roleId integer Contributor role ID.
artistName string | null Display name of the contributing artist.
GET
/catalog/v1/videos curl -X GET "https://platform.revelator.com/catalog/v1/videos?pageNumber=1&pageSize=20&videoType=officialVideo&orderByProperty=creationDate&orderByDescending=true" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"curl -X GET "https://platform.revelator.com/catalog/v1/videos?pageNumber=1&pageSize=20&videoType=officialVideo&orderByProperty=creationDate&orderByDescending=true" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" Example response 200
{
"pageNumber": 1,
"pageSize": 20,
"totalItemsCount": 1,
"totalPagesCount": 1,
"items": [
{
"videoId": 4501,
"assetId": 4419901,
"name": "Night Lights",
"version": "Official Video",
"phoneticName": null,
"metadataLanguageId": 1,
"metadataLanguageName": "English",
"audioLanguageId": 1,
"audioLanguageName": "English",
"languageAndScriptCode": null,
"videoType": "officialVideo",
"recordingType": "original",
"parentalAdvisory": "notExplicit",
"catalog": "NLR-0042",
"copyrightP": "2024 Northline Records",
"copyrightC": "2024 Northline Records",
"artistName": "Nova Days",
"artistId": 4402,
"tenantId": 2001,
"enterpriseId": 3001,
"enterpriseName": "Client Name",
"primaryMusicStyleId": 17,
"primaryMusicStyleName": "Electronic",
"secondaryMusicStyleId": null,
"secondaryMusicStyleName": null,
"linkedTrackId": 7701,
"linkedTrackName": "Night Lights",
"posterImageId": "3b7e9a1c-4d5f-4a2b-8c6e-1d0f2a4b6c88",
"createdBy": "b3f1a2c4-1111-4e5f-a678-426614174000",
"recordingVersions": [
{
"isrc": "QZ8AB2600011",
"recordingVersionType": "standard",
"files": [
{
"fileId": "8f3c1d2e-5a7b-4c9d-b0e1-2f4a6c8d0e13",
"format": "mp4",
"filename": "night-lights.mp4",
"duration": 30,
"bitDepth": null,
"sampleRate": 48000,
"bitrate": 256000,
"resolution": null,
"frameRate": 0,
"size": 17839845,
"channels": 2
}
]
}
],
"isAgeRestricted": false,
"creationDate": "2026-08-11T09:11:47.334Z",
"lastUpdateDate": "2026-08-11T09:11:47.334Z",
"archivedAt": null,
"releasesCount": 1,
"acrCloud": null,
"lockLevel": "unlocked",
"contributors": [
{ "artistId": 4409, "roleId": 12, "artistName": "Mara Quinn" }
]
}
]
}{
"pageNumber": 1,
"pageSize": 20,
"totalItemsCount": 1,
"totalPagesCount": 1,
"items": [
{
"videoId": 4501,
"assetId": 4419901,
"name": "Night Lights",
"version": "Official Video",
"phoneticName": null,
"metadataLanguageId": 1,
"metadataLanguageName": "English",
"audioLanguageId": 1,
"audioLanguageName": "English",
"languageAndScriptCode": null,
"videoType": "officialVideo",
"recordingType": "original",
"parentalAdvisory": "notExplicit",
"catalog": "NLR-0042",
"copyrightP": "2024 Northline Records",
"copyrightC": "2024 Northline Records",
"artistName": "Nova Days",
"artistId": 4402,
"tenantId": 2001,
"enterpriseId": 3001,
"enterpriseName": "Client Name",
"primaryMusicStyleId": 17,
"primaryMusicStyleName": "Electronic",
"secondaryMusicStyleId": null,
"secondaryMusicStyleName": null,
"linkedTrackId": 7701,
"linkedTrackName": "Night Lights",
"posterImageId": "3b7e9a1c-4d5f-4a2b-8c6e-1d0f2a4b6c88",
"createdBy": "b3f1a2c4-1111-4e5f-a678-426614174000",
"recordingVersions": [
{
"isrc": "QZ8AB2600011",
"recordingVersionType": "standard",
"files": [
{
"fileId": "8f3c1d2e-5a7b-4c9d-b0e1-2f4a6c8d0e13",
"format": "mp4",
"filename": "night-lights.mp4",
"duration": 30,
"bitDepth": null,
"sampleRate": 48000,
"bitrate": 256000,
"resolution": null,
"frameRate": 0,
"size": 17839845,
"channels": 2
}
]
}
],
"isAgeRestricted": false,
"creationDate": "2026-08-11T09:11:47.334Z",
"lastUpdateDate": "2026-08-11T09:11:47.334Z",
"archivedAt": null,
"releasesCount": 1,
"acrCloud": null,
"lockLevel": "unlocked",
"contributors": [
{ "artistId": 4409, "roleId": 12, "artistName": "Mara Quinn" }
]
}
]
}Update Video
PUT
/catalog/v1/videos/{videoId} Updates an existing video by its ID. Replaces the entire video—fields omitted from the payload are cleared.
Path Parameters
| Parameter | Description |
|---|---|
videoId * integer | The ID of the video to update. |
Request Body *
object enterpriseId integer Ignored when updating an existing video; the update always targets the video identified by
videoId regardless of client. name * string Title of the video.
version string Version of the video (e.g., "Live", "Remix", "Extended Cut").
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 video's phonetic name/version, not the main title (e.g.,
ja-Latn). Available values can be retrieved from GET /common/lookup/languageAndScriptCodes on the V1.0 API. Supply a code that matches the audioLanguageId set on the video. framePosterImageId string File ID (GUID) of a poster image taken as a still from the video, required for distribution. Omitting this field clears the existing poster.
customPosterImageId string File ID (GUID) of a poster image designed separately from the video, optional for distribution. Omitting this field clears the existing poster.
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.
videoType * VideoTypes Classification of the video. See the Video Type & Tags section above.
Examples:
officialVideo, performance, other recordingType * RecordingTypes Origin of the recording.
Examples:
original, cover, publicDomain, undeclared parentalAdvisory * ParentalAdvisories Advisory label for the video content.
Examples:
notExplicit, clean, explicit isAgeRestricted * boolean Whether the video is restricted to adult viewers.
recordingProperties * TrackPropertyType[] Additional properties describing the recording. At least one entry is required—use
none when no property applies. artistId * integer ID of an existing artist to assign as the primary artist for the video. Apple Music does not allow the artist name or artist ID to change after the first submission, so confirm both are correct before saving.
primaryMusicStyleId integer Primary genre/music style ID for the video. Retrieved from GET /common/lookup/musicstyles on the V1.0 API.
secondaryMusicStyleId integer Secondary genre/music style ID for the video. Retrieved from GET /common/lookup/musicstyles on the V1.0 API.
catalog string Internal catalog reference number for the video.
copyrightP string Sound recording copyright (℗) for the video. Format:
[Year] [Rights Holder] (e.g., "2026 Acme Inc."). copyrightC string Composition/artwork copyright (©) for the video. Format:
[Year] [Rights Holder] (e.g., "2026 Acme Inc."). metadataLanguageId * integer Language the video'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 performance—what is sung or spoken in the video. Required for distribution. Retrieved from GET /common/lookup/languages on the V1.0 API.
linkedTrackId integer ID of the linked audio asset. Omitting this field unlinks the track.
locals VideoLocalRequest[] Localized title and version strings. Omitting the array removes all localizations.
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 Video 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. Retrieved from GET /common/lookup/languageAndScriptCodes on the V1.0 API.
recordingVersions VideoRecordingItemModel[] The video recording. Provide at most one entry, resubmitting the existing
fileId when you are editing unrelated fields—omitting the array detaches the video file from the asset and frees it for use on another video. isrc string ISRC code for this recording version. Leave
null to have one generated automatically during distribution. recordingVersionType * VideoRecordingVersionTypes Type of recording version. Videos support a single type.
Example:
standard files VideoFileModel[] Video files for this recording version. Provide a single file.
fileId * string File ID (GUID) of the previously uploaded video file, generated by the Files API. A file can be attached to only one video.
format * VideoFileFormats Video container format.
Examples:
mp4, mov filename string Name of the uploaded file, including the extension. Derived from the upload.
duration integer Duration of the video, in seconds. Computed automatically after processing.
bitDepth integer Audio bit depth of the embedded audio stream. Computed automatically after processing.
sampleRate integer Audio sample rate, in Hz. Computed automatically after processing.
bitrate integer Audio bitrate, in bps. Computed automatically after processing.
resolution string Video resolution label. Populated on encoded renditions rather than on the source file.
frameRate number Frames per second. Populated on encoded renditions rather than on the source file.
size integer File size, in bytes. Computed automatically after processing.
channels integer Number of audio channels. Computed automatically after processing.
tags VideoTags[] Descriptive tags for the video. Must include
officialMusicVideo when videoType is officialVideo. Omitting the array clears all existing tags. captions VideoCaptionRequest[] Caption files for the video. Include
videoCaptionId to retain an existing entry. Omitting the array removes all captions. videoCaptionId integer ID of an existing caption entry. Omit when adding a new caption.
languageId * integer Language of the caption file. Retrieved from GET /common/lookup/languages on the V1.0 API.
fileId * string File ID (GUID) of the uploaded caption file, generated by the Files API using the
VideoCaption purpose. fileName * string Original caption file name, including the extension (e.g.,
captions.scc). contributors ContributorItemModel[] Contributing artists credited on this video. Omitting the array removes all contributor credits.
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.
composers ComposerItemModel[] Publishing contributors (composers) for this video. Omitting the array removes all composer credits.
composerId integer ID of an existing composer to credit on this video.
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. Only relevant when
rightsId is 2. share number Optional share percentage for the composer. Shares must be either omitted on every composer or supplied on every composer summing to exactly 100—any other combination is rejected. Shares do not affect royalty payments.
compositions CompositionItemModel[] The underlying musical work(s) this video represents. Omitting the array removes all compositions.
iswc string International Standard Musical Work Code (ISWC) for the underlying composition. Format:
T followed by 10 digits (e.g., T1234567890). ISWCs are issued by your national or regional ISWC agency, usually through your local copyright or performing rights organisation—once a work is registered there you receive an ISWC for each composition.Responses
object videoId integer Unique identifier for the video.
assetId integer Universal asset ID for this video.
name string | null Title of the video.
version string | null Version of the video.
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 video's phonetic name/version, not the main title.
framePosterImageId string | null File ID of a poster image taken as a still from the video. Required for distribution.
customPosterImageId string | null File ID of a poster image designed separately from the video. Optional.
previewStartSeconds integer | null Preview/clip start time, in seconds. If omitted or set to null, the preview clip start time defaults to whatever value the DSP uses.
videoType VideoTypes Classification of the video.
Examples:
officialVideo, performance, other recordingType RecordingTypes Origin of the recording.
Examples:
original, cover, publicDomain, undeclared parentalAdvisory ParentalAdvisories Advisory label for the video content.
Examples:
notExplicit, clean, explicit catalog string | null Internal catalog reference number for the video.
copyrightP string | null Sound recording copyright (℗) for the video.
copyrightC string | null Composition/artwork copyright (©) for the video.
metadataLanguageId integer | null Language the video's title and other text fields are written in.
audioLanguageId integer | null Language of the performance—what is sung or spoken in the video.
artistId integer | null ID of the primary artist credited on the video.
primaryMusicStyleId integer | null Primary genre/music style ID for the video.
secondaryMusicStyleId integer | null Secondary genre/music style ID for the video.
linkedTrackId integer | null ID of the audio track this video presents.
null if the video is not linked to a track. tenantId integer ID of the organization that owns this video.
enterpriseId integer ID of the client that owns this video.
creationDate string (date-time) | null UTC timestamp when the video was created.
lastUpdateDate string (date-time) | null UTC timestamp of this update.
archivedAt string (date-time) | null UTC timestamp when the video was archived.
null if the video is active. locals VideoLocalItemModel[] | null Localized title and version strings.
languageId integer Language ID for this localization entry.
name string | null Video 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.
creationDate string (date-time) | null UTC timestamp when the localization entry was created.
createdBy string | null ID of the user who created the localization entry.
recordingVersions VideoRecordingItemModel[] | null The video recording and its source file.
isrc string | null ISRC code for this recording version.
recordingVersionType VideoRecordingVersionTypes Type of recording version.
Example:
standard files VideoFileModel[] The source video file.
fileId string File ID of the uploaded video file.
format VideoFileFormats Video container format.
Examples:
mp4, mov filename string | null Name of the uploaded file, including the extension.
duration integer | null Duration of the video, in seconds.
bitDepth integer | null Audio bit depth of the embedded audio stream.
sampleRate integer | null Audio sample rate, in Hz.
bitrate integer | null Audio bitrate, in bps.
resolution string | null Video resolution label (e.g.,
1080p), extracted from the file during processing. frameRate number Frames per second, extracted from the file during processing.
size integer | null File size, in bytes.
channels integer | null Number of audio channels.
tags VideoTags[] | null Descriptive tags for the video.
isAgeRestricted boolean Whether the video is restricted to adult viewers.
recordingProperties TrackPropertyType[] | null Additional properties describing the recording.
captions VideoCaptionItemModel[] | null Caption files attached to this video.
videoCaptionId integer Unique identifier for this caption entry.
languageId integer Language of the caption file.
fileId string File ID of the uploaded caption file.
fileName string | null Original caption file name, including the extension.
creationDate string (date-time) | null UTC timestamp when the caption was attached.
createdBy string | null ID of the user who attached the caption.
encodedVideos VideoFileModel[] | null Streamable renditions generated from the source video file. Empty until encoding completes.
fileId string File ID of the source video file this rendition was generated from.
format VideoFileFormats Container format of the rendition. Always
mp4. filename string | null Generated file name of the rendition.
duration integer | null Duration of the rendition, in seconds.
bitDepth integer | null Audio bit depth of the rendition's audio stream.
sampleRate integer | null Audio sample rate of the rendition, in Hz.
bitrate integer | null Audio bitrate of the rendition, in bps.
resolution string | null Resolution label of the rendition (e.g.,
1080p). frameRate number Frames per second of the rendition.
size integer | null Size of the rendition, in bytes.
channels integer | null Number of audio channels in the rendition.
contributors ContributorItemModel[] | null Contributing artists credited on this video. Use List Video Contributors to resolve the full artist records.
artistId * integer ID of the contributing artist.
roleId * integer Contributor role ID.
composers ComposerItemModel[] | null Publishing contributors (composers) for this video. Use List Video Composers to resolve the full composer records.
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 video carry a share summing to 100, or all are
null. compositions CompositionItemModel[] | null The underlying musical work(s) this video represents.
iswc string | null International Standard Musical Work Code (ISWC) for the underlying composition.
acrCloud AcrCloudModel Automatic Content Recognition (ACR) scan results for this video's audio.
null if no scan has run yet. fileId string File ID of the video 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 video.
Examples:
unlocked, partiallyLocked, fullyLocked PUT
/catalog/v1/videos/{videoId} curl -X PUT "https://platform.revelator.com/catalog/v1/videos/4501" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Night Lights",
"version": "Official Video",
"videoType": "officialVideo",
"tags": ["officialMusicVideo", "closedCaptioned"],
"recordingType": "original",
"recordingProperties": ["none"],
"parentalAdvisory": "explicit",
"isAgeRestricted": true,
"artistId": 4402,
"primaryMusicStyleId": 17,
"metadataLanguageId": 1,
"audioLanguageId": 1,
"catalog": "NR-2026-014",
"copyrightP": "2026 Northline Records",
"copyrightC": "2026 Northline Records",
"linkedTrackId": 7701,
"previewStartSeconds": 10,
"customPosterImageId": "3b7e9a1c-4d5f-4a2b-8c6e-1d0f2a4b6c88",
"recordingVersions": [
{
"isrc": "QZ8AB2600011",
"recordingVersionType": "standard",
"files": [
{ "fileId": "8f3c1d2e-5a7b-4c9d-b0e1-2f4a6c8d0e13", "format": "mp4" }
]
}
],
"captions": [
{
"videoCaptionId": 184,
"languageId": 1,
"fileId": "c5a1e703-9b24-4f68-a1d7-83e5f0b2c419",
"fileName": "night-lights.scc"
}
],
"contributors": [
{ "artistId": 4410, "roleId": 5 }
],
"composers": [
{ "composerId": 6601, "roleId": 2, "rightsId": 2, "publisherId": 3301, "share": 100 }
],
"compositions": [],
"locals": []
}'curl -X PUT "https://platform.revelator.com/catalog/v1/videos/4501" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Night Lights",
"version": "Official Video",
"videoType": "officialVideo",
"tags": ["officialMusicVideo", "closedCaptioned"],
"recordingType": "original",
"recordingProperties": ["none"],
"parentalAdvisory": "explicit",
"isAgeRestricted": true,
"artistId": 4402,
"primaryMusicStyleId": 17,
"metadataLanguageId": 1,
"audioLanguageId": 1,
"catalog": "NR-2026-014",
"copyrightP": "2026 Northline Records",
"copyrightC": "2026 Northline Records",
"linkedTrackId": 7701,
"previewStartSeconds": 10,
"customPosterImageId": "3b7e9a1c-4d5f-4a2b-8c6e-1d0f2a4b6c88",
"recordingVersions": [
{
"isrc": "QZ8AB2600011",
"recordingVersionType": "standard",
"files": [
{ "fileId": "8f3c1d2e-5a7b-4c9d-b0e1-2f4a6c8d0e13", "format": "mp4" }
]
}
],
"captions": [
{
"videoCaptionId": 184,
"languageId": 1,
"fileId": "c5a1e703-9b24-4f68-a1d7-83e5f0b2c419",
"fileName": "night-lights.scc"
}
],
"contributors": [
{ "artistId": 4410, "roleId": 5 }
],
"composers": [
{ "composerId": 6601, "roleId": 2, "rightsId": 2, "publisherId": 3301, "share": 100 }
],
"compositions": [],
"locals": []
}' Example response 200
{
"videoId": 4501,
"assetId": 4419901,
"name": "Night Lights",
"version": "Official Video",
"videoType": "officialVideo",
"recordingType": "original",
"parentalAdvisory": "explicit",
"isAgeRestricted": true,
"artistId": 4402,
"linkedTrackId": 7701,
"customPosterImageId": "3b7e9a1c-4d5f-4a2b-8c6e-1d0f2a4b6c88",
"previewStartSeconds": 10,
"tenantId": 2001,
"enterpriseId": 3001,
"creationDate": "2026-08-11T09:11:47.334Z",
"lastUpdateDate": "2026-08-11T10:02:15.907Z",
"archivedAt": null,
"tags": ["officialMusicVideo", "closedCaptioned"],
"recordingProperties": ["none"],
"acrCloud": null,
"lockLevel": "unlocked"
}{
"videoId": 4501,
"assetId": 4419901,
"name": "Night Lights",
"version": "Official Video",
"videoType": "officialVideo",
"recordingType": "original",
"parentalAdvisory": "explicit",
"isAgeRestricted": true,
"artistId": 4402,
"linkedTrackId": 7701,
"customPosterImageId": "3b7e9a1c-4d5f-4a2b-8c6e-1d0f2a4b6c88",
"previewStartSeconds": 10,
"tenantId": 2001,
"enterpriseId": 3001,
"creationDate": "2026-08-11T09:11:47.334Z",
"lastUpdateDate": "2026-08-11T10:02:15.907Z",
"archivedAt": null,
"tags": ["officialMusicVideo", "closedCaptioned"],
"recordingProperties": ["none"],
"acrCloud": null,
"lockLevel": "unlocked"
}List Video Contributors
GET
/catalog/v1/videos/{videoId}/contributors Retrieves the full artist records for every contributing artist credited on the video.
Path Parameters
| Parameter | Description |
|---|---|
videoId * integer | The ID of the video. |
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. externalIds ArtistExternalIdItemModel[] | null External DSP profile IDs for this artist (e.g., Spotify artist URI, Apple Music artist ID).
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/videos/{videoId}/contributors curl -X GET "https://platform.revelator.com/catalog/v1/videos/4501/contributors" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"curl -X GET "https://platform.revelator.com/catalog/v1/videos/4501/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]
}
][
{
"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 Video Composers
GET
/catalog/v1/videos/{videoId}/composers Retrieves the full composer records for every composer credited on the video.
Path Parameters
| Parameter | Description |
|---|---|
videoId * integer | The ID of the video. |
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. roles ComposerRoleItemModel[] | null Contributor roles this composer has been credited with.
roleId integer Contributor role ID.
name string | null Contributor role name.
GET
/catalog/v1/videos/{videoId}/composers curl -X GET "https://platform.revelator.com/catalog/v1/videos/4501/composers" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"curl -X GET "https://platform.revelator.com/catalog/v1/videos/4501/composers" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" Example response 200
[
{
"composerId": 6601,
"tenantId": 2001,
"enterpriseId": 3001,
"name": "Example Composer",
"logoImageId": null,
"isni": null,
"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
}
][
{
"composerId": 6601,
"tenantId": 2001,
"enterpriseId": 3001,
"name": "Example Composer",
"logoImageId": null,
"isni": null,
"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 Video Publishers
GET
/catalog/v1/videos/{videoId}/publishers Retrieves the full publisher records for every publisher associated with the video's composer credits.
Path Parameters
| Parameter | Description |
|---|---|
videoId * integer | The ID of the video. |
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/videos/{videoId}/publishers curl -X GET "https://platform.revelator.com/catalog/v1/videos/4501/publishers" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"curl -X GET "https://platform.revelator.com/catalog/v1/videos/4501/publishers" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" Example response 200
[
{
"publisherId": 3301,
"tenantId": 2001,
"enterpriseId": 3001,
"name": "Example Publisher",
"logoImageId": null,
"ipiCae": "123456",
"countryId": 875,
"creationDate": "2025-12-11T12:06:28Z",
"lastUpdateDate": "2026-07-20T13:33:31.867Z",
"archivedAt": null,
"archivedBy": null
}
][
{
"publisherId": 3301,
"tenantId": 2001,
"enterpriseId": 3001,
"name": "Example Publisher",
"logoImageId": null,
"ipiCae": "123456",
"countryId": 875,
"creationDate": "2025-12-11T12:06:28Z",
"lastUpdateDate": "2026-07-20T13:33:31.867Z",
"archivedAt": null,
"archivedBy": null
}
]Get Encoded Versions
GET
/catalog/v1/video-files/{videoFileId}/encoded-versions Retrieves the streamable renditions generated from a source video file.
Path Parameters
| Parameter | Description |
|---|---|
videoFileId * string | The file ID (GUID) of the source video file, as returned in the video's |
Responses
object[] fileId string File ID of the source video file this rendition was generated from.
format VideoFileFormats Container format of the rendition. Always
mp4, regardless of the source container. Example:
mp4 filename string | null Generated file name of the rendition.
duration integer | null Duration of the rendition, in seconds.
bitDepth integer | null Audio bit depth of the rendition.
sampleRate integer | null Audio sample rate of the rendition, in Hz.
bitrate integer | null Bitrate of the rendition.
resolution string | null Resolution label of the rendition (e.g.,
1080p). frameRate number Frames per second of the rendition.
size integer | null Size of the rendition, in bytes.
channels integer | null Number of audio channels in the rendition.
GET
/catalog/v1/video-files/{videoFileId}/encoded-versions curl -X GET "https://platform.revelator.com/catalog/v1/video-files/8f3c1d2e-5a7b-4c9d-b0e1-2f4a6c8d0e13/encoded-versions" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"curl -X GET "https://platform.revelator.com/catalog/v1/video-files/8f3c1d2e-5a7b-4c9d-b0e1-2f4a6c8d0e13/encoded-versions" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" Example response 200
[
{
"fileId": "8f3c1d2e-5a7b-4c9d-b0e1-2f4a6c8d0e13",
"format": "mp4",
"filename": "8f3c1d2e-5a7b-4c9d-b0e1-2f4a6c8d0e13_streamable.mp4",
"duration": 30,
"bitDepth": null,
"sampleRate": 48000,
"bitrate": 2276,
"resolution": "1080p",
"frameRate": 24,
"size": 3422218,
"channels": 2
}
][
{
"fileId": "8f3c1d2e-5a7b-4c9d-b0e1-2f4a6c8d0e13",
"format": "mp4",
"filename": "8f3c1d2e-5a7b-4c9d-b0e1-2f4a6c8d0e13_streamable.mp4",
"duration": 30,
"bitDepth": null,
"sampleRate": 48000,
"bitrate": 2276,
"resolution": "1080p",
"frameRate": 24,
"size": 3422218,
"channels": 2
}
]Archive Videos
POST
/catalog/v1/videos/archive Archives videos in batch by their universal asset IDs.
Request Body *
object Batch archive request payload.
assetIds * integer[] List of video asset IDs to archive. Maximum 100 IDs per request. These are
assetId values, not videoId values.Responses
object results ArchiveResult[] Array of batch archive results, one entry per requested asset ID.
id integer Video asset ID from the request.
succeeded boolean Whether the archive operation succeeded for this video.
errors ArchiveResultError[] | null Errors that prevented archiving this video.
null when succeeded is true. code string Error code.
message string Human-readable error message.
POST
/catalog/v1/videos/archive curl -X POST "https://platform.revelator.com/catalog/v1/videos/archive" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"assetIds": [4419901, 4419902]
}'curl -X POST "https://platform.revelator.com/catalog/v1/videos/archive" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"assetIds": [4419901, 4419902]
}' Example response 200
{
"results": [
{
"id": 4419901,
"succeeded": true,
"errors": null
},
{
"id": 4419902,
"succeeded": true,
"errors": null
}
]
}{
"results": [
{
"id": 4419901,
"succeeded": true,
"errors": null
},
{
"id": 4419902,
"succeeded": true,
"errors": null
}
]
}Unarchive Videos
POST
/catalog/v1/videos/unarchive Unarchives videos in batch by their universal asset IDs.
Request Body *
object Batch unarchive request payload.
assetIds * integer[] List of video asset IDs to unarchive. Maximum 100 IDs per request. These are
assetId values, not videoId values.Responses
object results UnarchiveResult[] Array of batch unarchive results, one entry per requested asset ID.
id integer Video asset ID from the request.
succeeded boolean Whether the unarchive operation succeeded for this video.
errors UnarchiveResultError[] | null Errors that prevented unarchiving this video.
null when succeeded is true. code string Error code.
message string Human-readable error message.
POST
/catalog/v1/videos/unarchive curl -X POST "https://platform.revelator.com/catalog/v1/videos/unarchive" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"assetIds": [4419901, 4419902]
}'curl -X POST "https://platform.revelator.com/catalog/v1/videos/unarchive" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"assetIds": [4419901, 4419902]
}' Example response 200
{
"results": [
{
"id": 4419901,
"succeeded": true,
"errors": null
},
{
"id": 4419902,
"succeeded": true,
"errors": null
}
]
}{
"results": [
{
"id": 4419901,
"succeeded": true,
"errors": null
},
{
"id": 4419902,
"succeeded": true,
"errors": null
}
]
}