openapi: 3.0.1
info:
  title: |
    Topic Extraction
  contact:
    email: support@rev.com
    name: Rev
    url: https://www.rev.ai/
  version: v1
  description: |
    # Quick Start
    Follow the [getting started checklist](https://www.rev.ai/getting_started).
  license:
    name: Rev AI Terms of Service
    url: https://www.rev.ai/about/terms
servers:
  - url: https://api.rev.ai
    description: Rev AI API
security:
  - AccessToken: []
paths:
  /topic_extraction/v1/jobs:
    post:
      summary: Submit Topic Extraction Job
      operationId: SubmitTopicExtractionJob
      description: >
        Starts an asynchronous job to extract topics from a transcript.

        The transcript can be supplied through `text` as plain text or `json` as
        a [rev.com transcript format](https://www.rev.ai/docs#tag/Transcript)
      tags:
        - Jobs
      requestBody:
        description: Topic Extraction Job Options
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitTopicExtractionJobOptions'
            examples:
              JSON Submission:
                value:
                  language: en
                  metadata: sample user provided metadata
                  notification_config:
                    url: https://www.example.com/callback
                    auth_headers:
                      Authorization: Bearer <notification-url-token>
                  delete_after_seconds: 1000000
                  json:
                    monologues:
                      - speaker: 1
                        elements:
                          - type: text
                            value: hello
                            ts: 0.75
                            end_ts: 1.25
                            confidence: 0.85
              Plain Text Submission:
                value:
                  language: en
                  metadata: sample user provided metadata
                  notification_config:
                    url: https://www.example.com/callback
                    auth_headers:
                      Authorization: Bearer <notification-url-token>
                  delete_after_seconds: 1000000
                  text: Plain text I would like topic extraction performed on
      responses:
        '200':
          description: Topic Extraction Job Details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopicExtractionJob'
              examples:
                New Job:
                  $ref: '#/components/examples/NewTopicExtractionJob'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestProblemDetails'
              examples:
                No Input Text:
                  $ref: '#/components/examples/BadRequestNoInputText'
                Both Json and Plaintext Provided:
                  $ref: '#/components/examples/BadRequestBothJsonText'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenDeployment'
        '404':
          $ref: '#/components/responses/DeploymentUnsupported'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
    get:
      summary: Get List of Topic Extraction Jobs
      operationId: GetListOfTopicExtractionJobs
      description: >
        Gets a list of topic extraction 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 Topic Extraction Jobs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TopicExtractionJob'
              examples:
                Jobs Found:
                  value:
                    - id: Bmx5c8F5pH7a
                      status: completed
                      language: en
                      created_on: '2018-05-05T23:23:22.29Z'
                      completed_on: '2018-05-05T23:45:13.41Z'
                      callback_url: https://www.example.com/callback
                      type: topic_extraction
                    - id: 6BxQYGa638Yt
                      status: completed
                      language: en
                      created_on: '2018-05-05T23:23:22.29Z'
                      completed_on: '2018-05-05T23:45:13.41Z'
                      callback_url: https://www.example.com/callback
                      word_count: 4231
                      type: topic_extraction
                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/DeploymentUnsupported'
  /topic_extraction/v1/jobs/{id}:
    parameters:
      - $ref: '#/components/parameters/JobId'
    get:
      summary: Get Topic Extraction Job By Id
      operationId: GetTopicExtractionJobById
      description: Returns information about a topic extraction job
      tags:
        - Jobs
      responses:
        '200':
          description: Topic Extraction Job Details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopicExtractionJob'
              examples:
                New Job:
                  $ref: '#/components/examples/NewTopicExtractionJob'
                Completed Job:
                  $ref: '#/components/examples/CompletedTopicExtractionJob'
                Failed Job:
                  $ref: '#/components/examples/FailedTopicExtractionJob'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenDeployment'
        '404':
          $ref: '#/components/responses/UnableToFindResourceOrDeploymentUnsupported'
    delete:
      summary: Delete Topic Extraction Job by Id
      operationId: DeleteTopicExtractionJobById
      description: >-
        Deletes a topic extraction 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/UnableToFindResourceOrDeploymentUnsupported'
        '409':
          description: Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/InvalidStateDetails'
              examples:
                In Progress Job:
                  $ref: >-
                    #/components/examples/ConflictTextAnalysisJob_InvalidDeleteState
  /topic_extraction/v1/jobs/{id}/result:
    get:
      parameters:
        - $ref: '#/components/parameters/JobId'
        - $ref: '#/components/parameters/threshold'
      summary: Get Topic Extraction Result By Id
      operationId: GetTopicExtractionResultById
      description: |
        Returns the results for a completed topic extraction job.
      tags:
        - Jobs
      responses:
        '200':
          $ref: '#/components/responses/SampleTopicExtractionResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenDeployment'
        '404':
          $ref: '#/components/responses/UnableToFindResourceOrDeploymentUnsupported'
        '409':
          description: Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/InvalidStateDetails'
              examples:
                In Progress Job:
                  $ref: >-
                    #/components/examples/ConflictTextAnalysisJob_InvalidStateInProgress
                Failed Job:
                  $ref: >-
                    #/components/examples/ConflictTextAnalysisJob_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
    threshold:
      name: threshold
      in: query
      description: >-
        Score threshold for topics. If specified all topics with a score lower
        than this threshold will be filtered out
      schema:
        type: number
        default: 0.3
        minimum: 0
        maximum: 1
        nullable: true
  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.
    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
    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
    BaseApiJob:
      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'
        callback_url:
          $ref: '#/components/schemas/CallbackUrlField'
        delete_after_seconds:
          $ref: '#/components/schemas/DeleteAfterSecondsField'
    TextAnalysisStatusField:
      type: string
      enum:
        - in_progress
        - completed
        - failed
      description: Current status of the job.
      example: completed
    TextAnalysisFailureField:
      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
        - input_too_small
        - input_too_large
    TextAnalysisLanguageField:
      type: string
      description: The user input language of the transcript.
      enum:
        - en
      example: en
      nullable: true
      default: en
    TextAnalysisWordCountField:
      type: integer
      description: The amount of words processed.
      example: 4231
      nullable: true
    BaseTextAnalysisJob:
      allOf:
        - $ref: '#/components/schemas/BaseApiJob'
        - type: object
          properties:
            status:
              $ref: '#/components/schemas/TextAnalysisStatusField'
            failure:
              $ref: '#/components/schemas/TextAnalysisFailureField'
            language:
              $ref: '#/components/schemas/TextAnalysisLanguageField'
            word_count:
              $ref: '#/components/schemas/TextAnalysisWordCountField'
    TopicExtractionJob:
      description: >
        Rev AI Topic Extraction Job

        ***

        Note: properties are not displayed in the returned object if they are
        null
      allOf:
        - $ref: '#/components/schemas/BaseTextAnalysisJob'
        - type: object
          properties:
            type:
              type: string
              description: The type of action performed, in this case `topic_extraction`
              enum:
                - topic_extraction
              nullable: false
              default: topic_extraction
              example: topic_extraction
      example: $ref:'#/examples/NewTopicExtractionJob'
    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
    BaseSubmitJobOptions:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/MetadataField'
        callback_url:
          $ref: '#/components/schemas/CallbackUrlField'
        notification_config:
          $ref: '#/components/schemas/NotificationConfig'
        delete_after_seconds:
          $ref: '#/components/schemas/DeleteAfterSecondsField'
    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
    BaseTextAnalysisSubmitJobOptions:
      allOf:
        - $ref: '#/components/schemas/BaseSubmitJobOptions'
        - type: object
          properties:
            language:
              $ref: '#/components/schemas/TextAnalysisLanguageField'
            text:
              nullable: true
              type: string
              example: Plain text I would like processed.
              description: >
                Plain text to be analyzed in this job submission. No timestamps
                will be included in the response if input is provided this way.
            json:
              type: object
              nullable: true
              description: >
                Rev AI transcript to be analyzed in this job submission. With
                this input timestamps will be in result.
              allOf:
                - $ref: '#/components/schemas/Transcript'
    SubmitTopicExtractionJobOptions:
      allOf:
        - $ref: '#/components/schemas/BaseTextAnalysisSubmitJobOptions'
    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
    BaseInformant:
      properties:
        content:
          type: string
          description: Portion of the input transcript that informed this topic choice
    TranscriptSubmissionInformants:
      type: array
      items:
        allOf:
          - $ref: '#/components/schemas/BaseInformant'
          - type: object
            properties:
              ts:
                $ref: '#/components/schemas/TsField'
              end_ts:
                $ref: '#/components/schemas/EndTsField'
    TextSubmissionInformants:
      type: array
      items:
        allOf:
          - $ref: '#/components/schemas/BaseInformant'
          - type: object
            properties:
              offset:
                type: number
                description: >
                  Number of characters (excluding newline characters such as
                  `\n` or `\r`) in the input leading up to the

                  content of this message. Only included if input to sentiment
                  analysis was plain text.
              length:
                type: number
                description: >
                  Number of characters (excluding newline characters such as
                  `\n` or `\r`) in the content. Only included

                  if input to sentiment analysis was plain text.
    TopicExtractionResult:
      description: Rev AI Topic Extraction Result Model
      type: object
      properties:
        topics:
          type: array
          items:
            type: object
            properties:
              topic_name:
                type: string
                description: >-
                  Name of the detected topic. Topics will always consist of
                  content that existed within the input transcript
              score:
                type: number
                minimum: 0
                maximum: 1
                description: >
                  Score of the topic, similar to confidence scores in our speech
                  to text api.

                  The higher the score, the more likely we think it is that this
                  is a topic of the input transcript
              informants:
                description: >
                  All of the pieces of content from the transcript which our
                  engine detected as being relevant to this topic. Positional
                  properties will be different

                  depending on the type of submission.
                oneOf:
                  - $ref: '#/components/schemas/TranscriptSubmissionInformants'
                  - $ref: '#/components/schemas/TextSubmissionInformants'
  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
    NewTopicExtractionJob:
      value:
        id: Umx5c6F7pH7r
        status: in_progress
        language: en
        created_on: '2018-05-05T23:23:22.29Z'
        type: topic_extraction
    BadRequestNoInputText:
      value:
        parameters:
          json:
            - Empty input, neither JSON or plain text input was provided
          text:
            - Empty input, neither JSON or plain text input was provided
        type: https://www.rev.ai/api/v1/errors/invalid-parameters
        title: Your request parameters didn't validate
        status: 400
    BadRequestBothJsonText:
      value:
        parameters:
          json:
            - Only one of JSON and plaintext may be provided
          text:
            - Only one of JSON and plaintext may be provided
        type: https://www.rev.ai/api/v1/errors/invalid-parameters
        title: Your request parameters didn't validate
        status: 400
    CompletedTopicExtractionJob:
      value:
        id: Umx5c6F7pH7r
        status: completed
        language: en
        created_on: '2018-05-05T23:23:22.29Z'
        completed_on: '2018-05-05T23:45:13.41Z'
        word_count: 4231
        type: topic_extraction
    FailedTopicExtractionJob:
      value:
        id: Umx5c6F7pH7r
        status: failed
        language: en
        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: topic_extraction
    ConflictTextAnalysisJob_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
    ConflictTextAnalysisJob_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
    ConflictTextAnalysisJob_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
    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
    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
    UnableToFindResourceOrDeploymentUnsupported:
      description: Unable to find resource or deployment does not support this API
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/BaseProblemDetails'
          examples:
            Job not found:
              value:
                type: https://www.rev.ai/api/v1/errors/job-not-found
                title: could not find job
                status: 404
            Deployment unsupported:
              value:
                type: https://www.rev.ai/api/v1/errors/unsupported-api
                title: This api is not supported in this deployment
                status: 404
    DeleteJobSuccessful:
      description: |
        Job was successfully deleted
      content: {}
    SampleTopicExtractionResult:
      description: |
        Rev AI API Topic Result
      content:
        application/vnd.rev.topic.v1.0+json:
          schema:
            $ref: '#/components/schemas/TopicExtractionResult'
          examples:
            Transcript Job Submission:
              value:
                topics:
                  - topic_name: incredible team
                    score: 0.9
                    informants:
                      - content: >-
                          We have 17 folks and, uh, I think we have an
                          incredible team and I just want to talk about some
                          things that we've done that I think have helped us get
                          there.
                        ts: 71.4
                        end_ts: 78.39
                      - content: >-
                          Some people think that you can raise money and spend a
                          few weeks building your team and then move on to more.
                        ts: 84.21
                        end_ts: 88.47
                  - topic_name: quick background
                    score: 0.6
                    informants:
                      - content: Um, I want to give you a quick background on myself.
                        ts: 55.92
                        end_ts: 58.17
            Plain Text Job Submission:
              value:
                topics:
                  - topic_name: incredible team
                    score: 0.9
                    informants:
                      - content: >-
                          We have 17 folks and, uh, I think we have an
                          incredible team and I just want to talk about some
                          things that we've done that I think have helped us get
                          there.
                        offset: 0
                        length: 157
                      - content: >-
                          Some people think that you can raise money and spend a
                          few weeks building your team and then move on to more.
                        offset: 160
                        length: 109
                  - topic_name: quick background
                    score: 0.6
                    informants:
                      - content: Um, I want to give you a quick background on myself.
                        offset: 13
                        length: 52
