Retool OpenAPI Resource: Override Base URL per Environment

If you're using a Retool OpenAPI resource and can't figure out how to override the base URL for your staging environment, you're in good company. This is one of the most commonly reported pain points with the OpenAPI resource type in Retool: the spec's servers field gets picked up automatically, but there's no obvious UI knob to swap it out per environment. The result? Teams end up maintaining two copies of their spec — one for staging, one for production — and syncing them manually every time something changes. This guide shows you how to solve that properly using OpenAPI server variables.

Why Retool Locks Onto Your Production Server URL

When you point Retool at an OpenAPI spec, it reads the servers array and uses the first URL it finds as the base for all requests. If your spec looks like this:

{"servers": [{"url": "https://api.yourcompany.com"}]}

…Retool will use https://api.yourcompany.com regardless of whether you've switched to the staging environment in your workspace. There's no built-in field to override that value at the resource level — unless you use server variables. That's the key insight most people miss.

What Are OpenAPI Server Variables?

OpenAPI 3.0 supports a feature called server variables — templated placeholders in your server URL that can be swapped out at runtime. Instead of hardcoding a full URL, you define a URL template with a variable, then list the allowed values and a default. Retool reads these variables and exposes them as configurable fields on the resource settings page, with the ability to set a different value per environment.

How to Set Up Server Variables in Your OpenAPI Spec

Here's how to restructure your servers block to take advantage of this. Replace a hardcoded URL like this:

{"servers": [{"url": "https://api.yourcompany.com"}]}

With a templated version using a server variable:

{"servers": [{"url": "https://{environment}.yourcompany.com", "description": "Dynamic environment endpoint", "variables": {"environment": {"enum": ["api", "staging-api"], "default": "api"}}}]}

Or, if your staging and production URLs have completely different structures, you can use the variable to represent the entire host:

{"servers": [{"url": "{baseUrl}", "description": "Configurable base URL", "variables": {"baseUrl": {"enum": ["https://api.yourcompany.com", "https://staging.yourcompany.com"], "default": "https://api.yourcompany.com"}}}]}

Either pattern works — the important thing is that the variables object is present inside the server entry. Without it, Retool won't render the server variable fields in the UI.

Step-by-Step: Configuring the Resource in Retool

• Step 1: Update your OpenAPI spec file to use server variables as shown above. Save and re-host or re-upload the file.
• Step 2: In Retool, go to the Resources page and create a new OpenAPI resource pointing at your updated spec. Important: existing resources may not pick up the new server variable fields — this appears to be a known limitation. Creating a new resource is the most reliable path.
• Step 3: Once the resource is created and the spec is loaded, you should see a Server Variables section appear on the resource configuration page.
• Step 4: In that section, set the variable value for your Production environment (e.g., https://api.yourcompany.com) and a different value for Staging (e.g., https://staging.yourcompany.com).
• Step 5: Save the resource. Now when you toggle between environments in Retool, queries using this resource will automatically hit the correct base URL.

Why Existing Resources May Not Show Server Variables

Several users have hit this wall: you update your spec to include variables, but the server variable section never appears on your existing resource's settings page. This happens because Retool appears to parse the spec at resource creation time and may not re-evaluate the schema on subsequent saves. The workaround is straightforward — create a new resource pointing at the updated spec rather than editing the existing one. Once you've confirmed the new resource works correctly with server variables, you can update your apps to use it and delete the old resource.

What If You're Using a Vendor-Hosted Spec?

If you're consuming an OpenAPI spec hosted by a third-party vendor — where you have no control over the spec file itself — and that vendor hosts multiple tenants at different base URLs, server variables won't help directly. In this case, your best current option is to create separate OpenAPI resources in Retool, one per tenant or environment, each pointing at the same spec URL but configured with different credentials or base paths where possible. It's not elegant, but it avoids duplicating the spec file itself since the source remains the vendor's canonical URL.

The Bottom Line

The fix for overriding a Retool OpenAPI resource's base URL per environment is to use OpenAPI 3.0 server variables in your spec. Once your servers block includes a variables definition, Retool exposes per-environment controls directly in the resource UI — no duplicate spec files, no manual syncing. If the server variable fields don't appear, create a fresh resource rather than editing the existing one. It's an extra step, but it's a one-time fix that keeps your staging and production workflows cleanly separated from a single source of truth.