Skip to main content

OpenAPI

Kapa provides an integration to pull OpenAPI references. This integration allows your AI assistant to understand your API structure, enabling it to answer questions about endpoints, parameters, response formats, and authentication methods.

Prerequisites​

  • A hosted OpenAPI schema in JSON or YAML format
  • A publicly accessible URL for the schema
  • Schema conforming to OpenAPI specification version 2.x or 3.x

Data ingested​

When you connect Kapa to an OpenAPI schema, the following data is ingested:

  • URL where the schema is hosted
  • API endpoints and their descriptions
  • Request parameters and their requirements
  • Response structures and status codes
  • Authentication methods
  • Data models and schemas
  • Examples (if included in the specification)

Supported formats​

The OpenAPI integration supports:

  • OpenAPI 2.x (formerly Swagger) specifications
  • OpenAPI 3.x specifications
  • JSON format (.json files)
  • YAML format (.yaml or .yml files)

Setup​

Step 1: Prepare your OpenAPI schema​

  1. Ensure your OpenAPI schema is accessible via a public URL
  2. Verify the schema is in valid JSON or YAML format
  3. Check that the schema follows OpenAPI 2.x or 3.x specifications

Step 2: Configure the Kapa platform​

  1. Go to the Sources tab in the Kapa platform
  2. Click Add new source
  3. Select OpenAPI as the source type
  4. Enter the URL to your hosted OpenAPI schema
  5. Click Save to begin the ingestion process

Configuration options​

The following configuration options are available for the OpenAPI integration:

OptionDescriptionDefaultRequired
Schema URLThe URL pointing to your hosted OpenAPI schemaNoneYes
Refresh intervalHow often Kapa should check for updates to your schemaWeeklyNo

Schema requirements​

Kapa only requires a URL to a hosted OpenAPI schema in either JSON or YAML format. Both OpenAPI 2.x and 3.x are supported.

Blob URLs like the following are not supported:

blob:https://clerk.com/05c96426-79cc-42f3-8940-aa4c9dcc243f

Alternative approach: File upload​

If no hosted version of the schema is available, you can also upload OpenAPI schema files through the File Upload source type. However, the downside of File Upload is that it cannot automatically refresh.

Best practices​

  • Include comprehensive descriptions: Ensure your OpenAPI schema includes detailed descriptions for endpoints, parameters, and responses
  • Provide examples: Include example requests and responses in your schema to help Kapa understand typical usage
  • Keep schemas updated: Regularly update your schema to reflect the current state of your API
  • Use semantic versioning: If your API changes frequently, consider providing schemas for different API versions

Troubleshooting​

  • Invalid schema error: Ensure your schema conforms to OpenAPI specifications
  • URL not accessible: Verify the schema URL is publicly accessible
  • Blob URL not supported: URLs starting with blob: are not supported
  • Schema not being updated: Check that the schema URL still points to the current version