> ## 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 Message

> Send a conversation to any Gateway model using the Anthropic Messages schema. Set `stream: true` to receive server-sent events. Authenticate with your Perplexity API key — both `Authorization: Bearer` and the Anthropic SDK's default `x-api-key` header are accepted.

<Info>
  Authenticate with your Perplexity API key. Both `Authorization: Bearer` and the Anthropic SDK's default `x-api-key` header are accepted, so the stock SDK `api_key` parameter works unchanged. No `anthropic-version` header is required.
</Info>

<AccordionGroup>
  <Accordion title="Parameter support">
    **Honored:** `model`, `max_tokens` (required), `messages`, `system`, `stream`, `temperature`, `top_p`, `stop_sequences`, `thinking` (only `{"type": "disabled"}`), `tools`, `tool_choice`.

    **Accepted but not forwarded to the model:** `metadata`.

    **Rejected with a 400:** `top_k`, `service_tier`, `thinking` with `{"type": "enabled"}`, `cache_control` on content blocks or tools, plus any unrecognized top-level field. Tools require a non-empty `description`.
  </Accordion>

  <Accordion title="Errors">
    Errors use the Anthropic envelope:

    ```json theme={null}
    {
      "type": "error",
      "error": {
        "type": "overloaded_error",
        "message": "upstream model is overloaded, please try again later"
      }
    }
    ```

    An overloaded model returns HTTP `429` with type `overloaded_error` and a `Retry-After` header. Requests that fail before producing output are not billed.
  </Accordion>
</AccordionGroup>


## OpenAPI

````yaml post /router/v1/messages
openapi: 3.0.3
info:
  title: Perplexity Gateway API (Anthropic-compatible)
  description: Anthropic Messages-compatible access to models across providers.
  version: 0.1.0
servers:
  - url: https://api.perplexity.ai
security: []
paths:
  /router/v1/messages:
    post:
      summary: Create Message
      description: >-
        Send a conversation to any Gateway model using the Anthropic Messages
        schema. Set `stream: true` to receive server-sent events. Authenticate
        with your Perplexity API key — both `Authorization: Bearer` and the
        Anthropic SDK's default `x-api-key` header are accepted.
      operationId: gateway_create_message
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMessageRequest'
      responses:
        '200':
          description: >-
            Successful response. JSON for non-streaming requests; a
            `text/event-stream` of typed events (`message_start` through
            `message_stop`) when `stream` is true.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '400':
          description: >-
            Invalid request — malformed body, unsupported parameter, or a model
            that is not available on the Gateway.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: >-
            Rate limit exceeded or the upstream model is overloaded. Retry after
            the `Retry-After` interval.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - HTTPBearer: []
