Filter by domain

Request hostnames#

import { createSearch } from '@belweave/search-sdk';
import { createMockProvider } from '@belweave/search-sdk/testing';

const client = createSearch({ provider: createMockProvider() });
const response = await client.web.search({
  query: 'search API reference',
  limit: 3,
  includeDomains: ['example.org'],
  excludeDomains: ['excluded.example.org'],
});

console.log(response.results); // Mock hostname filtering; no live search

Use ASCII hostnames or punycode. Schemes, paths, ports, wildcards, and empty lists are rejected. The SDK lowercases and deduplicates hosts. The same normalized host cannot appear in both lists.

Check provider capacity#

Every provider in a configured fallback chain must support the requested filters and capacity before any network dispatch. A Brave fallback makes a filtered request unsupported even when the primary supports it. A provider declaring mutuallyExclusiveDomainFilters rejects simultaneous lists before dispatch.

Keep matching semantics explicit#

Built-in adapters forward native filter options. They do not rewrite the query into site: operators or remove provider results locally. Root-domain and subdomain behavior remains provider-specific; do not infer exact-host matching from the SDK's hostname syntax.

• Request validation reference↗
• Provider capability reference↗