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

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

Go to Sources → Add Source
Select Documentation
Set format to OpenAPI
Enter the URL to your OpenAPI spec (JSON or YAML)
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:

# 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:

info:
  title: Stripe API
  version: "2023-10-16"

This version appears in citations:

{
  "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:

{
  "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

Use official OpenAPI specs

Prefer the canonical OpenAPI spec from your API provider rather than generated or third-party specs.

Set explicit version labels

If your spec doesn’t have a good info.version, set doc_version_label when creating the source.

Index multiple API versions

Create separate sources for different API versions (v1, v2) to search across all versions with conflict detection.

Sync after API updates

Trigger a sync whenever your API spec is updated to keep Ground in sync.

Troubleshooting

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

Missing operations

Check that operations have the expected HTTP methods
Verify paths are properly defined in the spec

Version not detected

Add or fix info.version in your OpenAPI spec
Or set doc_version_label explicitly on the source

Getting Started

Core Concepts

Guides

OpenAPI Ingestion

OpenAPI Ingestion

Why Use OpenAPI Sources?

Adding an OpenAPI Source

Via API

Via UI

Supported Formats

What Gets Indexed

Example Chunk

Version Tracking

Incremental Updates

Conflict Detection

Best Practices

Troubleshooting

​OpenAPI Ingestion

​Why Use OpenAPI Sources?

​Adding an OpenAPI Source

​Via API

​Via UI

​Supported Formats

​What Gets Indexed

​Example Chunk

​Version Tracking

​Incremental Updates

​Conflict Detection

​Best Practices

​Troubleshooting

OpenAPI Ingestion

Why Use OpenAPI Sources?

Adding an OpenAPI Source

Via API

Via UI

Supported Formats

What Gets Indexed

Example Chunk

Version Tracking

Incremental Updates

Conflict Detection

Best Practices

Troubleshooting