Skip to content

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:

  1. In an app, add an AI query and choose the resource you created.
  2. Pick a model from its list, for example gpt-4o-mini.
  3. 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.