openapi: 3.0.1
info:
  title: Streaming Speech-To-Text API Documentation
  version: v1
  description: Rev AI Streaming Speech-To-Text API Documentation
servers:
  - url: https://api.rev.ai
    description: Rev AI API
security:
  - AccessToken: []
tags:
  - name: Vocabularies
paths:
  /vocabularies:
    post:
      summary: Submit Custom Vocabulary
      operationId: SubmitCustomVocabulary
      tags:
        - Vocabularies
      description: |
        Submits a Custom Vocabulary for asynchronous processing.
      requestBody:
        description: Custom Vocabulary Definition
        required: true
        content:
          application/json:
            schema:
              allOf:
                - type: object
                  required:
                    - custom_vocabularies
                  properties:
                    metadata:
                      description: Optional metadata that was provided during submission
                    callback_url:
                      $ref: '#/components/schemas/CallbackUrlField'
                    notification_config:
                      $ref: '#/components/schemas/NotificationConfig'
                    strict:
                      $ref: '#/components/schemas/Strict'
                - $ref: '#/components/schemas/CustomVocabulariesProperties'
                - $ref: '#/components/schemas/DescriptionlessMetadataProperties'
            examples:
              Example:
                value:
                  metadata: example metadata
                  notification_config:
                    url: https://www.example.com/callback
                    auth_headers:
                      Authorization: Bearer <token>
                  custom_vocabularies:
                    - phrases:
                        - Paul McCartney
                        - Amelia Earhart
                        - Weiss-Bergman
                        - BLM
      responses:
        '200':
          $ref: '#/components/responses/CustomVocabularyDetailsResponse'
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestProblemDetails'
              example:
                parameter:
                  custom_vocabularies:
                    - The custom_vocabularies field is required
                type: https://www.rev.ai/api/v1/errors/invalid-parameters
                title: Your request parameters didn't validate
                status: 400
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenDeployment'
        '404':
          $ref: '#/components/responses/DeploymentUnsupported'
    get:
      summary: Get List of Custom Vocabularies
      operationId: GetCustomVocabularies
      tags:
        - Vocabularies
      description: |
        Gets a list of most recent custom vocabularies' processing information
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 0
            maximum: 1000
          required: false
          description: >-
            Limits the number of custom vocabulary details returned, default is
            100, max is 1000
      responses:
        '200':
          $ref: '#/components/responses/CustomVocabulariesDetailsResponse'
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestProblemDetails'
              example:
                parameter:
                  limit:
                    - The field limit must be between 0 and 1000.
                type: https://www.rev.ai/api/v1/errors/invalid-parameters
                title: Your request parameters didn't validate
                status: 400
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenDeployment'
        '404':
          $ref: '#/components/responses/DeploymentUnsupported'
  /vocabularies/{id}:
    parameters:
      - $ref: '#/components/parameters/vocabulary_id'
    get:
      summary: Get Custom Vocabulary
      operationId: GetCustomVocabulary
      tags:
        - Vocabularies
      description: |
        Gets the custom vocabulary processing information
      responses:
        '200':
          $ref: '#/components/responses/CustomVocabularyDetailsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenDeployment'
        '404':
          $ref: '#/components/responses/CustomVocabularyNotFound'
    delete:
      summary: Delete Custom Vocabulary
      operationId: DeleteCustomVocabulary
      tags:
        - Vocabularies
      description: >
        Deletes a custom vocabulary. All data related to the custom vocabulary,
        such as webhooks and metadata, will be permanently deleted. A custom
        vocabulary can only be deleted once it's completed (either with success
        or failure).
      responses:
        '204':
          description: Custom vocabulary was successfully deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenDeployment'
        '404':
          $ref: '#/components/responses/CustomVocabularyNotFound'
        '409':
          $ref: '#/components/responses/CustomVocabularyInvalidDeletionState'
