zuplo 7.9.5 → 7.9.8

package/docs/ai-gateway/integrations/github-copilot.mdx

@@ -2,8 +2,8 @@
 title: GitHub Copilot
 sidebar_label: GitHub Copilot
 description:
-  Route GitHub Copilot in VS Code and the Copilot CLI through an AI Gateway app
-  so the gateway authenticates, meters, and routes every Copilot model request.
+  Route GitHub Copilot in VS Code and the Copilot CLI through the AI Gateway
+  with a personal API key, so every Copilot model request is metered per person.
 ---
 
 [GitHub Copilot](https://github.com/features/copilot) can use your own model
@@ -11,26 +11,26 @@ endpoint instead of GitHub's hosted models — the
 [Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/use-byok-models)
 through environment variables, and VS Code through its
 [Custom Endpoint provider](https://code.visualstudio.com/docs/agent-customization/language-models#_add-a-custom-endpoint-model).
-Point that endpoint at an AI Gateway app, and every Copilot chat and agent
-request is authenticated with the app's key, metered against the app's budgets,
-and limited to the models you allow. Developers keep using Copilot exactly as
-before; the app's page in the Zuplo Portal shows their requests, tokens, and
-spend as they work.
+Point that endpoint at the AI Gateway, and every Copilot chat and agent request
+is authenticated, metered against a budget, and limited to the models you allow.
+Developers keep using Copilot exactly as before, and their requests, tokens, and
+spend show up in the Zuplo Portal as they work.
 
 ## Before you start
 
-<Stepper>
-
-1. Create a [provider](../managing-providers.mdx) for the models Copilot will
-   use, such as OpenAI or Anthropic
-
-2. [Create a team](../managing-teams.mdx) for the developers using Copilot
+Create a [provider](../managing-providers.mdx) for the models Copilot will use,
+such as OpenAI or Anthropic, then get a gateway URL and key in one of two ways:
 
-3. Create an [app](../managing-apps.mdx) for Copilot and assign it to the team
+- **Use your personal API key (recommended).** Each developer calls the
+  project's [User App](../user-apps.mdx) with their own key. Open the
+  [**Home**](https://portal.zuplo.com/+/account/project/ai/home) tab of your AI
+  Gateway project, copy the **Gateway URL**, and create a key under **My API
+  keys**. Each developer's requests count against their own budget.
+- **Use an app.** For a shared setup with one key,
+  [create a pool](../managing-pools.mdx) and [an app](../managing-apps.mdx) for
+  Copilot, then copy the app's **API URL** and **API Key**.
 
-4. Copy the **API URL** and **API Key** shown at the top of the app page
-
-</Stepper>
+The rest of this guide calls these your **gateway URL** and **gateway key**.
 
 The gateway names models as `providerName/model`, where `providerName` is the
 name you gave the provider. The examples below use `openai` and `anthropic`;
@@ -39,12 +39,12 @@ substitute your own provider names.
 ## Copilot CLI
 
 The CLI reads its provider from four environment variables. Set the base URL to
-the app's API URL plus `/v1`, and name a model that supports tool calls, such as
+your gateway URL plus `/v1`, and name a model that supports tool calls, such as
 GPT-4.1:
 
 ```bash
-export COPILOT_PROVIDER_BASE_URL="https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1"
-export COPILOT_PROVIDER_API_KEY="<your-ai-gateway-app-api-key>"
+export COPILOT_PROVIDER_BASE_URL="https://my-gateway-main-2e18f50.zuplo.app/u/741d375d631b429293481d6d0458bb64/v1"
+export COPILOT_PROVIDER_API_KEY="<your-gateway-key>"
 export COPILOT_PROVIDER_TYPE="openai"
 export COPILOT_MODEL="openai/gpt-4.1-mini"
 ```
@@ -52,13 +52,13 @@ export COPILOT_MODEL="openai/gpt-4.1-mini"
 Start `copilot` from the same shell. Every request in the session now passes
 through the gateway.
 
-For a Claude model, use the `anthropic` provider type with the app's API URL
+For a Claude model, use the `anthropic` provider type with your gateway URL
 without `/v1` — the CLI appends `/v1/messages` itself — and pass the key as a
 bearer token, which is the header the gateway reads:
 
 ```bash
-export COPILOT_PROVIDER_BASE_URL="https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e"
-export COPILOT_PROVIDER_BEARER_TOKEN="<your-ai-gateway-app-api-key>"
+export COPILOT_PROVIDER_BASE_URL="https://my-gateway-main-2e18f50.zuplo.app/u/741d375d631b429293481d6d0458bb64"
+export COPILOT_PROVIDER_BEARER_TOKEN="<your-gateway-key>"
 export COPILOT_PROVIDER_TYPE="anthropic"
 export COPILOT_MODEL="anthropic/claude-sonnet-4-6"
 ```
@@ -79,8 +79,8 @@ configuration file VS Code opens.
 
 2. Select **Add Models**, then **Custom Endpoint**
 
-3. Enter a name for the group, such as `Zuplo AI Gateway`, and paste the app's
-   API key
+3. Enter a name for the group, such as `Zuplo AI Gateway`, and paste your
+   gateway key
 
 4. Select **Chat Completions** as the API type
 
@@ -89,7 +89,8 @@ configuration file VS Code opens.
 
 </Stepper>
 
-This configuration offers a GPT model and a Claude model from one app:
+This configuration offers a GPT model and a Claude model through one gateway
+URL:
 
 ```json
 [
@@ -102,7 +103,7 @@ This configuration offers a GPT model and a Claude model from one app:
         "id": "openai/gpt-5.6",
         "name": "GPT-5.6 (Zuplo)",
         "apiType": "responses",
-        "url": "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1/responses",
+        "url": "https://my-gateway-main-2e18f50.zuplo.app/u/741d375d631b429293481d6d0458bb64/v1/responses",
         "toolCalling": true,
         "vision": true,
         "maxInputTokens": 128000,
@@ -113,7 +114,7 @@ This configuration offers a GPT model and a Claude model from one app:
         "id": "anthropic/claude-sonnet-5",
         "name": "Claude Sonnet 5 (Zuplo)",
         "apiType": "messages",
-        "url": "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1/messages",
+        "url": "https://my-gateway-main-2e18f50.zuplo.app/u/741d375d631b429293481d6d0458bb64/v1/messages",
         "toolCalling": true,
         "vision": true,
         "maxInputTokens": 200000,
@@ -145,9 +146,9 @@ Save the file and pick a model from the chat model picker.
 ## What routes through the gateway
 
 Chat and agent requests, on both surfaces. Copilot's inline code completions
-stay on GitHub's infrastructure. The app's
+stay on GitHub's infrastructure. The
 [Model Filtering](../../policies/ai-gateway-model-filtering-inbound.mdx) policy
-decides which models Copilot may use.
+on the User App or the app decides which models Copilot may use.
 
 ## Troubleshooting
 
@@ -156,10 +157,11 @@ Copilot reports gateway errors as a retry failure, such as
 **GitHub Copilot Chat** channel of VS Code's Output panel, or in the CLI's error
 text.
 
-| The gateway responds                                              | Cause                                                                          | Fix                                                                     |
-| ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
-| `401` `Header configured by options.authHeader is missing`        | The key was sent as `x-api-key`                                                | VS Code: add `requestHeaders`. CLI: use `COPILOT_PROVIDER_BEARER_TOKEN` |
-| `401` `Invalid Authorization Scheme`                              | VS Code's `apiKey` was replaced with the key itself, so the key sent was empty | Re-enter the key with **Chat: Manage Language Models**                  |
-| `404`                                                             | The `url` stops at the app ID                                                  | Append `/v1/responses`, `/v1/messages`, or `/v1/chat/completions`       |
-| `Function tools with reasoning_effort are not supported`          | A GPT-5.x model on Chat Completions                                            | VS Code: `"apiType": "responses"`. CLI: use a GPT-4.1 or Claude model   |
-| `'temperature' does not support 0` or `temperature is deprecated` | The CLI's temperature setting on a GPT-5.x or Claude Sonnet 5 model            | Use GPT-4.1, GPT-4o, Claude Sonnet 4.6, or Claude Haiku 4.5             |
+| The gateway responds                                              | Cause                                                                              | Fix                                                                                                |
+| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `403` `This User App route requires a personal API key`           | A personal key that's missing, wrong, from another project, or sent as `x-api-key` | VS Code: add `requestHeaders`. CLI: use `COPILOT_PROVIDER_BEARER_TOKEN`. Check the key on **Home** |
+| `401` `Header configured by options.authHeader is missing`        | With an app key: the key was sent as `x-api-key`                                   | VS Code: add `requestHeaders`. CLI: use `COPILOT_PROVIDER_BEARER_TOKEN`                            |
+| `401` `Invalid Authorization Scheme`                              | VS Code's `apiKey` was replaced with the key itself, so the key sent was empty     | Re-enter the key with **Chat: Manage Language Models**                                             |
+| `404`                                                             | The `url` stops at the gateway URL                                                 | Append `/v1/responses`, `/v1/messages`, or `/v1/chat/completions`                                  |
+| `Function tools with reasoning_effort are not supported`          | A GPT-5.x model on Chat Completions                                                | VS Code: `"apiType": "responses"`. CLI: use a GPT-4.1 or Claude model                              |
+| `'temperature' does not support 0` or `temperature is deprecated` | The CLI's temperature setting on a GPT-5.x or Claude Sonnet 5 model                | Use GPT-4.1, GPT-4o, Claude Sonnet 4.6, or Claude Haiku 4.5                                        |

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

@@ -2,8 +2,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.
+  Add the AI Gateway as an OpenAI-compatible provider in the goose CLI or
+  desktop app, with your personal API key, so goose's requests route through the
+  gateway.
 ---
 
 [goose](https://block.github.io/goose/) is a local AI agent and CLI tool for
@@ -14,22 +15,20 @@ powerful extensibility through recipes.
 
 ## Prerequisites
 
-In order to use the AI Gateway with goose you will need to complete these steps
-first:
+Create a [provider](../managing-providers.mdx) in the AI Gateway for the
+provider you want to use with goose, then get a gateway URL and key in one of
+two ways:
 
-<Stepper>
-
-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](../managing-teams.mdx)
+- **Use your personal API key (recommended).** goose runs on your own machine,
+  so call the project's [User App](../user-apps.mdx). Open the
+  [**Home**](https://portal.zuplo.com/+/account/project/ai/home) tab of your AI
+  Gateway project, copy the **Gateway URL**, and create a key under **My API
+  keys**. Your requests count against your own budget.
+- **Use an app.** For a shared or automated setup,
+  [create a pool](../managing-pools.mdx) and [an app](../managing-apps.mdx) for
+  goose, then copy the app's **API URL** and **API Key**.
 
-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 URL** and **API Key** shown at the top of the app page
-
-</Stepper>
+The rest of this guide calls these your **gateway URL** and **gateway key**.
 
 ## Configure goose
 
@@ -47,12 +46,11 @@ configuration approaches depending on which version you choose.
 3. Choose **OpenAI** as the provider you want to add (this will work for any
    OpenAI compatible provider and model)
 
-4. Set the `OPENAI_API_KEY` to the API Key for the app you created for goose in
-   Zuplo
+4. Set the `OPENAI_API_KEY` to your gateway key
 
-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
+5. Set the `OPENAI_HOST` to your gateway URL _without_ the `/v1` suffix (for
+   example
+   `https://my-gateway-main-2e18f50.zuplo.app/u/741d375d631b429293481d6d0458bb64`)—the
    base path in the next step supplies it
 
 6. The `OPENAI_BASE_PATH` may already be configured. If it's not, enter
@@ -65,10 +63,9 @@ configuration approaches depending on which version you choose.
 
 :::note
 
-The app's
-[Model Filtering](../../policies/ai-gateway-model-filtering-inbound.mdx) policy
-controls which models the app may use, so the model you enter here must be one
-that policy allows.
+The [Model Filtering](../../policies/ai-gateway-model-filtering-inbound.mdx)
+policy on the User App or the app controls which models you may use, so the
+model you enter here must be one that policy allows.
 
 :::
 
@@ -96,13 +93,13 @@ Gateway by following these steps:
 
 6. Enter a **Display Name** (for example Zuplo AI Gateway)
 
-7. Set the **API URL** to your app's gateway URL
+7. Set the **API URL** to your gateway URL
 
-8. Set the **API Key** to the API key of the app you created for goose in Zuplo
+8. Set the **API Key** to your gateway key
 
-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`)
+9. Set the list of **Available Models** to the models the 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**
 

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

@@ -21,10 +21,10 @@ complete these steps first:
 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](../managing-teams.mdx)
+2. [Set up a new pool](../managing-pools.mdx)
 
 3. Create a [new app](../managing-apps.mdx) to use specifically with LangChain
-   and assign it to the team you created
+   and assign it to the pool you created
 
 4. Copy the **API URL** and **API Key** shown at the top of the app page
 

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

@@ -21,10 +21,10 @@ complete these steps first:
 1. Create a [new provider](../managing-providers.mdx) in the AI Gateway for
    OpenAI
 
-2. [Set up a new team](../managing-teams.mdx)
+2. [Set up a new pool](../managing-pools.mdx)
 
 3. Create a [new app](../managing-apps.mdx) to use specifically with the OpenAI
-   SDK and assign it to the team you created
+   SDK and assign it to the pool you created
 
 4. Copy the **API URL** and **API Key** shown at the top of the app page
 

package/docs/ai-gateway/jev.mdx

@@ -0,0 +1,344 @@
+---
+title: Using Jev
+sidebar_label: Jev
+description:
+  Call TypeSafe's Jev System One model through your AI Gateway. Send a state and
+  typed questions to your app's System One endpoint and get calibrated answers.
+---
+
+**Jev** is [TypeSafe's](https://typesafe.ai) System One model. It doesn't write
+text. You send it a piece of text—the _state_—and a set of typed questions, and
+it returns a calibrated answer for each one: a probability, a choice from
+options you define, or a score on a scale you define. Adding it as a provider
+puts the gateway in front of TypeSafe's API for authentication, model filtering,
+usage metering, and cost tracking, on your own TypeSafe account and billing.
+
+Jev differs from every other provider in three ways that change what you type:
+
+- **It has its own endpoint.** Requests go to `/v1/systemone`, not to chat
+  completions.
+- **Chat clients can't call it.** Every other endpoint refuses a Jev model, and
+  the default model list doesn't include it.
+- **Only input tokens cost money.** TypeSafe charges $0.042 per million input
+  tokens, and output tokens are free.
+
+## What Jev answers
+
+Each request carries a `state` and a set of named `questions`. A question's type
+decides the shape of its answer:
+
+| Question type | Asks                                | Answer                                                               |
+| ------------- | ----------------------------------- | -------------------------------------------------------------------- |
+| `noul`        | A yes-or-no question                | A probability between 0 and 1                                        |
+| `choice`      | Which of your options applies       | The chosen option, a probability for each option, and a confidence   |
+| `score`       | Where the state falls on your scale | A score on the scale, a probability for each level, and a confidence |
+
+The `state` is text: a string, a JSON object, or an array of text values. Jev
+doesn't accept images, audio, or video. TypeSafe's documentation explains
+[state](https://docs.typesafe.ai/concepts/state), the
+[question types](https://docs.typesafe.ai/primitives), and how to read a
+[confidence](https://docs.typesafe.ai/confidence).
+
+## Supported endpoint
+
+A Jev model serves one endpoint:
+
+| Endpoint                                                                  | Jev |
+| ------------------------------------------------------------------------- | --- |
+| `/v1/systemone`                                                           | ✅  |
+| `/v1/chat/completions`, `/v1/responses`, `/v1/messages`, `/v1/embeddings` | ❌  |
+
+The gateway forwards your request body to TypeSafe unchanged, except for the
+`model` field, which it replaces with the model ID your provider serves. The
+response body comes back unchanged too, including the `model` field, which
+reports the versioned model that answered. The `x-typesafe-request-id` header
+comes back as well. TypeSafe's own error responses (`401`, `422`, `429`, and
+`529`) pass through with TypeSafe's body, so the field a `422` names is the one
+to fix.
+
+The refusal works in both directions. A Jev model sent to a chat endpoint
+(`/v1/chat/completions`, `/v1/responses`, or `/v1/messages`) returns a `400`
+that names the endpoint, and a model from any other provider sent to
+`/v1/systemone` returns a `400` that names Jev. `/v1/embeddings` fails
+differently: Jev has no embedding models, so the gateway returns a `500` saying
+the model `is not included in model selections`.
+
+## Before you begin
+
+You need:
+
+- A TypeSafe account and an API key. Create a key in the
+  [TypeSafe console](https://console.typesafe.ai/keys).
+- An AI Gateway project in the Zuplo Portal, and an [app](./apps.mdx) to call
+  from. The app page shows its API URL, and its API key lives on the app's **API
+  Key** tab.
+
+## Add the provider
+
+Adding or editing providers requires the **Edit** permission, granted to Zuplo
+account and project **Admins**—see
+[Managing Providers](./managing-providers.mdx).
+
+<Stepper>
+
+1. Open
+   [**Settings → AI Providers**](https://portal.zuplo.com/+/account/project/ai/settings/data-models)
+   in your AI Gateway project in the Zuplo Portal.
+
+1. Click the **Add Provider** button.
+
+1. In the **AI Provider** list, select **Jev**.
+
+1. Review the **Provider Name**, which fills in as `jev`. You can replace it
+   with your own name, but only now—the name is permanent after creation, and
+   it's the prefix in every model reference.
+
+1. Paste your TypeSafe **API Key**. There's no endpoint or region to enter,
+   because TypeSafe is a single global host.
+
+1. Select the models to enable, then click **Create**.
+
+</Stepper>
+
+:::note
+
+Saving provider settings triggers an automatic production deployment of your
+gateway, because provider credentials are part of the deployed gateway. The
+change is live once the deployment completes.
+
+:::
+
+## Model references
+
+Apps reference models as `providerName/model`, where `providerName` is the name
+you gave the provider. The Jev catalog has three models, so a provider named
+`jev` can serve:
+
+| Model reference   | What it is                                                                                                                             |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `jev/jev-latest`  | TypeSafe's most recent stable release, and the default in TypeSafe's SDKs.                                                             |
+| `jev/jev-1.13.0`  | A specific release. Pin it when you tune confidence thresholds against one version.                                                    |
+| `jev/jev-preview` | TypeSafe's most recent release, official or not. It points to the same model as `jev-latest` until TypeSafe publishes a preview build. |
+
+An alias moves when TypeSafe ships a release, so the answers behind it can
+change without a change on your side. The response's `model` field reports the
+versioned ID that answered, so you can log which release produced each result.
+
+## Call the model
+
+Send requests to `/v1/systemone` under your app's URL, with the app's API key as
+a bearer token. Include the `model` in every request, as `jev/<model>`.
+
+### With TypeSafe's SDK
+
+TypeSafe's JavaScript SDK works against your app. Set `baseURL` to the app URL
+**without** `/v1`, because the SDK appends `/v1/systemone` itself. The `apiKey`
+is the app's API key, not your TypeSafe key.
+
+```ts
+import { choice, noul, score, TypeSafeClient } from "@typesafe-ai/sdk";
+
+const client = new TypeSafeClient({
+  baseURL:
+    "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e",
+  apiKey: process.env.ZUPLO_APP_API_KEY,
+  defaultModel: "jev/jev-latest",
+});
+
+const response = await client.systemOne({
+  state: "Help! My payouts have been failing for 3 days.",
+  questions: {
+    urgent: noul("Does this convey urgency?"),
+    department: choice("Which team should handle this?", {
+      billing: "Payments and invoices",
+      technical: null,
+    }),
+    frustration: score("How frustrated is the customer?", [
+      "Calm",
+      "Frustrated",
+      "Very angry",
+    ]),
+  },
+});
+
+console.log(response.answers.department.choice);
+```
+
+To use a different model for one call, pass `model: "jev/jev-1.13.0"` to
+`systemOne()`.
+
+### With HTTP
+
+```bash
+curl https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1/systemone \
+  -H "Authorization: Bearer $ZUPLO_APP_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "jev/jev-latest",
+    "state": "Help! My payouts have been failing for 3 days.",
+    "questions": {
+      "urgent": {
+        "type": "noul",
+        "instructions": "Does this convey urgency?"
+      },
+      "department": {
+        "type": "choice",
+        "instructions": "Which team should handle this?",
+        "criteria": { "billing": "Payments and invoices", "technical": null }
+      },
+      "frustration": {
+        "type": "score",
+        "instructions": "How frustrated is the customer?",
+        "criteria": ["Calm", "Frustrated", "Very angry"]
+      }
+    }
+  }'
+```
+
+The response is TypeSafe's, unchanged. The values below are illustrative:
+
+```json
+{
+  "model": "jev-1.13.0",
+  "answers": {
+    "urgent": { "type": "noul", "noul": 0.95 },
+    "department": {
+      "type": "choice",
+      "choice": "billing",
+      "probabilities": { "billing": 0.88, "technical": 0.12 },
+      "confidence": 0.81
+    },
+    "frustration": {
+      "type": "score",
+      "score": 1.05,
+      "legend": { "0": "Calm", "1": "Frustrated", "2": "Very angry" },
+      "probabilities": { "0": 0, "1": 0.95, "2": 0.05 },
+      "confidence": 0.92
+    }
+  },
+  "usage": { "input_tokens": 296, "output_tokens": 20 }
+}
+```
+
+### List the Jev models
+
+The default `GET /v1/models` list holds chat models, so it leaves Jev out. To
+list your Jev models, send `x-zuplo-models-endpoint: systemone`:
+
+```bash
+curl https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1/models \
+  -H "Authorization: Bearer $ZUPLO_APP_API_KEY" \
+  -H "x-zuplo-models-endpoint: systemone"
+```
+
+The list has one entry for each enabled model, such as `jev/jev-latest`.
+
+## Pricing and budgets
+
+The gateway prices each request from the model catalog at the rate on TypeSafe's
+[Models page](https://docs.typesafe.ai/models): $0.042 per million input tokens,
+and nothing for output. The response carries `X-Cost-USD` with the cost and
+`X-Cost-Source: catalog`, which tells you the figure came from the catalog
+rather than from TypeSafe. Each request counts toward token, request, and
+spending [budgets](./usage-limits.mdx).
+
+A token budget counts output tokens too, even though they're free, so it's
+slightly stricter than your TypeSafe invoice. A spending budget matches it.
+
+When a budget is exhausted, the gateway refuses the request with a `429` before
+it calls TypeSafe. A System One request never falls back to another model,
+because no chat model can answer a set of typed questions.
+
+TypeSafe's own rate limits apply to your key. A request over a limit returns
+TypeSafe's `429` with its `retry-after` header. The Models page lists the
+current limits.
+
+## Policies on System One routes
+
+These routes run your app's [policy chain](./policy-chains.mdx) like any other.
+What changes is the request body: it's a System One request, not a chat message,
+so a policy that reads chat content applies its `onUnknownShape` setting
+instead. Each policy's default follows from its job: a guardrail fails closed,
+while an observer or an optimization fails open.
+
+| Policy                                                                                                                                                                                       | On System One routes                                                                                                                                                                                             |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Authentication](../policies/ai-gateway-auth-inbound.mdx)                                                                                                                                    | Works. Reads the app key from `Authorization: Bearer`, which is how TypeSafe's SDK sends it.                                                                                                                     |
+| [Model Filtering](../policies/ai-gateway-model-filtering-inbound.mdx)                                                                                                                        | Works. Add the Jev models to the allow list. A Jev model outside the list returns `403`, and a listed model from another provider returns `400`.                                                                 |
+| [Model Override](../policies/ai-gateway-model-override-inbound.mdx)                                                                                                                          | Works when the configured model is a Jev model. A chat model returns a configuration error that names the option, such as `options.models.completions.force`.                                                    |
+| [Metering and budgets](../policies/ai-gateway-metering-inbound.mdx)                                                                                                                          | Works. Counts each request with its tokens and cost. An exhausted budget returns `429`.                                                                                                                          |
+| [DLP](../policies/ai-gateway-dlp-inbound.mdx), [Akamai AI Firewall](../policies/ai-gateway-akamai-firewall-inbound.mdx), and [Prompt Injection](../policies/ai-gateway-prompt-injection.mdx) | **Blocks by default.** The policy can't inspect a System One body, so it denies the request with a `400` and the error code `guardrail_uninspectable`. Set `onUnknownShape` to `skip` to forward it uninspected. |
+| [Galileo](../policies/ai-gateway-galileo-tracing-inbound.mdx) and [Comet Opik](../policies/ai-gateway-opik-tracing-inbound.mdx) tracing                                                      | **Skipped by default.** The request goes through untraced. Set `onUnknownShape` to `deny` to make a trace a hard requirement.                                                                                    |
+| Semantic Cache and Smart Router                                                                                                                                                              | Skipped.                                                                                                                                                                                                         |
+| [Fallback Model](./fallback.mdx)                                                                                                                                                             | Doesn't apply. A System One request goes to the one model it names, so a configured backup isn't used.                                                                                                           |
+
+:::tip{title="Give System One its own app"}
+
+An app can serve chat models and Jev side by side, as long as every request
+names its model and no policy overrides it. Model Override's `force` replaces
+the model in every request, and its `default` and the first entry of a Model
+Filtering allow list supply one when a request omits it. Each picks a single
+model, which can't be both a chat model and a Jev model. If you use one of them,
+give System One its own app.
+
+:::
+
+## Troubleshooting
+
+**A `400` that names a chat endpoint and your Jev provider.** You sent a Jev
+model to `/v1/chat/completions`, `/v1/responses`, or `/v1/messages`. Call
+`/v1/systemone` instead.
+
+**A `400` saying `/v1/systemone` is only supported by providers that serve the
+TypeSafe System One API.** The model in the request belongs to another provider.
+Use a `jev/<model>` reference.
+
+**A `400` saying the route requires the `jev` API.** The Model Filtering policy
+found a model that isn't a Jev model. Send a `jev/<model>` reference, and put a
+Jev model first in the allow list if requests omit `model`.
+
+**A `403` from the Model Filtering policy.** The Jev model isn't in the app's
+allow list. Add it, for example `jev/jev-latest`.
+
+**A `400` with the error code `guardrail_uninspectable`.** A guardrail policy in
+the app's chain can't inspect System One requests and denies them by default.
+See [the policy table](#policies-on-system-one-routes).
+
+**A `401`.** Two different keys can cause one. A `401` with a Problem Details
+body (`application/problem+json`) comes from the gateway's authentication, so
+check the app's API key. A `401` whose `detail.message` begins
+`Cannot authenticate with the server` comes from TypeSafe, which rejected the
+provider's API key. Update it in
+[**Settings → AI Providers**](https://portal.zuplo.com/+/account/project/ai/settings/data-models)
+with a key from the [TypeSafe console](https://console.typesafe.ai/keys).
+
+**A `422` naming a field.** TypeSafe rejected the request body, and the gateway
+passed its answer through. The `detail` array names the field that failed
+validation.
+
+**An error saying the model `is not included in model selections`.** On
+`/v1/embeddings`, this is expected: Jev has no embedding models, so call
+`/v1/systemone` instead. On `/v1/systemone`, the model isn't enabled for the
+provider. Open the provider in
+[**Settings → AI Providers**](https://portal.zuplo.com/+/account/project/ai/settings/data-models),
+enable the model, and save.
+
+**Your app's model list has no Jev models.** Expected. The default list holds
+chat models—see [List the Jev models](#list-the-jev-models).
+
+**TypeSafe's `client.models.list()` throws.** The SDK expects TypeSafe's own
+list format, and the gateway answers `GET /v1/models` in the OpenAI format. Name
+the model in `defaultModel` or in each call instead, or list the models with the
+`x-zuplo-models-endpoint` header.
+
+## Next steps
+
+- [AI Providers](./providers.mdx)—the capability matrix across every supported
+  provider.
+- [Managing Providers](./managing-providers.mdx)—edit models and keys, and
+  understand when changes deploy.
+- [AI Gateway Apps](./apps.mdx)—create the apps that call your models.
+- [Model Filtering policy](../policies/ai-gateway-model-filtering-inbound.mdx)—control
+  which models each app can call.
+- [Usage limits](./usage-limits.mdx)—set budgets on tokens, requests, and
+  spending.