Marginalia

env var

MARGINALIA_API_KEY

auth

API-Key header

operations

search

results

10, up to 100

Marginalia indexes its own crawl and leans toward personal sites, blogs and plain HTML documentation. Ask it about "rust async" and the top hits are fasterthanli.me and a couple of personal blogs, not the usual content farms. Worth having next to a Google style provider, because it finds different pages.

Address it

import { create } from "@agntn/web";

const marginalia = await create("marginalia"); // MARGINALIA_API_KEY, or the shared "public" key
const results = await marginalia.search("rust async", { maxResults: 20 });

The key goes in the API-Key header on api2.marginalia-search.com. Without MARGINALIA_API_KEY the adapter sends public, the key Marginalia hands out for trying the API.

When does it run without a key?

Only when you ask for it by name, create("marginalia") or --provider marginalia. Automatic selection and provider: "all" skip it until MARGINALIA_API_KEY is set, so nobody's queries start going to a new host just because they upgraded. With the key set it joins the detection order right after Mojeek.

What it reads

What comes back

url, title and snippet, nothing else. Marginalia's answer also has a ranking number, a document format and a count of hits per domain, and all three are left out, so the agent does not pay tokens for them. Paging works through page. No domain filters, no date bounds, no categories. A search that asks for them gets them back in ignoredFilters.

Gotchas

• The public key has one quota per minute, shared by everybody who uses it. Two calls in a row can already get 429 QPM Limit Exceeded, which comes back as a RateLimitError and moves the fallback chain on.
• Results under a free key are licensed CC-BY-NC-SA 4.0. A free key of your own comes by email to Marginalia, commercial use needs a paid key.
• count goes up to 100, a bigger maxResults is clamped to that.
• The answer says how many pages there are and the page after the last one comes back empty, so the continuation stops at pages.

Where it lives

src/providers/marginalia.ts.