Connecting a REST API
For an HTTP API with no specification — and the shortest way to give it one.
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, write a small one yourself. Cover only the handful of operations an agent should use, host it somewhere the platform can reach, and point an OpenAPI connection at it. 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
Where the API lives, how to sign in to it, and anything it expects on every request.
- 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.
Sources and further reading
- 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
- OWASP Server-Side Request Forgery Prevention Cheat Sheet — cheatsheetseries.owasp.org