Loose OpenAPI spec for Perplexity AI's API

openapi.yaml

openapi: 3.0.3
info:
  title: Perplexity API
  version: '1.0'
  description: API specification for Perplexity's chat completions endpoint

servers:
  - url: https://api.perplexity.ai
    description: Production server

paths:
  /chat/completions:
    post:
      summary: Create a chat completion
      description: Generates a model's response for the given chat conversation.
      operationId: createChatCompletion
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionsRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionsResponse'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/ChatCompletionsStreamResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

  schemas:
    ChatCompletionsRequest:
      type: object
      required:
        - model
        - messages
      properties:
        model:
          type: string
          description: The name of the model that will complete your prompt.
          example: llama-3.1-sonar-small-128k-online
        messages:
          type: array
          description: A list of messages comprising the conversation so far.
          items:
            $ref: '#/components/schemas/Message'
        max_tokens:
          type: integer
          description: The maximum number of completion tokens returned by the API.
        temperature:
          type: number
          description: The amount of randomness in the response.
          default: 0.2
          minimum: 0
          maximum: 1.999999
        top_p:
          type: number
          description: The nucleus sampling threshold.
          default: 0.9
          minimum: 0
          maximum: 1
        top_k:
          type: integer
          description: The number of tokens to keep for highest top-k filtering.
          default: 0
          minimum: 0
          maximum: 2048
        stream:
          type: boolean
          description: Whether to stream the response.
          default: false
        presence_penalty:
          type: number
          description: Penalty for new tokens based on presence in text.
          default: 0
          minimum: -2
          maximum: 2
        frequency_penalty:
          type: number
          description: Penalty for new tokens based on frequency in text.
          default: 1
          minimum: 0.000001
          maximum: 1000000
        search_domain_filter:
          type: array
          description: Limit citations to specific domains.
          items:
            type: string
          maxItems: 3
        return_images:
          type: boolean
          description: Whether to return images in the response.
          default: false
        return_related_questions:
          type: boolean
          description: Whether to return related questions.
          default: false
        search_recency_filter:
          type: string
          description: Time filter for search results.
          enum: [month, week, day, hour]

    Message:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum: [system, user, assistant]
          description: The role of the speaker in the conversation.
        content:
          type: string
          description: The content of the message.

    ChatCompletionsResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique response identifier.
        model:
          type: string
          description: The model used to generate the response.
        object:
          type: string
          enum: [chat.completion]
          description: The object type.
        created:
          type: integer
          description: Unix timestamp of creation time.
        citations:
          type: array
          description: Citations for the generated answer.
          items:
            type: string
            format: uri
        choices:
          type: array
          description: The generated completions.
          items:
            $ref: '#/components/schemas/Choice'
        usage:
          $ref: '#/components/schemas/Usage'

    ChatCompletionsStreamResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ChatCompletionsResponse'

    Choice:
      type: object
      properties:
        index:
          type: integer
          description: Index of the choice.
        finish_reason:
          type: string
          enum: [stop, length]
          description: Reason for finishing the generation.
        message:
          $ref: '#/components/schemas/Message'
          description: The generated message.
        delta:
          $ref: '#/components/schemas/Message'
          description: Incremental message content for streaming.

    Usage:
      type: object
      properties:
        prompt_tokens:
          type: integer
          description: Number of tokens in the prompt.
        completion_tokens:
          type: integer
          description: Number of tokens in the completion.
        total_tokens:
          type: integer
          description: Total number of tokens used.

    HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'

    ValidationError:
      type: object
      required:
        - loc
        - msg
        - type
      properties:
        loc:
          type: array
          items:
            oneOf:
              - type: string
              - type: integer
        msg:
          type: string
        type:
          type: string