Your first search

Try without credentials#

Install the alpha package. Save the following example as first-search.mjs in your server application, then run node first-search.mjs on Node 24. It uses plain ESM JavaScript and needs no compiler. For an immediate browser demo, open the playground and choose “Demo · no key”.

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

const provider = createMockProvider();
const client = createSearch({ provider });
const response = await client.web.search({ query: 'SQLite concurrency' });

console.log(response.results); // Fixed example-domain fixtures
console.log(provider.calls.length); // 1; no network requests

The mock returns three fixed example-domain results and performs no outbound requests. This validates your application integration, not a provider's retrieval quality.

Connect Context.dev#

Save this example as search.mjs. Configure CONTEXT_API_KEY in a server-only environment or local .env file, then run node --env-file=.env search.mjs. With a production-injected environment, use node search.mjs. This makes a real provider request and may incur charges.

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

const apiKey = process.env.CONTEXT_API_KEY;
if (!apiKey) throw new Error('CONTEXT_API_KEY is required');

const client = createSearch({
  provider: context({ apiKey }),
  timeoutMs: 10_000,
});

const response = await client.web.search({
  query: 'SQLite write concurrency',
  limit: 5,
});

for (const result of response.results) {
  console.log(result.title ?? result.url, result.url);
}
console.log(response.provider, response.attempts);

The same ESM example can be saved as search.ts and run directly with Node 24 in a type: module project. Missing, blank, or invalid keys must be resolved through your provider account. A configured factory is not proof that the key is valid.

Read the response#

• results contains up to your requested limit in provider order.
• provider identifies the winning provider. Every result also has its own provenance.
• attempts records successes and failures. warnings uses stable SDK codes.
• usage is provider-reported usage from the winner, or null when unknown.

Add one policy at a time#

• Filter by domain↗
• Configure explicit fallback↗
• Connect a different provider↗