{ "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" } ], "paths": { "/router/v1/messages": { "post": { "summary": "Create Message", "operationId": "gateway_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.", "security": [ { "HTTPBearer": [] } ], "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" } } } } } } } }, "components": { "schemas": { "CreateMessageRequest": { "type": "object", "description": "Request body for POST /router/v1/messages.", "properties": { "model": { "type": "string", "description": "Public model slug, e.g. `perplexity/kimi-k3`." }, "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" ] }, "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" ] }, "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": "#/components/schemas/TextBlock", "image": "#/components/schemas/ImageBlock", "tool_use": "#/components/schemas/ToolUseBlock", "tool_result": "#/components/schemas/ToolResultBlock", "thinking": "#/components/schemas/ThinkingBlock", "redacted_thinking": "#/components/schemas/RedactedThinkingBlock" } } }, "TextBlock": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ] }, "ImageBlock": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "$ref": "#/components/schemas/ImageSource" } }, "required": [ "type", "source" ] }, "ImageSource": { "oneOf": [ { "$ref": "#/components/schemas/Base64ImageSource" }, { "$ref": "#/components/schemas/URLImageSource" } ], "discriminator": { "propertyName": "type", "mapping": { "base64": "#/components/schemas/Base64ImageSource", "url": "#/components/schemas/URLImageSource" } } }, "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" ] }, "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" ] }, "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" ] }, "ToolResultContentBlock": { "oneOf": [ { "$ref": "#/components/schemas/TextBlock" }, { "$ref": "#/components/schemas/ImageBlock" } ], "discriminator": { "propertyName": "type", "mapping": { "text": "#/components/schemas/TextBlock", "image": "#/components/schemas/ImageBlock" } } }, "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" ] }, "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" ] }, "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": "#/components/schemas/ToolChoiceAuto", "any": "#/components/schemas/ToolChoiceAny", "tool": "#/components/schemas/ToolChoiceTool", "none": "#/components/schemas/ToolChoiceNone" } } }, "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" ] }, "ThinkingConfig": { "oneOf": [ { "$ref": "#/components/schemas/ThinkingConfigEnabled" }, { "$ref": "#/components/schemas/ThinkingConfigDisabled" } ], "discriminator": { "propertyName": "type", "mapping": { "enabled": "#/components/schemas/ThinkingConfigEnabled", "disabled": "#/components/schemas/ThinkingConfigDisabled" } } }, "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" ] }, "RequestMetadata": { "type": "object", "properties": { "user_id": { "type": "string", "nullable": true } } }, "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" ] }, "ContentBlock": { "oneOf": [ { "$ref": "#/components/schemas/TextBlock" }, { "$ref": "#/components/schemas/ToolUseBlock" }, { "$ref": "#/components/schemas/ThinkingBlock" } ], "discriminator": { "propertyName": "type", "mapping": { "text": "#/components/schemas/TextBlock", "tool_use": "#/components/schemas/ToolUseBlock", "thinking": "#/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" ] }, "MessageStartEvent": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "message_start" ] }, "message": { "$ref": "#/components/schemas/Message" } }, "required": [ "type", "message" ] }, "ContentBlockStartEvent": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "content_block_start" ] }, "index": { "type": "integer" }, "content_block": { "$ref": "#/components/schemas/ContentBlock" } }, "required": [ "type", "index", "content_block" ] }, "ContentBlockDeltaEvent": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "content_block_delta" ] }, "index": { "type": "integer" }, "delta": { "$ref": "#/components/schemas/ContentBlockDelta" } }, "required": [ "type", "index", "delta" ] }, "ContentBlockDelta": { "oneOf": [ { "$ref": "#/components/schemas/TextDelta" }, { "$ref": "#/components/schemas/InputJSONDelta" }, { "$ref": "#/components/schemas/ThinkingDelta" }, { "$ref": "#/components/schemas/SignatureDelta" } ], "discriminator": { "propertyName": "type", "mapping": { "text_delta": "#/components/schemas/TextDelta", "input_json_delta": "#/components/schemas/InputJSONDelta", "thinking_delta": "#/components/schemas/ThinkingDelta", "signature_delta": "#/components/schemas/SignatureDelta" } } }, "TextDelta": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text_delta" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ] }, "InputJSONDelta": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "input_json_delta" ] }, "partial_json": { "type": "string" } }, "required": [ "type", "partial_json" ] }, "ThinkingDelta": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "thinking_delta" ] }, "thinking": { "type": "string" } }, "required": [ "type", "thinking" ] }, "SignatureDelta": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "signature_delta" ] }, "signature": { "type": "string" } }, "required": [ "type", "signature" ] }, "ContentBlockStopEvent": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "content_block_stop" ] }, "index": { "type": "integer" } }, "required": [ "type", "index" ] }, "MessageDeltaEvent": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "message_delta" ] }, "delta": { "$ref": "#/components/schemas/MessageDelta" }, "usage": { "$ref": "#/components/schemas/MessageDeltaUsage" } }, "required": [ "type", "delta", "usage" ] }, "MessageDelta": { "type": "object", "properties": { "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 } }, "required": [ "stop_reason", "stop_sequence" ] }, "MessageDeltaUsage": { "type": "object", "properties": { "output_tokens": { "type": "integer" } }, "required": [ "output_tokens" ] }, "MessageStopEvent": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "message_stop" ] } }, "required": [ "type" ] }, "PingEvent": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ping" ] } }, "required": [ "type" ] }, "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" ] }, "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" ] } }, "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer", "description": "Your Perplexity API key." } } } }