SearXNG
Normalized JSON search through a trusted, operator-selected SearXNG instance.
On this page
Choose your instance
SearXNG is metasearch software rather than a single hosted API. Configure the HTTPS baseUrl of an instance you trust on your server. The adapter appends /search and sends a form-encoded POST requesting JSON, page one, and the general category by default. It does not discover or select public instances.
import { createSearch } from '@belweave/search-sdk';
import { searxng } from '@belweave/search-sdk/searxng';
const baseUrl = process.env.SEARXNG_BASE_URL;
if (!baseUrl) throw new Error('SEARXNG_BASE_URL is required');
const client = createSearch({
provider: searxng({ baseUrl }),
timeoutMs: 10_000,
});
const response = await client.web.search({
query: 'SQLite write concurrency',
limit: 5,
});
console.log(response.results, response.warnings);JSON output must be enabled by the instance operator. SearXNG documents a 403 response when a requested format is disabled, including on many public instances. Search engines, access requirements, and availability depend on the selected instance.
Instance settings
| Option | Behavior |
|---|---|
baseUrl | Required trusted HTTPS instance URL; optional base path, no embedded credentials, query, or fragment. |
headers | Optional server-owned reverse-proxy authentication headers; no standard SearXNG search API key. |
language | Instance-supported language selection. |
safeSearch | 0, 1, or 2; engine-dependent behavior. |
timeRange | day, month, or year; engine-dependent behavior. |
categories | Instance-specific category names; defaults to general. |
fetch | Optional trusted transport for tests or server networking policy. |
The selected URL is a server configuration boundary. Never take baseUrl or authentication headers directly from an untrusted caller. Requests reject redirects. Domain filters are unsupported: the SDK does not rewrite queries into engine-dependent site operators.
Keep metasearch semantics visible
- One response page is read. limit caps normalized output and does not request extra pages.
- Content maps to snippet and a supplied score stays native. Unreported usage is null.
- Unresponsive engines produce a sanitized provider_warning when reported. A valid source list can be partial.
- Provider text remains untrusted, including any markup in content.
For engine attribution, dates, suggestions, or unresponsive-engine details, call the adapter's searchRaw(request, { signal }) method. It returns { provider, retrievedAt, data }; validate unknown raw fields before use. Direct raw calls do not apply createSearch reliability policies; the HTTP transport retains its own resource bounds.
Coverage and verification
This is a normalized adapter with raw JSON access, without a generated native client. Fixture validation does not establish a particular instance's access, engine configuration, privacy policy, or availability.