Skip to content

docs: document sources API parameter and focusMode deprecation (v1.12.1) #1043

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
willtwilson wants to merge 2 commits into
base: master
Choose a base branch
from
Open

docs: document sources API parameter and focusMode deprecation (v1.12.1) #1043

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4d4b8e4
docs: document sources API parameter and focusMode deprecation
willtwilson Mar 8, 2026
77f0099
docs: fix focusMode silent-ignore accuracy, systemInstructions type, …
willtwilson Mar 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 90 additions & 0 deletions docs/API/SEARCH.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,27 @@

Perplexica’s Search API makes it easy to use our AI-powered search engine. You can run different types of searches, pick the models you want to use, and get the most recent info. Follow the following headings to learn more about Perplexica's search API.

## ⚠️ Migration Guide

### v1.12.1: `focusMode` replaced by `sources`

The `focusMode` parameter has been removed from all API endpoints and replaced with `sources`.

| Before (v1.12.0 and earlier) | After (v1.12.1+) |
|------------------------------|-------------------|
| `"focusMode": "webSearch"` | `"sources": ["web"]` |
| `"focusMode": "academicSearch"` | `"sources": ["academic"]` |

> **⚠️ Breaking change in v1.12.1:** The `focusMode` parameter has been removed.
> Replace `focusMode: "webSearch"` with `sources: ["web"]` in all integrations.
>
> **Behaviour by endpoint:**
> - `/api/chat` — `focusMode` is stripped by Zod schema validation and `sources`
> defaults to `[]`. No error is returned, but no sources are searched. Queries
> appear to work but return LLM-only answers with no web data.
> - `/api/search` — `focusMode` is not accepted. Sending `focusMode` without `sources`
> returns **HTTP 400** `Missing sources or query`.

## Endpoints

### Get Available Providers and Models
Expand Down Expand Up @@ -188,3 +209,72 @@ If an error occurs during the search process, the API will return an appropriate

- **400**: If the request is malformed or missing required fields (e.g., no `sources` or `query`).
- **500**: If an internal server error occurs during the search.

---

## Internal Chat API

The `/api/chat` endpoint is the internal streaming API used by Perplexica's frontend. It uses a different request/response format from `/api/search` and is documented here for integration developers.

> **Note**: For most integrations, prefer `/api/search` above. The `/api/chat` endpoint is designed for Perplexica's UI and may change between versions.

### **POST** `/api/chat`

**Full URL**: `http://localhost:3000/api/chat`

#### Request Body Structure

```json
{
"message": {
"messageId": "msg-123",
"chatId": "chat-456",
"content": "What is Perplexica?"
},
"chatModel": {
"providerId": "550e8400-e29b-41d4-a716-446655440000",
"key": "gpt-4o-mini"
},
"embeddingModel": {
"providerId": "550e8400-e29b-41d4-a716-446655440000",
"key": "text-embedding-3-large"
},
"sources": ["web"],
"optimizationMode": "balanced",
"history": [
["human", "Hi"],
["assistant", "Hello! How can I help?"]
],
"files": [],
"systemInstructions": ""
}
```

#### Request Parameters

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `message` | object | ✅ | `{ messageId, chatId, content }` — message identifiers and query text |
| `chatModel` | object | ✅ | `{ providerId, key }` — chat model to use (from `/api/providers`) |
| `embeddingModel` | object | ✅ | `{ providerId, key }` — embedding model (from `/api/providers`) |
| `sources` | string[] | No | Sources to search: `"web"`, `"academic"`, `"discussions"`. Default: `[]` |
| `optimizationMode` | string | ✅ | `"speed"`, `"balanced"`, or `"quality"` |
| `history` | array | No | Previous conversation as `["human"/"assistant", "text"]` tuples |
| `files` | string[] | No | Uploaded file IDs to include in search context |
| `systemInstructions` | string \| null | No | Custom instructions for the AI (may be null or omitted) |

#### Response Format

The response is an NDJSON (newline-delimited JSON) stream with `Content-Type: text/event-stream`. Each line is a complete JSON object.

Event types:

| Type | Description | Fields |
|------|-------------|--------|
| `block` | New content block created | `block` (full block object, e.g. `{ id, type, data, ... }`) |
| `updateBlock` | Incremental update to a block | `blockId, patch` (JSON Patch array) |
| `researchComplete` | Search/research phase finished | — |
| `messageEnd` | Stream complete | — |
| `error` | Error occurred | `data` (error message) |

The `updateBlock` events use [JSON Patch](https://jsonpatch.com/) format. To get the final answer text, look for `patch` entries with `op: "replace"` and `path: "/data"` — the `value` field contains the cumulative text for that block.