# SearXNG

Normalized JSON search through a trusted, operator-selected SearXNG instance.

Canonical: https://searchsdk.dev/docs/providers/searxng
Markdown: https://searchsdk.dev/docs/providers/searxng.md

<a id="overview"></a>

## Choose your instance

> **TypeScript reference**
> The API names, code and policy behavior in this article describe the TypeScript SDK. See [your language guide](https://searchsdk.dev/docs/sdks) for its supported surface and limits.

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.

**searxng-search.ts · server**

```typescript
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.

<a id="settings"></a>

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

<a id="results"></a>

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

<a id="boundaries"></a>

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

- [Official SearXNG Search API](https://docs.searxng.org/dev/search_api.html)
- [Server integration guide](https://searchsdk.dev/docs/guides/server-integration)
- [All providers](https://searchsdk.dev/docs/providers)