API reference overview

Bloques turns an OpenAPI spec into a browsable API reference: one page per endpoint, with parameters, schemas, example requests, and a playground for sending live calls. Point a navigation group at a spec file and the pages appear on your next deploy. This page covers how generation works and where its limits are. For the setup steps, see Set up an API reference.

How it works

The spec drives everything, on the same push-to-deploy flow as the rest of your site:

• An OpenAPI spec (JSON) lives in your repo, alongside your MDX pages.
• A navigation group in docs.json points at the spec through its openapi field.
• On each deploy, Bloques reads the spec and generates one page per operation under that group.

The spec stays the single source of truth: no generated files land in your repo to commit or keep in sync. Edit the spec, push, and the pages update. Each page renders from the spec when a reader opens it, so the reference always matches what you shipped.

What each page includes

Every operation in the spec becomes a page with:

• Endpoint summary: method, path, and the operation's description.
• Parameters: path, query, header, and body parameters with their types and constraints.
• Schemas: request and response bodies with example values, expandable by field.
• Code samples: example requests in multiple languages, ready to copy.
• Playground: an interactive panel for sending a real request and reading the response. Requests route through Bloques by default, so no CORS setup is needed — see How requests are sent. Turn the panel off with api.playground.display.

Mix generated pages with hand-written ones in the same group, for example an overview or authentication guide above the endpoints.

Each generated page is also available as markdown for AI tools, listed in /llms.txt alongside the rest of your site. See LLM endpoints.

How requests are sent

Send routes through Bloques rather than calling your API from the reader's browser, so your API doesn't need to allow cross-origin requests (CORS) from your docs domain, and an API that never answers reports a real error instead of failing silently.

Set proxy to false to send from the browser instead. Do that when your API authenticates the browser itself — mutual TLS, a client certificate, an IP allowlist — or when you'd rather reader-supplied keys never reach our servers. Your API then has to allow CORS from your docs domain.

{
  "api": {
    "playground": {
      "proxy": false
    }
  }
}

Some servers are called straight from the browser either way, because Bloques can't safely proxy them: a localhost or private-network address, a plain http:// URL, or a server URL with a free-form variable in its hostname.

Turning off the playground

Some endpoints shouldn't be called from the docs at all — there are no sandbox keys to hand out, or the operation isn't safe to run on a whim. Set api.playground.display in docs.json to drop the live-request panel and keep the rest of the page:

{
  "api": {
    "playground": {
      "display": "simple"
    }
  }
}

simple leaves a static card with the method and path. none removes the panel entirely. Parameters, schemas, and code samples render either way. The setting applies to every generated page on the site. See api for the full field reference.

What isn't supported yet