Search endpoint

Execute AI-powered searches with customizable sources and models

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

POST /api/search

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.

Show properties

providerId · string · required

The UUID of the provider. You can get this from the /api/providers endpoint response.

key · string · required

The model key/identifier (e.g., gpt-4o-mini, llama3.1:latest). Use the key value from the provider’s chatModels array, not the display name.

embeddingModel · object · required

Defines the embedding model for similarity-based searching. Get available providers and models from the /api/providers endpoint.

Show properties

providerId · string · required

The UUID of the embedding provider. You can get this from the /api/providers endpoint response.

key · string · required

The embedding model key (e.g., text-embedding-3-large, nomic-embed-text). Use the key value from the provider’s embeddingModels array, not the display name.

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.

Show source object

content · string

A snippet of the relevant content from the source.

metadata · object

Show properties

title · string

The title of the webpage.

url · string

The URL of the webpage.

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

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

Standard response

{
  "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.