zuplo 7.1.0 → 7.1.2

package/docs/ai-gateway/integrations/claude-code.mdx

@@ -1,6 +1,9 @@
 ---
 title: Claude Code
 sidebar_label: Claude Code
+description:
+  Point Claude Code at an AI Gateway app so every Claude Code request is
+  authenticated, metered, and routed by the gateway.
 ---
 
 The Zuplo AI Gateway supports the [Anthropic](https://docs.claude.com/en/home)
@@ -12,17 +15,17 @@ the AI Gateway.
 
 <Stepper>
 
-1. Create a [new provider](/ai-gateway/managing-providers) in the AI Gateway for
+1. Create a [new provider](../managing-providers.mdx) in the AI Gateway for
    Anthropic
 
-2. [Set up a new team](/ai-gateway/managing-teams)
+2. [Set up a new team](../managing-teams.mdx)
 
-3. Create a [new app](/ai-gateway/managing-apps) to use with Claude Code and
-   assign it to the team you created
+3. Create a [new app](../managing-apps.mdx) to use with Claude Code and assign
+   it to the team you created
 
-4. Copy the API Key for the app you created, as well as the Gateway URL
+4. Copy the **API URL** and **API Key** shown at the top of the app page
 
-5. Add the API key and Gateway URL to your environment, or Claude Code settings,
+5. Add the API key and gateway URL to your environment, or Claude Code settings,
    using either approach below
 
 </Stepper>
@@ -31,7 +34,7 @@ the AI Gateway.
 
 ```
 ANTHROPIC_AUTH_TOKEN=<your-ai-gateway-app-api-key>
-ANTHROPIC_BASE_URL=<your-ai-gateway-url>
+ANTHROPIC_BASE_URL=https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e
 ```
 
 ### Using settings.json
@@ -40,10 +43,31 @@ ANTHROPIC_BASE_URL=<your-ai-gateway-url>
 {
   "env": {
     "ANTHROPIC_AUTH_TOKEN": "<your-ai-gateway-app-api-key>",
-    "ANTHROPIC_BASE_URL": "<your-ai-gateway-url>"
+    "ANTHROPIC_BASE_URL": "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e"
   }
 }
 ```
 
+:::note
+
+Claude Code appends `/v1/messages` to the base URL itself, so
+`ANTHROPIC_BASE_URL` is the app's URL _without_ the `/v1` suffix.
+
+:::
+
 Restart Claude and it will switch to using your new AI Gateway configuration and
 all your Claude Code LLM requests will route through the AI Gateway.
+
+### Choosing a model
+
+The gateway routes models named as `providerName/model`, where `providerName` is
+the provider name configured in your gateway. Claude Code's default model names
+don't carry that prefix, so set the model explicitly:
+
+```
+ANTHROPIC_MODEL=anthropic/claude-sonnet-4-5-20250929
+ANTHROPIC_SMALL_FAST_MODEL=anthropic/claude-haiku-4-5
+```
+
+The app's [Model Filtering](../policies/model-filtering.mdx) policy controls
+which models the app may use.

package/docs/ai-gateway/integrations/codex.mdx

@@ -1,6 +1,9 @@
 ---
 title: Codex
 sidebar_label: Codex
+description:
+  Configure the Codex CLI to send its requests through an AI Gateway app, either
+  by rerouting the built-in OpenAI provider or by adding a Zuplo provider.
 ---
 
 [Codex](https://developers.openai.com/codex) is a coding agent developed by
@@ -15,15 +18,15 @@ first:
 
 <Stepper>
 
-1. Create a [new provider](/ai-gateway/managing-providers) in the AI Gateway for
-   the provider you want to use with Codex
+1. Create a [new provider](../managing-providers.mdx) in the AI Gateway for the
+   provider you want to use with Codex
 
-2. [Set up a new team](/ai-gateway/managing-teams)
+2. [Set up a new team](../managing-teams.mdx)
 
-3. Create a [new app](/ai-gateway/managing-apps) to use specifically with Codex
-   and assign it to the team you created
+3. Create a [new app](../managing-apps.mdx) to use specifically with Codex and
+   assign it to the team you created
 
-4. Copy the API Key for the app you created, as well as the Gateway URL
+4. Copy the **API URL** and **API Key** shown at the top of the app page
 
 </Stepper>
 
@@ -45,13 +48,14 @@ Configuration steps for both options are below:
 
 Open the [Codex configuration](https://developers.openai.com/codex/local-config)
 `~/.codex/config.toml` and modify the `model_providers.openai-chat-completions`
-entry so that the `base_url` points to your AI Gateway URL, and your `env_key`
-is set to the API Key of the app you created to use with Codex.
+entry so that the `base_url` points to your app's API URL with `/v1` appended,
+and set your `env_key` to the API Key of the app you created to use with Codex.
+The app page in the Zuplo Portal shows the API URL, which ends in the app's ID.
 
 ```toml
 [model_providers.openai-chat-completions]
 name = "OpenAI using Chat Completions"
-base_url = "https://<your-ai-gateway-url>/v1"
+base_url = "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1"
 env_key = "ZUPLO_AI_GATEWAY_API_KEY"
 ```
 
@@ -66,7 +70,7 @@ the Codex `config.toml` file.
 ```toml
 [model_providers.zuplo]
 name = "Zuplo AI Gateway"
-base_url = "https://<your-ai-gateway-url>/v1"
+base_url = "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1"
 env_key = "ZUPLO_AI_GATEWAY_API_KEY"
 ```
 
@@ -76,3 +80,17 @@ available and you can switch Codex over to use it at any time by running:
 ```bash
 codex --config model_provider="zuplo"
 ```
+
+### Choosing a model
+
+The app's [Model Filtering](../policies/model-filtering.mdx) policy controls
+which models the app may use. Codex names the model as `providerName/model`,
+where `providerName` is the provider name configured in your gateway:
+
+```bash
+codex --config model_provider="zuplo" --model "openai/gpt-5"
+```
+
+A request with no model, or a model without that prefix, gets a `400`. Adding
+[Model Filtering](../policies/model-filtering.mdx) with an allow list also
+supplies a default, letting requests omit the model.

package/docs/ai-gateway/integrations/goose.mdx

@@ -1,6 +1,9 @@
 ---
 title: goose
 sidebar_label: Goose
+description:
+  Add your AI Gateway app as an OpenAI-compatible provider in the goose CLI or
+  desktop app so goose's requests route through the gateway.
 ---
 
 [goose](https://block.github.io/goose/) is a local AI agent and CLI tool for
@@ -16,15 +19,15 @@ first:
 
 <Stepper>
 
-1. Create a [new provider](/ai-gateway/managing-providers) in the AI Gateway for
-   the provider you want to use with goose
+1. Create a [new provider](../managing-providers.mdx) in the AI Gateway for the
+   provider you want to use with goose
 
-2. [Set up a new team](/ai-gateway/managing-teams)
+2. [Set up a new team](../managing-teams.mdx)
 
-3. Create a [new app](/ai-gateway/managing-apps) to use specifically with goose
-   and assign it to the team you created
+3. Create a [new app](../managing-apps.mdx) to use specifically with goose and
+   assign it to the team you created
 
-4. Copy the API Key for the app you created, as well as the Gateway URL
+4. Copy the **API URL** and **API Key** shown at the top of the app page
 
 </Stepper>
 
@@ -47,20 +50,24 @@ configuration approaches depending on which version you choose.
 4. Set the `OPENAI_API_KEY` to the API Key for the app you created for goose in
    Zuplo
 
-5. Set the `OPENAI_HOST` to the URL of your AI Gateway using the Gateway URL
-   from your project
+5. Set the `OPENAI_HOST` to your app's gateway URL _without_ the `/v1` suffix
+   (for example
+   `https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e`)—the
+   base path in the next step supplies it
 
 6. The `OPENAI_BASE_PATH` may already be configured. If it's not, enter
    `v1/chat/completions` as the value
 
-7. Enter the model you want to use with goose.
+7. Enter the model you want to use with goose, as `providerName/model`—for
+   example `openai/gpt-5-mini`.
 
 </Stepper>
 
 :::note
 
-The provider model you want to use with goose must be selected in the provider
-you created in the Prerequisites step above
+The app's [Model Filtering](../policies/model-filtering.mdx) policy controls
+which models the app may use, so the model you enter here must be one that
+policy allows.
 
 :::
 
@@ -70,12 +77,12 @@ the AI Gateway.
 
 ### Desktop App
 
-If you are using the goose desktop application you can add a Custom Provider for
-AI Gateway by following these steps:
+If you are using the goose desktop app you can add a Custom Provider for AI
+Gateway by following these steps:
 
 <Stepper>
 
-1. Open the goose desktop application
+1. Open the goose desktop app
 
 2. Click on **Settings**
 
@@ -88,17 +95,17 @@ AI Gateway by following these steps:
 
 6. Enter a **Display Name** (for example Zuplo AI Gateway)
 
-7. Set the **API URL** to the URL of your Zuplo AI Gateway
+7. Set the **API URL** to your app's gateway URL
 
 8. Set the **API Key** to the API key of the app you created for goose in Zuplo
 
-9. Set the list of **Available Models** to the same list you selected when you
-   set up the provider in the Prerequisites step (for example gpt-4o, gpt-5,
-   gpt-5-nano)
+9. Set the list of **Available Models** to the models the app's Model Filtering
+   policy allows, named as `providerName/model` (for example
+   `openai/gpt-5-mini`, `openai/gpt-5`, `openai/gpt-5-nano`)
 
 10. Click on **Create Provider**
 
 </Stepper>
 
 The Zuplo AI Gateway and associated provider and models will now be available to
-use with the goose desktop application.
+use with the goose desktop app.

package/docs/ai-gateway/integrations/langchain.mdx

@@ -1,6 +1,9 @@
 ---
 title: LangChain
 sidebar_label: LangChain SDK
+description:
+  Point LangChain's ChatOpenAI integration at your AI Gateway app's URL so every
+  LangChain call is routed and metered by the gateway.
 ---
 
 LangChain is a framework for developing applications that are powered by Large
@@ -10,20 +13,20 @@ integrates with hundreds of providers.
 
 ## Prerequisites
 
-In order to use the AI Gateway with any LangChain powered application you will
-need to complete these steps first:
+In order to use the AI Gateway with any LangChain powered app you will need to
+complete these steps first:
 
 <Stepper>
 
-1. Create a [new provider](/ai-gateway/managing-providers) in the AI Gateway for
-   the provider you want to use with LangChain
+1. Create a [new provider](../managing-providers.mdx) in the AI Gateway for the
+   provider you want to use with LangChain
 
-2. [Set up a new team](/ai-gateway/managing-teams)
+2. [Set up a new team](../managing-teams.mdx)
 
-3. Create a [new app](/ai-gateway/managing-apps) to use specifically with
-   LangChain and assign it to the team you created
+3. Create a [new app](../managing-apps.mdx) to use specifically with LangChain
+   and assign it to the team you created
 
-4. Copy the API Key for the app you created, as well as the Gateway URL
+4. Copy the **API URL** and **API Key** shown at the top of the app page
 
 </Stepper>
 
@@ -46,21 +49,34 @@ def init_chat_model():
         print("❌ Error: Please set your ZUPLO_AI_GATEWAY_API_KEY in a .env file")
         exit(1)
 
-    # Check for custom BASE_URL - this is the AI Gateway URL from Zuplo
+    # Check for custom BASE_URL - this is the app's gateway URL from Zuplo
     base_url = os.getenv("BASE_URL")
 
-    if base_url:
-        return ChatOpenAI(api_key=api_key, model="gpt-4o", base_url=base_url)
-    else:
-        return ChatOpenAI(api_key=api_key, model="gpt-4o")
+    if not base_url:
+        print("❌ Error: Please set BASE_URL to your app's gateway URL")
+        exit(1)
+
+    return ChatOpenAI(
+        api_key=api_key, model="openai/gpt-5-mini", base_url=base_url
+    )
 ```
 
 In the code above, checks are performed for two environment variables:
 
 - `ZUPLO_AI_GATEWAY_API_KEY` - This is the API key of the app you have
   configured to use with LangChain in Zuplo
-- `BASE_URL` - This is the Gateway URL of your AI Gateway project in Zuplo
+- `BASE_URL` - This is your app's API URL with `/v1` appended, for example
+  `https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1`.
+  The app page in the Zuplo Portal shows the API URL, which ends in the app's ID
 
 Both of these values are passed to `ChatOpenAI` when it's instantiated,
 switching the configuration from using default OpenAI APIs to using Zuplo's AI
-Gateway for all `gpt-4o` requests that the LangChain SDK will make.
+Gateway.
+
+Always name the model as `providerName/model`, where `providerName` is the
+provider name configured in your gateway. The gateway needs the prefix to know
+which provider to route to, and a request with no model, or a model without that
+prefix, gets a `400`. Adding the
+[Model Filtering](../policies/model-filtering.mdx) policy restricts an app to
+certain models, and an allow list also supplies a default so requests may omit
+the model.

package/docs/ai-gateway/integrations/openai.mdx

@@ -1,6 +1,9 @@
 ---
 title: OpenAI SDK
 sidebar_label: OpenAI SDK
+description:
+  Set the OpenAI SDK's baseURL to your AI Gateway app's URL to route chat
+  completions, embeddings, and responses requests through the gateway.
 ---
 
 The
@@ -10,20 +13,20 @@ OpenAI compatible models from other providers in Node.js.
 
 ## Prerequisites
 
-In order to use the AI Gateway with any OpenAI SDK powered application you will
-need to complete these steps first:
+In order to use the AI Gateway with any OpenAI SDK powered app you will need to
+complete these steps first:
 
 <Stepper>
 
-1. Create a [new provider](/ai-gateway/managing-providers) in the AI Gateway for
+1. Create a [new provider](../managing-providers.mdx) in the AI Gateway for
    OpenAI
 
-2. [Set up a new team](/ai-gateway/managing-teams)
+2. [Set up a new team](../managing-teams.mdx)
 
-3. Create a [new app](/ai-gateway/managing-apps) to use specifically with the
-   OpenAI SDK and assign it to the team you created
+3. Create a [new app](../managing-apps.mdx) to use specifically with the OpenAI
+   SDK and assign it to the team you created
 
-4. Copy the API Key for the app you created, as well as the Gateway URL
+4. Copy the **API URL** and **API Key** shown at the top of the app page
 
 </Stepper>
 
@@ -32,23 +35,31 @@ need to complete these steps first:
 To route all OpenAI SDK requests through Zuplo instead of directly to the OpenAI
 API, you must set the API `baseUrl` in the SDK configuration.
 
-For example, if your Zuplo application is hosted at
-https://my-ai-gateway.zuplo.app, you can change the base URL in your API client
-to https://my-ai-gateway.zuplo.app/v1.
+The app page in the Zuplo Portal shows each app's API URL. It ends in the app's
+ID, so append `/v1` to it to get the base URL for your API client.
 
 Additionally, change the value of `apiKey` to the API key of the app you have
 configured in Zuplo
 
+Always name the model as `providerName/model`, where `providerName` is the
+provider name configured in your gateway. The gateway needs the prefix to know
+which provider to route to, and a request with no model, or a model without that
+prefix, gets a `400`. Adding the
+[Model Filtering](../policies/model-filtering.mdx) policy restricts an app to
+certain models, and an allow list also supplies a default so requests may omit
+the model.
+
 ```typescript
 import OpenAI from "openai";
 
 const client = new OpenAI({
   apiKey: process.env.ZUPLO_AI_GATEWAY_API_KEY,
-  baseURL: "https://my-ai-gateway.zuplo.app/v1",
+  baseURL:
+    "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1",
 });
 
 const response = await client.chat.completions.create({
-  model: "gpt-4",
+  model: "openai/gpt-5-mini",
   messages: [
     {
       role: "user",
@@ -65,8 +76,8 @@ APIs to using Zuplo's AI Gateway for all requests.
 
 ## Supported Endpoints
 
-The AI Gateway supports all major OpenAI API endpoints through the universal
-API:
+The AI Gateway supports all major OpenAI API endpoints through the
+[universal API](../universal-api.mdx):
 
 - **Chat Completions** (`/v1/chat/completions`) - For conversational AI
   interactions
@@ -84,11 +95,12 @@ import OpenAI from "openai";
 
 const client = new OpenAI({
   apiKey: process.env.ZUPLO_AI_GATEWAY_API_KEY,
-  baseURL: "https://my-ai-gateway.zuplo.app/v1",
+  baseURL:
+    "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1",
 });
 
 const response = await client.responses.create({
-  model: "gpt-5",
+  model: "openai/gpt-5",
   input: "Write a one-sentence bedtime story about a unicorn.",
 });
 

package/docs/ai-gateway/introduction.mdx

@@ -1,33 +1,49 @@
 ---
 title: Zuplo AI Gateway
 sidebar_label: Introduction
+description:
+  The Zuplo AI Gateway is a proxy between your apps and LLM providers, deployed
+  from your own Git repository, with per-app policy pipelines for cost control,
+  model access, guardrails, and observability.
 ---
 
 Zuplo's AI Gateway acts as an intelligent proxy layer that sits between your
-engineering team's applications and LLM providers like OpenAI, Anthropic,
-Google, Mistral, and xAI. Instead of your applications communicating directly
-with these providers, all requests flow through the Zuplo AI Gateway, which
-streams responses while applying policies, controls, and monitoring.
+engineering team's apps and LLM providers like OpenAI, Anthropic, Google,
+Mistral, and xAI. Instead of your apps communicating directly with these
+providers, all requests flow through the Zuplo AI Gateway, which streams
+responses while applying policies, controls, and monitoring.
+
+Each piece of software that calls the gateway registers as an **app**—your
+support chatbot is one app; an internal coding agent is another. A single AI
+Gateway holds as many apps as you need, and you control exactly which policies
+run for each one. Every app has its own ordered policy chain, so the
+customer-facing chatbot can enforce budgets and guardrails while the internal
+agent runs with none. Beyond the built-in policies, you can write your own in
+TypeScript, and apps add them to their chains like any other policy. Chain
+changes apply within about a minute, with no redeploy. See [Apps](./apps.mdx).
 
 ## Key Benefits
 
 **Provider Independence**: Switch between LLM providers (OpenAI, Anthropic,
-Google, Mistral, xAI, and more) dynamically without modifying application code.
-Configure your provider choice through the gateway rather than hard coding it
-into your applications.
+Google, Mistral, xAI, and more) dynamically without modifying app code.
+Configure model access through the gateway rather than hard coding it into your
+apps.
 
-**Cost Control**: Set spending limits at organization, team, and application
-levels with hierarchical budgets that cascade down through your structure.
-Configure daily and monthly thresholds with enforcement or warning
-notifications.
+**Cost Control**: Set spending limits at organization, team, and app levels with
+hierarchical budgets that cascade down through your structure. Configure daily
+and monthly thresholds with enforcement or warning notifications.
 
 **Security & Compliance**: Apply guardrails to detect and block prompt injection
 attempts and prevent PII leakage in both requests and responses through
 integrated AI firewall policies.
 
-**Self-Service Access**: Developers can create applications and access LLMs
-without needing direct access to provider API keys. Administrators configure
-providers once, and teams consume them securely.
+**Self-Service Access**: Developers can create apps and access LLMs without
+needing direct access to provider API keys. Administrators configure providers
+once, and teams consume them securely.
+
+**Extensibility**: Write custom policies in TypeScript—content filters, dynamic
+model routing, plan-based limits—and let apps add them to their chains like any
+built-in policy.
 
 **Performance Optimization**: Enable semantic caching to identify and return
 cached responses for similar prompts, reducing costs and improving response
@@ -38,12 +54,20 @@ time-to-first-byte metrics, and spending patterns across your organization.
 
 ## How It Works
 
-Your applications send requests to the Zuplo AI Gateway URL using your Zuplo API
-key. The gateway authenticates the request, applies configured policies (cost
-controls, security guardrails), routes to the selected LLM provider, and streams
-the response back to your application. Throughout this process, the gateway
-captures metrics and enforces limits without exposing underlying provider
-credentials.
+Your code sends its LLM requests to your AI Gateway instead of directly to a
+provider. Each app has its own URL, API key, and policy chain, so one gateway
+serves teams with completely different configurations.
+
+Each request arrives at the URL of the app it belongs to. The gateway identifies
+that app, runs its policy chain (model access, cost controls, security
+guardrails), routes to the selected LLM provider, and streams the response back.
+Throughout this process, the gateway captures metrics without exposing
+underlying provider credentials.
+
+Every control is opt-in. An app whose policy chain is empty proxies requests
+immediately—each request names its own model, and no model restrictions,
+budgets, guardrails, or caching apply until you add the policies that enforce
+them.
 
 ## Core Features
 
@@ -52,32 +76,49 @@ credentials.
 Configure multiple LLM providers within a single gateway project. Supported
 providers include OpenAI, Anthropic, Google, Mistral, xAI, and OpenAI-compatible
 custom providers. See [AI Providers](./providers.mdx) for the full list of
-providers and supported capabilities. Select which models are available to your
-teams when configuring each provider.
+providers and supported capabilities. Apps reference models as
+`providerName/model`—for example `openai/gpt-5-mini`—so a single app can use
+models from several providers.
+
+### Source-Controlled Gateway
+
+Every AI Gateway project connects to a Git repository that contains the
+gateway's routes and policy declarations. The default branch is what production
+runs, so gateway changes go through your normal review workflow. See
+[Source Control](./source-control.mdx).
+
+### Per-App Policy Chains
+
+Each app runs its own ordered chain of policies—model filtering, fallback
+models, budgets, semantic caching, guardrails, tracing, and any custom policies
+declared in the repository. Team policy templates give new apps a consistent
+starting pipeline. See [Policy Chains](./policy-chains.mdx) and
+[Custom Policies](./custom-policies.mdx).
 
 ### Team Hierarchy & Budgets
 
 Organize users into teams with hierarchical structures. Set budget limits at
 each level that cascade down:
 
-- **Root Team**: Organization-wide limits (for example, $1,000/day)
-- **Sub-Teams**: Team-specific limits that can't exceed parent limits (for
-  example, $500/day for the Credit Team)
-- **Applications**: Per-app limits for granular control
+- **Gateway**: Organization-wide limits (for example, $1,000/day)
+- **Teams**: Team-specific limits that can't exceed parent limits (for example,
+  $500/day for the Credit Team)
+- **Apps**: Per-app limits for granular control
+
+See [Usage Limits](./usage-limits.mdx).
 
-### Application Configuration
+### App Configuration
 
-Each application gets its own:
+Each app gets its own:
 
 - **Unique Gateway URL**: Single endpoint regardless of underlying provider
 - **API Key**: Zuplo-managed key that never exposes provider credentials
-- **Model Selection**: Choose specific models from configured providers
-- **Budget Thresholds**: Daily and monthly limits with enforcement or warnings
-- **Semantic Caching**: Optional caching of similar prompts to reduce costs
+- **Policy Chain**: Model access, budgets, caching, guardrails, and custom
+  policies, applied in the order the app chooses
 
 ## Use Cases
 
-- **Multi-tenant AI Applications**: Enforce spending limits per customer or team
+- **Multi-tenant AI Apps**: Enforce spending limits per customer or team
 - **Agent Development**: Build AI agents that can switch providers without code
   changes
 - **Cost Management**: Control and monitor LLM spending across your organization