{
  "openapi": "3.0.0",
  "info": {
    "title": "Perplexity Sonar API",
    "version": "1.0.0",
    "description": "Perplexity Sonar API — LLM with built-in web search. Returns AI-generated answers with citations from web sources."
  },
  "servers": [
    {
      "url": "https://api.aisa.one/apis/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "ChatCompletionRequest": {
        "type": "object",
        "required": [
          "model",
          "messages"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "The Sonar model to use.",
            "enum": [
              "sonar",
              "sonar-pro",
              "sonar-reasoning-pro",
              "sonar-deep-research"
            ]
          },
          "messages": {
            "type": "array",
            "description": "A list of messages comprising the conversation so far.",
            "items": {
              "type": "object",
              "required": [
                "role",
                "content"
              ],
              "properties": {
                "role": {
                  "type": "string",
                  "enum": [
                    "system",
                    "user",
                    "assistant"
                  ],
                  "description": "The role of the message author."
                },
                "content": {
                  "type": "string",
                  "description": "The content of the message."
                }
              }
            }
          },
          "max_tokens": {
            "type": "integer",
            "description": "The maximum number of tokens to generate in the response."
          },
          "temperature": {
            "type": "number",
            "description": "Sampling temperature between 0 and 2. Lower values make output more focused and deterministic.",
            "default": 0.2,
            "minimum": 0,
            "maximum": 2
          },
          "top_p": {
            "type": "number",
            "description": "Nucleus sampling parameter. The model considers tokens with top_p probability mass.",
            "default": 0.9,
            "minimum": 0,
            "maximum": 1
          },
          "top_k": {
            "type": "integer",
            "description": "The number of tokens to keep for top-k filtering.",
            "default": 0,
            "minimum": 0,
            "maximum": 2048
          },
          "stream": {
            "type": "boolean",
            "description": "Whether to stream the response using server-sent events.",
            "default": false
          },
          "search_context": {
            "type": "string",
            "description": "Controls how much search context to use. Affects per-request cost.",
            "enum": [
              "low",
              "medium",
              "high"
            ],
            "default": "low"
          },
          "frequency_penalty": {
            "type": "number",
            "description": "Penalizes new tokens based on their existing frequency in the text so far. Positive values decrease the likelihood of repeating the same line verbatim.",
            "default": 1,
            "minimum": 0,
            "maximum": 2
          },
          "presence_penalty": {
            "type": "number",
            "description": "Penalizes new tokens based on whether they appear in the text so far. Positive values increase the likelihood of talking about new topics.",
            "default": 0,
            "minimum": -2,
            "maximum": 2
          },
          "return_citations": {
            "type": "boolean",
            "description": "Whether to return citations and search results in the response.",
            "default": true
          },
          "search_recency_filter": {
            "type": "string",
            "description": "Filter search results by recency.",
            "enum": [
              "month",
              "week",
              "day",
              "hour"
            ]
          },
          "search_domain_filter": {
            "type": "array",
            "description": "Limit search to specific domains.",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "ChatCompletionResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the completion."
          },
          "model": {
            "type": "string",
            "description": "The model used for the completion."
          },
          "object": {
            "type": "string",
            "example": "chat.completion"
          },
          "created": {
            "type": "integer",
            "description": "Unix timestamp of when the completion was created."
          },
          "choices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": {
                  "type": "integer"
                },
                "message": {
                  "type": "object",
                  "properties": {
                    "role": {
                      "type": "string"
                    },
                    "content": {
                      "type": "string",
                      "description": "The AI-generated answer, with inline citation references like [1][2]."
                    }
                  }
                },
                "finish_reason": {
                  "type": "string",
                  "enum": [
                    "stop",
                    "length"
                  ]
                }
              }
            }
          },
          "citations": {
            "type": "array",
            "description": "List of source URLs referenced in the answer.",
            "items": {
              "type": "string"
            }
          },
          "search_results": {
            "type": "array",
            "description": "Detailed search results with titles, snippets, and URLs.",
            "items": {
              "type": "object",
              "properties": {
                "title": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "snippet": {
                  "type": "string"
                },
                "date": {
                  "type": "string"
                },
                "source": {
                  "type": "string"
                }
              }
            }
          },
          "usage": {
            "type": "object",
            "properties": {
              "prompt_tokens": {
                "type": "integer"
              },
              "completion_tokens": {
                "type": "integer"
              },
              "total_tokens": {
                "type": "integer"
              },
              "search_context_size": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/perplexity/sonar": {
      "post": {
        "x-aisa-pricing": {
          "model": "dynamic",
          "currency": "USD",
          "basis": "provider_cost x 2",
          "nominal_usd": 0.012,
          "observed_usd": {
            "min": 0.01,
            "p50": 0.012,
            "p95": 0.01282,
            "max": 0.25566
          },
          "cost_drivers": [
            {
              "param": "response size",
              "effect": "charge scales with provider response size"
            }
          ],
          "cost_tier": "variable",
          "note": "nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower"
        },
        "tags": [
          "Perplexity Sonar"
        ],
        "operationId": "post_perplexity_sonar",
        "summary": "Sonar — lightweight search + answer",
        "description": "Ask a question and get a written answer with web citations, rather than a list of links to read yourself. Body is OpenAI chat-completions shaped: `model` (required, `sonar`) and `messages`. Returns `choices[0].message.content` as prose, plus `citations` (an array of URL strings) and `search_results[]` with `title`, `url`, `snippet`, `date` and `source`, and a `usage` block. Measured at about 3 seconds. Billed at a flat $0.012 per request. This is the cheapest and fastest of the four Perplexity endpoints — use it for a single factual question. Step up to `post_perplexity_sonar_pro` for multi-part questions, or `post_perplexity_sonar_reasoning_pro` when the answer requires working through steps. If you need results you can iterate over rather than prose, use `post_tavily_search`; `post_exa_answer` answers the same shape of question with semantic retrieval, at $0.08.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatCompletionRequest"
              },
              "example": {
                "model": "sonar",
                "messages": [
                  {
                    "role": "user",
                    "content": "What are the latest developments in quantum computing?"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response with AI answer and citations",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatCompletionResponse"
                }
              }
            }
          }
        }
      }
    },
    "/perplexity/sonar-pro": {
      "post": {
        "x-aisa-pricing": {
          "model": "dynamic",
          "currency": "USD",
          "basis": "provider_cost x 2",
          "nominal_usd": 0.012,
          "observed_usd": {
            "min": 0.012,
            "p50": 0.012,
            "p95": 0.0682,
            "max": 0.22546
          },
          "cost_drivers": [
            {
              "param": "response size",
              "effect": "charge scales with provider response size"
            }
          ],
          "cost_tier": "variable",
          "note": "nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower"
        },
        "tags": [
          "Perplexity Sonar Pro"
        ],
        "operationId": "post_perplexity_sonar_pro",
        "summary": "Sonar Pro — advanced search for complex queries",
        "description": "Ask a question that needs more than one search pass and get a written answer with citations. Same request and response shape as `post_perplexity_sonar` — `model` (required, `sonar-pro`) and `messages` in, `choices[0].message.content`, `citations`, `search_results[]` and `usage` out. Measured at about 10 seconds, roughly three times `sonar`, for the same flat $0.012 per request. Use it for questions with several parts or follow-ups. For a single lookup `sonar` answers in a third of the time at the same price; when the difficulty is reasoning rather than retrieval, `post_perplexity_sonar_reasoning_pro` shows its working.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatCompletionRequest"
              },
              "example": {
                "model": "sonar-pro",
                "messages": [
                  {
                    "role": "user",
                    "content": "Compare the economic policies of the US and EU regarding AI regulation in 2025-2026"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response with AI answer and citations",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatCompletionResponse"
                }
              }
            }
          }
        }
      }
    },
    "/perplexity/sonar-reasoning-pro": {
      "post": {
        "x-aisa-pricing": {
          "model": "dynamic",
          "currency": "USD",
          "basis": "provider_cost x 2",
          "nominal_usd": 0.012,
          "observed_usd": {
            "min": 0.012,
            "p50": 0.01228,
            "p95": 0.06066,
            "max": 0.07052
          },
          "cost_drivers": [
            {
              "param": "response size",
              "effect": "charge scales with provider response size"
            }
          ],
          "cost_tier": "variable",
          "note": "nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower"
        },
        "tags": [
          "Perplexity Sonar Reasoning"
        ],
        "operationId": "post_perplexity_sonar_reasoning_pro",
        "summary": "Sonar Reasoning Pro — chain-of-thought reasoning with search",
        "description": "Ask a question that has to be worked through, not just looked up, and get a step-by-step answer backed by web search. Same shape as the other Perplexity endpoints — `model` (required, `sonar-reasoning-pro`) and `messages` in; `choices[0].message.content`, `citations`, `search_results[]` and `usage` out. Measured at about 5 seconds, flat $0.012 per request. Use it for comparison, causation and analysis. When the question is simply what is the case, `post_perplexity_sonar` is faster; when you need a long report over many sources rather than an answer, `post_perplexity_sonar_deep_research`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatCompletionRequest"
              },
              "example": {
                "model": "sonar-reasoning-pro",
                "messages": [
                  {
                    "role": "user",
                    "content": "Analyze whether Tesla stock is overvalued based on current P/E ratio compared to industry averages"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response with AI answer and citations",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatCompletionResponse"
                }
              }
            }
          }
        }
      }
    },
    "/perplexity/sonar-deep-research": {
      "post": {
        "x-aisa-pricing": {
          "model": "dynamic",
          "currency": "USD",
          "basis": "provider_cost x 2",
          "nominal_usd": 0.012,
          "observed_usd": {
            "min": 0.01004,
            "p50": 0.012,
            "p95": 1.72686,
            "max": 1.72686
          },
          "cost_drivers": [
            {
              "param": "response size",
              "effect": "charge scales with provider response size"
            }
          ],
          "cost_tier": "variable",
          "note": "nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower"
        },
        "tags": [
          "Perplexity Deep Research"
        ],
        "operationId": "post_perplexity_sonar_deep_research",
        "summary": "Sonar Deep Research — exhaustive research & comprehensive reports",
        "description": "Commission a report: this endpoint runs many searches and writes a long, cited document. `model` (required, `sonar-deep-research`) and `messages` in; `choices[0].message.content`, `citations`, `search_results[]` and `usage` out, where `usage` also reports `num_search_queries` and `reasoning_tokens`. ⚠️ Budget for the wait: a two-sentence question measured **192 seconds** and returned 86 KB after 10 upstream searches — roughly 60 times slower and 10 times larger than `post_perplexity_sonar`, at the same flat $0.012 per request. Many clients time out well before it answers, so call it only when a report is genuinely the deliverable, and never in a loop. For anything you would read in one sitting, the other three Perplexity endpoints answer in seconds.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatCompletionRequest"
              },
              "example": {
                "model": "sonar-deep-research",
                "messages": [
                  {
                    "role": "user",
                    "content": "Write a comprehensive analysis of the global semiconductor supply chain risks in 2026"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response with AI answer and citations",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatCompletionResponse"
                }
              }
            }
          }
        }
      }
    }
  }
}