Deepgram Text API

openapi: 3.2.0
info:
  title: REST Text API
  version: 1.0.0
servers:
- url: https://agent.deepgram.com
  description: Production
- url: https://api.deepgram.com
  description: Base
tags:
- name: Text
paths:
  /v1/read:
    post:
      operationId: text_analyze
      summary: Analyze text content
      description: Analyze text content using Deepgrams text analysis API
      tags:
      - Text
      parameters:
      - name: callback
        in: query
        description: URL to which we'll make the callback request
        required: false
        schema:
          type: string
      - name: callback_method
        in: query
        description: HTTP method by which the callback request will be made
        required: false
        schema:
          $ref: '#/components/schemas/V1ReadPostParametersCallbackMethod'
          default: POST
      - name: sentiment
        in: query
        description: Recognizes the sentiment throughout a transcript or text
        required: false
        schema:
          type: boolean
          default: false
      - name: summarize
        in: query
        description: Summarize content. For Listen API, supports string version option. For Read API, accepts boolean only.
        required: false
        schema:
          $ref: '#/components/schemas/V1ReadPostParametersSummarize'
      - name: tag
        in: query
        description: Label your requests for the purpose of identification during usage reporting
        required: false
        schema:
          $ref: '#/components/schemas/V1ReadPostParametersTag'
      - name: topics
        in: query
        description: Detect topics throughout a transcript or text
        required: false
        schema:
          type: boolean
          default: false
      - name: custom_topic
        in: query
        description: Custom topics you want the model to detect within your input audio or text if present Submit up to `100`.
        required: false
        schema:
          $ref: '#/components/schemas/V1ReadPostParametersCustomTopic'
      - name: custom_topic_mode
        in: query
        description: Sets how the model will interpret strings submitted to the `custom_topic` param. When `strict`, the model will only return topics submitted using the `custom_topic` param. When `extended`, the model will return its own detected topics in addition to those submitted using the `custom_topic` param
        required: false
        schema:
          $ref: '#/components/schemas/V1ReadPostParametersCustomTopicMode'
          default: extended
      - name: intents
        in: query
        description: Recognizes speaker intent throughout a transcript or text
        required: false
        schema:
          type: boolean
          default: false
      - name: custom_intent
        in: query
        description: Custom intents you want the model to detect within your input audio if present
        required: false
        schema:
          $ref: '#/components/schemas/V1ReadPostParametersCustomIntent'
      - name: custom_intent_mode
        in: query
        description: Sets how the model will interpret intents submitted to the `custom_intent` param. When `strict`, the model will only return intents submitted using the `custom_intent` param. When `extended`, the model will return its own detected intents in the `custom_intent` param.
        required: false
        schema:
          $ref: '#/components/schemas/V1ReadPostParametersCustomIntentMode'
          default: extended
      - name: language
        in: query
        description: The [BCP-47 language tag](https://tools.ietf.org/html/bcp47) that hints at the primary spoken language. Depending on the Model and API endpoint you choose only certain languages are available
        required: false
        schema:
          type: string
          default: en
      responses:
        '200':
          description: Successful text analysis
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadV1Response'
        '400':
          description: Invalid Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        description: Analyze a text file
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReadV1Request'
      security:
      - ApiKeyAuth: []
components:
  schemas:
    V1ReadPostParametersCustomIntent:
      oneOf:
      - type: string
      - type: array
        items:
          type: string
      title: V1ReadPostParametersCustomIntent
    SharedSentiments:
      type: object
      properties:
        segments:
          type: array
          items:
            $ref: '#/components/schemas/SharedSentimentsSegmentsItems'
        average:
          $ref: '#/components/schemas/SharedSentimentsAverage'
      description: Output whenever `sentiment=true` is used
      title: SharedSentiments
    V1ReadPostParametersCallbackMethod:
      type: string
      enum:
      - POST
      - PUT
      default: POST
      title: V1ReadPostParametersCallbackMethod
    ReadV1ResponseMetadataMetadataSentimentInfo:
      type: object
      properties:
        model_uuid:
          type: string
          format: uuid
        input_tokens:
          type: integer
        output_tokens:
          type: integer
      title: ReadV1ResponseMetadataMetadataSentimentInfo
    ReadV1ResponseMetadataMetadataTopicsInfo:
      type: object
      properties:
        model_uuid:
          type: string
          format: uuid
        input_tokens:
          type: integer
        output_tokens:
          type: integer
      title: ReadV1ResponseMetadataMetadataTopicsInfo
    ReadV1RequestText:
      type: object
      properties:
        text:
          type: string
          description: The plain text to analyze
      required:
      - text
      title: ReadV1RequestText
    SharedSentimentsAverage:
      type: object
      properties:
        sentiment:
          type: string
        sentiment_score:
          type: number
          format: double
      title: SharedSentimentsAverage
    SharedTopicsSegmentsItemsTopicsItems:
      type: object
      properties:
        topic:
          type: string
        confidence_score:
          type: string
          title: float
      title: SharedTopicsSegmentsItemsTopicsItems
    ErrorResponseModernError:
      type: object
      properties:
        category:
          type: string
          description: The category of the error
        message:
          type: string
          description: A message about the error
        details:
          type: string
          description: A description of the error
        request_id:
          type: string
          description: The unique identifier of the request
      title: ErrorResponseModernError
    SharedIntentsSegmentsItems:
      type: object
      properties:
        text:
          type: string
        start_word:
          type: number
          format: double
        end_word:
          type: number
          format: double
        intents:
          type: array
          items:
            $ref: '#/components/schemas/SharedIntentsSegmentsItemsIntentsItems'
      title: SharedIntentsSegmentsItems
    ReadV1RequestUrl:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: A URL pointing to the text source
      required:
      - url
      title: ReadV1RequestUrl
    V1ReadPostParametersCustomTopicMode:
      type: string
      enum:
      - extended
      - strict
      default: extended
      title: V1ReadPostParametersCustomTopicMode
    SharedTopicsSegmentsItems:
      type: object
      properties:
        text:
          type: string
        start_word:
          type: number
          format: double
        end_word:
          type: number
          format: double
        topics:
          type: array
          items:
            $ref: '#/components/schemas/SharedTopicsSegmentsItemsTopicsItems'
      title: SharedTopicsSegmentsItems
    ReadV1ResponseResultsSummaryResults:
      type: object
      properties:
        summary:
          $ref: '#/components/schemas/ReadV1ResponseResultsSummaryResultsSummary'
      title: ReadV1ResponseResultsSummaryResults
    SharedTopics:
      type: object
      properties:
        segments:
          type: array
          items:
            $ref: '#/components/schemas/SharedTopicsSegmentsItems'
      description: Output whenever `topics=true` is used
      title: SharedTopics
    V1ReadPostParametersSummarize0:
      type: string
      enum:
      - v2
      title: V1ReadPostParametersSummarize0
    ReadV1Response:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/ReadV1ResponseMetadata'
        results:
          $ref: '#/components/schemas/ReadV1ResponseResults'
      required:
      - metadata
      - results
      description: The standard text response
      title: ReadV1Response
    ReadV1Request:
      oneOf:
      - $ref: '#/components/schemas/ReadV1RequestUrl'
      - $ref: '#/components/schemas/ReadV1RequestText'
      title: ReadV1Request
    ReadV1ResponseResultsSummaryResultsSummary:
      type: object
      properties:
        text:
          type: string
      title: ReadV1ResponseResultsSummaryResultsSummary
    ReadV1ResponseMetadataMetadata:
      type: object
      properties:
        request_id:
          type: string
          format: uuid
        created:
          type: string
          format: date-time
        language:
          type: string
        summary_info:
          $ref: '#/components/schemas/ReadV1ResponseMetadataMetadataSummaryInfo'
        sentiment_info:
          $ref: '#/components/schemas/ReadV1ResponseMetadataMetadataSentimentInfo'
        topics_info:
          $ref: '#/components/schemas/ReadV1ResponseMetadataMetadataTopicsInfo'
        intents_info:
          $ref: '#/components/schemas/ReadV1ResponseMetadataMetadataIntentsInfo'
      title: ReadV1ResponseMetadataMetadata
    SharedIntents:
      type: object
      properties:
        segments:
          type: array
          items:
            $ref: '#/components/schemas/SharedIntentsSegmentsItems'
      description: Output whenever `intents=true` is used
      title: SharedIntents
    V1ReadPostParametersTag:
      oneOf:
      - type: string
      - type: array
        items:
          type: string
      title: V1ReadPostParametersTag
    ReadV1ResponseResults:
      type: object
      properties:
        summary:
          $ref: '#/components/schemas/ReadV1ResponseResultsSummary'
        topics:
          $ref: '#/components/schemas/SharedTopics'
        intents:
          $ref: '#/components/schemas/SharedIntents'
        sentiments:
          $ref: '#/components/schemas/SharedSentiments'
      title: ReadV1ResponseResults
    ReadV1ResponseResultsSummary:
      type: object
      properties:
        results:
          $ref: '#/components/schemas/ReadV1ResponseResultsSummaryResults'
      description: Output whenever `summary=true` is used
      title: ReadV1ResponseResultsSummary
    ErrorResponse:
      oneOf:
      - $ref: '#/components/schemas/ErrorResponseTextError'
      - $ref: '#/components/schemas/ErrorResponseLegacyError'
      - $ref: '#/components/schemas/ErrorResponseModernError'
      title: ErrorResponse
    SharedSentimentsSegmentsItems:
      type: object
      properties:
        text:
          type: string
        start_word:
          type: number
          format: double
        end_word:
          type: number
          format: double
        sentiment:
          type: string
        sentiment_score:
          type: number
          format: double
      title: SharedSentimentsSegmentsItems
    ReadV1ResponseMetadata:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/ReadV1ResponseMetadataMetadata'
      title: ReadV1ResponseMetadata
    ErrorResponseLegacyError:
      type: object
      properties:
        err_code:
          type: string
          description: The error code
        err_msg:
          type: string
          description: The error message
        request_id:
          type: string
          description: The request ID
      title: ErrorResponseLegacyError
    V1ReadPostParametersSummarize:
      oneOf:
      - $ref: '#/components/schemas/V1ReadPostParametersSummarize0'
      - type: boolean
        default: false
      title: V1ReadPostParametersSummarize
    V1ReadPostParametersCustomTopic:
      oneOf:
      - type: string
      - type: array
        items:
          type: string
      title: V1ReadPostParametersCustomTopic
    ReadV1ResponseMetadataMetadataSummaryInfo:
      type: object
      properties:
        model_uuid:
          type: string
          format: uuid
        input_tokens:
          type: integer
        output_tokens:
          type: integer
      title: ReadV1ResponseMetadataMetadataSummaryInfo
    ReadV1ResponseMetadataMetadataIntentsInfo:
      type: object
      properties:
        model_uuid:
          type: string
          format: uuid
        input_tokens:
          type: integer
        output_tokens:
          type: integer
      title: ReadV1ResponseMetadataMetadataIntentsInfo
    ErrorResponseTextError:
      type: string
      title: ErrorResponseTextError
    SharedIntentsSegmentsItemsIntentsItems:
      type: object
      properties:
        intent:
          type: string
        confidence_score:
          type: string
          title: float
      title: SharedIntentsSegmentsItemsIntentsItems
    V1ReadPostParametersCustomIntentMode:
      type: string
      enum:
      - extended
      - strict
      default: extended
      title: V1ReadPostParametersCustomIntentMode
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use `Authorization: Token <API_KEY>`

        Example: `Authorization: Token 12345abcdef`

        '
    JwtAuth:
      type: http
      scheme: bearer
      description: 'Use `Authorization: Bearer <JWT>`

        Example: `Authorization: Bearer eyJhbGciOiJ...`

        '