API Explorer

The API Explorer renders OpenAPI specifications as interactive API documentation. When you configure it in your content set, docs-builder automatically generates pages for each API operation, request and response schemas, shared type definitions, and inline examples.

Add the api key to your docset.yml file to enable the API Explorer. Each product key takes a single-entry sequence with a required spec: and product:, and optional repository: and children::

api:
  elasticsearch:
    - spec: elasticsearch-openapi.json
      product: elasticsearch
  kibana:
    - spec: kibana-openapi.json
      product: kibana
		

Each product key produces its own section of API documentation. For example, elasticsearch generates pages under /api/elasticsearch/ and kibana generates pages under /api/kibana/.

The api key is only valid in docset.yml. You can't use it in toc.yml files.

A path to an OpenAPI spec file, relative to the folder that contains docset.yml. spec: serves two purposes at once:

• If a file exists at that path, docs-builder renders it directly. This is the common setup for a docset that carries its own spec file.
• Its basename (for example elasticsearch-openapi.json) is always used to look up this API's entry in the remote version index, whether or not the file exists locally. See Remote spec resolution.

A product id defined in products.yml. This binds the API to that product's versioning system and display name. The build fails with a suggestion if product: doesn't match a known product id.

An org/repo override (for example elastic/elasticsearch-specification) used to look up this API in the remote version index, instead of the current checkout's own GitHub remote. Set this whenever the repository that publishes the OpenAPI spec differs from the repository the docset itself builds from:

api:
  elasticsearch:
    - spec: elasticsearch-openapi.json
      product: elasticsearch
      repository: elastic/elasticsearch-specification
		

Most docsets omit repository: — it's only needed for this cross-repo case. When omitted, docs-builder derives the repository from the current checkout's GitHub remote.

Explicit hand-written pages rendered under api/<key>/, in the declared order:

api:
  kibana:
    - spec: kibana-openapi.json
      product: kibana
      children:
        - file: kibana-api-overview.md
		

children: is the only way to inject hand-written content into an API reference section:

• Child pages are fully rendered Markdown with access to all MyST directives, substitutions, and cross-links.
• Child files are automatically excluded from normal HTML generation — you do not need to add them to the exclude: list.

What you cannot do today: there is no way to override or augment an individual operation, tag, schema, or parameter description using a local Markdown file. Every description for generated operations, tags, and schema types comes verbatim from the OpenAPI JSON. For per-operation and per-parameter enrichment see the CLI reference, which provides a fine-grained supplemental mechanism as a reference model for what future API augmentation could look like.

A file's URL slug is derived from its filename: lowercase, with spaces and underscores replaced by hyphens, and the .md extension removed. For example, Getting-Started.md becomes the slug getting-started.

The following slugs are reserved and cannot be used as child file names:

Additionally, the slug must not match any operation moniker already generated by the spec. The build fails with a descriptive error if either collision occurs, naming the conflicting file and the reserved or operation segment.

If the same slug is produced by two different child files in the same product, the build also fails with a duplicate-slug error.

Each product key in the api: block must have exactly one entry, with exactly one spec:. The build fails if a product sequence is empty or has more than one entry. Multiple specs per product are not currently supported.

A docset will not need to carry its OpenAPI spec file locally once #719 ships. When spec: does not resolve to a file on disk, docs-builder will resolve the current (main) version of that spec remotely, through a CloudFront-backed version index shared by every Elastic repository that publishes OpenAPI specs.

Each repository publishes its OpenAPI spec under a stable object key in a shared bucket:

<org>/<repo>/<branch>/<spec-name>.<ext>
		

For example, Elasticsearch's spec is published from a separate specification repository, at keys like elastic/elasticsearch-specification/main/elasticsearch.json and elastic/elasticsearch-specification/8.19/elasticsearch.json.

