> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verlon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Gates

> Route AI requests through configurable gates with intelligent model selection, fallbacks, and cost controls

## What is a Gate?

A gate is the core building block of Verlon AI. It's a configuration that sits between your application and AI providers, controlling how requests are routed, which models are used, and how failures are handled.

When you make a request through Verlon, you reference a gate by its ID (a UUID). The gate determines:

* Which model handles the request
* What happens if that model fails
* What parameters are applied (temperature, max tokens, etc.)
* Whether spending limits are enforced
* What system prompt is prepended

## Gate Types

Verlon supports two gate types:

| Type | Use Case |
| - | - |
| **Standard** | Discrete, stateless LLM calls — chat, image generation, embeddings, etc. |
| **Agent** | The identity of one agent: run traces (LLM calls, tools, sub-agents on one timeline) and per-call-site model control via tasks. See [Agent Gates](https://docs.verlon.ai/platform/agent-gates.md). |

## Task Types

Every gate is configured for a specific task type, which determines which models are available:

| Task Type | Description | Example Models |
| - | - | - |
| `chat` | Text generation, conversation | GPT-4o, Claude Sonnet, Gemini |
| `image` | Image generation | DALL-E, Stable Diffusion |
| `video` | Video generation | Runway, Pika |
| `tts` | Text-to-speech | OpenAI TTS, ElevenLabs |
| `embeddings` | Text embeddings | text-embedding-3, Ada |
| `ocr` | Document processing | OpenAI Vision, Claude Vision |

Chat gates also support optional subtypes for specialized models:

* **Reasoning** — o3, o4-mini, Gemini 2.5 Pro
* **Code** — Codestral, Devstral
* **Realtime** — gpt-4o-realtime

## Routing Strategies

Gates support three strategies for handling requests:

### Single (Default)

Use only the primary model. No fallbacks. Simplest and most predictable.

### Fallback

Try the primary model first. If it fails (provider outage, rate limit, etc.), try each fallback model in order until one succeeds.

```
Primary: claude-sonnet-4 → fails
Fallback 1: gpt-4o → fails
Fallback 2: gemini-2.0-flash → succeeds ✓
```

### Round-Robin

Randomly distribute requests across the primary model and all fallback models. Useful for load balancing or informal cost distribution across providers.

## Creating a Gate

### From the Dashboard

1. Go to **Dashboard → Gates → Create New Gate**
2. Fill in the required fields:
   * **Name** — A human-readable label for the gate (e.g., `customer-support`). The gate ID (UUID) is what you use in API calls.
   * **Task Type** — What kind of requests this gate handles
   * **Model** — The primary model to use
3. Optionally configure:
   * **Fallback models** and routing strategy
   * **System prompt** applied to all requests
   * **Temperature**, **max tokens**, and **top P** defaults
   * **Spending limits** with alert or block enforcement
   * **Structured output** (JSON schema) for consistent response formats

### Via the API

```bash theme={null}
curl -X POST https://api.verlon.ai/v1/gates \
  -H "Authorization: Bearer sk-vrln-your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer-support",
    "taskType": "chat",
    "model": "claude-sonnet-4-20250514",
    "description": "Handles customer support queries",
    "fallbackModels": ["gpt-4o"],
    "routingStrategy": "fallback",
    "temperature": 0.7,
    "systemPrompt": "You are a helpful customer support agent."
  }'
```

## Using a Gate

Once created, reference the gate in your requests:

> [tab] OpenAI SDK
>
> ```typescript theme={null}
> import OpenAI from 'openai';
>
> const openai = new OpenAI({
>   baseURL: 'https://api.verlon.ai/v1',
>   apiKey: process.env.VERLON_API_KEY
> });
>
> const response = await openai.chat.completions.create({
>   model: 'your-gate-uuid', // gate UUID in the model slot
>   messages: [
>     { role: 'user', content: 'How do I reset my password?' }
>   ]
> });
> ```

> [tab] OpenAI SDK (default header)
>
> ```typescript theme={null}
> import OpenAI from 'openai';
>
> const openai = new OpenAI({
>   baseURL: 'https://api.verlon.ai/v1',
>   apiKey: process.env.VERLON_API_KEY,
>   defaultHeaders: {
>     'X-Verlon-Gate-Id': 'your-gate-uuid'
>   }
> });
>
> const response = await openai.chat.completions.create({
>   model: 'claude-sonnet-4-20250514',
>   messages: [
>     { role: 'user', content: 'How do I reset my password?' }
>   ]
> });
> ```

> [tab] cURL
>
> ```bash theme={null}
> curl -X POST https://api.verlon.ai/v3/chat \
>   -H "Authorization: Bearer sk-vrln-your_key" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "gateId": "your-gate-uuid",
>     "data": {
>       "messages": [
>         { "role": "user", "content": "How do I reset my password?" }
>       ]
>     }
>   }'
> ```

## Gate Configuration Reference

The full gate configuration interface. Fields marked **required** must be provided when creating a gate. All other fields are optional.

### Core Fields

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | `string` | Yes | Human-readable label for the gate (e.g., `customer-support`). Must be unique per user. Used for display in the dashboard and logs. |
| `model` | `SupportedModel` | Yes | Primary model to use for requests (e.g., `claude-sonnet-4-20250514`, `gpt-4o`). |
| `taskType` | `ModelType` | Yes | Determines which models are available. One of: `chat`, `image`, `video`, `tts`, `embeddings`, `ocr`, `audio`, `stt`, `moderation`. |
| `taskSubtype` | `ModelSubtype` | No | Specialization for chat models. One of: `reasoning`, `code`, `realtime`. |
| `description` | `string` | No | Describes what this gate is for. Used by the Architect for smart routing recommendations. The dashboard offers an **Auto-enhance description** option — if you accept the Architect's suggestion, the enhanced version replaces this field. |
| `tags` | `string[]` | No | Organizational labels for filtering and grouping gates. |

### Model Routing

| Field | Type | Default | Description |
| - | - | - | - |
| `routingStrategy` | `'single' \| 'fallback' \| 'round-robin'` | `'single'` | How requests are distributed across models. |
| `fallbackModels` | `SupportedModel[]` | `[]` | Ordered list of fallback models. Used by `fallback` and `round-robin` strategies. |

### Request Parameters

Defaults applied to all requests through the gate. Can be overridden per-request if `allowOverrides` is configured.

| Field | Type | Default | Description |
| - | - | - | - |
| `systemPrompt` | `string` | — | System prompt prepended to all requests. |
| `temperature` | `number` | — | Controls randomness (0 = deterministic, 2 = most random). |
| `maxTokens` | `number` | — | Maximum response length in tokens. |
| `topP` | `number` | — | Nucleus sampling threshold (0 - 1). Lower = more focused. |
| `allowOverrides` | `boolean \| OverrideConfig` | `false` | Whether clients can override gate defaults per-request. Can be `true` (all overrides) or an object specifying which fields: `{ model?: boolean, temperature?: boolean, maxTokens?: boolean, topP?: boolean }`. |

### Smart Routing (Architect)

Verlon's AI agent (the Architect) analyzes your gate's description and usage patterns to recommend optimal models.

| Field | Type | Default | Description |
| - | - | - | - |
| `costWeight` | `number` | — | Weight for cost optimization (0 - 1). |
| `latencyWeight` | `number` | — | Weight for latency optimization (0 - 1). |
| `qualityWeight` | `number` | — | Weight for quality optimization (0 - 1). |
| `analysisMethod` | `'cost' \| 'balanced' \| 'performance' \| 'custom'` | — | Preset optimization profile. `custom` uses the individual weights above. |
| `maxCostPer1kTokens` | `number` | — | Maximum acceptable cost per 1,000 tokens (USD). |
| `maxLatencyMs` | `number` | — | Maximum acceptable latency in milliseconds. |
| `reanalysisPeriod` | `'daily' \| 'weekly' \| 'monthly' \| 'never'` | `'never'` | How often the Architect re-evaluates model recommendations. |
| `autoApplyRecommendations` | `boolean` | `false` | Automatically apply Architect recommendations without manual review. |
| `taskAnalysis` | `TaskAnalysis` | — | Read-only. The Architect's current recommendation including primary model, alternatives, and reasoning. |

### Structured Output

Force responses into a consistent format. Native JSON schema support for OpenAI models; prompt-injected for other providers.

| Field | Type | Default | Description |
| - | - | - | - |
| `responseFormatEnabled` | `boolean` | `false` | Enable structured output. |
| `responseFormatType` | `'text' \| 'json_object' \| 'json_schema'` | `'text'` | Output format. `json_object` guarantees valid JSON. `json_schema` validates against a strict schema. |
| `responseFormatSchema` | `object` | — | JSON schema for `json_schema` mode. Defines the exact structure of responses. |

### Spending Limits

Control costs at the gate level. See [Spending](https://docs.verlon.ai/platform/spending.md) for account-level controls.

| Field | Type | Default | Description |
| - | - | - | - |
| `spendingLimit` | `number \| null` | `null` | Dollar cap per period. `null` = no limit. |
| `spendingLimitPeriod` | `'monthly' \| 'daily'` | `'monthly'` | How often the spending counter resets. |
| `spendingEnforcement` | `'alert_only' \| 'block'` | `'alert_only'` | `alert_only` warns but allows requests. `block` rejects requests when the limit is hit. |

> [!NOTE]
>
> Agent gates are created with identity only (name + description) — their control surface is per-task model config. See [Agent Gates](https://docs.verlon.ai/platform/agent-gates.md).

### Read-Only Fields

These fields are returned by the API but cannot be set directly.

| Field | Type | Description |
| - | - | - |
| `id` | `string` | Gate UUID. This is what you use in API calls. |
| `userId` | `string` | Owner's user ID. |
| `createdAt` | `Date` | When the gate was created. |
| `updatedAt` | `Date` | When the gate was last modified. |
| `spendingCurrent` | `number` | Current period spending (USD). |
| `spendingPeriodStart` | `string` | Start of the current spending period. |
| `spendingStatus` | `'active' \| 'suspended'` | Whether the gate is active or suspended due to spending limit. |

## Dashboard Tabs

When editing a gate in the dashboard, configuration is organized into tabs:

### Basic Info

Name, description, task type, subtypes, and tags. Includes an **Auto-enhance description** toggle — when enabled, the Architect generates an improved version of your description optimized for smart routing analysis. If you accept the suggestion, it replaces your gate's `description` field with the enhanced version.

### Models & Routing

Primary model, fallback models, routing strategy, optimization weights, and smart routing (Architect) configuration.

### Request Config

System prompt, temperature, max tokens, top P, and override permissions.

### Spending Limits

Gate-level spending cap, period, and enforcement type.

### Connections

Shows which agent gates delegate a task to this gate. When an agent gate's task is bound to this gate, calls through that task inherit this gate's model, parameters, and instructions.

This is read-only context — delegation is managed from the agent gate's Tasks tab. See [Agent Gates](https://docs.verlon.ai/platform/agent-gates.md).

### Danger Zone

Delete the gate. This action is irreversible. Agent-gate tasks that delegated to this gate fall back to pass-through.

## Gate Limits

The number of gates you can create depends on your plan tier. Check your current usage at **Dashboard → Settings**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.