openapi: 3.0.3
info:
  title: Speechmatics Batch Transcription API Keys Jobs API
  version: 2.0.0
  description: The Speechmatics Automatic Speech Recognition REST API is used to submit ASR jobs and receive the results. The supported job type is transcription of audio files. Supports 55+ languages, speaker diarization, translation, summarization, sentiment analysis, topic detection, and custom vocabulary.
  contact:
    email: support@speechmatics.com
  x-providerName: speechmatics
  x-serviceName: batch-transcription-api
servers:
- url: https://asr.api.speechmatics.com/v2
  description: Speechmatics Batch ASR API (EU)
- url: https://eu1.asr.api.speechmatics.com/v2
  description: Speechmatics Batch ASR API (EU1)
- url: https://usa.asr.api.speechmatics.com/v2
  description: Speechmatics Batch ASR API (USA)
security:
- bearerAuth: []
tags:
- name: Jobs
paths:
  /jobs:
    post:
      summary: Create a new job
      operationId: createJob
      tags:
      - Jobs
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - config
              properties:
                config:
                  type: string
                  description: JSON containing a JobConfig model.
                data_file:
                  type: string
                  format: binary
                  description: The audio data file to be processed.
      parameters:
      - name: X-SM-Processing-Data
        in: header
        required: false
        schema:
          type: string
        description: On-prem processing settings JSON (parallel_engines, user_id).
      responses:
        '201':
          description: Job created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateJobResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      summary: List all jobs
      operationId: listJobs
      tags:
      - Jobs
      parameters:
      - name: created_before
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: Cursor for paginating by creation time.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
        description: Limit on number of items returned.
      - name: include_deleted
        in: query
        required: false
        schema:
          type: boolean
        description: Include deleted jobs in response.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveJobsResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limited
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /jobs/{jobid}:
    get:
      summary: Get job details
      operationId: getJob
      tags:
      - Jobs
      parameters:
      - name: jobid
        in: path
        required: true
        schema:
          type: string
        description: ID of the job.
        example: a1b2c3d4e5
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveJobResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '410':
          description: Gone (expired)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limited
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      summary: Delete a job
      operationId: deleteJob
      tags:
      - Jobs
      parameters:
      - name: jobid
        in: path
        required: true
        schema:
          type: string
        description: ID of the job to delete.
        example: a1b2c3d4e5
      - name: force
        in: query
        required: false
        schema:
          type: boolean
        description: Force terminate a running job.
      responses:
        '200':
          description: Job deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteJobResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '410':
          description: Gone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '423':
          description: Locked (running job, use force=true)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limited
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /jobs/{jobid}/transcript:
    get:
      summary: Get transcript for a job
      operationId: getTranscript
      tags:
      - Jobs
      parameters:
      - name: jobid
        in: path
        required: true
        schema:
          type: string
        example: a1b2c3d4e5
      - name: format
        in: query
        required: false
        schema:
          type: string
          enum:
          - json-v2
          - txt
          - srt
        description: Transcription output format (default json-v2).
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveTranscriptResponse'
            text/plain:
              schema:
                type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '410':
          description: Gone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limited
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /jobs/{jobid}/log:
    get:
      summary: Get log file for a job
      operationId: getJobLog
      tags:
      - Jobs
      parameters:
      - name: jobid
        in: path
        required: true
        schema:
          type: string
        example: a1b2c3d4e5
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '410':
          description: Gone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limited
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    JobDetails:
      type: object
      required:
      - created_at
      - data_name
      - id
      - status
      properties:
        created_at:
          type: string
          format: date-time
        data_name:
          type: string
        text_name:
          type: string
        duration:
          type: integer
          minimum: 0
        id:
          type: string
          example: a1b2c3d4e5
        status:
          type: string
          enum:
          - running
          - done
          - rejected
          - deleted
          - expired
        config:
          $ref: '#/components/schemas/JobConfig'
        lang:
          type: string
        errors:
          type: array
          items:
            $ref: '#/components/schemas/JobDetailError'
    AutoChaptersConfig:
      type: object
    RecognitionDisplay:
      type: object
      required:
      - direction
      properties:
        direction:
          type: string
          enum:
          - ltr
          - rtl
    NotificationConfig:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          description: URL for job completion callback.
        contents:
          type: array
          items:
            type: string
            enum:
            - jobinfo
            - transcript
            - transcript.json-v2
            - transcript.txt
            - transcript.srt
            - data
            - text
        method:
          type: string
          enum:
          - post
          - put
        auth_headers:
          type: array
          items:
            type: string
    TrackingData:
      type: object
      properties:
        title:
          type: string
          description: The title of the job.
        reference:
          type: string
          description: External system reference.
        tags:
          type: array
          items:
            type: string
        details:
          type: object
          description: Customer-defined JSON structure.
          additionalProperties: true
    ErrorResponse:
      type: object
      required:
      - code
      - error
      properties:
        code:
          type: integer
          description: The HTTP status code.
          minimum: 100
        error:
          type: string
          description: The error message.
          enum:
          - Bad Request
          - File Expired
          - Forbidden
          - Resource Locked
          - Format Not Supported
          - Internal Server Error
          - Job error
          - Job Expired
          - Job In Progress
          - Job is not of type transcription
          - Job not found
          - Job rejected
          - Job rejected due to invalid audio
          - Job rejected due to invalid text
          - Malformed request
          - Missing callback
          - Missing data_file
          - No language selected
          - Not Implemented
          - Permission Denied
          - Requested product not available
          - Transcription not ready
          - Log file not available
          - Unprocessable Entity
          - Max concurrent running jobs exceeded
        detail:
          type: string
          description: The details of the error.
    DataFetchConfig:
      type: object
      required:
      - url
      properties:
        url:
          type: string
        auth_headers:
          type: array
          items:
            type: string
          description: A list of additional headers to be added to the input fetch request.
    TopicDetectionConfig:
      type: object
      properties:
        topics:
          type: array
          items:
            type: string
    SpeakersInputItem:
      type: object
      required:
      - label
      - speaker_identifiers
      properties:
        label:
          type: string
          minLength: 1
        speaker_identifiers:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: string
    JobConfig:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - transcription
        fetch_data:
          $ref: '#/components/schemas/DataFetchConfig'
        fetch_text:
          $ref: '#/components/schemas/DataFetchConfig'
        transcription_config:
          $ref: '#/components/schemas/TranscriptionConfig'
        notification_config:
          type: array
          items:
            $ref: '#/components/schemas/NotificationConfig'
        tracking:
          $ref: '#/components/schemas/TrackingData'
        output_config:
          $ref: '#/components/schemas/OutputConfig'
        translation_config:
          $ref: '#/components/schemas/TranslationConfig'
        language_identification_config:
          $ref: '#/components/schemas/LanguageIdentificationConfig'
        summarization_config:
          $ref: '#/components/schemas/SummarizationConfig'
        sentiment_analysis_config:
          $ref: '#/components/schemas/SentimentAnalysisConfig'
        topic_detection_config:
          $ref: '#/components/schemas/TopicDetectionConfig'
        auto_chapters_config:
          $ref: '#/components/schemas/AutoChaptersConfig'
        audio_events_config:
          $ref: '#/components/schemas/AudioEventsConfig'
    TranscriptionConfig:
      type: object
      required:
      - language
      properties:
        language:
          type: string
          description: Language model to process the audio input (ISO language code).
        domain:
          type: string
          description: Specialized model domain (e.g. finance, medical).
        output_locale:
          type: string
          description: Language locale for transcription output.
        model:
          $ref: '#/components/schemas/Model'
        operating_point:
          $ref: '#/components/schemas/OperatingPoint'
          deprecated: true
        additional_vocab:
          type: array
          items:
            type: object
            required:
            - content
            properties:
              content:
                type: string
              sounds_like:
                type: array
                items:
                  type: string
          description: List of custom words or phrases with optional pronunciations.
        punctuation_overrides:
          type: object
          properties:
            sensitivity:
              type: number
              format: float
              minimum: 0
              maximum: 1
              description: Controls punctuation density (0-1, default 0.5).
            permitted_marks:
              type: array
              items:
                type: string
              description: Accepted punctuation marks.
        diarization:
          type: string
          enum:
          - none
          - speaker
          - channel
          description: Speaker or channel label attribution mode.
        channel_diarization_labels:
          type: array
          items:
            type: string
            pattern: ^[A-Za-z0-9._]+$
          description: Labels for channel diarization.
        enable_entities:
          type: boolean
          description: Include entity objects (dates, numbers) in transcription results.
        max_delay_mode:
          type: string
          enum:
          - fixed
          - flexible
        audio_filtering_config:
          type: object
          properties:
            volume_threshold:
              type: number
              format: float
              minimum: 0
              maximum: 100
        transcript_filtering_config:
          type: object
          properties:
            remove_disfluencies:
              type: boolean
            replacements:
              type: array
              items:
                type: object
                required:
                - from
                - to
                additionalProperties: false
                properties:
                  from:
                    type: string
                  to:
                    type: string
        speaker_diarization_config:
          type: object
          properties:
            prefer_current_speaker:
              type: boolean
            speaker_sensitivity:
              type: number
              format: float
              minimum: 0
              maximum: 1
            get_speakers:
              type: boolean
            speakers:
              type: array
              items:
                $ref: '#/components/schemas/SpeakersInputItem'
    JobDetailError:
      type: object
      required:
      - timestamp
      - message
      properties:
        timestamp:
          type: string
          example: 2021-07-14 11:53:49.242000+00:00
        message:
          type: string
          example: Audio fetch error, http status 418
    RecognitionAlternative:
      type: object
      required:
      - content
      - confidence
      - language
      properties:
        content:
          type: string
        confidence:
          type: number
          format: float
        language:
          type: string
        display:
          $ref: '#/components/schemas/RecognitionDisplay'
        speaker:
          type: string
        tags:
          type: array
          items:
            type: string
    TranslationConfig:
      type: object
      required:
      - target_languages
      properties:
        target_languages:
          type: array
          maxItems: 5
          items:
            type: string
    RetrieveTranscriptResponse:
      type: object
      required:
      - format
      - job
      - metadata
      - results
      properties:
        format:
          type: string
          example: '2.7'
        job:
          type: object
        metadata:
          type: object
        results:
          type: array
          items:
            $ref: '#/components/schemas/RecognitionResult'
        speakers:
          type: array
          items:
            $ref: '#/components/schemas/SpeakersResultItem'
        translations:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/TranslationSentence'
        summary:
          $ref: '#/components/schemas/SummarizationResult'
    RecognitionResult:
      type: object
      required:
      - start_time
      - end_time
      - type
      properties:
        channel:
          type: string
        start_time:
          type: number
          format: float
        end_time:
          type: number
          format: float
        volume:
          type: number
          format: float
          minimum: 0
          maximum: 100
        is_eos:
          type: boolean
        type:
          type: string
          enum:
          - word
          - punctuation
          - entity
        alternatives:
          type: array
          items:
            $ref: '#/components/schemas/RecognitionAlternative'
        attaches_to:
          type: string
          enum:
          - previous
          - next
          - both
          - none
    SummarizationConfig:
      type: object
      properties:
        content_type:
          type: string
          enum:
          - auto
          - informative
          - conversational
        summary_length:
          type: string
          enum:
          - brief
          - detailed
          default: brief
        summary_type:
          type: string
          enum:
          - paragraphs
          - bullets
    SpeakersResultItem:
      type: object
      required:
      - label
      - speaker_identifiers
      properties:
        label:
          type: string
          minLength: 1
        speaker_identifiers:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: string
    OutputConfig:
      type: object
      properties:
        srt_overrides:
          type: object
          properties:
            max_line_length:
              type: integer
            max_lines:
              type: integer
    CreateJobResponse:
      type: object
      required:
      - id
      properties:
        id:
          type: string
          description: The unique ID assigned to the job.
          example: a1b2c3d4e5
    Model:
      type: string
      description: Specific model to use in transcription.
      enum:
      - standard
      - enhanced
    AudioEventsConfig:
      type: object
      properties:
        types:
          type: array
          items:
            type: string
    LanguageIdentificationConfig:
      type: object
      properties:
        expected_languages:
          type: array
          items:
            type: string
        low_confidence_action:
          type: string
          enum:
          - allow
          - reject
          - use_default_language
        default_language:
          type: string
    SummarizationResult:
      type: object
      properties:
        content:
          type: string
    RetrieveJobResponse:
      type: object
      required:
      - job
      properties:
        job:
          $ref: '#/components/schemas/JobDetails'
    DeleteJobResponse:
      type: object
      required:
      - job
      properties:
        job:
          $ref: '#/components/schemas/JobDetails'
    SentimentAnalysisConfig:
      type: object
    TranslationSentence:
      type: object
      properties:
        start_time:
          type: number
          format: float
        end_time:
          type: number
          format: float
        content:
          type: string
        speaker:
          type: string
        channel:
          type: string
    RetrieveJobsResponse:
      type: object
      required:
      - jobs
      properties:
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/JobDetails'
    OperatingPoint:
      type: string
      description: Deprecated. Use model instead.
      enum:
      - standard
      - enhanced
      deprecated: true
  securitySchemes:
    bearerAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Bearer token authentication. Use the format: Bearer $API_KEY_OR_JWT'