REST API Documentation

Our REST API docs are generated by Mintlify from an OpenAPI spec. The Mintlify site is configured (in docs/docs.ensnode.io/docs.json) with two API doc groups that use different OpenAPI spec sources:

Group	Visibility	OpenAPI Source	Purpose
API Reference	Visible	Live production ENSApi instance	Always reflects the currently deployed production API
Preview	Hidden	Committed ensapi-openapi.json file	Shows REST API docs based on the source branch

The API Reference group always fetches the OpenAPI spec from the live production ENSApi instance, regardless of whether it’s a production or preview build. This means the visible API Reference docs always reflect the currently deployed API, which may differ from what’s committed to the main branch or to any other branch that’s being previewed under development.

The Preview group reads from the committed ensapi-openapi.json file. It is hidden by default but is accessible by manually navigating to /ensapi/preview in the Mintlify site. The contents of this group depend on which branch was used for the build:

• Production builds (on main): shows the spec committed to main
• PR preview builds: shows the spec committed to the PR branch, allowing reviewers to see upcoming API changes before they are deployed

Mintlify Docs Builds

On each commit to the main branch, Mintlify automatically deploys a new production build. On each push to a PR branch that changes files in docs/docs.ensnode.io, Mintlify deploys a new preview build (and posts a link as a comment on the PR).

Local Preview

You can preview REST API doc changes locally before pushing to a PR. First, regenerate the OpenAPI spec from the monorepo root if you’ve modified any API route schemas:

# from the monorepo root
pnpm generate:openapi

Then start the Mintlify docs site locally:

cd docs/docs.ensnode.io
pnpm mint dev

This starts a local server at http://localhost:3000. Since the visible API Reference group always fetches from production, manually navigate to the hidden preview page at http://localhost:3000/ensapi/preview to review your local changes.

OpenAPI Spec Sync Check

On every PR, our CI runs an openapi-sync-check job that:

1. Regenerates the OpenAPI spec from the ENSApi route definitions by running pnpm generate:openapi
2. Compares the freshly generated OpenAPI spec against the committed docs/docs.ensnode.io/ensapi-openapi.json, failing with a diff if they don’t match
3. Validates that Mintlify can parse the spec with openapi-check

If you modify any API route schemas in apps/ensapi, you must regenerate and commit the updated spec from the monorepo root:

# from the monorepo root
pnpm generate:openapi

Then commit the updated OpenAPI spec to docs/docs.ensnode.io/ensapi-openapi.json.