mintlify__docs/organize/settings-api.mdx

---
title: "API settings"
description: "Configure OpenAPI and AsyncAPI specs, the interactive playground, code examples, and authentication in `docs.json`."
keywords: ["api", "openapi", "asyncapi", "playground", "docs.json", "api reference"]
---

Use the `api` field in `docs.json` to configure what API specifications are available to generate API pages from; the interactive API playground users can test API endpoints with; and how to generate and display code examples.

## Settings

### `api`

**Type:** `object`

Define all API-related settings under the `api` key.

<ResponseField name="api.openapi" type="string or array or object">
  OpenAPI specification files for generating API reference pages. Accepts a single path or URL, an array of paths and URLs, or an object specifying a source and directory.

  <Expandable title="api.openapi object">
    <ResponseField name="source" type="string">
      URL or path to your OpenAPI specification file. Minimum length: 1.
    </ResponseField>
    <ResponseField name="directory" type="string">
      Directory to search for OpenAPI files. Do not include a leading slash.
    </ResponseField>
  </Expandable>

  <CodeGroup>

  ```json Single file
  "openapi": "openapi.json"
  ```

  ```json Multiple files
  "openapi": [
    "openapi/v1.json",
    "openapi/v2.json",
    "https://api.example.com/openapi.yaml"
  ]
  ```

  ```json Directory
  "openapi": {
    "source": "openapi.json",
    "directory": "api-reference"
  }
  ```

  </CodeGroup>
</ResponseField>

<ResponseField name="api.asyncapi" type="string or array or object">
  AsyncAPI specification files for generating event-driven API reference pages. Accepts a single path or URL, an array of paths and URLs, or an object specifying a source and directory.

  <Expandable title="api.asyncapi object">
    <ResponseField name="source" type="string">
      URL or path to your AsyncAPI specification file. Minimum length: 1.
    </ResponseField>
    <ResponseField name="directory" type="string">
      Directory to search for AsyncAPI files. Do not include a leading slash.
    </ResponseField>
  </Expandable>

  <CodeGroup>

  ```json Single file
  "asyncapi": "asyncapi.json"
  ```

  ```json Multiple files
  "asyncapi": [
    "asyncapi/events.yaml",
    "asyncapi/webhooks.yaml"
  ]
  ```

  ```json Directory
  "asyncapi": {
    "source": "asyncapi.json",
    "directory": "websockets"
  }
  ```

  </CodeGroup>
</ResponseField>

<ResponseField name="api.playground" type="object">
  Interactive API playground settings.

  <Expandable title="api.playground">
    <ResponseField name="display" type='"interactive" | "simple" | "none" | "auth"'>
      The display mode for the playground. Defaults to `interactive`.

      - `interactive` — Full interactive playground with request builder
      - `simple` — Simplified view without the request builder
      - `none` — Hide the playground entirely
      - `auth` — Show the playground only to authenticated users
    </ResponseField>
    <ResponseField name="proxy" type="boolean">
      Whether to route API requests through a proxy server. Defaults to `true`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="api.params" type="object">
  Display settings for API parameters.

  <Expandable title="api.params">
    <ResponseField name="expanded" type='"all" | "closed"'>
      Whether to expand all parameters by default. Defaults to `closed`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="api.url" type='"full"'>
  Display mode for the base URL in the endpoint header. Set to `full` to always show the complete base URL on every endpoint page. By default, the base URL is only shown when there are multiple base URLs to select from.
</ResponseField>

<ResponseField name="api.examples" type="object">
  Settings for autogenerated API code examples.

  <Expandable title="api.examples">
    <ResponseField name="languages" type="array of string">
      Languages for autogenerated code snippets. See [supported languages](/api-playground/overview#all-supported-languages) for the full list of available languages and aliases.
    </ResponseField>
    <ResponseField name="defaults" type='"required" | "all"'>
      Whether to include optional parameters in generated examples. Defaults to `all`.
    </ResponseField>
    <ResponseField name="prefill" type="boolean">
      Whether to prefill the playground with example values from your OpenAPI specification. Defaults to `false`.
    </ResponseField>
    <ResponseField name="autogenerate" type="boolean">
      Whether to generate code samples for endpoints from your API specification. Defaults to `true`. When set to `false`, only manually written code samples (from `x-codeSamples` in OpenAPI or `<RequestExample>` components in MDX) appear in the playground.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="api.spec" type="object">
  OpenAPI specification display settings. Including the download button on API reference pages.

  <Expandable title="api.spec">
    <ResponseField name="download" type="boolean">
      Whether to show a download button for the OpenAPI spec on API reference pages. Defaults to `false`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="api.mdx" type="object">
  Settings for API pages built from MDX files rather than OpenAPI specs.

  <Expandable title="api.mdx">
    <ResponseField name="auth" type="object">
      Authentication configuration for MDX-based API requests.

      <Expandable title="auth">
        <ResponseField name="method" type='"bearer" | "basic" | "key" | "cobo"'>
          Authentication method for API requests.
        </ResponseField>
        <ResponseField name="name" type="string">
          Authentication parameter name for API requests.
        </ResponseField>
      </Expandable>
    </ResponseField>
    <ResponseField name="server" type="string or array">
      Base URL prepended to relative paths in page-level `api` frontmatter fields. Not used when the frontmatter contains a full URL.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

```json docs.json
{
  "api": {
    "openapi": ["openapi/v1.json", "openapi/v2.json"],
    "playground": {
      "display": "interactive"
    },
    "params": {
      "expanded": "all"
    },
    "url": "full",
    "examples": {
      "languages": ["curl", "python", "javascript", "go"],
      "defaults": "required",
      "prefill": true,
      "autogenerate": true
    },
    "spec": {
      "download": true
    }
  }
}
```