A single root index.json manifest maps every published spec to its highest-minor branch per major. It is keyed by org/repo, then by spec basename (matching spec:'s basename), then by version moniker (main, 9, 8, ...):

{
  "elastic/elasticsearch-specification": {
    "elasticsearch.json": {
      "main": { "version": "main" },
      "9": { "version": "9.5" },
      "8": { "version": "8.19" }
    }
  }
}
		

docs-builder will fetch this manifest once per build from https://d29hkgsdo66d1n.cloudfront.net/index.json, then look up the org/repo (from repository:, falling back to the current checkout's GitHub remote) and the spec: basename to find this API's versions. Spec objects are fetched at {base}/{org}/{repo}/{version}/{spec-basename}.

Today only the main moniker is rendered — there is no version-prefixed output or version switcher yet.

To carry a spec locally, place the OpenAPI specification file in the same folder as your docset.yml (or in a subfolder of it). The path you specify in spec: is resolved relative to the docset.yml location.

For example, if your content set is structured like this:

docs/
  docset.yml
  elasticsearch-openapi.json
  kibana-openapi.json
  index.md
  ...
		

Your docset.yml references the specs as follows:

api:
  elasticsearch:
    - spec: elasticsearch-openapi.json
      product: elasticsearch
  kibana:
    - spec: kibana-openapi.json
      product: kibana
		

The API Explorer generates documentation in two scenarios:

• docs-builder build: API docs are generated as part of the standard build. Use --skip-api to skip generation for faster iteration on content.
• docs-builder serve: API docs are generated on startup and regenerated automatically when spec files change.

You can reference API pages in your toc.yml or docset.yml navigation using cross-link syntax:

toc:
  - file: index.md
  - title: Elasticsearch API Reference
    crosslink: elasticsearch://api/elasticsearch/
		

The API Explorer generates the following types of pages from your OpenAPI spec:

• Landing page: An overview of the API grouped by tag
• Tag landing pages: One page per tag that lists operations in that tag, with the tag's display name, optional OpenAPI description (CommonMark), and optional externalDocs link
• Operation pages: One page per API operation, with the HTTP method, path, parameters, request body, response schemas, and examples
• Schema type pages: Dedicated pages for complex shared types such as QueryContainer and AggregationContainer

The API Explorer supports some OpenAPI specification extensions to enhance navigation and display:

• x-codeSamples
• x-displayName
• x-req-auth
• x-tagGroups

For background on OpenAPI vendor extensions, refer to OpenAPI Specification.

When an OpenAPI operation includes the x-codeSamples extension, the API Explorer renders the code samples with a language selector tab. This lets users switch between available languages such as Console, cURL, Python, JavaScript, Ruby, PHP, and Java.

The x-codeSamples extension is a JSON array of objects, each with a lang and source field:

"x-codeSamples": [
  { "lang": "Console", "source": "GET /_search" },
  { "lang": "curl", "source": "curl -X GET ..." },
  { "lang": "Python", "source": "resp = client.search()" }
]
		

The code samples appear in a standalone "Code Examples" section on every operation page that has the extension, regardless of HTTP method. This means GET, DELETE, and other operations without a request body also display language tabs when x-codeSamples are present. When multiple languages are available, they appear as tabs. The selected language persists across operations and page navigations. When only one language is available, the example renders without a tab selector.

Console is treated as the default language and appears first in the tab order when present.

Add the operation-level x-req-auth extension to list authentication or privilege requirements that users must satisfy before calling the API. The API Explorer renders these lines in a Prerequisites section on the operation page.

x-req-auth is a JSON array of strings. Each non-empty string becomes one item in the prerequisites list (leading and trailing whitespace is trimmed).

{
  "get": {
    "operationId": "get-snapshot",
    "responses": { "200": { "description": "ok" } },
    "x-req-auth": [
      "Cluster privilege: `cluster:admin/snapshot`"
    ]
  }
}
		

When prerequisites are present, Prerequisites also appears in the on-page table of contents (after Paths). When the extension is missing, empty, or not a JSON array, the section is omitted. Malformed values are skipped and the build may log a warning.

Use the x-displayName extension (from Redocly) on tag objects to provide user-friendly display names in navigation and landing pages while maintaining stable URLs based on the canonical tag name.

{
  "tags": [
    {
      "name": "tasks",
      "description": "The task management APIs enable you to get information about tasks currently running.",
      "x-displayName": "Task management"
    },
    {
      "name": "ml_anomaly",
      "description": "Machine learning anomaly detection APIs.",
      "x-displayName": "Machine Learning Anomaly Detection"
    }
  ]
}
		

Behavior:

• When x-displayName is present, it's used for navigation titles, tag landing page titles, and section headings on the main API overview
• When x-displayName is absent, the canonical tag name is used as a fallback
• Tag landing page URLs and tag URL segments are derived from the canonical tag name

Use the document-level x-tagGroups extension (from Redocly) to define how tags are grouped in the API Explorer sidebar. Each group has a display name and a list of tag name values that belong to it. Group order in the array is the order of top-level sections in the navigation.

{
  "openapi": "3.0.3",
  "info": { "title": "Example", "version": "1.0.0" },
  "paths": {},
  "x-tagGroups": [
    {
      "name": "Search & Document APIs",
      "tags": ["search", "document", "eql", "esql", "sql"]
    },
    {
      "name": "Cluster Management",
      "tags": ["indices", "cluster", "snapshot"]
    }
  ]
}
		

Behavior:

• When x-tagGroups is present and valid, the API Explorer uses it as an additional level of grouping in the sidebar.
• In the navigation tree, a group's section title links to the main API overview for that product (it is not a separate page and does not point at the first tag in the group; tag landings stay under .../tags/... only for tags).
• When x-tagGroups is absent, tags are listed directly under the API root in a single flat layer.
• Any operation tag that is not listed under any group is still included: it appears under a fallback section named unknown, and the build logs a warning so you can fix the spec.