Dynamoi Data API

openapi: 3.2.0
info:
  description: Agent-facing paid data endpoints for sanitized Dynamoi machine-readable music royalty data. Paid resources use HTTP 402 and Stripe Machine Payments.
  title: Dynamoi Paid Machine Data API
  version: 2026-09
servers:
- url: https://dynamoi.com
tags:
- name: Data
paths:
  /api/data/mpp/v1/catalog:
    get:
      description: Free machine-readable catalog of paid datasets, schemas, samples, license terms, and MPP endpoints.
      responses:
        '200':
          description: Paid data catalog
      tags:
      - Data
      summary: Get api data mpp catalog
      x-summary-source: derived
      operationId: getApiDataMppV1Catalog
      x-operation-id-source: derived
  /api/data/mpp/v1/bundles/snapshot:
    get:
      description: Paid current snapshot bundle covering Master recording streaming rates (more families coming). Use format=jsonl, csv, or json. A request without a valid payment credential returns 402.
      operationId: getMusicRoyaltiesSnapshotBundle
      parameters:
      - in: query
        name: format
        required: false
        schema:
          enum:
          - jsonl
          - csv
          - json
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaidDataBundle'
            application/x-ndjson:
              schema:
                description: Newline-delimited JSON; each line is a PaidDataBundleRow.
                type: string
            text/csv:
              schema:
                description: CSV with a header row; columns are the PaidDataBundleRow keys in their declared order.
                type: string
          description: Paid bundle export response with MPP receipt metadata attached by the payment middleware.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SnapshotFormatProblem'
          description: Unsupported snapshot format. Use format=jsonl, csv, or json.
        '402':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/PaymentProblem'
          description: Machine Payments challenge. Agents must inspect every WWW-Authenticate Payment challenge to select and satisfy a supported payment method.
          headers:
            WWW-Authenticate:
              description: Payment challenge for Stripe Machine Payments Protocol (MPP).
              schema:
                type: string
      x-payment-info:
        offers:
        - amount: '14900'
          currency: usd
          description: One-time Stripe MPP charge for the current music royalties snapshot bundle covering Master recording streaming rates (more families coming).
          intent: charge
          method: stripe
      tags:
      - Data
      summary: Get music royalties snapshot bundle
      x-summary-source: derived
  /api/data/v1/checkout:
    post:
      description: Initiate a Stripe Checkout Session for interactive human browser purchase of the Launch Snapshot Bundle ($149). Strictly POST-only; GET requests return HTTP 405 Method Not Allowed.
      operationId: createDataCheckoutSession
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  checkoutUrl:
                    type: string
                  sessionId:
                    type: string
                type: object
          description: JSON response containing Stripe Checkout URL and session ID.
        '303':
          description: Redirect to Stripe Checkout for browser form submissions.
        '405':
          description: Method Not Allowed. GET is rejected to prevent crawlers from spawning checkout sessions.
      tags:
      - Data
      summary: Create data checkout session
      x-summary-source: derived
  /api/data/v1/publications/{publicationId}:
    get:
      description: Retrieve one published dataset family (a dataset's currentVersion in the catalog) with a monthly API key. Monthly subscriptions are available to purchase.
      operationId: getPaidDataPublication
      parameters:
      - in: path
        name: publicationId
        required: true
        schema:
          type: string
      - in: query
        name: format
        required: false
        schema:
          enum:
          - jsonl
          - csv
          - json
          type: string
      responses:
        '200':
          description: The publication in the requested format.
        '401':
          description: Missing or invalid API key.
        '403':
          description: The key's subscription does not cover this publication.
      security:
      - monthlyApiKey: []
      tags:
      - Data
      summary: Get paid data publication
      x-summary-source: derived
components:
  schemas:
    SnapshotFormatProblem:
      additionalProperties: false
      description: Unsupported paid snapshot format. Use one of the advertised formats.
      properties:
        error:
          const: Unsupported format
        openapiUrl:
          format: uri
          type: string
        supportedFormats:
          items:
            enum:
            - jsonl
            - csv
            - json
            type: string
          type: array
      required:
      - error
      - openapiUrl
      - supportedFormats
      type: object
    PaymentProblem:
      additionalProperties: true
      description: HTTP payment challenge body. Agents should parse WWW-Authenticate payment challenges as the source of truth.
      properties:
        detail:
          type: string
        status:
          const: 402
        title:
          type: string
        type:
          type: string
      type: object
    PaidDataFamilyArtifact:
      type: object
      properties:
        familySlug:
          type: string
          enum:
          - master-streaming-rpm
          - publishing-mechanical-rpm
          - publishing-performance-rpm
          - youtube-publishing-rpm
          - youtube-adsense-rpm
        formatVersion:
          type: string
          const: paid-data-family-v1
        licenseVersion:
          type: string
          minLength: 1
          maxLength: 128
        methodologyVersion:
          type: string
          minLength: 1
          maxLength: 128
        rows:
          minItems: 1
          type: array
          items:
            type: object
            properties:
              countryCode:
                type: string
                pattern: ^[A-Z]{2}$
              countryLabel:
                type: string
                minLength: 1
                maxLength: 128
              genreSlug:
                type: string
                maxLength: 128
                pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
              rights_category:
                type: string
                enum:
                - sound_recording_master
                - musical_work_mechanical
                - musical_work_performance
                - channel_owner_advertising
              rpmUsdPerThousand:
                type: number
                minimum: 0
              serviceLabel:
                type: string
                minLength: 1
                maxLength: 128
              serviceSlug:
                type: string
                maxLength: 128
                pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
              usage_category:
                type: string
                enum:
                - interactive_audio_streaming
                - youtube_video
                - youtube_monetized_video
              windowStartMonth:
                type: string
                pattern: ^\d{4}-(0[1-9]|1[0-2])$
              windowThroughMonth:
                type: string
                pattern: ^\d{4}-(0[1-9]|1[0-2])$
            required:
            - countryCode
            - countryLabel
            - rights_category
            - rpmUsdPerThousand
            - serviceLabel
            - serviceSlug
            - usage_category
            - windowStartMonth
            - windowThroughMonth
            additionalProperties: false
        sourceCutoff:
          type: string
          minLength: 1
          maxLength: 128
        taxonomyVersion:
          type: string
          minLength: 1
          maxLength: 128
      required:
      - familySlug
      - formatVersion
      - licenseVersion
      - methodologyVersion
      - rows
      - sourceCutoff
      - taxonomyVersion
      additionalProperties: false
    PaidDataBundle:
      additionalProperties: false
      description: 'format=json body: the bundle envelope with one immutable artifact per family. Rows carry rights_category and usage_category as separate fields.'
      properties:
        bundleFormatVersion:
          type: string
        families:
          items:
            additionalProperties: false
            properties:
              artifact:
                $ref: '#/components/schemas/PaidDataFamilyArtifact'
              publicationHash:
                pattern: ^[a-f0-9]{64}$
                type: string
              publicationId:
                type: string
            required:
            - artifact
            - publicationHash
            - publicationId
            type: object
          maxItems: 5
          minItems: 1
          type: array
        licenseVersion:
          type: string
        methodologyVersion:
          type: string
        taxonomyVersion:
          type: string
      required:
      - bundleFormatVersion
      - families
      - licenseVersion
      - methodologyVersion
      - taxonomyVersion
      type: object
  securitySchemes:
    monthlyApiKey:
      bearerFormat: dmd_ API key
      description: 'Monthly API subscription key, sent as `Authorization: Bearer dmd_<api-key>`. Monthly subscriptions are available to purchase.'
      scheme: bearer
      type: http
x-monthly-offers:
- code: machine_data_api_internal_monthly
  description: Monthly API access to every active royalty and benchmark dataset family. Internal analysis, RAG, and internal product use. No model training. No redistribution.
  displayName: Dynamoi Machine Data API - Internal (Monthly)
  licenseUrl: https://dynamoi.com/data-license#version-2026-09
  price:
    amountMinor: 49900
    currency: USD
    interval: month
    usd: '499.00'
  purchasable: true
  rights:
    analysisScopes:
    - INTERNAL
    internalProductUse: true
    modelTraining: false
    rag: true
    redistribution: false
  status: AVAILABLE
- code: machine_data_api_commercial_monthly
  description: Monthly API access to every active royalty and benchmark dataset family. Internal analysis, RAG, internal product use, and model training. No redistribution.
  displayName: Dynamoi Machine Data API - Commercial (Monthly)
  licenseUrl: https://dynamoi.com/data-license#version-2026-09
  price:
    amountMinor: 150000
    currency: USD
    interval: month
    usd: '1500.00'
  purchasable: true
  rights:
    analysisScopes:
    - INTERNAL
    internalProductUse: true
    modelTraining: true
    rag: true
    redistribution: false
  status: AVAILABLE
x-service-info:
  categories:
  - data
  - media
  - developer-tools
  docs:
    apiReference: https://dynamoi.com/openapi.json
    homepage: https://dynamoi.com/data