Skip to main content

Connect to REST API

Learn how to connect to REST APIs and make HTTP requests in Retool.

Create a REST API resource to connect Retool to any HTTP-based API. REST API resources are generic integrations that enable you to securely connect to external services and build internal tools, admin panels, and workflows that interact with your APIs.

What you can do with REST API​

  • Make HTTP requests: Send GET, POST, PUT, PATCH, and DELETE requests to any REST API.
  • Multiple auth methods: Authenticate with Bearer tokens, Basic auth, OAuth 2.0, AWS Signature V4, and more.
  • Handle responses: Parse JSON, XML, and other response formats.
  • Custom headers: Add custom headers, cookies, and request parameters for complete control over API requests.

For quick, one-off API calls that don't require authentication, you can use the built-in REST API query type available from the Resource dropdown in the query editor. This allows you to populate API details (base URL, endpoint, headers) directly in the query without creating a resource. However, if your API requires authentication, create a REST API resource instead—resources securely encrypt credentials and authentication details.

Before you begin​

To connect a REST API to Retool, you need the following:

  • 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 a REST API resource​

Follow these steps to create a REST API 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 REST API and click the REST API tile to begin configuration.

Searching for REST API in the resource creation page.

2. Configure connection settings​

Configure the following connection settings for your REST API resource.

REST API connection settings form.

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
OpenWeatherMap APIA REST API resource for the OpenWeatherMap weather data service.
Internal customer APIA REST API resource for our internal customer management API.

Base URL​

The base URL for all API requests. Query paths are appended to this base URL.

Examples
https://api.openweathermap.org/data/2.5
https://api.example.com/v2
https://internal-api.company.com/api

URL parameters​

Global URL parameters applied to all requests. Add parameters as key-value pairs.

Headers​

Global headers applied to all requests. Add headers as key-value pairs.

3. Configure authentication​

REST API supports multiple authentication methods based on your API requirements.

Authentication methodUse cases
Auth0 Client CredentialsAuth0 for identity and access management. Retool handles OAuth flow and token management automatically.
AWS Signature V4AWS-hosted APIs requiring signed requests (API Gateway). Retool signs each request using AWS Signature Version 4.
Basic authenticationUsername and password credentials sent with each request. Retool encodes credentials as base64 in the Authorization header. Common for simple APIs.
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. Test connection disabled for custom auth.
Digest authenticationDigest authentication (RFC 2617). Uses MD5 hashing for improved security over Basic auth.
Google Service AccountGoogle service account authentication for Google Cloud services. Upload JSON key file for automatic JWT generation and token refresh.
NonePublic endpoints or custom authentication via headers. Add authentication tokens as custom headers.
OAuth 1.0Legacy OAuth 1.0 authentication (older services). Retool signs requests using OAuth 1.0a signature method.
OAuth 2.0User authentication via OAuth 2.0. Use Authorization Code flow for user credentials or Client Credentials for server-to-server authentication with automatic token refresh.
Session-based DeprecatedSession cookies for authentication. Configure login endpoint and Retool maintains session cookies across requests.

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.

REST API authentication settings dropdown.

4. Test the connection​

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

If the connection test fails, verify:

  • Base URL is correct and accessible from Retool
  • Authentication credentials are valid and not expired
  • API accepts requests from Retool's IP addresses (for Cloud organizations)
  • Custom headers are formatted correctly

5. Save the resource​

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

Query REST API data​

Once you've created a REST API resource, you can query it in apps, workflows, and agent tools.

Create a query​

You can create a REST API query in a Retool app using Assist to generate queries with natural language, or manually using code.

Use Assist to generate queries from natural language prompts. Assist can create REST API queries to retrieve, send, and manipulate data from your REST API resource.

To create a query with Assist:

  1. In the Retool app IDE, click the Assist button at the bottom of the left toolbar to open the Assist panel (if not already visible).
  2. Write a prompt describing the API request you want to make, referencing your resource using @.
  3. Press Enter to submit the prompt.
  4. Select your REST API resource when prompted.
  5. Review the generated query and click Run query to add it to your app.
Example prompt
get current weather data from the weather endpoint using @OpenWeatherMap API

Assist connecting to the OpenWeatherMap API resource and planning a query.

Query configuration fields​

Each REST API query has the following configuration fields:

HTTP method​

The HTTP method for the request.

MethodUse case
GETRetrieve data from the API. Most common read operation.
POSTCreate new objects or submit data to the API.
PUTReplace an existing object completely.
PATCHPartially update an existing object.
DELETERemove an object from the API.

URL path​

The path appended to the resource's base URL. Include dynamic values using embedded expressions.

URL path examples
// Static path
/users

// Dynamic with ID
/users/{{ table1.selectedRow.data.id }}

// With query parameters
/search?q={{ searchInput.value }}&limit=20

// Multiple path segments
/customers/{{ customerId.value }}/orders

URL parameters​

Query parameters appended to the URL. Add parameters as key-value pairs to build the query string.

Headers​

Request-specific headers that override or extend the resource's global headers.

Body​

The request body for POST, PUT, and PATCH requests. Use embedded expressions to include dynamic data.

Body example
{
  "name": {{ nameInput.value }},
  "email": {{ emailInput.value }},
  "role": {{ roleSelect.value }},
  "metadata": {
    "created_by": {{ current_user.email }},
    "created_at": {{ new Date().toISOString() }}
  }
}

Body type​

The format of the request body.

Body typeDescriptionContent-Type header
JSONJavaScript object serialized to JSON.application/json
RawPlain text or custom format.Custom or none
NoneNo request body.None

Common use cases​

The following examples demonstrate typical REST API operations in Retool apps using a sample REST API.

Use the mock API generator below to generate a fully functional temporary REST API with sample data that you can use.

  1. Select the sample data set.
  2. Specify the number of Items that the data set should include.
  3. Click Generate API to generate the API with sample data.
  4. Click Copy URL to copy the API URL to your clipboard.
Mock API generator

The mock API is for testing purposes only and does not require authentication. Do not attempt to use it for production purposes or with any type of sensitive information.

fetch data from an API

First, create a REST API resource with the base URL from the mock API generator, for example: https://retoolapi.dev/SPq6yI.

Next, create a query to fetch customer data:

FieldValue
HTTP methodGET
URL path/customers

Then, add a Table component to the app and set its Data property to {{ getCustomersQuery.data }}.

filter data with query parameters

Query parameters allow you to filter and refine API responses.

Create a query with query parameters:

FieldValue
HTTP methodGET
URL path/customers
Query parameters[["company", {{ companySelect.value }}], ["_limit", "50"]]

The query sends a request to /customers?company=Acme&_limit=50 and returns filtered results.

fetch a single record by ID

Retrieve a specific customer record using their ID.

Create a query with a dynamic ID in the path:

FieldValue
HTTP methodGET
URL path/customers/{{ table1.selectedRow.data.id }}

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

create a new record via POST

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

Next, create a POST query:

FieldValue
HTTP methodPOST
URL path/customers
Body typeJSON

Body:

{
  "name": {{ form1.data.name }},
  "email": {{ form1.data.email }},
  "company": {{ form1.data.company }}
}

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 PATCH

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

Next, create a PATCH query:

FieldValue
HTTP methodPATCH
URL path/customers/{{ table1.selectedRow.data.id }}
Body typeJSON

Body:

{
  "name": {{ form1.data.name }},
  "email": {{ form1.data.email }},
  "company": {{ form1.data.company }}
}

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
HTTP methodDELETE
URL path/customers/{{ 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
handle paginated responses

For APIs that return paginated data, use query parameters to implement pagination.

Create a query with pagination parameters:

FieldValue
HTTP methodGET
URL path/customers
Query parameters[["_page", {{ table1.pagination.pageIndex + 1 }}], ["_limit", "10"]]

The query sends a request to /customers?_page=2&_limit=10 and returns paginated results. Connect the query to a table component and enable server-side pagination.

Best practices​

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

Performance​

  • Cache responses: For data that doesn't change frequently, enable query caching to reduce API calls and improve response times.
  • Implement pagination: For endpoints that return large datasets, use query parameters to implement pagination and reduce payload size.
  • Batch requests: When available, use batch API endpoints to combine multiple operations into a single request.
  • Minimize payload size: Request only the fields you need using query parameters or API-specific field selection features.
  • Set appropriate timeouts: Configure query timeouts based on expected API response times to prevent hung requests.

Security​

  • Use configuration variables: Store API keys and tokens in configuration variables or rather than hardcoding them.
  • Use HTTPS only: Always connect to APIs over HTTPS to encrypt data in transit and protect authentication credentials.
  • Rotate credentials regularly: Follow your API provider's recommendations for credential rotation and key management.
  • Validate SSL certificates: Keep SSL certificate verification enabled unless absolutely necessary for development environments.
  • Use resource environments: Organizations on an Enterprise plan can configure multiple resource environments to maintain separate configurations for production, staging, and development.
  • Apply least privilege: Use API keys with minimal required permissions. Create separate keys for different environments.

Data integrity​

  • Validate user input: Sanitize and validate all user input before including it in API requests to prevent injection attacks.
  • Handle errors gracefully: Configure error notifications and fallback behavior for failed API calls to improve user experience.
  • Use idempotency keys: For APIs that support idempotency keys, include them in POST/PATCH requests to prevent duplicate operations.
  • Verify responses: Check response status codes and validate response data structure before using it in your app.
  • Implement retry logic: For transient failures, use Retool's automatic retry settings or implement custom retry logic with exponential backoff.
  • Log API interactions: Enable query logging to track API requests and responses for debugging and auditing.