Skip to main content

Connect to OpenAPI

Learn how to connect to APIs using OpenAPI specifications in Retool.

Create an OpenAPI resource to connect Retool to REST APIs using OpenAPI specifications. OpenAPI resources are generic integrations that enable you to securely connect to external services and automatically generate query fields, parameters, and documentation from your API spec, reducing manual configuration and ensuring accuracy.

What you can do with OpenAPI​

  • Auto-generate query fields: Retool reads your OpenAPI spec and automatically creates query fields, parameters, and documentation for each API operation.
  • Type-safe queries: Query parameters and request bodies are validated against the OpenAPI schema, ensuring correct data types and required fields.
  • Multiple auth methods: Authenticate with Bearer tokens, Basic auth, OAuth 2.0, and custom authentication methods inherited from the spec.
  • Server variables: Use OpenAPI 3.0+ server variables to switch between environments (development, staging, production) without changing the resource configuration.
  • Auto-pagination: For Stripe OpenAPI resources, automatically fetch all pages of results without manual pagination logic.

Before you begin​

To connect an OpenAPI API to Retool, you need the following:

  • OpenAPI specification URL: The URL to your OpenAPI specification file (JSON or YAML format). Retool supports OpenAPI 2.0 (Swagger), 3.0.x, and 3.1.0.
  • API credentials: API keys, OAuth credentials, or other authentication method required by the API.
  • Retool permissions: Edit all permissions for resources in your organization.

Create an OpenAPI resource​

Follow these steps to create an OpenAPI resource in Retool.

1. Create a new resource​

In your Retool organization, navigate to Resources in the main navigation and click Create new → Resource. Search for OpenAPI and click the OpenAPI tile to begin configuration.

2. Configure connection settings​

Configure the following connection settings for your OpenAPI resource.

Resource name and description​

Specify a name for the resource that indicates which API it connects to. Include a description that can provide more context to users and Assist about how to use the resource.

Example NameExample Description
Petstore APIOpenAPI resource for the Swagger Petstore demo API.
Internal Orders APIOpenAPI resource for our internal order management system API.

OpenAPI specification URL​

The URL to your OpenAPI specification file. Retool fetches and parses the specification to discover available API operations, auto-generate query fields, extract authentication requirements, and identify server URLs.

Examples
https://petstore3.swagger.io/api/v3/openapi.json
https://api.example.com/openapi.yaml
https://api.example.com/v2/swagger.json

Retool caches OpenAPI specifications for performance. Retool-hosted specs are cached for 12 hours. Custom specs use a configurable cache duration.

Server URL (OpenAPI 3.0+)​

If your OpenAPI specification defines multiple servers, select the server URL from the dropdown. For specs with a single server, this is set automatically.

Server variables (OpenAPI 3.0+)​

If your selected server URL includes variables, provide values for each variable. Variables allow you to switch between environments or API versions without changing the resource configuration.

Example server with variables
servers:
  - url: https://api.example.com/{environment}/v{version}
    variables:
      environment:
        default: production
        enum: [development, staging, production]
      version:
        default: '1'

3. Configure authentication​

OpenAPI supports multiple authentication methods based on your API requirements. You can inherit authentication from the OpenAPI spec or configure it manually.

Authentication methodUse cases
API KeyAPI key authentication sent as a header or query parameter. Retool includes the API key in each request based on the OpenAPI specification's security scheme.
Basic authenticationUsername and password credentials. Retool encodes credentials as base64 in the Authorization header.
Bearer tokenStatic API token authentication. Retool sends the token as Authorization: Bearer {token}.
CustomCustom authentication logic not covered by standard methods, such as multi-step flows. Add custom headers and authentication workflow using JavaScript.
NonePublic APIs or custom authentication via headers. Add authentication tokens as custom headers.
OAuth 2.0User or server authentication via OAuth 2.0. Use Authorization Code flow for user credentials or Client Credentials for server-to-server.

Select an authentication method from the Authentication dropdown and provide the required credentials. For sensitive values like API keys, tokens, and secrets, use configuration variables or rather than hardcoding them.

4. Configure additional settings​

SettingDescription
Forward headers when fetching specEnable to include resource headers when fetching the OpenAPI specification itself.
HeadersAdd custom HTTP headers as key-value pairs. Use template syntax for dynamic values.
URL parametersAdd query parameters appended to all requests.
CookiesConfigure which cookies to forward from the user's session to the API endpoint.

For OpenAPI 2.0 (Swagger) specs, Retool reads securityDefinitions to determine the authentication parameter name and location (header or query parameter).

5. Test the connection​

Click Test connection to verify Retool can connect to your API and fetch the OpenAPI specification. A successful test confirms the specification URL is accessible and authentication credentials are valid.

