The catalogue endpoint

The credits API tells the toll who to pay for one article. The catalogue endpoint lists which articles you have, so they show up in the naulon directory and in agent search before anyone has read them. It is optional: without it, your articles are still tolled when an agent reads one.

It is read-only and, like the credits API, lists only the teaser, never the body.

What naulon does with your article text

When your articles are enriched, naulon stores their text and never serves it. Search uses it, so a buyer can find an article by what is inside it. When a buyer asks a question, a model reads the relevant passages to judge what paying for your article would add. The buyer sees a verdict and, at most, a line built from your title, teaser, headings and the terms you emphasise. No sentence, figure or quote from the text is shown to anyone who has not paid for it.

The request

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

We probe /catalog and /api/catalog when you turn on discovery, or you can give us any URL. The naulon WordPress plugin serves this endpoint for you at /wp-json/naulon/v1/catalog, and we look there too. A bare GET returns your whole catalogue, or its first page; see paging below for ?cursor=.

Make the route public and cacheable. It is polled on an interval, not per read, so a few minutes of caching (ISR, a CDN, Cache-Control) is enough. The poll sends no If-None-Match, so an ETag will not turn it into a 304; caching is what keeps it cheap.

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"
  }
]

Two fields are required: a title, and a slug or a url we can derive the toll slug from. The rest are optional:

• summary: a one-line teaser, shown in the directory. It is public, like 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 objects { "name": "…", "id": "…" }. Send id when your credits API names the author with one: the same string you put in a contributor's authorId. Then your reports credit each read to the person it paid. Without it, an author is matched by name. The money still comes from your credits API at pay time.
• publishedAt: ISO-8601.

Paging a large catalogue

For a large catalogue, 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 catalogue is not the same as being tolled. Your credits API is the source of truth for what costs money; the catalogue only says what exists.

If you serve this endpoint, we take your listing as your tollable set and don't re-check each slug against your credits API. Keep the two in step: an article listed here that your credits API answers 404 for is a listing nobody can buy.

The fallbacks work differently. An RSS feed or a sitemap does not say what you charge for, so each new slug from one is checked against your credits API: credits means listed, 404 means dropped.

If a buyer's agent tries to pay for a listed article and the read comes back 404 because the page moved or was deleted, we drop it from the directory immediately. A listing that turns out to be free is left listed, because a briefly misconfigured credits endpoint or API key produces the same result. Fix the mismatch in your catalogue response or your credits API and the next sync corrects it.

How large a catalogue can get

Your plan sets how many articles one site's catalogue 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, so you can tell it from a sync that found nothing new.

Getting listed

There is nothing to turn on. Once your site runs on a credits endpoint, its catalogue is synced automatically: we detect your /catalog endpoint, or fall back to your RSS feed or sitemap, and list what your credits API tolls. Sites → Manage → Which pages → Where the list comes from shows the last sync and a Sync catalogue button to trigger one by hand.

Public visibility is a separate switch, on by default: Sites → Manage → Advanced → Public visibility → List in the public directory. Turn it off and your articles delist immediately; turn it back on and the synced list reappears with no re-crawl.

Prices and payees are not set here. They stay in your site settings and your credits API.