JSON-API

Die schreibgeschützte JSON-API, die jede Blume-Site ausliefert — Seitenindex, Dokumente pro Seite, Navigation, Suche — und die OpenAPI-3.1-Beschreibung, mit der Function-Calling-Frameworks daraus Tools bauen können.

Jede Blume-Site liefert ihre Dokumentation zusätzlich als kleine, schreibgeschützte JSON-API aus — das REST-Pendant zu den Tools des MCP-Servers, über denselben Seiten-Snapshot, für Agents und Function-Calling-Frameworks, die schlichtes HTTP statt MCP sprechen. Sie ist standardmäßig aktiv und braucht keine Konfiguration:

Der Seitenindex lässt versteckte Seiten weg, die auch kein Dokument pro Seite erhalten; get_page und der .md-Spiegel der Seite liefern trotzdem eines aus, denn versteckt heißt nicht privat. Seiten mit seo.noindex, ai.exclude oder search.exclude werden wie alle anderen aufgeführt. Das markdown eines Seitendokuments ist der Quelltext der Seite, so wie Agents ihn lesen, wobei der Frontmatter-Block oben erhalten bleibt.

Der Seitenindex, die Dokumente pro Seite und die Navigation werden vorgerendert, sodass eine statische Site sie von jedem Host als Dateien ausliefert. Die Suche ist ein Live-Endpunkt und existiert nur bei Server-Output, wo sie denselben Index nutzt wie search_docs.

Fehler

Fehler sind Problem Details nach RFC 9457 (application/problem+json) mit einem stabilen code, einem detail und einem resolution-Hinweis, der dem Agent sagt, wo es weitergeht — eine fehlende Seite, eine leere Suchanfrage oder, bei Server-Output, jede /api/…-URL, die kein Endpunkt beantwortet:

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

OpenAPI-Beschreibung

Das OpenAPI-Dokument unter /openapi.json wird bei jedem Build aus deiner Konfiguration erzeugt und beschreibt daher nur das, was die deployte Site tatsächlich ausliefert: jeden JSON-Endpunkt mit einer eindeutigen operationId, typisierten Parametern und Response-Schemas, dazu die Text-Oberflächen daneben — die .md-Spiegel, llms.txt und llms-full.txt, agent-readability.json — sowie den MCP-Endpunkt, wenn er aktiviert ist. Frameworks, die aus einer OpenAPI-Beschreibung Tools bauen, erhalten dieselbe Reichweite wie ein MCP-Client. Das Dokument ist aus dem API-Katalog, dem Readability-Manifest, dem Link-Header der Startseite als rel="service-desc" und aus llms.txt verlinkt.

Nichts davon berührt deine eigene API-Referenz: Eine dokumentierte Spec wird in Seiten gerendert, niemals unter /openapi.json ausgeliefert, und der Katalog listet beides. Eine public/openapi.json, die du selbst ausspielst, übernimmt diese Route (die JSON-Endpunkte bleiben bestehen), begleitet von einer BLUME_PUBLIC_OPENAPI_JSON-Warnung: Der Katalog listet /openapi.json weiterhin als Beschreibung der Dokumentations-API, Agents würden deine Datei also als solche lesen. Wenn du eine eigene Spec-Datei veröffentlichen willst, lege sie unter einem anderen Pfad ab, etwa public/specs/openapi.json. Der /api/…-Catch-all tritt zurück, wenn ein Dokumentationsbereich aus dem /api-Namespace ausgeliefert wird (content/api/overview.md) oder eine eigene Seite eine Rest-Route unter /api/ besetzt — diese Seiten gewinnen also weiterhin.

Abschalten

Setze agents.api auf false, um nichts davon zu veröffentlichen:

agents: {
  api: false,
}