Ditto Audio Licenses API

openapi: 3.2.0
info:
  title: ditto.audio Licenses 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: Licenses
  description: ditto-native desktop app — license activation & heartbeat
paths:
  /v1/licenses:
    post:
      operationId: DittoLicensesController_create
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLicenseDto'
      responses:
        '201':
          description: License created
      security:
      - bearer: []
      summary: Create a new license key
      tags:
      - Licenses
    get:
      operationId: DittoLicensesController_list
      parameters: []
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: List all license keys for the current user
      tags:
      - Licenses
  /v1/licenses/{id}:
    get:
      operationId: DittoLicensesController_findOne
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: Get a specific license with activations
      tags:
      - Licenses
  /v1/licenses/{id}/revoke:
    patch:
      operationId: DittoLicensesController_revoke
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: Revoke a license key (invalidates all activations)
      tags:
      - Licenses
  /v1/licenses/{id}/regenerate:
    post:
      operationId: DittoLicensesController_regenerate
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '201':
          description: ''
      security:
      - bearer: []
      summary: Generate a new key (old key invalid, all machines deactivated)
      tags:
      - Licenses
  /v1/licenses/{licenseId}/activations:
    get:
      operationId: DittoLicensesController_listActivations
      parameters:
      - name: licenseId
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: List all hardware activations for a license
      tags:
      - Licenses
  /v1/licenses/{licenseId}/activations/{id}/deactivate:
    patch:
      operationId: DittoLicensesController_deactivateActivation
      parameters:
      - name: licenseId
        required: true
        in: path
        schema:
          type: string
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: Deactivate a specific hardware slot (frees a seat)
      tags:
      - Licenses
  /v1/licenses/{licenseId}/activations/{id}/reactivate:
    patch:
      operationId: DittoLicensesController_reactivateActivation
      parameters:
      - name: licenseId
        required: true
        in: path
        schema:
          type: string
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: Re-activate a previously deactivated hardware slot
      tags:
      - Licenses
  /v1/licenses/{licenseId}/activations/{id}/remove:
    patch:
      operationId: DittoLicensesController_removeActivation
      parameters:
      - name: licenseId
        required: true
        in: path
        schema:
          type: string
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '204':
          description: ''
      security:
      - bearer: []
      summary: Permanently remove a hardware activation entry
      tags:
      - Licenses
components:
  schemas:
    CreateLicenseDto:
      type: object
      properties:
        tier:
          type: string
          enum:
          - starter
          - pro
          - enterprise
          default: pro
        productId:
          type: string
          example: ditto-native
        maxActivations:
          type: number
          example: 5
          description: Max simultaneous hardware activations
        expiresAt:
          type: string
          example: '2027-12-31T23:59:59Z'
          description: Expiry date (null = perpetual)
        metadata:
          type: object
          example:
            org: acme
            plan: team
          description: Arbitrary app-specific metadata stored on the license
  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.