OpenAPI Connector

Connect any REST API to your PlisAI agents by importing its OpenAPI/Swagger specification. Auto-generates tool definitions in seconds.

Quick Start

Navigate to Connectors → OpenAPI or go to /connectors/openapi/new

Paste your provider's Swagger/OpenAPI URL (e.g. https://petstore3.swagger.io/api/v3/openapi.json) or paste the raw spec YAML/JSON

Select the operations you want to expose as agent tools (checkboxes grouped by tag)

Configure authentication: API Key, Bearer Token, or Basic Auth

Click Save Connector — your tools are now available in the Agent Builder

Common Provider Examples

Petstore (Sample)

https://petstore3.swagger.io/api/v3/openapi.json

GitHub REST API

https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json

Stripe API

https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json

HubSpot CRM API

https://api.hubspot.com/api-catalog-public/v1/apis/crm/v3/objects

Supported Spec Formats

Format	Version	Input Method
OpenAPI 3.x	3.0.x, 3.1.x	URL or Paste (JSON/YAML)
Swagger 2.0	2.0	URL or Paste (JSON/YAML)

Authentication Types

Type	Header Sent	Use Case
None	—	Public APIs
API Key	`X-Api-Key: {secret}`	Most REST APIs
Bearer Token	`Authorization: Bearer {secret}`	OAuth2 access tokens
Basic Auth	`Authorization: Basic {b64}`	Legacy systems

API Reference

Method	Endpoint	Description
POST	`/api/connectors/openapi/preview`	Preview spec metadata + operations
POST	`/api/connectors/openapi/generate-tools`	Generate tool definitions (dry run)
POST	`/api/connectors/openapi/`	Create and save a connector
GET	`/api/connectors/openapi/`	List all connectors
GET	`/api/connectors/openapi/{id}`	Get connector details
PATCH	`/api/connectors/openapi/{id}`	Update connector
DELETE	`/api/connectors/openapi/{id}`	Soft-delete connector
POST	`/api/connectors/openapi/{id}/refresh-tools`	Re-generate tools from spec

Architecture

PlisAI Agent  ──►  OpenAPI Connector  ──►  Tool Executor  ──►  Provider REST API
                     │                       │
                     │ parse spec             │ inject auth headers
                     │ generate tools         │ map parameters
                     ▼                       ▼
                  openapi_connectors      httpx request
                  (database)              (runtime)

Troubleshooting

Spec URL returns 403 or 401

Some API specs require authentication to access. Try downloading the spec manually and pasting it via the "Paste Spec" option instead.

No operations found

Ensure the spec has a paths section with at least one HTTP method. Some specs only define schemas without endpoints.

Large spec takes too long

Specs with 500+ operations (e.g., GitHub, AWS) are supported but may take a few seconds to parse. Consider selecting only the operations you need.

$ref resolution fails

External $ref references (pointing to other files) are not yet supported. Only internal references (#/components/...) are resolved.

← Back to Documentation Hub