Skip to main content

​
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

  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 DataUsage
Method + PathUnique identifier, conflict detection
Operation IDSymbol in citations
SummarySearchable content
DescriptionSearchable content
ParametersSearchable, schema hash
Request BodySearchable, schema hash
ResponsesSearchable, 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

Prefer the canonical OpenAPI spec from your API provider rather than generated or third-party specs.
If your spec doesn’t have a good info.version, set doc_version_label when creating the source.
Create separate sources for different API versions (v1, v2) to search across all versions with conflict detection.
Trigger a sync whenever your API spec is updated to keep Ground in sync.

​
Troubleshooting

  • 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
  • Check that operations have the expected HTTP methods
  • Verify paths are properly defined in the spec
  • Add or fix info.version in your OpenAPI spec
  • Or set doc_version_label explicitly on the source