# How to Use the Retool API to Manage Applications

- Tool: Retool
- Difficulty: Intermediate
- Time required: 25-30 min
- Compatibility: Retool Cloud and Self-hosted (some endpoints require Enterprise)
- Last updated: March 2026

## TL;DR

The Retool API v2 is a REST API at https://[your-org].retool.com/api/v2/ authenticated with Bearer tokens. Generate tokens at Settings → Retool API. Use it to programmatically list apps, manage users, automate deployments, and integrate Retool management into your CI/CD pipeline. Some endpoints require Enterprise plan.

## Automate Retool Management with the REST API

The Retool API lets you programmatically manage your Retool organization: list apps, create users, manage groups, trigger deployments, and more. This is useful for: automating user onboarding (provisioning users when they join your company), integrating Retool deployments into CI/CD pipelines, building a meta-app in Retool that manages other Retool apps, and scripting bulk operations.

The API follows REST conventions and uses Bearer token authentication. Most endpoints return JSON. Rate limits apply — check the documentation for current limits per endpoint.

## Before you start

- Admin access to your Retool organization
- Basic familiarity with REST APIs and HTTP requests (curl or any HTTP client)
- Retool API token generated from Settings → Retool API

## Step-by-step guide

### 1. Generate a Retool API token

Navigate to Settings → Retool API (or Settings → API). Click 'Create new API token'. Give it a descriptive name like 'CI/CD Pipeline' or 'Admin Automation'. Select the scopes your use case needs — you can choose read-only or read-write access for different resource types (apps, users, workflows, etc.). Copy the token immediately — it's only shown once. Store it securely in a secrets manager or environment variable. Never commit API tokens to version control.

**Expected result:** API token generated and securely stored. Token has appropriate scopes for the intended use case.

### 2. Make your first API request — list all apps

Test the API with a simple GET request to list all apps in your organization. Use curl, Postman, or any HTTP client. The base URL for Retool Cloud is https://[your-org].retool.com/api/v2/. Include the Bearer token in the Authorization header. The response is a JSON array of app objects with id, name, createdAt, and metadata.

```
# List all apps in your Retool org (curl)
curl -X GET \
  'https://yourcompany.retool.com/api/v2/apps' \
  -H 'Authorization: Bearer YOUR_RETOOL_API_TOKEN' \
  -H 'Content-Type: application/json'

# Response:
# {
#   "apps": [
#     { "id": "abc123", "name": "Order Management", "createdAt": "2025-01-15T..." },
#     { "id": "def456", "name": "Customer Dashboard", "createdAt": "2025-02-20T..." }
#   ],
#   "totalCount": 47,
#   "nextPageToken": "xyz789"
# }
```

**Expected result:** API returns JSON list of all apps in the org.

### 3. Manage users programmatically

Use the Users API to automate user onboarding: create users, update their group memberships, and deactivate accounts when team members leave. This is especially useful when integrated with your HR system — new employee created in Workday → webhook → Retool API call creates their Retool account and assigns them to the correct group.

```
# Create a new user
curl -X POST \
  'https://yourcompany.retool.com/api/v2/users' \
  -H 'Authorization: Bearer YOUR_RETOOL_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "newemployee@company.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "groups": ["engineering"]
  }'

# Add user to a group
curl -X PUT \
  'https://yourcompany.retool.com/api/v2/groups/engineering/users' \
  -H 'Authorization: Bearer YOUR_RETOOL_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "userEmail": "newemployee@company.com" }'
```

**Expected result:** User created in Retool and assigned to the correct group via API.

### 4. Trigger deployments via API for CI/CD

Integrate Retool deployments into your CI/CD pipeline. After running tests, trigger a Retool app deployment via the API. This works best with Retool's Git sync (Enterprise) where code changes come from Git — the API trigger deploys the current main branch state to production. Without Git sync, the API can trigger a republish of the current editor state.

```
# Trigger a deployment (Enterprise + Git sync)
curl -X POST \
  'https://yourcompany.retool.com/api/v2/deployments' \
  -H 'Authorization: Bearer YOUR_RETOOL_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "appId": "abc123",
    "releaseVersion": "v2.5",
    "releaseNotes": "Automated deploy from CI/CD pipeline at $(date)"
  }'

# Check deployment status
curl -X GET \
  'https://yourcompany.retool.com/api/v2/deployments/deploy_xyz' \
  -H 'Authorization: Bearer YOUR_RETOOL_API_TOKEN'
```

**Expected result:** App deployed programmatically from CI/CD pipeline.

### 5. Call the Retool API from within a Retool app

You can build a Retool meta-app that manages other Retool apps using the API. Create a REST API resource in Retool pointing to https://[your-org].retool.com/api/v2 with the Authorization header set to Bearer {{ environment.variables.RETOOL_API_TOKEN }} (storing the token as a secret config variable). Then create queries to list apps, users, and groups. Build a UI with tables and forms to manage your org without leaving Retool.