If the connection test fails, verify:

  • OpenAPI specification URL is correct and accessible from Retool
  • Specification file is valid OpenAPI 2.0, 3.0.x, or 3.1.0 format
  • Authentication credentials are valid if the spec requires authentication
  • Forward headers when fetching spec is enabled if the spec URL requires authentication

6. Save the resource​

Click Create resource to save your OpenAPI resource. The resource is now available to use in apps, workflows, and agent tools across your Retool organization.

Query OpenAPI data​

Once you've created an OpenAPI resource, you can query it in apps, workflows, and agent tools.

Create a query​

To create an OpenAPI query in a Retool app:

  1. In the Retool app IDE, open the Code tab, then click + in the page or global scope.
  2. Select Resource query.
  3. Choose your OpenAPI resource.
  4. Select an operation from the dropdown and configure parameters.

Query configuration fields​

Each OpenAPI query has specific configuration fields auto-generated from your API specification.

Operation​

Select the API operation from the dropdown. Operations are populated from the OpenAPI spec's paths object and display the HTTP method, path, and description.

Operations are grouped by path for easy navigation. Each operation shows:

  • HTTP method (GET, POST, PUT, DELETE, PATCH)
  • Path, for example: /users/{userId}
  • Description or summary from the spec
  • Link to external documentation (if defined)

Path parameters​

Path parameters are auto-generated from the spec and appear as input fields. For example, a path /users/{userId} generates a userId parameter field.

Example
// userId parameter
{{ table1.selectedRow.data.id }}

// productId parameter
{{ selectedProductId }}

Required parameters are marked with an asterisk (*).

Query parameters​

Query parameters are auto-generated from the spec and appear as input fields with their name, type, required status, and description from the spec.

Examples
// limit parameter
{{ 50 }}

// search parameter
{{ searchInput.value }}

// status parameter
{{ statusSelect.value }}

Request body​

For operations that accept a request body (POST, PUT, PATCH), the body structure is auto-generated from the spec's requestBody definition. The IDE displays the expected content type, schema structure, required fields, and field descriptions.

Example
{{
  {
    name: nameInput.value,
    email: emailInput.value,
    status: statusSelect.value,
    metadata: {
      source: "retool",
      createdBy: retoolContext.currentUser.email
    }
  }
}}

Match the schema structure defined in the OpenAPI spec for complex nested objects or arrays.

Headers​

Custom HTTP headers for this specific query. These are merged with resource-level headers.

Example
[
  ["X-Request-ID", uuid()],
  ["X-Correlation-ID", correlationId.value]
]

Auto-pagination (Stripe only)​

For Stripe OpenAPI resources, enable auto-pagination to automatically fetch all pages of results. Retool automatically follows Stripe's pagination pattern using the has_more flag and starting_after parameter.

  • Auto-paginate: Enable automatic pagination.
  • Limit: Maximum total number of results to fetch.

Auto-pagination is currently available only for Stripe resources. Other APIs require manual pagination implementation.

Common use cases​

The following examples demonstrate typical OpenAPI operations in Retool apps.

fetch and display data

Create an OpenAPI query to fetch data from the API.

FieldValue
OperationGET /orders
Query parametersstatus: {{ statusSelect.value }}, limit: {{ 50 }}

Add a Table component to the app and set its Data property to {{ openapiQuery1.data }}.

fetch a single record by ID

Retrieve a specific record using a path parameter.

FieldValue
OperationGET /users/{userId}
Path parametersuserId: {{ table1.selectedRow.data.id }}

The query fetches the selected user's details and you can display them in a form or detail view.

create a record via POST

First, add a Form component (form1) with input fields for the data you want to collect.

Next, create a POST query:

FieldValue
OperationPOST /customers

Request body:

{{
  {
    name: form1.data.name,
    email: form1.data.email,
    phone: form1.data.phone,
    address: {
      street: form1.data.street,
      city: form1.data.city,
      state: form1.data.state,
      zip: form1.data.zip
    }
  }
}}

Then, add an event handler to the form's Submit event that runs the POST query and displays a success notification.

update a record via PUT or PATCH

First, add a Form component with fields pre-populated from selected row data.

Next, create a PATCH query:

FieldValue
OperationPATCH /customers/{customerId}
Path parameterscustomerId: {{ table1.selectedRow.data.id }}

Request body:

{{
  {
    name: form1.data.name,
    email: form1.data.email,
    status: form1.data.status
  }
}}

Then, add an event handler that runs the PATCH query when the form is submitted and refreshes the data query.

delete a record with confirmation

First, add a Button component in your table's action column.

Next, create a DELETE query:

FieldValue
OperationDELETE /customers/{customerId}
Path parameterscustomerId: {{ table1.selectedRow.data.id }}

Then, add an event handler to the button's Click event:

  1. Action: Show confirmation modal
  2. If confirmed, trigger the DELETE query
  3. Then refresh the data query
use server variables for environments

