API References

Add an API reference from the Scalar dashboard, or configure a local file, a Scalar Registry document, or a remote URL in this repository.

Using the Scalar Dashboard

1. Open your docs project in the Scalar dashboard.
2. Click the + button next to the docs navigation heading and select Add API Reference.
3. Select an existing API from your team and click Add API. To use a new document, select Import a new API and click Continue. If your team has no APIs yet, the import screen opens directly.
4. When importing, upload or paste your OpenAPI or AsyncAPI document. Review its Registry path and choose Public or Private access, then click Add API.
5. Open the new API reference in the docs sidebar to check its content, then save your changes.

Importing stores the document in the Scalar Registry and adds a reference to your docs navigation. Importing an API into the Registry on its own does not add it to a docs project. Use Add API Reference to attach it.

Using a Local File

Reference an OpenAPI file stored in your GitHub repository by specifying a relative path from your configuration root:

{
  "$schema": "https://registry.scalar.com/@scalar/schemas/config",
  "scalar": "2.0.0",
  "navigation": {
    "routes": {
      "/api": {
        "type": "openapi",
        "title": "My API",
        "filepath": "docs/api-reference/openapi.yaml",
        "icon": "phosphor/regular/plug"
      }
    }
  }
}

Using the Scalar Registry

Upload your OpenAPI document to the Scalar Registry:

scalar auth login
scalar registry publish ./openapi.yaml --namespace my-organization --slug my-api

And reference it using a namespace, slug, and version (optional):

{
  "$schema": "https://registry.scalar.com/@scalar/schemas/config",
  "scalar": "2.0.0",
  "navigation": {
    "routes": {
      "/api": {
        "type": "openapi",
        "title": "My API",
        "namespace": "my-organization",
        "slug": "my-api",
        // "version": "1.0.0",
        "icon": "phosphor/regular/plug"
      }
    }
  }
}

Using a URL

Fetch an OpenAPI document from a remote URL. The document is fetched on each page load, keeping your documentation in sync with your live API:

{
  "$schema": "https://registry.scalar.com/@scalar/schemas/config",
  "scalar": "2.0.0",
  "navigation": {
    "routes": {
      "/api": {
        "type": "openapi",
        "title": "My API",
        "url": "https://api.example.com/openapi.json",
        "icon": "phosphor/regular/plug"
      }
    }
  }
}

Configuration

All OpenAPI entries support the following options:

Display Modes

• folder (default): Shows a single level of links with a folder icon
• flat Shows a single level of links with a section title
• nested Shows a sub-sidebar with breadcrumbs for deep navigation