components:
  schemas:
    CreateMessageRequest:
      type: object
      description: Request body for POST /router/v1/messages.
      properties:
        model:
          type: string
          description: Public model slug, e.g. `anthropic/claude-sonnet-4-5`.
        max_tokens:
          type: integer
          minimum: 1
          maximum: 2147483647
          description: Maximum number of tokens to generate. Required by the Messages API.
        messages:
          type: array
          items:
            $ref: '#/components/schemas/InputMessage'
        system:
          description: System prompt as plain text or an array of text blocks.
          oneOf:
            - type: string
              title: Text
            - type: array
              title: Text blocks
              items:
                $ref: '#/components/schemas/TextBlock'
        temperature:
          type: number
          format: float
          minimum: 0
          maximum: 1
        top_p:
          type: number
          format: float
          minimum: 0
          maximum: 1
        stop_sequences:
          type: array
          items:
            type: string
        stream:
          type: boolean
          description: When true, respond with server-sent events.
        tools:
          type: array
          items:
            $ref: '#/components/schemas/Tool'
        tool_choice:
          $ref: '#/components/schemas/ToolChoice'
        metadata:
          $ref: '#/components/schemas/RequestMetadata'
        thinking:
          $ref: '#/components/schemas/ThinkingConfig'
      required:
        - model
        - max_tokens
        - messages
    Message:
      type: object
      description: Non-streaming response body and the message_start payload.
      properties:
        id:
          type: string
        type:
          type: string
          enum:
            - message
        role:
          type: string
          enum:
            - assistant
        model:
          type: string
        content:
          type: array
          items:
            $ref: '#/components/schemas/ContentBlock'
        stop_reason:
          type: string
          enum:
            - end_turn
            - max_tokens
            - stop_sequence
            - tool_use
            - pause_turn
            - refusal
            - model_context_window_exceeded
          nullable: true
        stop_sequence:
          type: string
          nullable: true
        usage:
          $ref: '#/components/schemas/Usage'
      required:
        - id
        - type
        - role
        - model
        - content
        - stop_reason
        - stop_sequence
        - usage
    ErrorResponse:
      type: object
      description: Error envelope, as a JSON body and as the SSE error event payload.
      properties:
        type:
          type: string
          enum:
            - error
        error:
          $ref: '#/components/schemas/ErrorObject'
      required:
        - type
        - error
    InputMessage:
      type: object
      properties:
        role:
          type: string
          enum:
            - user
            - assistant
        content:
          description: Message content as plain text or an array of content blocks.
          oneOf:
            - type: string
              title: Text
            - type: array
              title: Content blocks
              items:
                $ref: '#/components/schemas/InputContentBlock'
      required:
        - role
        - content
    TextBlock:
      type: object
      properties:
        type:
          type: string
          enum:
            - text
        text:
          type: string
      required:
        - type
        - text
    Tool:
      type: object
      properties:
        type:
          type: string
          enum:
            - custom
          description: >-
            Optional explicit tool kind; `custom` is the default. Server tool
            types are rejected by validation.
        name:
          type: string
        description:
          type: string
        input_schema:
          type: object
          additionalProperties: true
          description: >-
            JSON Schema for the tool input, kept as raw JSON and forwarded
            verbatim.
          x-go-type: json.RawMessage
      required:
        - name
        - input_schema
    ToolChoice:
      oneOf:
        - $ref: '#/components/schemas/ToolChoiceAuto'
        - $ref: '#/components/schemas/ToolChoiceAny'
        - $ref: '#/components/schemas/ToolChoiceTool'
        - $ref: '#/components/schemas/ToolChoiceNone'
      discriminator:
        propertyName: type
        mapping:
          auto:
            $ref: '#/components/schemas/ToolChoiceAuto'
          any:
            $ref: '#/components/schemas/ToolChoiceAny'
          tool:
            $ref: '#/components/schemas/ToolChoiceTool'
          none:
            $ref: '#/components/schemas/ToolChoiceNone'
    RequestMetadata:
      type: object
      properties:
        user_id:
          type: string
          nullable: true
    ThinkingConfig:
      oneOf:
        - $ref: '#/components/schemas/ThinkingConfigEnabled'
        - $ref: '#/components/schemas/ThinkingConfigDisabled'
      discriminator:
        propertyName: type
        mapping:
          enabled:
            $ref: '#/components/schemas/ThinkingConfigEnabled'
          disabled:
            $ref: '#/components/schemas/ThinkingConfigDisabled'
    ContentBlock:
      oneOf:
        - $ref: '#/components/schemas/TextBlock'
        - $ref: '#/components/schemas/ToolUseBlock'
        - $ref: '#/components/schemas/ThinkingBlock'
      discriminator:
        propertyName: type
        mapping:
          text:
            $ref: '#/components/schemas/TextBlock'
          tool_use:
            $ref: '#/components/schemas/ToolUseBlock'
          thinking:
            $ref: '#/components/schemas/ThinkingBlock'
    Usage:
      type: object
      properties:
        input_tokens:
          type: integer
        output_tokens:
          type: integer
        cache_creation_input_tokens:
          type: integer
          nullable: true
        cache_read_input_tokens:
          type: integer
          nullable: true
      required:
        - input_tokens
        - output_tokens
        - cache_creation_input_tokens
        - cache_read_input_tokens
    ErrorObject:
      type: object
      properties:
        type:
          type: string
          enum:
            - invalid_request_error
            - authentication_error
            - permission_error
            - not_found_error
            - request_too_large
            - rate_limit_error
            - api_error
            - timeout_error
            - overloaded_error
        message:
          type: string
      required:
        - type
        - message
    InputContentBlock:
      oneOf:
        - $ref: '#/components/schemas/TextBlock'
        - $ref: '#/components/schemas/ImageBlock'
        - $ref: '#/components/schemas/ToolUseBlock'
        - $ref: '#/components/schemas/ToolResultBlock'
        - $ref: '#/components/schemas/ThinkingBlock'
        - $ref: '#/components/schemas/RedactedThinkingBlock'
      discriminator:
        propertyName: type
        mapping:
          text:
            $ref: '#/components/schemas/TextBlock'
          image:
            $ref: '#/components/schemas/ImageBlock'
          tool_use:
            $ref: '#/components/schemas/ToolUseBlock'
          tool_result:
            $ref: '#/components/schemas/ToolResultBlock'
          thinking:
            $ref: '#/components/schemas/ThinkingBlock'
          redacted_thinking:
            $ref: '#/components/schemas/RedactedThinkingBlock'
    ToolChoiceAuto:
      type: object
      properties:
        type:
          type: string
          enum:
            - auto
        disable_parallel_tool_use:
          type: boolean
      required:
        - type
    ToolChoiceAny:
      type: object
      properties:
        type:
          type: string
          enum:
            - any
        disable_parallel_tool_use:
          type: boolean
      required:
        - type
    ToolChoiceTool:
      type: object
      properties:
        type:
          type: string
          enum:
            - tool
        name:
          type: string
        disable_parallel_tool_use:
          type: boolean
      required:
        - type
        - name
    ToolChoiceNone:
      type: object
      properties:
        type:
          type: string
          enum:
            - none
      required:
        - type
    ThinkingConfigEnabled:
      type: object
      description: Accepted by the spec, rejected by validation (no budget mapping).
      properties:
        type:
          type: string
          enum:
            - enabled
        budget_tokens:
          type: integer
      required:
        - type
        - budget_tokens
    ThinkingConfigDisabled:
      type: object
      properties:
        type:
          type: string
          enum:
            - disabled
      required:
        - type
    ToolUseBlock:
      type: object
      description: Tool invocation, in assistant history and in responses.
      properties:
        type:
          type: string
          enum:
            - tool_use
        id:
          type: string
        name:
          type: string
        input:
          type: object
          additionalProperties: true
          description: >-
            Kept as raw JSON so caller bytes (e.g. int64 ids) pass through
            verbatim.
          x-go-type: json.RawMessage
      required:
        - type
        - id
        - name
        - input
    ThinkingBlock:
      type: object
      description: Extended-thinking output; in requests only as replayed history.
      properties:
        type:
          type: string
          enum:
            - thinking
        thinking:
          type: string
        signature:
          type: string
      required:
        - type
        - thinking
        - signature
    ImageBlock:
      type: object
      properties:
        type:
          type: string
          enum:
            - image
        source:
          $ref: '#/components/schemas/ImageSource'
      required:
        - type
        - source
    ToolResultBlock:
      type: object
      properties:
        type:
          type: string
          enum:
            - tool_result
        tool_use_id:
          type: string
        content:
          description: Tool output as plain text or an array of content blocks.
          oneOf:
            - type: string
              title: Text
            - type: array
              title: Content blocks
              items:
                $ref: '#/components/schemas/ToolResultContentBlock'
        is_error:
          type: boolean
      required:
        - type
        - tool_use_id
    RedactedThinkingBlock:
      type: object
      description: Redacted thinking replay. Accepted by the spec, rejected by validation.
      properties:
        type:
          type: string
          enum:
            - redacted_thinking
        data:
          type: string
      required:
        - type
        - data
    ImageSource:
      oneOf:
        - $ref: '#/components/schemas/Base64ImageSource'
        - $ref: '#/components/schemas/URLImageSource'
      discriminator:
        propertyName: type
        mapping:
          base64:
            $ref: '#/components/schemas/Base64ImageSource'
          url:
            $ref: '#/components/schemas/URLImageSource'
    ToolResultContentBlock:
      oneOf:
        - $ref: '#/components/schemas/TextBlock'
        - $ref: '#/components/schemas/ImageBlock'
      discriminator:
        propertyName: type
        mapping:
          text:
            $ref: '#/components/schemas/TextBlock'
          image:
            $ref: '#/components/schemas/ImageBlock'
    Base64ImageSource:
      type: object
      properties:
        type:
          type: string
          enum:
            - base64
        media_type:
          type: string
          enum:
            - image/jpeg
            - image/png
            - image/gif
            - image/webp
        data:
          type: string
          description: Base64-encoded image bytes, kept as a string end to end.
      required:
        - type
        - media_type
        - data
    URLImageSource:
      type: object
      properties:
        type:
          type: string
          enum:
            - url
        url:
          type: string
      required:
        - type
        - url
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
      description: Your Perplexity API key.

````