openapi: 3.1.0
info:
  title: Koldan
  description: Speech Recognition Platform
  version: 1.0.0
externalDocs:
  description: Koldan Documentation
  url: https://www.dixilang.com/koldan-docs/
servers:
- url: https://koldan.dixilang.com
  description: Koldan Cloud
- url: http://localhost:8193
  description: Local Koldan Deployment
security:
- bearerAuth: []
- apiKey: []
tags:
- name: Users - Lookup
  description: Search tenant users for collaboration.
- name: Speech - Transcriptions
  description: Manage speech transcription jobs.
- name: Subscriptions - Plans
  description: View available subscription plans
- name: MySubscription
  description: View the caller's subscription.
- name: Sentence Verification - Models
  description: Discover available sentence verification model aliases. All model identifiers
    are aliases that resolve to concrete model versions.
- name: Speaker Services - Enrollments
  description: Manage speaker enrollment records.
- name: Speech - Files - Sharing
  description: Manage direct user shares on speech files.
- name: Speech - Files
  description: Manage media files for speech services.
- name: Tags
  description: Manage user-scoped tags
- name: API Keys
  description: "Create, rotate and revoke API keys."
- name: Permissions - Effective
  description: Inspect the caller's effective permissions.
- name: Speaker Services - Speakers
  description: Manage speaker identities and lifecycle.
- name: Speaker Embeddings - Models
  description: Discover available speaker embedding model aliases.
- name: Languages
  description: Manage supported languages.
- name: Speech - Summaries
  description: Manage AI-generated summaries for speech files.
- name: Quotas
  description: Monitor and manage resource usage quotas
- name: Speech - Streaming Sessions
  description: Manage online speech recognition streaming sessions.
- name: Data Retention
  description: Monitor data retention policies
- name: Speaker Verification Service - Analytics
  description: "Pre-aggregated verification statistics by time period, speaker, model,\
    \ and voice print."
- name: Site Properties
  description: Global site configuration properties.
- name: Authentication
  description: User authentication and token issuance.
- name: Speech - Models
  description: Browse available speech models. All model identifiers are aliases that
    resolve to concrete model versions.
- name: Speaker Verification Service - Verifications
  description: Perform synchronous speaker verification and manage retained records.
- name: Speaker Services - Voice Prints
  description: Manage speaker voice prints.
- name: Rate Limits
  description: Monitor and manage API rate limits
