> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ItzCrazyKns/Perplexica/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<CodeGroup>
  ```bash POST /api/search theme={null}
  http://localhost:3000/api/search
  ```
</CodeGroup>

<Note>Replace `localhost:3000` with your Perplexica instance URL if running on a different host or port.</Note>

## Request body

<ParamField body="chatModel" type="object" required>
  Defines the chat model to be used for the query. Get available providers and models from the `/api/providers` endpoint.

  <Expandable title="properties">
    <ParamField body="providerId" type="string" required>
      The UUID of the provider. You can get this from the `/api/providers` endpoint response.
    </ParamField>

    <ParamField body="key" type="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.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="embeddingModel" type="object" required>
  Defines the embedding model for similarity-based searching. Get available providers and models from the `/api/providers` endpoint.

  <Expandable title="properties">
    <ParamField body="providerId" type="string" required>
      The UUID of the embedding provider. You can get this from the `/api/providers` endpoint response.
    </ParamField>

    <ParamField body="key" type="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.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="sources" type="array" required>
  Which search sources to enable. Available values: `web`, `academic`, `discussions`.
</ParamField>

<ParamField body="query" type="string" required>
  The search query or question.
</ParamField>

<ParamField body="optimizationMode" type="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)
</ParamField>

<ParamField body="history" type="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:

  ```json theme={null}
  [
    ["human", "What is Perplexica?"],
    ["assistant", "Perplexica is an AI-powered search engine..."]
  ]
  ```
</ParamField>

<ParamField body="systemInstructions" type="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.
</ParamField>

<ParamField body="stream" type="boolean" default={false}>
  When set to `true`, enables streaming responses using Server-Sent Events (SSE).
</ParamField>

## Response

### Standard response (stream: false)

<ResponseField name="message" type="string">
  The search result, generated based on the query and enabled sources.
</ResponseField>

<ResponseField name="sources" type="array">
  A list of sources that were used to generate the search result.

  <Expandable title="source object">
    <ResponseField name="content" type="string">
      A snippet of the relevant content from the source.
    </ResponseField>

    <ResponseField name="metadata" type="object">
      <Expandable title="properties">
        <ResponseField name="title" type="string">
          The title of the webpage.
        </ResponseField>

        <ResponseField name="url" type="string">
          The URL of the webpage.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### 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

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('http://localhost:3000/api/search', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      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
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'http://localhost:3000/api/search',
      json={
          '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
      }
  )

  data = response.json()
  print(data)
  ```
</CodeGroup>

## Response example

<CodeGroup>
  ```json Standard response theme={null}
  {
    "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"
        }
      }
    ]
  }
  ```

  ```json Streaming response theme={null}
  {"type":"init","data":"Stream connected"}
  {"type":"sources","data":[{"content":"...","metadata":{"title":"...","url":"..."}}]}
  {"type":"response","data":"Perplexica is an "}
  {"type":"response","data":"innovative, open-source "}
  {"type":"response","data":"AI-powered search engine..."}
  {"type":"done"}
  ```
</CodeGroup>

<Warning>
  The `providerId` must be a valid UUID obtained from the `/api/providers` endpoint. The example UUID shown is for demonstration purposes only.
</Warning>

## Error responses

<ResponseField name="400" type="Bad Request">
  Returned if the request is malformed or missing required fields (e.g., no `sources` or `query`).
</ResponseField>

<ResponseField name="500" type="Internal Server Error">
  Returned if an internal server error occurs during the search.
</ResponseField>