Agent in Scalar API Reference

Agent can also power the chat control inside Scalar API Reference (the sparkle icon in the reference UI). That flow uses an Agent key from your API's Settings → Agent page, separate from MCP installations. See Agent Keys.

Free limits

• 10 free messages per session in the embedded chat
• Full chat functionality on supported hosts
• No API key required on http://localhost

Ready to upgrade? See pricing.

Local development

Agent is enabled by default on http://localhost with 10 free messages. No configuration required.

Scalar.createApiReference('#app', {
  url: '/openapi.json',
})

The chat icon appears in the top left corner.

Production deployment

Agent requires a key for production. Without a key, the chat control does not appear.

Scalar.createApiReference('#app', {
  sources: [
    {
      url: 'https://registry.scalar.com/@your-namespace/apis/your-api/latest?format=json',
      agent: {
        key: 'your-agent-scalar-key',
      },
    },
  ],
})

See How to get an Agent key.

Disabling Agent

To disable Agent entirely (including on localhost):

Scalar.createApiReference('#app', {
  agent: {
    disabled: true,
  },
})

Hiding the Add API control

When you preload specific APIs (for example via sources or registry documents), you can hide the control that lets users add more APIs from the public list. Set hideAddApi: true in the agent config for that source:

Scalar.createApiReference('#app', {
  sources: [
    {
      url: 'https://registry.scalar.com/@your-namespace/apis/your-api/latest?format=json',
      agent: {
        key: 'your-agent-scalar-key',
        hideAddApi: true,
      },
    },
  ],
})

Only your preloaded APIs are shown; the “+ API” control and “Add context from dozens of API’s” section are hidden.

Configuration reference

The agent configuration accepts:

Per-source configuration when using multiple sources:

Scalar.createApiReference('#app', {
  sources: [
    {
      url: 'https://registry.scalar.com/@your-namespace/apis/first-api/latest?format=json',
      agent: {
        key: 'key-for-first-api',
      },
    },
    {
      url: 'https://registry.scalar.com/@your-namespace/apis/second-api/latest?format=json',
      agent: {
        key: 'key-for-second-api',
      },
    },
  ],
})

Global configuration — disable across all sources:

Scalar.createApiReference('#app', {
  agent: {
    disabled: true,
  },
  sources: [
    { url: '/api/v1/openapi.json' },
    { url: '/api/v2/openapi.json' },
  ],
})

OpenAPI and AsyncAPI context

The embedded chat supports frontend context and result display for both OpenAPI and AsyncAPI descriptions. Each question includes the selected description’s title, format, version, and source name, including when sources share an agent key. Open the chat with Ask AI beside search. Switching sources starts a new conversation; closing and reopening the drawer preserves the current conversation.

AsyncAPI uploads and answers require backend support. The frontend keeps the existing chat endpoints and tool names. Live AsyncAPI messaging and authentication are not available in the embedded chat; OpenAPI HTTP request execution is unchanged.