Reference

# One base URL, one key.

Everything the gateway serves, the headers it sets, the errors it returns and what bounds what you spend. It speaks the OpenAI HTTP API, so an existing client points at it by changing two lines.

On this page

Your first callAuthenticationEndpointsMedia, 3D and trainingRealtime voiceClients that work unchangedGoogle GenAI SDKStructured outputThinkingWhat comes backRoutes and fallbacksStored promptsCachingAttributionA daily limit for each of your usersBatchesBatches from a fileBatch statusesBatch refusalsWorkflowsWorkflow guardrailsErrorsWhat it costsWebhooksChannelsVatan MCPWhat an API key cannot do

## Your first call

One base URL and one key. Everything else on this page is optional.

The gateway speaks the OpenAI HTTP API. An existing client points at it by changing two lines: the base URL and the key. Nothing else in your code changes, and the response shape is the one your SDK already parses.

```
curl -s https://gateway.vatan.one/v1/chat/completions \
 -H "authorization: Bearer $VATAN_API_KEY" \
 -H "content-type: application/json" \
 -d '{
 "model": "anthropic/claude-sonnet-5",
 "messages": [{ "role": "user", "content": "Say hello" }]
 }'
```

Watch the gateway demo

85 seconds, silent, with the text on screen.The console screens are examples, not a customer account.

