Deepgram Text Intelligence API

openapi: 3.2.0
info:
  title: Deepgram Speech-to-Text Text Intelligence API
  description: The Deepgram Speech-to-Text API provides accurate, fast transcription of audio content using advanced AI models.
  version: '1.0'
  contact:
    name: Deepgram Support
    url: https://developers.deepgram.com
  termsOfService: https://deepgram.com/tos
servers:
- url: https://api.deepgram.com
  description: Deepgram Production Server
- url: https://api.eu.deepgram.com
  description: Deepgram EU Server
security:
- bearerAuth: []
tags:
- name: Text Intelligence
  description: Analyze text content for summarization, sentiment, topics, and intents.
paths:
  /v1/read:
    post:
      operationId: analyzeText
      summary: Deepgram Analyze text content
      description: Analyzes text content for summarization, sentiment analysis, topic detection, and intent recognition using Deepgram's text intelligence models. Accepts text as a string in a JSON request body, a local file, or a hosted URL.
      tags:
      - Text Intelligence
      parameters:
      - $ref: '#/components/parameters/sentiment'
      - $ref: '#/components/parameters/summarize'
      - $ref: '#/components/parameters/topics'
      - $ref: '#/components/parameters/intents'
      - $ref: '#/components/parameters/language'
      - $ref: '#/components/parameters/callback'
      - $ref: '#/components/parameters/callback_method'
      - $ref: '#/components/parameters/custom_topic'
      requestBody:
        description: Text content to analyze. Can be a JSON object with a text string or a URL to a text document.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TextAnalysisRequest'
      responses:
        '200':
          description: Text analysis completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TextAnalysisResponse'
        '400':
          description: Bad request due to invalid parameters or input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized due to missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    TextAnalysisRequest:
      type: object
      properties:
        text:
          type: string
          description: Text content to analyze.
        url:
          type: string
          format: uri
          description: URL of a text document to analyze.
    IntentResults:
      type: object
      properties:
        segments:
          type: array
          items:
            $ref: '#/components/schemas/IntentSegment'
          description: Intent recognition results for content segments.
    SentimentSegment:
      type: object
      properties:
        text:
          type: string
          description: Text of the segment.
        start_word:
          type: integer
          description: Index of the first word in this segment.
        end_word:
          type: integer
          description: Index of the last word in this segment.
        sentiment:
          type: string
          enum:
          - positive
          - negative
          - neutral
          description: Overall sentiment of the segment.
        sentiment_score:
          type: number
          format: float
          description: Confidence score for the sentiment classification.
    TopicSegment:
      type: object
      properties:
        text:
          type: string
          description: Text of the segment.
        start_word:
          type: integer
          description: Index of the first word in this segment.
        end_word:
          type: integer
          description: Index of the last word in this segment.
        topics:
          type: array
          items:
            $ref: '#/components/schemas/Topic'
          description: Topics detected in this segment.
    TextAnalysisResponse:
      type: object
      properties:
        metadata:
          type: object
          properties:
            request_id:
              type: string
              description: Unique identifier for the API request.
            created:
              type: string
              format: date-time
              description: Timestamp when the request was created.
        results:
          type: object
          properties:
            summary:
              $ref: '#/components/schemas/Summary'
            sentiments:
              $ref: '#/components/schemas/SentimentResults'
            topics:
              $ref: '#/components/schemas/TopicResults'
            intents:
              $ref: '#/components/schemas/IntentResults'
    Intent:
      type: object
      properties:
        intent:
          type: string
          description: Detected intent label.
        confidence_score:
          type: number
          format: float
          description: Confidence score for the intent recognition.
    TopicResults:
      type: object
      properties:
        segments:
          type: array
          items:
            $ref: '#/components/schemas/TopicSegment'
          description: Topic detection results for content segments.
    Error:
      type: object
      properties:
        err_code:
          type: string
          description: Error code identifying the type of error.
        err_msg:
          type: string
          description: Human-readable error message.
        request_id:
          type: string
          description: Unique identifier for the request that produced the error.
    Topic:
      type: object
      properties:
        topic:
          type: string
          description: Detected topic label.
        confidence_score:
          type: number
          format: float
          description: Confidence score for the topic detection.
    Summary:
      type: object
      properties:
        short:
          type: string
          description: Short summary of the content.
    IntentSegment:
      type: object
      properties:
        text:
          type: string
          description: Text of the segment.
        start_word:
          type: integer
          description: Index of the first word in this segment.
        end_word:
          type: integer
          description: Index of the last word in this segment.
        intents:
          type: array
          items:
            $ref: '#/components/schemas/Intent'
          description: Intents detected in this segment.
    SentimentResults:
      type: object
      properties:
        segments:
          type: array
          items:
            $ref: '#/components/schemas/SentimentSegment'
          description: Sentiment analysis results for content segments.
        average:
          $ref: '#/components/schemas/SentimentAverage'
    SentimentAverage:
      type: object
      properties:
        sentiment:
          type: string
          enum:
          - positive
          - negative
          - neutral
          description: Overall average sentiment.
        sentiment_score:
          type: number
          format: float
          description: Average sentiment score.
  parameters:
    callback_method:
      name: callback_method
      in: query
      description: HTTP method for the callback request.
      schema:
        type: string
        enum:
        - POST
        - PUT
        default: POST
    intents:
      name: intents
      in: query
      description: Indicates whether to detect intents in the content.
      schema:
        type: boolean
        default: false
    sentiment:
      name: sentiment
      in: query
      description: Indicates whether to perform sentiment analysis on the content.
      schema:
        type: boolean
        default: false
    summarize:
      name: summarize
      in: query
      description: Indicates whether to generate a summary of the content. Can be a boolean or a specific summary format.
      schema:
        type: string
    topics:
      name: topics
      in: query
      description: Indicates whether to detect topics in the content.
      schema:
        type: boolean
        default: false
    custom_topic:
      name: custom_topic
      in: query
      description: Custom topics to detect within the input content. Up to 100 custom topics are allowed.
      schema:
        type: array
        items:
          type: string
    language:
      name: language
      in: query
      description: BCP-47 language tag for the primary spoken language in the audio.
      schema:
        type: string
        example: en
    callback:
      name: callback
      in: query
      description: URL to which Deepgram will make a callback request when processing is complete.
      schema:
        type: string
        format: uri
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Deepgram API key passed as a bearer token in the Authorization header.
    tokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Deepgram API key passed with Token prefix, e.g. Token YOUR_API_KEY.
externalDocs:
  description: Deepgram Speech-to-Text Documentation
  url: https://developers.deepgram.com/docs/stt/getting-started