What the Public Read API Will Not Do

A public API on a document site normally means one thing: an address you post a file to. This one is not that, and the difference is the entire point of it. The read API returns what this site already publishes on its own pages, in a shape a script can use. It accepts nothing, it stores nothing, and there is no endpoint anywhere on it that takes a document.

Five addresses under /api/v1, all of them read-only.

• The index gives you the site name, one line about what it is, the API version, a link to the documentation page, the other four addresses, and a flag saying read-only in as many words.
• The health check returns a status, the version the site reports for itself, and the current time. It is never cached, because a cached health check reports the past.
• The site record is this site describing itself: name, canonical address, description, version, and the address of its assistant endpoint.
• The capability list returns a count and the things this site can do, each one a stable name and a single sentence written to be read in terminal output.
• The sibling list returns the other Novus properties, so a client that found any one of them can walk the rest without being told where to look.

GET and HEAD are answered. OPTIONS answers the browser preflight. Every other verb returns 405 with a one-line message saying the API is read-only. That is not a placeholder for something not yet built: there is no write path behind it to implement. An endpoint that changes state needs authentication, authentication needs accounts, and most of the sites running this same contract have none.

The refusal says what it means rather than returning a bare status code. You get an error name, a sentence telling you the API is read-only and to use GET, and a header naming the verbs that are accepted, which is the part a well-behaved client reads before it decides whether to retry. That is not politeness for its own sake. A machine surface that fails without explaining itself produces a support question instead of a corrected client.

The obvious way to build a capability list is an array of endpoints written out by hand. That array would be a second copy of a list this site already maintains for its assistant endpoint, and the two would part company the first time anything was renamed. Silently, because nothing compares them, and a client reading JSON cannot tell a stale name from a live one.

So there is no second array. The capability list is a projection of the catalogue the MCP server already publishes. Rename something and it renames in both places in the same change; remove it and it disappears from both. The sentences you get back are the short human-readable ones rather than the longer instructions written for a model choosing between tools.

• No keys, dashboard or usage console. There is no management layer at all, and adding one would be a separate product decision rather than a quiet addition here.
• No private data. Nothing served reads a record belonging to a person. Every byte of it is already visible on the site's own pages.
• No per-caller state. There is no session and no cookie, so every caller receives the identical answer to the identical request.
• No writes. Not a restricted subset of writes, not a write behind a key. None.

Because every response is identical for every caller, they are cacheable by anything in front of the site, with a short lifetime and a long window in which a stale copy may be served while a fresh one is fetched behind it. A burst of requests after expiry is answered instantly from the edge while one request refreshes. That is what keeps a crawler from ever reaching the origin in volume. The health check is the exception and is never stored anywhere.

Rate limiting is applied per address rather than per site, which matters more than it sounds. A client hammering the capability list cannot exhaust the budget for the health check and take the site's own monitoring down as collateral damage. Cross-origin requests are allowed from anywhere, which is correct rather than lax: every response is public and unauthenticated, no credentials are attached, and restricting the origin would block exactly the browser-based clients the API exists for while protecting nothing.

A client speaking JSON-RPC already has a door, which is the assistant endpoint described on the MCP server page. A plain reader had none. This is that door: a command-line fetch, a crawler, a spreadsheet, somebody's script, a status page that wants to know whether the site is answering. It is the same shape on every Novus property, so one client can walk the whole estate from any entry point.

It is also a reasonable way to check a claim rather than take it on faith. The catalogue you get back is the catalogue the pages render, and if the two ever disagreed, one of them would be lying to you. That is the reason the list is projected rather than retyped.

Nothing about it is versioned casually, either. The version sits in the address itself and moves only for a change that would break an existing reader. That is the promise which makes it reasonable to point a script at one of these addresses and walk away for a year, and it is also why the list of addresses is short. A surface that keeps growing is a surface that keeps breaking.

If what you need is the job finished rather than the catalogue read, the API is not the route and never will be. Open the tool in a browser and give it the file there. Your document stays on your device, which is precisely why this API is allowed to be as boring as it is, and how it works walks through the path a file takes once you pick it.