OpenAPI Connector

The OpenAPI connector turns any API with an OpenAPI (Swagger) specification into a set of tools the AI agent can discover and invoke. It provides 6 tools for parsing specs, listing endpoints, and executing API calls.

Configuration

Provide the URL or raw content of an OpenAPI spec (v2 or v3):

URL-Based

{
  "name": "Internal API",
  "source_type": "openapi",
  "config": {
    "spec_url": "https://api.example.com/openapi.json",
    "base_url": "https://api.example.com",
    "auth_header": "Authorization",
    "auth_value": "Bearer your-api-token"
  }
}

Inline Spec

{
  "name": "Partner API",
  "source_type": "openapi",
  "config": {
    "spec_content": "openapi: '3.0.0'\ninfo:\n  title: Partner API\n  version: '1.0'\npaths:\n  /users:\n    get:\n      summary: List users\n      ...",
    "base_url": "https://partner-api.example.com",
    "auth_header": "X-API-Key",
    "auth_value": "key-xxxxx"
  }
}

Authentication Methods

The OpenAPI connector supports multiple authentication strategies:

Method	Config Fields	Example
Bearer Token	auth_header, auth_value	Authorization: Bearer xxx
API Key (Header)	auth_header, auth_value	X-API-Key: xxx
API Key (Query)	auth_query_param, auth_value	?api_key=xxx
Basic Auth	auth_header, auth_value	Authorization: Basic base64(user:pass)
No Auth	--	Public APIs

Live Tools (6)

Tool	Description	Arguments
openapi_parse_spec	Parse and validate an OpenAPI spec, returning summary info	spec_url?
openapi_list_endpoints	List all endpoints with methods, paths, and descriptions	tag?, method?
openapi_get_endpoint	Get detailed endpoint info including parameters and schemas	method, path
openapi_execute	Execute an API call to a specific endpoint	method, path, params?, body?, headers?
openapi_list_schemas	List all schema definitions in the spec	--
openapi_get_schema	Get a specific schema definition with properties and examples	schema_name

Example: Agent Using OpenAPI Tools

User: "What endpoints does the payments API have for refunds?"

Agent: Let me check the API spec.
→ Calls openapi_list_endpoints(tag: "refunds")
→ Returns:
  POST /refunds — Create a refund
  GET /refunds/{id} — Get refund details
  GET /refunds — List refunds with filters
→ Calls openapi_get_endpoint(method: "POST", path: "/refunds")
→ Returns: request body schema, required fields, response schema
→ Summarizes the refund API capabilities

ETL Ingestion

Nodes Created

Node Label	Properties	Source
APISpec	title, version, description, base_url, format (openapi/swagger)	Spec info
APIEndpoint	method, path, summary, description, tags, deprecated	Paths
APIParameter	name, in (query/path/header/cookie), required, type, description	Parameters
APISchema	name, type, properties, required_fields	Components/Definitions

Relationships Created

Relationship	From	To
DEFINES	APISpec	APIEndpoint
HAS_PARAMETER	APIEndpoint	APIParameter
ACCEPTS	APIEndpoint	APISchema (request body)
RETURNS	APIEndpoint	APISchema (response)
REFERENCES	APISchema	APISchema (nested/allOf/oneOf)

Graph Queries

-- Find all endpoints that accept a specific schema
MATCH (e:APIEndpoint)-[:ACCEPTS]->(s:APISchema)
WHERE s.name = "CreateOrderRequest"
RETURN e.method, e.path, e.summary

-- Map API coverage: endpoints with and without descriptions
MATCH (e:APIEndpoint)
RETURN e.method, e.path,
       CASE WHEN e.description IS NOT NULL THEN "documented" ELSE "undocumented" END AS status

-- Find deprecated endpoints still in use
MATCH (e:APIEndpoint)
WHERE e.deprecated = true
RETURN e.method, e.path, e.summary

Configuration Reference

Field	Type	Default	Description
spec_url	string	--	URL to fetch the OpenAPI spec from
spec_content	string	--	Inline OpenAPI spec (YAML or JSON)
base_url	string	from spec	Override the base URL for API calls
auth_header	string	--	Authentication header name
auth_value	string	--	Authentication header value
auth_query_param	string	--	Authentication query parameter name
verify_ssl	bool	true	Verify SSL certificates for API calls
timeout_secs	int	30	Request timeout for API execution
max_response_size_kb	int	1024	Maximum response size to process

TIP

You must provide either spec_url or spec_content — not both. If the spec contains a servers block, the base_url is auto-detected. You can override it when the spec URL differs from the runtime API URL.

Supported Spec Formats

Format	Version	Support
OpenAPI	3.1	Full
OpenAPI	3.0	Full
Swagger	2.0	Full (auto-converted to 3.0 internally)
JSON	--	Full
YAML	--	Full

Troubleshooting

Error	Cause	Fix
Failed to parse spec	Invalid OpenAPI/Swagger format	Validate the spec with editor.swagger.io
Connection refused	Spec URL or base URL is unreachable	Verify the URL and network connectivity
401 Unauthorized	API authentication failed	Check the auth_header and auth_value configuration
SSL certificate error	Self-signed or expired certificate	Set verify_ssl: false (not recommended for production)
Response too large	API response exceeds max_response_size_kb	Increase the limit or use query parameters to reduce the response