Skip to main content

Browsing Your API

How to use the auto-generated Scalar API reference page that ships with every ɳSelf deployment.

Every ɳSelf backend ships with an interactive API reference at /docs. It is generated automatically from your Hasura schema and installed plugins. No configuration needed to get started.

Opening the docs

After nself start, open your browser at:

http://localhost/docs        # local dev
https://api.example.com/docs # production (replace with your BASE_DOMAIN)

The page loads instantly: Scalar is served from disk, not a CDN.

What you see

The reference page has three sections:

Auth: signup, signin, signout, token refresh, and user endpoints from the nHost auth service. All include request/response schemas and a try-out panel.

GraphQL: a single POST /v1/graphql entry with an executable request editor. Paste any query or mutation, set variables, and send. The response appears inline. Subscriptions are documented separately but marked as WebSocket-only.

Plugins: REST routes registered by your installed plugins (e.g. /ai/v1/complete, /notify/v1/send). Each plugin’s routes appear as a named group.

Trying out requests

  1. Click any endpoint to expand it.
  2. Select the Try tab.
  3. The bearer token is pre-filled from nself if you configured API_DOCS_AUTH_ENV_VAR. Otherwise, paste your JWT into the auth field at the top of the page.
  4. Fill in path parameters, query strings, or request body.
  5. Click Send.

The response panel shows status code, headers, and body. JSON is syntax-highlighted.

Getting the raw spec

The OpenAPI 3.1 JSON is available at /api-docs:

curl http://localhost/api-docs | jq .

Import it into any OpenAPI-compatible tool: Postman, Insomnia, Bruno, or your language’s SDK generator.

Generating client SDKs

With the raw spec at hand, generate typed clients using standard tools:

# TypeScript (openapi-typescript)
npx openapi-typescript http://localhost/api-docs -o src/api.d.ts

# Python (openapi-generator)
openapi-generator generate -i http://localhost/api-docs -g python -o ./sdk

The spec is OpenAPI 3.1, compatible with all generators that support 3.0+.

Keeping the spec current

The spec is regenerated on every nself build. Run a build after:

  • Installing or removing a plugin
  • Adding a custom service with REST endpoints
  • Rotating the anon key (to update the pre-filled token)

There is no manual step. The spec always reflects the current installed state.

Offline use

The Scalar page makes no external requests. It works on hosts with no internet access. The spec is served from .nself/dist/openapi.json by nginx, no backend process is required beyond nginx being up.

Disabling the docs page

Set API_DOCS_ENABLED=false in your .env file and run nself build. The nginx location blocks are removed. The /docs and /api-docs paths return 404.

See API Docs Configuration for the full option reference.