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: 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 - Transcriptions
  description: Manage speech transcription jobs.
- name: Subscriptions - Plans
  description: View available subscription plans
- name: Speech - Streaming Sessions
  description: Manage online speech recognition streaming sessions.
- name: Data Retention
  description: Monitor data retention policies
- name: MySubscription
  description: View the caller's subscription.
- name: Site Properties
  description: Global site configuration properties.
- name: Speech - Files - Sharing
  description: Manage direct user shares on speech files.
- name: Speech - Files
  description: Manage media files for speech services.
- 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: Tags
  description: Manage user-scoped tags
- name: API Keys
  description: "Create, rotate and revoke API keys."
- name: Rate Limits
  description: Monitor and manage API rate limits
- name: Permissions - Effective
  description: Inspect the caller's effective permissions.
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/SpeechServiceWebhook"
        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:
        "200":
          description: OK
  /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/SpeechServiceWebhook"
        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:
        "200":
          description: OK
  /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: 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:
        "200":
          description: OK
          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:
        "200":
          description: OK
  /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:
        "200":
          description: OK
  /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:
        "200":
          description: OK
          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:
        "200":
          description: OK
  /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:
        "200":
          description: OK
  /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:
        "200":
          description: OK
  /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:
        "200":
          description: OK
          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:
        "200":
          description: OK
  /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:
        "200":
          description: OK
          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:
        "200":
          description: OK
  /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/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:
        "200":
          description: OK
    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/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:
        "200":
          description: OK
  /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:
        "200":
          description: OK
  /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: 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:
        "200":
          description: OK
  /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:
        "200":
          description: OK
  /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/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:
        "200":
          description: OK
  /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:
    SpeechServiceWebhook:
      type: object
      description: Configuration for webhook notifications
      properties:
        url:
          type: string
          description: The URL to send the webhook notification to. Must be HTTPS.
          example: https://example.com/webhook/jobs
        secret:
          type:
          - string
          - "null"
          description: A shared secret used to sign webhook payloads with HMAC-SHA256
        headers:
          type:
          - object
          - "null"
          additionalProperties:
            type: string
          description: Custom HTTP headers to include in the webhook request
      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. May\
            \ not be respected, depends on the modelUsed only when mode is 'speaker'."
          example: 5
        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/SpeechServiceWebhook"
          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)
    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:
          $ref: "#/components/schemas/SpeechServiceTranscriptionLanguageOptions"
          description: Language configuration for transcription
        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"
      required:
      - language
      - 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/SpeechServiceWebhook"
          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/SpeechServiceWebhook"
          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/SpeechServiceWebhook"
          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
    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:
          - string
          - "null"
          description: Permission level granted to the user
          enum:
          - VIEW
          - EDIT
          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
    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
    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
    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
    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
    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
    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"
    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
        diarizationEnabled:
          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
    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
    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
    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
    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
    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
