Skip to content
naulon
Get started
docs

The catalog endpoint

The credits API tells the toll who to pay for one article. The catalog endpoint tells the fleet which articles you have at all, so an AI buyer searching the directory can find yours and pay to read them. It is optional. Without it your articles are still tolled the moment an agent reads one; with it they also show up in the fleet directory and in agent search before anyone has read them.

It is read-only, it holds no money, and like the credits API it only ever lists the teaser, never the article body.

The request

GET https://your-site.example/catalog

/catalog or /api/catalog are the paths we probe when you turn on fleet discovery; you can also point us at any URL you like. The buyer may pass a search term as ?q= and a page cursor as ?cursor=. Both are optional; a bare GET returns your whole catalog.

The route should be public and cacheable. It is polled on an interval, not per read, so a few minutes of caching (ISR, a CDN, Cache-Control) is plenty, and that caching is what makes the poll cheap, because the crawl fetches your catalog unconditionally. It sends no If-None-Match, so an ETag on your side will not turn a poll into a 304; serve the route from a cache and the repeat cost is a cache hit either way.

The response

Return a JSON array of entries:

[
  {
    "slug": "the-river-and-the-name",
    "title": "The River and the Name",
    "summary": "Identity, change, and whether a thing survives its own renaming.",
    "url": "https://your-site.example/essays/the-river-and-the-name",
    "authors": ["Ada Lorne"],
    "publishedAt": "2026-05-01T09:00:00Z"
  }
]

Only two fields matter: a slug or a url we can derive the toll slug from, and a title. Everything else is optional:

  • summary: a one-line teaser, shown in the directory. This is a public teaser, the same boundary as your RSS feed: never put the article body here.
  • url: the article's canonical URL. Send it and buyers pay that exact URL; omit it and we reconstruct one from your slug, which can miss a custom path.
  • authors: bylines as strings (or { "name": "…" } objects). Display only; the money still comes from your credits API at pay time.
  • publishedAt: ISO-8601.

Paging a large catalog

If you have more articles than fit in one response, return an envelope with a cursor instead of a bare array:

{
  "entries": [ { "slug": "…", "title": "…" } ],
  "nextCursor": "eyJwYWdlIjoyfQ"
}

We fetch the next page as ?cursor=<nextCursor> and keep going until an entry comes back without a nextCursor. Use whatever opaque cursor string you like.

What "listed" means

Being in the catalog is not the same as being tolled. Your credits API is the source of truth for what costs money; the catalog only says what exists.

If you serve this endpoint, we take your listing at face value. It is your tollable set, and we don't re-check each slug against your credits API, because you already made that call when you decided what to put in the response. So keep the two in step: an article here that your credits API answers 404 for is a listing for something nobody can buy.

That is what separates this endpoint from the fallbacks. An RSS feed or a sitemap is not a statement about what you charge for, so when we fall back to one, each new slug is checked against your credits API first: credits means listed, and 404 (your deliberate "this one is free" signal) means dropped.

If a buyer pays for a listed article and finds it is not actually gated, we drop it from the directory on the spot. You never end up charging for a free read, and a stale listing heals itself.

How large a catalog can get

Your plan sets how many articles one site's catalog holds, and the pricing page states the numbers. The ceiling applies to growth only: at the limit a sync adds nothing new but keeps refreshing what is already listed, so titles and tollability stay current.

A sync held at the ceiling says so on the run, so you can tell it from a sync that simply found nothing new.

Turning it on

You don't hand-register anything. In your site's content settings, turn on fleet discovery. We detect your catalog endpoint (or fall back to your RSS feed or sitemap), sync it on an interval, and list what your credits API tolls. Turn it off and your articles delist immediately. The synced list is kept, so turning it back on relists them without a re-crawl.

Pricing never lives here. Your read and citation prices, and who gets paid, stay exactly where they are today: your site settings and your credits API.