Zapier¶
A Zap that summarises a form, drafts a reply or sorts a ticket can call your organisation's approved models through the gateway: 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¶
Zapier connects apps with Zaps. Its built-in ChatGPT (OpenAI) app always calls OpenAI with an OpenAI key: it has no setting for another address, so it can't go through the gateway. Two of Zapier's own tools can:
- Webhooks by Zapier, action Custom Request: sends any HTTP request. A premium app, on Zapier's paid plans.
- Code by Zapier, Run Python (or Run JavaScript): a few lines of code that call the gateway. Python's
requestslibrary is built in.
Both call the gateway's chat endpoint, which reaches every provider your organisation has set up.
The two settings¶
| Setting | Value |
|---|---|
| Address | https://<your-gateway>/v1/chat/completions |
| Key | An Authorization header with the value Bearer vk_…: your Vidai key, never a provider's key |
The gateway's address is 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. Zapier has no secret store for these steps, so anyone who can edit the Zap can read the key: issue one key for the Zap (or a group of Zaps) and never share the Zap as a template with the key in it.
A minimal call¶
- Add an action step: Webhooks by Zapier, event Custom Request.
- Method:
POST. URL:https://<your-gateway>/v1/chat/completions. -
Data (sent exactly as typed, so keep it valid JSON):
{ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Say hello in Dutch."}] } -
Headers:
Authorization=Bearer vk_…, andContent-Type=application/json. - Test the step. The answer is in
choices, first item,message›content.
Add an action step Code by Zapier, event Run Python. Under Input Data add prompt (mapped from an
earlier step) and key (your Vidai key), then:
import requests
r = requests.post(
"https://<your-gateway>/v1/chat/completions",
headers={"Authorization": "Bearer " + input_data["key"]},
json={"model": "gpt-4o-mini", "messages": [{"role": "user", "content": input_data["prompt"]}]},
timeout=60,
)
output = {
"status": r.status_code,
"reply": r.json()["choices"][0]["message"]["content"] if r.ok else "",
"error_code": r.headers.get("x-vidai-error-code", ""),
"request_id": r.headers.get("x-vidai-request-id", ""),
}
Later steps can map reply, error_code and request_id.
The same step calls Claude or Gemini: put a name such as claude-sonnet-4.5 in model. The gateway translates the
request for that provider and the answer back into the OpenAI shape.
Mapping text from an earlier step straight into the Data of a Custom Request breaks the JSON when that text has quotes or line breaks. The Code step builds the JSON for you, so prefer it for free text.
Reading what the gateway did¶
A Webhooks step doesn't show the response headers. The Code step above returns x-vidai-request-id, the call's
reference: paste it into Request logs › Request reference. Or find the call in Request logs with the Key or
Model filter under More filters. Cost is never in the answer; it's on the call in Request logs.
Errors¶
| Status | Gateway code | What to do |
|---|---|---|
| 401 | invalid_api_key, missing_api_key |
Check the Authorization header: Bearer then the 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 the model name on Models |
| 429 | rate_limit_exceeded, token_limit_exceeded, concurrency_limit_exceeded |
Slow the Zap down |
Match on the x-vidai-error-code header (the Code step returns it), not on the message.
Model names¶
Use the names your organisation has approved, as listed under Models in the Control room. A GET to
https://<your-gateway>/v1/models with the same header lists exactly the models your key may call.
What goes through the gateway¶
| In Zapier | Through the gateway |
|---|---|
| Webhooks by Zapier or Code by Zapier calling the gateway | Yes, to every provider your organisation has set up |
| The ChatGPT (OpenAI) app, AI by Zapier and Zapier's other built-in AI features | No: they use Zapier's or OpenAI's own connection |
| Streaming | No: a Zap step waits for the whole answer |
Check it works in a minute¶
Test the step in the Zap editor 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¶
- The gateway must be reachable from the internet: Zapier runs every step in its own cloud.
- One key per Zap, or per team of Zaps, keeps their spend apart: what the key acts for decides who pays.
- The gateway's own 429 has no
Retry-Afterheader; Zapier's replay of failed runs is the simplest way to try again. - A Zap step times out on Zapier's side after a while; keep prompts and answers short, and set
max_tokens.