npm

@scalar/api-reference

1.67.0scalar/scalar ↗

Generate beautiful API references from OpenAPI documents

Last release today
28 Aug 2026
Ships on a steady schedule
a new release about every 1 weeks
Most releases are documented
notes for 51 of the last 60 stable releases
1 version withdrawn
withdrawn after publishing
3 years old
705 releases · first in 2023

Release timeline

705 releases since 2023

2023202420252026

20232026

One column per quarter.

Releases

1.67.028 Aug 2026
Release notes
Minor Changes
- #10043: Resolve heading levels from a block's place in the page outline instead of hardcoding them, so a block rendered on its own starts at h1.
  
  A block now assumes it is the top of the page: rendered alone, an operation's title is the h1 and everything it contains follows beneath it. A component that renders several blocks alongside each other owns the relationship between them and anchors the outline — Content renders the info block above the tags and operations, so it declares document and the rest resolve against it. Composed into a full reference, every heading renders at the level it always has.
  
  Also fixes two headings that never went through the heading components: the classic-layout operation title was a raw h3, and the classic-layout Models section label passed a level prop to a component that does not accept one, so it rendered no heading element at all.
- feat: test OpenAPI webhooks from the API reference and API client
Patch Changes
- #9983: Bump the zod catalog to ^4.4.3 so the standalone bundle ships a single zod instead of two (4.3.5 from @scalar/types plus 4.4.3 from the ai / @ai-sdk peer). This makes standalone.js ~68KB raw / ~18KB gzip smaller.
- #9965: Fix oneOf selector labels showing the shared allOf base name instead of the variant's own name. When a oneOf branch extended a common base through a single-$ref allOf (a common inheritance pattern), flattening that allOf for display left the base schema's own identity ($ref, title, or name) on the flattened variant, so the selector picked up the base's name for every branch instead of each branch's own name.
- #9973: Fix the "OAuth scopes" section rendering for any security scheme with a non-empty scope array, including http and apiKey schemes. Scopes are only meaningful for oauth2 and openIdConnect schemes, so the section is now skipped when the resolved scheme is of a different type.
- #9289: fix response example panel to reflect selected content type from the response dropdown
- #9968: Move the schema Pattern hover chip next to the Example chip so it no longer collides with the preceding constraint (for example max length: 26Pattern). Real constraints like length and nullable now stay together in the dotted list.
Open source →
1.66.120 Aug 2026
Release notes
Patch Changes
- #9941: Republish every package through npm trusted publishing. No functional changes.
Open source →
1.65.113 Aug 2026
Nothing published for this version
1.65.013 Aug 2026
Release notes
Minor Changes
- #9884: Export the AsyncAPI content components (AsyncApiChannel, AsyncApiOperation, AsyncApiMessage, AsyncApiTraversedEntry) from @scalar/api-reference/components so downstream renderers can render an individual channel/operation/message on its own page.
Patch Changes
- #9856: Render model names as plain text when there is no models section to link to. The names next to types and on the request body heading used to be links even when the whole models section was hidden via hideModels, or when the referenced model itself was hidden via x-internal / x-scalar-ignore. There was nothing to scroll to, so clicking them did nothing. They now render as plain text in both cases.
- #9858: Only render a clickable model name link when the $ref actually targets #/components/schemas/. Refs into other component buckets (parameters, responses, ...) or external files now show the name as plain text instead of a dead link that scrolls nowhere.
- #9857: Fix dead model-name links for schemas grouped under a tag via x-tags. The models index now collects model entries from the whole navigation tree, so clicking a model name that lives under a tag group scrolls to the model instead of doing nothing.
- #9859: Fix empty popup when hovering the "Generate MCP" button without an MCP config
- #9862: Use the webhook icon for webhooks in search results so they are easy to tell apart from operations
Open source →
1.64.17 Aug 2026
Release notes
Patch Changes
- #9828: Bump shared build and runtime dependencies to their latest compatible versions (fuse.js, vite, vitest, tailwindcss, @vitejs/plugin-vue, @vue/test-utils, posthog-js, yaml, and the CSS injection plugin). The fuse.js 7.5.0 upgrade tightened generic inference, so the empty new Fuse([]) search instances now pass an explicit FuseData type argument.
- #9837: Keep the selected server when the configuration is updated. Pushing a config update to a mounted reference (for example a refreshed auth token via updateConfiguration) rebases the document in the store, which previously reset the server selector back to the first server. The user's selected server is now preserved across configuration updates.
- #9783: fix: resolve axe-core ARIA violations in the API reference sidebar and client tabs
  
  Sidebar items used aria-selected on links/buttons (invalid for those roles) and the search trigger used role="search" on a button. Selected items now use aria-current="page", the search control is a plain named button, and the sidebar no longer sets an invalid role="navigation" on <aside> (it keeps the default complementary landmark).
  
  Client library and SDK installation "More" comboboxes sat inside role="tablist", which fails aria-required-children. They now sit beside the tablist. MCP install controls without a target URL render as buttons instead of empty a[href=""] links.
- #9791: Stop recursive schema rendering when a discriminator variant allOfs back to its base type. The selected child now inherits the parent's discriminator context so the mapping is not re-inferred on every nest.
- #9830: Stop listing enum values twice for an array parameter whose items is a $ref to an enum schema. The values are now listed only in the array items card, which also shows the item schema's title and description.
- #9839: Harden the API reference against untrusted OpenAPI documents:
  - Link targets taken from the document (info.license.url, info.termsOfService, info.contact.url, externalDocs.url, x-scalar-links) and the direct download link are now checked against an allow list of protocols, so a document can no longer render a javascript: link that runs script when a reader clicks it. Unsafe values fall back to plain text.
  - deepMerge (used by the exported createEmptySpecification) no longer writes through the prototype chain, so a document can no longer add properties to Object.prototype via __proto__, constructor, or prototype. Keys with those names are kept as plain data instead of being dropped, so a schema is still free to describe a property named constructor.
  - customCss can no longer close the injected <style> tag, which mattered during server rendering where the value lands in the HTML stream verbatim.
  - Added rel="noopener noreferrer" to the remaining target="_blank" links.
  Adds isSafeUrl and sanitizeUrl to @scalar/helpers/url/is-safe-url.
