---
title: Contribute to Elasticsearch API docs locally
description: Set up a local Elasticsearch API docs workflow, from environment setup to generating and previewing your changes.
url: https://www.elastic.co/elastic/docs-builder/docs/3028/contribute-docs/api-docs/elasticsearch-api-docs-quickstart
applies_to:
  - Elastic Cloud Serverless: Generally available
  - Elastic Stack: Generally available
---

# Contribute to Elasticsearch API docs locally
## Overview

The Elasticsearch APIs are the foundation of the Elastic Stack and the largest API set we maintain. Because the workflow is complex, we created this quickstart guide to help you get started.
This is a step-by-step local development workflow. While CI runs these steps automatically on PR branches in the `elasticsearch-specification` repo (see [Makefile](https://github.com/elastic/elasticsearch-specification/blob/main/Makefile)), working locally enables you to validate, preview and debug before submitting your changes. For a complete list of available make targets, run `make help`.
For the official Elasticsearch specification contribution guidance, see [`CONTRIBUTING.md`](https://github.com/elastic/elasticsearch-specification/blob/main/CONTRIBUTING.md#contributing-to-the-elasticsearch-specification).

## Quickstart

Follow these steps to contribute to Elasticsearch API docs locally:
<stepper>
  <step title="Clone the specification repo">
    ```shell
    git clone https://github.com/elastic/elasticsearch-specification.git
    cd elasticsearch-specification
    ```

    <warning>
      You must [create PRs from a branch](https://github.com/elastic/elasticsearch-specification/blob/main/CONTRIBUTING.md#send-your-pull-request-from-a-branch) in the `elasticsearch-specification` repo, not a fork.
    </warning>
  </step>

  <step title="Prepare your environment">
    Run this command to set up your Node.js environment:
    ```shell
    nvm use
    ```
    If you don't have Node.js installed, refer to the [setup guide](https://github.com/elastic/elasticsearch-specification/tree/main?tab=readme-ov-file#prepare-the-environment).
  </step>

  <step title="Install dependencies">
    ```shell
    make setup
    ```

    <important>
      You should run `make setup` every time you begin work on a contribution, because the `elasticsearch-specification` repository is under active development. This ensures you have the latest dependencies and tools.
    </important>
  </step>

  <step title="Make your docs changes">
    Edit the relevant TypeScript files in the `specification` directory. Use JSDoc comments to describe your API interfaces, following the [guidelines](https://www.elastic.co/elastic/docs-builder/docs/3028/contribute-docs/api-docs/guidelines). Add or update summaries, descriptions, tags, metadata, links, and examples as needed.
  </step>

  <step title="Format, generate and validate your changes">
    ```shell
    make contrib
    ```
    This command runs multiple steps in sequence:
    1. Formats your code (`spec-format-fix`)
    2. Generates the schema JSON (`generate`)
    3. Transforms to OpenAPI format for language clients (`transform-to-openapi`)
    4. Filters for serverless (`filter-for-serverless`)
    5. Lints the language clients OpenAPI docs (`lint-docs`)

    <note>
      Some linter errors at this stage can be false alarms, and are fixed by path consolidation and overlays. You'll need to run `make lint` later against the docs-specific OpenAPI files.
    </note>
  </step>

  <step title="Generate docs-specific OpenAPI files">
    ```shell
    make transform-to-openapi-for-docs
    ```
    Generates the OpenAPI files specifically for docs purposes. This step also runs `generate-language-examples` to autogenerate examples for the various language clients and `curl`.
    <note>
      The `transform-to-openapi` command (run by `make contrib`) is used for client libraries and does not generate the JSON schema files needed for docs purposes.
    </note>
  </step>

  <step title="Apply overlays">
    [OpenAPI overlays](https://github.com/OAI/Overlay-Specification?tab=readme-ov-file#overlay-specification) are used to handle publisher-specific requirements or work around rendering limitations. For example, they sort the list of tags alphabetically and apply `x-model` extensions to abbreviate deeply nested and recursive schema objects.
    ```shell
    make overlay-docs
    ```
  </step>

  <step title="Lint your docs">
    Run this command to lint your docs-specific OpenAPI files:
    ```shell
    make lint-docs
    ```

    <tip>
      You should try to fix all linter warnings and not only errors. Fixing errors alone will not ensure your docs are complete (helpful for users).
    </tip>
  </step>

  <step title="Preview your changes">
    Install [`bump-cli`](https://www.npmjs.com/package/bump-cli):
    ```bash
    npm install -g bump-cli
    ```
    Run these commands to generate short-lived previews:
    ```shell
    bump preview output/openapi/elasticsearch-openapi-docs-final.json
    bump preview output/openapi/elasticsearch-serverless-openapi-docs-final.json
    ```
  </step>

  <step title="Open a pull request">
    Once you're satisfied with your docs changes:
    1. Create a pull request from a branch on your local clone
    2. The CI will validate your OpenAPI specs
    3. Once approved, merge your changes and ensure they are backported to the appropriate branches
  </step>
</stepper>