openapi: 3.0.1
info:
  termsOfService: https://www.rev.ai/about/terms
  title: Rev AI Forced Alignment
  contact:
    email: support@rev.ai
    name: Rev
    url: https://www.rev.ai/
  version: v1
  description: Rev AI Forced Alignment
servers:
  - url: https://api.rev.ai
    description: Rev AI API
security:
  - AccessToken: []
paths:
  /alignment/v1/jobs:
    post:
      summary: Submit Forced Alignment Job
      operationId: SubmitAlignmentJob
      description: >
        Starts an asynchronous job to obtain precise word timings for an audio
        file and text transcript. Audio can be specified by including a public
        url to the media via the `source_config`. A transcript can be specified
        by including a public url to the text file via the
        `source_transcript_config` or by submitting the text directly in the
        `transcript_text` field. Transcripts should contain only the words of a
        transcript (punctuation is omitted) separated by spaces.
      tags:
        - Jobs
      requestBody:
        description: Forced Alignment Job Options
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitAlignmentJobOptions'
            examples:
              JSON Submission:
                value:
                  metadata: sample user provided metadata
                  notification_config:
                    url: https://www.example.com/callback
                    auth_headers:
                      Authorization: Bearer <notification-url-token>
                  delete_after_seconds: 1000000
                  source_config:
                    url: https://www.rev.ai/FTC_Sample_1.mp3
                    auth_headers:
                      Authorization: Bearer <source-url-token>
                  source_transcript_config:
                    url: >-
                      https://your-bucket.s3.us-west-2.amazonaws.com/transcript.txt
                    auth_headers:
                      Authorization: Bearer <source-url-token>
      responses:
        '200':
          description: Alignment Job Details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlignmentJob'
              examples:
                New Job:
                  $ref: '#/components/examples/NewAlignmentJob'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestProblemDetails'
              examples:
                No Input Media Url:
                  $ref: '#/components/examples/BadRequestNoTranscript'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
      x-code-samples:
        - lang: Shell
          label: curl
          source: >
            # Submit via media URL. URL must be publicly accessible and a direct
            link to media

            curl -X POST "https://api.rev.ai/alignment/v1/jobs" -H
            "Authorization: Bearer $REV_ACCESS_TOKEN" -H "Content-Type:
            application/json" -d "{\"metadata\": \"sample user provided
            metadata\", \"notification_config\": {\"url\":
            \"https://www.example.com/callback\"}, \"delete_after_seconds\":
            1000000, \"source_config\": {\"url:\":
            \"https://www.rev.ai/FTC_Sample_1.mp3\"}, \"transcript_text\":\"hi
            my name's jack\"" 
    get:
      summary: Get List of Forced Alignment Jobs
      operationId: GetListOfAlignmentJobs
      description: >
        Gets a list of alignment jobs submitted within the last 30 days in
        reverse chronological order up to the provided `limit` number of jobs
        per call. **Note:** Jobs older than 30 days will not be listed.
        Pagination is supported via passing the last job `id` from a previous
        call into `starting_after`.
      tags:
        - Jobs
      parameters:
        - $ref: '#/components/parameters/JobListLimit'
        - $ref: '#/components/parameters/JobListStartingAfter'
      responses:
        '200':
          description: List of Rev AI Forced Alignment Jobs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AlignmentJob'
              examples:
                Jobs Found:
                  value:
                    - id: Bmx5c8F5pH7a
                      status: in_progress
                      created_on: '2018-05-05T23:23:22.29Z'
                      type: alignment
                    - id: 6BxQYGa638Yt
                      status: completed
                      created_on: '2018-05-05T23:23:22.29Z'
                      completed_on: '2018-05-05T23:45:13.41Z'
                      language: es
                      type: alignment
                No Jobs Found:
                  value: []
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestProblemDetails'
              examples:
                Limit Above Max Value:
                  $ref: '#/components/examples/BadLimitResponse'
                Invalid Job Id:
                  $ref: '#/components/examples/InvalidStartingAfterResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenDeployment'
        '404':
          $ref: '#/components/responses/JobNotFound'
  /alignment/v1/jobs/{id}:
    parameters:
      - $ref: '#/components/parameters/JobId'
    get:
      summary: Get Forced Alignment Job By Id
      operationId: GetAlignmentJobById
      description: Returns information about a forced alignment job.
      tags:
        - Jobs
      responses:
        '200':
          description: Forced Alignment Job Details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlignmentJob'
              examples:
                New Job:
                  $ref: '#/components/examples/NewAlignmentJob'
                Completed Job:
                  $ref: '#/components/examples/CompletedAlignmentJob'
                Failed Job:
                  $ref: '#/components/examples/FailedAlignmentJob'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenDeployment'
        '404':
          $ref: '#/components/responses/JobNotFound'
    delete:
      summary: Delete Forced Alignment Job by Id
      operationId: DeleteAlignmentJobById
      description: >-
        Deletes a forced alignment job. All data related to the job will be
        permanently deleted. A job can only be deleted once it's completed
        (either with success or failure).
      tags:
        - Jobs
      responses:
        '204':
          $ref: '#/components/responses/DeleteJobSuccessful'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenDeployment'
        '404':
          $ref: '#/components/responses/JobNotFound'
        '409':
          description: Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/InvalidStateDetails'
              examples:
                In Progress Job:
                  $ref: >-
                    #/components/examples/ConflictAudioAnalysisJob_InvalidDeleteState
  /alignment/v1/jobs/{id}/transcript:
    get:
      parameters:
        - $ref: '#/components/parameters/JobId'
        - $ref: '#/components/parameters/AcceptRevJson'
      summary: Get Forced Alignment Transcript By Id
      operationId: GetAlignmentTranscriptById
      description: |
        Returns the results for a completed forced alignment job.
      tags:
        - Jobs
      responses:
        '200':
          $ref: '#/components/responses/SampleAlignmentTranscript'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenDeployment'
        '404':
          $ref: '#/components/responses/JobNotFound'
        '409':
          description: Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/InvalidStateDetails'
              examples:
                In Progress Job:
                  $ref: >-
                    #/components/examples/ConflictAudioAnalysisJob_InvalidStateInProgress
                Failed Job:
                  $ref: >-
                    #/components/examples/ConflictAudioAnalysisJob_InvalidStateFailed
components:
  securitySchemes:
    AccessToken:
      type: http
      scheme: bearer
  parameters:
    JobListLimit:
      in: query
      name: limit
      schema:
        type: integer
        default: 100
        maximum: 1000
        minimum: 0
        nullable: true
      required: false
      description: Limits the number of jobs returned, default is 100, max is 1000
    JobListStartingAfter:
      in: query
      name: starting_after
      schema:
        type: string
        nullable: true
      required: false
      description: >-
        If specified, returns jobs submitted before the job with this id,
        exclusive (job with this id is not included)
    JobId:
      name: id
      in: path
      description: Rev AI API Job Id
      required: true
      schema:
        type: string
    AcceptRevJson:
      name: Accept
      in: header
      description: MIME type specifying the transcription output format
      required: false
      schema:
        type: string
        enum:
          - application/vnd.rev.transcript.v1.0+json
  schemas:
    JobIdField:
      type: string
      description: Id of the job.
      example: Umx5c6F7pH7r
    CreatedOnField:
      type: string
      format: date-time
      description: The date and time the job was created in ISO-8601 UTC form.
      example: '2018-05-05T23:23:22.29Z'
    CompletedOnField:
      type: string
      format: date-time
      description: >-
        The date and time the job was completed, whether successfully or
        failing, in ISO-8601 UTC form.
      nullable: true
      example: '2018-05-05T23:28:22.29Z'
    MetadataField:
      type: string
      maxLength: 512
      description: Optional metadata that was provided during job submission.
      nullable: true
    FailureDetailField:
      type: string
      description: Human-readable reason why the job failed.
      nullable: true
      example: Internal server error.
    DeleteAfterSecondsField:
      description: >-
        Amount of time after job completion when job is auto-deleted. Present
        only when preference set in job request.
      type: integer
      minimum: 0
      maximum: 2592000
      nullable: true
    BaseApiJobV2:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/JobIdField'
        created_on:
          $ref: '#/components/schemas/CreatedOnField'
        completed_on:
          $ref: '#/components/schemas/CompletedOnField'
        metadata:
          $ref: '#/components/schemas/MetadataField'
        failure_detail:
          $ref: '#/components/schemas/FailureDetailField'
        delete_after_seconds:
          $ref: '#/components/schemas/DeleteAfterSecondsField'
    AudioAnalysisStatusField:
      type: string
      enum:
        - in_progress
        - completed
        - failed
      description: Current status of the job.
      example: completed
    AudioAnalysisFailureField:
      type: string
      description: >-
        Simple reason of why the job failed. Check `failure_detail` for specific
        details and solutions.
      enum:
        - internal_processing
        - insufficient_balance
        - invoicing_limit_exceeded
    BaseAudioAnalysisJobV2:
      allOf:
        - $ref: '#/components/schemas/BaseApiJobV2'
        - type: object
          properties:
            status:
              $ref: '#/components/schemas/AudioAnalysisStatusField'
            failure:
              $ref: '#/components/schemas/AudioAnalysisFailureField'
    AlignmentJob:
      description: >
        Rev AI Forced Alignment Job

        ***

        Note: properties are not displayed in the returned object if they are
        null
      allOf:
        - $ref: '#/components/schemas/BaseAudioAnalysisJobV2'
        - type: object
          properties:
            type:
              type: string
              description: The type of action performed, in this case `alignment`
              enum:
                - alignment
              nullable: false
              default: alignment
              example: alignment
            language:
              type: string
              description: The language of the submitted audio and transcript
              enum:
                - en
                - es
                - fr
              nullable: true
              default: en
              example: en
            processed_duration_seconds:
              type: number
              format: double
              description: >-
                Duration of the processed audio in seconds. Null if the job has
                not completed
              nullable: true
              example: 107
      example: $ref:'#/examples/NewAlignmentJob'
    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
    BaseSubmitJobOptionsV2:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/MetadataField'
        notification_config:
          $ref: '#/components/schemas/NotificationConfig'
        delete_after_seconds:
          $ref: '#/components/schemas/DeleteAfterSecondsField'
    RequiredSourceConfig:
      description: >
        URL to a media resource, and optional authorization headers if they are
        needed to access the resource at the URL. Headers could be
         a single `Authorization` header of the form `<scheme> <token>`, and one of the [AWS signature v4 headers](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-auth-using-authorization-header.html).
        This option will not be visible in the submission response.
      nullable: false
      type: object
      required:
        - url
      properties:
        url:
          type: string
          description: Direct download media url. Ignored if submitting job from file.
          maxLength: 2048
          example: https://www.rev.ai/FTC_Sample_1.mp3
        auth_headers:
          description: >-
            Optional authorization headers, if they are needed to access the
            resource at the media url. 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
    BaseAudioAnalysisSubmitJobOptionsV2:
      allOf:
        - $ref: '#/components/schemas/BaseSubmitJobOptionsV2'
        - type: object
          properties:
            source_config:
              $ref: '#/components/schemas/RequiredSourceConfig'
    SourceTranscriptConfig:
      description: >
        URL to a text transcript resource, and optional authorization headers if
        they are needed to access the resource at the URL. Transcript should be
        a text file containing only the words of the transcript (no
        punctuation). Headers could be
         a single `Authorization` header of the form `<scheme> <token>`, and one of the [AWS signature v4 headers](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-auth-using-authorization-header.html).
        Only one of `source_transcript_config` and `transcript_text` may be set.

        This option will not be visible in the submission response.
      nullable: true
      type: object
      required:
        - url
      properties:
        url:
          type: string
          description: >-
            Direct download transcript url. Ignored if submitting
            transcript_text.
          maxLength: 2048
          example: https://your-bucket.s3.us-west-2.amazonaws.com/transcript.txt
        auth_headers:
          description: >-
            Optional authorization headers, if they are needed to access the
            resource at the transcript url. 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
    SubmitAlignmentJobOptions:
      allOf:
        - $ref: '#/components/schemas/BaseAudioAnalysisSubmitJobOptionsV2'
        - type: object
          properties:
            source_transcript_config:
              type: object
              $ref: '#/components/schemas/SourceTranscriptConfig'
            transcript_text:
              type: string
              description: >-
                The text of the transcript to be aligned. Should contain only
                words, no punctuation. One of either `source_transcript_config`
                or `transcript_text` is required
              nullable: true
              example: this is a transcript
            language:
              type: string
              description: The language of the submitted audio and transcript
              enum:
                - en
                - es
                - fr
              nullable: true
              default: en
              example: en
    InvalidStateDetails:
      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
    SpeakerField:
      type: integer
      description: Id of the speaker of the monologue.
      example: 1
    SpeakerInfoField:
      type: object
      nullable: true
      description: >-
        Information about the speaker for this monologue. Null if speaker_names
        option not provided or no speaker name detected.
      properties:
        id:
          type: integer
          description: Id of the speaker of the monologue
          example: 1
        display_name:
          type: string
          description: Human readable name of the speaker that was provided
          example: Jane Doe
    TsField:
      type: number
      description: >
        The timestamp of the beginning of the element relative to the beginning
        of the audio in seconds (centisecond precision).
    NullableTsField:
      type: number
      nullable: true
      allOf:
        - $ref: '#/components/schemas/TsField'
    EndTsField:
      type: number
      description: >
        The timestamp of the end of the element relative to the beginning of the
        audio in seconds (centisecond precision).
    NullableEndTsField:
      type: number
      nullable: true
      allOf:
        - $ref: '#/components/schemas/EndTsField'
    Transcript:
      type: object
      description: |
        Rev AI Transcript Model
      properties:
        monologues:
          type: array
          items:
            type: object
            properties:
              speaker:
                $ref: '#/components/schemas/SpeakerField'
              speaker_info:
                $ref: '#/components/schemas/SpeakerInfoField'
              elements:
                type: array
                description: Array of transcript elements
                items:
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                        - text
                        - punct
                        - unknown
                      description: Type of transcript element.
                      example: text
                    value:
                      type: string
                      description: Value of the transcript element.
                      example: Hello
                    ts:
                      $ref: '#/components/schemas/NullableTsField'
                    end_ts:
                      $ref: '#/components/schemas/NullableEndTsField'
                    confidence:
                      type: number
                      format: double
                      nullable: true
                      minimum: 0
                      maximum: 1
                      description: >-
                        Confidence score of the provided value. If the element
                        `type` is `punct` or `unknown`, confidence will be
                        `null`
                      example: 0.85
  examples:
    BadLimitResponse:
      value:
        parameters:
          limit:
            - The max value for limit is 1000
        type: https://www.rev.ai/api/v1/errors/invalid-parameters
        title: Your request parameters didn't validate
        status: 400
    InvalidStartingAfterResponse:
      value:
        parameters:
          starting_after:
            - Invalid job ID
        type: https://www.rev.ai/api/v1/errors/invalid-parameters
        title: Your request parameters didn't validate
        status: 400
    NewAlignmentJob:
      value:
        id: Umx5c6F7pH7r
        status: in_progress
        created_on: '2018-05-05T23:23:22.29Z'
        type: alignment
    BadRequestNoTranscript:
      value:
        parameters:
          transcript_text:
            - One of transcript_text or source_transcript_config must be set
        type: https://www.rev.ai/api/v1/errors/invalid-parameters
        title: Your request parameters didn't validate
        status: 400
    CompletedAlignmentJob:
      value:
        id: Umx5c6F7pH7r
        status: completed
        created_on: '2018-05-05T23:23:22.29Z'
        completed_on: '2018-05-05T23:45:13.41Z'
        type: alignment
        language: es
        processed_duration_seconds: 107.07
    FailedAlignmentJob:
      value:
        id: Umx5c6F7pH7r
        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 failed
        type: alignment
    ConflictAudioAnalysisJob_InvalidDeleteState:
      value:
        allowed_values:
          - completed
          - failed
        current_value: in_progress
        type: https://rev.ai/api/v1/errors/invalid-job-state
        title: Job is in invalid state
        detail: Job is in invalid state to be deleted
        status: 409
    ConflictAudioAnalysisJob_InvalidStateInProgress:
      value:
        allowed_values:
          - completed
        current_value: in_progress
        type: https://rev.ai/api/v1/errors/invalid-job-state
        title: Job is in invalid state
        detail: Job is in invalid state to obtain the output
        status: 409
    ConflictAudioAnalysisJob_InvalidStateFailed:
      value:
        allowed_values:
          - completed
        current_value: failed
        type: https://rev.ai/api/v1/errors/invalid-job-state
        title: Job is in invalid state
        detail: Job is in invalid state to obtain the output
        status: 409
  responses:
    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
    JobNotFound:
      description: Job Not Found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/BaseProblemDetails'
          example:
            type: https://www.rev.ai/api/v1/errors/job-not-found
            title: could not find job
            status: 404
    PayloadTooLarge:
      description: |
        Payload Too Large
      content:
        application/problem+json:
          schema:
            properties:
              title:
                type: string
                description: Short, human-readable summary of the problem type
              detail:
                type: string
                description: >-
                  Human-readable explanation specific to this occurrence of the
                  problem
              status:
                type: integer
                description: HTTP status code of the error
          example:
            title: Payload Too Large
            detail: Submitted payload exceeds maximum allowed file size
            status: 413
    DeleteJobSuccessful:
      description: |
        Job was successfully deleted
      content: {}
    SampleAlignmentTranscript:
      description: |
        Rev AI API Forced Alignment Transcript
      content:
        application/vnd.rev.transcript.v1.0+json:
          schema:
            $ref: '#/components/schemas/Transcript'
          example:
            monologues:
              - speaker: 0
                elements:
                  - type: text
                    value: this
                    ts: 0.25
                    end_ts: 0.5
                  - type: text
                    value: is
                    ts: 0.6
                    end_ts: 0.75
                  - type: text
                    value: a
                    ts: 0.75
                    end_ts: 0.85
                  - type: text
                    value: transcript
                    ts: 0.95
                    end_ts: 1.85