- #9829: Update Vue to 3.5.40. Vue 3.5.36 tightened defineModel default validation, so models with array or object defaults now use the factory form (defineModel<T[]>({ default: () => [] })) as Vue already requires for regular props. Behaviour is unchanged.
- #9790: fix: keep dots in webhook navigation deep links
  
  Webhook event names that use dots (for example account_holder.created) had the dot dropped when building the navigation id, joining adjacent words into account-holdercreated. Dots are now kept, producing account-holder.created.
  
  Old deep links using the dropped-dot slug are redirected to the new slug, so existing bookmarks keep resolving.
Open source →
1.64.031 Jul 2026
Release notes
Minor Changes
- #9683: Surface the required OAuth scopes for an operation as a dedicated "OAuth scopes" section below the description (above parameters), instead of only inside the "Auth Required" badge popover. Scopes are de-duplicated across security alternatives and shown in both the modern and classic layouts, as well as on AsyncAPI operations.
- #9711: feat: add pluginUrls configuration option to load API Reference plugins from URLs
  
  Each entry must point to an ESM module that exports a plugin (the same shape as the plugins entries) as its default export. The standalone build (Scalar.createApiReference) imports the modules before the API reference mounts and registers their default exports alongside the plugins passed directly. Unlike plugins, the new option is JSON-serializable, so integrations that pass their configuration as JSON (for example the Docker container or Scalar for Aspire) can load plugins without replacing the whole bundle.
Patch Changes
- #9732: Render every oneOf/anyOf group of an allOf in place. Previously, when one object composed several mutually-exclusive choices as sibling oneOf/anyOf under allOf, only the first group was shown and the rest were silently dropped. Each choice group now renders its own selector in the position it was declared, and the generated request example stays in sync per group.
- #9794: Keep sibling properties when flattening a single-member allOf. Previously, a schema declaring its own properties next to an allOf holding a single $ref lost those sibling properties: the referenced schema's properties overwrote them instead of being combined, and the referenced schema's title/description replaced the parent's. Sibling and inherited properties now render together, required lists are unioned, and the parent schema's own annotations win over the base it extends.
- #9757: fix: read enum metadata from array items
  
  When an enum is defined inside an array schema's items, the enum values were resolved from items but their x-enum-varnames, x-enumNames, and x-enumDescriptions were still read from the outer schema, so the metadata was dropped. Both the values and their metadata are now read from the same schema.
- #9681: The "Auth Required" / "Auth Optional" badge on operations now opens on hover, not just on click
- #9753: fix: badge base styles no longer rely on zero specificity
  
  The badge base rule was written with :where(.badge), which the scoped-style compiler collapsed to zero specificity, letting any late-loading reset clobber the badge font size, padding, and colors. The base styles now carry real specificity, and consumers that intentionally override them (the download-link json/yaml badges and the webhook badge) keep winning through tailwind-merge and higher-specificity variant rules.
- #9766: fix: give the collapsible section trigger an accessible name and a valid aria-controls target
  
  The trigger button rendered by CompactSection carried aria-controls set to its own id, so it declared that it controls itself, and it exposed no accessible name of its own. Screen reader users heard an unnamed button, and axe-core reported button-name and aria-allowed-attr on every model section.
  
  The trigger now points aria-controls at the collapsible region, which carries its own id. While the section is collapsed the attribute is dropped entirely rather than left pointing at an element that is not rendered.
  
  The accessible name now comes from aria-labelledby pointing at the heading the trigger already renders, so the name is always the visible text. Referencing the heading rather than copying it into an aria-label means the name cannot drift out of sync with what is on screen, which is the WCAG 2.5.3 (Label in Name) failure a duplicated string would risk.
- #9754: fix: adapt the info links to the rendered width of the reference instead of the viewport
  
  The introduction's info links (contact, license, terms of service, external docs, and x-scalar-links), the section header grid, and the classic-layout selector cards switched their layout based on viewport media queries, while the rest of the reference adapts to the rendered width of the reference through the narrow-references-container container query. They now restyle based on the container as well, through a new narrow: Tailwind variant.
- #9751: fix: keep even heading-to-description spacing on the operation title in narrow layouts
  
  The narrow (single-column) operation layout bumped the operation title's bottom margin to 24px, so the gap between the heading and its description no longer matched the 12px used on wider screens. The override is removed so the title keeps the shared 12px spacing at every width.
- #9676: Preload additional documents in a multi-document setup while the browser is idle, so switching between them is instant.
- #9788: Add print styles so printing (or saving to PDF) no longer renders expanded content over the text that follows it. The reference lays itself out as a fixed-viewport application, and its sticky columns were pinned to a screen measurement that is meaningless on paper. Printing now flattens that shell into ordinary document flow: navigation and floating chrome are hidden, sticky positioning and viewport-derived height caps are dropped so long examples are no longer truncated, and small units such as properties and cards avoid breaking across pages.
- #9691: Show the format of primitive array items (e.g. an array of uuid strings) in the schema property heading
Open source →
1.63.020 Jul 2026
Release notes
Minor Changes
- #9728: feat: export SdkInstallationInstructions and getRenderableSdks from @scalar/api-reference/blocks, so consumers that compose their own reference layout can render x-scalar-sdk-installation again
Open source →
1.62.916 Jul 2026
Release notes
Patch Changes
- #9719: docs: update the Scalar platform overview block in the README
Open source →
1.62.816 Jul 2026
Release notes
Patch Changes
- #9687: feat(themes): derive the border radius scale from --scalar-radius
  
  The radius tokens used to be independent, so setting --scalar-radius: 0 still left rounded corners behind on anything using --scalar-radius-lg, --scalar-radius-xl or rounded-full. They now all derive from --scalar-radius, which means overriding that single variable rescales every corner in the interface, and 0 squares it off completely.
  
  Two new tokens fill out the scale, --scalar-radius-2xl (12px) and --scalar-radius-3xl (16px), along with --scalar-radius-full for pills and circles. The matching rounded-2xl and rounded-3xl Tailwind utilities now emit CSS; previously they were silently dropped.
  
  Every default value is unchanged, so nothing shifts unless you were relying on the old behaviour. If your theme sets --scalar-radius on its own and expects the larger radii to stay put, set those tokens explicitly. Override --scalar-radius on :root: a custom property substitutes var() at the element where it is declared, so setting the base further down the tree moves it without moving anything derived from it.
Open source →
1.62.715 Jul 2026
Nothing published for this version
1.62.615 Jul 2026
Release notes
Patch Changes
- #9618: Render document-wide authentication for AsyncAPI documents. The introduction now shows the same Authentication selector used for OpenAPI, populated from components.securitySchemes, with requirements derived from the union of every server's security (AsyncAPI has no root-level security). When some servers require auth and others accept unauthenticated connections, a no-auth option is offered too. Schemes shared with OpenAPI (http, oauth2, openIdConnect, apiKey) get full input UI, and AsyncAPI OAuth2 availableScopes are mapped onto OpenAPI scopes so the scope list renders. Broker-specific types still appear in the selector but have no dedicated input yet. The selector is now fully interactive for AsyncAPI (selecting schemes, entering credentials, editing scopes) because the auth mutators accept AsyncAPI documents. Operation/channel-level auth is intentionally left for a follow-up.
- #9618: Name the actual document type in the "security scheme is missing a type" warning. When a scheme has no recognizable type, the auth selector previously always told users to check their "OpenAPI document", even for AsyncAPI documents. The warning now reflects the document it belongs to (e.g. "AsyncAPI") via a new optional documentType prop on the auth selector block, defaulting to openapi. Schemes that carry a valid but unsupported type (such as AsyncAPI broker types like userPassword or scramSha256) now show a dedicated "not supported yet" message naming the type, instead of the misleading "missing a type" warning.
- #9679: Fix the plugin auth accessor reading from the wrong store. It now reads from the client store — the same store the reference-side Authentication panel writes credentials into — so plugins see the secrets and selected security schemes the user actually entered instead of an empty state.
Open source →
1.62.58 Jul 2026
Release notes
Patch Changes
- #9671: Add a canDeleteSchemes prop to the auth selector so the delete (trash) affordance can be hidden. It defaults to true (unchanged for the API client, where schemes are editable) and the API reference now passes false, since its schemes come from the rendered document and cannot be removed there.
- #9646: Fix deep links to response properties. Response property anchors now carry a responses marker so the target operation is found and scrolled to on a fresh load, and response properties are linkable even when expandAllResponses is off (a deep link expands the collapsed response and scrolls the property into view).
- #9631: Hide the protocol and server filters in the classic layout for AsyncAPI documents
- #9639: Add a read-only accessor for the global authentication state to the plugin API. Plugin lifecycle hooks (onInit, onConfigChange) now receive an auth accessor alongside config, and the plugin manager exposes getAuthState() for view components. Plugins can read stored secrets and the selected security schemes via auth.export(), auth.getAuthSecrets(documentName, schemeName), and auth.getAuthSelectedSchemas(payload) without being able to mutate auth.
- #9664: fix: keep base allOf properties when merging oneOf/anyOf branches
  
  When a schema used allOf to factor out shared object properties next to a oneOf/anyOf, each branch's own properties/required overwrote the shared base fields instead of being combined with them. The base fields now stay visible alongside each branch's own fields.
Open source →
1.62.43 Jul 2026
Nothing published for this version
1.62.32 Jul 2026
Nothing published for this version
1.62.22 Jul 2026
Release notes
Patch Changes
- #9630: Render AsyncAPI tags without the extra horizontal indentation on nested channels, and replace the empty "Operations" card in an AsyncAPI tag header with a "Channels" card that lists the channels in the tag.
- #9541: Fix an SSR hydration mismatch on the root element: the obtrusive-scrollbar class is now resolved after mount so the first client render matches the server.
Open source →
1.62.130 Jun 2026
Release notes
Patch Changes
- #9575: Render the discriminator variant dropdown for object schemas that only declare a discriminator.mapping (no explicit oneOf/anyOf), which is the shape NSwag emits for polymorphic types
- #9483: Render JSON Schema 2020-12 $dynamicRef in schemas, so generic patterns like PaginatedResponse<T> show their concrete bound item type (for example User[]) instead of an empty shape. The reference threads the active dynamic scope through the schema tree and binds each $dynamicRef to the matching $dynamicAnchor.
- #9587: Fix Maximum call stack size exceeded crash when rendering a schema whose self-reference is reached through an allOf branch
Open source →
1.62.026 Jun 2026
Release notes
Minor Changes
- #9597: Add API Reference UI localization configuration with built-in English, Russian, Spanish, French, German, Simplified Chinese and Arabic translations, including automatic RTL direction for Arabic locales.
  
  Update the shared theme reset so text inputs align to the logical start by default for RTL documents.
  
  Add a mergeObjects deep-merge helper to @scalar/helpers, used by the localization layer to merge translation overrides onto the built-in locale.
- #9568: Add AsyncAPI protocol and server pickers to the sidebar (like the multi-document picker) that filter the navigation down to the operations reachable over the selected protocol/server
- #9543: Add the x-scalar-links OpenAPI extension to render extra named links (like a privacy policy or imprint) next to the contact, license and terms of service links in the introduction.
Patch Changes
- #9545: Render the divider between the contact email and url links in the introduction, so they are separated like the other info links.
- #8519: refactor: extract the code example block into @scalar/blocks/code-example. api-client, api-client-react, and api-reference now import CodeExample, findClient, generateClientOptions, and the related helpers from the new package. workspace-store exports isParamDisabled with an optional defaultDisabled argument.
  
  Breaking (@scalar/api-client): the @scalar/api-client/blocks/operation-code-sample and @scalar/api-client/v2/blocks/operation-code-sample export paths have been removed. Import from @scalar/blocks/code-example instead, and use the renamed CodeExample / CodeExampleProps (previously OperationCodeSample / OperationCodeSampleProps).
- #9578: Show the propertyNames type and format (e.g. string · uuid) for a map of additional properties, so key constraints are no longer dropped from the rendered schema
- #9548: Keep request and response example pickers in sync across operations. Selecting an example (e.g. "Use case 1") now selects the example with the same key on every other operation that defines it, mirroring how the programming-language selection already syncs. Operations that do not have a matching example keep their current selection.
Open source →
1.61.022 Jun 2026
Release notes
Minor Changes
- #9520: Render AsyncAPI operations and their messages (with payload and header schemas) nested inside each channel, in both the modern and classic layouts
- #9569: Show server and protocol labels when rendering AsyncAPI channels and messages: each channel header lists the servers it's available on and their protocols, and each message surfaces every protocol it's carried over (its channel's server protocols unioned with its own binding protocols)
- #9515: feat: add requestBuilt client plugin hook and onRequestBuilt configuration callback that receive the exact fetch Request that is sent over the wire
  
  The hook runs after the request has been built, right before it is sent. Header mutations apply to the outgoing request and the body bytes match what the server receives, which makes request signing possible: hashing the body of a rebuilt multipart/form-data request would produce a different multipart boundary than the request that is actually sent.
Patch Changes
- #9559: Render an object's own properties when they are factored out alongside a composition keyword (anyOf/oneOf/allOf/not)
- #9542: Fix an SSR hydration mismatch in the injected <style> tag: the CSS is now rendered verbatim instead of being HTML-escaped on the server (" became "), which broke font styles and caused a hydration mismatch.
- #9546: fix: let a later allOf member override the description and title of an earlier one
- #9557: Fix oneOf/anyOf being dropped when nested inside an allOf. The composition is now preserved so its variants keep rendering alongside the merged base properties, instead of only the first allOf member showing up.
Open source →
1.60.017 Jun 2026
Release notes
Minor Changes
- #9478: Add content.start plugin view slot and sidebar visibility option for plugin view components.
  - content.start: A new view slot that renders custom plugin components before the Introduction/Info section (at the top of the content area).
  - sidebar option on ViewComponent: Plugins can now opt-in to display a sidebar entry for their custom views by providing sidebar: { show: true, label: 'My Page' }. Omitting sidebar or setting show: false hides the entry from the sidebar. The entry hooks into the existing navigation, so clicking it scrolls to the plugin view and it highlights as it scrolls into view.
Patch Changes
- #9504: Fix extra nesting and duplicated description when array items are wrapped in a single-item composition (allOf, oneOf, or anyOf)
- #9526: Fix anchor links to schema properties that are hidden inside collapsed sections. Deep links now expand the disclosures on the path to the target property and scroll to it, so links work without enabling expandAllSchemaProperties.
- #9484: Fix the schema description being hidden for responses when expandAllResponses is enabled. A response's own description and its content schema's description are now both shown.
- #9531: fix: the introduction loading skeleton now mirrors the actual layout (badges, title, links, description and selector cards) instead of generic stacked bars, so the page no longer jumps once the document loads
- #9524: Fix sidebar overlapping the content at exactly 1000px wide. The layout grid switched to the mobile (stacked) layout at max-width: 1000px while the sidebar visibility is driven by Tailwind's lg: variant (min-width: 1000px), so both fired at 1000px. The mobile breakpoint now uses width < 1000px, the exact complement of lg:, so 1000px is treated as desktop.
Open source →
1.59.311 Jun 2026
Release notes
Patch Changes
- #9396: Refactor URL redirects into a routing-agnostic, list-driven engine. Redirects now operate on the bare navigation id, so each rule works across hash, hash-base-path, and path routing automatically. Also redirect old models/<name> bookmarks to the configured models section slug when the section label is customized (e.g. schemas/).
- #9489: Do not render the info link list when no links are available.
- #9342: fix: resolve operations when OpenAPI path items use $ref
  
  Path entries and webhooks can reference components.pathItems instead of inlining operations. Navigation, mutators, search, and markdown export now resolve path-item references before reading HTTP methods and path-level parameters.
- #9498: Sync the SDK installation tabs with the operation code examples: picking a language under "Client Libraries" now switches every operation's code sample to that language's custom example
Open source →
1.59.29 Jun 2026
Release notes
Patch Changes
- #9471: Restore support for the deprecated source install command on x-scalar-sdk-installation. When set, it is appended to description as a fenced code block (or used on its own when there is no description). description remains the promoted field.
Open source →
1.59.19 Jun 2026
Release notes
Patch Changes
- #9462: fix(api-reference): align examples panel and disable sticky when narrow
Open source →
1.59.08 Jun 2026
Release notes
Minor Changes
- #9435: feat(api-reference): render AsyncAPI channel parameters
  
  Channel address parameters (the {param} placeholders in a channel address) are now shown in the API reference, reusing the same parameter list component as OpenAPI operations. Their enum, default, and examples are displayed on a string schema.
- #9438: feat(api-reference): add an AsyncAPI server selector
  
  Adds a server selector for AsyncAPI documents in the API reference introduction. It mirrors the OpenAPI server selector but works with the AsyncAPI server shape (a named map of host/protocol/pathname), labelling each server with its constructed connection URL.
  
  Server selection and variable changes are now persisted to the workspace store via new asyncapi-server:update:selected and asyncapi-server:update:variables events and their mutators, mirroring the OpenAPI wiring.
- #9422: Add a nonce option for Content Security Policy support.
  
  When you pass a nonce, the rendered HTML stamps it onto the inline <script> and the CDN <script> tag (and Scalar's own <style> tags, plus a matching <meta property="csp-nonce">). This lets the API Reference run under a strict script-src with no unsafe-inline and no unsafe-eval.
```
ApiReference({
  url: '/openapi.json',
  // Match this value in your `script-src` CSP directive.
  nonce: 'r4nd0m',
})
```
  Note: style-src still needs 'unsafe-inline'. The reference renders inline style="…" attributes, which a CSP nonce can never authorize (nonces only apply to <script>, <style> and <link> elements), so a nonce-only style-src is not possible. The win is a fully strict script-src.
- #9400: feat(api-reference): add expandAllSchemaProperties config option.
  
  When enabled, nested schema properties are expanded by default while keeping the "Show/Hide Child Attributes" button available for manual collapsing. Expansion is cycle-safe: every finite branch is expanded fully, and self-referential ($ref or inline) schemas stop at the point they would otherwise recurse forever.
- #9399: Show custom SDK installation instructions from x-scalar-sdk-installation in the introduction card, falling back to the client selector when there are none. Each entry takes a lang and a Markdown description, so a single tab can render rich instructions with syntax-highlighted code blocks (for example Maven and Gradle for Java)
Patch Changes
- #9388: Add ScalarVirtualCodeBlock component with copy button support for virtualized code blocks
- #9436: Hide the client selector for AsyncAPI documents
- #9398: feat: read code samples from x-readme, x-stainless and x-scalar extensions
  
  In addition to x-codeSamples, the code sample picker now reads custom samples from x-scalar-examples, x-stainless-snippets, x-stainless-examples, and x-readme.code-samples. When more than one is present on an operation, the highest-priority source is used (x-scalar-examples > x-stainless-snippets > x-stainless-examples > x-readme > x-codeSamples).
- #9426: feat(api-reference): render the contact URL from info.contact.url
- #8573: fix(api-reference): infer discriminator variants from mapping
- #9131: fix(api-reference): preserve OAuth redirect URI when switching OpenAPI documents
  
  When using multiple OpenAPI documents with OAuth configured via oauth2RedirectUri, switching to another document no longer clears the Redirect URL in the Authentication section.
  
  The fix threads oauth2RedirectUri from the top-level configuration into the security scheme merge chain so that each newly loaded document's OAuth flows are pre-populated with the configured redirect URI, rather than relying solely on a component-level watcher that would skip re-population when the same OAuth flow identity was detected across documents.
- #9391: fix: stabilize the tab title at the top of the document
  
  The document-start sentinel and the Introduction section both fire an intersection event at scroll-top. They resolved to different entries, so the tab title raced between the section title and the document title. The sentinel now emits the Introduction entry, so both agree.
- #9370: fix(api-reference): rework the modern operation layout with CSS grid so the request example sits directly under the description on narrow screens, and move the operation title and auth badge into the same grid
- #9421: fix(api-reference): avoid SSR hydration mismatch from the search shortcut and teleport ids
  
  The macOS search shortcut symbol was derived from navigator during render, so a Mac client hydrated ⌘ where the server sent ⌃. The platform is now resolved after mount. Teleport target ids and the search modal ids also switched from nanoid() to Vue's SSR-stable useId().
- #9392: Clean up the standalone build's injected <head> styles on destroy() so they no longer linger after SPA-style navigation (Turbo Drive, htmx). The styles are re-attached when a new instance mounts.
- #9420: fix(api-reference): make x-tagGroups titles navigable from search
  
  Tag group titles appeared as search results but clicking them did nothing, because the flattened modern layout rendered no element carrying the tag group id to scroll to. The group now exposes its id as a scroll anchor.
Open source →
1.58.02 Jun 2026
Release notes
Minor Changes
- #9372: Render AsyncAPI components.schemas as Models, listed in the sidebar and content just like OpenAPI schemas
- #7618: feat(api-reference): add setPageTitle to customize the browser tab title
  
  Pass a setPageTitle function to control the browser tab title. It is called whenever the section in view changes — on sidebar clicks, on scroll, and when switching documents — and receives the section title and the active OpenAPI document:
```
setPageTitle: ({ title, document }) => `${document.title} – ${title}`
```
Patch Changes
- #9348: Render AsyncAPI channels as sections in the content area, with the channel address as the heading and the channel description below. Channels are grouped under tags when the navigation tree groups them. Operations and messages are not rendered yet.
- #9255: Surface the Introduction entry and any headings extracted from info.description of AsyncAPI documents in the sidebar, mirroring how OpenAPI documents are handled.
- #9347: Surface AsyncAPI info.description headings in the search modal, mirroring the sidebar behaviour. AsyncAPI channels, operations, and messages are not indexed yet.
- #9350: feat(api-reference): list Ask AI and MCP Servers as Scalar Docs features in the Deploy popover
- #9310: Add an ESM standalone build (dist/browser/standalone.esm.js) alongside the existing UMD bundle. The new bundle works as a side-effect script (registers window.Scalar.createApiReference and reads data-* configuration) and exports createApiReference for direct ESM consumers. It is fully minified through Rolldown's native minifier and uses code splitting so heavy features load asynchronously after first paint:
  - The API client modal (request editor, response viewer, CodeMirror) is now await import'd inside onMounted instead of statically imported, moving ~265 KB into a chunks/modal-*.js chunk that loads in the background.
  - The Agent Scalar chat interface (already wrapped in defineAsyncComponent) becomes a real chunks/AgentScalarChatInterface-*.js chunk (~200 KB), loaded only when the agent is enabled.
  - The 84 per-icon dynamic imports from @scalar/icons/library are coalesced into a single chunks/icons-*.js.
  Net effect: initial sync load drops from ~3.32 MB (UMD) to ~2.73 MB (ESM) — a ~570 KB improvement — while total bundle size shrinks by ~140 KB.
  
  Also adds an @scalar/api-client/modal/map-hidden-clients-config deep export so consumers that only need the lightweight client-list helper don't pull the full modal barrel into their static graph.
- #9139: fix(api-reference): preserve OAuth redirect URL when switching between OpenAPI documents
  
  Auth changes were being persisted under the wrong document slug and shared a single debounce queue across all documents. When switching documents quickly, the pending save for the first document could be overwritten or dropped by a save for the second document, causing the redirect URL (and other auth secrets) to appear cleared after switching back.
  
  The fix uses event.documentName as both the debounce key and the storage key, giving each document its own independent debounce queue.
- #9194: fix(api-reference): break cycles in mergeAllOfSchemas for self-referencing schemas (whether they $ref back to themselves through array items or through a plain object property), which previously crashed the docs preview with "too much recursion"
- #9309: feat: add modelsSectionLabel configuration ('Models' | 'Schemas' | string) to use OpenAPI-style Schemas terminology in the sidebar, content, and search.
Open source →
1.57.522 May 2026
Release notes
Patch Changes
- #9318: fix: restore response content type selector when expandAllResponses is enabled
  
  Move the content type picker after the disclosure panel so it stacks above expanded response content and remains clickable when expandAllResponses is true.
Open source →
1.57.422 May 2026
Nothing published for this version
1.57.321 May 2026
Release notes
Patch Changes
- #9169: feat: add customFetch to the api-reference configuration and forward it to the API client so requests (including "Test Request" calls) use the custom fetch — enabling things like credentials: 'include'. The previous fetch option is deprecated and migrated automatically with a console warning.
- #9273: fix: render null, whitespace-only, and value/externalValue-shaped schema examples correctly
Open source →
1.57.216 May 2026
Release notes
Patch Changes
- #9234: fix(api-reference): prevent security badge from shrinking
Open source →
1.57.114 May 2026
Nothing published for this version
1.57.014 May 2026
Release notes
Minor Changes
- #9211: feat: make WorkspaceDocument an union of OpenApiDocument and AsyncApiDocument
Patch Changes
- #9211: fix(api-reference): clean up deprecated document listeners on destroy
  
  createApiReference() registered three document-level listeners (scalar:reload-references, scalar:destroy-references, scalar:update-references-config) but destroy() only unmounted the Vue app — the listeners stayed attached forever. In environments that mount and destroy instances repeatedly (notably the Astro integration's renderMode="client" with view transitions), each navigation leaked three permanent listeners on document.
  
  Tie the listeners to an AbortController and abort it from destroy() so they all come off in one shot.
- #9211: fix: show "Download AsyncAPI Document" label for AsyncAPI documents
- #9211: fix: rename the "OAS" version badge to "OpenAPI" and show an "AsyncAPI" badge for AsyncAPI documents
- #9211: fix(api-client): block invalid request URLs before send and surface buildRequest failures as results
  
  Request construction now treats a bad merged URL as a first-class failure instead of throwing deep inside helpers. After mergeUrls, resolveRequestFactoryUrl rejects incomplete targets when strict mode applies: relative URLs, an empty server base, or path strings that still contain unresolved {{variable}} placeholders. Callers may set allowMissingRequestServerBase where a full absolute URL is intentionally optional (for example the embedded modal layout in OperationBlock, or API Reference onBeforeRequest hooks that build against the document origin).
  
  buildRequest returns a Result (ok / err) with stable error codes such as MISSING_REQUEST_SERVER_BASE, INVALID_REQUEST_FACTORY_URL, and BUILD_REQUEST_FAILED for unexpected synchronous failures. Those failures are wrapped with safeRun from @scalar/helpers, which logs to console.error and maps throws to a string message on the result. The API Reference plugin path logs and skips onBeforeRequest when a preview request cannot be built, so user hooks never run against a half-built fetch payload.
  
  Downstream packages (api-client, api-reference, scalar-app where applicable) unwrap the result, show toasts or logs, and avoid calling sendRequest until the URL is valid.
- #9211: fix(api-reference): improve search ranking for parameter, request-body, and model field names, including polymorphic (oneOf/anyOf/allOf) schemas
- #9211: fix: resolve $ref in additionalProperties before rendering schema
- #9211: chore: use the new schemas
- #9211: Fix mobile sidebar z-index to ensure it appears above all content when open
- #9211: Avoid repeating request body schema descriptions above collapsed overflow properties.
- #9211: feat: add more analytics events
- #9211: fix: agent scalar warnings
- #9211: fix(api-reference): lower badge style specificity
- #9211: fix: posthog stream warning
Open source →
1.55.35 May 2026
Release notes
Patch Changes
- #9095: fix(api-reference): use overflow-wrap break-word for tag labels
Open source →
1.55.25 May 2026
Release notes
Patch Changes
- #9076: fix(api-reference): improve rendering of virtualized code blocks
- #9086: feat: code split tailwind CSS to reduce bundle size
Open source →
1.55.130 Apr 2026
Release notes
Patch Changes
- #9023: chore: use homemade slugger
Open source →
1.55.029 Apr 2026
Release notes
Minor Changes
- #9045: feat(api-reference): show an "auth required" / "auth optional" badge next to each operation's path. Requirements are resolved via operation.security ?? document.security; hover reveals the scheme names, types, and any required scopes.
Patch Changes
- #9045: fix(api-reference): flatten deepObject query parameter display in parameter rendering
- #9045: fix inline composed schema descriptions in api-reference
- #9045: fix(api-reference): ignore undefined examples on flattened deepObject parameters
- #9045: fix: remove extraneous eventBus prop from AgentScalarDrawer to eliminate Vue warning
- #9043: chore: move test documents to cdn
- #9045: chore: move scalar version logs
Open source →
1.54.029 Apr 2026
Release notes
Minor Changes
- #8970: feat(api-reference): show an "auth required" / "auth optional" badge next to each operation's path. Requirements are resolved via operation.security ?? document.security; hover reveals the scheme names, types, and any required scopes.
Patch Changes
- #8963: fix(api-reference): flatten deepObject query parameter display in parameter rendering
- #8906: fix inline composed schema descriptions in api-reference
- #8963: fix(api-reference): ignore undefined examples on flattened deepObject parameters
- #9003: fix: remove extraneous eventBus prop from AgentScalarDrawer to eliminate Vue warning
- #8987: chore: move scalar version logs
Open source →
1.53.128 Apr 2026
Nothing published for this version
1.53.027 Apr 2026
Release notes
Minor Changes
- #8772: feat: link to model from endpoints
Open source →
1.52.623 Apr 2026
Nothing published for this version
1.52.522 Apr 2026
Nothing published for this version
1.52.421 Apr 2026
Release notes
Patch Changes
- #8884: fix: restore position: fixed on .section-flare so the decorative hero flare stops reserving 100vh of empty space at the top of the documentation (affects the kepler, bluePlanet, and mars themes, which declare height: 100vh on the flare but rely on the framework to position it)
- #8907: Fix code sample missing body content type update
- #8925: chore: source vite-plugin-css-injected-by-js from the shared pnpm catalog
- #8944: feat(api-reference): add anchors and copy link buttons to allOf body parameters
Open source →
1.52.318 Apr 2026
Release notes
Patch Changes
- #8810: refactor: move telemetry to an optional plugin
- #8911: feat: switch from Request to RequestPayload to support body with GET
- #8859: refactor api-reference exports and enforce strict Vite entrypoint resolution from package exports
Open source →
1.52.216 Apr 2026
Release notes
Patch Changes
- #8827: chore: removed old client v1 code
- #8791: fix test requests so exploded array query parameters keep all values instead of collapsing to the last one
- #8863: chore: updated imports to new api client version
- #8780: fix: run intersect for the top of the document
- #8825: chore: moving files around in preparation for the big deletion of client v1
- #8831: refactor(api-reference): remove search index ts-expect-error by using typed collection access
- #8784: fix: correctly display schema names
Open source →
1.52.111 Apr 2026
Release notes
Patch Changes
- #8769: feat(themes): add Tailwind v3 transform reset
- #8767: feat(api-reference): collapse truncated descriptions
- #8776: fix: hide content type switch when there is no content
- #8777: fix(api-reference): set example z-index to context layer
- #8770: fix: generate the response examples by removing the priority order
Open source →
1.52.09 Apr 2026
Release notes
Minor Changes
- #8750: feat: display model name for body section
- #8695: feat: suport pre/post request scripts
Patch Changes
- #8431: fix: SSR breaks
- #8431: fix(api-reference): avoid duplicate app creation during hydration
- #8747: fix: extract request body from all content types in search index
Open source →
1.51.04 Apr 2026
Release notes
Minor Changes
- #8712: feat: use separate stores for client and shared state on the reference
Patch Changes
- #8728: fix: correctly merge security schemes with the config security
Open source →
1.50.03 Apr 2026
Release notes
Minor Changes
- #8524: feat: move request logic on the store and generate a request builder
- #8609: feat: display tag groups for classic layout
Patch Changes
- #8657: test(api-reference): add regression coverage for hiddenClients source switching
- #8642: refactor(api-reference): remove openapi-types dependency and align with workspace-store types
- #8659: fix search indexing to include path-level parameters and response examples for operations
- #8650: fix: ensure we have a introduction entry on the sidear by default
Open source →
1.49.831 Mar 2026
Release notes
Patch Changes
- #8628: chore: remove unused playgrounds
Open source →
1.49.729 Mar 2026
Release notes
Patch Changes
- #8612: fix: intersection observer for scroll-spy and tall sections
Open source →
1.49.628 Mar 2026
Release notes
Patch Changes
- #8599: fix(api-client): truncate long table tooltip content
- #8595: fix: deep resolve when generating examples from schema
Open source →
1.49.525 Mar 2026
Release notes
Patch Changes
- #8574: feat: make external urls configurable
- #8557: feat(api-reference): switch standalone build from terser to OXC minifier for faster builds
- #8473: fix: request body code samples when switching anyOf or oneOf schemas
Open source →
1.49.424 Mar 2026
Release notes
Patch Changes
- #8513: fix(api-reference): make responsive header rendering SSR-safe
- #8526: feat: improve filtering of client selector
- #8571: fix: [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".css" for
- #8563: fix: type declarations don't use the full path for imports
Open source →
1.49.320 Mar 2026
Release notes
Patch Changes
- #8529: rewrite declaration aliases in built type files
Open source →
1.49.220 Mar 2026
Release notes
Patch Changes
- #8509: fix: show falsy example values (false, 0) in schema property headings
- #8514: fix: invalid markup breaks ssr
Open source →
1.49.118 Mar 2026
Release notes
Patch Changes
- #8466: chore: new build pipeline
- #8479: fix: render schema property examples when values are falsy
Open source →
1.49.017 Mar 2026
Release notes
Minor Changes
- #8409: feat: lazy rendering
Patch Changes
- #8443: fix hash-prefixed basePath routing
- #8467: feat(api-reference): improve Ask AI button consistency and a11y
- #8442: fix object schema descriptions in parameter rendering
Updated Dependencies
- @scalar/[email protected]
  - #8468: fix: ignore response examples when generating navigation
- @scalar/[email protected]
  - #8468: fix: example extraction, environment navigation and general UI fixes
  - #8451: fix(api-client): default-close auth when not required
- @scalar/[email protected]
  - #8448: fix parser validation for unused path parameters
- @scalar/[email protected]
  - #8453: refactor: remove @ts-expect-error from ScalarTextArea
- @scalar/[email protected]
- @scalar/[email protected]
- @scalar/[email protected]
Open source →
1.48.815 Mar 2026
Release notes
Patch Changes
- #8425: fix auth default OAuth scope fallback
- #8416: fix: direct css import breaks build in react, vitepress and others
- #8417: fix: document not defined in SSR environments
Updated Dependencies
- @scalar/[email protected]
  - #8444: feat: cache last response for an example
  - #8424: fix(api-client): persist oauth credentials location
  - #8428: fix: overflow issues for mac app version
  - #8447: fix: propagate schema to request body form-data table
- @scalar/[email protected]
  - #8416: fix: direct css import breaks build in react, vitepress and others
- @scalar/[email protected]
  - #8424: feat: export XScalarCredentialsLocation
  - #8445: fix: generate unique id for models
- @scalar/[email protected]
- @scalar/[email protected]
- @scalar/[email protected]
Open source →
1.48.713 Mar 2026
Release notes
Patch Changes

Updated Dependencies
- @scalar/[email protected]
  - #8426: feat: interact with the original and intermediate documents
- @scalar/[email protected]
  - #8426: feat: sync with source flow with conflict resolution
- @scalar/[email protected]
- @scalar/[email protected]
- @scalar/[email protected]
- @scalar/[email protected]
Open source →
1.48.612 Mar 2026
Release notes
Patch Changes
- #8414: fix(api-reference): limit height of example response descriptions
Updated Dependencies
- @scalar/[email protected]
  - #8414: fix(api-client): pass example picker attributes to button component
- @scalar/[email protected]
  - #8327: fix: markdown tables with specified width attributes in td/th break the layout
- @scalar/[email protected]
  - #8420: fix TypeScript access to navigator.userAgentData in isMacOS without ts-expect-error
- @scalar/[email protected]
- @scalar/[email protected]
- @scalar/[email protected]
- @scalar/[email protected]
- @scalar/[email protected]
- @scalar/[email protected]
- @scalar/[email protected]
Open source →
1.48.511 Mar 2026
Release notes
Patch Changes
- #8406: feat: x-order
- #8097: fix: lazy load compositions
- #8380: feat(api-reference): render <a> HTML tag for documentDownloadType: direct
Updated Dependencies
- @scalar/[email protected]
  - #8393: fix: correctly update active tab on tab close event
  - #8403: Persist auth url and token url in local storage
- @scalar/[email protected]
  - #8403: Persist auth url and token url in local storage
  - #8402: Fix raw binary request bodies so uploaded files are sent correctly and code samples show file references.
  - #8398: fix code snippet HAR request URL generation to URL-encode substituted path parameter values, matching request sending behavior.
  - #8386: feat: app drag region for macos
  - #8408: Use the secret oauth urls before the default flow urls
  - #8407: Fix conditional rendering for token URL
- @scalar/[email protected]
  - #8404: Preserve duplicate query parameters in generated code snippets. php/guzzle: preserve duplicate query parameters as arrays.
- @scalar/[email protected]
  - #8386: feat: add spacer slot to sidebar
- @scalar/[email protected]
- @scalar/[email protected]
- @scalar/[email protected]
Open source →
1.48.410 Mar 2026
Release notes
Patch Changes

Updated Dependencies
- @scalar/[email protected]
  - #8396: feat: preselect correct authentication for document and operation
  - #8394: chore: rollback export document button
- @scalar/[email protected]
Open source →

@scalar/api-reference

Release timeline

Releases

Minor Changes

Patch Changes

Patch Changes

Minor Changes

Patch Changes

Patch Changes

Minor Changes

Patch Changes

Minor Changes

Patch Changes

Patch Changes

Patch Changes

Patch Changes

Patch Changes

Patch Changes

Minor Changes

Patch Changes

Minor Changes

Patch Changes

Minor Changes

Patch Changes

Patch Changes

Patch Changes

Patch Changes

Minor Changes

Patch Changes

Minor Changes

Patch Changes

Patch Changes

Patch Changes

Patch Changes

Minor Changes

Patch Changes

Patch Changes

Patch Changes

Patch Changes

Minor Changes

Patch Changes

Minor Changes

Patch Changes

Minor Changes

Patch Changes

Patch Changes

Patch Changes

Patch Changes

Minor Changes

Patch Changes

Minor Changes

Patch Changes

Minor Changes

Patch Changes

Patch Changes

Patch Changes

Patch Changes

Patch Changes

Patch Changes

Patch Changes

Patch Changes

Patch Changes

Minor Changes

Patch Changes

Updated Dependencies

Patch Changes

Updated Dependencies

Patch Changes

Updated Dependencies

Patch Changes

Updated Dependencies

Patch Changes

Updated Dependencies

Patch Changes

Updated Dependencies