# For agents

Two different surfaces are useful to software here, and they are worth separating. **This
portal** describes the API you build a site with; it is machine-readable because the
documents it renders are generated from the service itself. **Every site the platform
renders** carries its own agent surface — a read API, Markdown twins of its pages, an MCP
endpoint and the discovery documents that lead to them — so an agent can read a customer's
site without being told anything about it beyond the hostname.

## This portal

- **OpenAPI 3.1, per surface.** The [Tenant API](/tenant-api) and the
  [Sign-up API](/site-api) each render one generated document, and each page offers it for
  download. It is the same file the platform's own contract tests read, from the same
  build as the running service — so a generator pointed at it produces a client for what
  is deployed, not for what somebody documented.
- **Markdown twins.** Every prose page here answers at its own URL with `.md` appended —
  [/guides/quickstart.md](/guides/quickstart.md), [/concepts/errors.md](/concepts/errors.md)
  — with the frontmatter stripped. The suffix, rather than an `Accept` header, because the
  cache in front of this site does not vary on `Accept`.
- **[/llms.txt](/llms.txt)** lists those pages for a model that wants the map before the
  territory, and [/llms-full.txt](/llms-full.txt) is the whole site in one file.
- **An executable example.** [quickstart.sh](/quickstart.sh) is the script the guides quote
  region by region; it runs end to end, so it is a working example rather than a plausible
  one.
- **A crawl map and a stated policy.** [/sitemap.xml](/sitemap.xml) lists every page this
  site renders, and [/robots.txt](/robots.txt) carries the site's Content Signals: search,
  AI input and AI training are all answered `yes` here. This is documentation written so
  that software calls the platform correctly — a model that has read it is the point, not
  a side effect.
- **`Link` headers.** Every page names, in its response headers, its own Markdown twin, the
  sitemap and `/llms.txt`; every page rendered from an API document also names that document
  (`rel="describedby"`, `rel="service-desc"`). A client learns what else exists before
  parsing anything, and on a `HEAD` request — which is the cost the header exists to avoid.

## Every site the platform renders

These come with the site — a tenant switches them on or off in their settings, and they
need no code:

- **A read API per view**, at `/api/v1/…` on the site's own domain (and under each
  language's path prefix), with the site's own **`/openapi.json`** describing it and
  `/api/health` reporting whether it is up.
- **Markdown twins of every page**, at the `.md` suffix or by asking for `text/markdown`,
  with front matter carrying the canonical URL, locale, dates and authorship — the fields
  a citation needs.
- **`/llms.txt`** per view: the site's pages and posts, each as a title, a `.md` link and a
  line of context.
- **[`/.well-known/api-catalog`](https://www.rfc-editor.org/rfc/rfc9727.html)** — the one
  address an agent can try knowing only the hostname. It links each view's API description
  and status, and the MCP endpoint.
- **An MCP server** at `/mcp`, with a server card at `/mcp/server-card`, offering read-only
  tools over the site's pages, posts and search. The tool list follows what the site
  actually has: no blog tools without a blog, no search tool without search.
- **In-page tools for a browsing agent** (WebMCP), registered by the page itself, so an
  agent already inside the browser can search or read without a second protocol.
- **Agent Skills** under `/.well-known/agent-skills/`: two documents per site — how to read
  it, and what to cite from it, including the site's own AI policy in the same words its
  `robots.txt` uses.
- **`robots.txt` with Content Signals**, where the tenant's answer to search, AI input and
  AI training is stated rather than implied.

Everything on that list is generated per site from its content and settings, which is the
same rule this portal follows: one description, produced by the thing it describes.