components:
  securitySchemes:
    AccessToken:
      type: http
      scheme: bearer
  schemas:
    CustomVocabularyDetails:
      type: object
      description: >
        Custom Vocabulary Details

        ***

        Note: properties are not displayed in the returned object if they are
        null
      properties:
        id:
          type: string
          description: Id of the Custom Vocabulary
          example: cvUmx5c6F7pH7r
        status:
          type: string
          enum:
            - in_progress
            - complete
            - failed
          description: Current status of the custom vocabulary
          example: complete
        created_on:
          type: string
          format: dateTime
          description: >-
            The date and time the custom vocabulary was submitted in ISO-8601
            UTC form
          example: '2018-05-05T23:23:22.29Z'
        completed_on:
          type: string
          format: dateTime
          description: >-
            The date and time the custom vocabulary was completed on, whether
            successful or failure, in ISO-8601 UTC form
          nullable: true
          example: '2018-05-05T23:28:22.29Z'
        metadata:
          type: string
          description: >-
            Optional metadata that was provided during custom vocabulary
            submission
          maxLength: 512
          nullable: true
          example: sample metadata
        callback_url:
          $ref: '#/components/schemas/CallbackUrlField'
        failure:
          type: string
          description: >-
            Simple reason of why the transcription job failed. Check
            `failure_detail` for specific details and solutions
          enum:
            - internal_processing
          nullable: true
          example: internal_processing
        failure_detail:
          type: string
          description: Human-readable reason why the job failed
          nullable: true
          example: Failed to process. Please check your url and file type
      example:
        id: cvUmx5c6F7pH7r
        status: in_progress
        created_on: '2018-05-05T23:23:22.29Z'
    CustomVocabulariesDetails:
      type: array
      description: |
        List of Custom Vocabularies' Details
      items:
        type: object
        $ref: '#/components/schemas/CustomVocabularyDetails'
      example:
        - id: cvUmx5c6F7pH7r
          status: in_progress
          created_on: '2018-05-05T23:23:22.29Z'
          callback_url: https://www.example.com/callback
        - id: cvx5c6F7pcvUmH
          status: complete
          created_on: '2018-05-05T23:23:22.29Z'
          completed_on: '2018-05-05T23:45:13.41Z'
          callback_url: https://www.example.com/callback
        - id: cv6F7aspH7rUmx
          status: failed
          created_on: '2018-05-05T23:23:22.29Z'
          completed_on: '2018-05-05T23:23:24.11Z'
          failure: internal_processing
          failure_detail: Internal processing failure
    CallbackUrlField:
      deprecated: true
      type: string
      maxLength: 1024
      description: >
        *Deprecated. Use notification_config instead*. Optional callback url to
        invoke when processing is complete.

        If this parameter is used to pass in the callback url, the callback url
        will be visible in the response.

        It is recommended to provide webhooks with the `notification_config`
        parameter as authorization headers can be included

        and both the callback url and auth headers will be encrypted when
        stored.
      nullable: true
      example: https://www.example.com/callback
    BaseProblemDetails:
      type: object
      description: Problem details object returned on errors
      properties:
        title:
          type: string
          description: Short, human-readable summary of the problem type
        type:
          type: string
          description: URI that identifies the problem
        status:
          type: integer
          description: HTTP status code of the error
    BadRequestProblemDetails:
      allOf:
        - $ref: '#/components/schemas/BaseProblemDetails'
        - type: object
          properties:
            parameters:
              description: >-
                Invalid properties object where each property is the key, mapped
                to a list of reasons why the property is invalid
              type: object
              additionalProperties: true
    NotificationConfig:
      type: object
      nullable: true
      description: >
        Optional configuration for a callback url to invoke when processing is
        complete, in addition to auth

        headers if they are needed to invoke the callback url.

        Cannot be set if `callback_url` is set.

        This option will not be visible in the submission response.
      required:
        - url
      properties:
        url:
          type: string
          description: Optional callback url to invoke when processing is complete
          maxLength: 2048
          example: https://www.example.com/callback
        auth_headers:
          description: >-
            Optional authorization headers, if they are needed to invoke the
            callback. There are a few constraints: 1) the “Authorization” header
            is the only header that can be passed in, and 2) the header value
            must be of the form `<scheme> <token>`. For example:
            `{"Authorization": "Bearer $BEARER_TOKEN"}`
          type: object
          nullable: true
          properties:
            Authorization:
              type: string
              example: Bearer <token>
          required:
            - Authorization
          maxLength: 1000
    Strict:
      type: boolean
      example: true
      description: >-
        If true, only exact phrases will be used as custom vocabulary, i.e.
        phrases will not be split into individual words for processing. By
        default is enabled.
    CustomVocabulariesField:
      type: array
      minItems: 1
      maxItems: 50
      items:
        type: object
        description: >-
          Contains a collection of phrases. Custom vocabulary informs and biases
          the speech recognition to find those phrases (at the cost of slightly
          slower transcription).
        required:
          - phrases
        properties:
          phrases:
            type: array
            minItems: 1
            maxItems: 6000
            description: >
              Array of phrases not found in normal dictionary. Add technical
              jargon, proper nouns and uncommon phrases as strings in this array
              to add them to the lexicon for this job.


              A phrase must contain at least 1 alpha character but may contain
              any non-numeric character from the Basic Latin set. A phrase can
              contain up to 12 words. Each word can contain up to 34 characters.


              **Note**: Only 6000 phrases can be used per transcription job. For
              more details, check [Custom
              Vocabularies](https://docs.rev.ai/api/features/#custom-vocabularies).
            items:
              type: string
              title: phrase
            example:
              - Paul McCartney
              - Amelia Earhart
              - Weiss-Bergman
              - BLM
    CustomVocabulariesProperties:
      type: object
      properties:
        custom_vocabularies:
          $ref: '#/components/schemas/CustomVocabulariesField'
    DescriptionlessMetadataProperties:
      type: object
      properties:
        metadata:
          type: string
          maxLength: 512
          nullable: true
          example: sample metadata
  parameters:
    vocabulary_id:
      name: id
      in: path
      description: Id of a custom vocabulary
      required: true
      schema:
        type: string
  responses:
    CustomVocabularyDetailsResponse:
      description: Custom Vocabulary Job Details
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CustomVocabularyDetails'
          examples:
            New Submission for CustomVocabulary:
              value:
                id: cvUmx5c6F7pH7r
                status: in_progress
                created_on: '2018-05-05T23:23:22.29Z'
                callback_url: https://www.example.com/callback
            Complete CustomVocabulary:
              value:
                id: cvUmx5c6F7pH7r
                status: complete
                created_on: '2018-05-05T23:23:22.29Z'
                completed_on: '2018-05-05T23:45:13.41Z'
                callback_url: https://www.example.com/callback
            Failed CustomVocabulary:
              value:
                id: cvUmx5c6F7pH7r
                status: failed
                created_on: '2018-05-05T23:23:22.29Z'
                completed_on: '2018-05-05T23:23:24.11Z'
                callback_url: https://www.example.com/callback
                failure: internal_processing
                failure_detail: Internal processing failure
    CustomVocabulariesDetailsResponse:
      description: List of Custom Vocabularies' Processing Details
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CustomVocabulariesDetails'
    CustomVocabularyNotFound:
      description: Custom Vocabulary Not Found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/BaseProblemDetails'
          example:
            type: https://www.rev.ai/api/v1/errors/custom-vocabulary-not-found
            title: could not find custom vocabulary
            status: 404
    CustomVocabularyInvalidDeletionState:
      description: Invalid Deletion State
      content:
        application/problem+json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseProblemDetails'
              - type: object
                properties:
                  current_value:
                    type: string
                    description: Value passed in given request
                  allowed_values:
                    type: array
                    description: Allowed values for this request
                    items:
                      type: string
                  detail:
                    type: string
                    description: >-
                      Human-readable explanation specific to this occurrence of
                      the problem
          example:
            allowed_values:
              - complete
              - failed
            current_value: in_progress
            type: https://rev.ai/api/v1/errors/invalid-custom-vocabulary-state
            title: Custom vocabulary is in invalid state
            detail: Custom vocabulary is in invalid state to be deleted
            status: 409
    Unauthorized:
      description: |
        Request Unauthorized
      content:
        application/problem+json:
          schema:
            properties:
              title:
                type: string
                description: Short, human-readable summary of the problem type
              status:
                type: integer
                description: HTTP status code of the error
          example:
            title: Authorization has been denied for this request
            status: 401
    ForbiddenDeployment:
      description: User does not have permission to access this deployment
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/BaseProblemDetails'
          example:
            type: https://www.rev.ai/api/v1/errors/access-denied
            title: >-
              Permisson has been denied for this request - access to this
              deployment is not allowed
            status: 403
    DeploymentUnsupported:
      description: Deployment does not support this API
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/BaseProblemDetails'
          example:
            type: https://www.rev.ai/api/v1/errors/unsupported-api
            title: This api is not supported in this deployment
            status: 404
