openapi: 3.0.0
info:
  title: Speech To Text - Xdroid
  version: 1.0.0
  description:  | 
    Xdroid Speech To Text API provides a seamless audio transcription service. 

    ### Key highlights
    
    - **Sandbox:** Full-fledged capabilities.

    - **Security:** HTTPS, OAuth, Rate limit.

    - **Versioning:** Supports version-less API, version tight. If no version is provided (in header) it defaults to latest version. 
  
    ---
    
    [Source view](https://app.swaggerhub.com/apis/kpn/speech-to-text-Xdroid)<br/>
    [Documentation view](https://app.swaggerhub.com/apis-docs/kpn/speech-to-text-Xdroid/)
      
    ---
        
    [KPN Developer](https://developer.kpn.com/)<br/>
    [Getting Started](https://developer.kpn.com/getting-started)
        
    ---

  contact:
    name: API Support Support
    email: api_developer@kpn.com
    url: 'https://developer.kpn.com/support'
  termsOfService: 'https://developer.kpn.com/legal'
  
servers:
- url: https://api-prd.kpn.com/data/kpn/voiceanalytics

security:
  - oauth2: []

tags:
  - name: Upload audio
    description: |
        Uploads an audio file and start a new analytics job.
  - name: Retrieve transcription
    description: | 
        To retrieve transcritions, check the processing status with your unique **job_id**. 
    
        Please do not use intervals that are shorter than 10 seconds to check status to avoid a throttle penalty.

paths:
  /job:
    post:
      tags:
        - Upload audio
      summary: Submits audio files for analyis.
      description: >-
        To create a new transcript use the following recommendations: 

        + Accepted container formats:
          - .wav
          - .mp3 / .mp4
          - .opus / .ogg
          
        + Preferred requirements:
          - Bitrate: 64 Kbit/s per channel (stero recording is supported)
          - Sample rate: 8 KHz
          - Uncompressed files preferred

        + Max audio file size: 150 MB.
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                config:
                  type: object
                  description: |
                    A JSON object defining the language of the audio file. For example: 
                    
                    `{"language":"en","recording_start":"20201119121111" }` or
                    `{"language":"en","recording_start":"" }`
                    
                    Body parameter | Description
                    ---------------|----------------------
                    `language` | The parameter `language` is required in ISO language code. Supported language codes: </br> Global English: `en` </br> Global Spanish: `es` </br> Dutch: `nl` </br> French: `fr `</br> Example: `{"language":"en"}`
                    `recording_start` | Day and time when the recording starts. Optional </br> Format: `YmdHis`. Example: `20201216081228`
                    
                    
                audio_file:
                  type: string
                  format: binary
                  description: Attach the audio file to be transcribed. Requirements see above.
      responses:
        200:
          $ref: '#/components/responses/ok'
        400:
          $ref: '#/components/responses/bad_request'
        401:
          $ref: '#/components/responses/unauthorized'
        404:
          $ref: '#/components/responses/not_found'
        413:
          $ref: '#/components/responses/request_entity_too_large'
        500:
          $ref: '#/components/responses/server_error'
  
  /job/{job_id}:
    get:
      tags:
      - Retrieve transcription
      summary: Retrieves JSON transcript of a finished transcription job.
      description: >-
        Retrieves JSON file with the transcript of a previously uploaded audio file.
         
      parameters:
        - name: job_id
          in: path
          description: ID of job to fetch.
          required: true
          schema:
            $ref: '#/components/parameters/job_id'
      responses:
        200:
          description: Success response if job is found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      job_id:
                        type: integer
                        description: Job ID
                        example: 17424
                      created_at:
                        type: string
                        description: Job creation timestamp
                        example: "2020-11-19 15:26:06"
                      audio_file:
                        type: string
                        description: Uploaded audio file name
                        example: "0036550e-720f-1239-0b99-eecf4973.wav"
                      status:
                        type: string
                        description: Waiting | PROCESSING | Analyzed  
                        enum: ['queued', 'processing', 'parsing', 'analyzed']
                  results:
                    type: object
                    properties:
                      data_type:
                        type: string
                        example: TRANSCRIPT
                      data_channel:
                        type: integer
                        description: 0 = first speaker, 1 = second speaker
                        example: 1
                      data_detect_start:
                        type: integer
                        description: block start in millisec
                        example: 8820
                      data_detect_end:
                        type: integer
                        description: block end in millisec
                        example: 9070
                      data_length:
                        type: integer
                        description: block length in millisec
                        example: 250
                      data_probability:
                        type: integer
                        description: probability of result
                        example: 0.83 
                        

        400:
          $ref: '#/components/responses/bad_request'
        401:
          $ref: '#/components/responses/unauthorized'
        404:
          $ref: '#/components/responses/not_found'
        413:
          $ref: '#/components/responses/request_entity_too_large'
        500:
          $ref: '#/components/responses/server_error'

components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials
          scopes : {}
  schemas:
    job:
      type: object
      properties:
        job_id:
          type: integer
          description: The job_id identifies your request, you should refer to this identifier later.
          example: 17424
    error:
      type: object
      properties:
        transactionId:
          type: string
          description: Transaction ID of the the request.
          title: Transaction ID
        status:
          type: string
          description: Status
          title: Status
        name:
          type: string
          description: Error name
          title: Error name
        message:
          type: string
          description: Error message
          title: Error message
        info:
          type: string
          description: Additional information about error.
          title: Info 

    
  responses:
    ok:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/job'
            
    bad_request:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'

    unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    not_found:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    server_error:
      description: Server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    request_entity_too_large:
      description: Request entity too large
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
            
  parameters:
    job_id:
      in: path
      name: Job ID
      schema:
        type: string
      required: true
      description: ID of job to show