Skip to main content

REST / OpenAPI connector

For Studio users with an API that publishes an OpenAPI 3.x specification as JSON and issues credentials (an API key, a token, or several values). You paste the specification, Studio validates it and drafts the guide from it, and you add the credentials as headers or query parameters.

Before you start: the base URL must be a public http or https address; Studio refuses private, loopback, link-local and cloud-metadata hosts when you save and each time it connects.

Steps​

  1. Open Data Connectors, click Create Connector, choose REST API and fill Connector Name, Description and a short Connector Guide (step 4 expands it).
  2. In Connection Configuration ("The base URL agents will hit and the OpenAPI spec we use to enrich the connector guide."), enter the Base URL (for example https://api.example.com) and paste the OpenAPI JSON. The byte counter shows the size; over 8 MiB the form blocks with an alert.
  3. Click Validate OpenAPI. A pass reads "✓ Passed." with a short report; a failure reads "✗ Validation failed" with the report and a list of errors. Editing the specification clears the result, so validate again after a change.
  4. Click Enrich guide from OpenAPI. Studio streams a guide built from the endpoints into the enriched-guide box; review and edit it, then click Accept (or Discard to keep your text).
  1. In Authentication Configuration ("Add each credential the API requires and choose whether they are sent as HTTP headers or URL query parameters. Values are stored in Secrets Manager."), choose Credential placement (one per connector, applied to every row) and fill each row: Credential key (labelled Query parameter name for query placement), an optional header name that defaults to the key (headers only) and Value. Add credential adds a row, up to 12; Remove deletes one (the last row stays).
  2. Click Create Connector (v1). There is no Test Connection for this type; the button is enabled when name, description and guide are filled, the base URL is set, the specification is under 8 MiB and validated, an enriched guide is accepted, and one credential row has both a key and a value.
  1. Open the agent, choose Configure, and add the connector (Agents: configure and activate).

What you should see​

The list shows REST API "(v1)", Active. Configuration shows the base URL, the authentication type (custom headers or query parameters), the header or parameter mapping, the rate limit and the timeout. Credentials shows each key masked with a View toggle. The specification is stored with the connector, so Update shows it pre-filled and you re-validate rather than re-paste.

In chat​

The agent's code sends requests to the base URL with the stored credentials placed as configured, follows the endpoints the guide describes, saves responses into the run's workspace and reads them from there. Credentials are read from the run's environment and are never printed or shown to you.

Notes​

  • Limits: specification 8 MiB (over it the form blocks and the service answers 413 openapi_spec_too_large); 12 credential rows; one placement per connector; public http or https hosts only; request timeout stored on the connector, 30 seconds by default.
  • "✗ Validation failed": the document must be OpenAPI 3.x JSON; convert YAML first. The counter turned into an alert: trim the specification to the paths agents need.
  • Create Connector (v1) disabled: validation must have passed after your last edit, the enriched guide must be accepted, and one row needs both key and value.
  • An address error on save: the base URL resolves to a private or reserved address; use the API's public hostname.
  • The agent gets an authentication error from the API: open Update, re-enter the values under Credentials ("Re-enter credential values to rotate secrets.") and check the placement matches what the API expects.