In the console: [Create a key](https://vatan.one/gateway/keys)

## Authentication

A bearer key, and the budget, rate limit and address allowlist it carries.

Every request needs `authorization: Bearer <key>`. A key is stored as a sha256 and there is no path back to the value, so a key you have lost is replaced rather than recovered.

A key is not only a credential. It carries the budget it may spend, its own rate limit, and optionally a list of addresses it may be used from. Those are the things that refuse a request before any model sees it.

A workspace can hold many keys, each with its own budget, so one app cannot spend another's.

| Carried on a key | What it does |
| Budget | A ceiling in dollars, for its lifetime or per calendar month. Past it, the key is refused and the rest of the workspace carries on. |
| Rate limit | Requests and tokens a minute, per key. A burst is refused with 429 rather than queued. |
| Address allowlist | CIDR ranges the key may be used from. Empty means anywhere. |
| Team | Which people in the workspace can see and spend from it. |

In the console: [Keys](https://vatan.one/gateway/keys)

## Endpoints

What the gateway serves, and the shape each one speaks.

Nine endpoints take live traffic; chat completions can also run as a batch. Two more let other vendors' clients work unchanged.

| Endpoint | What it is |
| POST /v1/chat/completions | Completions, streaming or not, with tools. The endpoint most callers use and the default for a batch. |
| POST /v1/embeddings | Vectors for text. Takes one string or an array of them. |
| POST /v1/decisions | A typed choice: yes or no, one of a set, or a score. |
| POST /v1/images/generations | Pictures. Returns a URL or base64 depending on the model. |
| POST /v1/audio/speech | Text to speech. Returns audio bytes. |
| POST /v1/audio/transcriptions | Speech to text, multipart, files up to 25 MB. |
| WSS /v1/realtime | A live spoken conversation over a WebSocket, with openai/gpt-realtime or openai/gpt-realtime-mini. See Realtime voice below. |
| POST /v1/videos | Starts a video job. Poll GET /v1/videos/{id}, then GET /v1/videos/{id}/content for the bytes. |
| POST /v1/3d | Starts a 3D job. Poll GET /v1/3d/{id}, then GET /v1/3d/{id}/content?format=glb for the model file. |
| POST /v1/training | Trains on a dataset. Send dry_run first for the exact price, then max_usd at least that. Poll GET /v1/training/{id}, then GET /v1/training/{id}/content for the trained file. |
| POST /v1/messages | Anthropic's own shape, for a client that speaks it. Also /v1/messages/count_tokens. |
| POST /v1/responses | OpenAI's Responses API. Codex requires this one and has no fallback. |
| POST /v1beta/models/{model}:generateContent | Google's own shape, for a client that speaks it. Also :streamGenerateContent, :countTokens, :batchEmbedContents, :predictLongRunning, :batchGenerateContent and /upload/v1beta/files. |
| GET /v1/models | The catalogue, in OpenAI shape or, for an Anthropic client, Anthropic's. `attachments` lists what chat models read besides text; `attachments_unknown`, what is unconfirmed. Prices are per token, in pricing.input_usd_per_token and pricing.output_usd_per_token. |

In the console: [Browse the catalogue](https://vatan.one/gateway/models)

## Media, 3D and training

How to call the picture, speech, video, 3D and training models, including the ones from fal, and what they refuse.

Find a media model in `GET /v1/models`: its `capabilities` says `images`, `speech`, `video` or `3d`. Send it to the matching endpoint above with the same key. Prices are per picture, per megapixel, per 1,000 characters or per generation, and a request is charged once it has finished. A fal model's row also carries a one-line `usage` saying how to call it. fal models run at fal.ai, whose terms let it use anonymised data derived from inputs; the Trust page lists it.

A picture model takes `prompt`, `n` (1 to 4), `size` as `1024x768` and `seed`. A model that edits a picture also takes `image`: an https link or a base64 data URI. The gateway never fetches your link; the provider does. Options that belong to one model go in a `fal` object. Each model lists the few it allows, and any other field is refused by name, because some options change what the provider charges.

Files go in by kind. A picture editor takes `image`; when it bills by the megapixel it must be a base64 PNG, JPEG, GIF or WebP, so its size can be read. A video-to-video model takes `video`, a base64 MP4 of at most 15 seconds, and is billed for that length. An audio-to-audio model takes `audio` and a 3D-to-3D model takes `mesh`. Models that make a video from a picture also accept a `prompt` when they list one. A trained LoRA goes in `fal.loras`.

A training run is quoted first. Send `dry_run: true` for the exact price, then the run with `max_usd` at least that, poll it, and fetch the trained file. When a video, 3D or training job ends, a `media.job.finished` webhook says so; the file is still fetched with your key.

A video takes `model`, `prompt`, `duration` in seconds, and `resolution` (`720p`) or `size` (`1280x720`). Add `aspect_ratio: "9:16"` for a vertical clip. Each model makes only some sizes, and the error names the ones it has.

Newer models start inside a daily request limit while their cost is checked against the provider's bill. Polling and downloading a job never count. A model that costs more than it brings in is paused, and a job already started still finishes and is charged.

| You see | What it means |
| 400, naming a field | The model does not take that field, or the field changes the price. Remove it or use one the message lists. |
| 429 on a media model | That model's daily limit of new jobs is used up. It resets at midnight UTC. Polling and downloading still work. |
| 503 saying paused | The model is switched off while its cost is checked. It is not retired. |
| Your request id | In the console trace drawer, a media call shows what it was billed on and the provider's own error. |

A picture, curl

```
curl https://gateway.vatan.one/v1/images/generations \
 -H "authorization: Bearer $VATAN_API_KEY" \
 -H "content-type: application/json" \
 -d '{ "model": "fal/fal-ai/flux/dev", "prompt": "a small wooden chair", "size": "1024x768" }'
```

A vertical video, curl

```
curl https://gateway.vatan.one/v1/videos \
 -H "authorization: Bearer $VATAN_API_KEY" \
 -H "content-type: application/json" \
 -d '{ "model": "openrouter/bytedance/seedance-2.5", "prompt": "a paper boat on a river",
 "resolution": "720p", "aspect_ratio": "9:16", "duration": 5 }'
# then GET https://gateway.vatan.one/v1/videos/{id} until it says completed,
# and GET https://gateway.vatan.one/v1/videos/{id}/content for the file
```

A 3D model, curl

```
curl https://gateway.vatan.one/v1/3d \
 -H "authorization: Bearer $VATAN_API_KEY" \
 -H "content-type: application/json" \
 -d '{ "model": "fal/fal-ai/meshy/v7/text-to-3d", "prompt": "a small wooden chair" }'
# then GET https://gateway.vatan.one/v1/3d/{id} until it says completed,
# and GET https://gateway.vatan.one/v1/3d/{id}/content?format=glb for the file
```

A training run, curl

```
# the exact price first: nothing is held or started
curl https://gateway.vatan.one/v1/training \
 -H "authorization: Bearer $VATAN_API_KEY" -H "content-type: application/json" \
 -d '{ "model": "fal/fal-ai/qwen-image-2512-trainer", "steps": 1000, "dry_run": true }'
# then the run, naming a ceiling at least that price
curl https://gateway.vatan.one/v1/training \
 -H "authorization: Bearer $VATAN_API_KEY" -H "content-type: application/json" \
 -d '{ "model": "fal/fal-ai/qwen-image-2512-trainer", "steps": 1000, "max_usd": 2, "dataset": "https://example.com/photos.zip" }'
```

In the console: [Browse the catalogue](https://vatan.one/gateway/models)

## Realtime voice

A live spoken conversation with OpenAI's realtime models over a WebSocket, open to every workspace.

Connect with `wss://` to `/v1/realtime?model=openai/gpt-realtime-mini`, with your key as a Bearer token or, from a browser, in the `openai-insecure-api-key.<key>` subprotocol.

Events pass through unchanged, so OpenAI's realtime SDKs work by changing the base URL.

Each response is charged when it finishes. About five minutes of use is held from your balance ahead of it, and the session closes when that cannot be held.

Sessions last 30 minutes at most, 5 per key.

For the caller's words as text, set `audio.input.transcription` in `session.update`, naming `openai/gpt-4o-mini-transcribe` (the default), `openai/gpt-4o-transcribe`, `openai/gpt-transcribe` or `openai/whisper-1`.

Each transcript costs $0.0000013125 a token in and $0.00000525 out on gpt-4o-mini-transcribe, twice that on gpt-4o-transcribe, and per second $0.00007875 on gpt-transcribe and $0.000105 on whisper-1.

A gateway update closes sessions with code 1012. Reconnect: only finished responses are charged.

| Price per token | gpt-realtime and gpt-realtime-mini |
| Audio in, cached | $0.0000336 and $0.0000105; cached $0.00000042 and $0.000000315. |
| Audio out | $0.0000672 and $0.000021. |
| Text in, cached | $0.0000042 and $0.00000063; cached $0.00000042 and $0.000000063. |
| Text out | $0.0000168 and $0.00000252. |
| Image in | $0.00000525 and $0.00000084. |

Open a session, Python

```
from openai import OpenAI

client = OpenAI(api_key=VATAN_API_KEY, base_url="https://gateway.vatan.one/v1")
with client.realtime.connect(model="openai/gpt-realtime-mini") as conn:
 conn.session.update(session={"type": "realtime", "output_modalities": ["audio"]})
 conn.response.create()
 for event in conn:
 if event.type == "response.done":
 break
```

## Clients that work unchanged

What a two-line change gets you, and the one client that needs a specific endpoint.

The OpenAI SDKs, the Anthropic SDKs, the Google GenAI SDK, Claude Code, Codex and n8n all work against this gateway with a base URL and a key. Codex is the one with a hard requirement: it speaks `/v1/responses` and nothing else.

OpenAI SDK, TypeScript

```
const client = new OpenAI({
 baseURL: 'https://gateway.vatan.one/v1',
 apiKey: process.env.VATAN_API_KEY,
})
```

Anthropic SDK, or Claude Code

```
export ANTHROPIC_BASE_URL="https://gateway.vatan.one"
export ANTHROPIC_AUTH_TOKEN="$VATAN_API_KEY"
```

Watch Codex run on a Vatan key

82 seconds, silent, with the text on screen.The terminal is a real recording; the console screen is an example. The slow part is sped up.

In the console: [Connect your app](https://vatan.one/gateway/integrate)

## Google GenAI SDK

What `google-genai` can do through this gateway, and what it cannot.

The base URL is the only edit, because the SDK already sends the key as `x-goog-api-key`. Completions, streaming, chats, tool calling, structured output, images both ways, embeddings, files, batches and video all work.

Batches follow the same rules as every other batch here. The model id must end `:batch`.

A call through this door is metered and budgeted exactly as the same request through `/v1/chat/completions`. It is a translation, not a second pipeline.

Anything this door cannot translate is refused by name, never quietly removed. The refusal says what to use instead.

| Not served | What to use instead |
| Context caching (cachedContents) | Vatan's own cache, under Gateway, Caching. A Google cache belongs to the project that made it, and every workspace here shares one. |
| Fine-tuning (tunedModels) | The published models, listed at GET /v1beta/models. |
| Ephemeral tokens (auth_tokens) | A key with its own budget and rate limit. These are for the Live API, which needs a realtime connection. |
| File search stores | Vatan Knowledge, at /v1/knowledge on the control plane. |
| Agents, environments, credentials, triggers | Vatan's own agents and webhooks, run from the console. |
| Deleting a model or a batch | 405. A batch is kept so its usage row can still be read. |
| topK | `topP`. The providers behind this gateway take top_p and not top_k. |
| Logprobs on Gemini models | Nothing. Remove `responseLogprobs` and `logprobs`. |
| speechConfig, audioTimestamp | The audio endpoints: /v1/audio/speech and /v1/audio/transcriptions. |
| mediaResolution, routingConfig | Routing is Vatan’s own. Name the model you want, or use a route. |

google-genai, Python

```
import os
from google import genai

client = genai.Client(
 api_key=os.environ["VATAN_API_KEY"],
 http_options={"base_url": "https://gateway.vatan.one"},
)
```

google-genai, name, keep, then delete

```
from google.genai import types

short = genai.Client(
 api_key=os.environ["VATAN_API_KEY"],
 http_options={
 "base_url": "https://gateway.vatan.one",
 # seconds, 3600 to 2592000; without it a file is kept 30 days
 "headers": {"x-vatan-expires-after": "3600"},
 },
)
short.files.upload(
 file="batch.jsonl",
 config=types.UploadFileConfig(display_name="nightly-2026-09-27", mime_type="application/jsonl"),
)

# page_size goes up to 100 (default 50); the pager follows nextPageToken
files = list(client.files.list(config=types.ListFilesConfig(page_size=100)))

for f in files:
 if f.display_name.startswith("nightly-"): # display_name, else the filename
 client.files.delete(name=f.name)
```

In the console: [Connect your app](https://vatan.one/gateway/integrate)

## Structured output

Getting JSON back that matches a schema you wrote, on either door.

On the OpenAI wire this is `response_format`, with `json_schema` or `json_object`. Every provider here honours it, emulated where the provider has no such field.

GOOGLE HAS TWO SCHEMA FIELDS AND THEY ARE NOT THE SAME. `responseJsonSchema` takes full JSON Schema. `responseSchema` takes Google’s smaller OpenAPI subset.

A Pydantic `model_json_schema()` is full JSON Schema, so it goes in `responseJsonSchema`. Nested models work: `$defs` and `$ref` are kept as you wrote them.

Sending both is refused, and so is a schema beside a `responseMimeType` that contradicts it. They are alternatives, and Vatan will not pick for you.

| Field | What it takes |
| responseJsonSchema | Full JSON Schema, $defs and $ref included. What a Pydantic model_json_schema() emits. |
| responseSchema | Google’s OpenAPI subset. Refused alongside responseJsonSchema. |
| responseMimeType | application/json, or text/plain. Refused when it contradicts a schema you also sent. |
| response_format | The OpenAI wire spelling, with json_schema or json_object. Served on every provider. |

google-genai, a nested Pydantic model

```
from pydantic import BaseModel

class Address(BaseModel):
 street: str
 city: str

class CompanyInfo(BaseModel):
 name: str
 address: Address
 tags: list[str]

answer = client.models.generate_content(
 model="google/gemini-3.5-flash",
 contents="Acme Ltd, 1 High Street, London. Tags: retail, uk.",
 config={
 "max_output_tokens": 2000,
 "response_mime_type": "application/json",
 "response_json_schema": CompanyInfo.model_json_schema(),
 },
)

print(CompanyInfo.model_validate_json(answer.text))
```

## Thinking

Asking a reasoning model how hard to think, and reading what it cost.

Gemini models think by default, and you can set how much. Send a budget in tokens, or a level such as "LOW". Not both. The fields are below.

Thinking is bounded by `max_output_tokens`, so a bound you set caps the whole answer, thoughts included. That is what makes a batch cost checkable.

THOUGHT TOKENS ARE BILLED AS OUTPUT, on every provider. A reasoning model can spend far more on thinking than on the answer you read.

On the Google door the two counts are separate, and the total is their sum. On the OpenAI wire thinking sits inside `completion_tokens`, streamed or not.

That wire carries the same settings in `vatan_google`, which only Google models accept. Any other model refuses the request rather than ignoring the field.

| Field | What it does |
| thinkingBudget | A whole number of tokens. 0 switches thinking off. Refused alongside thinkingLevel. |
| thinkingLevel | A word such as LOW or HIGH, sent to Google unchanged. Refused alongside thinkingBudget. |
| includeThoughts | Returns the reasoning as its own part, marked `thought`. The answer part stays clean. |
| vatan_google | The same three on the OpenAI wire, as thinking_budget, thinking_level and include_thoughts. |
| thoughtsTokenCount | Thinking tokens on the Google door. Billed at the output rate. |
| completion_tokens_details.reasoning_tokens | The same number on the OpenAI wire, counted inside completion_tokens. |

google-genai, a level and the thoughts

```
answer = client.models.generate_content(
 model="google/gemini-3.5-flash",
 contents="Which is heavier, a kilo of steel or a kilo of feathers?",
 config={
 "max_output_tokens": 2000,
 "thinking_config": {"thinking_level": "LOW", "include_thoughts": True},
 },
)

for part in answer.candidates[0].content.parts:
 print("thought" if part.thought else "answer", part.text)

print(answer.usage_metadata.thoughts_token_count, "tokens of thinking")
```

The same request on the OpenAI wire

```
curl -s https://gateway.vatan.one/v1/chat/completions \
 -H "authorization: Bearer $VATAN_API_KEY" \
 -H "content-type: application/json" \
 -d '{
 "model": "google/gemini-3.5-flash",
 "messages": [{ "role": "user", "content": "Which is heavier?" }],
 "max_tokens": 2000,
 "vatan_google": { "thinking_level": "LOW" }
 }'
```

## What comes back

The headers on a response, and the one header you can send.

Every response carries `x-vatan-request-id`. It is the string to quote in a support conversation: it resolves to the request, its trace and its usage row.

| Header | What it tells you |
| x-vatan-request-id | This request. Resolves on the Requests screen and in a trace. |
| x-vatan-model | The model that answered, which is not always the one you asked for. |
| x-vatan-resolved-from | The name you sent, when it was an alias, a route or auto. |
| x-vatan-auto-tier / x-vatan-auto-reason | On model auto: fast or strong, and a short reason such as "strong: asks for work". |
| x-vatan-route / x-vatan-route-tried | The route that served it and every model it tried on the way, in order. |
| x-vatan-prompt | The stored prompt used, as name@version. |
| x-vatan-cache | hit, miss, semantic-hit or semantic-miss. With cache-age, cache-source and, on a semantic hit, cache-similarity. |
| x-vatan-prompt-tokens / completion-tokens / cached-tokens | What was metered, before the response body is parsed. |
| x-vatan-cost-usd | What this request cost, in dollars. |
| x-vatan-tags | Sent by you, not returned. Up to five key=value pairs written onto the usage row. |
| x-vatan-user-daily-limit-usd | Sent by you, not returned. What the user named in the body may spend in a UTC day, in dollars. |

## Routes and fallbacks

A ladder of models under one name, so a provider outage is a slower answer rather than an error.

A route is a name and an ordered list of models. Send the route name where a model id would go and the gateway tries them in order until one answers. The response says which one did, and which were tried.

Nothing has to change in your code to use one: a route name goes in the `model` field.

Or send `model: "auto"` and the gateway chooses per request from a small vetted set. A fast model answers by default. A stronger one answers work, reasoning, many tools or a long context. You are billed for the model that answered, at its own price.

Auto is chat only. Every other endpoint answers 400 with `auto_chat_only`. To keep one model across a task, send the id from `x-vatan-model` on later calls. `auto` cannot be a route name.

```
# "cheap-summariser" is a route, not a model.
curl -s https://gateway.vatan.one/v1/chat/completions \
 -H "authorization: Bearer $VATAN_API_KEY" \
 -H "content-type: application/json" \
 -d '{"model": "cheap-summariser", "messages": [{"role":"user","content":"..."}]}'

# The response says what happened:
# x-vatan-route: cheap-summariser
# x-vatan-route-tried: google/gemini-3.1-flash,anthropic/claude-haiku-4.5
# x-vatan-model: anthropic/claude-haiku-4.5
```

**REQUEST**model: "cheap-summariser"a route name where a model id would go

**THE ROUTE, IN ORDER**

**FIRST**No answergoogle/gemini-3.1-flash

**NEXT**This one answersanthropic/claude-haiku-4.5

**THE RESPONSE SAYS**Which route, what was tried, what answeredx-vatan-route, x-vatan-route-tried, x-vatan-model

**OR model: "auto"**A fast model by defaulta stronger one for work, reasoning, many tools or a long context; chat only

Press enter or space to select a node. You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

In the console: [Routes](https://vatan.one/gateway/routes)

## Stored prompts

A prompt kept here and referred to by name, so changing it does not mean a deploy.

Send `prompt: "name"` or `prompt: "name@3"` instead of the messages that would have been in front. A version is immutable once written, so a pinned reference cannot change underneath a running integration; a bare name follows the latest.

```
curl -s https://gateway.vatan.one/v1/chat/completions \
 -H "authorization: Bearer $VATAN_API_KEY" \
 -H "content-type: application/json" \
 -d '{
 "model": "anthropic/claude-sonnet-5",
 "prompt": "summarise@3",
 "messages": [{ "role": "user", "content": "The text to summarise" }]
 }'
```

In the console: [Prompts](https://vatan.one/gateway/prompts)

## Caching

An identical question answered from the last answer, and a near-identical one if you ask for that.

Off unless the workspace turns it on. Exact caching returns a stored answer for a request that matches byte for byte. Semantic caching returns one for a request that is close enough, and the response says how close.

A single request can opt out with `x-vatan-cache: no-store`, which is the escape hatch for the one call that must be fresh.

**REQUEST**A chat request

**WORKSPACE CACHE, OFF UNLESS TURNED ON**

**EXACT**Byte for bytethe same request again

**SEMANTIC**Close enoughthe response says how close

**A MATCH**The stored answernot charged

**NO MATCH**The model answers

**ONE REQUEST OPTS OUT**x-vatan-cache: no-storefor the call that must be fresh

Press enter or space to select a node. You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

In the console: [Caching](https://vatan.one/gateway/caching)

## Attribution

Your own dimensions on the usage row, so spend can be grouped by team, feature or customer.

Send `x-vatan-tags: team=platform,feature=search`. Up to five pairs, 32 characters of key and 64 of value, and the same bounds are a constraint on the column. They appear on the usage screen as a grouping you chose rather than one we did.

Deliberately a header rather than a body field: the body is forwarded to the provider verbatim, and a field we had to strip before forwarding would be a field somebody eventually forgets to strip.

In the console: [Usage](https://vatan.one/gateway/usage)

## A daily limit for each of your users

One key serves all your users, and one of them cannot spend what was meant for the rest.

Send `user` in the body: your own id for the person, as the OpenAI API has it. Letters, digits and `_ . : | -` only, 64 at most. Do not send a name or an email address. One that is not an id is passed to the provider as before and is not metered.

Send `x-vatan-user-daily-limit-usd: 0.50` with it. Once that user has spent the limit today, the request is refused with a 429 whose `error.type` is `user_limit_exhausted`. It carries `spent_usd`, `limit_usd` and `resets_at`. The day is the UTC day.

The limit travels with each request, so a free user and a paid one can have different limits. A request without the header has no per-user limit. A header with no usable `user` is a 400, never a request served unchecked.

It works the same on a workflow, where every model call of the run counts. Requests already running are not counted yet, so a user can end slightly over. `GET /v1/usage/users/{user}` answers what they have spent today.

```
curl -s https://gateway.vatan.one/v1/chat/completions \
 -H "authorization: Bearer $VATAN_API_KEY" \
 -H "content-type: application/json" \
 -H "x-vatan-user-daily-limit-usd: 0.50" \
 -d '{
 "model": "anthropic/claude-sonnet-5",
 "user": "u_18273",
 "messages": [{ "role": "user", "content": "Say hello" }]
 }'

curl -s https://gateway.vatan.one/v1/usage/users/u_18273 \
 -H "authorization: Bearer $VATAN_API_KEY"
```

In the console: [Usage](https://vatan.one/gateway/usage)

## Batches

A list of requests run by us, with no connection held and no loop of your own to get right.

Only a model id ending `:batch` can be batched, at the provider’s own batch price. Any other id is refused when you create the batch.

Send the requests in the body, up to 25 MB, or as a file (below).

A batch runs one model against one endpoint, and bills to the key that created it. A request without `max_tokens` runs under the model’s own maximum output, fitted to the room its prompt leaves.

Every `:batch` id takes text only. A request carrying an image, audio or a file is refused when the batch is created.

The worst case is checked against your balance and budgets, and held until charged. A batch refused for money is never sent.

A stop reads `cancelling` until the provider ends the batch. Only finished requests are charged. Google may still finish, charging in full. OpenRouter cannot stop one.

Subscribe a webhook to `batch.finished` to be told when a batch ends.

| Endpoint | Most per batch |
| /v1/chat/completions | 10,000 requests |

```
curl -s https://gateway.vatan.one/v1/batches \
 -H "authorization: Bearer $VATAN_API_KEY" \
 -H "content-type: application/json" \
 -d '{"model": "openrouter/openai/gpt-5.6-luna:batch", "requests": [
 {"messages": [{"role": "user", "content": "Classify this"}], "max_tokens": 200}
 ]}'
# -> {"id": "3ca5b540-...", "status": "validating", "total": 1}

curl -s https://gateway.vatan.one/v1/batches/$BATCH_ID -H "authorization: Bearer $VATAN_API_KEY"
curl -s "https://gateway.vatan.one/v1/batches?limit=50" -H "authorization: Bearer $VATAN_API_KEY"
curl -s -X POST https://gateway.vatan.one/v1/batches/$BATCH_ID/cancel -H "authorization: Bearer $VATAN_API_KEY"
curl -s https://gateway.vatan.one/v1/batches/$BATCH_ID/items/0/content -H "authorization: Bearer $VATAN_API_KEY" -o item-0.json
```

Watch a batch sent in one request body

67 seconds, silent, with the text on screen.The console screens are examples, not a customer account.

In the console: [Batches](https://vatan.one/gateway/batches)

## Batches from a file

Upload a file of requests, run it as a batch, and download the answers as files.

The OpenAI SDKs work unchanged with this base URL and a Vatan key.

A file is JSONL, one request per line, or one JSON array of requests. Its first character decides, never its name.

A request is the OpenAI wrapper (`custom_id`, `method`, `url`, `body`) or the bare body, whose `custom_id` is its position from 0.

Upload with `POST /files`, then create with `POST /batches` and `input_file_id`. A bad request is refused by `line`, or by `position` in an array, before anything is sent.

When `status` ends, download `output_file_id` and `error_file_id` with `GET /files/{id}/content`. The error file is empty when nothing failed.

Downloads are JSONL, which the SDKs read. `?format=json` gives one JSON array; `?format=jsonl` turns an uploaded array into lines.

`DELETE /files/{id}` removes an input file. Output and error files belong to the batch and stay.

`completion_window` must be "24h". The window shown back is the model’s own, which can be longer.

A file uploaded through the Google door is Gemini-shaped instead: `key` and `request`, with `contents` and `generation_config`. The model is named once, on the job.

A Gemini-shaped line without `max_output_tokens` runs under the model’s own maximum output, fitted to the room its prompt leaves.

A refused upload is discarded whole. Nothing is stored and nothing is charged, so fix the line the refusal names and send the file again.

| Limit | Value |
| One file | Up to 2,000 MB, and 100,000 lines |
| One line | Up to 5 MB |
| One batch | Up to 25 MB of requests, from a file or a list |
| A Google batch from a file | Up to 180 MB and 20,000 requests, one output format per batch |
| /v1/chat/completions | Up to 10,000 requests in one batch |
| Kept for | 30 days, unless you set expires_after to less or delete the file |
| Per workspace | 25 GB and 1,000 files, and 500 uploads an hour |

requests.jsonl, one request per line

```
{"custom_id": "review-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "openrouter/openai/gpt-5.6-luna:batch", "messages": [{"role": "user", "content": "Classify: great product"}], "max_tokens": 200}}
{"model": "openrouter/openai/gpt-5.6-luna:batch", "messages": [{"role": "user", "content": "Classify: arrived broken"}], "max_tokens": 200}
```

requests.json, the same two requests as one array

```
[
 {"custom_id": "review-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "openrouter/openai/gpt-5.6-luna:batch", "messages": [{"role": "user", "content": "Classify: great product"}], "max_tokens": 200}},
 {"model": "openrouter/openai/gpt-5.6-luna:batch", "messages": [{"role": "user", "content": "Classify: arrived broken"}], "max_tokens": 200}
]
```

requests.jsonl, the google-genai shape

```
{"key": "acme", "request": {"system_instruction": {"parts": [{"text": "Extract the company."}]}, "contents": [{"role": "user", "parts": [{"text": "Acme Ltd, 1 High Street, London."}]}], "generation_config": {"max_output_tokens": 2000, "response_mime_type": "application/json", "response_json_schema": {"type": "object", "properties": {"name": {"type": "string"}}, "required": ["name"]}, "thinking_config": {"thinking_level": "LOW"}}}}
```

Python

```
import os, time
from openai import OpenAI

client = OpenAI(base_url="https://gateway.vatan.one/v1", api_key=os.environ["VATAN_API_KEY"])

upload = client.files.create(file=open("requests.jsonl", "rb"), purpose="batch")
batch = client.batches.create(
 input_file_id=upload.id,
 endpoint="/v1/chat/completions",
 completion_window="24h",
)

# status ends on one of these four, for every workspace
while batch.status not in ("completed", "failed", "expired", "cancelled"):
 time.sleep(30)
 batch = client.batches.retrieve(batch.id)

if batch.output_file_id:
 open("output.jsonl", "w").write(client.files.content(batch.output_file_id).text)
if batch.error_file_id:
 open("errors.jsonl", "w").write(client.files.content(batch.error_file_id).text)

client.files.delete(upload.id)
```

TypeScript

```
import fs from 'node:fs'
import OpenAI from 'openai'

const client = new OpenAI({ baseURL: 'https://gateway.vatan.one/v1', apiKey: process.env.VATAN_API_KEY })

const upload = await client.files.create({ file: fs.createReadStream('requests.jsonl'), purpose: 'batch' })
let batch = await client.batches.create({
 input_file_id: upload.id,
 endpoint: '/v1/chat/completions',
 completion_window: '24h',
})

while (!['completed', 'failed', 'expired', 'cancelled'].includes(batch.status)) {
 await new Promise((r) => setTimeout(r, 30_000))
 batch = await client.batches.retrieve(batch.id)
}

if (batch.output_file_id) {
 fs.writeFileSync('output.jsonl', await (await client.files.content(batch.output_file_id)).text())
}
if (batch.error_file_id) {
 fs.writeFileSync('errors.jsonl', await (await client.files.content(batch.error_file_id)).text())
}

await client.files.delete(upload.id)
```

The same, with curl

```
curl -s https://gateway.vatan.one/v1/files -H "authorization: Bearer $VATAN_API_KEY" \
 -F purpose=batch -F file=@requests.jsonl
# -> {"id": "file-7d0c1f7e-...", "object": "file", "lines": 2, "expires_at": ...}

curl -s https://gateway.vatan.one/v1/batches -H "authorization: Bearer $VATAN_API_KEY" \
 -H "content-type: application/json" \
 -d '{"input_file_id": "file-7d0c1f7e-...", "endpoint": "/v1/chat/completions", "completion_window": "24h"}'

curl -s https://gateway.vatan.one/v1/files/$OUTPUT_FILE_ID/content -H "authorization: Bearer $VATAN_API_KEY" -o output.jsonl
curl -s "https://gateway.vatan.one/v1/files/$OUTPUT_FILE_ID/content?format=json" -H "authorization: Bearer $VATAN_API_KEY" -o output.json
curl -s -X DELETE https://gateway.vatan.one/v1/files/file-7d0c1f7e-... -H "authorization: Bearer $VATAN_API_KEY"
```

Watch a batch run from an uploaded file

70 seconds, silent, with the text on screen.The console screens are examples, not a customer account.

In the console: [Batches](https://vatan.one/gateway/batches)

## Batch statuses

What `status` says at each stage, in the words the OpenAI SDKs expect.

`legacy_status` keeps the older word: queued, running, done, failed or cancelled.

| status | What it means |
| validating | Accepted, or being sent. Nothing charged yet. |
| in_progress | With the provider. |
| finalizing | Collecting the answers and the charge. |
| completed | Every request answered or failed. Files ready. |
| failed | Ended as a whole. `errors` says why. |
| expired | Window ran out. Only finished requests are charged. |
| cancelling | Asked to stop, not ended yet. |
| cancelled | Stopped. Finished requests are charged. |

**THE USUAL PATH**

validatingaccepted or being sent; nothing charged yet

in_progresswith the provider

finalizingcollecting the answers and the charge

completedevery request answered or failed; files ready

**OR IT STOPS SHORT**

failedended as a whole; errors says why

expiredwindow ran out; only finished requests charged

cancellingasked to stop, not ended yet

cancelledstopped; finished requests charged

legacy_status keeps the older word: queued, running, done, failed or cancelled.

Press enter or space to select a node. You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

In the console: [Batches](https://vatan.one/gateway/batches)

## Batch refusals

Every refusal creating a batch can answer with, in the words it uses.

A refusal arrives before any work is queued, and nothing is charged.

A refusal about one request names its position, and its `line` in a JSONL file.

| Code | What it means |
| input_missing | Send either a requests array or an input_file_id. |
| input_mixed | Send a requests array or an input_file_id, not both. |
| model_required | model is required with a requests array. A batch runs one model. |
| invalid_request | {param} cannot be "{value}". See the docs for GET /v1/batches. |
| endpoint_not_batchable | "{endpoint}" cannot run as a batch. The batch endpoints are listed in the docs under Limits. |
| endpoint_not_discounted | {model} runs at the batch price only on {endpoints}. Use {base} to run this endpoint at the live price. |
| model_not_batch | {model} cannot be used in a batch. Only model ids ending :batch can. |
| model_not_batchable | {model} cannot run at a batch price. Use {base} to run this batch at the live price. |
| model_mismatch | Request {n} names {line_model}, and this batch runs {model}. A batch runs one model. |
| url_mismatch | Request {n} is for {url}, and this batch runs {endpoint}. A batch runs one endpoint. |
| method_invalid | Request {n} has method {method}. A batch request is always POST. |
| too_many_requests_in_batch | A batch against {endpoint} holds at most {max} requests. This one has {count}. Split it. |
| item_too_large | Request {n} is {size} MB. One request can be at most 5 MB. Send large media as an https link. |
| batch_too_large | This batch is {size} MB, and a list batch can be at most {max} MB. Split it into smaller batches. Or: This request is over 26 MB, and the requests list can be at most 25 MB. Split it into smaller batches. |
| custom_id_invalid | Request {n} has a custom_id Vatan cannot use. Use 1 to 64 letters, digits, underscores, dashes, dots or colons. |
| custom_id_duplicate | custom_id "{id}" appears at requests {a} and {b}. Each custom_id must be unique in a batch. |
| output_bound_required | Request {n} has no max_tokens, and Vatan does not know the most {model} can write. Set max_tokens, so the worst-case cost can be checked first. Or: Request {n} is about {tokens} prompt tokens, which leaves under {floor} tokens of the {window}-token window on {model} for an answer. Shorten it, or set max_tokens. Or: Request {n} sets {field} to something other than a whole number above 0. Set a positive whole number. |
| stream_not_allowed | Request {n} sets stream. A batch cannot stream. Remove it and read the result from the batch. |
| n_not_allowed | Request {n} asks for {k} answers. A batch request returns one. Send the request more than once instead. |
| field_not_allowed | Request {n} sets {field}, which {provider} cannot take in a batch. {reason} Remove it. Or: Request {n} sets a thinking budget of 0, and {model} cannot switch thinking off. Set a budget above 0 or a thinking level, or remove the budget. Or: This batch sets service_tier, which a batch cannot take. The batch price is the tier, and it is chosen by the :batch model id. Remove it. |
| hosted_tool_not_allowed | Request {n} uses {tool}. The provider charges per use, so the cost cannot be checked first. Remove it, or send this request live. |
| provider_reference_not_allowed | Request {n} points at a provider file or cache by id. Those are shared across Vatan's customers. Send the content as base64 or an https link. |
| media_not_supported | Request {n} carries {kind}, and {model} takes text only in a batch. |
| output_format_mixed | Request {n} asks for {format}, and request {first} asks for {first_format}. {model} takes one output format per batch. Send one batch per format. Or: Request {n} has a different JSON schema from request {first}, and the order of its properties counts. {model} takes one schema per batch. Send one batch per schema. |
| too_many_parts | This file would run as {parts} separate batches, and one batch is cut into at most {max}. Each output format and schema runs separately. Use fewer formats, or split the file. |
| reasoning_unbounded | Request {n} does not bound reasoning. On {model}, max_tokens does not limit reasoning. Set reasoning_effort, so the worst case can be checked. |
| prompt_too_long_for_batch | Request {n} is about {tokens} prompt tokens. {model} charges more above {threshold}, so a batch takes at most {limit}. Send it live. |
| completion_window_invalid | completion_window must be "24h". The batch still runs to the model's own window, which is {window}. |
| metadata_invalid | metadata takes up to 16 keys. Keys can be 64 characters and values 512. |
| key_required | keyId is required. A batch runs as one of your keys and bills to it. |
| insufficient_credit | This batch could cost up to {ceiling} and your available balance is {balance}, so it is {short} short and was not created. Nothing was charged. The estimate is a worst case: it assumes every request uses its full output allowance, so the real charge is usually lower. Top up at least {short}, send fewer requests, or set a lower max_tokens. |
| group_budget_exhausted | This batch could cost up to {ceiling} and {team} has {left} left of its budget of {budget}, so it is {over} over and was not created. Nothing was charged. What is left already excludes money set aside for requests still running. An owner, or anyone with Manage people, can raise the team's budget by more than {over}. Or move this key out of the team, or send a smaller batch. |
| budget_exhausted | This batch could cost up to {ceiling} and this key has {left} left of its budget of {budget}, so it is {over} over and was not created. Nothing was charged. What is left already excludes money set aside for requests still running. An owner, or anyone with Manage keys, can raise this key's budget by more than {over}. Or use another key, or send a smaller batch. |
| provider_not_configured | {model} is not available on this deployment right now. Try again later, or send the requests live with {base}. |
| no_such_key | That key does not exist on this account, or it is revoked. |
| no_such_file | No file with that id exists in this workspace. |
| file_not_batch_input | {file} is a batch output file. Create a batch from a file you uploaded with purpose batch. |
| admission_unavailable | Your balance and budgets could not be checked just now, so the batch was not created. Nothing was charged. Try again shortly. |
| file_purpose_invalid | purpose must be "batch". Vatan stores files for batches only. |
| file_expires_after_invalid | expires_after must use anchor "created_at" and between 3600 and 2592000 seconds. |
| file_missing | Send the file as a multipart field named file. |
| file_empty | This file has no requests in it. Nothing was stored. |
| file_too_large | This file is over 2000 MB. Split it into smaller files, one per batch. |
| file_not_jsonl | Line {n} is not a JSON object. Each line must be one request, as JSON. Nothing was stored, so send the whole file again once that line is fixed. |
| file_line_too_large | Line {n} is {size} MB. One line can be at most 5 MB. Nothing was stored, so send the whole file again once that line is fixed. Or: Request {n} is {size} MB. One request can be at most 5 MB. Nothing was stored, so send the whole file again once it is fixed. |
| file_too_many_lines | This file has {count} lines. A file holds at most 100,000 requests. Nothing was stored, so split it and upload again. Or: This file has {count} requests. A file holds at most 100,000 requests. Nothing was stored, so split it and upload again. |
| file_request_not_object | Request {n} is not a JSON object. Each element of the array must be one request. Nothing was stored, so send the whole file again once it is fixed. |
| file_not_json_array | This JSON array ends before its closing ]. Upload the whole file again. Or: This file has more after the closing ] of its JSON array. Remove it and upload again. Or: This JSON array has a comma or bracket out of place at request {n}. Fix it and upload again. |
| file_not_utf8 | This file is not UTF-8 text, from byte {offset}. Save it as UTF-8 and upload it again. |
| file_storage_full | This workspace stores {used} of its 25 GB of files. Delete files you no longer need, then upload again. Or: This workspace has {files} of 1,000 files, the most it can keep. The limit is the number of files, not their size. Delete a file you no longer need to free a slot, then upload again. Or: This workspace has {files} of 1,000 files and stores {used} of its 25 GB, so both limits are reached. Delete files you no longer need, then upload again. |
| file_upload_rate_limited | This workspace has uploaded 500 files in the last hour. Try again after {time}. |
| file_storage_unavailable | File storage is not available right now. Nothing was stored. Send the requests as a list, or try again later. |
| no_such_batch | No batch with that id exists in this workspace. |
| cannot_cancel | This batch will finish and be charged. It is already with {provider}, which offers no way to stop a batch once it has it. Or: This batch is being sent to the provider right now. Try again in a minute, once it has arrived. |
| already_finished | This batch is already {status}, so there is nothing left to stop. |
| results_not_ready | This batch is still {status}. Its results are ready when it finishes. |
| no_such_result | No stored file at position {n} of that batch. Files a batch produces are kept for 7 days after it finishes. |
| file_not_deletable | Output files are part of the batch record, so they cannot be deleted on their own. |
| missing_api_key | Send your API key in the authorization header, as Bearer followed by the key. |
| invalid_api_key | This API key does not exist or was revoked. Use a live key from the console. |
| file_service_unreachable | Files could not be reached just now. Try again shortly. After a failed upload, list your files first, in case it arrived. |

In the console: [Batches](https://vatan.one/gateway/batches)

## Workflows

A workflow you drew in the console, called from your own product with the same key.

Two ways in, both on this host. As a model: send `model: "workflow/<slug>"` to `/chat/completions`. The last user message is the question and the turns before it are the history; a system message is ignored, because what the workflow is told is drawn on its canvas. The answer comes back as a chat completion with two extra fields: `citations`, the documents behind it, and `workflow_run`, its id and what it cost.

As a run: `POST /workflows/{slug-or-id}/runs` with `{"input", "history", "wait"}`. With `wait: true` the response holds until the run finishes, up to the workflow's own time limit, and carries `output`, `citations`, `spentUsd` and the run `id`. Without it you get 202 and the id, and `GET /workflows/runs/{id}` reads it. A run that has not finished when the wait ends also answers 202.

The key that calls is the key that pays. Its IP allowlist, budget and rate limit apply as on any request, and every model call inside the run is metered on it. Runs are listed in Jobs with the key named.

With `stream: true` the chunks follow the chat-completion shape, but the whole answer arrives as one chunk when the run finishes, with a keep-alive comment every fifteen seconds until then. Token-by-token streaming of a workflow is not offered yet.

A run can carry files: voice notes, videos, photos, PDFs or Word files. As a run, add `files`, a list of `{"name", "type", "data"}` with the file in base64 or as a data URL, or `{"url"}` for one Vatan fetches itself. As a model, put `image_url`, `input_audio` or `file` parts in the last user message. Up to 10 files and 25 MB a run. The workflow reads them with its Turn speech into text, Watch a video and Read a document blocks, and each file is deleted when the run ends.

An API call inside a workflow sends its credentials as a header written `{{secrets.NAME}}`. You set the value once in the workflow's settings; it is encrypted, never shown again, and never written into a run's steps, even when the far end echoes it.

```
curl -s https://gateway.vatan.one/v1/workflows/ask-gazar-dev/runs \
 -H "authorization: Bearer $VATAN_API_KEY" \
 -H "content-type: application/json" \
 -d '{"input": "How would you design a URL shortener?", "wait": true}'
# -> {"id": "...", "status": "completed", "output": "...", "citations": [...], "spentUsd": 0.0011}
```

```
import OpenAI from 'openai'

const client = new OpenAI({ baseURL: 'https://gateway.vatan.one/v1', apiKey: process.env.VATAN_API_KEY })

const answer = await client.chat.completions.create({
 model: 'workflow/ask-gazar-dev',
 messages: [{ role: 'user', content: 'How would you design a URL shortener?' }],
})
console.log(answer.choices[0].message.content)
```

**YOUR KEY**The key that calls is the key that paysits IP allowlist, budget and rate limit apply

**AS A MODEL**POST /chat/completionsmodel: "workflow/<slug>"

**AS A RUN**Start a runPOST /workflows/{slug-or-id}/runs

**THE WORKFLOW**Runs as drawn in the console

**BACK AS**A chat completionwith citations and workflow_run

**BACK AS**

wait: trueoutput, citations, spentUsd, id

202 and the idread it with GET /workflows/runs/{id}

Press enter or space to select a node. You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

In the console: [Workflows](https://vatan.one/workflows)

## Workflow guardrails

What a workflow checks on the way in and out.

Set them in the workflow's settings, under Guardrails. The first and last always apply; the rest start off.

| Guardrail | What it does |
| Longest message | A longer message to a widget or channel is refused before any step runs. |
| Override check | A decisions model judges each message first. If sure enough, the refusal is sent. |
| Secrets and keys | Secret values and key-shaped text are removed. Quoting its own instructions is refused. |
| Allowed links | Links to other sites are removed, or the answer refused. |
| Longest answer | A longer answer is cut at a word. |
| Garbled answers | A broken or looping answer is refused. |
| Value cap | Each value sent to an API or tool is cut short. |
| Mail headers | Visitor text never fills a from, to or subject. |

**IN**A message arrives

**ON THE WAY IN**

Longest message*ALWAYS*

Override check

**IF IT PASSES**The workflow's steps

**WHAT STEPS SEND ONWARD**

Value cap

Mail headers*ALWAYS*

**ON THE WAY OUT**

Secrets and keys

Allowed links

Longest answer

Garbled answers

Longest message and Mail headers always apply. The rest start off; set them under Guardrails in the workflow's settings.

Press enter or space to select a node. You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

In the console: [Workflows](https://vatan.one/agents/workflows)

## Errors

The shape, and what each status actually means here.

A refusal is JSON with an `error` object carrying a `message` and a `type`, which is the shape an OpenAI client already handles. Every refusal is metered and appears on your usage screen: a wholly broken integration should not look like an idle one.

| Status | What it means here |
| 400 | The request. A model that does not exist, a route with nothing servable on it, a body the endpoint will not take. The message names the field. |
| 400 auto | auto_chat_only: auto sent to a non-chat endpoint. auto_unservable: no model Auto may choose can serve this request. |
| 401 | The key. Missing, invalid, revoked or expired. Type authentication_error. |
| 402 | The money. The balance is spent, or a key or team budget is. Carried out unchanged from the check that raised it. |
| 404 | The thing named in the path does not exist for this workspace. |
| 429 | A rate limit, yours or the provider's. Type rate_limit_error. |
| 502 / 503 | The provider, or a model this deployment holds no credential for. |
| 504 | The provider took too long and the request was given up on. |

In the console: [Requests](https://vatan.one/gateway/requests)

## What it costs

How a price is arrived at, and what stops a runaway loop.

A request is charged per token at the catalogue rate for that model.

Three things bound spend, and they are checked before a request is forwarded: the workspace balance, the key budget, and the team budget. Any of them refuses with 402 and the rest of the workspace carries on.

A request

**CHECKED BEFORE IT IS FORWARDED**

**WORKSPACE**Balance

**KEY**Budget

**TEAM**Budget

**ALL THREE PASS**Forwarded to the provider

**402, ANY ONE SPENT**Refusedthe rest of the workspace carries on

**CHARGED PER TOKEN**At the catalogue rate for the model

Press enter or space to select a node. You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

In the console: [Usage and spend](https://vatan.one/gateway/usage)

## Webhooks

Told rather than polled, for the handful of things worth being told about.

A workspace registers an address and the events it wants. Deliveries are signed and every attempt is recorded, so a failing endpoint is visible rather than silent.

Conversation events carry ids, and message text only when the hook asks for it.

Watch the webhooks demo

78 seconds, silent, with the text on screen.The console screens are examples, not a customer account.

In the console: [Webhooks](https://vatan.one/admin/webhooks)

## Channels

Your own bot on Telegram, Bale, Slack, Microsoft Teams, WhatsApp, Instagram or Messenger, answered by a workflow or an agent. Switched on per account.

A channel connects a bot you own to your workspace. A workflow or agent you pick answers each message.

By default it answers members only. Each links their account with a one-time code and picks the key their questions bill to.

A Telegram, Bale, WhatsApp, Instagram or Messenger channel can answer anyone instead, billed to one key you choose. Slack and Teams answer members only.

A public bot has a daily spend cap, $0.01 to $1,000, and a daily limit per person, 30 by default. Past either, the sender is told once.

Messages over 4,096 characters are refused. Only a public Telegram bot answers in groups, with a daily cap per group.

On WhatsApp, Instagram and Messenger, Meta allows a reply only within 24 hours of the person's last message. Later messages are not answered.

There is no channel fee, seat or subscription: you pay for the model tokens each reply uses.

Meta's own prices apply to your Meta account. Meta charges for each WhatsApp reply it delivers, and a long answer may be several messages.

Instagram and Messenger reach people outside your team only after Meta's App Review.

| App | What you bring |
| Telegram | A bot token from @BotFather. |
| Bale | A bot token from Bale's @botfather. |
| Slack | A bot token and signing secret. Paste Vatan's address as the Request URL. |
| Microsoft Teams | An Azure Bot's app ID and password. Paste Vatan's address as its Messaging endpoint. |
| WhatsApp | Your own Meta app and a dedicated number, in a verified business with a payment method: an access token, phone number ID and app secret. |
| Instagram | Your own Meta app and a professional account: a Unified login token, the account ID and the app secret. |
| Messenger | Your own Meta app and a Facebook Page: a Page access token, the Page ID and the app secret. |

In the console: [Channels](https://vatan.one/admin/channels)

## Vatan MCP

Let a coding assistant work in your workspace through three tools. You sign in once in the browser.

Vatan MCP is a remote MCP server at https://mcp.vatan.one/mcp. It works with Claude Code, Codex, Cursor and Claude.ai connectors.

To connect, add the server. Your client opens the browser. Sign in to Vatan, or create an account there. Pick what to allow, and you are done. There is no key to copy.

It has three tools. `search` finds operations in the whole Vatan API and says which permission each one needs. `execute` runs a short JavaScript snippet in a sandbox against a `vatan` client: vatan.get, vatan.post, vatan.put, vatan.patch, vatan.delete and vatan.request. `access` says what your key may do.

You choose scopes when you allow the app: read, write, spend and destructive. Read and write are the default. Spend and destructive are opt-in.

The app acts as you. Each call uses your permissions today, cut down to the scopes you allowed. Remove your access and the app loses it too.

Destructive and spend calls need `confirm: true`. Pass `dryRun` to list what would be called without calling it.

Limits per run: about 20 seconds and 50 API calls.

It can never make another key of equal power, sign in, change passwords or sessions, change a payment method, top up, delete the account, or reach operator routes. Those stay in the console.

MCP calls are free. Anything that reaches the model gateway is billed as normal.

Access renews itself for 30 days. Sign in again after 30 days unused, after disconnecting, or for another workspace.

To stop an app, open MCP keys in the console and disconnect it under Connected apps. It stops at once.

One risk is left. A client that holds your access and a web tool can be talked into sending workspace data to a page it read. Use read-only scope for untrusted contexts.

For scripts and CI, where no browser is there, make a key instead. You need the keys.manage permission. Copy the secret at once: it is shown one time. It starts with vmcp_. Send it as an Authorization Bearer header. A key has the same scopes and the same limits as a connected app.

Claude Code

```
claude mcp add --transport http vatan https://mcp.vatan.one/mcp
```

Codex

```
codex mcp add vatan --url https://mcp.vatan.one/mcp
```

Cursor (mcp.json) and Claude.ai (Settings, Connectors, Add custom connector)

```
{ "mcpServers": { "vatan": { "url": "https://mcp.vatan.one/mcp" } } }
```

Scripts and CI: a key in a header

```
claude mcp add --transport http vatan https://mcp.vatan.one/mcp \
 --header "Authorization: Bearer vmcp_..."
```

Worked example: list keys, then 7-day usage by key, in one execute

```
const keys = await vatan.get('/v1/keys')
const usage = await vatan.get('/v1/usage/by/key?days=7')
return keys.data.map((k) => ({
 name: k.name,
 prefix: k.prefix,
 usage: usage.data.find((u) => u.name === k.name) ?? null,
}))
```

In the console: [MCP keys](https://vatan.one/gateway/mcp-keys)

## What an API key cannot do

The line between spending and administering, and why it is drawn where it is.

A gateway key reaches inference and the batch queue. It cannot read or change keys, people, budgets, billing or the workspace, because every key in existence is a gateway key: the day that boundary bends, thousands of spending credentials become administrative ones.

Administration is done by a person in the console, or with a management key, which is a separate credential with its own explicit list of what it may reach.

In the console: [People and permissions](https://vatan.one/people)

Source: https://vatan.one/docs
