openapi: 3.0.1
info:
  title: Revelator API
  description: >-
    REST API for the Revelator music distribution and rights, royalties, and
    payments platform. Covers account/catalog management, distribution to DSPs,
    analytics and trends, royalty accounting and financial reporting, and
    payments / royalty-token (Web3 wallet) operations. Authentication uses an
    access token (Bearer) obtained from the partner login endpoints; tokens are
    valid for 8 hours and must be sent in the Authorization header.
  termsOfService: https://www.revelator.com/terms
  contact:
    name: Revelator Support
    url: https://api-docs.revelator.com
  version: '1.0'
servers:
  - url: https://api.revelator.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Account
    description: Partner account signup, login, switching, and permissions.
  - name: Lookup
    description: Common reference/lookup data.
  - name: Distribution
    description: Release validation, distribution options, queueing, status, takedown.
  - name: Analytics
    description: Revenue, consumption, engagement, playlist, and artificial-streaming analytics.
  - name: Accounting
    description: Rights contracts and payee management.
  - name: Revenue
    description: Financial sale reports and user statements.
  - name: Royalty Tokens
    description: Minting and retrieving ERC1155 royalty tokens.
  - name: Integrations
    description: Payment-provider (Tipalti) integration.
paths:
  /partner/account/signup:
    post:
      operationId: partnerAccountSignup
      tags:
        - Account
      summary: Create a new child account and user.
      description: Creates a new child (enterprise) account and user under the partner. Authenticated with the partner API key.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignupRequest'
      responses:
        '200':
          description: Account created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthToken'
  /partner/account/login:
    post:
      operationId: partnerAccountLogin
      tags:
        - Account
      summary: Authenticate a user and obtain an access token.
      description: >-
        Prompted login uses username/password plus partnerApiKey; unprompted
        login uses partnerUserId plus partnerApiKey. Returns an access token
        valid for 8 hours.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthToken'
  /partner/account/upgrade:
    post:
      operationId: partnerAccountUpgrade
      tags:
        - Account
      summary: Upgrade an account type or settings.
      responses:
        '200':
          description: OK
  /account/login/as:
    post:
      operationId: accountLoginAs
      tags:
        - Account
      summary: Switch authentication context to a different enterprise.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthToken'
  /account/permissions:
    get:
      operationId: getAccountPermissions
      tags:
        - Account
      summary: Retrieve the list of accessible accounts.
      responses:
        '200':
          description: OK
  /enterprise/clients/{enterpriseId}:
    get:
      operationId: getEnterpriseClients
      tags:
        - Account
      summary: Retrieve client information for an enterprise.
      parameters:
        - name: enterpriseId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
  /distribution/release/{releaseId}/validate:
    post:
      operationId: validateRelease
      tags:
        - Distribution
      summary: Validate release metadata.
      description: Runs automated validation of release metadata, returning errors with severity levels (1 = blocking, 2 = warning).
      parameters:
        - name: releaseId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Validation results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResult'
  /content/release/retail/save:
    post:
      operationId: saveRetailDistributionOptions
      tags:
        - Distribution
      summary: Configure distribution / retail options.
      description: Configures distribution settings including sale dates, times, timezones, monetization policies, territorial availability, and price tiers.
      responses:
        '200':
          description: OK
  /distribution/release/addtoqueue:
    post:
      operationId: addReleaseToQueue
      tags:
        - Distribution
      summary: Add a release to the distribution queue.
      description: Adds a release to the distribution queue, specifying target DSP/store IDs for delivery.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddToQueueRequest'
      responses:
        '200':
          description: OK
  /distribution/release/all:
    get:
      operationId: getAllReleaseDistributionStatus
      tags:
        - Distribution
      summary: List releases with distribution statuses.
      description: Retrieves a paginated list of releases with distribution statuses per store, supporting filters by artist, label, date ranges, and status.
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/pageNumber'
      responses:
        '200':
          description: OK
  /distribution/store/all:
    get:
      operationId: getStoreDistributionStatus
      tags:
        - Distribution
      summary: Distribution status counts across stores.
      description: Returns distribution status counts across DSPs; includes detailed per-store status when the releaseId parameter is provided.
      parameters:
        - name: releaseId
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
  /distribution/release/takedown:
    post:
      operationId: takedownRelease
      tags:
        - Distribution
      summary: Take a release down from stores.
      description: Removes a release from one or more specified stores.
      responses:
        '200':
          description: OK
  /analytics/{dataSet}/{aggregationDimension}:
    get:
      operationId: getAnalytics
      tags:
        - Analytics
      summary: Aggregated analytics by data set and dimension.
      description: Retrieves aggregated analytics data (e.g. revenue) grouped by a dimension such as byCountry, byTrack, byRelease, byArtist, byLabel, byDistributor, byDeliveryType, byFormat, byYouTubeChannel, or byYouTubeVideo.
      parameters:
        - name: dataSet
          in: path
          required: true
          schema:
            type: string
            example: revenue
        - name: aggregationDimension
          in: path
          required: true
          schema:
            type: string
            example: byCountry
        - name: dateGranularity
          in: query
          required: false
          schema:
            type: string
            enum: [Daily, Monthly, Yearly, All]
        - $ref: '#/components/parameters/fromDate'
        - $ref: '#/components/parameters/toDate'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/pageNumber'
      responses:
        '200':
          description: OK
  /analytics/revenue/metricsByDate:
    get:
      operationId: getRevenueMetricsByDate
      tags:
        - Analytics
      summary: Monthly revenue metrics with pre-calculated enterprise-level values.
      parameters:
        - $ref: '#/components/parameters/fromDate'
        - $ref: '#/components/parameters/toDate'
        - name: metrics
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: targetEnterpriseId
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
  /analytics/{metric}/{aggregation}:
    get:
      operationId: getConsumptionAnalytics
      tags:
        - Analytics
      summary: V3 consumption and engagement analytics by dimension.
      description: Provides consumption and engagement metrics aggregated by various dimensions (byArtist, byCountry, byDate, byRelease, byTrack, byDistributor, byLabel, byDeliveryType, byDiscoveryType, byRecordingVersion, bySourceOfStream).
      parameters:
        - name: metric
          in: path
          required: true
          schema:
            type: string
            enum: [consumption, engagement]
        - name: aggregation
          in: path
          required: true
          schema:
            type: string
            example: byArtist
        - $ref: '#/components/parameters/fromDateRequired'
        - $ref: '#/components/parameters/toDateRequired'
        - name: dateGranularity
          in: query
          required: false
          schema:
            type: string
            enum: [Daily, Weekly, Monthly, Quarterly, Yearly, All]
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/pageNumber'
      responses:
        '200':
          description: OK
  /analytics/artificialStreams/{aggregation}:
    get:
      operationId: getArtificialStreams
      tags:
        - Analytics
      summary: Artificial / fraudulent streaming detection by dimension.
      parameters:
        - name: aggregation
          in: path
          required: true
          schema:
            type: string
            example: byTrack
        - $ref: '#/components/parameters/fromDate'
        - $ref: '#/components/parameters/toDate'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/pageNumber'
      responses:
        '200':
          description: OK
  /analytics/playlists/byMetadata:
    get:
      operationId: getPlaylistAnalytics
      tags:
        - Analytics
      summary: Playlist-driven performance metrics.
      description: Retrieves playlist performance such as streams from playlists, reach, followers, and coverage.
      parameters:
        - name: metric
          in: query
          required: true
          schema:
            type: string
            enum: [Streams, PlaylistsCount, Followers, TracksCount, All]
        - name: metadata
          in: query
          required: false
          schema:
            type: string
            enum: [Distributor, Country, Playlist, PlaylistType]
        - $ref: '#/components/parameters/fromDate'
        - $ref: '#/components/parameters/toDate'
      responses:
        '200':
          description: OK
  /accounting/contract/save:
    post:
      operationId: saveContract
      tags:
        - Accounting
      summary: Create or update a rights contract.
      description: >-
        Creates or modifies a contract (account, label, artist, release, or
        track level) with full payee and licensor configuration. Requires a
        parent account access token. The API does not support partial updates -
        the full object must be submitted.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Contract'
      responses:
        '200':
          description: OK
  /accounting/contracts:
    get:
      operationId: getContracts
      tags:
        - Accounting
      summary: List contracts.
      description: Retrieves a paginated list of contracts with filtering, sorting, and search.
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/pageNumber'
      responses:
        '200':
          description: OK
  /accounting/contracts/{contractId}:
    get:
      operationId: getContract
      tags:
        - Accounting
      summary: Retrieve a contract by id.
      parameters:
        - name: contractId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contract'
  /accounting/payee/{payeeId}:
    get:
      operationId: getPayee
      tags:
        - Accounting
      summary: Retrieve payee information.
      parameters:
        - name: payeeId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payee'
  /accounting/payee/save:
    post:
      operationId: savePayee
      tags:
        - Integrations
      summary: Update the payment method for a payee.
      description: Updates the payment method for a payee within the Revelator system (paymentProviderId, paymentProviderName, paymentUserId).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Payee'
      responses:
        '200':
          description: OK
  /integrations/tipalti/generateIframeHashkey:
    post:
      operationId: generateTipaltiIframeHashkey
      tags:
        - Integrations
      summary: Generate a Tipalti iFrame hashkey for payee setup.
      description: Generates an iFrame hashkey used to embed the Tipalti payee payment-setup flow. Requires a payee user access token.
      responses:
        '200':
          description: OK
  /finance/salereport/all:
    get:
      operationId: getSaleReports
      tags:
        - Revenue
      summary: List financial reports (user statements and sale reports).
      description: >-
        Retrieves User Statements (system-generated during royalty runs) and
        Sale Reports (raw DSP imports). Supports filtering by date range,
        release id, track id, store id, payee id, processing status, and
        approval status.
      parameters:
        - $ref: '#/components/parameters/fromDate'
        - $ref: '#/components/parameters/toDate'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/pageNumber'
      responses:
        '200':
          description: OK
  /finance/salereport/{statementId}:
    get:
      operationId: getSaleReport
      tags:
        - Revenue
      summary: Retrieve a single statement.
      description: 'Retrieves a single statement. The statement id uses the format {statementTypeId}|{statementId}.'
      parameters:
        - name: statementId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
  /finance/salereport/download/summary:
    get:
      operationId: downloadStatementSummary
      tags:
        - Revenue
      summary: Download a user-statement summary (HTML).
      description: 'Deprecated: effective June 19, 2026 this endpoint will be removed.'
      deprecated: true
      responses:
        '200':
          description: HTML file.
          content:
            text/html:
              schema:
                type: string
  /finance/salereport/download/details:
    get:
      operationId: downloadStatementDetails
      tags:
        - Revenue
      summary: Download user-statement details (CSV).
      responses:
        '200':
          description: CSV file.
          content:
            text/csv:
              schema:
                type: string
  /finance/salereport/post-download:
    post:
      operationId: postDownloadSaleReports
      tags:
        - Revenue
      summary: Download one or more sale reports as a ZIP archive.
      description: Accepts a JSON array of statement ids and returns a compressed ZIP archive.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
      responses:
        '200':
          description: ZIP archive.
          content:
            application/zip:
              schema:
                type: string
                format: binary
  /royaltyTokens:
    get:
      operationId: getRoyaltyTokens
      tags:
        - Royalty Tokens
      summary: List royalty tokens.
      description: Retrieves all royalty tokens for the account, with pagination, filtering by status and date range, and search.
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/pageNumber'
      responses:
        '200':
          description: OK
    post:
      operationId: mintRoyaltyToken
      tags:
        - Royalty Tokens
      summary: Mint a royalty token.
      description: >-
        Mints a new ERC1155 royalty token for a track asset, with a total
        supply and a holder list (Web3 wallet addresses, friendly names, token
        balances) and an optional payout rate (1-100%, defaults to 100%). The
        enterprise smart-wallet address is automatically designated an Admin
        holder.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoyaltyTokenMintRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoyaltyToken'
  /royaltyTokens/{tokenId}:
    get:
      operationId: getRoyaltyToken
      tags:
        - Royalty Tokens
      summary: Retrieve a royalty token by id.
      parameters:
        - name: tokenId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoyaltyToken'
  /common/lookup/{type}:
    get:
      operationId: getLookup
      tags:
        - Lookup
      summary: Retrieve lookup data.
      description: Retrieves lookup data such as currencies, countries, and stores.
      parameters:
        - name: type
          in: path
          required: true
          schema:
            type: string
            example: stores
      responses:
        '200':
          description: OK
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Access token obtained from POST /partner/account/login (or
        /account/login/as), sent as 'Authorization: Bearer <token>'. Tokens are
        valid for 8 hours.
  parameters:
    pageSize:
      name: pageSize
      in: query
      required: false
      schema:
        type: integer
    pageNumber:
      name: pageNumber
      in: query
      required: false
      schema:
        type: integer
    fromDate:
      name: fromDate
      in: query
      required: false
      schema:
        type: string
        format: date
    toDate:
      name: toDate
      in: query
      required: false
      schema:
        type: string
        format: date
    fromDateRequired:
      name: fromDate
      in: query
      required: true
      schema:
        type: string
        format: date
    toDateRequired:
      name: toDate
      in: query
      required: true
      schema:
        type: string
        format: date
  schemas:
    AuthToken:
      type: object
      properties:
        access_token:
          type: string
        enterpriseId:
          type: string
        expiresIn:
          type: integer
          description: Token lifetime in seconds (8 hours).
    LoginRequest:
      type: object
      properties:
        username:
          type: string
          description: Email (prompted login).
        password:
          type: string
          description: Password (prompted login).
        partnerUserId:
          type: string
          description: Partner-side user id (unprompted login).
        partnerApiKey:
          type: string
      required:
        - partnerApiKey
    SignupRequest:
      type: object
      properties:
        partnerApiKey:
          type: string
        email:
          type: string
        name:
          type: string
      required:
        - partnerApiKey
    ValidationResult:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
              severity:
                type: integer
                description: 1 = blocking, 2 = warning.
    AddToQueueRequest:
      type: object
      properties:
        releaseId:
          type: string
        storeIds:
          type: array
          items:
            type: string
      required:
        - releaseId
        - storeIds
    Contract:
      type: object
      properties:
        contractId:
          type: string
        name:
          type: string
        level:
          type: string
          enum: [account, label, artist, release, track]
        active:
          type: boolean
        payees:
          type: array
          items:
            $ref: '#/components/schemas/Payee'
        licensors:
          type: array
          items:
            type: object
    Payee:
      type: object
      properties:
        payeeId:
          type: string
        name:
          type: string
        paymentProviderId:
          type: string
        paymentProviderName:
          type: string
        paymentUserId:
          type: string
    RoyaltyTokenMintRequest:
      type: object
      properties:
        assetType:
          type: string
          enum: [track]
        assetId:
          type: string
        totalSupply:
          type: integer
        smartContractStandard:
          type: string
          enum: [ERC1155]
        payoutRate:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
        holders:
          type: array
          items:
            type: object
            properties:
              walletAddress:
                type: string
              friendlyName:
                type: string
              balance:
                type: integer
      required:
        - assetType
        - assetId
        - totalSupply
        - smartContractStandard
        - holders
    RoyaltyToken:
      type: object
      properties:
        tokenId:
          type: string
        assetId:
          type: string
        totalSupply:
          type: integer
        smartContractStandard:
          type: string
        status:
          type: string
        holders:
          type: array
          items:
            type: object