> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getpostchi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAPI Sync

> Import an OpenAPI spec into Postchi and keep your request files in sync as the spec evolves.

Beyond a one-time import, Postchi supports **source syncing**: you link a URL to a live spec, and Postchi checks for updates and merges new or changed operations into your project while preserving any edits you've made.

With an open api spec you also get enhanced linting, requests are chcked against the spec and provide auto complete for values and show errors if the request does not conform to the spec.

## Add an OpenAPI source

<Steps>
  <Step title="Open Imports">
    From the file menu select **Import** then select **Live Source**
  </Step>

  <Step title="Provide the spec URL">
    Enter the URL of your OpenAPI spec. For example:

    ```text theme={null}
    https://petstore3.swagger.io/api/v3/openapi.json
    ```

    Postchi accepts both JSON and YAML specs.
  </Step>

  <Step title="Choose a folder name (coming soon)">
    Enter a name for the collection folder Postchi will create. This becomes the top-level folder under your `requests/` directory.
  </Step>

  <Step title="Configure auth (optional)">
    If the spec URL requires authentication — for example, a private GitLab repository — provide a personal access token. currently postchi supports **Github** and **Gitlab** personal access tokens.
  </Step>

  <Step title="Click Fetch Spec">
    Postchi downloads the spec, and shows the name and version of the spec.
  </Step>

  <Step title="Import">
    Postchi downloads the spec, generates request files
  </Step>

  <Step title="Configure">
    After import click configure to open the settings for this source. Set a **base url** and configure the **authentication** methods that were discovered from the spec file.
  </Step>
</Steps>

## What gets generated

Postchi groups operations by their first OpenAPI tag. Each tag becomes a subfolder, and each operation becomes a `.chttp` request file inside it. Operations with no tags are placed directly in the root collection folder.

**File naming**: the request file name comes from the operation's `summary` field. If no summary is set, Postchi falls back to the `operationId`, then to `METHOD /path`.

<Note>
  Open api spec paths are relative make sure to set a base url in the root source folder
</Note>

## Syncing updates

At startup postchi checks for changes in the remote source:

1. Postchi fetches the latest spec and compares it to your local request files.
2. A diff view shows added, modified, and removed operations.
3. Review the changes and click **Apply Changes** to update your files.

<Note>
  If you've edited a request file — changed a header value, filled in a query parameter, or customized the body — Postchi preserves your changes when applying upstream updates.
</Note>