Skip to content
unlob
Get an API key

unlob for Vercel AI SDK

A tool definition, a Zod schema and one fetch. Works with any model provider the SDK supports, which is the point — retrieval stays yours when the model changes.

app/tools/unlob.tstypescript
import { tool } from 'ai';
import { z } from 'zod';

const BASE = 'https://api.unlob.com';
const headers = { 'x-api-key': process.env.UNLOB_API_KEY! };

export const webSearch = tool({
  description:
    'Search the web. Returns metadata-only hits — url, host, title, snippet — never page bodies.',
  parameters: z.object({
    query: z.string().describe('Boolean query. Supports AND, OR, -negation, "phrases".'),
    limit: z.number().min(1).max(20).default(8),
  }),
  execute: async ({ query, limit }) => {
    const url = new URL('/search', BASE);
    url.searchParams.set('q', query);
    url.searchParams.set('limit', String(limit));
    // Pinned server-side: the model should not be choosing these.
    url.searchParams.set('collapse', 'story');
    url.searchParams.set('min_independent_sources', '2');

    const res = await fetch(url, { headers });
    if (!res.ok) throw new Error(`unlob: ${res.status}`);
    const { results } = await res.json();
    return results;
  },
});

Setup

  1. Get an API key

    10,000 free requests a month.

  2. Define the tool

    A Zod schema for what the model may set, and a fetch for the rest. Keep the key server-side.

  3. Pin your filters

    Expose query and limit to the model; set collapse and corroboration thresholds yourself.

  4. Stream as usual

    Metadata-only results are small, which keeps tool round-trips fast in a streaming UI.

Worth knowing

  • Never expose the API key to the browser — keep the tool in a server route or server action.
  • A tight Zod schema is a feature: the fewer parameters the model can set, the fewer ways retrieval can go wrong.

Frequently asked questions

Can I call unlob from the browser?

No — that would expose your API key. Call it from a server route, a server action or an edge function.

Get a key and connect it

10,000 requests a month, no card. The config above works unchanged once you have a key.

Get your API keyAPI reference