Connecting an OpenAPI service
Point at the document and every operation becomes a validated tool.
If your API publishes an OpenAPI 3.x specification document, this is the least work of any connection. Give Caterfli the URL and it generates one tool per operation, with argument schemas taken from the specification. An argument the model proposes is checked against the real contract before any request is made.
What you need
An OpenAPI 3.x document Caterfli can fetch, the address the API itself answers on, and credentials if it asks for them.
- The document URL. JSON or YAML, OpenAPI 3.x. Swagger 2.0 is not supported.
- The base URL of the API itself.
- Credentials, if it needs them.
Authentication
Choose the strategy your API uses and fill in the matching fields:
- API key in a header — the key, plus the header name if it is not
X-API-Key. - API key in a query parameter — the key, plus the parameter name if it is not
api_key. - Bearer token — the token.
- Basic — username and password.
- OAuth2 client credentials — client id and secret.
You can also set static headers sent on every request: an API version, a tenant id, anything the service expects everywhere.
Whatever you enter is encrypted at rest and attached to requests by the platform. It is never placed in a prompt and never shown to the model.
What happens on import
An operation that cannot be parsed is skipped and reported rather than failing the whole import, so one malformed path does not cost you the other two hundred. Deprecated operations are ignored.
Read the warnings on the connection page afterwards. A skipped operation is a tool your agent does not have, and the reason is usually a fixable error in the specification.
Keeping up with the API
Re-run discovery when the specification changes.
Sources and further reading
- OpenAPI Specification 3.1.0 — spec.openapis.org
- RFC 6749 §4.4: OAuth 2.0 client credentials grant — datatracker.ietf.org
- RFC 6750: OAuth 2.0 bearer token usage — datatracker.ietf.org
- RFC 7617: HTTP Basic authentication — datatracker.ietf.org