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

# OpenAPI Ingestion

> Index OpenAPI specifications for accurate API documentation retrieval

# OpenAPI Ingestion

Ground can index OpenAPI 3.x specifications, providing structured, version-tracked API documentation with strong provenance.

## Why Use OpenAPI Sources?

* **Structured data**: Operations, parameters, and schemas are parsed and preserved
* **Version tracking**: API version from `info.version` is captured automatically
* **Conflict detection**: Different definitions of the same endpoint are detected
* **Better search**: Operation metadata enables precise matching

## Adding an OpenAPI Source

### Via API

```bash theme={null}
curl -X POST https://api.trygroundai.com/sources \
  -H "Authorization: Bearer gnd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Stripe API",
    "source_type": "docs",
    "docs_format": "openapi",
    "url": "https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json"
  }'
```

### Via UI

1. Go to **Sources** → **Add Source**
2. Select **Documentation**
3. Set format to **OpenAPI**
4. Enter the URL to your OpenAPI spec (JSON or YAML)
5. Click **Create**

## Supported Formats

* OpenAPI 3.0.x (JSON or YAML)
* OpenAPI 3.1.x (JSON or YAML)

Ground auto-detects the format based on file extension and content.

## What Gets Indexed

For each operation in the spec:

| Extracted Data | Usage                                 |
| -------------- | ------------------------------------- |
| Method + Path  | Unique identifier, conflict detection |
| Operation ID   | Symbol in citations                   |
| Summary        | Searchable content                    |
| Description    | Searchable content                    |
| Parameters     | Searchable, schema hash               |
| Request Body   | Searchable, schema hash               |
| Responses      | Searchable, schema hash               |

### Example Chunk

For `POST /v1/payment_intents`:

```markdown theme={null}
# POST /v1/payment_intents
Operation ID: createPaymentIntent
Summary: Creates a PaymentIntent object.

Description:
After the PaymentIntent is created, attach a payment method and confirm...

## Parameters
- amount (body) [required]: Amount intended to be collected
- currency (body) [required]: Three-letter ISO currency code

## Request Body
Content-Type: application/json
Schema: {"type": "object", "properties": {...}}

## Responses
- 200: Successful response
- 400: Bad request
```

## Version Tracking

Ground extracts the API version from `info.version`:

```yaml theme={null}
info:
  title: Stripe API
  version: "2023-10-16"
```

This version appears in citations:

```json theme={null}
{
  "version_ref": "2023-10-16",
  "chunk_type": "openapi"
}
```

## Incremental Updates

Ground uses:

* **ETag/Last-Modified**: Conditional requests to skip unchanged specs
* **Content hash**: Detect changes when headers aren't available
* **Schema hash**: Track per-operation changes for conflict detection

## Conflict Detection

When the same endpoint exists in multiple OpenAPI sources with different schemas, Ground detects the conflict:

```json theme={null}
{
  "conflicts": [
    {
      "endpoint_key": "POST /api/users",
      "sources": ["API v1", "API v2"],
      "schema_hashes": ["abc123", "def456"],
      "description": "Endpoint 'POST /api/users' has different definitions across 2 sources"
    }
  ]
}
```

This helps identify version inconsistencies across your API documentation.

## Best Practices

<AccordionGroup>
  <Accordion title="Use official OpenAPI specs">
    Prefer the canonical OpenAPI spec from your API provider rather than generated or third-party specs.
  </Accordion>

  <Accordion title="Set explicit version labels">
    If your spec doesn't have a good `info.version`, set `doc_version_label` when creating the source.
  </Accordion>

  <Accordion title="Index multiple API versions">
    Create separate sources for different API versions (v1, v2) to search across all versions with conflict detection.
  </Accordion>

  <Accordion title="Sync after API updates">
    Trigger a sync whenever your API spec is updated to keep Ground in sync.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Spec not parsing">
    * Ensure the URL returns valid JSON or YAML
    * Check for CORS issues (spec must be publicly accessible)
    * Verify the spec is OpenAPI 3.x format
  </Accordion>

  <Accordion title="Missing operations">
    * Check that operations have the expected HTTP methods
    * Verify paths are properly defined in the spec
  </Accordion>

  <Accordion title="Version not detected">
    * Add or fix `info.version` in your OpenAPI spec
    * Or set `doc_version_label` explicitly on the source
  </Accordion>
</AccordionGroup>