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

[willtwilson]

Context

The v1.12.1 release replaced the \ocusMode\ parameter with \sources\ in the API endpoints. This is a breaking change with no migration documentation — existing integrations that pass \ocusMode\ get no error, but search does not work as expected because no sources are activated.

I discovered this while building an integration and had to read the source code to understand why web search had stopped working after upgrading.

Changes

Added to \docs/API/SEARCH.md:

• Migration guide with \ocusMode\ → \sources\ mapping table (e.g., \ocusMode: 'webSearch'\ → \sources: ['web'])
• Internal /api/chat\ endpoint documentation — request body parameters, NDJSON response event types, and JSON Patch accumulation pattern. This is documented as an internal API with a note to prefer /api/search\ for integrations.

Impact

This helps:

• Developers upgrading from pre-v1.12.1 who are wondering why search stopped working
• Integration authors who need to understand the /api/chat\ streaming format
• Anyone building MCP servers, browser extensions, or other tools on top of Perplexica

---

Summary by cubic

Documents the v1.12.1 change replacing focusMode with sources, adds a migration guide, and updates internal /api/chat streaming docs (NDJSON events, JSON Patch, block.data). Clarifies endpoint behavior: /api/chat returns 200 with LLM-only output when sources is omitted, while /api/search returns 400; prefer /api/search.

• Migration
  • Replace "focusMode": "webSearch" with "sources": ["web"], and "academicSearch" with ["academic"].
  • /api/chat strips focusMode (defaults sources to []); /api/search rejects it. Update to sources and set systemInstructions as string | null.

^{Written for commit 77f0099. Summary will update on new commits.}

[cubic-dev-ai]

No issues found across 1 file

[Copilot]

Pull request overview

Adds missing migration and internal streaming endpoint documentation to help integrators understand the v1.12.1 breaking API change and the /api/chat NDJSON stream format.

Changes:

• Document focusMode → sources migration for v1.12.1+.
• Add internal /api/chat endpoint request body and streaming event documentation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

For the /api/chat stream, block events include the full block object (e.g., { id, type, data: ... }), not just { id, type }. Documenting only id/type can mislead clients that need the block’s data payload (text chunks, widget params, research substeps, etc.). Please update the event schema description accordingly.

Suggested change

	| `block` | New content block created | `block: { id, type }` |
	| `block` | New content block created | `block` (full block object, e.g. `{ id, type, data, ... }`) |

[willtwilson]

Fixed in follow-up commit (77f0099) — updated the block event description to include the full block object shape including the data payload, which is the most important field for clients assembling streamed content. Thanks for the clarification.

[Copilot]

systemInstructions can be null in the /api/chat request body (the server schema accepts string | null). The docs currently list it as string only; please update the type/description so client implementations don’t fail strict validation when sending/receiving nulls.

Suggested change

	| `systemInstructions` | string | No | Custom instructions for the AI |
	| `systemInstructions` | string \| null | No | Custom instructions for the AI (may be `null` or omitted if not used) |

[willtwilson]

Fixed in follow-up commit (77f0099) — updated the type to string | null to match the server's Zod schema. Good catch.

[Copilot]

The note that focusMode is “silently ignored” is not accurate for /api/search: the handler returns a 400 when sources is missing (Missing sources or query). This silent-ignore behavior seems specific to /api/chat (Zod strips unknown keys and defaults sources to []). Please adjust the migration text to distinguish between /api/search vs /api/chat behavior so integrators know what to expect.

Suggested change

If you pass `focusMode` to v1.12.1+, it is silently ignored and no sources will be searched. Update your API calls to use `sources` instead.

For v1.12.1+ you must migrate to `sources`. On `/api/chat`, any `focusMode` value is ignored (Zod strips the field and defaults `sources` to `[]`, so no sources are searched). On `/api/search`, `focusMode` is not accepted as a replacement for `sources`: if you omit `sources` (even when sending `focusMode`), the request will fail with a 400 error such as `Missing sources or query`. Update your API calls to always send `sources` instead of `focusMode`.

[willtwilson]

Good catch — this was genuinely wrong. Fixed in the follow-up commit (77f0099). The updated text now correctly distinguishes the two failure modes: on /api/chat, Zod strips focusMode and defaults sources to [] (silent, no web data returned); on /api/search, omitting sources returns HTTP 400 Missing sources or query. Thanks for reading the source code to verify — I had only tested via /api/chat.