Skip to main content
The search endpoint is the main API for performing searches in Perplexica. It allows you to execute queries with different sources, models, and optimization modes.

​
Endpoint

http://localhost:3000/api/search
Replace localhost:3000 with your Perplexica instance URL if running on a different host or port.

​
Request body

​
chatModel
object
required
Defines the chat model to be used for the query. Get available providers and models from the /api/providers endpoint.
​
embeddingModel
object
required
Defines the embedding model for similarity-based searching. Get available providers and models from the /api/providers endpoint.
​
sources
array
required
Which search sources to enable. Available values: web, academic, discussions.
​
query
string
required
The search query or question.
​
optimizationMode
string
default:"speed"
Specifies the optimization mode to control the balance between performance and quality.Available modes:
  • speed: Prioritize speed and return the fastest answer
  • balanced: Provide a balanced answer with good speed and reasonable quality
  • quality: Prioritize answer quality (may be slower)
​
history
array
An array of message pairs representing the conversation history. Each pair consists of a role (either human or assistant) and the message content. This allows the system to use the context of the conversation to refine results.Example:
[
  ["human", "What is Perplexica?"],
  ["assistant", "Perplexica is an AI-powered search engine..."]
]
​
systemInstructions
string
Custom instructions provided by the user to guide the AI’s response. These instructions are treated as user preferences and have lower priority than the system’s core instructions. For example, you can specify a particular writing style, format, or focus area.
​
stream
boolean
default:false
When set to true, enables streaming responses using Server-Sent Events (SSE).

​
Response

​
Standard response (stream: false)

​
message
string
The search result, generated based on the query and enabled sources.
​
sources
array
A list of sources that were used to generate the search result.

​
Streaming response (stream: true)

When streaming is enabled, the API returns a stream of newline-delimited JSON objects using Server-Sent Events (SSE). Each line contains a complete, valid JSON object. The response has Content-Type: text/event-stream. The different message types include:
  • init: Initial connection message
  • sources: All sources used for the response
  • response: Chunks of the generated answer text
  • done: Indicates the stream is complete

​
Request example

curl -X POST http://localhost:3000/api/search \
  -H "Content-Type: application/json" \
  -d '{
    "chatModel": {
      "providerId": "550e8400-e29b-41d4-a716-446655440000",
      "key": "gpt-4o-mini"
    },
    "embeddingModel": {
      "providerId": "550e8400-e29b-41d4-a716-446655440000",
      "key": "text-embedding-3-large"
    },
    "optimizationMode": "speed",
    "sources": ["web"],
    "query": "What is Perplexica",
    "stream": false
  }'

​
Response example

{
  "message": "Perplexica is an innovative, open-source AI-powered search engine designed to enhance the way users search for information online. Here are some key features and characteristics of Perplexica:\n\n- **AI-Powered Technology**: It utilizes advanced machine learning algorithms to not only retrieve information but also to understand the context and intent behind user queries, providing more relevant results [1][5].\n\n- **Open-Source**: Being open-source, Perplexica offers flexibility and transparency, allowing users to explore its functionalities without the constraints of proprietary software [3][10].",
  "sources": [
    {
      "content": "Perplexica is an innovative, open-source AI-powered search engine designed to enhance the way users search for information online.",
      "metadata": {
        "title": "What is Perplexica, and how does it function as an AI-powered search ...",
        "url": "https://askai.glarity.app/search/What-is-Perplexica--and-how-does-it-function-as-an-AI-powered-search-engine"
      }
    },
    {
      "content": "Perplexica is an open-source AI-powered search tool that dives deep into the internet to find precise answers.",
      "metadata": {
        "title": "Sahar Mor's Post",
        "url": "https://www.linkedin.com/posts/sahar-mor_a-new-open-source-project-called-perplexica-activity-7204489745668694016-ncja"
      }
    }
  ]
}
The providerId must be a valid UUID obtained from the /api/providers endpoint. The example UUID shown is for demonstration purposes only.

​
Error responses

​
400
Bad Request
Returned if the request is malformed or missing required fields (e.g., no sources or query).
​
500
Internal Server Error
Returned if an internal server error occurs during the search.

Build docs developers (and LLMs) love

Get started for freeTalk to us