---
title: "Recipe: Sync Your OpenAPI Spec"
description: "Keep generated API reference pages in sync with your OpenAPI spec on every release."
---

# Recipe: Sync Your OpenAPI Spec

Import an OpenAPI 3.x spec and Syntext generates endpoint pages — request/response schemas, code samples, and an interactive try-it playground. This recipe keeps the spec in sync automatically.

## One-Time Import

Point Syntext at a spec URL or upload the document:

<CodeGroup>
```bash From a URL
curl -X POST https://api.syntext.dev/v1/projects/$PROJECT_ID/openapi \
  -H "Authorization: Bearer $SYNTEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://api.acme.com/openapi.json" }'
```

```bash Inline document
curl -X POST https://api.syntext.dev/v1/projects/$PROJECT_ID/openapi \
  -H "Authorization: Bearer $SYNTEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"spec\": $(cat openapi.json) }"
```
</CodeGroup>

Generated endpoint pages appear under your API reference tab after the next build.

## Auto-Sync on Release

Re-push the spec whenever your API ships. In GitHub Actions:

```yaml
name: Sync API docs
on:
  push:
    branches: [main]
    paths: ['openapi.json']

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Push spec to Syntext
        run: |
          curl -fsS -X POST https://api.syntext.dev/v1/projects/${{ vars.SYNTEXT_PROJECT_ID }}/openapi \
            -H "Authorization: Bearer ${{ secrets.SYNTEXT_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d "{\"spec\": $(cat openapi.json)}"
```

## Inspecting What's Imported

```bash
# List imported specs
curl https://api.syntext.dev/v1/projects/$PROJECT_ID/openapi/specs \
  -H "Authorization: Bearer $SYNTEXT_API_KEY"

# List generated endpoints
curl https://api.syntext.dev/v1/projects/$PROJECT_ID/openapi/endpoints
```

To remove a spec and its generated pages: `DELETE /v1/projects/{projectId}/openapi`.

## Combining with Hand-Written Content

Generated pages cover the *what*; write guides for the *why*. Link generated endpoint pages from your guides, and use [annotation coverage](/api-reference/analytics/annotation-coverage) to make sure code-level docs keep pace too.

<Note>
GraphQL, gRPC, and AsyncAPI schemas are also supported via the same import pattern (`/graphql`, `/grpc`, `/asyncapi` endpoints).
</Note>