openapi: 3.1.0
info:
  title: Reson8 Speech-to-Text Auth Custom Models API
  version: v1
  description: 'Reson8 provides infrastructure-grade automatic speech recognition (ASR): realtime WebSocket streaming, prerecorded file transcription, speaker diarization, turn detection, and text-based custom-model domain adaptation. This OpenAPI description was transcribed by API Evangelist from the published documentation at https://docs.reson8.dev/api/ — Reson8 does not publish its own OpenAPI file. WebSocket endpoints (realtime, turns) are described here as GET upgrade operations with the x-reson8-transport extension; consult the docs for the full message protocol.'
  contact:
    name: Reson8 (Resonate Labs B.V.)
    url: https://www.reson8.dev/
  termsOfService: https://www.reson8.dev/terms
servers:
- url: https://api.reson8.dev
  description: Production
security:
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: Custom Models
  description: Domain adaptation via custom phrase models.
paths:
  /v1/custom-model:
    post:
      operationId: createCustomModel
      tags:
      - Custom Models
      summary: Create a custom model
      description: Create a new custom model with an initial, non-empty set of phrases.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomModelCreate'
            example:
              name: Cardiology
              description: Cardiology-specific terminology
              phrases:
              - myocardial infarction
              - atrial fibrillation
              - echocardiogram
      responses:
        '201':
          description: Custom model created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomModel'
              example:
                id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                name: Cardiology
                description: Cardiology-specific terminology
                phraseCount: 3
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
    get:
      operationId: listCustomModels
      tags:
      - Custom Models
      summary: List custom models
      description: List all custom models for the authenticated organization.
      responses:
        '200':
          description: Array of custom models.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomModel'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/custom-model/{id}:
    get:
      operationId: getCustomModel
      tags:
      - Custom Models
      summary: Get a custom model
      description: Fetch a single custom model by ID.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: ID of the custom model
      responses:
        '200':
          description: The custom model.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomModel'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/custom-model/{id}/phrases:
    get:
      operationId: listPhrases
      tags:
      - Custom Models
      summary: List phrases
      description: List the phrases in a custom model. Results are paginated with page/size.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: page
        in: query
        schema:
          type: number
          default: 0
        description: Zero-based page index
      - name: size
        in: query
        schema:
          type: number
          default: 100
          minimum: 1
          maximum: 10000
        description: Page size
      responses:
        '200':
          description: A page of phrases.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhrasePage'
              example:
                phrases:
                - value: myocardial infarction
                - value: atrial fibrillation
                page: 0
                size: 100
                total: 2
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: addPhrases
      tags:
      - Custom Models
      summary: Add phrases
      description: 'Add phrases to a custom model. Idempotent: phrases already present are left unchanged and reported as skipped.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhraseList'
            example:
              phrases:
              - pericarditis
              - atrial fibrillation
      responses:
        '200':
          description: Result of the add operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddPhrasesResult'
              example:
                added: 1
                skipped: 1
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/custom-model/{id}/phrases/delete:
    post:
      operationId: deletePhrases
      tags:
      - Custom Models
      summary: Delete phrases
      description: 'Remove phrases from a custom model by value. Idempotent: phrases not present are reported as skipped.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhraseList'
            example:
              phrases:
              - pericarditis
              - tachycardia
      responses:
        '200':
          description: Result of the delete operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletePhrasesResult'
              example:
                deleted: 1
                skipped: 1
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  responses:
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: INTERNAL_ERROR
    Unauthorized:
      description: Missing or invalid credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: UNAUTHORIZED
    InvalidRequest:
      description: Missing or invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: INVALID_REQUEST
    NotFound:
      description: Custom model not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: NOT_FOUND
  schemas:
    CustomModel:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        phraseCount:
          type: number
    CustomModelCreate:
      type: object
      required:
      - name
      - description
      - phrases
      properties:
        name:
          type: string
        description:
          type: string
        phrases:
          type: array
          items:
            type: string
          minItems: 1
    Phrase:
      type: object
      properties:
        value:
          type: string
    DeletePhrasesResult:
      type: object
      properties:
        deleted:
          type: number
        skipped:
          type: number
    Error:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code.
          enum:
          - INVALID_REQUEST
          - UNAUTHORIZED
          - NOT_FOUND
          - PAYLOAD_TOO_LARGE
          - INTERNAL_ERROR
    PhrasePage:
      type: object
      properties:
        phrases:
          type: array
          items:
            $ref: '#/components/schemas/Phrase'
        page:
          type: number
        size:
          type: number
        total:
          type: number
    PhraseList:
      type: object
      required:
      - phrases
      properties:
        phrases:
          type: array
          items:
            type: string
          minItems: 1
    AddPhrasesResult:
      type: object
      properties:
        added:
          type: number
        skipped:
          type: number
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Server-to-server. Value form: ApiKey <your_api_key>'
    BearerAuth:
      type: http
      scheme: bearer
      description: Short-lived access token from POST /v1/auth/token, for client-side use.
x-generated: '2026-07-20'
x-method: generated
x-source: https://docs.reson8.dev/api/ (transcribed verbatim from published REST reference)