# Source: https://docs.perplexity.ai/api-reference/chat-completions-post.md

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perplexity.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Chat Completion

> Generate a chat completion response for the given conversation.



## OpenAPI

````yaml post /chat/completions
openapi: 3.1.0
info:
  title: Perplexity AI API
  description: Perplexity AI API
  version: 0.1.0
servers: []
security: []
paths:
  /chat/completions:
    post:
      summary: Create Chat Completion
      description: Generate a chat completion response for the given conversation.
      operationId: chat_completions_chat_completions_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiChatCompletionsRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompletionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    ApiChatCompletionsRequest:
      properties:
        max_tokens:
          anyOf:
            - type: integer
              maximum: 128000
              exclusiveMinimum: 0
            - type: 'null'
          title: Max Tokens
        'n':
          anyOf:
            - type: integer
              maximum: 10
              minimum: 1
            - type: 'null'
          title: 'N'
        model:
          type: string
          title: Model
        stream:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Stream
          default: false
        stop:
          anyOf:
            - type: string
            - items:
                type: string
              type: array
            - type: 'null'
          title: Stop
        cum_logprobs:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Cum Logprobs
        logprobs:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Logprobs
        top_logprobs:
          anyOf:
            - type: integer
            - type: 'null'
          title: Top Logprobs
        best_of:
          anyOf:
            - type: integer
            - type: 'null'
          title: Best Of
        response_metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Response Metadata
        response_format:
          anyOf:
            - $ref: '#/components/schemas/ResponseFormatText'
            - $ref: '#/components/schemas/ResponseFormatJSONSchema'
            - $ref: '#/components/schemas/ResponseFormatRegex'
            - type: 'null'
          title: Response Format
        diverse_first_token:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Diverse First Token
        _inputs:
          anyOf:
            - items:
                type: integer
              type: array
            - type: 'null'
          title: Inputs
        _prompt_token_length:
          anyOf:
            - type: integer
            - type: 'null'
          title: Prompt Token Length
        messages:
          items:
            $ref: '#/components/schemas/ChatMessage-Input'
          type: array
          title: Messages
        tools:
          anyOf:
            - items:
                $ref: '#/components/schemas/ToolSpec'
              type: array
            - type: 'null'
          title: Tools
        tool_choice:
          anyOf:
            - type: string
              enum:
                - none
                - auto
                - required
            - type: 'null'
          title: Tool Choice
        parallel_tool_calls:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Parallel Tool Calls
        web_search_options:
          $ref: '#/components/schemas/WebSearchOptions'
        search_mode:
          anyOf:
            - type: string
              enum:
                - web
                - academic
                - sec
            - type: 'null'
          title: Search Mode
        return_images:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Return Images
        return_related_questions:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Return Related Questions
        num_search_results:
          type: integer
          title: Num Search Results
          default: 10
        num_images:
          type: integer
          title: Num Images
          default: 5
        enable_search_classifier:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Enable Search Classifier
        disable_search:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Disable Search
        search_domain_filter:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Search Domain Filter
        search_language_filter:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Search Language Filter
        search_tenant:
          anyOf:
            - type: string
            - type: 'null'
          title: Search Tenant
        ranking_model:
          anyOf:
            - type: string
            - type: 'null'
          title: Ranking Model
        latitude:
          anyOf:
            - type: number
            - type: 'null'
          title: Latitude
        longitude:
          anyOf:
            - type: number
            - type: 'null'
          title: Longitude
        country:
          anyOf:
            - type: string
            - type: 'null'
          title: Country
        search_recency_filter:
          anyOf:
            - type: string
              enum:
                - hour
                - day
                - week
                - month
                - year
            - type: 'null'
          title: Search Recency Filter
        search_after_date_filter:
          anyOf:
            - type: string
            - type: 'null'
          title: Search After Date Filter
        search_before_date_filter:
          anyOf:
            - type: string
            - type: 'null'
          title: Search Before Date Filter
        last_updated_before_filter:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Updated Before Filter
        last_updated_after_filter:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Updated After Filter
        image_format_filter:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Image Format Filter
        image_domain_filter:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Image Domain Filter
        safe_search:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Safe Search
          default: true
        file_workspace_id:
          anyOf:
            - type: string
            - type: 'null'
          title: File Workspace Id
        updated_before_timestamp:
          anyOf:
            - type: integer
            - type: 'null'
          title: Updated Before Timestamp
        updated_after_timestamp:
          anyOf:
            - type: integer
            - type: 'null'
          title: Updated After Timestamp
        search_internal_properties:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Search Internal Properties
        use_threads:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Use Threads
        thread_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Thread Id
        stream_mode:
          type: string
          enum:
            - full
            - concise
          title: Stream Mode
          default: full
        _debug_pro_search:
          type: boolean
          title: Debug Pro Search
          default: false
        has_image_url:
          type: boolean
          title: Has Image Url
          default: false
        reasoning_effort:
          anyOf:
            - type: string
              enum:
                - minimal
                - low
                - medium
                - high
            - type: 'null'
          title: Reasoning Effort
        language_preference:
          anyOf:
            - type: string
            - type: 'null'
          title: Language Preference
        user_original_query:
          anyOf:
            - type: string
            - type: 'null'
          title: User Original Query
        _force_new_agent:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Force New Agent
      type: object
      required:
        - model
        - messages
      title: ApiChatCompletionsRequest
    CompletionResponse:
      properties:
        id:
          type: string
          title: Id
        model:
          type: string
          title: Model
        created:
          type: integer
          title: Created
        usage:
          anyOf:
            - $ref: '#/components/schemas/UsageInfo'
            - type: 'null'
        object:
          type: string
          title: Object
          default: chat.completion
        choices:
          items:
            $ref: '#/components/schemas/Choice'
          type: array
          title: Choices
        citations:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Citations
        search_results:
          anyOf:
            - items:
                $ref: '#/components/schemas/ApiPublicSearchResult'
              type: array
            - type: 'null'
          title: Search Results
        type:
          anyOf:
            - $ref: '#/components/schemas/CompletionResponseType'
            - type: 'null'
        status:
          anyOf:
            - $ref: '#/components/schemas/CompletionResponseStatus'
            - type: 'null'
      type: object
      required:
        - id
        - model
        - created
        - choices
      title: CompletionResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ResponseFormatText:
      properties:
        type:
          type: string
          const: text
          title: Type
      type: object
      required:
        - type
      title: ResponseFormatText
    ResponseFormatJSONSchema:
      properties:
        type:
          type: string
          const: json_schema
          title: Type
        json_schema:
          $ref: '#/components/schemas/JSONSchema'
      type: object
      required:
        - type
        - json_schema
      title: ResponseFormatJSONSchema
    ResponseFormatRegex:
      properties:
        type:
          type: string
          const: regex
          title: Type
        regex:
          $ref: '#/components/schemas/RegexSchema'
      type: object
      required:
        - type
        - regex
      title: ResponseFormatRegex
    ChatMessage-Input:
      properties:
        role:
          $ref: '#/components/schemas/ChatMessageRole'
        content:
          anyOf:
            - type: string
            - items:
                anyOf:
                  - $ref: '#/components/schemas/ChatMessageContentTextChunk'
                  - $ref: '#/components/schemas/ChatMessageContentImageChunk'
                  - $ref: '#/components/schemas/ChatMessageContentFileChunk'
                  - $ref: '#/components/schemas/ChatMessageContentPDFChunk'
                  - $ref: '#/components/schemas/ChatMessageContentVideoChunk'
              type: array
              title: Structured Content
            - type: 'null'
          title: Content
        reasoning_steps:
          anyOf:
            - items:
                $ref: '#/components/schemas/ReasoningStep-Input'
              type: array
            - type: 'null'
          title: Reasoning Steps
        tool_calls:
          anyOf:
            - items:
                $ref: '#/components/schemas/ToolCall'
              type: array
            - type: 'null'
          title: Tool Calls
        tool_call_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Tool Call Id
      type: object
      required:
        - role
        - content
      title: ChatMessage
    ToolSpec:
      properties:
        type:
          type: string
          const: function
          title: Type
        function:
          $ref: '#/components/schemas/FunctionSpec'
      type: object
      required:
        - type
        - function
      title: ToolSpec
    WebSearchOptions:
      properties:
        search_context_size:
          type: string
          enum:
            - low
            - medium
            - high
          title: Search Context Size
          default: low
        search_type:
          anyOf:
            - type: string
              enum:
                - fast
                - pro
                - auto
            - type: 'null'
          title: Search Type
        user_location:
          anyOf:
            - $ref: '#/components/schemas/UserLocation'
            - type: 'null'
        image_results_enhanced_relevance:
          type: boolean
          title: Image Results Enhanced Relevance
          default: false
      type: object
      title: WebSearchOptions
    UsageInfo:
      properties:
        prompt_tokens:
          type: integer
          title: Prompt Tokens
        completion_tokens:
          type: integer
          title: Completion Tokens
        total_tokens:
          type: integer
          title: Total Tokens
        search_context_size:
          anyOf:
            - type: string
            - type: 'null'
          title: Search Context Size
        citation_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Citation Tokens
        num_search_queries:
          anyOf:
            - type: integer
            - type: 'null'
          title: Num Search Queries
        reasoning_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Reasoning Tokens
        cost:
          $ref: '#/components/schemas/Cost'
      type: object
      required:
        - prompt_tokens
        - completion_tokens
        - total_tokens
        - cost
      title: UsageInfo
    Choice:
      properties:
        index:
          type: integer
          title: Index
        finish_reason:
          anyOf:
            - type: string
              enum:
                - stop
                - length
            - type: 'null'
          title: Finish Reason
        message:
          $ref: '#/components/schemas/ChatMessage-Output'
        delta:
          $ref: '#/components/schemas/ChatMessage-Output'
      type: object
      required:
        - index
        - message
        - delta
      title: Choice
    ApiPublicSearchResult:
      properties:
        title:
          type: string
          title: Title
        url:
          type: string
          title: Url
        date:
          anyOf:
            - type: string
            - type: 'null'
          title: Date
        last_updated:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Updated
        snippet:
          type: string
          title: Snippet
          default: ''
        source:
          type: string
          enum:
            - web
            - attachment
          title: Source
          default: web
      type: object
      required:
        - title
        - url
      title: ApiPublicSearchResult
    CompletionResponseType:
      type: string
      enum:
        - message
        - info
        - end_of_stream
      title: CompletionResponseType
    CompletionResponseStatus:
      type: string
      enum:
        - PENDING
        - COMPLETED
      title: CompletionResponseStatus
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    JSONSchema:
      properties:
        schema:
          additionalProperties: true
          type: object
          title: Schema
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          default: schema
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        strict:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Strict
          default: true
      type: object
      required:
        - schema
      title: JSONSchema
    RegexSchema:
      properties:
        regex:
          type: string
          title: Regex
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        strict:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Strict
      type: object
      required:
        - regex
      title: RegexSchema
    ChatMessageRole:
      type: string
      enum:
        - system
        - user
        - assistant
        - tool
      title: ChatMessageRole
      description: Chat roles enum
    ChatMessageContentTextChunk:
      properties:
        type:
          type: string
          const: text
          title: Type
        text:
          type: string
          title: Text
      type: object
      required:
        - type
        - text
      title: ChatMessageContentTextChunk
    ChatMessageContentImageChunk:
      properties:
        type:
          type: string
          const: image_url
          title: Type
        image_url:
          anyOf:
            - $ref: '#/components/schemas/URL'
            - type: string
          title: Image Url
      type: object
      required:
        - type
        - image_url
      title: ChatMessageContentImageChunk
    ChatMessageContentFileChunk:
      properties:
        type:
          type: string
          const: file_url
          title: Type
        file_url:
          anyOf:
            - $ref: '#/components/schemas/URL'
            - type: string
          title: File Url
        file_name:
          anyOf:
            - type: string
            - type: 'null'
          title: File Name
      type: object
      required:
        - type
        - file_url
      title: ChatMessageContentFileChunk
    ChatMessageContentPDFChunk:
      properties:
        type:
          type: string
          const: pdf_url
          title: Type
        pdf_url:
          anyOf:
            - $ref: '#/components/schemas/URL'
            - type: string
          title: Pdf Url
      type: object
      required:
        - type
        - pdf_url
      title: ChatMessageContentPDFChunk
    ChatMessageContentVideoChunk:
      properties:
        type:
          type: string
          const: video_url
          title: Type
        video_url:
          anyOf:
            - $ref: '#/components/schemas/VideoURL'
            - type: string
          title: Video Url
      type: object
      required:
        - type
        - video_url
      title: ChatMessageContentVideoChunk
    ReasoningStep-Input:
      properties:
        thought:
          type: string
          title: Thought
        type:
          anyOf:
            - type: string
            - type: 'null'
          title: Type
        web_search:
          anyOf:
            - $ref: '#/components/schemas/WebSearchStepDetails'
            - type: 'null'
        fetch_url_content:
          anyOf:
            - $ref: '#/components/schemas/FetchUrlContentStepDetails'
            - type: 'null'
        execute_python:
          anyOf:
            - $ref: '#/components/schemas/ExecutePythonStepDetails'
            - type: 'null'
      type: object
      required:
        - thought
      title: ReasoningStep
      description: Reasoning step wrapper class
    ToolCall:
      properties:
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
        type:
          anyOf:
            - type: string
              const: function
            - type: 'null'
          title: Type
        function:
          anyOf:
            - $ref: '#/components/schemas/ToolCallFunction'
            - type: 'null'
      type: object
      title: ToolCall
    FunctionSpec:
      properties:
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        parameters:
          $ref: '#/components/schemas/ParameterSpec'
        strict:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Strict
      type: object
      required:
        - name
        - description
        - parameters
      title: FunctionSpec
    UserLocation:
      properties:
        latitude:
          anyOf:
            - type: number
            - type: 'null'
          title: Latitude
        longitude:
          anyOf:
            - type: number
            - type: 'null'
          title: Longitude
        country:
          anyOf:
            - type: string
            - type: 'null'
          title: Country
        city:
          anyOf:
            - type: string
            - type: 'null'
          title: City
        region:
          anyOf:
            - type: string
            - type: 'null'
          title: Region
      type: object
      title: UserLocation
    Cost:
      properties:
        input_tokens_cost:
          type: number
          title: Input Tokens Cost
        output_tokens_cost:
          type: number
          title: Output Tokens Cost
        reasoning_tokens_cost:
          anyOf:
            - type: number
            - type: 'null'
          title: Reasoning Tokens Cost
        request_cost:
          anyOf:
            - type: number
            - type: 'null'
          title: Request Cost
        citation_tokens_cost:
          anyOf:
            - type: number
            - type: 'null'
          title: Citation Tokens Cost
        search_queries_cost:
          anyOf:
            - type: number
            - type: 'null'
          title: Search Queries Cost
        total_cost:
          type: number
          title: Total Cost
      type: object
      required:
        - input_tokens_cost
        - output_tokens_cost
        - total_cost
      title: Cost
    ChatMessage-Output:
      properties:
        role:
          $ref: '#/components/schemas/ChatMessageRole'
        content:
          anyOf:
            - type: string
            - items:
                anyOf:
                  - $ref: '#/components/schemas/ChatMessageContentTextChunk'
                  - $ref: '#/components/schemas/ChatMessageContentImageChunk'
                  - $ref: '#/components/schemas/ChatMessageContentFileChunk'
                  - $ref: '#/components/schemas/ChatMessageContentPDFChunk'
                  - $ref: '#/components/schemas/ChatMessageContentVideoChunk'
              type: array
              title: Structured Content
            - type: 'null'
          title: Content
        reasoning_steps:
          anyOf:
            - items:
                $ref: '#/components/schemas/ReasoningStep-Output'
              type: array
            - type: 'null'
          title: Reasoning Steps
        tool_calls:
          anyOf:
            - items:
                $ref: '#/components/schemas/ToolCall'
              type: array
            - type: 'null'
          title: Tool Calls
        tool_call_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Tool Call Id
      type: object
      required:
        - role
        - content
      title: ChatMessage
    URL:
      properties:
        url:
          type: string
          title: Url
      type: object
      required:
        - url
      title: URL
    VideoURL:
      properties:
        url:
          type: string
          title: Url
        frame_interval:
          anyOf:
            - type: string
            - type: integer
          title: Frame Interval
          default: 25
      type: object
      required:
        - url
      title: VideoURL
    WebSearchStepDetails:
      properties:
        search_results:
          items:
            $ref: '#/components/schemas/ApiPublicSearchResult'
          type: array
          title: Search Results
        search_keywords:
          items:
            type: string
          type: array
          title: Search Keywords
      type: object
      required:
        - search_results
        - search_keywords
      title: WebSearchStepDetails
      description: Web search step details wrapper class
    FetchUrlContentStepDetails:
      properties:
        contents:
          items:
            $ref: '#/components/schemas/ApiPublicSearchResult'
          type: array
          title: Contents
      type: object
      required:
        - contents
      title: FetchUrlContentStepDetails
      description: Fetch url content step details wrapper class
    ExecutePythonStepDetails:
      properties:
        code:
          type: string
          title: Code
        result:
          type: string
          title: Result
      type: object
      required:
        - code
        - result
      title: ExecutePythonStepDetails
      description: Code generation step details wrapper class
    ToolCallFunction:
      properties:
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        arguments:
          anyOf:
            - type: string
            - type: 'null'
          title: Arguments
      type: object
      title: ToolCallFunction
    ParameterSpec:
      properties:
        type:
          type: string
          title: Type
        properties:
          additionalProperties: true
          type: object
          title: Properties
        required:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Required
        additional_properties:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Additional Properties
      type: object
      required:
        - type
        - properties
      title: ParameterSpec
    ReasoningStep-Output:
      properties:
        thought:
          type: string
          title: Thought
        type:
          anyOf:
            - type: string
            - type: 'null'
          title: Type
        web_search:
          anyOf:
            - $ref: '#/components/schemas/WebSearchStepDetails'
            - type: 'null'
        fetch_url_content:
          anyOf:
            - $ref: '#/components/schemas/FetchUrlContentStepDetails'
            - type: 'null'
        execute_python:
          anyOf:
            - $ref: '#/components/schemas/ExecutePythonStepDetails'
            - type: 'null'
      type: object
      required:
        - thought
      title: ReasoningStep
      description: Reasoning step wrapper class
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````