zuplo 7.1.1 → 7.1.3

package/docs/ai-gateway/getting-started.mdx

@@ -1,130 +1,202 @@
 ---
 title: Zuplo AI Gateway Getting Started
 sidebar_label: Getting Started
+description:
+  Set up your first AI Gateway project. Connect a Git repository, configure an
+  AI provider, create a team and an app, review the app's policy chain, and make
+  your first LLM request through Zuplo.
 ---
 
-This guide will walk you through setting up your first AI Gateway project, from
-initial configuration to making your first LLM request through Zuplo.
+This guide walks you through setting up your first AI Gateway project, from
+connecting a Git repository to making your first LLM request through Zuplo.
 
 ## Prerequisites
 
 - A Zuplo account (sign up free at [zuplo.com](https://zuplo.com))
-- API keys for at least one LLM provider (OpenAI, Anthropic, Google, Mistral,
-  xAI, etc.)
-- An application that needs to call LLM APIs
+- An account with a supported Git provider that can create repositories (this
+  guide uses GitHub)
+- An API key for at least one LLM provider (OpenAI, Anthropic, Google, Mistral,
+  xAI, etc.)—or none at all, if you start with the free
+  [Zuplo Demo provider](./providers.mdx#zuplo-demo)
 
-## Step 1: Create an AI Gateway Project
+<Stepper>
 
-1. Log into your Zuplo account
-2. Navigate to **Projects**
-3. Click **New Project**
-4. Click **AI or MCP Gateway** at the bottom of the dialog
-5. Give your project a name (for example, "MyCompany AI Gateway")
-6. Click **Create Project**
+1. **Create an AI Gateway project**
 
-Your AI Gateway project will be created in seconds. You'll notice the interface
-includes Apps, Teams, and a setup guide to help you get started.
+   Log into the [Zuplo Portal](https://portal.zuplo.com), navigate to
+   **Projects**, and click **New Project**. Choose **Configure an AI gateway**,
+   give your project a name (for example, "MyCompany AI Gateway"), and click
+   **Create Project**.
 
-## Step 2: Configure Providers
+2. **Connect the project to a Git repository**
 
-Providers are the LLM services (like OpenAI or Anthropic) that your applications
-will use. You'll configure these once as an administrator, and your team members
-can use them without needing direct access to provider API keys.
+   Your AI Gateway deploys from source control, so the first step after creating
+   the project is connecting it to a repository. The project shows a **Let's Get
+   You Deployed** screen until a repository is connected.
 
-### Adding Your First Provider
+   Zuplo supports GitHub, GitLab, Bitbucket, and Azure DevOps. This guide uses
+   GitHub, which is the only provider with automatic deployments—see
+   [Source Control and Deployment](../concepts/source-control-and-deployment.mdx)
+   for the other providers, which deploy through the Zuplo CLI in your own CI/CD
+   pipeline.
 
-1. Click **Add Provider**
-2. Select your AI provider (for example, **OpenAI**)
-3. Enter a name for this provider configuration
-4. Paste your provider's API key
-5. Select which models you want to make available to your teams
-6. Click **Create**
+   With GitHub, click **Create New Repo** to open GitHub with the repository
+   name prefilled, create the repository, then return to the Zuplo Portal and
+   select the repository to connect it. Zuplo adds the gateway's source to the
+   repository and deploys it. After that, pushes to your default branch deploy
+   to production.
 
-### Adding Additional Providers
+   To work with the gateway's source later—for example, to add
+   [custom policies](./custom-policies.mdx)—clone the repository:
 
-Repeat the process above to add more providers. This allows your teams to switch
-between providers (OpenAI, Anthropic, etc.) without changing application code.
+   ```bash
+   git clone https://github.com/your-org/your-gateway-repo.git
+   ```
 
-**Example providers you might add:**
+   :::note
 
-- OpenAI (for GPT models)
-- Anthropic (for Claude models)
-- Google (for Gemini models)
-- Mistral (for Mistral models)
-- xAI (for Grok models)
+   If your default branch requires pull requests, Zuplo pushes the gateway
+   source to a setup branch and shows you a pull request to merge. The project
+   finishes connecting once the pull request lands on the default branch.
 
-See [AI Providers](./providers.mdx) for the full list of supported providers and
-capabilities, including OpenAI-compatible custom providers.
+   :::
 
-## Step 3: Create a Team
+   See [Source Control](./source-control.mdx) for what the repository contains
+   and how deployments work.
 
-Teams allow you to organize users and set hierarchical budget controls. Even if
-you're starting solo, you'll need at least one team.
+3. **Configure a provider**
 
-### Creating Your Root Team
+   Providers are the LLM services (like OpenAI or Anthropic) that your apps use.
+   You configure these once as an administrator, and your team members use them
+   without needing direct access to provider API keys.
 
-1. Click **Create Team**
-2. Name your team (for example, "Root" or your company name)
-3. Choose an icon for easy identification
-4. Click **Create Team**
-5. Set organization-wide limits (optional) by selecting the **Usage & Limits**
-   tab:
-   - **Budget Limit**: Maximum spend per day (for example, $1,000)
-   - **Rate Limits**: Request limits if needed
+   Open
+   [**Settings → AI Providers**](https://portal.zuplo.com/+/account/project/ai/settings/data-models)
+   and click **Add Provider**. Select your AI provider (for example,
+   **OpenAI**), paste your provider's API key, and select which models to make
+   available. The **Provider Name** field fills in automatically based on the
+   provider you selected—`openai`, for example. Click **Create**.
 
-### Creating Sub-Teams (Optional)
+   :::caution{title="The provider name becomes the model prefix"}
 
-For larger organizations, create sub-teams with their own budgets:
+   Apps reference this provider's models as `providerName/model`, so the
+   provider name is the prefix in every model string—a provider named `openai`
+   serves `openai/gpt-5-mini`. The pre-filled name is usually what you want. To
+   use your own, set it now—the name is permanent after creation—and keep it
+   short and lowercase.
 
-1. From your root team, click **Create Sub-Team**
-2. Name the team (for example, "Engineering Team", "Credit Team")
-3. Choose an icon
-4. Set team-specific limits by clicking on **Settings**:
-   - Daily budgets that are equal to or less than the parent team's limit
-   - Example: If root is $1,000/day, a sub-team might be $500/day
-5. Click **Save Changes**
+   :::
 
-## Step 4: Create Applications
+   Repeat for additional providers. See [AI Providers](./providers.mdx) for the
+   full list of supported providers, including OpenAI-compatible custom
+   providers.
 
-Applications represent individual projects or services that will use the AI
-Gateway. Each app gets its own unique URL and API key.
+4. **Create a team**
 
-### Creating Your First App
+   Teams organize users and carry hierarchical budget controls and policy
+   templates. Even if you're starting solo, you need at least one team.
 
-1. Click **Apps** followed by **Create App**
-2. Configure your app:
-   - **App Name**: Descriptive name (for example, "Tennis Chat", "Customer
-     Support Bot")
-   - **Team**: Select which team owns this app
-   - **Provider**: Choose your LLM provider (for example, OpenAI)
-   - **Completions**: Select the model for chat completions (for example,
-     GPT-4o)
-   - **Embeddings**: Select the model for embeddings (optional)
-3. Set application-level budgets:
-   - **Daily Limit**: (for example, $1/day for a hackathon project)
-   - **Monthly Limit**: (for example, $10/month)
-4. Enable **Semantic Caching** (optional):
-   - Caches similar prompts to reduce costs and improve performance
-   - Best for applications with repeated queries
-5. Click **Create App**
+   Open the **Teams** tab and click **Create Team**. Name your team (for
+   example, "Root" or your company name), choose an icon, and click **Create
+   Team**. To set organization-wide spending limits, open the gateway's
+   **Settings → Usage Limits**; for team-specific limits, use the team's **Usage
+   & Limits** tab. See [Usage Limits](./usage-limits.mdx).
 
-### Access Your App Credentials
+5. **Create an app**
 
-After creating your application, you'll see:
+   Apps represent individual projects or services that call the AI Gateway. Each
+   app gets its own unique URL and API key.
 
-- **API Key**: Your Zuplo-managed key. You'll need it to integrate with your
-  application.
+   Open the **Apps** tab and click **Create App**. Give the app a descriptive
+   name (for example, "Tennis Chat") and select the team that owns it. That's
+   the whole dialog—models, budgets, and other behavior are configured on the
+   app's policy chain in the next step.
 
-## Step 5: Integrate with Your Application
+   :::tip
 
-Now you'll update your application to use the Zuplo AI Gateway instead of
-calling LLM providers directly.
+   If the app's team has a policy template, the new app starts with the
+   template's policy chain already in place. See
+   [Policy Templates](./policy-templates.mdx).
 
-In the examples below, we assume that you are using the official
-[Node.js OpenAI SDK](https://platform.openai.com/docs/libraries/node-js-library)
-and that you have executed `npm install openai`.
+   :::
 
-### Before: Direct Provider Integration (sample.mjs)
+6. **Review the app's policy chain**
+
+   The portal opens the app's **Policies** tab, which shows the app's policy
+   chain—the ordered list of policies that run on each request. No policy is
+   required: an app with an empty chain works immediately, and each request
+   picks its own model as `providerName/model`, from any model your providers
+   expose.
+
+   To restrict that, add the **Model Filtering** policy and give it an allow
+   list such as `openai/gpt-5-mini`. Requests may then use only listed models,
+   and the first entry becomes the default when a request omits `model`.
+
+   :::caution{title="An unrestricted app can reach every model you configured"}
+
+   Without Model Filtering, an app may call any model available through the
+   providers assigned to its team, including expensive ones. Add Model Filtering
+   for any app that should be limited to a specific set.
+
+   :::
+
+   This is also where you add budgets, semantic caching, guardrails, and any
+   custom policies. Changes to the chain apply within about a minute—no redeploy
+   needed. See [Policy Chains](./policy-chains.mdx).
+
+7. **Get the app's URL and API key**
+
+   The app page shows its **API URL** and **API Key** at the top right. The API
+   URL is the gateway's hostname plus the app's ID—for example
+   `https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e`.
+   Copy both rather than constructing them.
+
+   Client libraries expect a base URL ending in `/v1`, so append it: the OpenAI
+   SDK examples below use
+   `https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1`
+   as a stand-in, and requests land on paths like `/v1/chat/completions`.
+
+   :::note
+
+   The gateway checks the key only after you add the
+   [authentication policy](./policy-chains.mdx#authentication) to the route or
+   to the app's chain. Until then the gateway identifies the app from the
+   `{app_id}` segment of the URL and accepts the request without a key. The
+   examples below send the key so they keep working once you add the policy.
+
+   :::
+
+   Export the key so the samples below can read it:
+
+   ```bash
+   export ZUPLO_APP_API_KEY="<the API key from the app page>"
+   ```
+
+8. **Send your first request from the Playground**
+
+   The app's **Playground** tab chats with the app's own gateway URL and API
+   key, so it exercises the same policy chain your code will hit—without wiring
+   up a client first.
+
+   Pick a model from the selector, optionally set a system prompt, and send a
+   message. The tab shows the cURL for the next request, and **Copy cURL** puts
+   it on your clipboard to run in a terminal or adapt it for your client. Expand
+   any reply to inspect the request and the raw response.
+
+</Stepper>
+
+## Integrate with your own code
+
+Once the Playground works, configure your own code with the same URL and key.
+
+These examples use the official
+[Node.js OpenAI SDK](https://platform.openai.com/docs/libraries/node-js-library);
+run `npm install openai` first. For other clients, see the integration guides
+for the [OpenAI SDK](./integrations/openai.mdx),
+[AI SDK](./integrations/ai-sdk.mdx), and
+[LangChain](./integrations/langchain.mdx).
+
+### Before: direct provider integration (sample.mjs)
 
 ```javascript
 import OpenAI from "openai";
@@ -135,26 +207,27 @@ const openai = new OpenAI({
 });
 
 const completion = await openai.chat.completions.create({
-  model: "gpt-4",
+  model: "gpt-5-mini",
   messages: [{ role: "user", content: "Hello!" }],
 });
 
 console.log(completion.choices[0].message.content);
 ```
 
-### After: Using Zuplo AI Gateway (sample.mjs)
+### After: using the Zuplo AI Gateway (sample.mjs)
 
 ```javascript
 import OpenAI from "openai";
 
 // New approach - using Zuplo AI Gateway
 const openai = new OpenAI({
-  apiKey: process.env.ZUPLO_API_KEY,
-  baseURL: "https://your-ai-gateway-url.zuplo.app/v1",
+  apiKey: process.env.ZUPLO_APP_API_KEY,
+  baseURL:
+    "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1",
 });
 
 const completion = await openai.chat.completions.create({
-  model: "gpt-4",
+  model: "openai/gpt-5-mini",
   messages: [{ role: "user", content: "Hello!" }],
 });
 
@@ -163,35 +236,39 @@ console.log(completion.choices[0].message.content);
 
 Run the example with `node sample.mjs`.
 
-### What Changed?
+### What changed?
 
-1. **URL**: Replace your provider's URL with your Zuplo Gateway URL
-2. **API Key**: Use your Zuplo API key instead of the provider's key
-3. **Everything else stays the same**: The request format remains compatible
+1. **URL**: Replace your provider's URL with your app's gateway URL from the app
+   page
+2. **API Key**: Use your app's API key instead of the provider's key—the gateway
+   checks it once the authentication policy applies
+3. **Model**: Reference models as `providerName/model` so the gateway knows
+   which provider to route to
+4. **Everything else stays the same**: The request format remains compatible
    with OpenAI's API
 
-## Verify Your Setup
+## Verify your setup
 
-### Make Your First Request
+### Make your first request
 
-Send a test request through your gateway:
+Send a test request through your gateway, using your app's URL and API key:
 
 ```bash
-curl https://your-ai-gateway-url.zuplo.app/v1/chat/completions \
-  -H "Authorization: Bearer YOUR_ZUPLO_API_KEY" \
+curl https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1/chat/completions \
+  -H "Authorization: Bearer YOUR_APP_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{
-    "model": "gpt-4",
+    "model": "openai/gpt-5-mini",
     "messages": [{"role": "user", "content": "Hello, world!"}]
   }'
 ```
 
-### Check Your Dashboard
+### Check your dashboard
 
 1. Open the [**Apps**](https://portal.zuplo.com/+/account/project/ai/apps) tab
    of your AI Gateway project
 2. Click on your app
-3. Click on **Dashboard** to view:
+3. Click on the app's **Dashboard** tab to view:
    - Request count
    - Token usage
    - Time to first byte
@@ -200,31 +277,23 @@ curl https://your-ai-gateway-url.zuplo.app/v1/chat/completions \
 You should see your test request appear with token usage and performance
 metrics.
 
-## Next Steps
-
-Now that your AI Gateway is running, explore additional features:
-
-### Switch Providers Without Code Changes
-
-1. Go to your app settings
-2. Change the **Provider** dropdown (for example, from OpenAI to Anthropic)
-3. Select a new model
-4. Click **Save Changes**
-
-Your application will now use the new provider without any code changes.
-
-## Common Issues
-
-**Issue**: "Authentication failed" error
-
-- **Solution**: Verify you're using your Zuplo API key, not your provider's key
-
-**Issue**: Budget limit reached immediately
-
-- **Solution**: Check that sub-team limits don't exceed available budget from
-  parent team
-
-**Issue**: Semantic caching not working
-
-- **Solution**: Ensure caching is enabled in your application settings and
-  prompts are similar enough to match
+## Next steps
+
+- [Policy Chains](./policy-chains.mdx): add budgets, semantic caching, and
+  guardrails to your app's chain
+- [Custom Policies](./custom-policies.mdx): write your own policy and add it to
+  an app's chain
+- [Policy Templates](./policy-templates.mdx): give every new app in a team a
+  consistent starting chain
+- [Usage Limits](./usage-limits.mdx): set spending limits for the gateway,
+  teams, and apps
+
+## Common issues
+
+| Symptom                                   | Fix                                                                                                                                                                 |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "Authentication failed" error             | Verify you're using your app's API key, not your provider's key. This error appears only when the authentication policy applies                                     |
+| 404 "Unsupported AI Gateway endpoint"     | The path must end with a supported `/v1/...` operation—usually the URL is missing its `/v1` segment. Use the app's API URL plus `/v1/chat/completions`, for example |
+| 400 error asking for `providerName/model` | Prefix the model with the provider name configured in the portal—`openai/gpt-5-mini`, not `gpt-5-mini`                                                              |
+| 403 error listing the allowed models      | The app's Model Filtering policy doesn't include the requested model; add it on the app's Policies tab or use a listed one                                          |
+| Budget limit reached immediately          | Check the limits at every level—gateway, team, and the app's Budgets and Costs policy—since any level's limit blocks the request                                    |

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

@@ -1,6 +1,10 @@
 ---
 title: AI SDK
 sidebar_label: AI SDK
+description:
+  Route AI SDK requests through the Zuplo AI Gateway by pointing each provider's
+  base URL at your app's gateway URL and referencing models as
+  providerName/model.
 ---
 
 The [AI SDK](https://ai-sdk.dev/) is a free open-source library that gives you
@@ -10,32 +14,47 @@ community supported providers being added regularly.
 
 ## Prerequisites
 
-In order to use the AI Gateway with any AI SDK powered application you will need
-to complete these steps first:
+In order to use the AI Gateway with any AI 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
-   the provider you want to use with AI SDK
+1. Create a [new provider](../managing-providers.mdx) in the AI Gateway for the
+   provider you want to use with AI SDK
 
-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 AI SDK
-   and assign it to the team you created
+3. Create a [new app](../managing-apps.mdx) to use specifically with AI 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>
 
 ## Configure the AI SDK
 
 To route all AI SDK requests through Zuplo instead of directly to the API of the
-chosen provider, you must set the API `baseUrl` in the SDK configuration to
-point to the Gateway URL of your Zuplo AI Gateway.
+chosen provider, you must set `baseURL` in the SDK configuration to point to
+your app's API URL with `/v1` appended. The app page in the Zuplo Portal shows
+the URL, which ends in the app's ID.
 
 Additionally, you will need to change the value of `apiKey` to the API key of
 the app you have configured in Zuplo.
 
+Models are referenced as `providerName/model`, where `providerName` is the
+provider name configured in your gateway. By default an app can reach any model
+offered by the providers assigned to its [team](../managing-teams.mdx). To limit
+it to a curated set, add the [Model Filtering](../policies/model-filtering.mdx)
+policy to the app—it applies separate rules to completions (`generateText`,
+`streamText`) and embeddings (`embed`), and rejects a capability it doesn't
+configure.
+
+Each provider package appends its own operation path to `baseURL`, so pick the
+model factory that targets an endpoint the gateway serves:
+`/v1/chat/completions` for OpenAI-compatible requests, `/v1/messages` for
+Anthropic, `/v1/embeddings`, and `/v1/responses` for OpenAI only. The examples
+below use the right factory for each provider.
+
 ### OpenAI
 
 ```typescript
@@ -44,43 +63,45 @@ import { generateText } from "ai";
 
 const openai = createOpenAI({
   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 { text } = await generateText({
-  model: openai.chat("gpt-4o"),
+  model: openai.chat("openai/gpt-5-mini"),
   prompt: "Write a one-sentence bedtime story about a unicorn.",
 });
 ```
 
 ### Anthropic
 
+Pass the app's API key as `authToken`, not `apiKey`. The provider sends `apiKey`
+as the `x-api-key` header, which the gateway doesn't read, while `authToken` is
+sent as `Authorization: Bearer`. Setting both throws an `InvalidArgumentError`.
+
 ```typescript
 import { createAnthropic } from "@ai-sdk/anthropic";
 import { generateText } from "ai";
 
 const anthropic = createAnthropic({
-  apiKey: process.env.ZUPLO_AI_GATEWAY_API_KEY,
-  baseURL: "https://my-ai-gateway.zuplo.app/v1",
-  // Authorization header is also required
-  headers: {
-    Authorization: `Bearer ${process.env.ZUPLO_AI_GATEWAY_API_KEY}`,
-  },
+  authToken: process.env.ZUPLO_AI_GATEWAY_API_KEY,
+  baseURL:
+    "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1",
 });
 
 const { text } = await generateText({
-  model: anthropic("claude-sonnet-4-5-20250929"),
+  model: anthropic("anthropic/claude-sonnet-4-5-20250929"),
   prompt: "Write a one-sentence bedtime story about a unicorn.",
 });
 ```
 
 ### Google
 
-The `@ai-sdk/google` provider speaks Gemini's native protocol: it sends requests
-to `/models/{model}:generateContent` and authenticates with the `x-goog-api-key`
+The `@ai-sdk/google` provider speaks Gemini's native protocol: it posts to a
+`{model}:generateContent` path and authenticates with the `x-goog-api-key`
 header, neither of which the AI Gateway serves. Use the
 [OpenAI-compatible provider](https://ai-sdk.dev/providers/openai-compatible-providers)
-instead — the AI Gateway translates OpenAI-format requests to Google upstream.
+instead—the AI Gateway translates OpenAI-format requests to Google upstream.
 
 ```typescript
 import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
@@ -89,11 +110,12 @@ import { generateText } from "ai";
 const gateway = createOpenAICompatible({
   name: "zuplo-ai-gateway",
   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 { text } = await generateText({
-  model: gateway("gemini-2.5-flash"),
+  model: gateway("google/gemini-2.5-flash"),
   prompt: "Write a one-sentence bedtime story about a unicorn.",
 });
 ```
@@ -106,28 +128,49 @@ import { generateText } from "ai";
 
 const mistral = createMistral({
   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 { text } = await generateText({
-  model: mistral("mistral-large-latest"),
+  model: mistral("mistral/mistral-large-latest"),
   prompt: "Write a one-sentence bedtime story about a unicorn.",
 });
 ```
 
 ### xAI
 
+Call `xai.chat(...)` rather than `xai(...)`. The bare callable targets xAI's
+Responses API, and the gateway serves `/v1/responses` for the OpenAI provider
+only—an xAI model sent there returns a `400`.
+
 ```typescript
 import { createXai } from "@ai-sdk/xai";
 import { generateText } from "ai";
 
 const xai = createXai({
   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 { text } = await generateText({
-  model: xai("grok-4"),
+  model: xai.chat("xai/grok-4"),
   prompt: "Write a one-sentence bedtime story about a unicorn.",
 });
 ```
+
+## Provider options the gateway doesn't forward
+
+On the OpenAI-shaped endpoints (`/v1/chat/completions`, `/v1/embeddings`, and
+`/v1/responses`) the gateway rebuilds the upstream request from a per-provider
+parameter list instead of forwarding your body as-is. Standard AI SDK settings—
+messages, `temperature`, `topP`, `maxOutputTokens`, `stopSequences`, `tools`,
+`toolChoice`, `responseFormat`, `presencePenalty`, and `frequencyPenalty`—are
+forwarded. Options outside that list are dropped without a warning. For example,
+`seed` and `providerOptions.mistral.safePrompt` don't reach Mistral, and
+`temperature` is capped at Mistral's maximum of `1`.
+
+Anthropic is different: `/v1/messages` is a native passthrough, so
+`@ai-sdk/anthropic` requests reach Anthropic unchanged apart from the model and
+credential, which the gateway sets from your app configuration.