# SearchProvider

The normalized adapter interface, capability descriptor, and trust boundary.

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

<a id="interface"></a>

## Interface

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

**TypeScript · abbreviated**

```typescript
import type {
  ProviderResponse, ValidatedSearchRequest,
} from '@belweave/search-sdk';

interface SearchProvider {
  readonly id: string;
  readonly capabilities: {
    readonly domainFilters: boolean;
    readonly mutuallyExclusiveDomainFilters?: boolean;
    readonly maxIncludeDomains: number;
    readonly maxExcludeDomains: number;
    readonly maxQueryLength?: number;
  };
  search(
    request: ValidatedSearchRequest,
    options: { signal: AbortSignal },
  ): Promise<ProviderResponse>;
}
```

<a id="capabilities"></a>

## Declare capabilities truthfully

The orchestrator checks capabilities across the entire fallback chain before dispatch. Capacities are nonnegative integers. An optional `maxQueryLength` must be a positive integer and is measured in UTF-16 code units. Context declares a ceiling of 500. IDs must be 1–64 ASCII letters, digits, hyphens, or underscores.

<a id="trust"></a>

## Custom implementations are trusted code

A custom provider must return the normalized response shape, assign truthful provenance, honor its advertised capabilities, and observe the signal where possible. The orchestrator validates response fields and applies deadlines, fallback policy, and result ceilings. It cannot verify the truth of supplied attribution.

Most hosted adapter options are `{ apiKey, fetch? }`; Valyu adds typed search settings, and SearXNG uses an operator-selected instance. Injected fetch has the shape `(input: string | URL, init?: RequestInit) => Promise<Response>` and is useful for controlled fixtures and server networking policy.