Ditto Audio Products API

openapi: 3.2.0
info:
  title: ditto.audio Products API
  description: Cloud API behind ditto.audio. The reader (reader.ditto.audio) and the voice studio (studio.ditto.audio) are separate apps sharing this one backend — see /docs/reader and /docs/inference for each app’s public surface. Third-party integrations want /docs/public (rendered for humans at https://ditto.audio/docs).
  version: '1.0'
  contact: {}
servers: []
tags:
- name: Products
  description: Desktop products — the Ditto app & DAW plugins as one-time purchases; unlocked by any active plan too
paths:
  /v1/products:
    get:
      operationId: ProductsController_list
      parameters:
      - name: locale
        required: false
        in: query
        description: The site page's language for taglines, descriptions, features and formats (else English). Names, prices and ids are never translated.
        schema:
          type: string
      responses:
        '200':
          description: ''
      summary: Public desktop-product catalog (app + DAW plugins) + whether billing is live
      tags:
      - Products
  /v1/products/mine:
    get:
      operationId: ProductsController_mine
      parameters: []
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: Which products the current user has, and why (purchase / app / subscription)
      tags:
      - Products
  /v1/products/entitlement:
    post:
      description: Called by the Ditto desktop app after sign-in and on refresh. The token lists every product the account has on this machine (purchases + an active plan) and is verified offline by the app and each plugin with the embedded public key. The machine takes one of the account’s seats (DESKTOP_MAX_MACHINES); over the cap the call answers 403 with code MACHINE_LIMIT and no token.
      operationId: ProductsController_entitlement
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitlementDto'
      responses:
        '201':
          description: ''
      security:
      - bearer: []
      summary: Issue the signed desktop entitlement token for this machine
      tags:
      - Products
  /v1/products/updates:
    get:
      description: The Ditto app checks here (with its session) instead of the public releases host; 403 NO_DESKTOP_PRODUCT otherwise.
      operationId: ProductsController_updates
      parameters: []
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: The desktop update manifest, for accounts that own a desktop product or hold a…
      tags:
      - Products
  /v1/products/downloads:
    get:
      description: 'The store’s download buttons: the Ditto app zip for any account that has a product, and each plugin’s VST3 / AU zips only for an account that has that plugin (purchase, the app, or an active plan). Urls are presigned per request; `version` is null when there is nothing to download.'
      operationId: ProductsController_downloads
      parameters: []
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: What this account may download from the current desktop release
      tags:
      - Products
  /v1/products/plugin-update:
    get:
      description: 'Asked by a sold plugin with its own session: ?product=ditto-voice&platform=darwin-arm64&format=au&version=1.0.3. Answers `update: null` (with a reason) or the signed update record plus a presigned url for that one zip. 403 NOT_ON_ACCOUNT for an account without the plugin.'
      operationId: ProductsController_pluginUpdate
      parameters: []
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: Whether a newer signed build of this plugin is in the current release…
      tags:
      - Products
  /v1/products/machines:
    get:
      operationId: ProductsController_machines
      parameters: []
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: The computers this account keeps its desktop products unlocked on
      tags:
      - Products
  /v1/products/machines/{machineId}/checkin:
    post:
      description: Called every minute by a signed-in Ditto app with the products installed and when each last ran. Answers `removed` once the computer was taken off the account on the web; the app then fetches its entitlement, which is the revoked token that locks the app and every plugin there.
      operationId: ProductsController_checkIn
      parameters:
      - name: machineId
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckInDto'
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: 'The running Ditto app checks in: is this computer still on the account?'
      tags:
      - Products
  /v1/products/machines/{machineId}:
    delete:
      description: 'An online Ditto app learns it at its next minute check-in and receives a revoked token: the app and every plugin there lock and say the computer was removed. Signing in on it again reclaims a seat when one is free.'
      operationId: ProductsController_removeMachine
      parameters:
      - name: machineId
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: Remove a computer from this account (frees its seat)
      tags:
      - Products
  /v1/products/checkout:
    post:
      operationId: ProductsController_checkout
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductCheckoutDto'
      responses:
        '201':
          description: ''
      security:
      - bearer: []
      summary: Create a one-time Stripe checkout session for a product
      tags:
      - Products
components:
  schemas:
    ProductCheckoutDto:
      type: object
      properties: {}
    CheckInDto:
      type: object
      properties: {}
    EntitlementDto:
      type: object
      properties: {}
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: ditto_sk_live_… API key, ditto_oat_… OAuth access token, or a session JWT
      type: http
      description: An API key (`ditto_sk_live_…`, made at https://ditto.audio/account/api-keys) authenticates /v1/audio/* and /v1/reader/*; an OAuth connection's one-hour access token (`ditto_oat_…`) holds the audio:read and audio:speech scopes only. Account routes (/v1/api-keys, /v1/usage, /v1/subscription) take the signed-in session's token (a JWT) only.