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.
| Fact | Value |
|---|---|
| Tool | Retool |
| Difficulty | Intermediate |
| Time required | 25-30 min |
| Compatibility | Retool Cloud and Self-hosted (some endpoints require Enterprise) |
| Last updated | March 2026 |
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.
Prerequisites
- 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
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.
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.
1# List all apps in your Retool org (curl)2curl -X GET \3 'https://yourcompany.retool.com/api/v2/apps' \4 -H 'Authorization: Bearer YOUR_RETOOL_API_TOKEN' \5 -H 'Content-Type: application/json'67# Response:8# {9# "apps": [10# { "id": "abc123", "name": "Order Management", "createdAt": "2025-01-15T..." },11# { "id": "def456", "name": "Customer Dashboard", "createdAt": "2025-02-20T..." }12# ],13# "totalCount": 47,14# "nextPageToken": "xyz789"15# }Expected result: API returns JSON list of all apps in the org.
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.
1# Create a new user2curl -X POST \3 'https://yourcompany.retool.com/api/v2/users' \4 -H 'Authorization: Bearer YOUR_RETOOL_API_TOKEN' \5 -H 'Content-Type: application/json' \6 -d '{7 "email": "newemployee@company.com",8 "firstName": "Jane",9 "lastName": "Smith",10 "groups": ["engineering"]11 }'1213# Add user to a group14curl -X PUT \15 'https://yourcompany.retool.com/api/v2/groups/engineering/users' \16 -H 'Authorization: Bearer YOUR_RETOOL_API_TOKEN' \17 -H 'Content-Type: application/json' \18 -d '{ "userEmail": "newemployee@company.com" }'Expected result: User created in Retool and assigned to the correct group via API.
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.
1# Trigger a deployment (Enterprise + Git sync)2curl -X POST \3 'https://yourcompany.retool.com/api/v2/deployments' \4 -H 'Authorization: Bearer YOUR_RETOOL_API_TOKEN' \5 -H 'Content-Type: application/json' \6 -d '{7 "appId": "abc123",8 "releaseVersion": "v2.5",9 "releaseNotes": "Automated deploy from CI/CD pipeline at $(date)"10 }'1112# Check deployment status13curl -X GET \14 'https://yourcompany.retool.com/api/v2/deployments/deploy_xyz' \15 -H 'Authorization: Bearer YOUR_RETOOL_API_TOKEN'Expected result: App deployed programmatically from CI/CD pipeline.
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.
1// REST API Resource configuration:2// Base URL: https://yourcompany.retool.com/api/v23// Header: Authorization = Bearer {{ environment.variables.RETOOL_API_TOKEN }}45// Query: listApps6// Method: GET7// URL path: /apps8// Result: {{ listApps.data.apps }}910// Query: createUser11// Method: POST12// URL path: /users13// Body (JSON):14// {15// "email": "{{ emailInput.value }}",16// "firstName": "{{ firstNameInput.value }}",17// "lastName": "{{ lastNameInput.value }}",18// "groups": ["{{ groupSelect.value }}"]19// }Expected result: Retool meta-app successfully lists and manages apps and users via the Retool API.
Complete working example
1// Node.js script for automated Retool user provisioning2// Run from CI/CD pipeline or HR system integration3// Requires: node-fetch or axios45const RETOOL_API_URL = 'https://yourcompany.retool.com/api/v2';6const RETOOL_API_TOKEN = process.env.RETOOL_API_TOKEN; // From environment variable78const retoolFetch = async (path, options = {}) => {9 const response = await fetch(`${RETOOL_API_URL}${path}`, {10 ...options,11 headers: {12 'Authorization': `Bearer ${RETOOL_API_TOKEN}`,13 'Content-Type': 'application/json',14 ...options.headers,15 },16 });1718 if (!response.ok) {19 const error = await response.json().catch(() => ({ message: response.statusText }));20 throw new Error(`Retool API error ${response.status}: ${error.message}`);21 }2223 return response.json();24};2526// Create user and assign to group27const provisionUser = async ({ email, firstName, lastName, department }) => {28 // Create user29 const user = await retoolFetch('/users', {30 method: 'POST',31 body: JSON.stringify({ email, firstName, lastName }),32 });33 console.log(`Created user: ${email} (ID: ${user.id})`);3435 // Map department to Retool group36 const groupMap = {37 engineering: 'Engineers',38 sales: 'Sales Team',39 support: 'Support',40 default: 'All Users',41 };42 const group = groupMap[department] || groupMap.default;4344 // Add to group45 await retoolFetch(`/groups/${encodeURIComponent(group)}/users`, {46 method: 'PUT',47 body: JSON.stringify({ userEmail: email }),48 });49 console.log(`Added ${email} to group: ${group}`);5051 return { user, group };52};5354// Example usage55const newEmployee = {56 email: 'alice@company.com',57 firstName: 'Alice',58 lastName: 'Smith',59 department: 'engineering',60};6162provisionUser(newEmployee)63 .then(result => console.log('Provisioning complete:', result))64 .catch(err => console.error('Provisioning failed:', err.message));Common mistakes
Why it's a problem: Hardcoding the Retool API token in scripts or Retool query bodies
How to avoid: 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.
Why it's a problem: Not handling pagination in API responses, only processing the first page of results
How to avoid: 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.
Why it's a problem: Using the Retool API to trigger deployments without testing the app first
How to avoid: 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
Still stuck?
Copy one of these prompts to get a personalized, step-by-step explanation.
I want to automate Retool user management using the Retool API. I need a Node.js script that: (1) creates a new user via POST /api/v2/users with email, firstName, lastName, (2) adds the user to a specific group via PUT /api/v2/groups/{groupName}/users, (3) handles 401/403 errors gracefully with descriptive messages, (4) uses a RETOOL_API_TOKEN environment variable for authentication (Bearer token in Authorization header), (5) can be triggered from a CI/CD pipeline when a new employee joins. Write the complete Node.js script with error handling.
Set up a Retool REST API resource for the Retool API: Base URL https://yourcompany.retool.com/api/v2, Header Authorization: Bearer {{ environment.variables.RETOOL_API_TOKEN }}. Create query 'listUsers' (GET /users), query 'createUser' (POST /users with JSON body), query 'listApps' (GET /apps). Show how to display app list in a Table component and create a form for user creation in a Retool meta-app.
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.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation