OpenAPI Specification

We're expecting the passed OpenAPI document to adhere to the Swagger 2.0, OpenAPI 3.0, OpenAPI 3.1 or OpenAPI 3.2 specification.

On top of that, we've added a few things for your convenience:

Editor completion and version compatibility

The Scalar App editor offers OpenAPI 3.2 completion and structural diagnostics for documents declaring either OpenAPI 3.1 or 3.2. This permissive editing policy helps you work with newer fields, but the absence of editor errors does not certify that a document conforms to its declared OpenAPI version.

For example, the editor accepts itemSchema, additionalOperations, and style: cookie even when the document still declares openapi: 3.1.0. Those fields are not part of OpenAPI 3.1, and tools that validate that version may reject the document. Editor completion does not automatically change the declared version.

Before using OpenAPI 3.2-only fields, migrate the document to OpenAPI 3.2 and explicitly set a matching version such as openapi: 3.2.0. Check that your validators, generators, and other consumers support that version, and validate the resulting document with a validator that respects the declared version. If you need to remain compatible with OpenAPI 3.1 consumers, keep the declaration and field usage within OpenAPI 3.1.

Whole-query parameters (OpenAPI 3.2)

An in: querystring parameter describes the entire query string. Its name is documentary and is not added to the request URL. Scalar uses the parameter's content media type to serialize its value.

For content other than application/x-www-form-urlencoded, Scalar percent-encodes the serialized value, including JSON delimiters. For example, a JSON value of {"limit":2} produces ?%7B%22limit%22%3A2%7D in both requests and generated code samples.

To supply URI-ready content with its encoding preserved, set serializedValue in an example on the parameter itself:

parameters:
  - name: search
    in: querystring
    required: true
    content:
      application/json:
        schema:
          type: object
          properties:
            limit:
              type: integer
    examples:
      default:
        serializedValue: '%7B%22limit%22%3A2%7D'

A serializedValue under a media type describes serialized media content and still undergoes URI encoding. The parameter-level example bypasses that step; provide any escaping required by the target server and HTTP client yourself.

OpenAPI 3.2 does not allow mixing in: querystring and named in: query parameters. For existing descriptions containing both, Scalar preserves the values and emits the whole-query content first, followed by named query parameters and query authentication parameters. Duplicate keys are preserved: a whole-query status=available and a named status=sold produce ?status=available&status=sold. Scalar does not choose which value wins; that depends on the receiving server. The editor explains why additional named parameters cannot be added while keeping existing rows editable.

Custom Specification Extensions

You can add custom specification extensions (starting with a x-) through our plugin API.

x-scalar-environments

You can specify predefined environment variables for the API Client/References to consume and use:

x-scalar-environments:
  production:
    description: 'Production environment'
    color: '#0082D0'
    # Variables are saved directly to the specification
    variables:
      userId:
        description: 'User ID'
        default: '1234567890'
      apiUrl:
        description: 'API URL'
        default: 'https://api.production.example.com'
  staging:
    description: 'Staging environment'
    variables:
      userId: '1234567890'
      apiUrl:
        description: 'API URL'
        default: 'https://api.staging.example.com'

x-scalar-active-environment

You can also specify the default active environment a user will have :) if there's none set here we pick the first from the x-scalar-environments to be the default

x-scalar-active-environment: staging

x-codeSamples

x-codeSamples and its legacy spelling x-code-samples also support a code file as the source:

openapi: 3.1.0
info: { title: Code samples, version: '1' }
paths:
  /pets:
    get:
      x-codeSamples:
        - lang: Python
          source:
            $ref: ./code/list-pets.py
      responses:
        '200': { description: OK }

Scalar loads the whole file as source text, preserving its formatting. Relative paths resolve against the API description that contains the operation. In-memory descriptions need a source URL to resolve relative files. A server-preprocessed operation can load its code file when the operation is loaded lazily. Local file references require a configured file loader.

Code files use the same network and filesystem controls as other external references. On the server, local files require documentLoading.basePath, and traversal and symlink escapes outside that directory are refused. A client running in Node uses the host-provided fileLoader; configure its basePath when using readFiles to confine reads. Any file readable by that loader can become sample text, regardless of its extension. Fetched code files have no built-in size limit, just like other external references.

If a file cannot be loaded, the sample is unavailable and its reference is retained. JSON Pointer fragments, such as #/components/schemas/Pet, are not code-file sources. Only these two extensions load code files; $ref keys in other extensions and example data remain literal.

We provide examples for a lot of popular HTTP clients and frameworks. For something completely custom, for example to show the use of your own SDK, you can use x-codeSamples:

openapi: 3.1.0
info:
  title: Val Town API
  version: 1.0
paths:
  '/v1/eval':
    post:
+      x-codeSamples:
+      - label: ValTown JS SDK
+        lang: JavaScript
+        source: |-
+          import ValTown from '@valtown/sdk';
+
+          const valTown = new ValTown();
+
+          async function main() {
+            const valRunAnonymousResponse = await valTown.vals.runAnonymous({ code: 'console.log(1);' });
+
+            console.log(valRunAnonymousResponse);
+          }
+
+          main();

Set example to a key in requestBody.content[contentType].examples and set contentType to that media type. Samples with the same lang and label share one language option. The example switcher chooses the matching sample without changing the selected language.

openapi: 3.1.0
info: { title: Widgets API, version: '1.0' }
paths:
  /widgets:
    post:
      requestBody:
        content:
          application/json:
            schema: { type: object }
            examples:
              simple: { value: { name: Basic } }
              detailed: { value: { name: Premium, description: More features } }
      responses:
        '200': { description: Created }
      x-codeSamples:
        - lang: Python
          example: simple
          contentType: application/json
          source: client.widgets.create(name="Basic")
        - lang: Python
          example: detailed
          contentType: application/json
          source: client.widgets.create(name="Premium", description="More features")

The same fields work with x-scalar-examples, x-code-samples, and x-custom-examples. Omit contentType to use a sample for any media type with that example key. The contentType must exactly match the request body media type key, including any parameters: application/json; charset=utf-8 does not match application/json. Static samples without example keep their own language-menu entries. Their source stays unchanged when switching body examples, but the switcher still controls which example opens in Test Request. If a linked sample is missing for the selected example, Scalar displays an unavailable message.

Code samples from other tools

If your OpenAPI document is generated by another tool, we also read code samples from the extensions those tools write. When more than one of these is present on an operation, we use the highest-priority source only (instead of showing duplicates from every tool). Priority, highest first:

  1. x-scalar-examples
  2. x-stainless-snippets (overrides x-stainless-examples)
  3. x-stainless-examples
  4. x-readme (via x-readme.code-samples)
  5. x-codeSamples / x-code-samples / x-custom-examples

x-scalar-examples uses the same shape as x-codeSamples (a list of lang / label / source entries):

paths:
  '/accounts':
    get:
      x-scalar-examples:
        - lang: python
          label: List accounts
          source: client.accounts.list()

x-stainless-examples is an example (or array of examples) with an optional title and a request map of source code keyed by language. The title is used as the label in the picker.

paths:
  '/accounts':
    get:
      x-stainless-examples:
        title: List active accounts
        request:
          python: client.accounts.list(status="active")
          node: await client.accounts.list({ status: 'active' });

x-stainless-snippets is a map of source code keyed by language:

paths:
  '/accounts':
    get:
      x-stainless-snippets:
        python: client.accounts.list()
        node: await client.accounts.list();

x-readme.code-samples is a list of samples using ReadMe's field names (language, code, name). ReadMe's correspondingExample refers to a response example, so it is not used to link samples to request body examples:

paths:
  '/accounts':
    get:
      x-readme:
        code-samples:
          - language: curl
            name: Custom cURL
            code: curl https://api.example.com/accounts

Custom sample groups

Set group on individual samples to give them separate headings in the code sample picker, for example an SDK and a CLI:

openapi: 3.1.0
info:
  title: Sample groups
  version: 1.0.0
paths:
  /pets:
    get:
      responses:
        '200':
          description: A list of pets
      x-codeSamples:
        - lang: python
          label: Python
          group: SDK
          source: client.pets.list()
        - lang: shell
          label: Command line
          group: CLI
          source: example-cli pets list

Groups appear in the order they first occur. Samples without a group, or with a blank group, keep the existing default heading. Grouping does not change IDs of unlinked samples or the priority between code sample extensions. Linked request examples share an ID only when their language, label, and group match. The same field is supported on x-scalar-examples, x-code-samples, and x-custom-examples entries.

Credentials in custom code samples

Use x-scalar-credential-placeholders on a security scheme to insert the reader's current credentials into custom code samples. Each name matches a case-sensitive {{name}} placeholder. Names may contain letters, digits, underscores, dots, and hyphens, and must start with a letter or underscore.

openapi: 3.1.0
info:
  title: Credential examples
  version: 1.0.0
security:
  - account: []
paths:
  /pets:
    get:
      responses:
        '200':
          description: A list of pets
      x-codeSamples:
        - lang: python
          source: client = ExampleClient("{{accountId}}", "{{apiKey}}")
components:
  securitySchemes:
    account:
      type: http
      scheme: basic
      x-scalar-credential-placeholders:
        accountId:
          field: username
          mask: false
        apiKey:
          field: password

Available fields are token for API keys and bearer authentication, username and password for basic authentication, and token, clientId, clientSecret, username, and password where available in OAuth2 or OpenID Connect. OAuth placeholders use the first flow with an access token, matching request authentication; other flows are not used.

Values are masked by default in the displayed example. Copy includes their real values, matching generated code samples. Set mask: false only for public values such as an account ID. If a public value is also a secret elsewhere in the selected schemes, it remains masked.

Only the operation's selected authentication schemes supply values. Unknown names, missing credentials, and names declared by multiple selected schemes remain unchanged. Samples update when credentials change, while the original API description keeps its placeholders. Replacement is literal and happens once: it does not evaluate expressions, escape programming-language strings, or expand placeholders contained in credentials. Choose sample syntax appropriate for the credential format your API accepts.

x-example / x-examples

For Swagger 2.0 documents, we support x-example and x-examples extensions on body parameters. These bring OpenAPI 3.x example functionality to older specifications.

Use x-example for a single example value:

swagger: '2.0'
paths:
  '/planets':
    post:
      consumes:
        - application/json
      parameters:
        - in: body
          name: body
          schema:
            type: object
          x-example:
            application/json:
              name: Earth

Use x-examples for multiple named examples with summaries:

swagger: '2.0'
paths:
  '/planets':
    post:
      consumes:
        - application/json
      parameters:
        - in: body
          name: body
          schema:
            type: object
          x-examples:
            application/json:
              earth-example:
                summary: Earth planet
                value:
                  name: Earth
              mars-example:
                summary: Mars planet
                value:
                  name: Mars

externalValue

externalValue is a standard OpenAPI field on an Example Object. It lets you keep large request or response examples outside of your OpenAPI document and point to them by URL instead. This is useful when a single document would otherwise contain hundreds or thousands of big example payloads.

Scalar fetches an external example only when its selected preview becomes visible or you open it in Test Request. Other examples, including examples on hidden operations, are not downloaded during document loading. The request preview, generated code snippets, and Test Request use the same resolved payload.

Successful downloads are cached for the loaded document. Selecting an example again reuses its payload; replacing the document clears the cache. While an example loads, Scalar shows a loading message. If the download fails, you can retry. Sending the request is disabled until its selected example is ready.

paths:
  '/shipments':
    post:
      requestBody:
        content:
          application/json:
            examples:
              shipper-standard:
                summary: Shipper Standard
                externalValue: /examples/post-shipment/shipper-standard.json

The referenced endpoint returns the raw example payload:

{
  "shippingType": "Shipper_001",
  "packages": []
}

A few things to keep in mind:

  • value and externalValue are mutually exclusive. If both are present, value is used.
  • Relative URLs (like the one above) are resolved against the URL your document was loaded from.
  • The referenced URL must be reachable by the browser (CORS applies), and should return JSON or YAML.

Nested tags (OpenAPI 3.2)

In OpenAPI 3.2, you can nest tags with the native parent field instead of x-tagGroups. Set parent to the name of another tag declared in the document. Tags can be nested across multiple levels, and a parent tag can have operations of its own alongside its child tags.

Use summary for a readable tag title in the navigation and section headings. Operations still reference the tag's name. If x-displayName is also set, it takes precedence over summary.

openapi: 3.2.0
info:
  title: Example
  version: '1.0.0'
tags:
  - name: galaxy
    summary: Galaxy
  - name: planets
    summary: Planets
    parent: galaxy
  - name: moons
    summary: Moons
    parent: planets
paths:
  /planets:
    get:
      summary: Get all planets
      tags:
        - planets
      responses:
        '200':
          description: A list of planets
  /moons:
    get:
      summary: Get all moons
      tags:
        - moons
      responses:
        '200':
          description: A list of moons

This creates the hierarchy Galaxy → Planets → Moons. The Planets section contains both its own operation and the nested Moons section.

When at least one parent relationship points to a declared tag without forming a cycle, Scalar uses native nesting for the document instead of x-tagGroups. Unknown parents, self-references, and circular relationships do not create nesting. If no valid nesting relationship remains, Scalar falls back to x-tagGroups.

x-displayName

You can overwrite tag names with x-displayName.

openapi: 3.1.0
info:
  title: Example
  version: 1.0
tags:
  - name: pl4n3t5
+    x-displayName: planets
paths:
  '/planets':
    get:
      summary: Get all planets
      tags:
        - pl4n3t5

In the modern sidebar, every tag with children can be expanded or collapsed, including parent tags at any nesting depth. Collapsing a parent preserves the expansion state of its children. Deep links and search results open the ancestors of the target. The defaultOpenFirstTag and defaultOpenAllTags configuration options also apply to parent tags and tag groups.

x-tagGroups

You can group your tags with x-tagGroups. This remains supported for existing API descriptions and OpenAPI versions before 3.2. For OpenAPI 3.2, use native nested tags with parent instead.

openapi: 3.1.0
info:
  title: Example
  version: 1.0
tags:
  - name: planets
+x-tagGroups:
+  - name: galaxy
+    tags:
+      - planets
paths:
  '/planets':
    get:
      summary: Get all planets
      tags:
        - planets

x-scalar-ignore

You can hide operations and webhooks from the reference with x-scalar-ignore.

openapi: 3.1.0
info:
  title: Example
  version: 1.0
paths:
  '/planets':
    get:
      summary: Get all planets
    post:
      summary: Create a new planet
+      x-scalar-ignore: true

Or to hide a tag and the operations under it:

openapi: 3.1.0
info:
  title: Example
  version: 1.0
tags:
  - name: planets
+    x-scalar-ignore: true
paths:
  '/planets':
    get:
      summary: Get all planets
      tags:
        - planets
    post:
      summary: Create a new planet
      tags:
        - planets

You can also hide authentication. Add x-scalar-ignore to a whole security scheme to drop it from the auth selector, or to a single OAuth2 flow to hide just that flow's tab. This is handy for flows that cannot run in the browser, like Client Credentials, which usually fails on CORS:

components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/authorize
          tokenUrl: https://auth.example.com/token
          scopes: {}
        clientCredentials:
          tokenUrl: https://auth.example.com/token
          scopes: {}
          x-scalar-ignore: true

Aliases: x-internal

x-additionalPropertiesName

OpenAPI allows description of "additionalProperties" that may be included in a schema. Their names are unknown, but the field types can be added to the API description so that producers and consumers understand whether additional fields are permitted and any additional rules that apply.

Since the field names are not specified, they are displayed with a generic name in the API reference documentation. Use x-additionalPropertiesName to display a more meaningful name in this scenario.

The following example shows a schema that accepts any fields as long as the values are numbers between 0-100, for a set of sensors reporting fill levels:

components:
  schemas:
    FillLevel:
      type: object
      properties:
        reportTime:
          type: string
          format: date-time
          description: Report creation time.
      required:
        - reportTime
      additionalProperties:
        x-additionalPropertiesName: percentage
        type: integer
        minimum: 0
        maximum: 100

The additional properties appear in the documentation as percentage*.

x-order

You can control the display order of schema properties with x-order. Properties with x-order are sorted by their numeric value (ascending) and displayed before properties without x-order.

openapi: 3.1.0
info:
  title: Example
  version: 1.0
components:
  schemas:
    Planet:
      type: object
      properties:
        name:
          type: string
+          x-order: 1
        description:
          type: string
+          x-order: 3
        diameter:
          type: number
+          x-order: 2

In this example, properties will be displayed in the order: name, diameter, description.

x-order also controls the order of OAuth2 flow tabs in the auth section. Flows with a lower x-order appear first, and the first tab is selected by default — so giving a flow the lowest x-order both moves it to the front and makes it the default:

components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://auth.example.com/authorize
          scopes: {}
          x-order: 2
        authorizationCode:
          authorizationUrl: https://auth.example.com/authorize
          tokenUrl: https://auth.example.com/token
          scopes: {}
          x-order: 1

Here the authorizationCode tab appears first and is selected by default.

x-scalar-stability

You can show the stability of an endpoint by setting the x-scalar-stability to either stable, experimental or deprecated. The native deprecated property will take precedence.

openapi: 3.1.0
info:
  title: Example
  version: 1.0
paths:
  '/planets':
    get:
      summary: Get all planets
    post:
      summary: Create a new planet
+      x-scalar-stability: 'experimental'

x-badges

You can add badges to operations to use as indicators in documentation. Each operation can have multiple badges, and the displayed color is also configurable. The following example sets badges on the GET /hello-world operation:

openapi: 3.1.0
info:
  title: x-badges
  version: 1.0.0
paths:
  /hello-world:
    get:
      summary: Hello World
+      x-badges:
+        - name: 'Alpha'
+        - name: 'Beta'
+          position: before
+        - name: 'Gamma'
+          position: after
+          color: '#ffcc00'
Option Type Description
name string REQUIRED. The text that displays in the badge.
position string The position of the badge in relation to the header. Possible values: before, after. The default value is after.
color string The color of the badge. It can be defined in various formats such as color keywords, RGB, RGBA, HSL, HSLA, and Hexadecimal.

Badges in the sidebar

Set showBadgesInSidebar to also show the badges next to the titles in the sidebar. In the sidebar, x-badges work on every level: operations, webhooks, tags (including nested OpenAPI 3.2 tags), x-tagGroups entries and schemas in components.schemas.

openapi: 3.1.0
info:
  title: x-badges
  version: 1.0.0
x-tagGroups:
  - name: Core
    tags: [Users]
+    x-badges:
+      - name: 'Stable'
tags:
  - name: Users
+    x-badges:
+      - name: 'Beta'
+        color: '#f59e0b'
paths:
  /users:
    get:
      summary: Get users
      tags: [Users]
+      x-badges:
+        - name: 'New'
+          color: '#22c55e'

x-enum-descriptions

You can add descriptions to enum values with x-enum-descriptions:

openapi: 3.1.0
info:
  title: Example
  version: 1.0
components:
  schemas:
    CustomerCancellationReason:
      type: string
      enum:
      - missing_features
      - too_expensive
      - unused
      - other
+      x-enum-descriptions:
+        missing_features: Missing features
+        too_expensive: Too expensive
+        unused: Unused
+        other: Other

Aliases: x-enumDescriptions

x-enum-varnames

You can provide variable names for enum values with x-enum-varnames. These names will be displayed alongside the enum values in the format value = varname:

openapi: 3.1.0
info:
  title: Example
  version: 1.0
components:
  schemas:
    HttpStatusCode:
      type: integer
      enum:
      - 100
      - 200
      - 300
      - 400
      - 500
+      x-enum-varnames:
+      - Continue
+      - OK
+      - MultipleChoices
+      - BadRequest
+      - InternalServerError

This will display as: 100 = Continue, 200 = OK, 300 = MultipleChoices, etc.

Aliases: x-enumNames

x-scalar-sdk-installation

We generate custom code examples for all languages, but you might have a custom SDK for your API. Provide installation instructions in the header and they replace the generic HTTP clients in the introduction.

Set showDefaultClientsWithSdkInstallation to true to show SDK tabs and built-in HTTP clients together in the same card.

Each entry has a lang (used to pick a matching language icon and synchronize code sample selection) and a description. Set an optional label to customize the tab text, for example lang: python with label: Python SDK. If label is missing or blank, the tab displays lang. The description supports Markdown, including fenced code blocks with syntax highlighting, so a single tab can show multiple snippets (for example Maven and Gradle for Java).

openapi: 3.1.0
info:
  title: Example
  version: 1.0
+  x-scalar-sdk-installation:
+  - lang: TypeScript
+    description: |-
+      Install our **Custom SDK** from npm:
+
+      ```sh
+      npm install @your-awesome-company/sdk
+      ```
+  - lang: Java
+    description: |-
+      Add the dependency with Maven:
+
+      ```xml
+      <dependency>
+        <groupId>com.your-awesome-company</groupId>
+        <artifactId>sdk</artifactId>
+        <version>1.0.0</version>
+      </dependency>
+      ```
+
+      …or with Gradle:
+
+      ```groovy
+      implementation 'com.your-awesome-company:sdk:1.0.0'
+      ```
Option Type Description
lang string REQUIRED. The language or platform of the SDK (for example TypeScript, Java, Python).
label string Optional display text for the SDK tab. Defaults to lang when omitted or blank.
description string The installation instructions for this language. Supports Markdown, including fenced code blocks.

Credentials in installation instructions

SDK installation instructions support the same {{name}} placeholders as custom code samples. Declare mappings with x-scalar-credential-placeholders on a security scheme, then enter credentials in the authentication panel. Installation instructions use the document's current authentication selection.

openapi: 3.1.0
info:
  title: Example API
  version: 1.0.0
  x-scalar-sdk-installation:
    - lang: shell
      description: |
        Configure the CLI:
        ```sh
        example-cli configure --api-key "{{apiKey}}"

security:

  • apiKey: [] components: securitySchemes: apiKey: type: apiKey in: header name: X-API-Key x-scalar-credential-placeholders: apiKey: field: token paths: {}
Placeholders work in ordinary Markdown text, inline code, fenced code blocks, and the legacy `source` field. Secret values appear masked; a code block's copy button copies the real value. Set `mask: false` in a mapping only for public identifiers. Missing or ambiguous values keep their placeholders.

Substituted values are literal text. They cannot create Markdown formatting, HTML, or new code blocks. Link destinations, raw HTML blocks, and paragraphs containing inline HTML are not substituted. The original API description remains unchanged.

## x-scalar-links

Add named links next to the contact, license and terms of service links in the introduction. This is handy for the legal texts that some countries require on public websites, like a privacy policy or an imprint.

```diff
openapi: 3.1.0
info:
  title: Example
  version: 1.0