OpenAPI 3.0+ server variables allow you to switch between environments without changing the resource configuration.

Configure the resource with server variables:

  • Server URL: https://api.example.com/{environment}/v1
  • Server variables: environment: {{ environmentSelect.value }}

Add a Select component with options: development, staging, production. All queries automatically use the selected environment.

auto-paginate Stripe results

For Stripe OpenAPI resources, enable auto-pagination to fetch all pages without manual pagination logic.

FieldValue
OperationGET /v1/customers
Auto-paginateEnabled
Limit{{ 1000 }}

Retool automatically fetches all pages up to the limit and combines results into a single array at {{ stripeQuery1.data }}.

Data types and formatting​

OpenAPI query responses follow the structure defined in your API specification. Retool returns responses as JSON objects matching the schema.

Response structure​

Access response data using these patterns:

  • Full response: {{ openapiQuery1.data }}
  • Specific field: {{ openapiQuery1.data.metadata.total }}
  • Array of items: {{ openapiQuery1.data.data }}

Parameter types​

OpenAPI parameters are typed according to the spec:

OpenAPI typeJavaScript typeExample value
stringstring"Jane Doe" or {{ nameInput.value }}
integernumber42 or {{ numberInput.value }}
numbernumber19.99 or {{ priceInput.value }}
booleanbooleantrue or {{ checkbox.value }}
arrayarray["tag1", "tag2"] or {{ multiselect.value }}
objectobject{ key: "value" }

Enum parameters​

Parameters with enum values (defined in the spec) display as dropdowns with allowed values. Select from the dropdown or reference a component value.

Date and time formatting​

Date and time parameters often use ISO 8601 format:

  • Date: YYYY-MM-DD, for example: 2025-01-26
  • DateTime: YYYY-MM-DDTHH:mm:ssZ, for example: 2025-01-26T10:30:00Z

Use JavaScript Date methods to format:

{{ new Date(dateInput.value).toISOString() }}

Best practices​

Follow these best practices to optimize performance, maintain security, and ensure data integrity when working with OpenAPI resources.

Performance​

  • Cache specifications: Retool caches OpenAPI specs for performance. For frequently changing specs, consider a shorter cache duration.
  • Use pagination: For operations returning large datasets, use pagination parameters (limit, offset, page) to reduce payload size.
  • Select specific fields: If your API supports field selection (e.g., fields query parameter), request only needed fields.
  • Leverage auto-pagination: For Stripe resources, use auto-pagination instead of implementing manual pagination logic.

Security​

  • Use configuration variables: Store API keys and tokens in configuration variables or rather than hardcoding them.
  • Use resource environments: Organizations on an Enterprise plan can configure multiple resource environments to maintain separate configurations for production, staging, and development.
  • Use environment-specific specs: Maintain separate OpenAPI specs for development, staging, and production environments with appropriate server URLs.
  • Validate API spec source: Only connect to trusted OpenAPI specification URLs. Malicious specs could expose sensitive parameter information.
  • HTTPS only: Always connect to API endpoints over HTTPS to encrypt data in transit.

Data integrity​

  • Match spec schemas: Ensure request bodies match the schema defined in the OpenAPI spec. Mismatched types or missing required fields cause API errors.
  • Handle required parameters: Required parameters (marked with *) must have values. Validate user input before submitting.
  • Check response schemas: Verify API responses match expected schemas. API changes may break queries if specs are outdated.
  • Refresh specs regularly: Update the OpenAPI specification URL or clear the cache when the API changes to ensure accurate field generation.

Troubleshooting​

Common issues and solutions when working with OpenAPI resources.

Spec fetch fails​

Problem: Cannot fetch OpenAPI specification from the provided URL.

Solution: Verify the specification URL is correct and accessible. If the spec requires authentication, enable Forward headers when fetching spec and configure appropriate authentication headers in the resource.

Operations not appearing​

Problem: Expected API operations don't appear in the operation selector.

Solution: Check that the OpenAPI spec is valid and includes the operations under the paths object. Retool supports GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD, and TRACE methods.

Parameters not auto-generating​

Problem: Expected parameters don't appear as input fields.

Solution: Verify the operation definition in the OpenAPI spec includes parameter definitions with name, in (location), and schema (type) properties.

Request body validation errors​

Problem: API returns validation errors for request body.

Solution: Check that your request body matches the schema in the OpenAPI spec's requestBody.content['application/json'].schema. Ensure required fields are present and types match.

Server variable errors​

Problem: API returns 404 or connection errors with server variables configured.

Solution: Verify server variable values match the enum options defined in the spec. Check that the final constructed URL (with variables replaced) is correct.

Auto-pagination not working​

Problem: Auto-pagination doesn't fetch all results.

Solution: Auto-pagination is currently only available for Stripe resources. For other APIs, implement manual pagination using query parameters and handle pagination logic in your app.