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. It supports pre-recorded audio files, delivering transcripts with features such as punctuation, diarization, language detection, smart formatting, summarization, sentiment analysis, topic detection, and intent recognition. Deepgram's Nova model family powers the transcription engine, offering high accuracy for conversational and professional audio across multiple languages and audio formats.
  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:
  parameters:
    callback:
      name: callback
      in: query
      description: URL to which Deepgram will make a callback request when processing is complete.
      schema:
        type: string
        format: uri
    sentiment:
      name: sentiment
      in: query
      description: Indicates whether to perform sentiment analysis on the content.
      schema:
        type: boolean
        default: false
    language:
      name: language
      in: query
      description: BCP-47 language tag for the primary spoken language in the audio.
      schema:
        type: string
        example: en
    intents:
      name: intents
      in: query
      description: Indicates whether to detect intents 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
    callback_method:
      name: callback_method
      in: query
      description: HTTP method for the callback request.
      schema:
        type: string
        enum:
        - POST
        - PUT
        default: POST
    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
  schemas:
    TopicResults:
      type: object
      properties:
        segments:
          type: array
          items:
            $ref: '#/components/schemas/TopicSegment'
          description: Topic detection results for content segments.
    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'
    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.
    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.
    Topic:
      type: object
      properties:
        topic:
          type: string
          description: Detected topic label.
        confidence_score:
          type: number
          format: float
          description: Confidence score for the topic detection.
    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.
    Summary:
      type: object
      properties:
        short:
          type: string
          description: Short summary of the content.
    Intent:
      type: object
      properties:
        intent:
          type: string
          description: Detected intent label.
        confidence_score:
          type: number
          format: float
          description: Confidence score for the intent recognition.
    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.
    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.
    IntentResults:
      type: object
      properties:
        segments:
          type: array
          items:
            $ref: '#/components/schemas/IntentSegment'
          description: Intent recognition results for content segments.
    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'
  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