OpenAPI integrations

Import and manage OpenAPI integrations

Parse an OpenAPI definition, select operations, configure authentication, and maintain the saved integration.

Import an OpenAPI or Swagger definition and turn selected REST operations into a saved Agent Studio integration. You can parse a definition from a URL or raw JSON, choose only the operations a workflow needs, and maintain the integration without re-importing unrelated APIs.

Before you begin

You must be signed in to Agent Studio with a Clerk session. Prepare a valid OpenAPI or Swagger document, the API’s base URL, and test credentials if the target API requires authentication. Use synthetic data and a non-production API environment for the first call.

Choose the smallest useful operation set. Every saved integration must have a valid base URL and at least one endpoint.

⚠️Importing a definition does not make every operation safe to run. Review write operations and the target API’s side effects before exposing them to a workflow.

Import the definition

Choose the specification source

Use either a reachable specification URL or the raw JSON document. For a URL import, send the source to the parser:

bash

curl -X POST 'https://studio.example.com/api/openapi/parse' \
  -H 'Content-Type: application/json' \
  -H 'Cookie: <clerk-session-cookie>' \
  --data '{"specUrl":"https://api.example.com/openapi.json"}'

For a raw import, send the parsed JSON value as rawSpec instead of specUrl. A successful request returns success: true and the parsed definition in data.

Review the parsed service

Inspect the parsed title, base URL, and operations before saving anything. Confirm that the base URL targets the intended test environment and that each operation has the expected HTTP method, path, and operation identifier.

If the definition contains several servers, choose the one your Agent Studio deployment can reach. Do not substitute a production origin merely because it appears first in the document.

Select operations

Keep only the endpoint definitions required by your workflow. For a support-ticket integration, for example, select the read operation for one ticket before adding an operation that creates or updates tickets.

Preserve the parsed endpoint definitions when you build the integration request. Agent Studio rejects a creation request that contains no endpoints.

Configure authentication

Choose the authentication mode that matches the target API: NONE, BEARER, API_KEY, BASIC, or CUSTOM_HEADER. Supply the corresponding authentication configuration required by that API.

Keep credentials out of the imported specification and examples. Use a test credential with the narrowest permissions required for the selected operations, and follow your organization’s secret-rotation process.

Create the integration

Send the integration name, valid base URL, chosen authentication settings, and at least one selected endpoint to POST /api/openapi/integrations. Agent Studio associates the new integration with the signed-in user and returns HTTP 201 with success: true and the saved integration in data.

Use a descriptive name such as Support API sandbox so workflow authors can distinguish the test integration from a production connection.

Confirm the saved record

List the current user’s integrations:

bash

curl 'https://studio.example.com/api/openapi/integrations?limit=25' \
  -H 'Cookie: <clerk-session-cookie>'

The optional limit must be a positive integer. Agent Studio caps it at 200; when omitted, the integrations hub can request the uncapped list. Confirm that the response contains the new integration and the intended operation set.

Maintain an integration

Use GET /api/openapi/integrations/{id} to retrieve one integration owned by the signed-in user. Send validated changes to PUT /api/openapi/integrations/{id} when its base URL, authentication configuration, or endpoint selection changes. The response contains the updated integration in data.

Test the revised operation set before using it in a workflow. If an integration is no longer required, remove workflow dependencies first, then send DELETE /api/openapi/integrations/{id}. A successful deletion returns success: true.

🚫Deleting an integration removes the saved connection. Confirm the integration ID and dependent workflows before sending the request.

Verify the integration

✅GET /api/openapi/integrations lists the integration with the intended base URL, authentication mode, and selected operations. A safe read operation succeeds against the test environment with synthetic input.

Troubleshoot imports

Next steps

Discover and test REST APIs before adding write operations to a workflow. For the HTTP contract, continue to the planned MCP and OpenAPI API reference.