```
// REST API Resource configuration:
// Base URL: https://yourcompany.retool.com/api/v2
// Header: Authorization = Bearer {{ environment.variables.RETOOL_API_TOKEN }}

// Query: listApps
// Method: GET
// URL path: /apps
// Result: {{ listApps.data.apps }}

// Query: createUser
// Method: POST
// URL path: /users
// Body (JSON):
// {
//   "email": "{{ emailInput.value }}",
//   "firstName": "{{ firstNameInput.value }}",
//   "lastName": "{{ lastNameInput.value }}",
//   "groups": ["{{ groupSelect.value }}"]
// }
```

**Expected result:** Retool meta-app successfully lists and manages apps and users via the Retool API.

## Complete code example

File: `Node.js script: retool-user-provisioning.js`

```javascript
// Node.js script for automated Retool user provisioning
// Run from CI/CD pipeline or HR system integration
// Requires: node-fetch or axios

const RETOOL_API_URL = 'https://yourcompany.retool.com/api/v2';
const RETOOL_API_TOKEN = process.env.RETOOL_API_TOKEN; // From environment variable

const retoolFetch = async (path, options = {}) => {
  const response = await fetch(`${RETOOL_API_URL}${path}`, {
    ...options,
    headers: {
      'Authorization': `Bearer ${RETOOL_API_TOKEN}`,
      'Content-Type': 'application/json',
      ...options.headers,
    },
  });

  if (!response.ok) {
    const error = await response.json().catch(() => ({ message: response.statusText }));
    throw new Error(`Retool API error ${response.status}: ${error.message}`);
  }

  return response.json();
};

// Create user and assign to group
const provisionUser = async ({ email, firstName, lastName, department }) => {
  // Create user
  const user = await retoolFetch('/users', {
    method: 'POST',
    body: JSON.stringify({ email, firstName, lastName }),
  });
  console.log(`Created user: ${email} (ID: ${user.id})`);

  // Map department to Retool group
  const groupMap = {
    engineering: 'Engineers',
    sales: 'Sales Team',
    support: 'Support',
    default: 'All Users',
  };
  const group = groupMap[department] || groupMap.default;

  // Add to group
  await retoolFetch(`/groups/${encodeURIComponent(group)}/users`, {
    method: 'PUT',
    body: JSON.stringify({ userEmail: email }),
  });
  console.log(`Added ${email} to group: ${group}`);

  return { user, group };
};

// Example usage
const newEmployee = {
  email: 'alice@company.com',
  firstName: 'Alice',
  lastName: 'Smith',
  department: 'engineering',
};

provisionUser(newEmployee)
  .then(result => console.log('Provisioning complete:', result))
  .catch(err => console.error('Provisioning failed:', err.message));
```

## Common mistakes

- **Hardcoding the Retool API token in scripts or Retool query bodies** — undefined Fix: Store tokens in environment variables (process.env.RETOOL_API_TOKEN in Node.js) or Retool's secret configuration variables. Reference as {{ environment.variables.RETOOL_API_TOKEN }} in Retool resource queries.
- **Not handling pagination in API responses, only processing the first page of results** — undefined Fix: Retool API responses include a nextPageToken field when more results exist. Implement pagination by following the token until it's empty or null to ensure you process all records.
- **Using the Retool API to trigger deployments without testing the app first** — undefined Fix: Always test deployments against a staging environment first. The API makes it easy to automate deployments, but automation without testing can push broken changes to production instantly.

## Best practices

- Store the Retool API token as an environment variable or in a secrets manager — never in code
- Use scoped tokens with minimum required permissions — create separate tokens for read-only monitoring and read-write automation
- Implement retry logic with exponential backoff for API calls in CI/CD pipelines — rate limits are per-minute
- Log all API operations for audit purposes — who provisioned which users at what time
- Test API automation against a staging Retool environment before running against production

## Frequently asked questions

### What is the rate limit for the Retool API?

Retool's API rate limits vary by endpoint and plan tier. As a general guideline, most read endpoints allow ~100 requests per minute per API token, and write endpoints allow ~20-50 requests per minute. Check the response headers for X-RateLimit-Remaining and X-RateLimit-Reset to implement dynamic rate limit handling.

### Can I use the Retool API to export or import app configurations?

Yes — the Retool API has endpoints to export app configurations as JSON and import them. This is useful for migrating apps between Retool organizations or creating app templates. App export includes all queries, components, and layout, but does not include resource credentials.

### Do I need Enterprise plan to use all Retool API features?

Basic API features (list apps, manage users, create groups) are available on Business plans. Advanced features like programmatic deployments with version control, organization-level settings management, and advanced audit log access typically require Enterprise. Check the Retool API documentation for per-endpoint plan requirements.

---

Source: https://www.rapidevelopers.com/retool-tutorial/how-to-use-retool-api-to-manage-applications
© RapidDev — https://www.rapidevelopers.com/retool-tutorial/how-to-use-retool-api-to-manage-applications