paths:
  /api/v1/speech-services/transcriptions/{id}/webhook:
    put:
      tags:
      - Speech - Transcriptions
      summary: Update job webhook
      description: Set or update the webhook configuration for an existing job
      operationId: updateWebhook
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CommonWebhook"
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeechServiceTranscriptionJobResponse"
    delete:
      tags:
      - Speech - Transcriptions
      summary: Delete job webhook
      description: Remove the webhook configuration from an existing job
      operationId: deleteWebhook
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "204":
          description: Webhook removed
  /api/v1/speech-services/summaries/{id}/webhook:
    put:
      tags:
      - Speech - Summaries
      summary: Update summary webhook
      description: Set or update the webhook configuration for an existing summary
      operationId: updateWebhook_1
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CommonWebhook"
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeechServiceSummaryResponse"
    delete:
      tags:
      - Speech - Summaries
      summary: Delete summary webhook
      description: Remove the webhook configuration from an existing summary
      operationId: deleteWebhook_1
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "204":
          description: Webhook removed
  /api/v1/languages/{name}:
    get:
      tags:
      - Languages
      summary: Get a language by name
      description: Retrieve a language by its unique name.
      operationId: getLanguageByName
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Language found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LanguageDTO"
        "404":
          description: Language not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LanguageDTO"
    put:
      tags:
      - Languages
      summary: Update an existing language
      description: Update the details of an existing language by its name.
      operationId: updateLanguage
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LanguageUpdateDTO"
        required: true
      responses:
        "200":
          description: Language updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LanguageDTO"
        "404":
          description: Language not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LanguageDTO"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LanguageDTO"
    delete:
      tags:
      - Languages
      summary: Delete a language
      description: Delete a language by its name.
      operationId: deleteLanguage
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Language deleted
        "404":
          description: Language not found
        "500":
          description: Internal Server Error
  /api/v1/tags/validate:
    post:
      tags:
      - Tags
      summary: Validate tag name
      description: Validate a tag display name and check whether it already exists
        for the current user
      operationId: validateTagName
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TagValidationRequest"
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TagValidationResponse"
  /api/v1/speech-services/transcriptions:
    get:
      tags:
      - Speech - Transcriptions
      summary: List transcription jobs
      description: "Retrieve a paginated list of transcription jobs. By default returns\
        \ only the current user's jobs. When fileId is specified, returns all transcriptions\
        \ for that file (requires READ access to the file, enabling discovery of transcriptions\
        \ on shared files)."
      operationId: listJobs
      parameters:
      - name: page
        in: query
        description: Page number (zero-based)
        required: false
        schema:
          type: integer
          format: int32
          default: 0
      - name: size
        in: query
        description: Page size (max 100)
        required: false
        schema:
          type: integer
          format: int32
          default: 20
      - name: status
        in: query
        description: Filter by job status (comma-separated)
        required: false
        schema:
          type: array
          items:
            type: string
      - name: fileId
        in: query
        description: "Filter by source file ID. When specified for a shared file,\
          \ returns all transcriptions for that file (requires READ access to the\
          \ file)."
        required: false
        schema:
          type: string
          format: uuid
      - name: isDeleted
        in: query
        description: Filter by deleted state
        required: false
        schema:
          type: boolean
          default: false
      - name: createdAfter
        in: query
        description: Return jobs created on or after this timestamp
        required: false
        schema:
          type: string
          format: date-time
      - name: createdBefore
        in: query
        description: Return jobs created on or before this timestamp
        required: false
        schema:
          type: string
          format: date-time
      - name: completedAfter
        in: query
        description: Return jobs completed on or after this timestamp
        required: false
        schema:
          type: string
          format: date-time
      - name: completedBefore
        in: query
        description: Return jobs completed on or before this timestamp
        required: false
        schema:
          type: string
          format: date-time
      - name: itnRequested
        in: query
        description: Filter by ITN requested
        required: false
        schema:
          type: boolean
      - name: punctuationRequested
        in: query
        description: Filter by punctuation requested
        required: false
        schema:
          type: boolean
      - name: capitalizationRequested
        in: query
        description: Filter by capitalization requested
        required: false
        schema:
          type: boolean
      - name: diarizationRequested
        in: query
        description: Filter by diarization requested
        required: false
        schema:
          type: boolean
      - name: sort
        in: query
        description: "Sort field and direction (e.g. creationDate,desc)"
        required: false
        schema:
          type: string
          default: "creationDate,desc"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeechServiceTranscriptionJobsListResponse"
    post:
      tags:
      - Speech - Transcriptions
      summary: Create transcription job
      description: Submit a new speech processing job for an uploaded file
      operationId: createJob
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SpeechServiceTranscriptionJobRequest"
        required: true
      responses:
        "201":
          description: Transcription job created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeechServiceTranscriptionJobResponse"
  /api/v1/speech-services/transcriptions/{id}/purge:
    post:
      tags:
      - Speech - Transcriptions
      summary: Purge transcription job
      description: Permanently purge result/error data of a deleted job. Irreversible.
      operationId: purgeJob
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "204":
          description: Job purged
  /api/v1/speech-services/transcriptions/{id}/cancel:
    post:
      tags:
      - Speech - Transcriptions
      summary: Cancel transcription job
      description: Cancel a pending or in-progress transcription job
      operationId: cancelJob
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "204":
          description: Job cancelled
  /api/v1/speech-services/transcriptions/upload:
    post:
      tags:
      - Speech - Transcriptions
      summary: Upload file and create transcription job
      description: "Upload a media file (or import from URI) and immediately start\
        \ a transcription job in one step. Provide either 'file' (multipart) or 'uri'\
        \ (string), but not both. Optionally provide 'summary' to schedule a summary\
        \ job that runs after transcription completes."
      operationId: uploadAndTranscribe
      parameters:
      - name: generateListeningAudio
        in: query
        required: false
        schema:
          type: boolean
          default: true
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                uri:
                  type: string
                name:
                  type: string
                description:
                  type: string
                path:
                  type: string
                metadata:
                  type: string
                transcription:
                  type: string
                diarization:
                  type: string
                webhook:
                  type: string
                summary:
                  type: string
                tags:
                  type: string
              required:
              - name
              - transcription
      responses:
        "201":
          description: Successfully uploaded and job created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeechServiceUploadAndTranscribeResponse"
        "400":
          description: "Invalid request (e.g. missing both file and URI, or invalid\
            \ JSON)"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeechServiceUploadAndTranscribeResponse"
        "403":
          description: Forbidden - missing required scope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeechServiceUploadAndTranscribeResponse"
        "404":
          description: Not found (e.g. user profile not found)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeechServiceUploadAndTranscribeResponse"
        "429":
          description: Too many requests - rate limit exceeded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeechServiceUploadAndTranscribeResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeechServiceUploadAndTranscribeResponse"
  /api/v1/speech-services/summaries:
    get:
      tags:
      - Speech - Summaries
      summary: List summaries
      description: "Retrieve a paginated list of summaries. By default returns only\
        \ the current user's summaries. When fileId is specified, returns all summaries\
        \ for that file's transcriptions (requires READ access to the file, enabling\
        \ discovery of summaries on shared files). When transcriptionId is specified,\
        \ returns all summaries for that transcription (requires READ access to the\
        \ parent file)."
      operationId: listSummaries
      parameters:
      - name: transcriptionId
        in: query
        description: "Filter by transcription ID. When specified, returns all summaries\
          \ for that transcription (requires READ access to the parent file)."
        required: false
        schema:
          type: string
          format: uuid
      - name: fileId
        in: query
        description: "Filter by file ID. When specified for a shared file, returns\
          \ all summaries for that file's transcriptions (requires READ access to\
          \ the file)."
        required: false
        schema:
          type: string
          format: uuid
      - name: page
        in: query
        description: Page number (zero-based)
        required: false
        schema:
          type: integer
          format: int32
          default: 0
      - name: size
        in: query
        description: Page size (max 100)
        required: false
        schema:
          type: integer
          format: int32
          default: 20
      - name: status
        in: query
        description: Filter by summary status (comma-separated)
        required: false
        schema:
          type: array
          items:
            type: string
      - name: promptTemplateId
        in: query
        description: Filter by prompt template ID
        required: false
        schema:
          type: string
          format: uuid
      - name: isDeleted
        in: query
        description: Filter by deleted state
        required: false
        schema:
          type: boolean
          default: false
      - name: createdAfter
        in: query
        description: Return summaries created on or after this timestamp
        required: false
        schema:
          type: string
          format: date-time
      - name: createdBefore
        in: query
        description: Return summaries created on or before this timestamp
        required: false
        schema:
          type: string
          format: date-time
      - name: completedAfter
        in: query
        description: Return summaries completed on or after this timestamp
        required: false
        schema:
          type: string
          format: date-time
      - name: completedBefore
        in: query
        description: Return summaries completed on or before this timestamp
        required: false
        schema:
          type: string
          format: date-time
      - name: sort
        in: query
        description: "Sort field and direction (e.g. creationDate,desc)"
        required: false
        schema:
          type: string
          default: "creationDate,desc"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeechServiceSummaryListResponse"
    post:
      tags:
      - Speech - Summaries
      summary: Create summary
      description: Generate an AI summary for a completed transcription
      operationId: createSummary
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SpeechServiceSummaryRequest"
        required: true
      responses:
        "201":
          description: Summary created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeechServiceSummaryResponse"
  /api/v1/speech-services/summaries/{id}/purge:
    post:
      tags:
      - Speech - Summaries
      summary: Purge summary
      description: Permanently purge result/error data of a deleted summary. Irreversible.
      operationId: purgeSummary
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "204":
          description: Summary purged
  /api/v1/speech-services/summaries/{id}/cancel:
    post:
      tags:
      - Speech - Summaries
      summary: Cancel summary
      description: Cancel a pending or in-progress summary generation
      operationId: cancelSummary
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "204":
          description: Summary cancelled
  /api/v1/speech-services/streams/{sessionId}/purge:
    post:
      tags:
      - Speech - Streaming Sessions
      summary: Purge session content
      description: Permanently deletes all transcript segments from the database and
        the audio recording from storage (if recorded and not already purged). The
        session metadata is preserved with isPurged=true and continues to count toward
        quota.
      operationId: purgeSessionContent
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "204":
          description: Session content purged
  /api/v1/speech-services/files:
    get:
      tags:
      - Speech - Files
      summary: List files
      description: Retrieve a paginated list of media files for the current user
      operationId: listFiles
      parameters:
      - name: page
        in: query
        description: Page number (zero-based)
        required: false
        schema:
          type: integer
          format: int32
          default: 0
      - name: size
        in: query
        description: Page size (max 100)
        required: false
        schema:
          type: integer
          format: int32
          default: 20
      - name: isDeleted
        in: query
        description: Filter by deleted state
        required: false
        schema:
          type: boolean
          default: false
      - name: isContentDiscarded
        in: query
        description: Filter by content discarded state
        required: false
        schema:
          type: boolean
      - name: ingestionStatus
        in: query
        description: Filter by ingestion status (comma-separated)
        required: false
        schema:
          type: array
          items:
            type: string
      - name: name
        in: query
        description: Partial case-insensitive search on file name
        required: false
        schema:
          type: string
      - name: filename
        in: query
        description: Partial case-insensitive search on filename
        required: false
        schema:
          type: string
      - name: sha256
        in: query
        description: Filter by SHA-256 checksum (exact match)
        required: false
        schema:
          type: string
      - name: createdAfter
        in: query
        description: Return files created on or after this timestamp
        required: false
        schema:
          type: string
          format: date-time
      - name: createdBefore
        in: query
        description: Return files created on or before this timestamp
        required: false
        schema:
          type: string
          format: date-time
      - name: listeningAudio.status
        in: query
        description: Filter by listening audio status (comma-separated)
        required: false
        schema:
          type: array
          items:
            type: string
      - name: listeningAudio.deleted
        in: query
        description: Filter by listening audio deleted state
        required: false
        schema:
          type: boolean
      - name: listeningAudio.contentDiscarded
        in: query
        description: Filter by listening audio content discarded state
        required: false
        schema:
          type: boolean
      - name: path
        in: query
        description: Virtual directory path to list. Must start and end with '/'
        required: false
        schema:
          type: string
          default: /
      - name: recursive
        in: query
        description: "If true, list all descendants recursively. If false, list only\
          \ direct children"
        required: false
        schema:
          type: boolean
          default: false
      - name: sort
        in: query
        description: "Sort field and direction (e.g. creationDate,desc)"
        required: false
        schema:
          type: string
          default: "creationDate,desc"
      - name: tags
        in: query
        description: "Filter by tags (comma-separated display names, case-insensitive)"
        required: false
        schema:
          type: array
          items:
            type: string
      - name: tagsMatch
        in: query
        description: "Tag match mode: 'all' requires every tag (AND), 'any' requires\
          \ at least one (OR). Default: all"
        required: false
        schema:
          type: string
          default: all
      - name: publishMode
        in: query
        description: "Filter by publish mode: PRIVATE or INTERNAL"
        required: false
        schema:
          type: string
          description: Controls the visibility scope of a file
          enum:
          - PRIVATE
          - INTERNAL
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeechServiceFilesListResponse"
    post:
      tags:
      - Speech - Files
      summary: Upload file
      description: "Create a new media file via multipart form. Provide either 'file'\
        \ for direct upload or 'uri' for remote import, but not both."
      operationId: uploadFile
      parameters:
      - name: generateListeningAudio
        in: query
        required: false
        schema:
          type: boolean
          default: true
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                uri:
                  type: string
                name:
                  type: string
                description:
                  type: string
                path:
                  type: string
                metadata:
                  type: string
                tags:
                  type: string
              required:
              - name
      responses:
        "201":
          description: File created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeechServiceFileResponse"
  /api/v1/speech-services/files/{id}/listening-audio/purge:
    post:
      tags:
      - Speech - Files
      summary: Purge listening audio
      description: Permanently remove the listening audio binary content to free storage.
        The listening audio metadata remains on the file record.
      operationId: purgeListeningAudio
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "204":
          description: Listening audio content purged
  /api/v1/speech-services/files/{id}/listening-audio/generate:
    post:
      tags:
      - Speech - Files
      summary: Generate listening audio
      description: "Trigger listening audio generation for a file that does not yet\
        \ have listening audio, or retry after a failed attempt."
      operationId: generateListeningAudio
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "202":
          description: Listening audio generation accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeechServiceFileResponse"
  /api/v1/speech-services/files/{id}/discard-content:
    post:
      tags:
      - Speech - Files
      summary: Discard file content
      description: Remove the binary content of a file to free storage. Metadata and
        associated data remain accessible.
      operationId: discardContent
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "204":
          description: File content discarded
  /api/v1/speech-services/files/{fileId}/shares:
    get:
      tags:
      - Speech - Files - Sharing
      summary: List shares for a file
      description: Retrieve all direct user shares for a file. Only the file owner
        can list shares.
      operationId: listShares
      parameters:
      - name: fileId
        in: path
        description: UUID of the file
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "200":
          description: Shares retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeechServiceFileShareListResponse"
        "404":
          description: File not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeechServiceFileShareListResponse"
    post:
      tags:
      - Speech - Files - Sharing
      summary: Share a file with a user
      description: "Grant a user access to a file with VIEW or EDIT permission. If\
        \ a share already exists for the target user, the permission is updated (returns\
        \ 200). Otherwise a new share is created (returns 201). The target user must\
        \ belong to the same tenant."
      operationId: addShare
      parameters:
      - name: fileId
        in: path
        description: UUID of the file
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SpeechServiceFileShareRequest"
        required: true
      responses:
        "201":
          description: Share created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeechServiceFileShareResponse"
        "200":
          description: Existing share updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeechServiceFileShareResponse"
        "400":
          description: "Invalid request (e.g. sharing with yourself, user not found)"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeechServiceFileShareResponse"
        "404":
          description: File not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeechServiceFileShareResponse"
  /api/v1/speaker-services/speaker-verification/voice-prints/{voicePrintId}/set-default:
    post:
      tags:
      - Speaker Services - Voice Prints
      summary: Set default voice print
      operationId: setDefaultSpeakerVerificationServiceVoicePrint
      parameters:
      - name: voicePrintId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeakerVerificationServiceVoicePrintResponse"
  /api/v1/speaker-services/speaker-verification/voice-prints/{voicePrintId}/purge:
    post:
      tags:
      - Speaker Services - Voice Prints
      summary: Purge voice print
      operationId: purgeSpeakerVerificationServiceVoicePrint
      parameters:
      - name: voicePrintId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "204":
          description: Voice print purged
  /api/v1/speaker-services/speaker-verification/voice-prints/{voicePrintId}/activate:
    post:
      tags:
      - Speaker Services - Voice Prints
      summary: Activate voice print
      operationId: activateSpeakerVerificationServiceVoicePrint
      parameters:
      - name: voicePrintId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeakerVerificationServiceVoicePrintResponse"
  /api/v1/speaker-services/speaker-verification/verifications:
    get:
      tags:
      - Speaker Verification Service - Verifications
      summary: List verifications
      operationId: listSpeakerVerificationServiceVerifications
      parameters:
      - name: speakerId
        in: query
        required: false
        schema:
          type: string
          format: uuid
      - name: decision
        in: query
        required: false
        schema:
          type: array
          items:
            $ref: "#/components/schemas/SpeakerVerificationDecision"
      - name: status
        in: query
        required: false
        schema:
          type: array
          items:
            $ref: "#/components/schemas/SpeakerVerificationServiceVerificationRecordStatus"
      - name: createdAfter
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: createdBefore
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: isDeleted
        in: query
        required: false
        schema:
          type: boolean
          default: false
      - name: page
        in: query
        description: Page number
        required: false
        schema:
          type: integer
          format: int32
          default: 0
      - name: size
        in: query
        description: Page size
        required: false
        schema:
          type: integer
          format: int32
          default: 20
      - name: sort
        in: query
        required: false
        schema:
          type: string
          default: "createdAt,desc"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeakerVerificationServiceVerificationsListResponse"
    post:
      tags:
      - Speaker Verification Service - Verifications
      summary: Verify speaker
      description: "The file or URI content must be WAV audio containing PCM S16LE,\
        \ mono, 16 kHz. The server stores the WAV and uses extracted PCM internally."
      operationId: verifySpeaker
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                speakerId:
                  type: string
                file:
                  type: string
                  format: binary
                uri:
                  type: string
                uriHeaders:
                  type: string
                segment:
                  type: string
                thresholdPolicy:
                  type: string
                model:
                  type: string
                sentenceVerification:
                  type: string
                metadata:
                  type: string
              required:
              - speakerId
      responses:
        "201":
          description: Verification created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeakerVerificationServiceVerificationResponse"
  /api/v1/speaker-services/speaker-verification/verifications/{verificationId}/purge:
    post:
      tags:
      - Speaker Verification Service - Verifications
      summary: Purge verification
      operationId: purgeSpeakerVerificationServiceVerification
      parameters:
      - name: verificationId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "204":
          description: Verification purged
  /api/v1/speaker-services/speaker-verification/speakers:
    get:
      tags:
      - Speaker Services - Speakers
      summary: List speakers
      operationId: listSpeakerVerificationServiceSpeakers
      parameters:
      - name: page
        in: query
        description: Page number
        required: false
        schema:
          type: integer
          format: int32
          default: 0
      - name: size
        in: query
        description: Page size
        required: false
        schema:
          type: integer
          format: int32
          default: 20
      - name: status
        in: query
        required: false
        schema:
          type: array
          items:
            $ref: "#/components/schemas/SpeakerVerificationServiceSpeakerStatus"
      - name: verificationStatus
        in: query
        required: false
        schema:
          type: array
          items:
            $ref: "#/components/schemas/SpeakerVerificationServiceVerificationStatus"
      - name: name
        in: query
        required: false
        schema:
          type: string
      - name: externalRef
        in: query
        required: false
        schema:
          type: string
      - name: tags
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
      - name: createdAfter
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: createdBefore
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: voicePrintModel
        in: query
        required: false
        schema:
          type: string
      - name: voicePrintModelAlias
        in: query
        required: false
        schema:
          type: string
      - name: voicePrintModelStatus
        in: query
        required: false
        schema:
          $ref: "#/components/schemas/SpeakerEmbeddingModelStatus"
      - name: isDeleted
        in: query
        required: false
        schema:
          type: boolean
          default: false
      - name: sort
        in: query
        required: false
        schema:
          type: string
          default: "creationDate,desc"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeakerVerificationServiceSpeakersListResponse"
    post:
      tags:
      - Speaker Services - Speakers
      summary: Create speaker
      operationId: createSpeakerVerificationServiceSpeaker
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SpeakerVerificationServiceCreateSpeakerRequest"
        required: true
      responses:
        "201":
          description: Speaker created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeakerVerificationServiceSpeakerResponse"
  /api/v1/speaker-services/speaker-verification/speakers/{speakerId}/voice-prints:
    post:
      tags:
      - Speaker Services - Voice Prints
      summary: Create voice print
      operationId: createSpeakerVerificationServiceVoicePrint
      parameters:
      - name: speakerId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SpeakerVerificationServiceCreateVoicePrintRequest"
      responses:
        "200":
          description: Existing active voice print returned
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeakerVerificationServiceVoicePrintResponse"
        "201":
          description: Voice print created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeakerVerificationServiceVoicePrintResponse"
  /api/v1/speaker-services/speaker-verification/speakers/{speakerId}/voice-prints/preview:
    post:
      tags:
      - Speaker Services - Voice Prints
      summary: Preview voice print quality
      operationId: previewSpeakerVerificationServiceVoicePrintQuality
      parameters:
      - name: speakerId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SpeakerVerificationServiceVoicePrintPreviewRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeakerVerificationServiceVoicePrintPreviewResponse"
  /api/v1/speaker-services/speaker-verification/speakers/{speakerId}/enrollments:
    get:
      tags:
      - Speaker Services - Enrollments
      summary: List enrollments
      operationId: listSpeakerVerificationServiceEnrollments
      parameters:
      - name: speakerId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: status
        in: query
        required: false
        schema:
          type: array
          items:
            $ref: "#/components/schemas/SpeakerVerificationServiceEnrollmentStatus"
      - name: isDeleted
        in: query
        required: false
        schema:
          type: boolean
          default: false
      - name: page
        in: query
        description: Page number
        required: false
        schema:
          type: integer
          format: int32
          default: 0
      - name: size
        in: query
        description: Page size
        required: false
        schema:
          type: integer
          format: int32
          default: 20
      - name: sort
        in: query
        required: false
        schema:
          type: string
          default: "creationDate,desc"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeakerVerificationServiceEnrollmentsListResponse"
    post:
      tags:
      - Speaker Services - Enrollments
      summary: Create enrollment
      description: "The file or URI content must be WAV audio containing PCM S16LE,\
        \ mono, 16 kHz. The server stores the WAV and uses extracted PCM internally."
      operationId: createSpeakerVerificationServiceEnrollment
      parameters:
      - name: speakerId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                uri:
                  type: string
                label:
                  type: string
                segment:
                  type: string
                sentenceVerification:
                  type: string
                webhook:
                  type: string
      responses:
        "201":
          description: Enrollment created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeakerVerificationServiceEnrollmentResponse"
  /api/v1/speaker-services/speaker-verification/speakers/{speakerId}/enrollments/{enrollmentId}/purge:
    post:
      tags:
      - Speaker Services - Enrollments
      summary: Purge enrollment
      operationId: purgeSpeakerVerificationServiceEnrollment
      parameters:
      - name: speakerId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: enrollmentId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "204":
          description: Enrollment purged
  /api/v1/speaker-services/speaker-verification/speakers/{speakerId}/enrollments/reset:
    post:
      tags:
      - Speaker Services - Enrollments
      summary: Reset speaker enrollments
      operationId: resetSpeakerVerificationServiceEnrollments
      parameters:
      - name: speakerId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SpeakerVerificationServiceEnrollmentResetRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeakerVerificationServiceEnrollmentResetResponse"
  /api/v1/speaker-services/speaker-verification/speakers/{id}/purge:
    post:
      tags:
      - Speaker Services - Speakers
      summary: Purge speaker
      operationId: purgeSpeakerVerificationServiceSpeaker
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "204":
          description: Speaker purged
  /api/v1/languages:
    get:
      tags:
      - Languages
      summary: Get all languages
      description: Retrieve a list of all available languages.
      operationId: getAllLanguages
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LanguageDTO"
        "204":
          description: No languages found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/LanguageDTO"
    post:
      tags:
      - Languages
      summary: Create a new language
      description: Create a new language with the given details.
      operationId: createLanguage
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LanguageDTO"
        required: true
      responses:
        "201":
          description: Language created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LanguageDTO"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LanguageDTO"
  /api/v1/auth/refresh-token:
    post:
      tags:
      - Authentication
      summary: Refresh access token
      description: Refreshes an access token using a refresh token provided in the
        request body.
      operationId: refreshAccessToken
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RefreshTokenRequest"
        required: true
      responses:
        "200":
          description: Access token successfully refreshed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthTokenResponse"
        "400":
          description: Failed to refresh access token
          content:
            application/json:
              schema:
                type: string
  /api/v1/auth/logout:
    post:
      tags:
      - Authentication
      summary: Log out a user
      description: Logs out a user by invalidating their refresh token.
      operationId: logout
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LogoutRequest"
        required: true
      responses:
        "200":
          description: User successfully logged out
          content:
            application/json:
              schema:
                type: object
        "400":
          description: Logout failed
  /api/v1/auth/login:
    post:
      tags:
      - Authentication
      summary: Log in user
      description: Log in a user by username and password
      operationId: login
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LoginRequest"
        required: true
      responses:
        "200":
          description: Successful login
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthTokenResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                type: object
  /api/v1/auth/exchange-auth-code:
    post:
      tags:
      - Authentication
      summary: Exchange Authorization Code for Token
      description: "Exchange an authorization code for an access token, with an optional\
        \ PKCE code verifier."
      operationId: exchangeAuthorizationCode
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UnifiedLoginRequest"
        required: true
      responses:
        "200":
          description: Successful token exchange
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthTokenResponse"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
        "503":
          description: Service Unavailable
          content:
            application/json:
              schema:
                type: object
  /api/v1/api-keys:
    get:
      tags:
      - API Keys
      summary: List all API keys
      description: Lists all API keys for the authenticated user.
      operationId: listApiKeys
      responses:
        "200":
          description: List of API keys
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiKeyResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiKeyResponse"
    post:
      tags:
      - API Keys
      summary: Create a new API key
      description: Creates a new API key for the authenticated user. The plain text
        key is only returned once.
      operationId: createApiKey
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApiKeyCreateRequest"
        required: true
      responses:
        "201":
          description: API key created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiKeyResponse"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiKeyResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiKeyResponse"
        "429":
          description: Active API key limit reached for this user
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiKeyResponse"
  /api/v1/speech-services/files/{id}:
    get:
      tags:
      - Speech - Files
      summary: Get file
      description: Retrieve metadata for a single media file
      operationId: getFile
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeechServiceFileResponse"
    delete:
      tags:
      - Speech - Files
      summary: Delete file
      description: Soft-delete a file and all associated data. Use ?purge=true for
        immediate permanent removal.
      operationId: deleteFile
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: purge
        in: query
        description: Immediately purge all data
        required: false
        schema:
          type: boolean
          default: false
      responses:
        "204":
          description: File deleted
    patch:
      tags:
      - Speech - Files
      summary: Update file
      description: Update the metadata of an existing media file
      operationId: updateFile
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SpeechServiceFileUpdateRequest"
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeechServiceFileResponse"
  /api/v1/speaker-services/speaker-verification/speakers/{id}:
    get:
      tags:
      - Speaker Services - Speakers
      summary: Get speaker
      operationId: getSpeakerVerificationServiceSpeaker
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeakerVerificationServiceSpeakerResponse"
    delete:
      tags:
      - Speaker Services - Speakers
      summary: Delete speaker
      operationId: deleteSpeakerVerificationServiceSpeaker
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: purge
        in: query
        required: false
        schema:
          type: boolean
          default: false
      responses:
        "204":
          description: Speaker deleted
    patch:
      tags:
      - Speaker Services - Speakers
      summary: Update speaker
      operationId: updateSpeakerVerificationServiceSpeaker
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SpeakerVerificationServiceUpdateSpeakerRequest"
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeakerVerificationServiceSpeakerResponse"
  /api/v1/users:
    get:
      tags:
      - Users - Lookup
      summary: Search users
      description: Search for users by name or username. Supports type-ahead / autocomplete
        scenarios. The search parameter is required (min 2 characters) to prevent
        open enumeration of all tenant users.
      operationId: searchUsers
      parameters:
      - name: search
        in: query
        description: Case-insensitive prefix match on name or username (min 2 chars)
        required: true
        schema:
          type: string
      - name: size
        in: query
        description: Number of results to return (max 20)
        required: false
        schema:
          type: integer
          format: int32
          default: 10
      - name: excludeWorkspace
        in: query
        description: Exclude users who are already members of this workspace (reserved
          for future use)
        required: false
        schema:
          type: string
          format: uuid
      - name: includeSelf
        in: query
        description: Include the calling user in the results (default false)
        required: false
        schema:
          type: boolean
          default: false
      responses:
        "200":
          description: Search results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserLookupSearchResponse"
        "400":
          description: Search parameter missing or fewer than 2 characters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserLookupSearchResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserLookupSearchResponse"
        "403":
          description: Forbidden - missing users:lookup scope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserLookupSearchResponse"
        "429":
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserLookupSearchResponse"
  /api/v1/users/{userId}:
    get:
      tags:
      - Users - Lookup
      summary: Get user card
      description: "Resolve a user ID into a minimal public profile. Useful when the\
        \ UI needs to display user information for workspace members, file owners,\
        \ or activity feeds."
      operationId: getUserCard
      parameters:
      - name: userId
        in: path
        description: The unique identifier of the user
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "200":
          description: User card
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserCardResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserCardResponse"
        "403":
          description: Forbidden - missing users:lookup scope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserCardResponse"
        "404":
          description: User does not exist in the caller's tenant
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserCardResponse"
  /api/v1/tags:
    get:
      tags:
      - Tags
      summary: List tags
      description: Retrieve a paginated list of tags owned by the current user. Supports
        search/suggest by providing a search term that matches against canonical tag
        names.
      operationId: listTags
      parameters:
      - name: page
        in: query
        description: Page number (zero-based)
        required: false
        schema:
          type: integer
          format: int32
          default: 0
      - name: size
        in: query
        description: Page size (max 100)
        required: false
        schema:
          type: integer
          format: int32
          default: 20
      - name: search
        in: query
        description: Search term to filter tags (matches against canonical name)
        required: false
        schema:
          type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TagListResponse"
  /api/v1/subscription:
    get:
      tags:
      - MySubscription
      summary: Get my subscription
      description: "Returns the authenticated user's current subscription, including\
        \ plan details."
      operationId: getMySubscription
      responses:
        "200":
          description: User subscription details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserSubscriptionResponse"
        "204":
          description: No active subscription
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserSubscriptionResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserSubscriptionResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserSubscriptionResponse"
  /api/v1/subscription-plans:
    get:
      tags:
      - Subscriptions - Plans
      summary: List available subscription plans
      description: "Returns all active subscription plans available, ordered by display\
        \ order."
      operationId: getActivePlans
      responses:
        "200":
          description: List of active subscription plans
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SubscriptionPlanResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SubscriptionPlanResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SubscriptionPlanResponse"
  /api/v1/subscription-plans/{slug}:
    get:
      tags:
      - Subscriptions - Plans
      summary: Get subscription plan by slug
      description: Returns a single subscription plan by its slug. Only active plans
        are returned.
      operationId: getPlanBySlug
      parameters:
      - name: slug
        in: path
        description: "The plan slug (e.g., free, pro)"
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Subscription plan details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubscriptionPlanResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubscriptionPlanResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubscriptionPlanResponse"
        "404":
          description: Plan not found or not active
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubscriptionPlanResponse"
  /api/v1/speech-services/transcriptions/{id}:
    get:
      tags:
      - Speech - Transcriptions
      summary: Get transcription job
      description: Retrieve details of a specific transcription job including result
        when completed
      operationId: getJob
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeechServiceTranscriptionJobResponse"
    delete:
      tags:
      - Speech - Transcriptions
      summary: Delete transcription job
      description: Soft-delete a transcription job. Use ?purge=true for immediate
        permanent data removal.
      operationId: deleteJob
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: purge
        in: query
        description: Immediately purge result/error data
        required: false
        schema:
          type: boolean
          default: false
      responses:
        "204":
          description: Job deleted
  /api/v1/speech-services/transcriptions/{id}/result:
    get:
      tags:
      - Speech - Transcriptions
      summary: Get transcription job result
      description: Retrieve the transcription result for a completed job. Supports
        multiple export formats.
      operationId: getJobResult
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: format
        in: query
        description: "Export format: json, srt, vtt, txt, word"
        required: false
        schema:
          type: string
          default: json
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
  /api/v1/speech-services/summaries/{id}:
    get:
      tags:
      - Speech - Summaries
      summary: Get summary
      description: Retrieve details of a specific summary including result when completed
      operationId: getSummary
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeechServiceSummaryResponse"
    delete:
      tags:
      - Speech - Summaries
      summary: Delete summary
      description: Soft-delete a summary. Use ?purge=true for immediate permanent
        data removal.
      operationId: deleteSummary
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: purge
        in: query
        description: Immediately purge result/error data
        required: false
        schema:
          type: boolean
          default: false
      responses:
        "204":
          description: Summary deleted
  /api/v1/speech-services/summaries/{id}/result:
    get:
      tags:
      - Speech - Summaries
      summary: Get summary result
      description: Retrieve the summary result text and token usage for a completed
        summary
      operationId: getSummaryResult
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeechServiceSummaryResult"
  /api/v1/speech-services/streams:
    get:
      tags:
      - Speech - Streaming Sessions
      summary: List sessions
      description: Returns a paginated list of streaming sessions for the current
        user with optional filtering
      operationId: listSessions
      parameters:
      - name: page
        in: query
        description: Page number (zero-based)
        required: false
        schema:
          type: integer
          format: int32
          default: 0
      - name: size
        in: query
        description: Page size (max 100)
        required: false
        schema:
          type: integer
          format: int32
          default: 20
      - name: state
        in: query
        description: Filter by session state
        required: false
        schema:
          type: string
          enum:
          - CREATED
          - ACTIVE
          - FINISHED
          - CANCELLED
          - FAILED
      - name: modelAlias
        in: query
        description: Filter by model alias
        required: false
        schema:
          type: string
      - name: startedAfter
        in: query
        description: Return sessions started on or after this timestamp
        required: false
        schema:
          type: string
          format: date-time
      - name: startedBefore
        in: query
        description: Return sessions started on or before this timestamp
        required: false
        schema:
          type: string
          format: date-time
      - name: recordingRequested
        in: query
        description: Filter by recording requested
        required: false
        schema:
          type: boolean
      - name: itnRequested
        in: query
        description: Filter by ITN requested
        required: false
        schema:
          type: boolean
      - name: diarizationRequested
        in: query
        description: Filter by diarization requested
        required: false
        schema:
          type: boolean
      - name: sort
        in: query
        description: "Sort field and direction (e.g. startTime,desc)"
        required: false
        schema:
          type: string
          default: "startTime,desc"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeechServiceSessionListResponse"
  /api/v1/speech-services/streams/{sessionId}:
    get:
      tags:
      - Speech - Streaming Sessions
      summary: Get session details
      description: Returns detailed information about a specific streaming session
      operationId: getSession
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeechServiceSessionResponse"
    delete:
      tags:
      - Speech - Streaming Sessions
      summary: Delete session
      description: Soft-deletes a streaming session. The session will no longer appear
        in list results.
      operationId: deleteSession
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "204":
          description: Session deleted
  /api/v1/speech-services/streams/{sessionId}/segments:
    get:
      tags:
      - Speech - Streaming Sessions
      summary: Get session segments
      description: "Returns all finalized transcript segments for a session, ordered\
        \ by segment index. Returns 410 Gone if the session content has been purged."
      operationId: getSessionSegments
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SpeechServiceSessionSegmentResponse"
  /api/v1/speech-services/streams/{sessionId}/recording:
    get:
      tags:
      - Speech - Streaming Sessions
      summary: Download session recording
      description: Downloads the PCM audio recording for a session. Returns 404 if
        no recording was requested or it has been purged.
      operationId: downloadRecording
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "200":
          description: OK
    delete:
      tags:
      - Speech - Streaming Sessions
      summary: Purge session recording
      description: Permanently deletes the audio recording from storage. The session
        metadata and transcript segments are preserved.
      operationId: purgeRecording
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "204":
          description: Recording purged
  /api/v1/speech-services/sentence-verification/models:
    get:
      tags:
      - Sentence Verification - Models
      summary: List available sentence verification models
      description: Returns all sentence verification model aliases accessible to the
        current user based on their assigned roles. Each entry represents a model
        alias — the stable identifier you use when configuring sentence verification
        in enrollment and verification requests.
      operationId: listSentverModels
      responses:
        "200":
          description: List of available sentence verification model aliases
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SentverModelAliasResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SentverModelAliasResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SentverModelAliasResponse"
  /api/v1/speech-services/sentence-verification/models/{model}:
    get:
      tags:
      - Sentence Verification - Models
      summary: Get sentence verification model details
      description: "Returns details for a specific sentence verification model alias,\
        \ including the resolved model version and capabilities. The '{model}' path\
        \ parameter must be an alias name."
      operationId: getSentverModel
      parameters:
      - name: model
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Sentence verification model alias details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SentverModelAliasResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SentverModelAliasResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SentverModelAliasResponse"
        "404":
          description: Model alias not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SentverModelAliasResponse"
        "410":
          description: Model alias has been sunset
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SentverModelAliasResponse"
  /api/v1/speech-services/models:
    get:
      tags:
      - Speech - Models
      summary: List available models
      description: Returns all model aliases accessible to the current user based
        on their assigned roles. Each entry represents a model alias - the stable
        identifier you use in all speech service requests.
      operationId: listSpeechModels
      responses:
        "200":
          description: List of available model aliases
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ModelAliasResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ModelAliasResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ModelAliasResponse"
  /api/v1/speech-services/models/{model}:
    get:
      tags:
      - Speech - Models
      summary: Get model details
      description: "Returns details for a specific model alias, including the resolved\
        \ model version and capabilities. The '{model}' path parameter must be an\
        \ alias name."
      operationId: getModel
      parameters:
      - name: model
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Model alias details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelAliasResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelAliasResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelAliasResponse"
        "404":
          description: Model alias not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelAliasResponse"
        "410":
          description: Model alias has been sunset
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelAliasResponse"
  /api/v1/speech-services/models/{model}/languages:
    get:
      tags:
      - Speech - Models
      summary: Get model languages
      description: "Returns the supported languages for a specific model alias. The\
        \ '{model}' path parameter must be an alias name."
      operationId: getModelLanguages
      parameters:
      - name: model
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Supported languages
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelLanguagesResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelLanguagesResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelLanguagesResponse"
        "404":
          description: Model alias not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelLanguagesResponse"
        "410":
          description: Model alias has been sunset
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelLanguagesResponse"
  /api/v1/speech-services/files/{id}/listening-audio/stream:
    get:
      tags:
      - Speech - Files
      summary: Stream listening audio
      description: Stream the listening audio wave file with HTTP Range support for
        buffered playback
      operationId: streamListeningAudio
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: Range
        in: header
        required: false
        schema:
          type: string
      responses:
        "200":
          description: OK
  /api/v1/speech-services/files/{id}/content:
    get:
      tags:
      - Speech - Files
      summary: Download file
      description: Download the binary content of a media file
      operationId: downloadMediaFile
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "200":
          description: OK
  /api/v1/speech-services/files/shared-with-me:
    get:
      tags:
      - Speech - Files
      summary: List files shared with me
      description: "Retrieve a paginated list of files that other users have shared\
        \ with the current user, either via direct share or INTERNAL publishing within\
        \ the same tenant"
      operationId: listSharedFiles
      parameters:
      - name: page
        in: query
        description: Page number (zero-based)
        required: false
        schema:
          type: integer
          format: int32
          default: 0
      - name: size
        in: query
        description: Page size (max 100)
        required: false
        schema:
          type: integer
          format: int32
          default: 20
      - name: accessType
        in: query
        description: "Filter by access type: DIRECT_SHARE or INTERNAL. If omitted,\
          \ returns both."
        required: false
        schema:
          $ref: "#/components/schemas/SpeechServiceFileAccessType"
      - name: name
        in: query
        description: Partial case-insensitive search on file name
        required: false
        schema:
          type: string
      - name: filename
        in: query
        description: Partial case-insensitive search on filename
        required: false
        schema:
          type: string
      - name: sort
        in: query
        description: "Sort field and direction (e.g. creationDate,desc)"
        required: false
        schema:
          type: string
          default: "creationDate,desc"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeechServiceSharedFilesListResponse"
  /api/v1/speaker-services/speaker-verification/voice-prints:
    get:
      tags:
      - Speaker Services - Voice Prints
      summary: List voice prints
      operationId: listSpeakerVerificationServiceVoicePrints
      parameters:
      - name: speakerId
        in: query
        required: false
        schema:
          type: string
          format: uuid
      - name: model
        in: query
        required: false
        schema:
          type: string
      - name: resolvedModel
        in: query
        required: false
        schema:
          type: string
      - name: status
        in: query
        required: false
        schema:
          type: array
          items:
            $ref: "#/components/schemas/SpeakerVerificationServiceVoicePrintStatus"
      - name: isActive
        in: query
        required: false
        schema:
          type: boolean
      - name: isDefault
        in: query
        required: false
        schema:
          type: boolean
      - name: isDeleted
        in: query
        required: false
        schema:
          type: boolean
          default: false
      - name: page
        in: query
        description: Page number
        required: false
        schema:
          type: integer
          format: int32
          default: 0
      - name: size
        in: query
        description: Page size
        required: false
        schema:
          type: integer
          format: int32
          default: 20
      - name: sort
        in: query
        required: false
        schema:
          type: string
          default: "createdAt,desc"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeakerVerificationServiceVoicePrintsListResponse"
  /api/v1/speaker-services/speaker-verification/voice-prints/{voicePrintId}:
    get:
      tags:
      - Speaker Services - Voice Prints
      summary: Get voice print
      operationId: getSpeakerVerificationServiceVoicePrint
      parameters:
      - name: voicePrintId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeakerVerificationServiceVoicePrintResponse"
    delete:
      tags:
      - Speaker Services - Voice Prints
      summary: Delete voice print
      operationId: deleteSpeakerVerificationServiceVoicePrint
      parameters:
      - name: voicePrintId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: purge
        in: query
        required: false
        schema:
          type: boolean
          default: false
      responses:
        "204":
          description: Voice print deleted
  /api/v1/speaker-services/speaker-verification/verifications/{verificationId}:
    get:
      tags:
      - Speaker Verification Service - Verifications
      summary: Get verification
      operationId: getSpeakerVerificationServiceVerification
      parameters:
      - name: verificationId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeakerVerificationServiceVerificationResponse"
    delete:
      tags:
      - Speaker Verification Service - Verifications
      summary: Delete verification
      operationId: deleteSpeakerVerificationServiceVerification
      parameters:
      - name: verificationId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: purge
        in: query
        required: false
        schema:
          type: boolean
          default: false
      responses:
        "204":
          description: Verification deleted
  /api/v1/speaker-services/speaker-verification/verifications/{verificationId}/recording:
    get:
      tags:
      - Speaker Verification Service - Verifications
      summary: Download verification probe recording
      operationId: downloadSpeakerVerificationServiceVerificationRecording
      parameters:
      - name: verificationId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
  /api/v1/speaker-services/speaker-verification/speakers/{speakerId}/enrollments/{enrollmentId}:
    get:
      tags:
      - Speaker Services - Enrollments
      summary: Get enrollment
      operationId: getSpeakerVerificationServiceEnrollment
      parameters:
      - name: speakerId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: enrollmentId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeakerVerificationServiceEnrollmentResponse"
    delete:
      tags:
      - Speaker Services - Enrollments
      summary: Delete enrollment
      operationId: deleteSpeakerVerificationServiceEnrollment
      parameters:
      - name: speakerId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: enrollmentId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: purge
        in: query
        required: false
        schema:
          type: boolean
          default: false
      responses:
        "204":
          description: Enrollment deleted
  /api/v1/speaker-services/speaker-verification/speakers/{speakerId}/enrollments/{enrollmentId}/recording:
    get:
      tags:
      - Speaker Services - Enrollments
      summary: Download enrollment recording
      operationId: downloadSpeakerVerificationServiceEnrollmentRecording
      parameters:
      - name: speakerId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: enrollmentId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
  /api/v1/speaker-services/speaker-verification/speakers/{speakerId}/enrollments/{enrollmentId}/embeddings:
    get:
      tags:
      - Speaker Services - Enrollments
      summary: List embeddings for enrollment
      operationId: listEnrollmentEmbeddings
      parameters:
      - name: speakerId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: enrollmentId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeakerVerificationServiceEnrollmentEmbeddingsListResponse"
  /api/v1/speaker-services/speaker-verification/speakers/{speakerId}/enrollments/{enrollmentId}/embeddings/{embeddingId}:
    get:
      tags:
      - Speaker Services - Enrollments
      summary: Get enrollment embedding
      operationId: getEnrollmentEmbedding
      parameters:
      - name: speakerId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: enrollmentId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: embeddingId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeakerVerificationServiceEnrollmentEmbeddingResponse"
  /api/v1/speaker-services/speaker-verification/analytics/verifications:
    get:
      tags:
      - Speaker Verification Service - Analytics
      summary: Get verification analytics
      description: |
        Returns aggregated verification statistics (success/error rates and accept/review/reject rates) for the requested time window, broken down by the selected granularity.

        **User view** (`speaker:analytics:read` only): statistics are restricted to verifications initiated by the authenticated user.

        **Admin view** (`speaker:analytics:read` + `speaker:analytics:admin`): statistics cover all users in the tenant.

        **Filtering**: all filter parameters are optional. When omitted the statistics cover the full scope permitted by the caller's role.
      operationId: getSpeakerVerificationAnalytics
      parameters:
      - name: from
        in: query
        description: Inclusive start of the analysis period (ISO 8601 UTC or PostgreSQL-style).
          Required.
        required: true
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        description: Exclusive end of the analysis period (ISO 8601 UTC or PostgreSQL-style).
          Defaults to now when omitted.
        required: false
        schema:
          type: string
          format: date-time
      - name: granularity
        in: query
        description: Time bucket granularity. Defaults to DAY.
        required: false
        schema:
          $ref: "#/components/schemas/VerificationAnalyticsGranularity"
          default: DAY
      - name: speakerId
        in: query
        description: Filter statistics to a single speaker (UUID).
        required: false
        schema:
          type: string
          format: uuid
      - name: embeddingsModel
        in: query
        description: Filter statistics to a specific speaker-embeddings model alias
          (e.g. `en-general-v2`).
        required: false
        schema:
          type: string
      - name: embeddingsResolvedModel
        in: query
        description: Filter statistics to a specific resolved (concrete) speaker-embeddings
          model name.
        required: false
        schema:
          type: string
      - name: voicePrintId
        in: query
        description: Filter statistics to a specific voice print (UUID).
        required: false
        schema:
          type: string
          format: uuid
      - name: sentverModel
        in: query
        description: Filter statistics to a specific sentence verification model alias
          (e.g. `en-sentver-v1`).
        required: false
        schema:
          type: string
      - name: sentverResolvedModel
        in: query
        description: Filter statistics to a specific resolved (concrete) sentence
          verification model name.
        required: false
        schema:
          type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VerificationAnalyticsResponse"
  /api/v1/speaker-services/speaker-embeddings/models:
    get:
      tags:
      - Speaker Embeddings - Models
      summary: List available speaker embedding models
      operationId: listSpeakerEmbeddingModels
      responses:
        "200":
          description: List of available speaker embedding model aliases
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SpeakerEmbeddingModelAliasResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SpeakerEmbeddingModelAliasResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SpeakerEmbeddingModelAliasResponse"
  /api/v1/speaker-services/speaker-embeddings/models/{model}:
    get:
      tags:
      - Speaker Embeddings - Models
      summary: Get speaker embedding model details
      operationId: getSpeakerEmbeddingModel
      parameters:
      - name: model
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Speaker embedding model alias details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeakerEmbeddingModelAliasResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeakerEmbeddingModelAliasResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeakerEmbeddingModelAliasResponse"
        "404":
          description: Model alias not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeakerEmbeddingModelAliasResponse"
        "410":
          description: Model alias has been sunset
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeakerEmbeddingModelAliasResponse"
  /api/v1/retention:
    get:
      tags:
      - Data Retention
      summary: Get my retention policy
      description: "Returns the authenticated user's effective retention policy across\
        \ all services. Values reflect any user-level overrides applied by an administrator,\
        \ falling back to tenant defaults."
      operationId: getMyRetentionPolicy
      responses:
        "200":
          description: Effective retention policy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RetentionPolicyResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RetentionPolicyResponse"
  /api/v1/rate-limits:
    get:
      tags:
      - Rate Limits
      summary: Get my rate limits
      description: "Returns the authenticated user's effective rate limits across\
        \ all services. Values reflect any user-level overrides applied by an administrator,\
        \ falling back to tenant defaults."
      operationId: getMyRateLimits
      responses:
        "200":
          description: Effective rate limits
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RateLimitsResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RateLimitsResponse"
  /api/v1/quotas:
    get:
      tags:
      - Quotas
      summary: Get my quotas
      description: "Returns the authenticated user's effective quota limits and current\
        \ usage across all services. Values reflect any user-level overrides applied\
        \ by an administrator, falling back to tenant defaults."
      operationId: getMyQuotas
      responses:
        "200":
          description: Effective quota limits and usage
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QuotasResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QuotasResponse"
  /api/v1/me/permissions:
    get:
      tags:
      - Permissions - Effective
      summary: Get my effective permissions
      description: Returns the full list of effective scopes derived from the current
        caller's authorization context
      operationId: getMyEffectivePermissions
      responses:
        "200":
          description: Effective permissions returned successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EffectivePermissionsResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EffectivePermissionsResponse"
  /api/v1/global/siteproperties:
    get:
      tags:
      - Site Properties
      summary: Get site properties
      description: Retrieve tenant-aware configuration details about the site.
      operationId: getSiteProperties
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SitePropertiesResponse"
  /api/v1/api-keys/{keyId}:
    get:
      tags:
      - API Keys
      summary: Get API key by ID
      description: Gets a specific API key by its ID.
      operationId: getApiKey
      parameters:
      - name: keyId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "200":
          description: API key found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiKeyResponse"
        "404":
          description: API key not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiKeyResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiKeyResponse"
    delete:
      tags:
      - API Keys
      summary: Revoke an API key
      description: "Revokes an API key. Once revoked, the key cannot be used."
      operationId: revokeApiKey
      parameters:
      - name: keyId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApiKeyRevokeRequest"
      responses:
        "204":
          description: API key revoked successfully
        "404":
          description: API key not found
        "401":
          description: Unauthorized
  /api/v1/speech-services/files/{id}/listening-audio:
    delete:
      tags:
      - Speech - Files
      summary: Delete listening audio
      description: Soft-delete the listening audio of a file. Use ?purge=true for
        immediate permanent removal of the listening audio content.
      operationId: deleteListeningAudio
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: purge
        in: query
        description: Immediately purge listening audio content
        required: false
        schema:
          type: boolean
          default: false
      responses:
        "204":
          description: Listening audio deleted
  /api/v1/speech-services/files/{fileId}/shares/{shareId}:
    delete:
      tags:
      - Speech - Files - Sharing
      summary: Revoke a share
      description: "Remove a direct share, revoking the user's access to the file.\
        \ Only the file owner can revoke shares."
      operationId: removeShare
      parameters:
      - name: fileId
        in: path
        description: UUID of the file
        required: true
        schema:
          type: string
          format: uuid
      - name: shareId
        in: path
        description: UUID of the share to revoke
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "204":
          description: Share revoked successfully
        "404":
          description: File or share not found
