Scalar API Reference Plugin for FastAPI

Installation

pip install scalar-fastapi

Usage

FastAPI makes it super easy to enable Scalar with their out of the box OpenAPI support.

Basic Usage

from fastapi import FastAPI
from scalar_fastapi import get_scalar_api_reference

app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "World"}

@app.get("/scalar", include_in_schema=False)
async def scalar_html():
    return get_scalar_api_reference(
        # Your OpenAPI document
        openapi_url=app.openapi_url,
        # Avoid CORS issues (optional)
        scalar_proxy_url="https://proxy.scalar.com",
    )

Multiple OpenAPI Sources

You can now display multiple OpenAPI documents in a single Scalar instance:

from scalar_fastapi import get_scalar_api_reference, OpenAPISource

@app.get("/scalar", include_in_schema=False)
async def scalar_html():
    return get_scalar_api_reference(
        sources=[
            OpenAPISource(
                title="User API",
                url="/openapi.json",
                default=True
            ),
            OpenAPISource(
                title="Admin API",
                url="/admin/openapi.json"
            ),
            OpenAPISource(
                title="External API",
                content='{"openapi": "3.0.0", ...}'
            )
        ],
        title="My API Documentation"
    )

Direct OpenAPI Content

You can pass OpenAPI content directly as a string or dictionary:

@app.get("/scalar", include_in_schema=False)
async def scalar_html():
    return get_scalar_api_reference(
        content='{"openapi": "3.0.0", "info": {"title": "My API"}}',
        title="My API"
    )

Agent Scalar

Agent Scalar adds an AI chat interface to your API reference. It is enabled by default on localhost (with limited free messages). For production you need an Agent Scalar key. See the Agent Scalar configuration section for details.

Per-source: enable Agent with a key

from scalar_fastapi import get_scalar_api_reference, OpenAPISource, AgentScalarConfig

@app.get("/scalar", include_in_schema=False)
async def scalar_html():
    return get_scalar_api_reference(
        sources=[
            OpenAPISource(
                title="User API",
                url="/openapi.json",
                default=True,
                agent=AgentScalarConfig(key="your-agent-scalar-key"),
            ),
        ],
        title="My API Documentation"
    )

Disable Agent entirely

from scalar_fastapi import get_scalar_api_reference, AgentScalarConfig

@app.get("/scalar", include_in_schema=False)
async def scalar_html():
    return get_scalar_api_reference(
        openapi_url="/openapi.json",
        agent=AgentScalarConfig(disabled=True),
    )

Configuration

Currently available configuration options are listed below.

Core Configuration

openapi_url (default None) - The OpenAPI URL that Scalar should load. If content or sources are provided, this parameter is ignored.
content (default None) - Directly pass an OpenAPI/Swagger document as a string (JSON or YAML) or as a dictionary. If sources are provided, this parameter is ignored.
sources (default None) - Add multiple OpenAPI documents to render all of them. Each source can have a title, slug, url, content, and default flag.
title (default "Scalar") - The title of the API reference page

OpenAPISource Configuration

When using multiple sources, each OpenAPISource can be configured with:

title (default None) - Display name for the API. If not provided, will fallback to 'API #1', 'API #2', etc.
slug (default None) - URL identifier for the API. If not provided, will be auto-generated from the title or index.
url (default None) - URL to the OpenAPI document (JSON or YAML). Mutually exclusive with content.
content (default None) - Direct OpenAPI content as string (JSON/YAML) or dictionary. Mutually exclusive with url.
default (default False) - Whether this source should be the default when multiple sources are provided.
agent (default None) - Optional Agent Scalar config for this source (key, disabled). See Agent Scalar for details.

Display Options

layout (default Layout.MODERN)
show_sidebar (default True)
hide_models (default False)
hide_search (default False) - Whether to show the sidebar search bar
hide_test_request_button (default False) - Whether to show the "Test Request" button
hide_download_button (default False) - Deprecated: Use document_download_type instead
document_download_type (default DocumentDownloadType.BOTH) - Sets the file type of the document to download. Options: JSON, YAML, BOTH, NONE
show_developer_tools (default "localhost") - Configures when to show the top developer tools panel. Options: "always", "localhost", "never"

DocumentDownloadType

from scalar_fastapi import DocumentDownloadType

# Available options:
DocumentDownloadType.JSON    # Download as JSON only
DocumentDownloadType.YAML    # Download as YAML only
DocumentDownloadType.BOTH    # Download as both JSON and YAML
DocumentDownloadType.NONE    # Hide download button

Theme and Appearance

dark_mode (default True)
force_dark_mode_state (default None) - Force dark mode state to always be this state. Can be 'dark' or 'light'
hide_dark_mode_toggle (default False) - Whether to show the dark mode toggle
with_default_fonts (default True) - Whether to use default fonts (Inter and JetBrains Mono)
custom_css (default "") - Custom CSS string to apply to the API reference

search_hot_key (default SearchHotKey.K)
default_open_all_tags (default False)
expand_all_model_sections (default False) - Whether to expand all model sections by default
expand_all_responses (default False) - Whether to expand all response sections by default
order_required_properties_first (default True) - Whether to order required properties first in schema objects

Server Configuration

base_server_url (default "") - If you want to prefix all relative servers with a base URL
servers (default [])
hidden_clients (default [])

Authentication

authentication (default {})
hide_client_button (default False) - Whether to show the client button from the reference sidebar and modal
persist_auth (default False) - Whether to persist authentication credentials in local storage

Advanced

scalar_js_url (default "https://cdn.jsdelivr.net/npm/@scalar/api-reference")
scalar_proxy_url (default None)
integration (default None)
theme (default Theme.DEFAULT)
agent (default None) - Set to AgentScalarConfig(disabled=True) to disable Agent Scalar entirely, or use per-source agent on OpenAPISource for keys. See Agent Scalar.
overrides (default {}) - Specific overrides directly to the config dictionary which is passed as Scalar.createApiReference("#app", {json.dumps(config)})
telemetry (default True) - Enable or disable api client usage telemetry. Options: True, False

Layout

from scalar_fastapi import Layout

# Available options:
Layout.MODERN    # Modern layout
Layout.CLASSIC   # Classic layout

SearchHotKey

from scalar_fastapi import SearchHotKey

# Available options:
SearchHotKey.K    # Use 'K' key
SearchHotKey.CMD_K # Use 'Cmd+K' (Mac) / 'Ctrl+K' (Windows/Linux)
SearchHotKey.NONE # Disable hotkey

Theme

from scalar_fastapi import Theme

# Available options:
Theme.DEFAULT # Default theme
Theme.NONE    # No theme

Express

Fastify