Gateway

Gateway is the proxy integration path. Your application keeps using its provider SDK, but changes the base URL and API key so requests pass through Featherlane AI first.

What you configure

Routes do not have a separate rule set. Every policy enabled for the selected environment and route agent applies automatically, using the same event service as POST /v1/events.

Set up a route

1. Open Gateway → Providers and connect an OpenAI-compatible or Anthropic provider.
2. Create or select the agent whose traffic the route represents.
3. Open Gateway → Routes and create a route using that provider and agent.
4. Create a runtime key under API Keys.
5. Copy the route-specific example shown below the Routes table.

For DigitalOcean inference, create an OpenAI-compatible provider with:

Base URL: https://inference.do-ai.run
Default model: deepseek-4-flash

Store the DigitalOcean model-access key as the provider secret. Applications call Featherlane AI with the Featherlane AI runtime key; the provider credential remains server-side.

OpenAI-compatible client

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: process.env.FEATHERLANE_AI_API_KEY,
  baseURL: 'https://<server>/v1/gateway/<route_id>/openai',
});

const response = await openai.chat.completions.create({
  model: 'deepseek-4-flash',
  messages: [{ role: 'user', content: userMessage }],
  max_tokens: 512,
});

The corresponding raw endpoint is:

POST /v1/gateway/<route_id>/openai/chat/completions
Authorization: Bearer <tl_live_...>

Anthropic client

import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({
  authToken: process.env.FEATHERLANE_AI_API_KEY,
  baseURL: 'https://<server>/v1/gateway/<route_id>/anthropic',
});

const response = await anthropic.messages.create({
  model: 'claude-3-5-sonnet-latest',
  max_tokens: 512,
  messages: [{ role: 'user', content: userMessage }],
});

Use authToken, not the provider's apiKey option: Gateway runtime calls authenticate with a Featherlane AI bearer key.

How policies apply

Gateway creates an input event before the provider call and an output event after it. Both go through the same execute_event_submission service as direct event submissions.

A rewrite without safe replacement text fails closed. Gateway does not issue an extra model call to regenerate output.

Non-permitted responses use the provider's content-filter response shape and include X-Featherlane AI-Effect, X-Featherlane AI-Phase, X-Featherlane AI-Trace-Id, and—when available—X-Featherlane AI-Policy-Id.

Streaming

Set stream: true normally. No route toggle is required. Gateway buffers the full upstream result, checks it, then emits guarded provider-native SSE. Tokens are not forwarded before the output policy decision is complete.

Spend controls

OpenAI-compatible calls support per-principal budgets. Create a financial policy with meter: llm_usage and configure the exact model's input/output price. Calls with a positive max_tokens or max_completion_tokens value atomically reserve their maximum cost before the provider call, then settle to actual reported usage. If that maximum would exceed the remaining daily, weekly, or monthly budget, Gateway returns HTTP 429 without contacting the provider. Calls without either bound are soft-admitted below the cap and settled afterward; one unbounded request can overshoot before later calls are stopped. Unknown pricing returns 503 before provider spend.

Configure these controls from Usage & budgets in the dashboard:

1. Add the model's exact input and output USD-per-million-token prices.
2. Create an LLM spending cap. This writes a normal unified financial policy with meter: llm_usage.
3. Add a percent alert such as 80%. Alerts are meter-scoped, so an action-spend alert cannot fire from model usage.

See Set AI Usage Cost Caps for the complete dashboard setup, per-principal behavior, and a safe hard-stop test.

Each Gateway request appears under Runs with the exact checked user and assistant turns, provider response id, model, token usage, latency, estimated cost, deterministic budget snapshot, and separate Featherlane AI guardrail overhead. Estimated costs use the price snapshot recorded with the request; reconcile invoices in the provider dashboard.

Troubleshooting

• 401 Unauthorized — the Authorization header is missing or the Featherlane AI runtime key is invalid. A provider key cannot authenticate the Gateway route.
• 404 gateway route not found — the route id in the URL does not match a route in the runtime key's workspace.
• 400 provider kind mismatch — use the /openai address for OpenAI-compatible providers and the /anthropic address for Anthropic providers.
• 429 budget_exceeded — a bounded request's reserved maximum is larger than the remaining budget, or an unbounded request arrived after the cap was reached.
• 503 pricing_unavailable — add a trusted workspace price for the exact model before using a hard LLM budget.
• 502 Bad Gateway — the upstream provider failed, timed out, or returned malformed JSON. This is not reported as a policy block.