+  x-scalar-links:
+  - name: Privacy Policy
+    url: https://example.com/privacy
+  - name: Imprint
+    url: https://example.com/imprint
Option Type Description
name string REQUIRED. The label to display for the link.
url string REQUIRED. The URL the link points to.

x-pre-request

Add pre-request scripts to operations or at the document level. Scripts run before the request is sent and can modify headers, set variables, or prepare authentication. See Scripts in the API Client for the full guide.

On an operation:

openapi: 3.1.0
info:
  title: Example
  version: 1.0
paths:
  '/users':
    get:
      summary: Get all users
+      x-pre-request: |-
+        pm.environment.set('timestamp', new Date().toISOString())

On the document (runs before every operation):

openapi: 3.1.0
info:
  title: Example
  version: 1.0
+x-pre-request: |-
+  pm.request.headers.add({
+    key: 'X-Request-Id',
+    value: 'req-' + Date.now()
+  })

When both document-level and operation-level scripts are present, the document-level script runs first.

x-post-response

Add post-response scripts to operations to automatically validate API responses. Scripts use a Postman-compatible syntax and run after each request in the API Client.

openapi: 3.1.0
info:
  title: Example
  version: 1.0
paths:
  '/planets':
    get:
      summary: Get all planets
+      x-post-response: |-
+        pm.test("Status code is 200", () => {
+          pm.response.to.have.status(200)
+        })

You can add multiple assertions in a single script:

openapi: 3.1.0
info:
  title: Example
  version: 1.0
paths:
  '/planets':
    post:
      summary: Create a planet
+      x-post-response: |-
+        pm.test("Returns 201", () => {
+          pm.expect(pm.response.code).to.be.oneOf([201, 202])
+        })
+        pm.test("Response is valid JSON", () => {
+          const data = pm.response.json()
+          pm.expect(data).to.be.an('object')
+        })

See Testing in the API Client for all available assertions and the full pm API reference.

XML examples

XML examples use the schema's xml metadata for element names, attributes, namespaces, and array wrappers. Automatic generation has depth and node limits to keep large API descriptions responsive. When a response example exceeds these limits, the response panel explains that a complete serialized example is needed.

To display an existing XML payload without generating a tree, use an OpenAPI 3.2 media-level serializedValue. It is preserved exactly, including whitespace:

openapi: 3.2.0
info:
  title: XML example
  version: 1.0.0
paths:
  /pets:
    get:
      responses:
        '200':
          description: Pets
          content:
            application/xml:
              examples:
                pets:
                  serializedValue: '<pets><pet id="1">Milo</pet></pets>'

For OpenAPI 3.0 or 3.1, use a string value in the media-level Example Object. Schema-level string examples represent data and are escaped as XML text.

Header API-key token prefixes

Set x-scalar-token-prefix on a header API-key security scheme to add a prefix to generated code samples and outgoing requests:

openapi: 3.0.3
info:
  title: Token authentication
  version: 1.0.0
security:
  - tokenAuth: []
paths:
  /me:
    get:
      responses:
        '200':
          description: Current user
components:
  securitySchemes:
    tokenAuth:
      type: apiKey
      in: header
      name: Authorization
      x-scalar-token-prefix: token

Readers enter the raw credential, for example abc. Scalar sends Authorization: token abc. With no credential, generated samples show token YOUR_SECRET_TOKEN; actual requests do not send a prefix by itself.

When a prefix is configured, the prefix and outgoing credential are trimmed and separated by one space. Whitespace-only credentials do not send a prefix. Stored credentials remain unchanged: entering token abc with the prefix token produces token token abc. Environment variables in credentials are resolved before the prefix is added. The prefix is ignored for query and cookie API keys and does not affect HTTP Basic, Bearer, or OAuth authentication.

What did you think of this content?