Retool¶
Your internal tools can use AI without each one holding a provider's key. Add the gateway once as a resource, and every AI query that uses it is checked against your policies, charged to the right team and recorded in Request logs, with Claude and Gemini as reachable as OpenAI's models.
What it is¶
Retool builds internal apps, workflows and agents. Its Custom AI Provider resource connects any service that speaks
the OpenAI Chat Completions format, which the gateway does at /v1. AI queries in apps and workflows can then use it
like any other AI resource.
The two settings¶
Go to Resources, choose Create new › Resource, search for Custom AI Provider, and fill in:
| Field | Value |
|---|---|
| Name | A name your builders will recognise, for example Vidai |
| Base URL | https://<your-gateway>/v1 |
| API Key | Your Vidai key (starts vk_), never a provider's key |
| Compatible Schema | OpenAI |
| Model Names | The names your organisation has approved, for example gpt-4o-mini, claude-sonnet-4.5 |
| Headers | Leave empty |
Then choose Create resource. The gateway's address, and the base URL for each kind of client, are under Connect your app on the Keys page and in System › Settings › Gateway. You get the key from Keys › Issue a key; its secret is shown once.
A minimal call¶
AI resources have no Test connection button, so test with a query:
- In an app, add an AI query and choose the resource you created.
- Pick a model from its list, for example
gpt-4o-mini. - Type a prompt such as "Say hello in Dutch" and run the query.
Every model in Model Names goes through the same resource: claude-sonnet-4.5 or gemini-3.5-flash work like
gpt-4o-mini. The gateway translates the request for that provider and the answer back into the OpenAI shape.
Reading what the gateway did¶
AI queries don't show response headers. Find the call in Request logs: filter by Key or Model under More filters. Each call shows the model that answered, its cost, and which policy or rule acted on it.
When you need the headers in an app, call https://<your-gateway>/v1/chat/completions from a REST API resource
(header Authorization: Bearer vk_…); the query's response metadata includes x-vidai-request-id, the call's
reference for Request logs › Request reference.
Errors¶
A refused call fails the query with the gateway's status and message.
| Status | Gateway code | What to do |
|---|---|---|
| 401 | invalid_api_key, missing_api_key |
Check the resource's API Key |
| 403 | model_not_allowed, denied_by_routing_rule |
Use a model your key may call |
| 403 | content_guardrail_blocked |
A guardrail stopped the content |
| 404 | model_not_found |
Check Model Names against Models |
| 429 | rate_limit_exceeded, token_limit_exceeded, concurrency_limit_exceeded |
Slow down |
Model names¶
List in Model Names the names your organisation has approved, as shown under Models in the Control room. A
GET to https://<your-gateway>/v1/models with your key returns exactly the models the key may call. An alias set by
an admin works like any other name.
What goes through the gateway¶
| In Retool | Through the gateway |
|---|---|
| AI queries in apps, workflows and agents using the Custom AI Provider resource | Yes, to every provider your organisation has set up |
| A REST API resource calling the gateway | Yes |
| Retool's own AI features using Retool-managed models, and AI resources with a provider's own key | No |
Check it works in a minute¶
Run the AI query above with the prompt "ping". A short answer means the address and key are right. The call shows in Request logs within seconds.
Good to know¶
- On Retool Cloud the gateway must be reachable from the internet; a self-hosted Retool needs to reach it on your network.
- One key per resource: create a second resource with its own key for an app or team whose spend you want apart.
- Where your Retool plan includes resource environments (production, staging), each environment can use its own key.
- Choose OpenAI as the Compatible Schema even for Claude and Gemini models: the gateway does the translating.