Skip to main content

Connect to the Retool API

Connect to the Retool API using a REST API resource and manage your Retool organization.

Create a REST API resource pointed at the Retool API to let your users write queries that interact with your Retool organization, such as managing users, groups, apps, and resources.

Before you begin​

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

Create a Retool API resource​

Follow these steps to create a REST API resource for the Retool API.

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.

Resource name and description​

Specify a name for the resource, such as Retool API. Include a description that can provide more context to users about how to use the resource.

Query mode and base URL​

You can connect using either query mode: manual queries with a base URL, or guided query creation with a spec URL. Use your instance URL as the base URL:

Base URL
https://example.retool.com/api/v2

To use guided query creation, use the Retool API's OpenAPI specification as the spec URL instead:

Spec URL
https://example.retool.com/api/v2/spec
Best practice

Cloud-hosted organizations can refer to the Retool API reference. Self-hosted organizations can view a version-specific API reference for their instance at https://example.retool.com/reference.

Configure authentication​

The Retool API authenticates using a Bearer token. Select Bearer token from the Authentication dropdown and provide your Retool API key as the token value.

Refer to the Retool API authentication guide for instructions on creating an API key with the required permission scopes.

Test the connection​

Click Test connection to verify Retool can connect to the Retool API. A successful test confirms the base URL is correct and your API key is valid. If it fails, check the following:

  • Base URL: Confirm it matches your instance URL.
  • API key: Confirm it's valid, not expired, and has the required permission scopes.
Use Debug Tools for detailed connection information

After testing the connection, click View in console to open the Debug Tools console. The console displays the request and response details, which is helpful for diagnosing authentication issues.

Save the resource​

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

Interact with Retool API data​

Once you've created a Retool API resource, you can query it in Retool.

Note

Switch to the new app builder to build with Retool API data using natural language prompts.

  • In the app builder, prompt the app building agent with @ and your resource name to generate queries against it.
  • In classic apps, workflows, and agents, write queries using the REST API query editor.

Pagination​

By default, responses include up to 100 items. When there are more items, the has_more field in the response is set to true and the next_token field has a pagination token.

{
  "data": [
    {...}
  ],
  "has_more": true,
  "next_token": "opaque-pagination-token"
}

To request the next page of results, include the token in the URL parameters of the request:

curl -H "Authorization: Bearer {token}" https://api.retool.com/api/v2/resources?next_token=opaque-pagination-token