{ "openapi": "3.1.0", "info": { "title": "Perplexity AI API", "description": "Perplexity AI API", "version": "1.0.0" }, "servers": [ { "url": "https://api.perplexity.ai", "description": "Perplexity AI API" } ], "paths": { "/v1/sonar": { "post": { "summary": "Create Chat Completion", "description": "Generate a chat completion response for the given conversation.", "operationId": "chat_completions_chat_completions_post", "security": [ { "HTTPBearer": [] } ], "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" } } } } } } }, "/search": { "post": { "summary": "Search the Web", "operationId": "search_search_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiSearchRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiSearchResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Search the web and retrieve relevant web page contents." } }, "/v1/embeddings": { "post": { "summary": "Create Embeddings", "description": "Generate embeddings for a list of texts. Use these embeddings for semantic search, clustering, and other machine learning applications.", "operationId": "embeddings_v1_embeddings_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/contextualizedembeddings": { "post": { "summary": "Create Contextualized Embeddings", "description": "Generate contextualized embeddings for document chunks. Chunks from the same document share context awareness, improving retrieval quality for document-based applications.", "operationId": "contextualized_embeddings_v1_contextualizedembeddings_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextualizedEmbeddingsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextualizedEmbeddingsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/async/sonar/{api_request}": { "get": { "summary": "Get Async Chat Completion", "description": "Retrieve the response for a given asynchronous chat completion request.", "operationId": "get_async_chat_completion_response_async_chat_completions__api_request__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "api_request", "in": "path", "required": true, "schema": { "type": "string", "title": "Api Request" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncApiChatCompletionsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/async/sonar": { "get": { "summary": "List Async Chat Completions", "description": "Retrieve a list of all asynchronous chat completion requests for a given user.", "operationId": "list_async_chat_completions_async_chat_completions_get", "security": [ { "HTTPBearer": [] } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAsyncApiChatCompletionsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "summary": "Create Async Chat Completion", "description": "Submit an asynchronous chat completion request.", "operationId": "create_async_chat_completions_async_chat_completions_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncApiChatCompletionsRequest" }, "example": { "request": { "model": "sonar-deep-research", "messages": [ { "role": "", "content": "" } ] } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncApiChatCompletionsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agent": { "post": { "description": "Generate a response for the provided input with optional web search and reasoning.", "operationId": "createAgent", "summary": "Create Agent Response", "security": [ { "HTTPBearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesResponse" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/ResponseStreamEvent" } } }, "description": "Successful response. Content type depends on `stream` parameter:\n- `stream: false` (default): `application/json` with Response\n- `stream: true`: `text/event-stream` with SSE events\n" } } } }, "/v1/models": { "get": { "summary": "List Models", "description": "List the models available for the Agent API. Returns model identifiers that can be used with the `POST /v1/agent` endpoint. The response follows the OpenAI List Models format for compatibility with third-party tools.", "operationId": "listModels", "security": [], "responses": { "200": { "description": "Successful response with the list of available models.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListModelsResponse" }, "example": { "object": "list", "data": [ { "id": "anthropic/claude-sonnet-4-6", "object": "model", "created": 0, "owned_by": "anthropic" }, { "id": "openai/gpt-5.4", "object": "model", "created": 0, "owned_by": "openai" }, { "id": "perplexity/sonar", "object": "model", "created": 0, "owned_by": "perplexity" } ] } } } } } } } }, "components": { "schemas": { "ApiChatCompletionsRequest": { "properties": { "max_tokens": { "anyOf": [ { "type": "integer", "maximum": 128000, "exclusiveMinimum": 0 }, { "type": "null" } ], "title": "Max Tokens", "description": "Maximum number of completion tokens to generate" }, "model": { "type": "string", "title": "Model", "description": "Model to use, for example, sonar-pro", "enum": [ "sonar", "sonar-pro", "sonar-deep-research", "sonar-reasoning-pro" ] }, "stream": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Stream", "description": "If true, returns streaming SSE response", "default": false }, "stop": { "anyOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Stop", "description": "Stop sequences. Generation stops when one of these strings is produced" }, "temperature": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 2 }, { "type": "null" } ], "title": "Temperature", "description": "Controls randomness in the response. Higher values make output more random. Range: 0-2" }, "top_p": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ], "title": "Top P", "description": "Nucleus sampling parameter. Controls diversity via nucleus sampling" }, "response_format": { "anyOf": [ { "$ref": "#/components/schemas/ResponseFormatText" }, { "$ref": "#/components/schemas/ResponseFormatJSONSchema" }, { "type": "null" } ], "title": "Response Format", "description": "Optional. Controls the output format. Omit for default text output. Set `type` to `json_schema` for structured output.", "discriminator": { "propertyName": "type", "mapping": { "text": "#/components/schemas/ResponseFormatText", "json_schema": "#/components/schemas/ResponseFormatJSONSchema" } } }, "messages": { "items": { "$ref": "#/components/schemas/ChatMessage-Input" }, "type": "array", "title": "Messages", "description": "Array of messages forming the conversation history" }, "web_search_options": { "$ref": "#/components/schemas/WebSearchOptions" }, "search_mode": { "anyOf": [ { "type": "string", "enum": [ "web", "academic", "sec" ] }, { "type": "null" } ], "title": "Search Mode", "description": "Source of search results (web, academic, or sec)" }, "return_images": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Return Images", "description": "When true, include image results in the response" }, "return_related_questions": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Return Related Questions", "description": "When true, generates suggested follow-up queries based on the search results" }, "enable_search_classifier": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enable Search Classifier", "description": "When true, uses a classifier to determine if web search is needed for the query" }, "disable_search": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Disable Search", "description": "When true, disables all web search capabilities. The model responds based solely on its training data" }, "search_domain_filter": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Search Domain Filter", "description": "Limit search results to specific domains (e.g. github.com, wikipedia.org)" }, "search_language_filter": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Search Language Filter", "description": "Filter results by language using ISO 639-1 codes (e.g. en, fr, de)" }, "search_recency_filter": { "anyOf": [ { "type": "string", "enum": [ "hour", "day", "week", "month", "year" ] }, { "type": "null" } ], "title": "Search Recency Filter", "description": "Filter by publication recency (hour, day, week, month, or year)" }, "search_after_date_filter": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search After Date Filter", "description": "Return results published after this date (MM/DD/YYYY)" }, "search_before_date_filter": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search Before Date Filter", "description": "Return results published before this date (MM/DD/YYYY)" }, "last_updated_before_filter": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Updated Before Filter", "description": "Return results last updated before this date (MM/DD/YYYY)" }, "last_updated_after_filter": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Updated After Filter", "description": "Return results last updated after this date (MM/DD/YYYY)" }, "image_format_filter": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Image Format Filter", "description": "Filter image results by format (e.g. png, jpg)" }, "image_domain_filter": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Image Domain Filter", "description": "Limit image results to specific domains" }, "stream_mode": { "type": "string", "enum": [ "full", "concise" ], "title": "Stream Mode", "description": "Controls the format of streaming events. 'full' suppresses reasoning events and includes metadata inline; 'concise' emits reasoning events separately", "default": "full" }, "reasoning_effort": { "anyOf": [ { "type": "string", "enum": [ "minimal", "low", "medium", "high" ] }, { "type": "null" } ], "title": "Reasoning Effort", "description": "Controls how much effort the model spends on reasoning" }, "language_preference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language Preference", "description": "ISO 639-1 language code for preferred response language" } }, "type": "object", "required": [ "model", "messages" ], "title": "ApiChatCompletionsRequest" }, "ApiPublicSearchResult": { "description": "A single search result from the web", "properties": { "title": { "type": "string", "title": "Title", "description": "Title of the search result page" }, "url": { "type": "string", "title": "Url", "description": "URL of the search result page" }, "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Date", "description": "Publication date of the result" }, "last_updated": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Updated", "description": "Date the result was last updated" }, "snippet": { "type": "string", "title": "Snippet", "description": "Text snippet from the search result", "default": "" }, "source": { "type": "string", "enum": [ "web", "attachment" ], "title": "Source", "description": "Source type of the result (web or attachment)", "default": "web" } }, "type": "object", "required": [ "title", "url" ], "title": "ApiPublicSearchResult" }, "ImageResult": { "properties": { "image_url": { "type": "string", "title": "Image Url", "description": "URL of the image" }, "origin_url": { "type": "string", "title": "Origin Url", "description": "Original URL where the image was found" }, "title": { "type": "string", "title": "Title", "description": "Title or description of the image" }, "width": { "type": "integer", "title": "Width", "description": "Width of the image in pixels" }, "height": { "type": "integer", "title": "Height", "description": "Height of the image in pixels" } }, "type": "object", "required": [ "image_url", "origin_url", "title", "width", "height" ], "title": "ImageResult" }, "ApiSearchPage": { "description": "A single page from search results", "properties": { "title": { "type": "string", "title": "Title", "description": "Title of the page" }, "url": { "type": "string", "title": "Url", "description": "URL of the page" }, "snippet": { "type": "string", "title": "Snippet", "description": "Content snippet extracted from the page" }, "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Date", "description": "Publication date of the page" }, "last_updated": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Updated", "description": "Date the page was last updated" } }, "type": "object", "required": [ "title", "url", "snippet" ], "title": "ApiSearchPage" }, "ApiSearchRequest": { "allOf": [ { "properties": { "country": { "description": "ISO 3166-1 alpha-2 country code", "maxLength": 2, "minLength": 2, "type": "string" }, "max_results": { "default": 10, "description": "Maximum number of results to return", "maximum": 20, "minimum": 1, "type": "integer" }, "max_tokens": { "default": 10000, "description": "Maximum tokens for context", "maximum": 1000000, "minimum": 1, "type": "integer" }, "max_tokens_per_page": { "default": 4096, "description": "Maximum tokens per page", "maximum": 1000000, "minimum": 1, "type": "integer" }, "query": { "anyOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" } ], "title": "Query", "description": "Search query (required)" }, "search_language_filter": { "description": "ISO 639-1 language codes (2-character max)", "items": { "maxLength": 2, "minLength": 2, "type": "string" }, "maxItems": 20, "type": "array" } }, "required": [ "query" ], "type": "object" }, { "$ref": "#/components/schemas/SearchDomainFilter" }, { "$ref": "#/components/schemas/DateFilters" } ], "type": "object", "title": "ApiSearchRequest" }, "ApiSearchResponse": { "properties": { "results": { "items": { "$ref": "#/components/schemas/ApiSearchPage" }, "type": "array", "title": "Results" }, "id": { "type": "string", "title": "Id" }, "server_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Server Time" } }, "type": "object", "required": [ "results", "id" ], "title": "ApiSearchResponse" }, "AsyncApiChatCompletionsRequest": { "description": "Request body for creating an asynchronous chat completion", "properties": { "request": { "$ref": "#/components/schemas/ApiChatCompletionsRequest", "description": "The chat completion request to execute asynchronously" }, "idempotency_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency Key", "description": "Unique key to prevent duplicate requests" } }, "type": "object", "required": [ "request" ], "title": "AsyncApiChatCompletionsRequest" }, "AsyncApiChatCompletionsResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier for the async request" }, "model": { "type": "string", "title": "Model", "description": "Model used for the request" }, "created_at": { "type": "integer", "title": "Created At", "description": "Unix timestamp when the request was created" }, "started_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Started At", "description": "Unix timestamp when processing started" }, "completed_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Completed At", "description": "Unix timestamp when processing completed" }, "response": { "anyOf": [ { "$ref": "#/components/schemas/CompletionResponse" }, { "type": "null" } ] }, "failed_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Failed At", "description": "Unix timestamp when the request failed (if applicable)" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Message", "description": "Error message if the request failed" }, "status": { "$ref": "#/components/schemas/AsyncProcessingStatus", "description": "Current processing status of the request" } }, "type": "object", "required": [ "id", "model", "created_at", "status" ], "title": "AsyncApiChatCompletionsResponse" }, "AsyncApiChatCompletionsResponseSummary": { "properties": { "id": { "type": "string", "title": "Id" }, "created_at": { "type": "integer", "title": "Created At" }, "started_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Started At" }, "completed_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Completed At" }, "failed_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Failed At" }, "model": { "type": "string", "title": "Model" }, "status": { "$ref": "#/components/schemas/AsyncProcessingStatus" } }, "type": "object", "required": [ "id", "created_at", "model", "status" ], "title": "AsyncApiChatCompletionsResponseSummary" }, "AsyncProcessingStatus": { "type": "string", "enum": [ "CREATED", "IN_PROGRESS", "COMPLETED", "FAILED" ], "title": "AsyncProcessingStatus", "description": "Status enum for async processing." }, "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" } }, "type": "object", "required": [ "role", "content" ], "title": "ChatMessage" }, "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" } }, "type": "object", "required": [ "role", "content" ], "title": "ChatMessage" }, "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" }, "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" }, "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" }, "ChatMessageContentTextChunk": { "properties": { "type": { "type": "string", "const": "text", "title": "Type" }, "text": { "type": "string", "title": "Text" } }, "type": "object", "required": [ "type", "text" ], "title": "ChatMessageContentTextChunk" }, "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" }, "ChatMessageRole": { "type": "string", "enum": [ "system", "user", "assistant", "tool" ], "title": "ChatMessageRole", "description": "Chat roles enum" }, "Choice": { "description": "A single completion choice", "properties": { "index": { "type": "integer", "title": "Index", "description": "Index of the choice in the array" }, "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length" ] }, { "type": "null" } ], "title": "Finish Reason", "description": "Reason generation stopped (stop or length)" }, "message": { "$ref": "#/components/schemas/ChatMessage-Output", "description": "Complete message (non-streaming)" }, "delta": { "$ref": "#/components/schemas/ChatMessage-Output", "description": "Incremental message delta (streaming)" } }, "type": "object", "required": [ "index", "message", "delta" ], "title": "Choice" }, "CompletionResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier for the completion" }, "model": { "type": "string", "title": "Model", "description": "Model used for generation" }, "created": { "type": "integer", "title": "Created", "description": "Unix timestamp when the completion was created" }, "usage": { "anyOf": [ { "$ref": "#/components/schemas/UsageInfo" }, { "type": "null" } ] }, "object": { "type": "string", "title": "Object", "description": "Object type identifier", "default": "chat.completion" }, "choices": { "items": { "$ref": "#/components/schemas/Choice" }, "type": "array", "title": "Choices", "description": "Array of completion choices" }, "citations": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Citations", "description": "URLs of sources used to generate the response" }, "search_results": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ApiPublicSearchResult" }, "type": "array" }, { "type": "null" } ], "title": "Search Results", "description": "Search results used for context in the response" }, "images": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ImageResult" }, "type": "array" }, { "type": "null" } ], "title": "Images", "description": "Array of images returned when return_images is true" }, "related_questions": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Related Questions", "description": "Array of related questions returned when return_related_questions is true" } }, "type": "object", "required": [ "id", "model", "created", "choices" ], "title": "CompletionResponse" }, "CompletionResponseStatus": { "description": "Status of a streaming completion response", "type": "string", "enum": [ "PENDING", "COMPLETED" ], "title": "CompletionResponseStatus" }, "CompletionResponseType": { "description": "Type of a streaming completion response chunk", "type": "string", "enum": [ "message", "info", "end_of_stream" ], "title": "CompletionResponseType" }, "Cost": { "description": "Cost breakdown for a chat completion request", "properties": { "input_tokens_cost": { "type": "number", "title": "Input Tokens Cost", "description": "Cost for input tokens in USD" }, "output_tokens_cost": { "type": "number", "title": "Output Tokens Cost", "description": "Cost for output tokens in USD" }, "reasoning_tokens_cost": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Reasoning Tokens Cost", "description": "Cost for reasoning tokens in USD" }, "request_cost": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Request Cost", "description": "Cost for web search requests in USD (includes pro search cost if applicable)" }, "citation_tokens_cost": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Citation Tokens Cost", "description": "Cost for citation tokens in USD" }, "search_queries_cost": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Search Queries Cost", "description": "Cost for search queries in USD" }, "total_cost": { "type": "number", "title": "Total Cost", "description": "Total cost for the request in USD" } }, "type": "object", "required": [ "input_tokens_cost", "output_tokens_cost", "total_cost" ], "title": "Cost" }, "Currency": { "description": "Currency code for cost values", "enum": [ "USD" ], "type": "string" }, "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" }, "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" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "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" }, "ListAsyncApiChatCompletionsResponse": { "properties": { "next_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Token" }, "requests": { "items": { "$ref": "#/components/schemas/AsyncApiChatCompletionsResponseSummary" }, "type": "array", "title": "Requests" } }, "type": "object", "required": [ "requests" ], "title": "ListAsyncApiChatCompletionsResponse" }, "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" } ] }, "finance_search": { "anyOf": [ { "$ref": "#/components/schemas/FinanceSearchStepDetails" }, { "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" }, "ResponseFormatJSONSchema": { "description": "Constrains the model output to match the provided JSON schema.", "properties": { "type": { "type": "string", "const": "json_schema", "title": "Type", "description": "Must be `json_schema`." }, "json_schema": { "$ref": "#/components/schemas/JSONSchema" } }, "type": "object", "required": [ "type", "json_schema" ], "title": "ResponseFormatJSONSchema" }, "ResponseFormatText": { "properties": { "type": { "type": "string", "const": "text", "title": "Type", "description": "Must be `text`." } }, "type": "object", "required": [ "type" ], "title": "ResponseFormatText" }, "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" }, "ToolCallFunction": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "arguments": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Arguments" } }, "type": "object", "title": "ToolCallFunction" }, "URL": { "properties": { "url": { "type": "string", "title": "Url" } }, "type": "object", "required": [ "url" ], "title": "URL" }, "UsageInfo": { "description": "Token usage and cost information for a request", "properties": { "prompt_tokens": { "type": "integer", "title": "Prompt Tokens", "description": "Number of tokens in the prompt/input" }, "completion_tokens": { "type": "integer", "title": "Completion Tokens", "description": "Number of tokens in the completion/output" }, "total_tokens": { "type": "integer", "title": "Total Tokens", "description": "Total tokens used (prompt + completion)" }, "search_context_size": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search Context Size", "description": "Size of search context used" }, "citation_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Citation Tokens", "description": "Number of tokens used for citations" }, "num_search_queries": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Num Search Queries", "description": "Number of search queries executed" }, "reasoning_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Reasoning Tokens", "description": "Number of tokens used for reasoning" }, "cost": { "$ref": "#/components/schemas/Cost", "description": "Cost breakdown for the request" } }, "type": "object", "required": [ "prompt_tokens", "completion_tokens", "total_tokens", "cost" ], "title": "UsageInfo" }, "UserLocation": { "description": "User's geographic location for search personalization", "properties": { "latitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Latitude", "description": "Latitude coordinate" }, "longitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Longitude", "description": "Longitude coordinate" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country", "description": "ISO 3166-1 alpha-2 country code" }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City", "description": "City name" }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Region", "description": "State or region name" } }, "type": "object", "title": "UserLocation" }, "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" }, "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" }, "WebSearchOptions": { "description": "Configuration options for web search behavior", "properties": { "search_context_size": { "type": "string", "enum": [ "low", "medium", "high" ], "title": "Search Context Size", "description": "Amount of search context to include (low, medium, or high)", "default": "low" }, "search_type": { "anyOf": [ { "type": "string", "enum": [ "fast", "pro", "auto" ] }, { "type": "null" } ], "title": "Search Type", "description": "Search type (fast for speed, pro for quality, auto to let the model decide)" }, "user_location": { "anyOf": [ { "$ref": "#/components/schemas/UserLocation" }, { "type": "null" } ] }, "image_results_enhanced_relevance": { "type": "boolean", "title": "Image Results Enhanced Relevance", "description": "When true, applies enhanced relevance filtering to image results", "default": false } }, "type": "object", "title": "WebSearchOptions" }, "ResponsesRequest": { "properties": { "input": { "$ref": "#/components/schemas/Input" }, "instructions": { "description": "System instructions for the model", "type": "string" }, "language_preference": { "description": "ISO 639-1 language code for response language", "type": "string" }, "max_output_tokens": { "description": "Maximum tokens to generate", "format": "int32", "minimum": 1, "type": "integer" }, "max_steps": { "description": "Maximum number of research loop steps.\nIf provided, overrides the preset's max_steps value.\nMust be >= 1 if specified. Maximum allowed is 10.\n", "format": "int32", "maximum": 10, "minimum": 1, "type": "integer" }, "model": { "description": "Model ID in provider/model format (e.g., \"xai/grok-4-1\", \"openai/gpt-4o\").\nIf models is also provided, models takes precedence.\nRequired if neither models nor preset is provided.\n", "type": "string" }, "models": { "description": "Model fallback chain. Each model is in provider/model format.\nModels are tried in order until one succeeds.\nMax 5 models allowed. If set, takes precedence over single model field.\nThe response.model will reflect the model that actually succeeded.\n", "items": { "type": "string" }, "maxItems": 5, "minItems": 1, "type": "array" }, "preset": { "description": "Preset configuration name (e.g., \"fast-search\", \"pro-search\", \"deep-research\").\nPre-configured model with system prompt and search parameters.\nRequired if model is not provided.\n", "type": "string" }, "reasoning": { "$ref": "#/components/schemas/ReasoningConfig" }, "response_format": { "$ref": "#/components/schemas/ResponseFormat" }, "stream": { "description": "If true, returns SSE stream instead of JSON", "type": "boolean" }, "tools": { "description": "Tools available to the model", "items": { "$ref": "#/components/schemas/Tool" }, "type": "array" } }, "required": [ "input" ], "type": "object", "title": "ResponsesRequest" }, "ResponsesResponse": { "description": "Non-streaming response returned when stream is false", "properties": { "created_at": { "description": "Unix timestamp when the response was created", "format": "int64", "type": "integer" }, "error": { "$ref": "#/components/schemas/ErrorInfo", "description": "Error details if the response failed" }, "id": { "description": "Unique identifier for the response", "type": "string" }, "model": { "description": "Model used for generation", "type": "string" }, "object": { "$ref": "#/components/schemas/ResponsesObjectType", "description": "Object type identifier" }, "output": { "description": "Array of output items (messages, search results, tool calls)", "items": { "$ref": "#/components/schemas/OutputItem" }, "type": "array" }, "status": { "$ref": "#/components/schemas/Status", "description": "Status of the response" }, "usage": { "$ref": "#/components/schemas/ResponsesUsage", "description": "Token usage and cost information" } }, "required": [ "id", "object", "created_at", "status", "model", "output" ], "type": "object", "title": "ResponsesResponse" }, "ResponsesObjectType": { "description": "Object type in API responses", "enum": [ "response" ], "type": "string", "title": "ResponsesObjectType" }, "ResponsesUsage": { "description": "Token usage and cost information for a Responses API request", "properties": { "cost": { "$ref": "#/components/schemas/ResponsesCost", "description": "Cost breakdown for the request" }, "input_tokens": { "description": "Number of input tokens used", "format": "int64", "type": "integer" }, "input_tokens_details": { "properties": { "cache_creation_input_tokens": { "description": "Tokens used for cache creation", "format": "int64", "type": "integer" }, "cache_read_input_tokens": { "description": "Tokens read from cache", "format": "int64", "type": "integer" } }, "type": "object" }, "output_tokens": { "description": "Number of output tokens generated", "format": "int64", "type": "integer" }, "tool_calls_details": { "description": "Details about tool call invocations", "additionalProperties": { "$ref": "#/components/schemas/ToolCallDetails" }, "type": "object" }, "total_tokens": { "description": "Total tokens used (input + output)", "format": "int64", "type": "integer" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "type": "object", "title": "ResponsesUsage" }, "ResponsesCost": { "description": "Cost breakdown for a Responses API request", "properties": { "cache_creation_cost": { "description": "Cost for cache creation in USD", "format": "double", "type": "number" }, "cache_read_cost": { "description": "Cost for cache reads in USD", "format": "double", "type": "number" }, "currency": { "$ref": "#/components/schemas/Currency", "description": "Currency of the cost values" }, "input_cost": { "description": "Cost for input tokens in USD", "format": "double", "type": "number" }, "output_cost": { "description": "Cost for output tokens in USD", "format": "double", "type": "number" }, "tool_calls_cost": { "description": "Cost for tool call invocations in USD", "format": "double", "type": "number" }, "total_cost": { "description": "Total cost for the request in USD", "format": "double", "type": "number" } }, "required": [ "currency", "input_cost", "output_cost", "total_cost" ], "type": "object", "title": "ResponsesCost" }, "Input": { "description": "Input content - either a string or array of input items", "oneOf": [ { "title": "StringInput", "type": "string" }, { "items": { "$ref": "#/components/schemas/InputItem" }, "title": "InputItemArray", "type": "array" } ], "title": "Input" }, "InputItem": { "discriminator": { "mapping": { "function_call": "#/components/schemas/FunctionCallInput", "function_call_output": "#/components/schemas/FunctionCallOutputInput", "message": "#/components/schemas/InputMessage" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/InputMessage" }, { "$ref": "#/components/schemas/FunctionCallOutputInput" }, { "$ref": "#/components/schemas/FunctionCallInput" } ], "title": "InputItem" }, "InputMessage": { "properties": { "content": { "$ref": "#/components/schemas/InputContent" }, "role": { "enum": [ "user", "assistant", "system", "developer" ], "type": "string" }, "type": { "enum": [ "message" ], "type": "string" } }, "required": [ "type", "role", "content" ], "type": "object", "title": "InputMessage" }, "InputContent": { "description": "Message content - either a string or array of content parts", "oneOf": [ { "title": "StringContent", "type": "string" }, { "items": { "$ref": "#/components/schemas/InputContentPart" }, "title": "ContentPartArray", "type": "array" } ], "title": "InputContent" }, "InputContentPart": { "properties": { "image_url": { "maxLength": 2048, "type": "string" }, "text": { "type": "string" }, "type": { "enum": [ "input_text", "input_image" ], "type": "string" } }, "required": [ "type" ], "type": "object", "title": "InputContentPart" }, "OutputItem": { "discriminator": { "mapping": { "fetch_url_results": "#/components/schemas/FetchUrlResultsOutputItem", "function_call": "#/components/schemas/FunctionCallOutputItem", "message": "#/components/schemas/MessageOutputItem", "search_results": "#/components/schemas/SearchResultsOutputItem" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/MessageOutputItem" }, { "$ref": "#/components/schemas/SearchResultsOutputItem" }, { "$ref": "#/components/schemas/FetchUrlResultsOutputItem" }, { "$ref": "#/components/schemas/FunctionCallOutputItem" } ], "title": "OutputItem" }, "MessageOutputItem": { "properties": { "content": { "items": { "$ref": "#/components/schemas/ContentPart" }, "type": "array" }, "id": { "type": "string" }, "role": { "$ref": "#/components/schemas/RoleType" }, "status": { "$ref": "#/components/schemas/Status" }, "type": { "enum": [ "message" ], "type": "string" } }, "required": [ "type", "id", "status", "role", "content" ], "type": "object", "title": "MessageOutputItem" }, "SearchResultsOutputItem": { "properties": { "queries": { "items": { "type": "string" }, "type": "array" }, "results": { "items": { "$ref": "#/components/schemas/SearchResult" }, "type": "array" }, "type": { "enum": [ "search_results" ], "type": "string" } }, "required": [ "type", "results" ], "type": "object", "title": "SearchResultsOutputItem" }, "FetchUrlResultsOutputItem": { "properties": { "contents": { "items": { "$ref": "#/components/schemas/UrlContent" }, "type": "array" }, "type": { "enum": [ "fetch_url_results" ], "type": "string" } }, "required": [ "type", "contents" ], "type": "object", "title": "FetchUrlResultsOutputItem" }, "ContentPart": { "properties": { "annotations": { "items": { "$ref": "#/components/schemas/Annotation" }, "type": "array" }, "text": { "type": "string" }, "type": { "$ref": "#/components/schemas/ContentPartType" } }, "required": [ "type", "text" ], "type": "object", "title": "ContentPart" }, "ContentPartType": { "description": "Type of a content part", "enum": [ "output_text" ], "type": "string", "title": "ContentPartType" }, "Annotation": { "description": "Text annotation (URL citation)", "properties": { "end_index": { "description": "End character index of the annotated text", "format": "int32", "type": "integer" }, "start_index": { "description": "Start character index of the annotated text", "format": "int32", "type": "integer" }, "title": { "description": "Title of the cited source", "type": "string" }, "type": { "description": "Annotation type (url_citation)", "type": "string" }, "url": { "description": "URL of the cited source", "type": "string" } }, "type": "object", "title": "Annotation" }, "SearchResult": { "description": "A single search result used in LLM responses", "properties": { "date": { "description": "Publication date of the result", "type": "string" }, "id": { "description": "Unique numeric identifier for the result", "format": "int64", "type": "integer" }, "last_updated": { "description": "Date the result was last updated", "type": "string" }, "snippet": { "description": "Text snippet from the search result", "type": "string" }, "source": { "$ref": "#/components/schemas/SearchSource", "description": "Source type of the result" }, "title": { "description": "Title of the search result page", "type": "string" }, "url": { "description": "URL of the search result page", "type": "string" } }, "required": [ "id", "url", "title", "snippet" ], "type": "object", "title": "SearchResult" }, "SearchSource": { "description": "Source of search results", "enum": [ "web" ], "type": "string", "title": "SearchSource" }, "UrlContent": { "description": "Content fetched from a URL", "properties": { "snippet": { "description": "The fetched content snippet", "type": "string" }, "title": { "description": "The title of the page", "type": "string" }, "url": { "description": "The URL from which content was fetched", "type": "string" } }, "required": [ "url", "title", "snippet" ], "type": "object", "title": "UrlContent" }, "RoleType": { "description": "Role in a message", "enum": [ "assistant" ], "type": "string", "title": "RoleType" }, "Status": { "description": "Status of a response or output item", "enum": [ "completed", "failed", "in_progress", "requires_action" ], "type": "string", "title": "Status" }, "ErrorInfo": { "description": "Error information returned when a request fails", "properties": { "code": { "description": "Error code", "type": "string" }, "message": { "description": "Human-readable error message", "type": "string" }, "type": { "description": "Error type category", "type": "string" } }, "required": [ "message" ], "type": "object", "title": "ErrorInfo" }, "ReasoningConfig": { "properties": { "effort": { "description": "How much effort the model should spend on reasoning", "enum": [ "low", "medium", "high" ], "type": "string" } }, "type": "object", "title": "ReasoningConfig" }, "ResponseFormat": { "description": "Specifies the desired output format for the model response", "properties": { "json_schema": { "$ref": "#/components/schemas/JSONSchemaFormat" }, "type": { "description": "The type of response format", "enum": [ "json_schema" ], "type": "string" } }, "required": [ "type" ], "type": "object", "title": "ResponseFormat" }, "JSONSchemaFormat": { "description": "Defines a JSON schema for structured output validation", "properties": { "description": { "description": "Optional description of the schema", "type": "string" }, "name": { "description": "Name of the schema (1-64 alphanumeric chars)", "maxLength": 64, "minLength": 1, "type": "string" }, "schema": { "additionalProperties": true, "description": "The JSON schema object", "type": "object" }, "strict": { "description": "Whether to enforce strict schema validation", "type": "boolean" } }, "required": [ "name", "schema" ], "type": "object", "title": "JSONSchemaFormat" }, "FunctionCallInput": { "properties": { "arguments": { "description": "Function arguments (JSON string)", "type": "string" }, "call_id": { "description": "The call_id that correlates with function_call_output", "type": "string" }, "name": { "description": "The function name", "type": "string" }, "thought_signature": { "description": "Base64-encoded signature for thinking models", "type": "string" }, "type": { "enum": [ "function_call" ], "type": "string" } }, "required": [ "type", "call_id", "name", "arguments" ], "type": "object", "title": "FunctionCallInput" }, "FunctionCallOutputInput": { "properties": { "call_id": { "description": "The call_id from function_call output", "type": "string" }, "name": { "description": "Function name (required by some providers)", "type": "string" }, "output": { "description": "Function result (JSON string)", "type": "string" }, "thought_signature": { "description": "Base64-encoded signature from function_call", "type": "string" }, "type": { "enum": [ "function_call_output" ], "type": "string" } }, "required": [ "type", "call_id", "output" ], "type": "object", "title": "FunctionCallOutputInput" }, "FunctionCallOutputItem": { "properties": { "arguments": { "description": "JSON string of arguments", "type": "string" }, "call_id": { "description": "Correlates with function_call_output input", "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "status": { "$ref": "#/components/schemas/Status" }, "thought_signature": { "description": "Base64-encoded opaque signature for thinking models", "type": "string" }, "type": { "enum": [ "function_call" ], "type": "string" } }, "required": [ "type", "id", "status", "name", "call_id", "arguments" ], "type": "object", "title": "FunctionCallOutputItem" }, "FunctionTool": { "properties": { "description": { "description": "A description of what the function does", "type": "string" }, "name": { "description": "The name of the function", "type": "string" }, "parameters": { "additionalProperties": true, "description": "JSON Schema defining the function's parameters", "type": "object" }, "strict": { "description": "Whether to enable strict schema validation", "type": "boolean" }, "type": { "enum": [ "function" ], "type": "string" } }, "required": [ "type", "name" ], "type": "object", "title": "FunctionTool" }, "Tool": { "discriminator": { "mapping": { "fetch_url": "#/components/schemas/FetchUrlTool", "finance_search": "#/components/schemas/FinanceSearchTool", "function": "#/components/schemas/FunctionTool", "web_search": "#/components/schemas/WebSearchTool" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/WebSearchTool" }, { "$ref": "#/components/schemas/FinanceSearchTool" }, { "$ref": "#/components/schemas/FetchUrlTool" }, { "$ref": "#/components/schemas/FunctionTool" } ], "title": "Tool" }, "WebSearchTool": { "description": "Web search tool configuration for the Responses API", "properties": { "filters": { "$ref": "#/components/schemas/WebSearchFilters", "description": "Domain and date filters for search results" }, "max_tokens": { "description": "Maximum total tokens for search context", "format": "int32", "type": "integer" }, "max_tokens_per_page": { "description": "Maximum tokens to extract per search result page", "format": "int32", "type": "integer" }, "type": { "description": "Tool type identifier", "enum": [ "web_search" ], "type": "string" }, "user_location": { "$ref": "#/components/schemas/ToolUserLocation", "description": "User's location for search personalization" } }, "required": [ "type" ], "type": "object", "title": "WebSearchTool" }, "FinanceSearchTool": { "description": "Finance search tool configuration for the Agent API", "properties": { "type": { "description": "Tool type identifier", "enum": [ "finance_search" ], "type": "string" } }, "required": [ "type" ], "type": "object", "title": "FinanceSearchTool" }, "FetchUrlTool": { "properties": { "max_urls": { "description": "Maximum number of URLs to fetch per tool call", "format": "int32", "maximum": 10, "minimum": 1, "type": "integer" }, "type": { "enum": [ "fetch_url" ], "type": "string" } }, "required": [ "type" ], "type": "object", "title": "FetchUrlTool" }, "WebSearchFilters": { "allOf": [ { "$ref": "#/components/schemas/SearchDomainFilter" }, { "$ref": "#/components/schemas/DateFilters" } ], "title": "WebSearchFilters" }, "SearchDomainFilter": { "properties": { "search_domain_filter": { "description": "Limit search results to specific domains (max 20)", "items": { "maxLength": 253, "type": "string" }, "maxItems": 20, "type": "array" } }, "type": "object", "title": "SearchDomainFilter" }, "DateFilters": { "properties": { "last_updated_after_filter": { "$ref": "#/components/schemas/Date", "description": "Return results updated after this date (MM/DD/YYYY)" }, "last_updated_before_filter": { "$ref": "#/components/schemas/Date", "description": "Return results updated before this date (MM/DD/YYYY)" }, "search_after_date_filter": { "$ref": "#/components/schemas/Date", "description": "Return results published after this date (MM/DD/YYYY)" }, "search_before_date_filter": { "$ref": "#/components/schemas/Date", "description": "Return results published before this date (MM/DD/YYYY)" }, "search_recency_filter": { "$ref": "#/components/schemas/SearchRecencyFilter", "description": "Filter by publication recency (hour/day/week/month/year)" } }, "type": "object", "title": "DateFilters" }, "Date": { "description": "Input: MM/DD/YYYY, Output: YYYY-MM-DD", "type": "string", "title": "Date" }, "SearchRecencyFilter": { "description": "Time-based recency filter for search results", "enum": [ "hour", "day", "week", "month", "year" ], "type": "string", "title": "SearchRecencyFilter" }, "ToolUserLocation": { "description": "User's geographic location for search personalization", "properties": { "city": { "description": "City name", "type": "string" }, "country": { "description": "ISO 3166-1 alpha-2 country code", "type": "string" }, "latitude": { "description": "Latitude coordinate", "format": "double", "type": "number" }, "longitude": { "description": "Longitude coordinate", "format": "double", "type": "number" }, "region": { "description": "State or region name", "type": "string" } }, "type": "object", "title": "ToolUserLocation" }, "ToolCallDetails": { "description": "Details about a tool call invocation", "properties": { "invocation": { "description": "Number of times this tool was invoked", "format": "int64", "type": "integer" } }, "type": "object", "title": "ToolCallDetails" }, "ResponseStreamEvent": { "description": "SSE stream event. Discriminate by the `type` field:\n- `response.created`: Initial response object\n- `response.in_progress`: Response processing started\n- `response.completed`: Final response with output\n- `response.failed`: Error occurred\n- `response.output_item.added`: New output item started\n- `response.output_item.done`: Output item completed\n- `response.output_text.delta`: Streaming text delta\n- `response.output_text.done`: Final text content\n- `response.reasoning.started`: Reasoning phase started\n- `response.reasoning.search_queries`: Search queries issued\n- `response.reasoning.search_results`: Search results received\n- `response.reasoning.fetch_url_queries`: URL fetch queries issued\n- `response.reasoning.fetch_url_results`: URL fetch results received\n- `response.reasoning.stopped`: Reasoning phase complete\n", "discriminator": { "mapping": { "response.completed": "#/components/schemas/ResponseCompletedEvent", "response.created": "#/components/schemas/ResponseCreatedEvent", "response.failed": "#/components/schemas/ResponseFailedEvent", "response.in_progress": "#/components/schemas/ResponseInProgressEvent", "response.output_item.added": "#/components/schemas/OutputItemAddedEvent", "response.output_item.done": "#/components/schemas/OutputItemDoneEvent", "response.output_text.delta": "#/components/schemas/TextDeltaEvent", "response.output_text.done": "#/components/schemas/TextDoneEvent", "response.reasoning.fetch_url_queries": "#/components/schemas/FetchUrlQueriesEvent", "response.reasoning.fetch_url_results": "#/components/schemas/FetchUrlResultsEvent", "response.reasoning.search_queries": "#/components/schemas/SearchQueriesEvent", "response.reasoning.search_results": "#/components/schemas/SearchResultsEvent", "response.reasoning.started": "#/components/schemas/ReasoningStartedEvent", "response.reasoning.stopped": "#/components/schemas/ReasoningStoppedEvent" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/ResponseCreatedEvent" }, { "$ref": "#/components/schemas/ResponseInProgressEvent" }, { "$ref": "#/components/schemas/ResponseCompletedEvent" }, { "$ref": "#/components/schemas/ResponseFailedEvent" }, { "$ref": "#/components/schemas/OutputItemAddedEvent" }, { "$ref": "#/components/schemas/OutputItemDoneEvent" }, { "$ref": "#/components/schemas/TextDeltaEvent" }, { "$ref": "#/components/schemas/TextDoneEvent" }, { "$ref": "#/components/schemas/ReasoningStartedEvent" }, { "$ref": "#/components/schemas/SearchQueriesEvent" }, { "$ref": "#/components/schemas/SearchResultsEvent" }, { "$ref": "#/components/schemas/FetchUrlQueriesEvent" }, { "$ref": "#/components/schemas/FetchUrlResultsEvent" }, { "$ref": "#/components/schemas/ReasoningStoppedEvent" } ], "title": "ResponseStreamEvent" }, "EventType": { "description": "SSE event type discriminator", "enum": [ "response.created", "response.in_progress", "response.completed", "response.failed", "response.output_item.added", "response.output_item.done", "response.output_text.delta", "response.output_text.done", "response.reasoning.started", "response.reasoning.search_queries", "response.reasoning.search_results", "response.reasoning.fetch_url_queries", "response.reasoning.fetch_url_results", "response.reasoning.stopped" ], "type": "string", "title": "EventType" }, "ResponseCreatedEvent": { "description": "Response created event (type: \"response.created\").\nContains the initial response object.\n", "properties": { "response": { "$ref": "#/components/schemas/ResponsesResponse" }, "sequence_number": { "description": "Monotonically increasing sequence number for event ordering", "format": "int64", "type": "integer" }, "type": { "$ref": "#/components/schemas/EventType" } }, "required": [ "type", "sequence_number" ], "type": "object", "title": "ResponseCreatedEvent" }, "ResponseInProgressEvent": { "description": "Response in progress event (type: \"response.in_progress\").\nEmitted when response processing has started.\n", "properties": { "response": { "$ref": "#/components/schemas/ResponsesResponse" }, "sequence_number": { "description": "Monotonically increasing sequence number for event ordering", "format": "int64", "type": "integer" }, "type": { "$ref": "#/components/schemas/EventType" } }, "required": [ "type", "sequence_number" ], "type": "object", "title": "ResponseInProgressEvent" }, "ResponseCompletedEvent": { "description": "Response event\nContains the full or partial response object.\n", "properties": { "response": { "$ref": "#/components/schemas/ResponsesResponse" }, "sequence_number": { "description": "Monotonically increasing sequence number for event ordering", "format": "int64", "type": "integer" }, "type": { "$ref": "#/components/schemas/EventType" } }, "required": [ "type", "sequence_number" ], "type": "object", "title": "ResponseCompletedEvent" }, "ResponseFailedEvent": { "description": "Response failed event (type: \"response.failed\").\nContains error details when streaming fails.\n", "properties": { "error": { "$ref": "#/components/schemas/ErrorInfo" }, "sequence_number": { "description": "Monotonically increasing sequence number for event ordering", "format": "int64", "type": "integer" }, "type": { "$ref": "#/components/schemas/EventType" } }, "required": [ "type", "sequence_number", "error" ], "type": "object", "title": "ResponseFailedEvent" }, "OutputItemAddedEvent": { "description": "Output item added event (type: \"response.output_item.added\").\nEmitted when a new output item (message or tool call) starts.\n", "properties": { "item": { "$ref": "#/components/schemas/OutputItem" }, "output_index": { "format": "int64", "type": "integer" }, "sequence_number": { "description": "Monotonically increasing sequence number for event ordering", "format": "int64", "type": "integer" }, "type": { "$ref": "#/components/schemas/EventType" } }, "required": [ "type", "sequence_number", "item", "output_index" ], "type": "object", "title": "OutputItemAddedEvent" }, "OutputItemDoneEvent": { "description": "Output item done event (type: \"response.output_item.done\").\nEmitted when an output item (message or tool call) completes.\n", "properties": { "item": { "$ref": "#/components/schemas/OutputItem" }, "output_index": { "format": "int64", "type": "integer" }, "sequence_number": { "description": "Monotonically increasing sequence number for event ordering", "format": "int64", "type": "integer" }, "type": { "$ref": "#/components/schemas/EventType" } }, "required": [ "type", "sequence_number", "item", "output_index" ], "type": "object", "title": "OutputItemDoneEvent" }, "TextDeltaEvent": { "description": "Text delta event (type: \"response.output_text.delta\").\nContains incremental text content.\n", "properties": { "content_index": { "format": "int64", "type": "integer" }, "delta": { "type": "string" }, "item_id": { "type": "string" }, "output_index": { "format": "int64", "type": "integer" }, "sequence_number": { "description": "Monotonically increasing sequence number for event ordering", "format": "int64", "type": "integer" }, "type": { "$ref": "#/components/schemas/EventType" } }, "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "delta" ], "type": "object", "title": "TextDeltaEvent" }, "TextDoneEvent": { "description": "Text done event (type: \"response.output_text.done\").\nContains the final text content.\n", "properties": { "content_index": { "format": "int64", "type": "integer" }, "item_id": { "type": "string" }, "output_index": { "format": "int64", "type": "integer" }, "sequence_number": { "description": "Monotonically increasing sequence number for event ordering", "format": "int64", "type": "integer" }, "text": { "type": "string" }, "type": { "$ref": "#/components/schemas/EventType" } }, "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "text" ], "type": "object", "title": "TextDoneEvent" }, "ReasoningStartedEvent": { "description": "Reasoning started event (type: \"response.reasoning.started\").\nSignals the model has started reasoning/searching.\n", "properties": { "sequence_number": { "description": "Monotonically increasing sequence number for event ordering", "format": "int64", "type": "integer" }, "thought": { "type": "string" }, "type": { "$ref": "#/components/schemas/EventType" } }, "required": [ "type", "sequence_number" ], "type": "object", "title": "ReasoningStartedEvent" }, "SearchQueriesEvent": { "description": "Search queries event (type: \"response.reasoning.search_queries\").\nContains search queries being executed.\n", "properties": { "queries": { "items": { "type": "string" }, "type": "array" }, "sequence_number": { "description": "Monotonically increasing sequence number for event ordering", "format": "int64", "type": "integer" }, "thought": { "type": "string" }, "type": { "$ref": "#/components/schemas/EventType" } }, "required": [ "type", "sequence_number", "queries" ], "type": "object", "title": "SearchQueriesEvent" }, "SearchResultsEvent": { "description": "Search results event (type: \"response.reasoning.search_results\").\nContains search results returned.\n", "properties": { "results": { "items": { "$ref": "#/components/schemas/SearchResult" }, "type": "array" }, "sequence_number": { "description": "Monotonically increasing sequence number for event ordering", "format": "int64", "type": "integer" }, "thought": { "type": "string" }, "type": { "$ref": "#/components/schemas/EventType" }, "usage": { "$ref": "#/components/schemas/ResponsesUsage" } }, "required": [ "type", "sequence_number", "results" ], "type": "object", "title": "SearchResultsEvent" }, "FetchUrlQueriesEvent": { "description": "URL fetch queries event (type: \"response.reasoning.fetch_url_queries\").\nContains URLs being fetched.\n", "properties": { "sequence_number": { "description": "Monotonically increasing sequence number for event ordering", "format": "int64", "type": "integer" }, "thought": { "type": "string" }, "type": { "$ref": "#/components/schemas/EventType" }, "urls": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "sequence_number", "urls" ], "type": "object", "title": "FetchUrlQueriesEvent" }, "FetchUrlResultsEvent": { "description": "URL fetch results event (type: \"response.reasoning.fetch_url_results\").\nContains fetched URL contents.\n", "properties": { "contents": { "items": { "$ref": "#/components/schemas/UrlContent" }, "type": "array" }, "sequence_number": { "description": "Monotonically increasing sequence number for event ordering", "format": "int64", "type": "integer" }, "thought": { "type": "string" }, "type": { "$ref": "#/components/schemas/EventType" } }, "required": [ "type", "sequence_number", "contents" ], "type": "object", "title": "FetchUrlResultsEvent" }, "ReasoningStoppedEvent": { "description": "Reasoning stopped event (type: \"response.reasoning.stopped\").\nSignals the model has finished reasoning/searching.\n", "properties": { "sequence_number": { "description": "Monotonically increasing sequence number for event ordering", "format": "int64", "type": "integer" }, "thought": { "type": "string" }, "type": { "$ref": "#/components/schemas/EventType" } }, "required": [ "type", "sequence_number" ], "type": "object", "title": "ReasoningStoppedEvent" }, "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" }, "FinanceSearchStepDetails": { "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": "FinanceSearchStepDetails", "description": "Finance search step details wrapper class" }, "EmbeddingsRequest": { "type": "object", "title": "Embeddings Request", "description": "Request body for creating embeddings", "required": [ "input", "model" ], "properties": { "input": { "title": "Input", "description": "Input text to embed, encoded as a string or array of strings. Maximum 512 texts per request. Each input must not exceed 32K tokens. All inputs in a single request must not exceed 120,000 tokens combined. Empty strings are not allowed.", "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 512 } ] }, "model": { "type": "string", "title": "Model", "description": "The embedding model to use", "enum": [ "pplx-embed-v1-0.6b", "pplx-embed-v1-4b" ] }, "dimensions": { "type": "integer", "title": "Dimensions", "description": "Number of dimensions for output embeddings (Matryoshka). Range: 128-1024 for pplx-embed-v1-0.6b, 128-2560 for pplx-embed-v1-4b. Defaults to full dimensions (1024 or 2560).", "minimum": 128, "maximum": 2560 }, "encoding_format": { "type": "string", "title": "Encoding Format", "description": "Output encoding format for embeddings. base64_int8 returns base64-encoded signed int8 values. base64_binary returns base64-encoded packed binary (1 bit per dimension).", "enum": [ "base64_int8", "base64_binary" ], "default": "base64_int8" } } }, "EmbeddingsResponse": { "type": "object", "title": "Embeddings Response", "description": "Response body for embeddings request", "properties": { "object": { "type": "string", "title": "Object", "description": "The object type", "example": "list" }, "data": { "type": "array", "title": "Data", "description": "List of embedding objects", "items": { "$ref": "#/components/schemas/EmbeddingObject" } }, "model": { "type": "string", "title": "Model", "description": "The model used to generate embeddings" }, "usage": { "$ref": "#/components/schemas/EmbeddingsUsage" } } }, "EmbeddingObject": { "type": "object", "title": "Embedding Object", "description": "A single embedding result", "properties": { "object": { "type": "string", "title": "Object", "description": "The object type", "example": "embedding" }, "index": { "type": "integer", "title": "Index", "description": "The index of the input text this embedding corresponds to" }, "embedding": { "type": "string", "title": "Embedding", "description": "Base64-encoded embedding vector. For base64_int8: decode to signed int8 array (length = dimensions). For base64_binary: decode to packed bits (length = dimensions / 8 bytes)." } } }, "EmbeddingsUsage": { "type": "object", "title": "Embeddings Usage", "description": "Token usage for the embeddings request", "properties": { "prompt_tokens": { "type": "integer", "title": "Prompt Tokens", "description": "Number of tokens in the input texts" }, "total_tokens": { "type": "integer", "title": "Total Tokens", "description": "Total number of tokens processed" }, "cost": { "type": "object", "title": "Cost", "description": "Cost breakdown for the request", "properties": { "input_cost": { "type": "number", "title": "Input Cost", "description": "Cost for input tokens in USD" }, "total_cost": { "type": "number", "title": "Total Cost", "description": "Total cost for the request in USD" }, "currency": { "type": "string", "title": "Currency", "description": "Currency of the cost values", "enum": [ "USD" ] } } } } }, "ContextualizedEmbeddingsRequest": { "type": "object", "title": "Contextualized Embeddings Request", "description": "Request body for creating contextualized embeddings", "required": [ "input", "model" ], "properties": { "input": { "type": "array", "title": "Input", "description": "Nested array structure where each inner array contains chunks from a single document. Chunks within the same document are encoded with document-level context awareness. Maximum 512 documents. Total chunks across all documents must not exceed 16,000. Total tokens per document must not exceed 32K. All chunks in a single request must not exceed 120,000 tokens combined. Empty strings are not allowed.", "items": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 }, "minItems": 1, "maxItems": 512 }, "model": { "type": "string", "title": "Model", "description": "The contextualized embedding model to use", "enum": [ "pplx-embed-context-v1-0.6b", "pplx-embed-context-v1-4b" ] }, "dimensions": { "type": "integer", "title": "Dimensions", "description": "Number of dimensions for output embeddings (Matryoshka). Range: 128-1024 for pplx-embed-context-v1-0.6b, 128-2560 for pplx-embed-context-v1-4b. Defaults to full dimensions (1024 or 2560).", "minimum": 128, "maximum": 2560 }, "encoding_format": { "type": "string", "title": "Encoding Format", "description": "Output encoding format for embeddings. base64_int8 returns base64-encoded signed int8 values. base64_binary returns base64-encoded packed binary (1 bit per dimension).", "enum": [ "base64_int8", "base64_binary" ], "default": "base64_int8" } } }, "ContextualizedEmbeddingsResponse": { "type": "object", "title": "Contextualized Embeddings Response", "description": "Response body for contextualized embeddings request", "properties": { "object": { "type": "string", "title": "Object", "description": "The object type", "example": "list" }, "data": { "type": "array", "title": "Data", "description": "List of contextualized embedding objects", "items": { "$ref": "#/components/schemas/ContextualizedEmbeddingObject" } }, "model": { "type": "string", "title": "Model", "description": "The model used to generate embeddings" }, "usage": { "$ref": "#/components/schemas/EmbeddingsUsage" } } }, "ContextualizedEmbeddingObject": { "type": "object", "title": "Contextualized Embedding Object", "description": "A single contextualized embedding result", "properties": { "object": { "type": "string", "title": "Object", "description": "The object type", "example": "list" }, "index": { "type": "integer", "title": "Index", "description": "The index of the document this chunk belongs to" }, "data": { "type": "array", "title": "Data", "description": "List of embedding objects for chunks in this document", "items": { "$ref": "#/components/schemas/EmbeddingObject" } } } }, "Model": { "type": "object", "description": "Represents a model available through the Agent API.", "properties": { "id": { "type": "string", "description": "The model identifier in `provider/model-name` format. Use this value as the `model` parameter in Agent API requests.", "example": "openai/gpt-5.4" }, "object": { "type": "string", "description": "The object type, which is always `model`.", "enum": [ "model" ], "example": "model" }, "created": { "type": "integer", "description": "The Unix timestamp (in seconds) when the model was created.", "example": 0 }, "owned_by": { "type": "string", "description": "The provider that owns the model (e.g. `openai`, `anthropic`, `google`, `perplexity`, `xai`, `nvidia`).", "example": "openai" } }, "required": [ "id", "object", "created", "owned_by" ] }, "ListModelsResponse": { "type": "object", "description": "Response from the List Models endpoint. Contains a list of available models.", "properties": { "object": { "type": "string", "description": "The object type, which is always `list`.", "enum": [ "list" ], "example": "list" }, "data": { "type": "array", "description": "A list of model objects.", "items": { "$ref": "#/components/schemas/Model" } } }, "required": [ "object", "data" ] } }, "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer" } } } }