DOCSEARCHbyAlgolia
Submit Docs

Revelator API Documentation

website·Indexed 34 days ago

https://api-docs.revelator.com/

API documentation for managing music business operations, including catalog management (artists, tracks, releases), supply chain distribution, revenue analytics, and rights management. Includes technical specifications for V2.0 API endpoints and Model Context Protocol (MCP) servers for AI assistants to interact with analytics, blockchain, royalties, and catalog data.

Tokens
114.2K
Snippets
460
Records
833
Agent score
51%

What's inside Revelator

  1. Overview of the Blockchain MCP Server

    v2
    The Blockchain MCP Server allows AI assistants to interact with Revelator’s Web3 and decentralized features. Key capabilities include retrieving wallet balances, checking royalty token distributions, and managing payee vaults. Note that this server is currently in BETA and subject to breaking changes; some tools may return 403 Forbidden errors.

  2. Overview of Revelator Model Context Protocol (MCP) Servers

    v2

    The Model Context Protocol (MCP) allows AI assistants (such as Claude Desktop) to connect to Revelator data to fetch, analyze, and manage catalog, analytics, and royalty data using natural language. These servers are currently in BETA and may be subject to breaking changes or 403 Forbidden errors.

    Available MCP Servers by domain:

    • Catalog: Query and manage metadata for releases, tracks, and artists.
    • Supply Chain: Manage distribution settings, pricing, and territories.
    • Analytics: Pull performance data, Top Movers, and revenue metrics.
    • Royalties: Manage accounting, royalty runs, and payee statements.
    • Blockchain: Interact with Web3 features, royalty tokens, and smart wallets.

  3. Overview of the Royalties MCP Server

    v2
    The Royalties MCP Server enables AI assistants to manage accounting operations within Revelator. This includes executing royalty runs, retrieving contracts, managing payee statements, and checking sales reports. Note that this server is currently in BETA and may be subject to breaking changes or intermittent 403 Forbidden errors.

  4. Overview of the Catalog MCP Server

    v2
    The Catalog MCP Server allows AI assistants (such as Claude Desktop) to query, retrieve, and manage metadata for releases, tracks, artists, labels, physical products, and YouTube channels using natural language. Note that this server is currently in BETA and may be subject to breaking changes or intermittent 403 Forbidden errors.

  5. Overview of the Revelator YouTube API

    v2
    The YouTube API is a read-only service used to retrieve and search metadata for YouTube channels and videos, including statistics, engagement metrics, and categories. It only provides access to channels and videos that have been previously imported or linked to the Revelator platform. You cannot modify YouTube content through these endpoints.

  6. Overview of the Supply Chain MCP Server

    v2
    The Supply Chain MCP Server allows AI assistants to view and manage distribution settings, including pricing tiers, monetization policies, and territory clearances. Note that this server is currently in BETA and subject to breaking changes; some tools may return 403 Forbidden or other errors.

  7. Overview of Supply Chain Validation Endpoints

    v2
    Validation endpoints are read-only GET requests used to determine if a release, track, or video is ready for distribution or eligible for takedown. They run the same rules as the actual distribution/takedown workflows but do not change the state of the records. Note that a record that saves successfully via Catalog endpoints may still fail validation because Catalog endpoints perform less strict validation to allow for incomplete records.

  8. Overview of the Revelator Files API upload workflow

    v2

    The Files API uses a three-step multipart upload process to securely upload binary files. Files uploaded via this API are only compatible with V2.0 API endpoints and cannot be used with V1.0 endpoints.

    The Workflow:

    1. Create Upload: Initialize the session to get an uploadId and suggested chunking parameters.
    2. Sign and Upload Parts: Obtain pre-signed URLs for each part. Upload binary data directly to these URLs. Pre-signed URLs expire after 20 minutes (returning 403 Forbidden).
    3. Complete Upload: Finalize the process to receive the final fileUrl.

    Key Concept: uploadId as fileId The uploadId returned during the creation step becomes the permanent fileId used to reference the file in V2.0 catalog payloads (e.g., posterImageId or recordingVersions[].files[].fileId).

  9. Overview of Physical Releases API

    v2

    The Physical Releases API is used to manage metadata for physical music and video products such as vinyl records, CDs, cassettes, DVDs, and Blu-rays.

    Key Constraints:

    • Metadata Only: The API does not support inventory, stock management, SKUs, manufacturing workflows, or physical distribution.
    • Asset Requirements: Cover artwork and additional media files must be uploaded via the Files API before they can be referenced in a physical release. Files uploaded via the V1.0 API are incompatible.
    • Configuration-Based: Each release must be tied to a specific configuration (e.g., "Vinyl Album") which determines available metadata fields and required assets.

  10. Understand Revelator Account and User hierarchy

    Revelator uses a hierarchical account structure to manage distribution and royalties:

    • Account: An environment users access. It is either a Parent or Client account.
    • Parent Account: Administers distribution and royalties for client accounts. It owns payees and contracts, inspects releases for fraud/metadata compliance, and processes royalties.
    • Client Account: Used for distributing releases; owns assets, artists, and labels.
    • User: A person with authentication credentials and permissions associated with one or more accounts.
    • Owner: The original creator of the account or a team member granted owner status.
    • Team Member: An invited user with full access to account content (assets for client accounts; contracts and payees for parent accounts).
    • Portal User: A user with content-specific permissions limited to a specific artist, label, or payee (e.g., Artist Portal, Label Portal, or Payee Portal).

  11. Retrieve information for a specific client enterprise

    Use the GET /enterprise/clients/{enterpriseId} endpoint to retrieve detailed information about a specific client enterprise, including its unique identifier, payee ID, trust scores, and account status (e.g., whether it is locked out or has Dolby Atmos enabled).

  12. Understand Revelator API account scoping

    v2
    Revelator uses a two-level scope for accounts. Organizations (referred to as tenant in the API) are top-level accounts that manage one or more Clients (referred to as enterprise in the API). Catalog entities like releases, tracks, artists, and labels are always created and managed under a Client.