---
title: API JSON
description: >-
  A API JSON somente leitura que todo site Blume serve — índice de páginas, documentos por página, navegação, busca — e a descrição OpenAPI 3.1 que permite a frameworks de function calling construírem ferramentas a partir dela.
---

Todo site Blume também serve sua documentação como uma pequena **API JSON** somente leitura — a gêmea REST das ferramentas do [servidor MCP](/docs/discoverability/mcp), sobre o mesmo snapshot de páginas, para agentes e frameworks de function calling que falam HTTP puro em vez de MCP. Ela vem ligada por padrão e não precisa de configuração:

| Endpoint | Retorna |
| --- | --- |
| `/api/docs/pages.json` | Todas as páginas com sua rota, título, descrição, tipo de conteúdo, idioma, facetas e as URLs de suas formas renderizada, Markdown e JSON. |
| `/api/docs/pages/{route}.json` | Uma página: sua entrada no índice mais o Markdown para agentes (o mesmo corpo que `get_page` retorna). `{route}` é a rota da página sem a barra inicial, `index` para a home. |
| `/api/docs/navigation.json` | A árvore de navegação — abas do cabeçalho e a hierarquia da barra lateral. |
| `/api/docs/search?q=` | Busca em texto completo, com o mesmo escopo de `limit`, `contentTypes`, `locale`, `version` e `filters[key]` que `search_docs`. Somente em saída de servidor. |
| `/openapi.json` | A descrição OpenAPI 3.1 de toda a superfície legível por máquina. |

O índice de páginas, os documentos por página e a navegação são pré-renderizados, então um site estático os serve como arquivos a partir de qualquer host. A busca é um endpoint ao vivo e existe apenas sob [saída de servidor](/docs/deployment#server-rendering), onde ela roda o mesmo índice que `search_docs` usa.

## Erros [#errors]

Os erros são problem details no formato [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) (`application/problem+json`) com um `code` estável, um `detail` e uma dica de `resolution` dizendo ao agente para onde ir em seguida — uma página inexistente, uma consulta de busca em branco ou, em saída de servidor, qualquer URL `/api/…` que nenhum endpoint responde:

```json
{
  "code": "API_ROUTE_NOT_FOUND",
  "detail": "No API route exists at /api/nope.",
  "instance": "/api/nope",
  "links": [
    {
      "href": "https://docs.example.com/openapi.json",
      "label": "OpenAPI description"
    },
    {
      "href": "https://docs.example.com/api/docs/pages.json",
      "label": "Page index"
    }
  ],
  "resolution": "Discover the available operations through the OpenAPI description at https://docs.example.com/openapi.json, or list every page at https://docs.example.com/api/docs/pages.json.",
  "status": 404,
  "title": "API route not found",
  "type": "about:blank"
}
```

## Descrição OpenAPI [#openapi-description]

O **documento OpenAPI** em `/openapi.json` é gerado a cada build a partir da sua config, então ele descreve apenas o que o site publicado serve: todo endpoint JSON com um `operationId` único, parâmetros tipados e schemas de resposta, além das superfícies de texto ao lado — os [espelhos `.md`](/docs/discoverability/markdown), [`llms.txt`](/docs/discoverability/llms-txt) e `llms-full.txt`, [`agent-readability.json`](/docs/discoverability/agent-discovery#agent-readability) — e o [endpoint MCP](/docs/discoverability/mcp) quando ele está habilitado. Frameworks que constroem ferramentas a partir de uma descrição OpenAPI ganham o mesmo alcance que um cliente MCP tem. O documento é referenciado a partir do [catálogo de APIs](/docs/discoverability/agent-discovery#api-catalog), do [manifesto de legibilidade](/docs/discoverability/agent-discovery#agent-readability), do cabeçalho `Link` da homepage como `rel="service-desc"` e do `llms.txt`.

Nada disso mexe na sua própria [referência de API](/docs/advanced/api-reference): uma spec documentada é renderizada em páginas, nunca servida em `/openapi.json`, e o catálogo lista as duas. Um `public/openapi.json` que você mesmo publica assume aquela rota (os endpoints JSON continuam). O catch-all de `/api/…` sai do caminho quando uma seção da documentação é servida a partir do namespace `/api` (`content/api/overview.md`) ou quando uma página personalizada é dona de uma rota rest sob `/api/`, então essas páginas continuam vencendo.

## Desligando [#turning-it-off]

Defina `ai.api` como `false` para não publicar nada disso:

```ts blume.config.ts lineNumbers
ai: {
  api: false,
}
```