Beacon

REST API Introduction

Beacon publishes its pages and navigation as JSON, so scripts, integrations, and AI tools can read the content without parsing HTML. The API is read-only and doesn't require authentication. Beacon generates each response as a static file at build time, so the API works on any static host and reflects the content of the latest deployment.

Endpoints

All endpoints use the GET method. Paths are relative to your site URL.

EndpointReturns
/api/v1/docs.jsonMetadata for every page
/api/v1/docs/{slug}.jsonMetadata and the Markdown body for one page
/api/v1/nav.jsonNavigation groups and their links
/api/v1/openapi.jsonAn OpenAPI 3.1 description of the API

A page's slug is its file name in content/docs/ without the .mdx extension. The home page's slug is introduction. A slug that doesn't exist returns your host's standard 404 response.

Set the site URL

The URLs in API responses come from the SITE_URL environment variable. Set it when you build the site, or the responses use https://example.com. If your site is served from a subpath, include the subpath in SITE_URL, and add it to the endpoint paths, such as /repo-name/api/v1/docs.json.

Call the API from a browser

Browser code on another domain can read a response only if the host allows cross-origin requests:

  • Vercel and Netlify: vercel.json and netlify.toml set Access-Control-Allow-Origin: * for /api/v1/ paths.

  • GitHub Pages: GitHub Pages sets this header on its responses, so you don't need to configure anything.

  • Other static hosts: Set Access-Control-Allow-Origin: * for /api/v1/ paths in your host's settings.

Limitations

Because responses are static files, the API doesn't support the following:

  • Query parameters, such as filtering, pagination, or server-side search.

  • Requests that create, update, or delete content. To change a page, edit its file and redeploy the site.