components:
  schemas:
    CommonWebhook:
      type: object
      description: Webhook configuration for service completion notifications
      properties:
        url:
          type: string
          description: HTTPS URL receiving webhook notifications
          example: https://example.com/koldan/webhooks
        secret:
          type:
          - string
          - "null"
          description: Shared secret used to sign webhook payloads with HMAC-SHA256.
            Responses return a masked value when configured.
          example: shared-secret
        headers:
          type:
          - object
          - "null"
          additionalProperties:
            type: string
          description: Custom HTTP headers included in webhook requests
          example:
            X-Integration: speaker-services
      required:
      - url
    ListeningAudioResponse:
      type: object
      description: Listening audio MP3 derivative and its lifecycle
      properties:
        status:
          type: "null"
          $ref: "#/components/schemas/ListeningAudioStatus"
          description: Generation status
          example: COMPLETED
        size:
          type:
          - integer
          - "null"
          format: int64
          description: Size of the generated MP3 in bytes
          example: 2097152
        createdAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the MP3 generation completed
        deleted:
          type:
          - boolean
          - "null"
          description: Whether the listening audio has been soft-deleted. Automatically
            set to true when the parent file is deleted.
        deletedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the listening audio was soft-deleted. Null if
            not deleted.
        purgedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the listening audio content was discarded. Null
            if not purged.
        purgeAt:
          type:
          - string
          - "null"
          format: date-time
          description: Scheduled timestamp for automatic purge. Null if not deleted
            or already purged.
        purged:
          type:
          - boolean
          - "null"
    ListeningAudioStatus:
      type: string
      description: Status of the listening-audio file derivative generation
      enum:
      - PENDING
      - PROCESSING
      - COMPLETED
      - FAILED
    SpeechServiceChannelMapping:
      type: object
      description: Maps an audio channel index to a custom speaker label
      properties:
        channel:
          type: integer
          format: int32
          description: Zero-based audio channel index
          example: 0
          minimum: 0
        label:
          type: string
          description: Custom speaker label for this channel
          example: Agent
      required:
      - channel
      - label
    SpeechServiceDiarizationOptions:
      type: object
      description: Configuration options for diarization (identifying and separating
        different speakers)
      properties:
        enabled:
          type: boolean
          description: Whether diarization should be performed
        mode:
          type:
          - string
          - "null"
          description: Diarization mode. 'speaker' (default) = Automatic speaker separation.
            'channel' = each audio channel maps to a speaker.
          enum:
          - SPEAKER
          - CHANNEL
        maxSpeakers:
          type:
          - integer
          - "null"
          format: int32
          description: The maximum number of speakers expected in the audio. Set to
            -1 for automatic speaker count detection. Used only when mode is 'speaker'.
          example: 4
        channelMapping:
          type:
          - array
          - "null"
          description: Optional mapping of channel indices to custom speaker labels.
            Used only when mode is 'channel'.
          items:
            $ref: "#/components/schemas/SpeechServiceChannelMapping"
      required:
      - enabled
    SpeechServiceFileResponse:
      type: object
      description: Represents a media file resource
      properties:
        id:
          type:
          - string
          - "null"
          format: uuid
          description: Unique identifier of the file
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        name:
          type:
          - string
          - "null"
          description: Display name of the file
          example: meeting-recording
        filename:
          type:
          - string
          - "null"
          description: Original filename of the uploaded file
          example: meeting-2026-02-25.wav
        description:
          type:
          - string
          - "null"
          description: Description of the file content
          example: Weekly engineering team meeting recording
        path:
          type:
          - string
          - "null"
          description: Virtual directory path of the file (S3-key style). Always starts
            and ends with '/'
          example: /meetings/2026/march/
        size:
          type:
          - integer
          - "null"
          format: int64
          description: File size in bytes
          example: 15728640
        durationSeconds:
          type:
          - number
          - "null"
          format: double
          description: Duration of the media file in seconds
          example: 125.3
        sha256:
          type:
          - string
          - "null"
          description: "SHA-256 checksum of the file content (lowercase hex, 64 characters)"
          example: e5b844cc57f57094ea4585e235f36c78c1cd222262bb89d53c94dcb4d6b3e55d
        ingestionStatus:
          type:
          - string
          - "null"
          description: Ingestion status for URI-imported files. Null for directly
            uploaded files.
          example: COMPLETED
        listeningAudio:
          type: "null"
          $ref: "#/components/schemas/ListeningAudioResponse"
          description: Listening audio sub-object. Null if listening audio has not
            been generated.
        creationDate:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the file was created
        deletedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the file was soft-deleted. Null if isDeleted
            is false.
        purgedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the file's binary data was permanently purged.
            Null if isPurged is false.
        purgeAt:
          type:
          - string
          - "null"
          format: date-time
          description: Scheduled timestamp for automatic purge. Null if not deleted
            or already purged.
        contentDiscardedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the file content was discarded. Null if isContentDiscarded
            is false.
        metadata:
          type:
          - object
          - "null"
          additionalProperties: {}
          description: Additional key-value metadata associated with the file
        tags:
          type:
          - array
          - "null"
          description: "Tag display names assigned to this file, sorted alphabetically\
            \ by canonical name"
          example:
          - Engineering
          - Meeting
          items:
            type: string
        publishMode:
          type:
          - string
          - "null"
          description: "Publish mode controlling file visibility: PRIVATE or INTERNAL"
          enum:
          - PRIVATE
          - INTERNAL
        publishedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the file was first published (set to INTERNAL).
            Null if the file has never been published.
        deleted:
          type:
          - boolean
          - "null"
        purged:
          type:
          - boolean
          - "null"
        contentDiscarded:
          type:
          - boolean
          - "null"
    SpeechServiceTranscriptionJobError:
      type: object
      description: Describes an error that occurred during job processing
      properties:
        code:
          type:
          - string
          - "null"
          description: Machine-readable error code
          enum:
          - TRANSCRIPTION_FAILED
          - DIARIZATION_FAILED
          - CHANNEL_DIARIZATION_FAILED
          - UNSUPPORTED_FORMAT
          - FILE_CORRUPTED
          - FILE_NOT_FOUND
          - EMPTY_AUDIO
          - DURATION_EXCEEDED
          - QUOTA_EXCEEDED
          - LANGUAGE_NOT_SUPPORTED
          - MODEL_UNAVAILABLE
          - PUNCTUATION_FAILED
          - INTERNAL_ERROR
          example: TRANSCRIPTION_FAILED
        message:
          type:
          - string
          - "null"
          description: Human-readable error message describing what went wrong
          example: "Failed to transcribe audio: unsupported codec"
        timestamp:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the error occurred
    SpeechServiceTranscriptionJobResponse:
      type: object
      description: Represents a speech processing job
      properties:
        id:
          type:
          - string
          - "null"
          format: uuid
          description: Unique identifier of the job
        status:
          type: "null"
          $ref: "#/components/schemas/TranscriptionJobStatus"
          description: Current status of the job
          example: COMPLETED
        creationDate:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the job was created
        completionDate:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the job completed. Null if not yet completed.
        deletedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the job was soft-deleted. Null if isDeleted
            is false.
        purgedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the job data was permanently purged. Null if
            isPurged is false.
        purgeAt:
          type:
          - string
          - "null"
          format: date-time
          description: Scheduled timestamp for automatic purge. Null if not deleted
            or already purged.
        file:
          type: "null"
          $ref: "#/components/schemas/SpeechServiceFileResponse"
          description: The media file associated with this job
        transcription:
          type: "null"
          $ref: "#/components/schemas/SpeechServiceTranscriptionOptions"
          description: Transcription configuration used for this job
        diarization:
          type: "null"
          $ref: "#/components/schemas/SpeechServiceDiarizationOptions"
          description: Diarization configuration used for this job
        result:
          type: "null"
          $ref: "#/components/schemas/SpeechServiceTranscriptionJobResult"
          description: Transcription result. Present only when status is COMPLETED
            and isPurged is false.
        errorCode:
          type:
          - string
          - "null"
          description: Top-level error code when the job has failed. Null if status
            is not FAILED.
          enum:
          - TRANSCRIPTION_FAILED
          - DIARIZATION_FAILED
          - CHANNEL_DIARIZATION_FAILED
          - UNSUPPORTED_FORMAT
          - FILE_CORRUPTED
          - FILE_NOT_FOUND
          - EMPTY_AUDIO
          - DURATION_EXCEEDED
          - QUOTA_EXCEEDED
          - LANGUAGE_NOT_SUPPORTED
          - MODEL_UNAVAILABLE
          - PUNCTUATION_FAILED
          - INTERNAL_ERROR
          example: TRANSCRIPTION_FAILED
        errors:
          type:
          - array
          - "null"
          description: Array of errors encountered during processing. Cleared when
            isPurged is true.
          items:
            $ref: "#/components/schemas/SpeechServiceTranscriptionJobError"
        webhook:
          type: "null"
          $ref: "#/components/schemas/CommonWebhook"
          description: Webhook configuration for job completion notifications
        deleted:
          type:
          - boolean
          - "null"
        purged:
          type:
          - boolean
          - "null"
    SpeechServiceTranscriptionJobResult:
      type: object
      description: Contains the transcription output for a completed job
      properties:
        text:
          type:
          - string
          - "null"
          description: The full transcription text
        detectedLanguages:
          type:
          - array
          - "null"
          description: Set of IETF BCP 47 codes of the detected languages
          items:
            type: string
        confidence:
          type:
          - number
          - "null"
          format: double
          description: Overall confidence score of the transcription (0.0 - 1.0)
          example: 0.94
        duration:
          type:
          - number
          - "null"
          format: double
          description: Total audio duration in seconds
          example: 420.5
        segments:
          type:
          - array
          - "null"
          description: Array of transcription segments with timestamps
          items:
            $ref: "#/components/schemas/SpeechServiceTranscriptionSegment"
    SpeechServiceTranscriptionLanguageOptions:
      type: object
      description: Language configuration options for transcription
      properties:
        defaultLanguageCode:
          type:
          - string
          - "null"
          description: IETF BCP 47 language code to use (if auto-detection is disabled).
            Blank or missing values are treated the same as omitting the field.
    SpeechServiceTranscriptionOptions:
      type: object
      description: Configuration options for speech-to-text transcription
      properties:
        model:
          type: string
          description: The transcription model to use
          example: large-v3
        language:
          type: "null"
          $ref: "#/components/schemas/SpeechServiceTranscriptionLanguageOptions"
          description: "Language configuration for transcription. Omit this field,\
            \ set it to null, or leave defaultLanguageCode blank to enable automatic\
            \ language detection."
        punctuation:
          type:
          - boolean
          - "null"
          description: "When true, enables automatic punctuation insertion in the\
            \ transcribed text"
        capitalization:
          type:
          - boolean
          - "null"
          description: "When true, enables automatic capitalization of the transcribed\
            \ text. May be ignored depends on the language"
        inverseTextNormalization:
          type:
          - boolean
          - "null"
          description: "When true, enables inverse text normalization — converting\
            \ spoken-form numbers, dates, and other entities into their written form\
            \ (e.g. \"two thousand eighteen\" → \"2018\")"
        segmentation:
          type:
          - string
          - "null"
          default: readable
          description: "Controls transcript segment layout. Use 'readable' for pause/word-based\
            \ readable segments, or 'raw' to preserve engine/merge segment boundaries."
          enum:
          - readable
          - raw
      required:
      - model
    SpeechServiceTranscriptionSegment:
      type: object
      description: A single segment of the transcription with timing and speaker information
      properties:
        start:
          type:
          - number
          - "null"
          format: double
          description: Start time of the segment in seconds from the beginning of
            the audio
          example: 0.0
        end:
          type:
          - number
          - "null"
          format: double
          description: End time of the segment in seconds from the beginning of the
            audio
          example: 3.2
        text:
          type:
          - string
          - "null"
          description: The transcribed text for this segment
          example: "Hello everyone, welcome to the weekly engineering meeting."
        confidence:
          type:
          - number
          - "null"
          format: double
          description: Confidence score for this segment (0.0 - 1.0)
          example: 0.96
        language:
          type:
          - string
          - "null"
          description: IETF BCP 47 language code detected for this segment
          example: en-US
        speaker:
          type:
          - string
          - "null"
          description: "Speaker label. For speaker mode: SPEAKER_00, SPEAKER_01, etc.\
            \ For channel mode: auto-generated CHANNEL_00, CHANNEL_01, or custom label\
            \ from channelMapping."
          example: SPEAKER_00
        channel:
          type:
          - integer
          - "null"
          format: int32
          default: 0
          description: Zero-based audio channel index. Present only when diarization
            mode is 'channel'.
          example: 0
        words:
          type:
          - array
          - "null"
          description: Word-level timing information
          items:
            $ref: "#/components/schemas/SpeechServiceWordTiming"
    SpeechServiceWordTiming:
      type: object
      description: Timing and confidence information for a single word within a transcription
        segment
      properties:
        word:
          type:
          - string
          - "null"
          description: The transcribed word
          example: Hello
        start:
          type:
          - number
          - "null"
          format: double
          description: Start time of the word in seconds from the beginning of the
            audio
          example: 0.0
        end:
          type:
          - number
          - "null"
          format: double
          description: End time of the word in seconds from the beginning of the audio
          example: 0.45
        confidence:
          type:
          - number
          - "null"
          format: double
          description: Confidence score for this word (0.0 - 1.0). Null when the model
            does not provide word-level confidence.
          example: 0.98
        punctuation:
          type:
          - string
          - "null"
          description: "Punctuation mark following the word, if any (e.g. '.', ',',\
            \ '?', '!'). Null when punctuation service was not applied."
          example: "."
        capitalization:
          type:
          - string
          - "null"
          description: "Capitalized form of the word as determined by the capitalization\
            \ service (e.g. 'The', 'NASA'). Null when capitalization service was not\
            \ applied."
          example: Hello
    TranscriptionJobStatus:
      type: string
      description: Status of a speech-to-text transcription job
      enum:
      - PENDING
      - IN_PROGRESS
      - COMPLETED
      - FAILED
      - CANCELLED
    SpeechServiceSummaryError:
      type: object
      description: Describes an error that occurred during summary generation
      properties:
        code:
          type:
          - string
          - "null"
          description: Machine-readable error code
          enum:
          - SUMMARIZATION_FAILED
          - PROMPT_TEMPLATE_NOT_FOUND
          - PROMPT_TEMPLATE_INVALID
          - CONTEXT_LENGTH_EXCEEDED
          - LLM_SERVICE_UNAVAILABLE
          - QUOTA_EXCEEDED
          - INTERNAL_ERROR
          example: SUMMARIZATION_FAILED
        message:
          type:
          - string
          - "null"
          description: Human-readable error message describing what went wrong
          example: "Failed to generate summary: LLM service unavailable"
        timestamp:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the error occurred
    SpeechServiceSummaryResponse:
      type: object
      description: Represents an AI-generated summary of a transcription job
      properties:
        id:
          type:
          - string
          - "null"
          format: uuid
          description: Unique identifier of the summary
        transcriptionId:
          type:
          - string
          - "null"
          format: uuid
          description: The ID of the parent transcription job
        status:
          type: "null"
          $ref: "#/components/schemas/SummaryStatus"
          description: Current status of the summary
          example: COMPLETED
        promptTemplateId:
          type:
          - string
          - "null"
          format: uuid
          description: The ID of the prompt template used for summary generation
        creationDate:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the summary was created
        completionDate:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the summary completed. Null if not yet completed.
        deletedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the summary was soft-deleted. Null if isDeleted
            is false.
        purgedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the summary data was permanently purged. Null
            if isPurged is false.
        purgeAt:
          type:
          - string
          - "null"
          format: date-time
          description: Scheduled timestamp for automatic purge. Null if not deleted
            or already purged.
        result:
          type: "null"
          $ref: "#/components/schemas/SpeechServiceSummaryResult"
          description: Summary result. Present only when status is COMPLETED and isPurged
            is false.
        errors:
          type:
          - array
          - "null"
          description: Array of errors encountered during processing. Cleared when
            isPurged is true.
          items:
            $ref: "#/components/schemas/SpeechServiceSummaryError"
        webhook:
          type: "null"
          $ref: "#/components/schemas/CommonWebhook"
          description: Webhook configuration for summary completion notifications
        deleted:
          type:
          - boolean
          - "null"
        purged:
          type:
          - boolean
          - "null"
    SpeechServiceSummaryResult:
      type: object
      description: Contains the summary output for a completed summary
      properties:
        text:
          type:
          - string
          - "null"
          description: The generated summary text
        promptTemplateId:
          type:
          - string
          - "null"
          format: uuid
          description: The ID of the prompt template used to generate this summary
        usage:
          type: "null"
          $ref: "#/components/schemas/SpeechServiceSummaryTokenUsage"
          description: Token usage statistics for the LLM request
    SpeechServiceSummaryTokenUsage:
      type: object
      description: Token usage statistics for a summary generation request
      properties:
        inputTokens:
          type:
          - integer
          - "null"
          format: int32
          description: Number of tokens in the input sent to the LLM
          example: 1250
        outputTokens:
          type:
          - integer
          - "null"
          format: int32
          description: Number of tokens in the LLM's output
          example: 380
        totalTokens:
          type:
          - integer
          - "null"
          format: int32
          description: Total tokens used (inputTokens + outputTokens)
          example: 1630
    SummaryStatus:
      type: string
      description: Status of an AI-generated transcription summary
      enum:
      - PENDING
      - IN_PROGRESS
      - COMPLETED
      - FAILED
      - CANCELLED
    LanguageDTO:
      type: object
      properties:
        name:
          type:
          - string
          - "null"
        localDisplayName:
          type:
          - string
          - "null"
        globalDisplayName:
          type:
          - string
          - "null"
        rtl:
          type:
          - boolean
          - "null"
        langTag:
          type:
          - string
          - "null"
    LanguageUpdateDTO:
      type: object
      properties:
        localDisplayName:
          type:
          - string
          - "null"
        globalDisplayName:
          type:
          - string
          - "null"
        rtl:
          type:
          - boolean
          - "null"
        langTag:
          type:
          - string
          - "null"
    TagValidationRequest:
      type: object
      description: Request to validate a tag display name
      properties:
        displayName:
          type: string
          description: Tag display name to validate
          example: Meeting Notes
          minLength: 1
      required:
      - displayName
    TagValidationResponse:
      type: object
      description: Result of tag display name validation
      properties:
        valid:
          type:
          - boolean
          - "null"
          description: Whether the display name is valid
          example: true
        canonicalName:
          type:
          - string
          - "null"
          description: The canonical (normalized) form of the display name. Null when
            invalid.
          example: meeting notes
        displayName:
          type:
          - string
          - "null"
          description: The trimmed display name as it would be stored. Null when invalid.
          example: Meeting Notes
        exists:
          type:
          - boolean
          - "null"
          description: Whether a tag with this canonical name already exists for the
            current user
          example: false
        error:
          type:
          - string
          - "null"
          description: Validation error message. Null when valid.
    SpeechServiceTranscriptionJobRequest:
      type: object
      description: Request body for creating a new speech processing job
      properties:
        fileId:
          type: string
          format: uuid
          description: The ID of the uploaded file to process
        transcription:
          $ref: "#/components/schemas/SpeechServiceTranscriptionOptions"
          description: Transcription configuration options
        diarization:
          type: "null"
          $ref: "#/components/schemas/SpeechServiceDiarizationOptions"
          description: Speaker diarization configuration options
        webhook:
          type: "null"
          $ref: "#/components/schemas/CommonWebhook"
          description: Webhook configuration for completion notifications
      required:
      - fileId
      - transcription
    SpeechServiceUploadAndTranscribeResponse:
      type: object
      description: "Response for combined upload, transcribe, and optionally summarize\
        \ operation"
      properties:
        file:
          type: "null"
          $ref: "#/components/schemas/SpeechServiceFileResponse"
          description: The uploaded file
        job:
          type: "null"
          $ref: "#/components/schemas/SpeechServiceTranscriptionJobResponse"
          description: The created transcription job
        summary:
          type: "null"
          $ref: "#/components/schemas/SpeechServiceSummaryResponse"
          description: The scheduled summary job. Present only when summary options
            were provided in the request.
    SpeechServiceSummaryRequest:
      type: object
      description: Request body for creating a new summary
      properties:
        transcriptionId:
          type: string
          format: uuid
          description: The ID of the transcription to summarize
        promptTemplateId:
          type: string
          format: uuid
          description: The ID of the prompt template to use for summary generation
        webhook:
          type: "null"
          $ref: "#/components/schemas/CommonWebhook"
          description: Webhook configuration for completion notifications
      required:
      - promptTemplateId
      - transcriptionId
    SpeechServiceFileShareRequest:
      type: object
      description: Request to share a file with a specific user
      properties:
        userId:
          type: string
          format: uuid
          description: UUID of the user to share with
          example: b2c3d4e5-f6a7-8901-bcde-f12345678901
        permission:
          type:
          - string
          - "null"
          default: VIEW
          description: "Permission level granted to the user: VIEW (read-only) or\
            \ EDIT (read + write)"
          enum:
          - VIEW
          - EDIT
          example: VIEW
      required:
      - userId
    SpeechServiceFileSharePermission:
      type: string
      description: Permission level granted to a user via a direct file share
      enum:
      - VIEW
      - EDIT
    SpeechServiceFileShareResponse:
      type: object
      description: A direct file share granting a specific user access to a file
      properties:
        id:
          type:
          - string
          - "null"
          format: uuid
          description: Unique identifier of this share
          example: c3d4e5f6-a7b8-9012-cdef-123456789012
        fileId:
          type:
          - string
          - "null"
          format: uuid
          description: UUID of the file being shared
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        userId:
          type:
          - string
          - "null"
          format: uuid
          description: UUID of the user this file is shared with
          example: b2c3d4e5-f6a7-8901-bcde-f12345678901
        permission:
          type: "null"
          $ref: "#/components/schemas/SpeechServiceFileSharePermission"
          description: Permission level granted to the user
          example: VIEW
        createdBy:
          type:
          - string
          - "null"
          format: uuid
          description: UUID of the user who created this share (file owner)
          example: d4e5f6a7-b8c9-0123-defa-234567890123
        createdAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when this share was created
    SpeakerVerificationServiceEnrollmentEmbeddingSource:
      type: object
      description: Enrollment and embedding pair identifying a source used to build
        the voice print
      properties:
        enrollmentId:
          type:
          - string
          - "null"
          format: uuid
          description: Source enrollment identifier
        embeddingId:
          type:
          - string
          - "null"
          format: uuid
          description: Embedding record identifier extracted from this enrollment
    SpeakerVerificationServiceProcessingError:
      type: object
      description: Processing error recorded during enrollment
      properties:
        code:
          $ref: "#/components/schemas/SpeakerVerificationServiceProcessingErrorCode"
          description: Machine-readable processing error code
        message:
          type: string
          description: Human-readable processing error description
        timestamp:
          type: string
          format: date-time
          description: Timestamp when the error was recorded
      required:
      - code
      - message
      - timestamp
    SpeakerVerificationServiceProcessingErrorCode:
      type: string
      description: Processing error code
      enum:
      - SENTVER_MODEL_NOT_AVAILABLE
      - SENTVER_LOCALE_UNSUPPORTED
      - UNSUPPORTED_FORMAT
      - MODEL_NOT_AVAILABLE
      - EMBEDDING_MODEL_HASH_MISMATCH
      - VOICE_PRINT_BUILD_FAILED
      - VOICE_PRINT_NOT_READY_FOR_MODEL
      - SENTVER_MODEL_NOT_CONFIGURED
      - SPEAKER_NOT_VERIFICATION_READY
      - VERIFICATION_INFERENCE_FAILED
      - INTERNAL_ERROR
    SpeakerVerificationServiceVoicePrintQualityLevel:
      type: string
      description: Voice-print quality band
      enum:
      - UNKNOWN
      - POOR
      - FAIR
      - GOOD
      - EXCELLENT
    SpeakerVerificationServiceVoicePrintQualityResponse:
      type: object
      description: Voice print quality score and level
      properties:
        score:
          type:
          - number
          - "null"
          format: float
          description: Aggregated quality score from 0.0 to 1.0
        level:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceVoicePrintQualityLevel"
          description: Quality band
    SpeakerVerificationServiceVoicePrintResponse:
      type: object
      description: Speaker voice print record
      properties:
        id:
          type:
          - string
          - "null"
          format: uuid
          description: Voice print identifier
        speakerId:
          type:
          - string
          - "null"
          format: uuid
          description: Speaker that owns the voice print
        status:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceVoicePrintStatus"
          description: Voice print lifecycle status
        modelAlias:
          type:
          - string
          - "null"
          description: Requested model alias
        resolvedModel:
          type:
          - string
          - "null"
          description: Concrete resolved model name
        modelHash:
          type:
          - string
          - "null"
          description: Model space hash for vector compatibility validation
        quality:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceVoicePrintQualityResponse"
          description: Voice print quality score and factor breakdown
        sourceEnrollments:
          type:
          - array
          - "null"
          description: Enrollment and embedding pairs used to build this voice print
          items:
            $ref: "#/components/schemas/SpeakerVerificationServiceEnrollmentEmbeddingSource"
        sourceEnrollmentCount:
          type:
          - integer
          - "null"
          format: int32
          description: Number of source enrollments
        isActive:
          type:
          - boolean
          - "null"
          description: Whether this is active for its resolved model
        isDefault:
          type:
          - boolean
          - "null"
          description: Whether this is the speaker default voice print
        errorCode:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceProcessingErrorCode"
          description: Top-level processing error code when creation failed
        errors:
          type:
          - array
          - "null"
          description: Processing errors for failed voice print creation
          items:
            $ref: "#/components/schemas/SpeakerVerificationServiceProcessingError"
        isDeleted:
          type:
          - boolean
          - "null"
          description: Whether the voice print has been deleted
        isPurged:
          type:
          - boolean
          - "null"
          description: Whether biometric artifacts have been permanently removed
        createdAt:
          type:
          - string
          - "null"
          format: date-time
          description: Creation timestamp
        completedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Completion timestamp
        activatedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Activation timestamp
        defaultedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Default selection timestamp
        deletedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Deletion timestamp
        purgedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Purge timestamp
        purgeAt:
          type:
          - string
          - "null"
          format: date-time
          description: Scheduled purge timestamp
    SpeakerVerificationServiceVoicePrintStatus:
      type: string
      description: Voice print lifecycle status
      enum:
      - READY
      - FAILED
    SentverSpeechSegment:
      type: object
      description: A detected speech segment within the submitted audio
      properties:
        startSeconds:
          type:
          - number
          - "null"
          format: float
          description: Start of the speech segment in seconds
          example: 0.5
        endSeconds:
          type:
          - number
          - "null"
          format: float
          description: End of the speech segment in seconds
          example: 3.2
    SentverThresholdMode:
      type: string
      description: Threshold preset mode for sentence verification
      enum:
      - STRICT
      - BALANCED
      - LENIENT
      - CUSTOM
    SpeakerVerificationDecision:
      type: string
      description: Speaker verification decision
      enum:
      - ACCEPT
      - REJECT
      - REVIEW
    SpeakerVerificationServiceAudioSegmentSelection:
      type: object
      description: Audio segment selection for enrollment media
      properties:
        start:
          type:
          - number
          - "null"
          format: double
          description: Start time in seconds
          example: 1.5
        end:
          type:
          - number
          - "null"
          format: double
          description: End time in seconds
          example: 12.0
        channel:
          type:
          - integer
          - "null"
          format: int32
          description: Zero-based audio channel index
          example: 0
        speaker:
          type:
          - string
          - "null"
          description: Optional upstream speaker label
          example: speaker-1
    SpeakerVerificationServiceMediaSource:
      type: object
      description: Submitted media source details
      properties:
        type:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceMediaSourceType"
          description: Source type
          example: UPLOAD
        filename:
          type:
          - string
          - "null"
          description: Original uploaded filename
        uri:
          type:
          - string
          - "null"
          description: Imported URI
        sha256:
          type:
          - string
          - "null"
          description: SHA-256 checksum of the uploaded audio
        size:
          type:
          - integer
          - "null"
          format: int64
          description: File size in bytes
        contentType:
          type:
          - string
          - "null"
          description: Media content type
          example: audio/wav
        durationSeconds:
          type:
          - number
          - "null"
          format: double
          description: "Detected audio duration in seconds, populated upon processing"
        contentRetained:
          type:
          - boolean
          - "null"
          description: Whether raw recording content is retained
    SpeakerVerificationServiceMediaSourceType:
      type: string
      description: Enrollment media source type
      enum:
      - UPLOAD
      - URI_IMPORT
    SpeakerVerificationServiceSentenceDecision:
      type: string
      description: Sentence verification decision
      enum:
      - ACCEPT
      - REJECT
      - REVIEW
    SpeakerVerificationServiceSentenceVerificationResult:
      type: object
      description: Sentence verification lineage and result
      properties:
        expectedText:
          type:
          - string
          - "null"
          description: Expected sentence when retained
        expectedTextSha256:
          type:
          - string
          - "null"
          description: SHA-256 hash of expected sentence
        locale:
          type:
          - string
          - "null"
          description: Locale used by sentver
          example: en-US
        modelAlias:
          type:
          - string
          - "null"
          description: Requested sentver model alias
          example: sentver-default
        resolvedModel:
          type:
          - string
          - "null"
          description: Resolved sentver model
        fallbackUsed:
          type:
          - boolean
          - "null"
          description: Whether alias fallback selected the resolved model
        decision:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceSentenceDecision"
          description: Sentence decision
          example: ACCEPT
        score:
          type:
          - number
          - "null"
          format: float
          description: Sentence match score (verification_score from SVP)
        thresholdMode:
          type: "null"
          $ref: "#/components/schemas/SentverThresholdMode"
          description: Threshold mode used for this sentence verification decision
        acceptThreshold:
          type:
          - number
          - "null"
          format: double
          description: Accept threshold
        reviewThreshold:
          type:
          - number
          - "null"
          format: double
          description: Review threshold
        reason:
          type:
          - string
          - "null"
          description: Human-readable result summary
        latencyMs:
          type:
          - integer
          - "null"
          format: int32
          description: Sentver processing latency in milliseconds
        confidenceScore:
          type:
          - number
          - "null"
          format: float
          description: Confidence level of the verification result
        speechRms:
          type:
          - number
          - "null"
          format: float
          description: Root mean square level of the detected speech audio
        audioSnr:
          type:
          - number
          - "null"
          format: float
          description: Speech/Noise SNR
        speechSegments:
          type:
          - array
          - "null"
          description: Speech segments detected in the submitted audio
          items:
            $ref: "#/components/schemas/SentverSpeechSegment"
        qualityIndicators:
          type:
          - array
          - "null"
          description: Audio quality issues detected during verification
          items:
            type: string
            description: Audio or speech quality indicator detected during sentence
              verification
            enum:
            - QUALITY_INDICATOR_UNSPECIFIED
            - SPEECH_TOO_LOW
            - SPEECH_NOT_DETECTED
            - SPEECH_TOO_FAST
            - SPEECH_TOO_SLOW
            - SPEECH_TOO_LONG
            - SPEECH_TOO_SHORT
    SpeakerVerificationServiceSpeakerMatchResult:
      type: object
      description: Speaker biometric match result before optional sentence gating
      properties:
        decision:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationDecision"
          description: Speaker match decision before sentence gating
        score:
          type:
          - number
          - "null"
          format: float
          description: Similarity score (0.0-1.0)
        acceptThreshold:
          type:
          - number
          - "null"
          format: float
          description: Accept threshold used
        reviewThreshold:
          type:
          - number
          - "null"
          format: float
          description: Review threshold used
    SpeakerVerificationServiceVerificationRecordStatus:
      type: string
      description: Verification record status
      enum:
      - COMPLETED
      - FAILED
    SpeakerVerificationServiceVerificationResponse:
      type: object
      description: Retained speaker verification record
      properties:
        id:
          type: string
          format: uuid
          description: Unique verification record identifier
        speakerId:
          type: string
          format: uuid
          description: Claimed speaker identity
        speakerName:
          type:
          - string
          - "null"
          description: Speaker display name
          example: Israel Israeli
        speakerExternalRef:
          type:
          - string
          - "null"
          description: Speaker external identifier
          example: crm-contact-1337
        voicePrintId:
          type:
          - string
          - "null"
          format: uuid
          description: Voice print used for this verification
        status:
          $ref: "#/components/schemas/SpeakerVerificationServiceVerificationRecordStatus"
          description: Verification record status
        source:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceMediaSource"
          description: Probe recording source metadata
        segment:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceAudioSegmentSelection"
          description: Segment used for the probe recording
        result:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceVerificationResult"
          description: Final verification decision after speaker and optional sentence
            gating
        speakerMatch:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceSpeakerMatchResult"
          description: Speaker biometric match result before optional sentence gating
        sentenceVerification:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceSentenceVerificationResult"
          description: Sentence verification result when requested
        qualityScore:
          type:
          - number
          - "null"
          format: float
          description: Audio quality score of the probe recording
        totalLatencyMs:
          type:
          - integer
          - "null"
          format: int32
          description: End-to-end processing latency in milliseconds
        sentverLatencyMs:
          type:
          - integer
          - "null"
          format: int32
          description: Sentence verification inference latency in milliseconds
        speakerVerificationLatencyMs:
          type:
          - integer
          - "null"
          format: int32
          description: Speaker verification (embedding comparison) inference latency
            in milliseconds
        context:
          type:
          - object
          - "null"
          additionalProperties: {}
          description: Client context retained until verification data is purged
        errorCode:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceProcessingErrorCode"
          description: Top-level error code for failed verification records
        errors:
          type:
          - array
          - "null"
          description: Processing errors for failed verification records
          items:
            $ref: "#/components/schemas/SpeakerVerificationServiceProcessingError"
        isDeleted:
          type:
          - boolean
          - "null"
          description: Whether the verification record has been deleted
        isPurged:
          type:
          - boolean
          - "null"
          description: Whether result/debug data has been permanently removed
        createdAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when verification was accepted
        processedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when verification completed
        deletedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when verification was deleted
        purgedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when verification data was purged
        purgeAt:
          type:
          - string
          - "null"
          format: date-time
          description: Scheduled purge timestamp based on retention policy
      required:
      - id
      - speakerId
      - status
    SpeakerVerificationServiceVerificationResult:
      type: object
      description: Final verification decision after speaker and optional sentence
        gating
      properties:
        decision:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationDecision"
          description: Final verification decision
        reason:
          type:
          - string
          - "null"
          description: Human-readable final decision summary
        speakerDecision:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationDecision"
          description: Speaker biometric decision before sentence gating
        sentenceDecision:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationDecision"
          description: Sentence verification decision when requested
    SpeakerVerificationServiceEnrollmentSummary:
      type: object
      description: Enrollment readiness summary
      properties:
        total:
          type:
          - integer
          - "null"
          format: int32
          description: Total non-deleted enrollments
        successful:
          type:
          - integer
          - "null"
          format: int32
          description: Number of READY enrollments
        rejected:
          type:
          - integer
          - "null"
          format: int32
          description: "Number of REJECTED enrollments (policy gate rejections, e.g.\
            \ sentence verification)"
        failed:
          type:
          - integer
          - "null"
          format: int32
          description: Number of FAILED enrollments (unexpected system errors)
        minimumRequired:
          type:
          - integer
          - "null"
          format: int32
          description: Minimum successful enrollments required for readiness
        recommendedTarget:
          type:
          - integer
          - "null"
          format: int32
          description: Recommended successful enrollment count
    SpeakerVerificationServiceSpeakerResponse:
      type: object
      description: "Speaker identity, readiness, lifecycle, and default voice-print\
        \ summary"
      properties:
        id:
          type: string
          format: uuid
          description: Unique speaker identifier
        name:
          type: string
          description: Display name
          example: Israel Israeli
        externalRef:
          type:
          - string
          - "null"
          description: Client-defined external identifier
          example: crm-contact-1337
        description:
          type:
          - string
          - "null"
          description: Optional description
        locale:
          type:
          - string
          - "null"
          description: Preferred IETF BCP 47 locale
          example: he-IL
        status:
          $ref: "#/components/schemas/SpeakerVerificationServiceSpeakerStatus"
          description: Administrative state
          example: DRAFT
        verificationStatus:
          $ref: "#/components/schemas/SpeakerVerificationServiceVerificationStatus"
          description: Verification readiness state
          example: NOT_READY
        enrollmentSummary:
          $ref: "#/components/schemas/SpeakerVerificationServiceEnrollmentSummary"
          description: Enrollment readiness summary
        voicePrintQuality:
          $ref: "#/components/schemas/SpeakerVerificationServiceVoicePrintQuality"
          description: Current quality estimate for the default voice print
        defaultVoicePrint:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceVoicePrintSummary"
          description: Default voice print used when verification omits model
        lastEnrollmentAt:
          type:
          - string
          - "null"
          format: date-time
          description: Most recent successful enrollment timestamp
        lastVerificationAt:
          type:
          - string
          - "null"
          format: date-time
          description: Most recent verification timestamp
        tags:
          type:
          - array
          - "null"
          description: Tags assigned to the speaker
          items:
            type: string
        metadata:
          type:
          - object
          - "null"
          additionalProperties: {}
          description: Additional customer metadata
        isDeleted:
          type:
          - boolean
          - "null"
          description: Whether the speaker has been soft-deleted
        isPurged:
          type:
          - boolean
          - "null"
          description: Whether biometric artifacts have been permanently purged
        creationDate:
          type:
          - string
          - "null"
          format: date-time
          description: Creation timestamp
        deletedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Deletion timestamp
        purgedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Purge timestamp
      required:
      - enrollmentSummary
      - id
      - name
      - status
      - verificationStatus
      - voicePrintQuality
    SpeakerVerificationServiceSpeakerStatus:
      type: string
      description: Administrative state of a speaker identity
      enum:
      - ACTIVE
      - DISABLED
      - ARCHIVED
    SpeakerVerificationServiceVerificationStatus:
      type: string
      description: Speaker verification readiness state
      enum:
      - NOT_READY
      - READY
      - DEGRADED
    SpeakerVerificationServiceVoicePrintQuality:
      type: object
      description: Voice-print quality summary
      properties:
        score:
          type:
          - number
          - "null"
          format: float
          description: Quality score from 0.0 to 1.0
        level:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceVoicePrintQualityLevel"
          description: Quality band
          example: UNKNOWN
    SpeakerVerificationServiceVoicePrintSummary:
      type: object
      description: Default voice-print summary
      properties:
        id:
          type:
          - string
          - "null"
          format: uuid
          description: Voice print identifier
        modelAlias:
          type:
          - string
          - "null"
          description: Model alias requested when the voice print was created
        resolvedModel:
          type:
          - string
          - "null"
          description: Concrete resolved model that produced the voice print
        quality:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceVoicePrintQuality"
          description: Voice print quality summary
        createdAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the voice print was created
    SpeakerVerificationServiceCreateSpeakerRequest:
      type: object
      description: Request to create a speaker identity
      properties:
        name:
          type: string
          description: Human-readable display name
          example: Dana Levi
          maxLength: 255
          minLength: 0
        externalRef:
          type:
          - string
          - "null"
          description: Client-defined external identifier unique per owner
          example: crm-contact-1842
          maxLength: 255
          minLength: 0
        description:
          type:
          - string
          - "null"
          description: Optional note describing the speaker
          example: Primary contact for retail onboarding
        locale:
          type:
          - string
          - "null"
          description: Preferred IETF BCP 47 locale
          example: he-IL
          maxLength: 32
          minLength: 0
        tags:
          type:
          - array
          - "null"
          description: Optional tags for search and organization
          example:
          - Retail
          - VIP
          items:
            type: string
        metadata:
          type:
          - object
          - "null"
          additionalProperties: {}
          description: Additional customer metadata
          example:
            department: sales
      required:
      - name
    SpeakerVerificationServiceCreateVoicePrintRequest:
      type: object
      description: Request to create a voice print from retained enrollments
      properties:
        model:
          type:
          - string
          - "null"
          description: "Embedding model alias. If omitted, the tenant default alias\
            \ is used."
          example: speaker-default
        sourceEnrollmentIds:
          type:
          - array
          - "null"
          description: Optional subset of ready enrollment IDs to use
          items:
            type: string
            format: uuid
        forceRebuild:
          type:
          - boolean
          - "null"
          default: false
          description: Create a replacement even when an active voice print already
            exists for the same resolved model
        makeDefault:
          type:
          - boolean
          - "null"
          default: false
          description: Make the new READY voice print the speaker default after successful
            creation
        reason:
          type:
          - string
          - "null"
          description: Optional audit/debug reason
    SpeakerVerificationServiceVoicePrintPreviewRequest:
      type: object
      description: Request to preview voice print quality from retained enrollments
        without creating a voice print
      properties:
        model:
          type:
          - string
          - "null"
          description: "Embedding model alias. If omitted, the tenant default alias\
            \ is used."
          example: speaker-default
        sourceEnrollmentIds:
          type:
          - array
          - "null"
          description: "Optional subset of ready enrollment IDs to evaluate. If omitted,\
            \ all completed enrollments for the speaker are used."
          items:
            type: string
            format: uuid
    SpeakerVerificationServiceVoicePrintPreviewResponse:
      type: object
      description: Voice print quality preview result — estimated quality without
        creating a voice print
      properties:
        enrollmentCount:
          type:
          - integer
          - "null"
          format: int32
          description: Number of source enrollments evaluated
        embeddingCount:
          type:
          - integer
          - "null"
          format: int32
          description: Number of embedding vectors extracted from the enrollments
        qualityScore:
          type:
          - number
          - "null"
          format: float
          description: Aggregated quality score from 0.0 to 1.0
        qualityLevel:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceVoicePrintQualityLevel"
          description: Quality band derived from the score
        minSimilarity:
          type:
          - number
          - "null"
          format: float
          description: Lowest pairwise similarity between enrollment embeddings
        maxSimilarity:
          type:
          - number
          - "null"
          format: float
          description: Highest pairwise similarity between enrollment embeddings
        outlierEnrollmentIds:
          type:
          - array
          - "null"
          description: Enrollment IDs identified as outliers in the centroid computation
          items:
            type: string
            format: uuid
        recommendation:
          type:
          - string
          - "null"
          description: Actionable recommendation based on quality analysis
          enum:
          - ADD_MORE_ENROLLMENTS
          - REMOVE_OUTLIERS
          - READY_TO_BUILD
    SpeakerVerificationServiceEnrollmentRejectionCode:
      type: string
      description: Expected enrollment rejection reason from quality or sentence policy
      enum:
      - NO_SPEECH_DETECTED
      - SPEECH_TOO_SHORT
      - OVERLAPPING_SPEECH
      - BACKGROUND_NOISE_TOO_HIGH
      - AUDIO_CLIPPING_DETECTED
      - SENTENCE_MISMATCH
    SpeakerVerificationServiceEnrollmentResponse:
      type: object
      description: Speaker enrollment record
      properties:
        id:
          type:
          - string
          - "null"
          format: uuid
          description: Enrollment identifier
        speakerId:
          type:
          - string
          - "null"
          format: uuid
          description: Parent speaker identifier
        status:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceEnrollmentStatus"
          description: Enrollment lifecycle status
          example: PENDING
        label:
          type:
          - string
          - "null"
          description: Client-defined sample label
          example: office-headset-1
        source:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceMediaSource"
          description: Submitted media source
        segment:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceAudioSegmentSelection"
          description: Audio segment selection
        sentenceVerification:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceSentenceVerificationResult"
          description: Sentence verification request/result lineage
        errorCode:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceProcessingErrorCode"
          description: Top-level processing error code when enrollment processing
            failed unexpectedly
        rejectionCode:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceEnrollmentRejectionCode"
          description: Domain rejection reason when the enrollment was rejected by
            quality or sentence verification policy
        errors:
          type:
          - array
          - "null"
          description: Processing errors
          items:
            $ref: "#/components/schemas/SpeakerVerificationServiceProcessingError"
        webhook:
          type: "null"
          $ref: "#/components/schemas/CommonWebhook"
          description: Completion webhook configuration
        isDeleted:
          type:
          - boolean
          - "null"
          description: Whether the enrollment is soft-deleted
        isPurged:
          type:
          - boolean
          - "null"
          description: Whether sensitive artifacts are purged
        creationDate:
          type:
          - string
          - "null"
          format: date-time
          description: Creation timestamp
        completionDate:
          type:
          - string
          - "null"
          format: date-time
          description: Completion timestamp
        deletedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Deletion timestamp
        purgedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Purge timestamp
        purgeAt:
          type:
          - string
          - "null"
          format: date-time
          description: Scheduled purge timestamp
    SpeakerVerificationServiceEnrollmentStatus:
      type: string
      description: Enrollment lifecycle status
      enum:
      - READY
      - REJECTED
      - FAILED
    SpeakerVerificationServiceEnrollmentResetRequest:
      type: object
      description: Request to reset a speaker's enrollments
      properties:
        purge:
          type:
          - boolean
          - "null"
          default: false
          description: Immediately purge enrollment recordings and artifacts
        reason:
          type:
          - string
          - "null"
          description: Optional customer-supplied reset reason
          example: Speaker re-enrollment requested
    SpeakerVerificationServiceEnrollmentResetResponse:
      type: object
      description: Result of resetting a speaker's enrollments
      properties:
        speakerId:
          type:
          - string
          - "null"
          format: uuid
          description: Speaker whose enrollments were reset
        failedCount:
          type:
          - integer
          - "null"
          format: int32
          description: Number of enrollments marked as failed
        deletedCount:
          type:
          - integer
          - "null"
          format: int32
          description: Number of enrollments soft-deleted
        purgedCount:
          type:
          - integer
          - "null"
          format: int32
          description: Number of enrollments immediately purged
        voicePrintDeletedCount:
          type:
          - integer
          - "null"
          format: int32
          description: Number of voice prints soft-deleted
        voicePrintPurgedCount:
          type:
          - integer
          - "null"
          format: int32
          description: Number of voice prints immediately purged
        verificationDeletedCount:
          type:
          - integer
          - "null"
          format: int32
          description: Number of verification records soft-deleted
        verificationPurgedCount:
          type:
          - integer
          - "null"
          format: int32
          description: Number of verification records immediately purged
        resetAt:
          type:
          - string
          - "null"
          format: date-time
          description: Reset timestamp
        speaker:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceSpeakerResponse"
          description: Updated speaker
    OAuthTokenResponse:
      type: object
      properties:
        access_token:
          type:
          - string
          - "null"
        refresh_token:
          type:
          - string
          - "null"
        token_type:
          type:
          - string
          - "null"
        expires_in:
          type:
          - integer
          - "null"
          format: int64
        id_token:
          type:
          - string
          - "null"
        scope:
          type:
          - string
          - "null"
        token:
          type:
          - string
          - "null"
    RefreshTokenRequest:
      type: object
      properties:
        refreshToken:
          type:
          - string
          - "null"
    LogoutRequest:
      type: object
      properties:
        refreshToken:
          type:
          - string
          - "null"
    LoginRequest:
      type: object
      properties:
        username:
          type:
          - string
          - "null"
        password:
          type:
          - string
          - "null"
    UnifiedLoginRequest:
      type: object
      properties:
        code:
          type:
          - string
          - "null"
        redirectUri:
          type:
          - string
          - "null"
        codeVerifier:
          type:
          - string
          - "null"
    ApiKeyResponse:
      type: object
      description: API key information response
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the API key
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          description: Name of the API key
          example: My Integration Key
        description:
          type:
          - string
          - "null"
          description: Description of the API key's purpose
          example: Used for automated reporting scripts
        scopes:
          type: array
          description: "List of permission scopes assigned to the API key in service:resource:action\
            \ format. Empty list indicates an identity-only key (authentication only,\
            \ no authorization scopes)."
          example:
          - speech:files:read
          - speech:transcriptions:read
          items:
            type: string
        expirationDate:
          type:
          - string
          - "null"
          format: date-time
          description: "Expiration date of the API key, null if the key does not expire"
          example: 2025-12-31T23:59:59Z
        revocationDate:
          type:
          - string
          - "null"
          format: date-time
          description: "Date when the API key was revoked, null if not revoked"
          example: 2025-06-15T10:30:00Z
        revocationReason:
          type:
          - string
          - "null"
          description: Reason for revoking the API key
          example: Key compromised
        createdAt:
          type: string
          format: date-time
          description: Date and time when the API key was created
          example: 2025-01-10T08:00:00Z
        lastUsedAt:
          type:
          - string
          - "null"
          format: date-time
          description: "Date and time when the API key was last used, null if never\
            \ used"
          example: 2025-06-20T14:30:00Z
        expired:
          type: boolean
          description: Whether the API key has expired
          example: false
        revoked:
          type: boolean
          description: Whether the API key has been revoked
          example: false
        key:
          type:
          - string
          - "null"
          description: The plain text API key. Only returned once during creation
            - store it securely as it cannot be retrieved again.
          example: kk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2
      required:
      - createdAt
      - expired
      - id
      - name
      - revoked
      - scopes
    ApiKeyCreateRequest:
      type: object
      description: Request to create a new API key
      properties:
        name:
          type: string
          description: Name of the API key for identification purposes
          example: My Integration Key
        description:
          type:
          - string
          - "null"
          description: Optional description of the API key's purpose
          example: Used for automated reporting scripts
        scopes:
          type:
          - array
          - "null"
          description: "Optional list of permission scopes for this API key. Uses\
            \ service:resource:action format (e.g. speech:files:read). If omitted,\
            \ the key is created as an identity-only key with no scopes. Requested\
            \ scopes cannot exceed the creator's own role permissions."
          example:
          - speech:files:read
          - speech:transcriptions:read
          items:
            type: string
        expirationDate:
          type:
          - string
          - "null"
          format: date-time
          description: "Optional expiration date for the API key. If not provided,\
            \ the key will not expire."
          example: 2027-12-31T23:59:59Z
      required:
      - name
    SpeechServiceFileUpdateRequest:
      type: object
      description: Request body for updating an existing media file's metadata
      properties:
        name:
          type:
          - string
          - "null"
          description: Updated display name for the file
          example: meeting-recording-updated
        description:
          type:
          - string
          - "null"
          description: Updated description of the file content
          example: Updated description for meeting recording
        path:
          type:
          - string
          - "null"
          description: Updated virtual directory path. Must start and end with '/'
          example: /meetings/archived/
        metadata:
          type:
          - object
          - "null"
          additionalProperties: {}
          description: Updated key-value metadata associated with the file
        tags:
          type:
          - array
          - "null"
          description: "Updated list of tag display names. Replace semantics: the\
            \ provided list becomes the complete tag set. Pass an empty array to clear\
            \ all tags. Omit the field to leave tags unchanged."
          example:
          - Engineering
          - Meeting
          items:
            type: string
        publishMode:
          type:
          - string
          - "null"
          description: "Publish mode controlling file visibility. PRIVATE: visible\
            \ only to the owner and explicitly shared users. INTERNAL: visible to\
            \ all authenticated users within the same tenant."
          enum:
          - PRIVATE
          - INTERNAL
          example: INTERNAL
    SpeakerVerificationServiceUpdateSpeakerRequest:
      type: object
      description: Request to update mutable speaker metadata and administrative state
      properties:
        name:
          type:
          - string
          - "null"
          description: Updated display name
          example: Dana Levi
          maxLength: 255
          minLength: 0
        externalRef:
          type:
          - string
          - "null"
          description: Updated external business identifier
          example: crm-contact-1842
          maxLength: 255
          minLength: 0
        description:
          type:
          - string
          - "null"
          description: Updated description
          example: Primary contact for retail onboarding
        locale:
          type:
          - string
          - "null"
          description: Updated preferred IETF BCP 47 locale
          example: he-IL
          maxLength: 32
          minLength: 0
        status:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceSpeakerStatus"
          description: Administrative state
          example: READY
        tags:
          type:
          - array
          - "null"
          description: Replacement tag list
          example:
          - Retail
          - VIP
          items:
            type: string
        metadata:
          type:
          - object
          - "null"
          additionalProperties: {}
          description: Replacement customer metadata
          example:
            department: sales
    UserCardResponse:
      type: object
      description: "User card, contains public information about user"
      properties:
        id:
          type:
          - string
          - "null"
          format: uuid
          description: User unique identifier
          example: b2c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e
        username:
          type:
          - string
          - "null"
          description: Login username
          example: john.doe
        displayName:
          type:
          - string
          - "null"
          description: Display name
          example: John Doe
    UserLookupSearchResponse:
      type: object
      description: User lookup search results
      properties:
        users:
          type:
          - array
          - "null"
          description: List of matching users
          items:
            $ref: "#/components/schemas/UserCardResponse"
        size:
          type:
          - integer
          - "null"
          format: int32
          description: Number of results returned
          example: 2
        hasMore:
          type:
          - boolean
          - "null"
          description: Whether more results are available beyond the requested page
            size
    TagListResponse:
      type: object
      description: Paginated list of tags for the current user
      properties:
        tags:
          type:
          - array
          - "null"
          description: Array of tag objects
          items:
            $ref: "#/components/schemas/TagResponse"
        size:
          type:
          - integer
          - "null"
          format: int32
          description: Number of items returned in this page
          example: 20
        total:
          type:
          - integer
          - "null"
          format: int64
          description: Total number of matching tags across all pages
          example: 42
        search:
          type:
          - string
          - "null"
          description: "Search term applied to filter results, if any"
          example: meet
    TagResponse:
      type: object
      description: Tag owned by the current user
      properties:
        id:
          type:
          - string
          - "null"
          format: uuid
          description: Tag identifier
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        canonicalName:
          type:
          - string
          - "null"
          description: Canonical (normalized) name used for matching and API operations
          example: meeting notes
        displayName:
          type:
          - string
          - "null"
          description: Human-readable display name
          example: Meeting Notes
        createdAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the tag was created
    SubscriptionPlanSummary:
      type: object
      description: Lightweight subscription plan reference
      properties:
        id:
          type:
          - string
          - "null"
          format: uuid
          description: Unique plan identifier
        slug:
          type:
          - string
          - "null"
          description: URL-friendly identifier
          example: pro
        name:
          type:
          - string
          - "null"
          description: Display name
          example: Professional Plan
    UserSubscriptionResponse:
      type: object
      description: User subscription details
      properties:
        id:
          type:
          - string
          - "null"
          format: uuid
          description: Unique subscription record identifier
        userUuid:
          type:
          - string
          - "null"
          format: uuid
          description: The subscribing user's identifier
        plan:
          type: "null"
          $ref: "#/components/schemas/SubscriptionPlanSummary"
          description: The associated subscription plan
        status:
          type:
          - string
          - "null"
          description: Current subscription status
          enum:
          - ACTIVE
          - CANCELED
        currentPeriodStart:
          type:
          - string
          - "null"
          format: date-time
          description: Start of the current subscription period
        currentPeriodEnd:
          type:
          - string
          - "null"
          format: date-time
          description: End of the current subscription period (expiration). Null if
            subscription has no expiration.
        canceledAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the subscription was canceled. Null if not canceled.
        createdAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the record was created
        updatedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp of the last update
    QuotaLimitsResponse:
      type: object
      description: Quota limits across all services
      properties:
        speech-service:
          type: "null"
          $ref: "#/components/schemas/SpeechServiceQuotaLimits"
          description: Speech Service quota limits
        text-service:
          type: "null"
          $ref: "#/components/schemas/TextServiceQuotaLimits"
          description: Text Service quota limits
        speaker-service:
          type: "null"
          $ref: "#/components/schemas/SpeakerServiceQuotaLimits"
          description: Speaker Service quota limits
    RateLimitsResponse:
      type: object
      description: Rate limits across all services
      properties:
        users:
          type: "null"
          $ref: "#/components/schemas/UsersServiceRateLimits"
          description: Rate limits for Users operations
        globalRequests:
          type:
          - integer
          - "null"
          format: int32
          description: Maximum total API requests per minute across all endpoints
          example: 600
        speech-service:
          type: "null"
          $ref: "#/components/schemas/SpeechServiceRateLimits"
          description: Rate limits for Speech Services operations
        text-service:
          type: "null"
          $ref: "#/components/schemas/TextServiceRateLimits"
          description: Rate limits for Text Services operations
        speaker-service:
          type: "null"
          $ref: "#/components/schemas/SpeakerServiceRateLimits"
          description: Rate limits for Speaker Services operations
    SpeakerServiceQuotaLimits:
      type: object
      description: Speaker Service quota limit values
      properties:
        monthlySpeakerVerifications:
          type:
          - integer
          - "null"
          format: int64
          description: Monthly synchronous speaker verification requests
          example: 10000
        monthlySpeakerEnrollments:
          type:
          - integer
          - "null"
          format: int64
          description: Monthly speaker enrollment creation requests
          example: 1000
        monthlySpeakerVoicePrintBuilds:
          type:
          - integer
          - "null"
          format: int64
          description: Monthly voice-print build/rebuild starts
          example: 100
        speakerBiometricStorageLimit:
          type:
          - integer
          - "null"
          format: int64
          description: Retained biometric storage limit in bytes
          example: 2147483648
        maxSpeakers:
          type:
          - integer
          - "null"
          format: int64
          description: Maximum active speakers
          example: 10000
        maxEnrollmentsPerSpeaker:
          type:
          - integer
          - "null"
          format: int64
          description: Maximum active enrollments per speaker
          example: 50
        maxVoicePrintsPerSpeaker:
          type:
          - integer
          - "null"
          format: int64
          description: Maximum active voice prints per speaker
          example: 20
    SpeakerServiceRateLimits:
      type: object
      description: Rate limits for Speaker Services operations
      properties:
        speakerEnrollmentCreations:
          type:
          - integer
          - "null"
          format: int32
          description: Maximum speaker enrollment creation requests per minute
          example: 10
        speakerVerificationExecutions:
          type:
          - integer
          - "null"
          format: int32
          description: Maximum synchronous speaker verification requests per minute
          example: 60
        speakerVoicePrintPreviews:
          type:
          - integer
          - "null"
          format: int32
          description: Maximum voice-print quality preview requests per minute
          example: 10
        speakerVoicePrintCreations:
          type:
          - integer
          - "null"
          format: int32
          description: Maximum voice-print creation requests per minute
          example: 10
        speakerVoicePrintRebuildStarts:
          type:
          - integer
          - "null"
          format: int32
          description: Maximum voice-print rebuild starts per user per 60 minutes
          example: 1
        speakerRecordingDownloads:
          type:
          - integer
          - "null"
          format: int32
          description: Maximum speaker recording download requests per minute
          example: 30
    SpeechServiceQuotaLimits:
      type: object
      description: Speech Service quota limit values
      properties:
        storageLimit:
          type:
          - integer
          - "null"
          format: int64
          description: Storage limit in bytes
          example: 10737418240
        monthlyTranscriptionMinutes:
          type:
          - integer
          - "null"
          format: int64
          description: Monthly transcription minutes
          example: 6000
        monthlySummaries:
          type:
          - integer
          - "null"
          format: int64
          description: Monthly summary requests
          example: 500
        monthlySummaryTokens:
          type:
          - integer
          - "null"
          format: int64
          description: Monthly summary tokens (total LLM tokens)
          example: 5000000
        monthlyTranslations:
          type:
          - integer
          - "null"
          format: int64
          description: Monthly translation requests
          example: 500
        monthlyTranslationTokens:
          type:
          - integer
          - "null"
          format: int64
          description: Monthly translation tokens (total LLM tokens)
          example: 5000000
    SpeechServiceRateLimits:
      type: object
      description: Rate limits for Speech Services operations
      properties:
        fileUploads:
          type:
          - integer
          - "null"
          format: int32
          description: Maximum file upload requests per minute
          example: 20
        transcriptionJobExecutions:
          type:
          - integer
          - "null"
          format: int32
          description: Maximum transcription job creation requests per minute
          example: 20
        summaryExecutions:
          type:
          - integer
          - "null"
          format: int32
          description: Maximum summary creation requests per minute
          example: 30
        translationExecutions:
          type:
          - integer
          - "null"
          format: int32
          description: Maximum translation creation requests per minute
          example: 30
        speechServiceStreamSessionStarts:
          type:
          - integer
          - "null"
          format: int32
          description: Maximum stream session start requests per minute
          example: 10
        speechServiceStreamMaxConcurrentSessions:
          type:
          - integer
          - "null"
          format: int32
          description: Maximum concurrent streaming sessions per user
          example: 1
        speechServiceStreamMaxSessionDurationSeconds:
          type:
          - integer
          - "null"
          format: int32
          description: Maximum streaming session duration in seconds
          example: 900
        speechServiceStreamMaxBytesPerSecond:
          type:
          - integer
          - "null"
          format: int32
          description: Maximum audio bytes per second for streaming
          example: 35000
        speechServiceFileDownloadBytesPerSecond:
          type:
          - integer
          - "null"
          format: int32
          description: Maximum file download speed in bytes per second
          example: 5242880
    SubscriptionPlanResponse:
      type: object
      description: Subscription plan details
      properties:
        id:
          type:
          - string
          - "null"
          format: uuid
          description: Unique plan identifier
        slug:
          type:
          - string
          - "null"
          description: URL-friendly identifier
          example: pro
        name:
          type:
          - string
          - "null"
          description: Display name
          example: Professional Plan
        active:
          type:
          - boolean
          - "null"
          description: Whether new users can subscribe to this plan
        displayOrder:
          type:
          - integer
          - "null"
          format: int32
          description: Ordering index for display purposes
        quotas:
          type: "null"
          $ref: "#/components/schemas/QuotaLimitsResponse"
          description: Quota limit overrides (null fields inherit defaults)
        rateLimits:
          type: "null"
          $ref: "#/components/schemas/RateLimitsResponse"
          description: Rate limit overrides (null fields inherit defaults)
        permissions:
          type:
          - array
          - "null"
          description: Permission scopes granted by this plan
          items:
            type: string
        createdAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the plan was created
        updatedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp of the last update
    TextServiceQuotaLimits:
      type: object
      description: Text Service quota limit values
      properties:
        monthlyTextTranslations:
          type:
          - integer
          - "null"
          format: int64
          description: Monthly on-demand text translation requests
          example: 10000
        monthlyTextTranslationTokens:
          type:
          - integer
          - "null"
          format: int64
          description: Monthly text translation tokens (total LLM tokens)
          example: 10000000
    TextServiceRateLimits:
      type: object
      description: Rate limits for Text Services operations
      properties:
        textTranslationExecutions:
          type:
          - integer
          - "null"
          format: int32
          description: Maximum on-demand text translation requests per minute
          example: 60
    UsersServiceRateLimits:
      type: object
      description: Rate limits for Users operations
      properties:
        userLookup:
          type:
          - integer
          - "null"
          format: int32
          description: Maximum user lookup requests per minute
          example: 30
    SpeechServiceTranscriptionJobsListResponse:
      type: object
      description: Paginated list of transcription jobs with applied filters and sort
        order
      properties:
        jobs:
          type:
          - array
          - "null"
          description: Array of job objects
          items:
            $ref: "#/components/schemas/SpeechServiceTranscriptionJobResponse"
        size:
          type:
          - integer
          - "null"
          format: int32
          description: Number of items returned in this page
          example: 20
        total:
          type:
          - integer
          - "null"
          format: int64
          description: Total number of matching items across all pages
          example: 42
        filters:
          type: "null"
          $ref: "#/components/schemas/TranscriptionJobsFilter"
          description: Echo of applied filters
        sort:
          type: "null"
          $ref: "#/components/schemas/TranscriptionJobsSort"
          description: Applied sort order
    TranscriptionJobsFilter:
      type: object
      description: Echo of applied transcription job filters
      properties:
        status:
          type:
          - array
          - "null"
          description: Applied job status filter values
          items:
            type: string
        fileId:
          type:
          - string
          - "null"
          format: uuid
          description: Applied file ID filter
        isDeleted:
          type:
          - boolean
          - "null"
          description: Applied deleted state filter
        createdAfter:
          type:
          - string
          - "null"
          format: date-time
          description: Applied lower bound for creation date
        createdBefore:
          type:
          - string
          - "null"
          format: date-time
          description: Applied upper bound for creation date
        completedAfter:
          type:
          - string
          - "null"
          format: date-time
          description: Applied lower bound for completion date
        completedBefore:
          type:
          - string
          - "null"
          format: date-time
          description: Applied upper bound for completion date
        itnRequested:
          type:
          - boolean
          - "null"
          description: Applied ITN requested filter
        punctuationRequested:
          type:
          - boolean
          - "null"
          description: Applied punctuation requested filter
        capitalizationRequested:
          type:
          - boolean
          - "null"
          description: Applied capitalization requested filter
        diarizationRequested:
          type:
          - boolean
          - "null"
          description: Applied diarization requested filter
    TranscriptionJobsSort:
      type: object
      description: Applied sort order for transcription jobs
      properties:
        field:
          type:
          - string
          - "null"
          description: Sort field
          example: creationDate
        direction:
          type:
          - string
          - "null"
          description: Sort direction
          example: desc
    SpeechServiceSummaryFilter:
      type: object
      description: Echo of applied summary filters
      properties:
        transcriptionId:
          type:
          - string
          - "null"
          format: uuid
          description: Applied transcription ID filter
        fileId:
          type:
          - string
          - "null"
          format: uuid
          description: Applied file ID filter
        status:
          type:
          - array
          - "null"
          description: Applied summary status filter values
          items:
            type: string
        promptTemplateId:
          type:
          - string
          - "null"
          format: uuid
          description: Applied prompt template ID filter
        isDeleted:
          type:
          - boolean
          - "null"
          description: Applied deleted state filter
        createdAfter:
          type:
          - string
          - "null"
          format: date-time
          description: Applied lower bound for creation date
        createdBefore:
          type:
          - string
          - "null"
          format: date-time
          description: Applied upper bound for creation date
        completedAfter:
          type:
          - string
          - "null"
          format: date-time
          description: Applied lower bound for completion date
        completedBefore:
          type:
          - string
          - "null"
          format: date-time
          description: Applied upper bound for completion date
    SpeechServiceSummaryListResponse:
      type: object
      description: Paginated list of summaries with applied filters and sort order
      properties:
        summaries:
          type:
          - array
          - "null"
          description: Array of summary objects
          items:
            $ref: "#/components/schemas/SpeechServiceSummaryResponse"
        size:
          type:
          - integer
          - "null"
          format: int32
          description: Number of items returned in this page
          example: 20
        total:
          type:
          - integer
          - "null"
          format: int64
          description: Total number of matching items across all pages
          example: 42
        filters:
          type: "null"
          $ref: "#/components/schemas/SpeechServiceSummaryFilter"
          description: Echo of applied filters
        sort:
          type: "null"
          $ref: "#/components/schemas/SpeechServiceSummarySort"
          description: Applied sort order
    SpeechServiceSummarySort:
      type: object
      description: Applied sort order for summaries
      properties:
        field:
          type:
          - string
          - "null"
          description: Sort field
          example: creationDate
        direction:
          type:
          - string
          - "null"
          description: Sort direction
          example: desc
    SpeechServiceSessionFilter:
      type: object
      description: Echo of applied session filters
      properties:
        state:
          type:
          - string
          - "null"
          description: Applied session state filter
          enum:
          - CREATED
          - ACTIVE
          - FINISHED
          - CANCELLED
          - FAILED
        modelAlias:
          type:
          - string
          - "null"
          description: Applied model alias filter
        startedAfter:
          type:
          - string
          - "null"
          format: date-time
          description: Applied lower bound for start time
        startedBefore:
          type:
          - string
          - "null"
          format: date-time
          description: Applied upper bound for start time
        recordingRequested:
          type:
          - boolean
          - "null"
          description: Applied recording requested filter
        itnRequested:
          type:
          - boolean
          - "null"
          description: Applied ITN requested filter
        diarizationRequested:
          type:
          - boolean
          - "null"
          description: Applied diarization requested filter
    SpeechServiceSessionListResponse:
      type: object
      description: Paginated list of speech-service streaming sessions
      properties:
        page:
          type:
          - integer
          - "null"
          format: int32
          description: Current page number (zero-based)
        size:
          type:
          - integer
          - "null"
          format: int32
          description: Page size
        total:
          type:
          - integer
          - "null"
          format: int64
          description: Total number of sessions matching the filter
        sessions:
          type:
          - array
          - "null"
          description: List of sessions on this page
          items:
            $ref: "#/components/schemas/SpeechServiceSessionResponse"
        filters:
          type: "null"
          $ref: "#/components/schemas/SpeechServiceSessionFilter"
          description: Echo of applied filters
    SpeechServiceSessionResponse:
      type: object
      description: Speech-service streaming session details
      properties:
        sessionId:
          type:
          - string
          - "null"
          format: uuid
          description: Session unique identifier
        tenantId:
          type:
          - string
          - "null"
          format: uuid
          description: Tenant ID
        userUuid:
          type:
          - string
          - "null"
          format: uuid
          description: User UUID
        apiKeyId:
          type:
          - string
          - "null"
          format: uuid
          description: API key ID (null if authenticated via JWT)
        authMethod:
          type:
          - string
          - "null"
          description: Authentication method used
          enum:
          - JWT
          - API_KEY
          example: JWT
        requestedModelAlias:
          type:
          - string
          - "null"
          description: Model alias requested by the client
          example: general
        resolvedModelName:
          type:
          - string
          - "null"
          description: Actual model name that was resolved
          example: koldan-he-general-v3.2
        usedFallback:
          type:
          - boolean
          - "null"
          description: Whether the fallback model was used
        backendType:
          type:
          - string
          - "null"
          description: Backend type
          enum:
          - INTERNAL
          - WERNICKE
          - GOOGLE
          example: INTERNAL
        state:
          type:
          - string
          - "null"
          description: Session lifecycle state
          enum:
          - CREATED
          - ACTIVE
          - FINISHED
          - CANCELLED
          - FAILED
          example: FINISHED
        failureReason:
          type:
          - string
          - "null"
          description: Failure reason (if state is FAILED or CANCELLED)
        source:
          type:
          - string
          - "null"
          description: Session source transport
          enum:
          - WEBSOCKET
          - GRPC_API
          example: WEBSOCKET
        startTime:
          type:
          - string
          - "null"
          format: date-time
          description: Session start timestamp
        endTime:
          type:
          - string
          - "null"
          format: date-time
          description: Session end timestamp (null if still active)
        durationMilliseconds:
          type:
          - integer
          - "null"
          format: int64
          description: Session duration in milliseconds
        wordsCount:
          type:
          - integer
          - "null"
          format: int32
          description: Total number of recognized words
        segmentCount:
          type:
          - integer
          - "null"
          format: int32
          description: Total number of finalized segments
        recordingRequested:
          type:
          - boolean
          - "null"
          description: Whether audio recording was requested for this session
        itnRequested:
          type:
          - boolean
          - "null"
          description: Whether inverse text normalization was requested for this session
        diarizationRequested:
          type:
          - boolean
          - "null"
          description: Whether online diarization was requested for this session
        diarizationRequestedMaxSpeakersCount:
          type:
          - integer
          - "null"
          format: int32
          description: Requested maximum number of speakers for online diarization.
            -1 when not specified.
        recordingPurged:
          type:
          - boolean
          - "null"
          description: Whether the recording has been purged from storage
        recordingPurgedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the recording was purged. Null if not purged.
        isPurged:
          type:
          - boolean
          - "null"
          description: Whether the session's segments and recording have been permanently
            purged
        purgedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the session content was purged. Null if not
            purged.
        clientAddress:
          type:
          - string
          - "null"
          description: Client IP address
        requestId:
          type:
          - string
          - "null"
          description: WebSocket request ID (e.g. ws-abc123)
        wsSessionId:
          type:
          - string
          - "null"
          description: WebSocket session ID assigned by the server
        userAgent:
          type:
          - string
          - "null"
          description: User-Agent header sent by the client during the WebSocket handshake
        metadata:
          type:
          - object
          - "null"
          additionalProperties: {}
          description: Custom key-value metadata associated with the session
    SpeechServiceSessionSegmentResponse:
      type: object
      description: A finalized transcript segment from a streaming session
      properties:
        id:
          type:
          - string
          - "null"
          format: uuid
          description: Segment unique identifier
        segmentIndex:
          type:
          - integer
          - "null"
          format: int32
          description: Zero-based segment index within the session
        transcript:
          type:
          - string
          - "null"
          description: Full transcript text of this segment
        confidence:
          type:
          - number
          - "null"
          format: double
          description: Overall confidence score for this segment
        words:
          type:
          - array
          - "null"
          description: "Word-level details including timing, confidence, and optional\
            \ speaker tag"
          items:
            type: object
            additionalProperties: {}
        startSeconds:
          type:
          - number
          - "null"
          format: double
          description: Start time of the segment in seconds from the beginning of
            the audio
        endSeconds:
          type:
          - number
          - "null"
          format: double
          description: End time of the segment in seconds from the beginning of the
            audio
        createdAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the segment was created
    SentverAliasType:
      type: string
      description: Type of a sentence verification model alias
      enum:
      - FAMILY
      - PINNED
      - CONCRETE
    SentverModelAliasResponse:
      type: object
      description: Public view of a sentence verification model alias
      properties:
        id:
          type: string
          description: Alias identifier that clients pass as the sentver model reference
          example: sentver-default
        type:
          $ref: "#/components/schemas/SentverAliasType"
          description: Alias type
          example: FAMILY
        displayName:
          type: string
          description: Human-readable alias name
          example: Sentence Verification Default
        description:
          type:
          - string
          - "null"
          description: Optional alias description
          example: Default sentence verification model for short speaker-verification
            prompts
        status:
          $ref: "#/components/schemas/SentverModelStatus"
          description: Effective status of the primary resolved model
          example: AVAILABLE
        resolvedModel:
          type: string
          description: Primary concrete resolved model name
          example: sentver-he-v2
        capabilities:
          $ref: "#/components/schemas/SentverModelCapabilities"
          description: Capabilities of the resolved model
        fallbackModel:
          type:
          - string
          - "null"
          description: "Fallback concrete model name, used when the primary model\
            \ is unavailable"
          example: sentver-he-v1
        deprecated:
          type: boolean
          description: Whether the alias is deprecated
          example: false
        deprecationDate:
          type:
          - string
          - "null"
          description: Timestamp when deprecation started (ISO 8601)
          example: 2026-07-01T00:00:00Z
        sunsetDate:
          type:
          - string
          - "null"
          description: Timestamp after which public requests will be rejected with
            410 Gone (ISO 8601)
          example: 2026-09-01T00:00:00Z
        deprecationMessage:
          type:
          - string
          - "null"
          description: Optional migration guidance
        default:
          type:
          - boolean
          - "null"
      required:
      - capabilities
      - deprecated
      - displayName
      - id
      - resolvedModel
      - status
      - type
    SentverModelCapabilities:
      type: object
      description: Capabilities of the resolved sentence verification model
      properties:
        supportedLocales:
          type: array
          description: Supported BCP-47 locales
          example:
          - he-IL
          - en-US
          items:
            type: string
        maxExpectedTextLength:
          type:
          - integer
          - "null"
          format: int32
          description: Maximum accepted expected sentence length in characters
          example: 500
      required:
      - supportedLocales
    SentverModelStatus:
      type: string
      description: Availability status of a sentence verification model
      enum:
      - AVAILABLE
      - DEPRECATED
      - MAINTENANCE
      - INACTIVE
    AliasType:
      type: string
      description: Type of a model alias
      enum:
      - FAMILY
      - PINNED
      - CONCRETE
    ModelAliasResponse:
      type: object
      description: Public model alias information
      properties:
        id:
          type:
          - string
          - "null"
          description: Model alias identifier
        type:
          type: "null"
          $ref: "#/components/schemas/AliasType"
          description: "Alias type: FAMILY, PINNED, or CONCRETE"
        displayName:
          type:
          - string
          - "null"
          description: Human-readable display name
        description:
          type:
          - string
          - "null"
          description: Model description
        status:
          type: "null"
          $ref: "#/components/schemas/ModelStatus"
          description: Model availability status
        currentVersion:
          type:
          - string
          - "null"
          description: Current resolved model version name
        capabilities:
          type: "null"
          $ref: "#/components/schemas/ModelCapabilitiesResponse"
          description: Model capabilities
        deprecated:
          type:
          - boolean
          - "null"
          description: Whether the model alias is deprecated
        deprecationDate:
          type:
          - string
          - "null"
          format: date
          description: Date when the model alias was deprecated
        deprecationMessage:
          type:
          - string
          - "null"
          description: Deprecation message
    ModelCapabilitiesResponse:
      type: object
      description: Model capabilities
      properties:
        languages:
          type:
          - array
          - "null"
          description: Supported BCP-47 language codes
          items:
            type: string
        supportsLangAutodetect:
          type:
          - boolean
          - "null"
          description: Whether the model supports automatic language detection
        supportsStreaming:
          type:
          - boolean
          - "null"
          description: Whether the model supports streaming transcription
        supportsBatch:
          type:
          - boolean
          - "null"
          description: Whether the model supports batch (offline) transcription
        supportsPunctuation:
          type:
          - boolean
          - "null"
          description: Whether the engine provides punctuation and capitalization
        supportsDiarization:
          type:
          - boolean
          - "null"
          description: Whether the engine provides speaker diarization
        supportsItn:
          type:
          - boolean
          - "null"
          description: Whether the engine provides inverse text normalization
    ModelStatus:
      type: string
      description: Availability status of a speech model
      enum:
      - AVAILABLE
      - UNAVAILABLE
      - MAINTENANCE
      - DEPRECATED
    ModelLanguagesResponse:
      type: object
      description: Supported languages for a model
      properties:
        model:
          type:
          - string
          - "null"
          description: Model alias identifier
        supportsLangAutodetect:
          type:
          - boolean
          - "null"
          description: Whether the model supports automatic language detection
        languages:
          type:
          - array
          - "null"
          description: Supported BCP-47 language codes
          items:
            type: string
    FilesFilter:
      type: object
      description: Echo of applied file filters
      properties:
        isDeleted:
          type:
          - boolean
          - "null"
          description: Applied deleted filter value
        isContentDiscarded:
          type:
          - boolean
          - "null"
          description: Applied content discarded filter value
        ingestionStatus:
          type:
          - array
          - "null"
          description: Applied ingestion status filter values
          items:
            type: string
        listeningAudio:
          type: "null"
          $ref: "#/components/schemas/ListeningAudioFilter"
          description: Applied listening audio filters
        name:
          type:
          - string
          - "null"
          description: Applied name search term
        filename:
          type:
          - string
          - "null"
          description: Applied filename search term
        sha256:
          type:
          - string
          - "null"
          description: Applied SHA-256 checksum filter value
        createdAfter:
          type:
          - string
          - "null"
          format: date-time
          description: Applied lower bound for creation date
        createdBefore:
          type:
          - string
          - "null"
          format: date-time
          description: Applied upper bound for creation date
        path:
          type:
          - string
          - "null"
          description: Applied virtual path filter
        recursive:
          type:
          - boolean
          - "null"
          description: Applied recursive flag
        tags:
          type:
          - array
          - "null"
          description: Applied tag filter values
          items:
            type: string
        tagsMatch:
          type:
          - string
          - "null"
          description: Applied tag match mode ('all' or 'any')
    FilesSort:
      type: object
      description: Applied sort order
      properties:
        field:
          type:
          - string
          - "null"
          description: Sort field
          example: creationDate
        direction:
          type:
          - string
          - "null"
          description: Sort direction
          example: desc
    ListeningAudioFilter:
      type: object
      description: Echo of applied listening audio filters
      properties:
        status:
          type:
          - array
          - "null"
          description: Applied listening audio status filter values
          items:
            type: string
        deleted:
          type:
          - boolean
          - "null"
          description: Applied listening audio deleted filter value
        contentDiscarded:
          type:
          - boolean
          - "null"
          description: Applied listening audio content discarded filter value
    SpeechServiceFilesListResponse:
      type: object
      description: Paginated list of media files with applied filters and sort order
      properties:
        files:
          type:
          - array
          - "null"
          description: Array of file objects
          items:
            $ref: "#/components/schemas/SpeechServiceFileResponse"
        directories:
          type:
          - array
          - "null"
          description: Immediate subdirectory names under the requested path (only
            present when recursive=false)
          items:
            type: string
        size:
          type:
          - integer
          - "null"
          format: int32
          description: Number of items returned in this page
          example: 20
        total:
          type:
          - integer
          - "null"
          format: int64
          description: Total number of matching items across all pages
          example: 42
        filters:
          type: "null"
          $ref: "#/components/schemas/FilesFilter"
          description: Echo of applied filters
        sort:
          type: "null"
          $ref: "#/components/schemas/FilesSort"
          description: Applied sort order
    SpeechServiceFileShareListResponse:
      type: object
      description: List of direct shares for a file
      properties:
        shares:
          type:
          - array
          - "null"
          description: Array of share objects
          items:
            $ref: "#/components/schemas/SpeechServiceFileShareResponse"
    SpeechServiceFileAccessType:
      type: string
      description: Describes how the current user gained access to a shared file
      enum:
      - DIRECT_SHARE
      - INTERNAL
    SharedFilesFilter:
      type: object
      description: Echo of applied shared-with-me filters
      properties:
        accessType:
          type: "null"
          $ref: "#/components/schemas/SpeechServiceFileAccessType"
          description: "Access type filter applied (DIRECT_SHARE, INTERNAL, or null\
            \ for both)"
        name:
          type:
          - string
          - "null"
          description: "Filter by file name (partial, case-insensitive)"
        filename:
          type:
          - string
          - "null"
          description: "Filter by original filename (partial, case-insensitive)"
    SpeechServiceSharedFileResponse:
      type: object
      description: "A file shared with the current user, including sharing context"
      properties:
        id:
          type:
          - string
          - "null"
          format: uuid
          description: Unique identifier of the file
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        name:
          type:
          - string
          - "null"
          description: Display name of the file
          example: meeting-recording
        filename:
          type:
          - string
          - "null"
          description: Original filename of the uploaded file
          example: meeting-2026-02-25.wav
        description:
          type:
          - string
          - "null"
          description: Description of the file content
          example: Weekly engineering team meeting recording
        path:
          type:
          - string
          - "null"
          description: Virtual directory path of the file (S3-key style). Always starts
            and ends with '/'
          example: /meetings/2026/march/
        size:
          type:
          - integer
          - "null"
          format: int64
          description: File size in bytes
          example: 15728640
        durationSeconds:
          type:
          - number
          - "null"
          format: double
          description: Duration of the media file in seconds
          example: 125.3
        sha256:
          type:
          - string
          - "null"
          description: "SHA-256 checksum of the file content (lowercase hex, 64 characters)"
          example: e5b844cc57f57094ea4585e235f36c78c1cd222262bb89d53c94dcb4d6b3e55d
        ingestionStatus:
          type:
          - string
          - "null"
          description: Ingestion status for URI-imported files. Null for directly
            uploaded files.
          example: COMPLETED
        listeningAudio:
          type: "null"
          $ref: "#/components/schemas/ListeningAudioResponse"
          description: Listening audio sub-object. Null if listening audio has not
            been generated.
        creationDate:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the file was created
        deletedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the file was soft-deleted. Null if isDeleted
            is false.
        purgedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the file's binary data was permanently purged.
            Null if isPurged is false.
        purgeAt:
          type:
          - string
          - "null"
          format: date-time
          description: Scheduled timestamp for automatic purge. Null if not deleted
            or already purged.
        contentDiscardedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the file content was discarded. Null if isContentDiscarded
            is false.
        metadata:
          type:
          - object
          - "null"
          additionalProperties: {}
          description: Additional key-value metadata associated with the file
        tags:
          type:
          - array
          - "null"
          description: "Tag display names assigned to this file, sorted alphabetically\
            \ by canonical name"
          example:
          - Engineering
          - Meeting
          items:
            type: string
        publishMode:
          type:
          - string
          - "null"
          description: "Publish mode controlling file visibility: PRIVATE or INTERNAL"
          enum:
          - PRIVATE
          - INTERNAL
        publishedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the file was first published (set to INTERNAL).
            Null if the file has never been published.
        accessType:
          type: "null"
          $ref: "#/components/schemas/SpeechServiceFileAccessType"
          description: How the current user gained access to this file
          example: DIRECT_SHARE
        permission:
          type:
          - string
          - "null"
          description: Permission level granted to the current user (only for DIRECT_SHARE
            access type)
          enum:
          - VIEW
          - EDIT
          example: VIEW
        sharedBy:
          type:
          - string
          - "null"
          format: uuid
          description: UUID of the user who shared this file (only for DIRECT_SHARE
            access type)
        sharedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the share was created (only for DIRECT_SHARE
            access type)
        deleted:
          type:
          - boolean
          - "null"
        purged:
          type:
          - boolean
          - "null"
        contentDiscarded:
          type:
          - boolean
          - "null"
    SpeechServiceSharedFilesListResponse:
      type: object
      description: Paginated list of files shared with the current user
      properties:
        files:
          type:
          - array
          - "null"
          description: Array of shared file objects
          items:
            $ref: "#/components/schemas/SpeechServiceSharedFileResponse"
        size:
          type:
          - integer
          - "null"
          format: int32
          description: Number of items returned in this page
          example: 20
        total:
          type:
          - integer
          - "null"
          format: int64
          description: Total number of matching items across all pages
          example: 42
        filters:
          type: "null"
          $ref: "#/components/schemas/SharedFilesFilter"
          description: Echo of applied filters
        sort:
          type: "null"
          $ref: "#/components/schemas/FilesSort"
          description: Applied sort order
    SpeakerVerificationServiceListSort:
      type: object
      description: Applied sort order
      properties:
        field:
          type:
          - string
          - "null"
          description: Sort field
          example: createdAt
        direction:
          type:
          - string
          - "null"
          description: Sort direction
          example: desc
    SpeakerVerificationServiceVoicePrintsListFilter:
      type: object
      description: Echo of applied voice print list filters
      properties:
        speakerId:
          type:
          - string
          - "null"
          format: uuid
          description: Applied speaker identifier filter
        model:
          type:
          - string
          - "null"
          description: Applied model alias filter
        resolvedModel:
          type:
          - string
          - "null"
          description: Applied resolved model filter
        isDeleted:
          type:
          - boolean
          - "null"
          description: Applied deleted filter value
        status:
          type:
          - array
          - "null"
          description: Applied status filter values
          items:
            $ref: "#/components/schemas/SpeakerVerificationServiceVoicePrintStatus"
        isActive:
          type:
          - boolean
          - "null"
          description: Applied active filter value
        isDefault:
          type:
          - boolean
          - "null"
          description: Applied default filter value
    SpeakerVerificationServiceVoicePrintsListResponse:
      type: object
      description: Paginated list of speaker voice prints
      properties:
        voicePrints:
          type:
          - array
          - "null"
          description: Array of voice prints
          items:
            $ref: "#/components/schemas/SpeakerVerificationServiceVoicePrintResponse"
        size:
          type:
          - integer
          - "null"
          format: int32
          description: Number of items returned
        total:
          type:
          - integer
          - "null"
          format: int64
          description: Total number of matching items
        filters:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceVoicePrintsListFilter"
          description: Echo of applied filters
        sort:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceListSort"
          description: Applied sort order
    SpeakerVerificationServiceVerificationsListFilter:
      type: object
      description: Echo of applied verification list filters
      properties:
        speakerId:
          type:
          - string
          - "null"
          format: uuid
          description: Applied speaker identifier filter
        decision:
          type:
          - array
          - "null"
          description: Applied decision filter values
          items:
            $ref: "#/components/schemas/SpeakerVerificationDecision"
        status:
          type:
          - array
          - "null"
          description: Applied status filter values
          items:
            $ref: "#/components/schemas/SpeakerVerificationServiceVerificationRecordStatus"
        createdAfter:
          type:
          - string
          - "null"
          format: date-time
          description: Applied createdAfter filter
        createdBefore:
          type:
          - string
          - "null"
          format: date-time
          description: Applied createdBefore filter
        isDeleted:
          type:
          - boolean
          - "null"
          description: Applied deleted filter value
    SpeakerVerificationServiceVerificationsListResponse:
      type: object
      description: Paginated list of speaker verification records
      properties:
        verifications:
          type:
          - array
          - "null"
          description: Array of verification records
          items:
            $ref: "#/components/schemas/SpeakerVerificationServiceVerificationResponse"
        size:
          type:
          - integer
          - "null"
          format: int32
          description: Number of items returned
        total:
          type:
          - integer
          - "null"
          format: int64
          description: Total number of matching items
        filters:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceVerificationsListFilter"
          description: Echo of applied filters
        sort:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceListSort"
          description: Applied sort order
    SpeakerEmbeddingModelStatus:
      type: string
      description: Availability status of a speaker embedding model
      enum:
      - AVAILABLE
      - DEPRECATED
      - MAINTENANCE
      - INACTIVE
    SpeakerVerificationServiceSpeakersListFilter:
      type: object
      description: Echo of applied speaker list filters
      properties:
        isDeleted:
          type:
          - boolean
          - "null"
          description: Applied deleted filter value
        status:
          type:
          - array
          - "null"
          description: Applied status filter values
          items:
            $ref: "#/components/schemas/SpeakerVerificationServiceSpeakerStatus"
        verificationStatus:
          type:
          - array
          - "null"
          description: Applied verification status filter values
          items:
            $ref: "#/components/schemas/SpeakerVerificationServiceVerificationStatus"
        voicePrintModel:
          type:
          - string
          - "null"
          description: Applied voice print resolved model filter
        voicePrintModelAlias:
          type:
          - string
          - "null"
          description: Applied voice print model alias filter
        voicePrintModelStatus:
          type:
          - string
          - "null"
          description: Applied voice print model status filter
    SpeakerVerificationServiceSpeakersListResponse:
      type: object
      description: Paginated speaker identity list
      properties:
        speakers:
          type:
          - array
          - "null"
          description: Speaker identities in this page
          items:
            $ref: "#/components/schemas/SpeakerVerificationServiceSpeakerResponse"
        size:
          type:
          - integer
          - "null"
          format: int32
          description: Number of items returned
        total:
          type:
          - integer
          - "null"
          format: int64
          description: Total number of matching items
        filters:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceSpeakersListFilter"
          description: Applied filters
        sort:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceListSort"
          description: Applied sort order
    SpeakerVerificationServiceEnrollmentsListFilter:
      type: object
      description: Echo of applied enrollment list filters
      properties:
        isDeleted:
          type:
          - boolean
          - "null"
          description: Applied deleted filter value
        status:
          type:
          - array
          - "null"
          description: Applied status filter values
          items:
            $ref: "#/components/schemas/SpeakerVerificationServiceEnrollmentStatus"
    SpeakerVerificationServiceEnrollmentsListResponse:
      type: object
      description: Speaker enrollment list
      properties:
        speakerId:
          type:
          - string
          - "null"
          format: uuid
          description: Parent speaker identifier
        enrollments:
          type:
          - array
          - "null"
          description: Enrollment records
          items:
            $ref: "#/components/schemas/SpeakerVerificationServiceEnrollmentResponse"
        size:
          type:
          - integer
          - "null"
          format: int32
          description: Number of items returned
        total:
          type:
          - integer
          - "null"
          format: int64
          description: Total number of matching items
        filters:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceEnrollmentsListFilter"
          description: Applied filters
        sort:
          type: "null"
          $ref: "#/components/schemas/SpeakerVerificationServiceListSort"
          description: Applied sort order
    SpeakerVerificationServiceEnrollmentEmbeddingResponse:
      type: object
      description: Enrollment embedding record
      properties:
        id:
          type:
          - string
          - "null"
          format: uuid
          description: Embedding identifier
        enrollmentId:
          type:
          - string
          - "null"
          format: uuid
          description: Parent enrollment identifier
        speakerId:
          type:
          - string
          - "null"
          format: uuid
          description: Parent speaker identifier
        modelAlias:
          type:
          - string
          - "null"
          description: Requested embedding model alias
        resolvedModel:
          type:
          - string
          - "null"
          description: Resolved embedding model that produced this embedding
        modelHash:
          type:
          - string
          - "null"
          description: Model space hash for vector compatibility validation
        dimension:
          type:
          - integer
          - "null"
          format: int32
          description: Embedding vector dimension
        createdAt:
          type:
          - string
          - "null"
          format: date-time
          description: Creation timestamp
    SpeakerVerificationServiceEnrollmentEmbeddingsListResponse:
      type: object
      description: Enrollment embeddings list response
      properties:
        enrollmentId:
          type:
          - string
          - "null"
          format: uuid
          description: Parent enrollment identifier
        embeddings:
          type:
          - array
          - "null"
          description: Array of embedding records
          items:
            $ref: "#/components/schemas/SpeakerVerificationServiceEnrollmentEmbeddingResponse"
        size:
          type:
          - integer
          - "null"
          format: int32
          description: Number of items returned
        total:
          type:
          - integer
          - "null"
          format: int64
          description: Total number of matching items
    VerificationAnalyticsGranularity:
      type: string
      description: Time bucket granularity for verification analytics
      enum:
      - TOTAL
      - DAY
      - WEEK
      - MONTH
    VerificationAnalyticsBucket:
      type: object
      description: Analytics data for a single time bucket
      properties:
        periodStart:
          type:
          - string
          - "null"
          format: date-time
          description: Inclusive start of the bucket period (ISO 8601 UTC)
        periodEnd:
          type:
          - string
          - "null"
          format: date-time
          description: Exclusive end of the bucket period (ISO 8601 UTC)
        processingStats:
          type: "null"
          $ref: "#/components/schemas/VerificationAnalyticsProcessingStats"
          description: Processing outcome statistics for this bucket
        decisionStats:
          type: "null"
          $ref: "#/components/schemas/VerificationAnalyticsDecisionStats"
          description: Final combined decision statistics (speaker-embedding + sentence
            verification policy applied together). Do not use this as a direct quality
            metric for a single model or voice print — use speakerDecisionStats or
            sentenceDecisionStats for that.
        speakerDecisionStats:
          type: "null"
          $ref: "#/components/schemas/VerificationAnalyticsDecisionStats"
          description: "Speaker-embedding sub-decision statistics only. When filtering\
            \ by model or voicePrintId, this is the directly attributable dimension."
        sentenceDecisionStats:
          type: "null"
          $ref: "#/components/schemas/VerificationAnalyticsDecisionStats"
          description: "Sentence-verification sub-decision statistics only. When filtering\
            \ by sentverModel or sentverResolvedModel, this is the directly attributable\
            \ dimension."
    VerificationAnalyticsDecisionStats:
      type: object
      description: Decision outcome counts and rates for completed verifications in
        a time bucket
      properties:
        totalDecided:
          type:
          - integer
          - "null"
          format: int64
          description: Number of completed verifications that produced a decision
        accept:
          type:
          - integer
          - "null"
          format: int64
          description: Number of ACCEPT decisions
        review:
          type:
          - integer
          - "null"
          format: int64
          description: Number of REVIEW decisions
        reject:
          type:
          - integer
          - "null"
          format: int64
          description: Number of REJECT decisions
        acceptRate:
          type:
          - number
          - "null"
          format: double
          description: Fraction of decided verifications that were ACCEPT (accept
            / totalDecided). Null when totalDecided is 0.
        reviewRate:
          type:
          - number
          - "null"
          format: double
          description: Fraction of decided verifications that were REVIEW (review
            / totalDecided). Null when totalDecided is 0.
        rejectRate:
          type:
          - number
          - "null"
          format: double
          description: Fraction of decided verifications that were REJECT (reject
            / totalDecided). Null when totalDecided is 0.
    VerificationAnalyticsFilters:
      type: object
      description: Applied filter dimensions for the analytics query
      properties:
        speakerId:
          type:
          - string
          - "null"
          format: uuid
          description: "Speaker filter applied to the query, or null for all speakers"
        embeddingsModel:
          type:
          - string
          - "null"
          description: "Speaker-embeddings model alias filter applied to the query,\
            \ or null for all models"
        embeddingsResolvedModel:
          type:
          - string
          - "null"
          description: "Resolved (concrete) speaker-embeddings model name filter,\
            \ or null for all"
        voicePrintId:
          type:
          - string
          - "null"
          format: uuid
          description: "Voice print filter applied to the query, or null for all voice\
            \ prints"
        sentverModel:
          type:
          - string
          - "null"
          description: "Sentence verification model alias filter (e.g. en-sentver-v1),\
            \ or null for all"
        sentverResolvedModel:
          type:
          - string
          - "null"
          description: "Resolved (concrete) sentence verification model name filter,\
            \ or null for all"
    VerificationAnalyticsProcessingStats:
      type: object
      description: Processing outcome counts and rates for a time bucket
      properties:
        total:
          type:
          - integer
          - "null"
          format: int64
          description: Total number of verification attempts in this bucket
        completed:
          type:
          - integer
          - "null"
          format: int64
          description: Number of successfully completed verifications
        failed:
          type:
          - integer
          - "null"
          format: int64
          description: Number of failed verifications
        successRate:
          type:
          - number
          - "null"
          format: double
          description: Fraction of verifications that completed successfully (completed
            / total). Null when total is 0.
        errorRate:
          type:
          - number
          - "null"
          format: double
          description: Fraction of verifications that failed (failed / total). Null
            when total is 0.
    VerificationAnalyticsResponse:
      type: object
      description: Speaker verification analytics response with time-bucketed statistics
      properties:
        from:
          type:
          - string
          - "null"
          format: date-time
          description: Inclusive start of the requested period (ISO 8601 UTC)
        to:
          type:
          - string
          - "null"
          format: date-time
          description: Exclusive end of the requested period (ISO 8601 UTC)
        granularity:
          type: "null"
          $ref: "#/components/schemas/VerificationAnalyticsGranularity"
          description: Granularity applied to the time buckets
        filters:
          type: "null"
          $ref: "#/components/schemas/VerificationAnalyticsFilters"
          description: Dimension filters applied to this query
        buckets:
          type:
          - array
          - "null"
          description: Time-bucketed analytics data. Empty when no verifications match
            the requested period and filters.
          items:
            $ref: "#/components/schemas/VerificationAnalyticsBucket"
        totals:
          type: "null"
          $ref: "#/components/schemas/VerificationAnalyticsBucket"
          description: Aggregate totals across the entire requested period and filters
        cachedAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when this result was computed or last served from
            cache (ISO 8601 UTC)
        cacheExpiresAt:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when the cached result will be considered stale (ISO
            8601 UTC)
    SpeakerEmbeddingAliasType:
      type: string
      description: Type of a speaker embedding model alias
      enum:
      - FAMILY
      - PINNED
      - CONCRETE
    SpeakerEmbeddingModelAliasResponse:
      type: object
      description: Speaker embedding model alias details
      properties:
        id:
          type: string
          description: Alias identifier that clients pass as the speaker embedding
            model reference
          example: speaker-default
        type:
          $ref: "#/components/schemas/SpeakerEmbeddingAliasType"
          description: Alias type
          example: FAMILY
        displayName:
          type: string
          description: Human-readable alias name
          example: Speaker Default
        description:
          type:
          - string
          - "null"
          description: Optional alias description
          example: Default speaker embedding model for the tenant
        status:
          $ref: "#/components/schemas/SpeakerEmbeddingModelStatus"
          description: Effective status of the resolved model
          example: AVAILABLE
        resolvedModel:
          type: string
          description: Concrete resolved model name
          example: spk-embed-he-v3
        capabilities:
          $ref: "#/components/schemas/SpeakerEmbeddingModelCapabilities"
          description: Capabilities of the resolved model
        deprecated:
          type: boolean
          description: Whether the alias is deprecated
          example: false
        deprecationDate:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp when deprecation started
          example: 2026-07-01T00:00:00Z
        sunsetDate:
          type:
          - string
          - "null"
          format: date-time
          description: Timestamp after which public requests reject the alias with
            410 Gone
          example: 2026-09-01T00:00:00Z
        deprecationMessage:
          type:
          - string
          - "null"
          description: Optional migration guidance
          example: Please migrate to speaker-default-v3 before the sunset date
      required:
      - capabilities
      - deprecated
      - displayName
      - id
      - resolvedModel
      - status
      - type
    SpeakerEmbeddingModelCapabilities:
      type: object
      description: Capabilities of a resolved speaker embedding model
      properties:
        supportedLocales:
          type:
          - array
          - "null"
          description: Supported BCP-47 speaker locales
          example:
          - he-IL
          - en-US
          items:
            type: string
    RetentionPolicyResponse:
      type: object
      description: Retention policy across all services
      properties:
        speech-service:
          type: "null"
          $ref: "#/components/schemas/SpeechServiceRetention"
          description: Retention policy for Speech Services resources
        text-service:
          type: "null"
          $ref: "#/components/schemas/TextServiceRetention"
          description: Retention policy for Text Services resources
        speaker-service:
          type: "null"
          $ref: "#/components/schemas/SpeakerServiceRetention"
          description: Retention policy for Speaker Services resources
    SpeakerServiceRetention:
      type: object
      description: Retention policy for Speaker Services resources
      properties:
        completedSpeakerVerificationRetentionDays:
          type:
          - integer
          - "null"
          format: int32
        failedSpeakerVerificationRetentionDays:
          type:
          - integer
          - "null"
          format: int32
        deletedSpeakerVerificationRetentionDays:
          type:
          - integer
          - "null"
          format: int32
        speakerVerificationProbeAudioRetentionDays:
          type:
          - integer
          - "null"
          format: int32
        readySpeakerEnrollmentRecordingRetentionDays:
          type:
          - integer
          - "null"
          format: int32
        failedSpeakerEnrollmentRetentionDays:
          type:
          - integer
          - "null"
          format: int32
        deletedSpeakerEnrollmentRetentionDays:
          type:
          - integer
          - "null"
          format: int32
        archivedSpeakerEnrollmentRetentionDays:
          type:
          - integer
          - "null"
          format: int32
        inactiveModelVoicePrintRetentionDays:
          type:
          - integer
          - "null"
          format: int32
        failedVoicePrintRetentionDays:
          type:
          - integer
          - "null"
          format: int32
        deletedVoicePrintRetentionDays:
          type:
          - integer
          - "null"
          format: int32
        deletedSpeakerRetentionDays:
          type:
          - integer
          - "null"
          format: int32
    SpeechServiceRetention:
      type: object
      description: Retention policy for Speech Services resources
      properties:
        deletedFileContentRetentionDays:
          type:
          - integer
          - "null"
          format: int32
          description: Days a soft-deleted file is retained before permanent purge
          example: 30
        fileContentRetentionDays:
          type:
          - integer
          - "null"
          format: int32
          description: Days after file creation before the source media binary is
            automatically discarded
          example: 90
        completedTranscriptionResultRetentionDays:
          type:
          - integer
          - "null"
          format: int32
          description: Days a completed job's transcription result is retained
          example: 90
        failedTranscriptionRetentionDays:
          type:
          - integer
          - "null"
          format: int32
          description: Days a failed or cancelled job record is retained before auto-deletion
          example: 30
        deletedTranscriptionRetentionDays:
          type:
          - integer
          - "null"
          format: int32
          description: Days a soft-deleted job's result/error data is retained before
            permanent purge
          example: 30
        completedSummaryResultRetentionDays:
          type:
          - integer
          - "null"
          format: int32
          description: Days a completed summary's result is retained
          example: 90
        failedSummaryRetentionDays:
          type:
          - integer
          - "null"
          format: int32
          description: Days a failed or cancelled summary record is retained before
            auto-deletion
          example: 30
        deletedSummaryRetentionDays:
          type:
          - integer
          - "null"
          format: int32
          description: Days a soft-deleted summary's result/error data is retained
            before permanent purge
          example: 30
        completedTranslationResultRetentionDays:
          type:
          - integer
          - "null"
          format: int32
          description: Days a completed translation's result is retained
          example: 90
        failedTranslationRetentionDays:
          type:
          - integer
          - "null"
          format: int32
          description: Days a failed or cancelled translation record is retained before
            auto-deletion
          example: 30
        deletedTranslationRetentionDays:
          type:
          - integer
          - "null"
          format: int32
          description: Days a soft-deleted translation's result/error data is retained
            before permanent purge
          example: 30
        completedListeningAudioRetentionDays:
          type:
          - integer
          - "null"
          format: int32
          description: Days a completed listening audio MP3 is retained after creation
          example: 90
        deletedListeningAudioRetentionDays:
          type:
          - integer
          - "null"
          format: int32
          description: Days a soft-deleted listening audio MP3 is retained before
            permanent purge
          example: 30
        listeningAudioContentRetentionDays:
          type:
          - integer
          - "null"
          format: int32
          description: Days after creation before a listening audio MP3 is automatically
            discarded
          example: 90
        completedStreamSessionRetentionDays:
          type:
          - integer
          - "null"
          format: int32
          description: Days a completed streaming session's segments and recording
            are retained
          example: 90
        failedStreamSessionRetentionDays:
          type:
          - integer
          - "null"
          format: int32
          description: Days a failed/cancelled streaming session is retained before
            auto-deletion
          example: 90
        deletedStreamSessionRetentionDays:
          type:
          - integer
          - "null"
          format: int32
          description: Days a soft-deleted streaming session's segments and recording
            are retained before permanent purge
          example: 0
        streamSessionRecordingRetentionDays:
          type:
          - integer
          - "null"
          format: int32
          description: Days a streaming session's audio recording is retained before
            automatic purge (independent of segment retention)
          example: 30
    TextServiceRetention:
      type: object
      description: Retention policy for Text Services resources
      properties:
        textTranslationHistoryRetentionDays:
          type:
          - integer
          - "null"
          format: int32
          description: Days a text translation history record is retained before automatic
            purge
          example: 90
        deletedTextTranslationRetentionDays:
          type:
          - integer
          - "null"
          format: int32
          description: Days a soft-deleted text translation's input/output data is
            retained before permanent purge
          example: 30
    QuotaEntry:
      type: object
      description: "Quota usage entry showing limit, current usage, and available\
        \ amount"
      properties:
        limit:
          type:
          - integer
          - "null"
          format: int64
          description: The maximum allowed value for this quota type
          example: 10737418240
        used:
          type:
          - integer
          - "null"
          format: int64
          description: The current usage for this quota type
          example: 3221225472
        available:
          type:
          - integer
          - "null"
          format: int64
          description: The remaining amount available (limit - used)
          example: 7516192768
    QuotasResponse:
      type: object
      description: Quota limits and usage across all services
      properties:
        speech-service:
          type: "null"
          $ref: "#/components/schemas/SpeechServiceQuotas"
          description: Quotas for Speech Services operations
        text-service:
          type: "null"
          $ref: "#/components/schemas/TextServiceQuotas"
          description: Quotas for Text Services operations
        speaker-service:
          type: "null"
          $ref: "#/components/schemas/SpeakerServiceQuotas"
          description: Quotas for Speaker Services operations
    SpeakerServiceQuotas:
      type: object
      description: Speaker Service quota usage
      properties:
        monthlyVerifications:
          type: "null"
          $ref: "#/components/schemas/QuotaEntry"
          description: Monthly speaker verification requests quota
        monthlyEnrollments:
          type: "null"
          $ref: "#/components/schemas/QuotaEntry"
          description: Monthly speaker enrollment creation quota
        monthlyVoicePrintBuilds:
          type: "null"
          $ref: "#/components/schemas/QuotaEntry"
          description: Monthly voice-print build/rebuild quota
        biometricStorage:
          type: "null"
          $ref: "#/components/schemas/QuotaEntry"
          description: Retained biometric storage quota in bytes
        speakers:
          type: "null"
          $ref: "#/components/schemas/QuotaEntry"
          description: Active speaker object count quota
    SpeechServiceQuotas:
      type: object
      description: Speech Service quota usage
      properties:
        storage:
          type: "null"
          $ref: "#/components/schemas/QuotaEntry"
          description: Storage quota (bytes)
        transcription:
          type: "null"
          $ref: "#/components/schemas/QuotaEntry"
          description: Monthly transcription minutes quota
        summaries:
          type: "null"
          $ref: "#/components/schemas/QuotaEntry"
          description: Monthly summary requests quota
        summaryTokens:
          type: "null"
          $ref: "#/components/schemas/QuotaEntry"
          description: Monthly summary tokens quota (total LLM tokens)
        translations:
          type: "null"
          $ref: "#/components/schemas/QuotaEntry"
          description: Monthly translation requests quota
        translationTokens:
          type: "null"
          $ref: "#/components/schemas/QuotaEntry"
          description: Monthly translation tokens quota (total LLM tokens)
    TextServiceQuotas:
      type: object
      description: Text Service quota usage
      properties:
        textTranslations:
          type: "null"
          $ref: "#/components/schemas/QuotaEntry"
          description: Monthly text translation requests quota
        textTranslationTokens:
          type: "null"
          $ref: "#/components/schemas/QuotaEntry"
          description: Monthly text translation tokens quota (total LLM tokens)
    EffectivePermissionsResponse:
      type: object
      properties:
        scopes:
          type:
          - array
          - "null"
          items:
            type: string
    OidcProviderInfo:
      type: object
      description: Public OIDC provider information for client-side authentication
      properties:
        oidcUrl:
          type:
          - string
          - "null"
          description: OIDC issuer URL
          example: https://idp.example.com/realms/myrealm
        clientId:
          type:
          - string
          - "null"
          description: OAuth2 client ID
          example: koldan-web
        scope:
          type:
          - string
          - "null"
          description: OAuth2 scopes
          example: openid profile email
    SiteCapabilitiesResponse:
      type: object
      description: Feature capabilities available on this site
      properties:
        sessionHistory:
          type:
          - boolean
          - "null"
          description: Whether session history is enabled
        sessionHistorySummary:
          type:
          - boolean
          - "null"
          description: Whether session history summary is enabled
        onlineDiarization:
          type:
          - boolean
          - "null"
          description: Whether online diarization is enabled
        speechServices:
          type:
          - boolean
          - "null"
          description: Whether speech services REST API is enabled
        multiTenancy:
          type:
          - boolean
          - "null"
          description: Whether multi-tenancy is enabled
        speechServiceFileInternalPublish:
          type:
          - boolean
          - "null"
          description: Whether speech-service files can be published internally within
            the tenant
        speechServiceFileDirectShare:
          type:
          - boolean
          - "null"
          description: Whether speech-service files can be directly shared between
            users
        speechServiceStreamRecordingEnabled:
          type:
          - boolean
          - "null"
          description: Whether speech-service streaming session audio recording is
            enabled for this tenant
    SitePropertiesResponse:
      type: object
      description: "Site configuration properties, resolved per tenant"
      properties:
        grpcUrl:
          type:
          - string
          - "null"
          description: gRPC server URL
          example: https://koldan.dixilang.com:8194
        consoleUrl:
          type:
          - string
          - "null"
          description: Web console URL
          example: https://koldan.dixilang.com:8193
        updatesUrl:
          type:
          - string
          - "null"
          description: Software updates URL
        updatesUrlV2:
          type:
          - string
          - "null"
          description: Software updates URL (v2)
        siteName:
          type:
          - string
          - "null"
          description: Site name (tenant display name)
          example: Koldan
        oidcProvider:
          type: "null"
          $ref: "#/components/schemas/OidcProviderInfo"
          description: OIDC provider configuration for client-side authentication
        capabilities:
          type: "null"
          $ref: "#/components/schemas/SiteCapabilitiesResponse"
          description: Feature capabilities
    ApiKeyRevokeRequest:
      type: object
      description: Request to revoke an API key
      properties:
        reason:
          type:
          - string
          - "null"
          description: Reason for revoking the API key
          example: Key compromised - rotating credentials
  securitySchemes:
    bearerAuth:
      type: http
      name: bearerAuth
      scheme: bearer
      bearerFormat: JWT
    apiKey:
      type: apiKey
      name: X-API-Key
      in: header
