Connecting a REST API

For an HTTP API you want an agent to call.

Check for a specification first

Many services publish an OpenAPI document without advertising it — try /openapi.json, /swagger.json or /v3/api-docs on the API's own host. If one exists, use an OpenAPI connection instead. You get every operation with argument schemas taken from the specification rather than described by hand.

If there is genuinely no document, the shortest path is to write a small one yourself covering only the handful of operations an agent should use, host it somewhere the platform can reach, and point an OpenAPI connection at that. A deliberately narrow specification is not a workaround here — it is a better starting point than importing four hundred operations and disabling most of them.

What you configure

• •Base URL — the root the paths hang off, such as https://api.example.com/v1.
• •Health check path — a cheap endpoint used to check the connection is alive. Defaults to the base URL.
• •Authentication — the same strategies as OpenAPI: API key in a header or query parameter, bearer token, basic, or OAuth2 client credentials.
• •Additional headers — static headers sent with every request.

What can be reached

Only public hostnames. Private addresses, loopback and cloud metadata endpoints are refused — on save, on every request, and again on every redirect. A hostname that resolves publicly today can resolve somewhere private tomorrow, which is why it is re-checked every time rather than trusted once.