zuplo 7.7.9 → 7.7.11

package/docs/ai-gateway/azure-ai.mdx

@@ -111,19 +111,53 @@ resource serves Claude on either host family the provider accepts.
 | ---------------------- | ------------------------ | ------------- |
 | `/v1/chat/completions` | ✅ Forwarded             | ✅ Translated |
 | `/v1/embeddings`       | ✅ Embedding models      | ❌            |
-| `/v1/messages`         | ❌                       | ✅ Native     |
-| `/v1/responses`        | ❌                       | ❌            |
+| `/v1/messages`         | ❌                       | ✅ Forwarded  |
+| `/v1/responses`        | ✅ Models that serve it  | ❌            |
 
-Streaming (`stream: true`) works on chat completions and messages.
+**Forwarded** means the gateway sends your request on in the shape you wrote it.
+**Translated** means it converts between two API shapes, which limits you to the
+parameters listed below.
+
+Streaming (`stream: true`) works on chat completions, messages, and responses.
 
 The catalog carries three embedding models—`text-embedding-3-small`,
 `text-embedding-3-large` and `text-embedding-ada-002`—so `/v1/embeddings` works
 once you deploy one of them and map your deployment to it.
 
-`/v1/responses` isn't served for Azure AI, and a Responses request fails with a
-`400` error before any upstream call. Azure does serve a Responses API on its
-own endpoint; the gateway doesn't route to it yet. Use `/v1/chat/completions`
-instead.
+`/v1/responses` serves the OpenAI Responses API, buffered and streaming. Support
+is **per deployed model**, not per resource: Azure serves Responses for
+particular model and version combinations, and a deployment outside that set
+answers `400` with `The requested operation is unsupported`—which is what an
+embedding deployment on this endpoint returns. Check Azure's own Responses API
+model list for your model and version before relying on it.
+
+The management operations on a stored response are forwarded too:
+
+| Operation                            | Does                                  |
+| ------------------------------------ | ------------------------------------- |
+| `GET /v1/responses/{id}`             | Retrieves the response                |
+| `GET /v1/responses/{id}/input_items` | Lists the input items of one response |
+| `DELETE /v1/responses/{id}`          | Deletes the response                  |
+
+Two things they need. Send **`store: true`** on the create, since your resource
+serves them only for a response it kept. And because these requests carry no
+body, there is no `model` in them for the gateway to route on—it uses the app's
+first configured completions model instead, so the app needs a
+[Model Filtering](../policies/ai-gateway-model-filtering-v2-inbound.mdx) policy
+whose completions allow list **starts with an OpenAI-compatible Azure
+deployment**. Without one the gateway answers `400`, asking for preselected
+routing, before reaching Azure.
+
+A Claude deployment doesn't work in that first slot, even though the allow list
+accepts it—Claude doesn't serve Responses at all, so the request still fails.
+
+Azure also takes a moment to make a new response readable. A `GET` immediately
+after a create can return `404` before it settles, so retry rather than treating
+the first `404` as final.
+
+Claude deployments don't serve Responses, so a Claude model on this endpoint
+fails with a `400` error—use
+[`/v1/messages`](#call-claude-models-on-the-messages-api) for those.
 
 Claude models work on `/v1/chat/completions` through the gateway's translation
 to the Messages API, which supports the core chat parameters: `messages`,
@@ -334,20 +368,27 @@ different beta still gets an answer, without that feature.
 The `model` field in a response doesn't always say what you might expect, and
 what it says depends on the model you called.
 
-**Claude responses report your deployment name.** Every other response reports
-Azure's own model ID, which usually carries a version date the short name
-doesn't.
+**Claude models and `/v1/responses` report your deployment name.** Everything
+else reports Azure's own model ID, which usually carries a version date the
+short name doesn't.
 
 | Endpoint               | Deployment `my-gpt` / `my-embed` / `my-claude` serves | `model` in the response   |
 | ---------------------- | ----------------------------------------------------- | ------------------------- |
 | `/v1/chat/completions` | `gpt-4.1-mini`                                        | `gpt-4.1-mini-2025-04-14` |
+| `/v1/responses`        | `gpt-4.1-mini`                                        | `my-gpt`                  |
 | `/v1/embeddings`       | `text-embedding-3-small`                              | `text-embedding-3-small`  |
 | `/v1/messages`         | `claude-haiku-4-5`                                    | `my-claude`               |
 | `/v1/chat/completions` | `claude-haiku-4-5`                                    | `my-claude`               |
 
+The same deployment reports two different values depending on the endpoint you
+call it on: chat completions answers with Azure's dated ID, Responses with the
+name you gave the deployment. That's Azure's own behavior on each surface, not
+something the gateway changes.
+
 A Claude model reports your deployment name on both endpoints—the native
-Messages API and the chat completions translation—because the gateway builds
-those responses itself and echoes back the model you asked for.
+Messages API and the chat completions translation—but for a different reason:
+there the gateway builds the response itself and echoes back the model you asked
+for.
 
 One exception, if you stream Claude: the `message_start` event reports Azure's
 ID (`claude-haiku-4-5-20251001`) rather than your deployment name, because the
@@ -388,8 +429,23 @@ resources deploy Claude. Confirm the deployment exists and is Anthropic-format,
 and see [Deploying Claude on Foundry](#deploying-claude-on-foundry) for the
 requirements Azure applies to those deployments.
 
-**A `400` error names `/v1/responses`.** The gateway doesn't serve the Responses
-API for Azure AI. Use `/v1/chat/completions`.
+**A `400` error names `/v1/responses`.** Two different causes, and the message
+tells you which. If it names the provider or the endpoint, the deployment is a
+**Claude** one—Claude doesn't serve Responses, so call
+[`/v1/messages`](#call-claude-models-on-the-messages-api) instead, or
+`/v1/chat/completions` for the translated form. If it says
+`The requested operation is unsupported`, that came from Azure: the deployed
+model doesn't serve Responses. Support is per model and version, so check
+Azure's Responses API model list—an embedding deployment always fails this way.
+
+**A `400` asks for preselected routing.** You called `GET` or `DELETE` on a
+response, or listed its input items. Those requests carry no body, so there is
+no `model` for the gateway to route on and it falls back to the app's first
+configured completions model. Add a
+[Model Filtering](../policies/ai-gateway-model-filtering-v2-inbound.mdx) policy
+to the app with an **OpenAI-compatible** Azure deployment first in its
+completions allow list. A Claude deployment in that slot still fails, since
+Claude doesn't serve Responses.
 
 **A model in the picker fails at request time.** The picker lists the full Azure
 catalog, but a model only works once you deploy it in your resource, and model

package/docs/ai-gateway/bedrock-mantle.mdx

@@ -72,9 +72,13 @@ either way.
 | ---------------------- | ---------------------------- | ------------- |
 | `/v1/chat/completions` | ✅ Forwarded                 | ✅ Translated |
 | `/v1/responses`        | ✅ Models that serve it      | ❌            |
-| `/v1/messages`         | ❌                           | ✅ Native     |
+| `/v1/messages`         | ❌                           | ✅ Forwarded  |
 | `/v1/embeddings`       | ❌ Mantle has no such models | ❌            |
 
+**Forwarded** means the gateway sends your request on in the shape you wrote it.
+**Translated** means it converts between two API shapes, which limits you to the
+parameters listed below.
+
 Streaming (`stream: true`) works on all three serving endpoints.
 
 On the OpenAI-compatible side, endpoint support is per model, decided by AWS:

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

@@ -10,6 +10,17 @@ You can configure [Claude Code](https://www.claude.com/product/claude-code) to
 send its model requests through the Zuplo AI Gateway, so the gateway
 authenticates, meters, and routes every Claude Code session.
 
+The gateway can authenticate to Anthropic in two ways. Pick one before you
+configure Claude Code:
+
+| Approach                                                  | The gateway sends Anthropic                                           | Claude Code sends the gateway                                             |
+| --------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| [Configured provider key](#use-a-configured-provider-key) | The Anthropic API key saved on your provider                          | The app's API key as `ANTHROPIC_AUTH_TOKEN`                               |
+| [Your Claude subscription](#use-your-claude-subscription) | The credential from your `claude.ai` login, such as a Claude Max plan | The app's API key in a `zp-gateway-api-key` header, plus your login as-is |
+
+Both approaches share the same provider, team, and app setup, and the same model
+configuration.
+
 ## Claude Code Setup
 
 <Stepper>
@@ -19,12 +30,18 @@ authenticates, meters, and routes every Claude Code session.
 
 2. [Set up a new team](../managing-teams.mdx)
 
-3. Create a [new app](../managing-apps.mdx) to use with Claude Code and assign
+3. If you plan to use your Claude subscription, configure the team's
+   [API Key Authentication policy](#configure-the-api-key-authentication-policy)
+   for passthrough before you create the app
+
+4. Create a [new app](../managing-apps.mdx) to use with Claude Code and assign
    it to the team you created
 
-4. Copy the **API URL** and **API Key** shown at the top of the app page
+5. Copy the **API URL** and **API Key** shown at the top of the app page
 
-5. Add the API key, gateway URL, and model mappings to `.claude/settings.json`
+6. Add the gateway URL, the app's API key, and model mappings to
+   `.claude/settings.json`, following the section below for the approach you
+   chose
 
 </Stepper>
 
@@ -45,7 +62,7 @@ The gateway routes every request using `providerName/model`. The provider prefix
 picks which of your providers handles the request — a gateway can contain
 several providers that serve Anthropic models.
 
-### Using settings.json
+### Where Claude Code reads its settings
 
 You can configure Claude Code either globally or per project by editing the
 settings file:
@@ -53,7 +70,24 @@ settings file:
 - **Global:** `~/.claude/settings.json`
 - **Project-specific:** `.claude/settings.json` in your project directory
 
-Add the following environment configuration to the settings file:
+Each approach below shows the `env` and `modelOverrides` blocks to add to that
+file. Restart Claude Code after saving it, and all your Claude Code LLM requests
+route through the AI Gateway.
+
+:::note
+
+Claude Code appends `/v1/messages` to the base URL itself, so
+`ANTHROPIC_BASE_URL` is the app's URL _without_ the `/v1` suffix.
+
+:::
+
+## Use a configured provider key
+
+With this approach the gateway calls Anthropic with the API key you saved on the
+[provider](../managing-providers.mdx). Claude Code presents only the app's API
+key, and Anthropic bills the account that owns the provider key.
+
+Add the following configuration to the settings file:
 
 ```json
 {
@@ -65,22 +99,155 @@ Add the following environment configuration to the settings file:
     "ANTHROPIC_DEFAULT_OPUS_MODEL": "anthropic/claude-opus-5",
     "ANTHROPIC_DEFAULT_SONNET_MODEL": "anthropic/claude-sonnet-5",
     "ANTHROPIC_DEFAULT_HAIKU_MODEL": "anthropic/claude-haiku-4-5",
-    "ANTHROPIC_DEFAULT_FABLE_MODEL": "anthropic/claude-fable-5"
+    "ANTHROPIC_DEFAULT_FABLE_MODEL": "anthropic/claude-fable-5-1"
+  },
+  "modelOverrides": {
+    "claude-opus-5": "anthropic/claude-opus-5",
+    "claude-sonnet-5": "anthropic/claude-sonnet-5",
+    "claude-haiku-4-5-20251001": "anthropic/claude-haiku-4-5-20251001",
+    "claude-fable-5-1": "anthropic/claude-fable-5-1"
   }
 }
 ```
 
-:::note
+`ANTHROPIC_AUTH_TOKEN` replaces whatever login Claude Code would otherwise use,
+so this approach doesn't consume your Claude subscription.
 
-Claude Code appends `/v1/messages` to the base URL itself, so
-`ANTHROPIC_BASE_URL` is the app's URL _without_ the `/v1` suffix.
+## Use your Claude subscription
 
-:::
+With this approach Claude Code stays signed in to `claude.ai` — for example with
+a Claude Max plan — and the gateway forwards that login credential to Anthropic
+as the request's provider credential. The app's API key travels in a separate
+`zp-gateway-api-key` header, so the gateway still authenticates the app, applies
+its policy chain, and meters its usage.
+
+Two pieces of configuration make this work: the app's **API Key Authentication**
+policy accepts the app key from the `zp-gateway-api-key` header and passes the
+`Authorization` header through, and Claude Code sends both headers.
+
+### Configure the API Key Authentication policy
+
+The [API Key Authentication](../../policies/ai-gateway-auth-v2-inbound.mdx)
+policy needs three options for passthrough:
+
+| Option                  | Value                | Effect                                                   |
+| ----------------------- | -------------------- | -------------------------------------------------------- |
+| `credentialPassthrough` | On                   | Forward the caller's `Authorization` header to Anthropic |
+| `authHeader`            | `zp-gateway-api-key` | Read the app's API key from this header instead          |
+| `authScheme`            | Empty value          | The header holds the bare key, with no `Bearer` prefix   |
+
+You can set these options on the team's
+[policy template](../policy-templates.mdx), so every app created in the team
+starts with passthrough enabled, or on a single app's **Policies** tab. The
+steps below use the team template; the app's policy editor works the same way.
+
+<Stepper>
 
-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.
+1. Open the team in the Zuplo Portal and select its **Policy Template** tab.
 
-### Configure every Claude Code model variable
+2. Click the edit (pencil) icon on the **API Key Authentication** entry.
+
+3. Turn on **credentialPassthrough**.
+
+4. Set **authHeader** to `zp-gateway-api-key`.
+
+5. Leave **authScheme** blank and click **Use an empty value for authScheme**.
+   The field then reports "Empty value set. The default (Bearer) is not
+   applied." Clearing the field alone isn't enough: a blank field omits the
+   option, so the `Bearer` default still applies and every request fails with
+   `401 Invalid Authorization Scheme`.
+
+6. Click **Apply**, then **Save changes**.
+
+</Stepper>
+
+The **JSON** editor mode shows the equivalent options:
+
+```json
+{
+  "credentialPassthrough": true,
+  "authHeader": "zp-gateway-api-key",
+  "authScheme": ""
+}
+```
+
+### The provider still needs an API key
+
+The Portal requires an API key to save an Anthropic provider, and passthrough
+requests never send it: the request to Anthropic carries the caller's credential
+instead. Anything else that uses this provider's configured credential still
+needs a real key. That includes apps on this gateway that don't use passthrough
+and any
+[Fallback Model](../../policies/ai-gateway-fallback-model-v2-inbound.mdx)
+target, because fallback requests use the provider's configured credential
+rather than the caller's. If nothing on the gateway uses the configured
+credential, a placeholder value works.
+
+The app's playground in the Portal sends the app key as a bearer token in
+`Authorization`, so it can't call an app that uses passthrough. Test the app
+from Claude Code instead, as described below.
+
+### Configure Claude Code
+
+Add the following configuration to the settings file. Don't set
+`ANTHROPIC_AUTH_TOKEN` or `ANTHROPIC_API_KEY` here or in your shell: either one
+replaces your `claude.ai` login, and the gateway would then forward that value
+to Anthropic as the credential.
+
+```json
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e",
+    "ANTHROPIC_CUSTOM_HEADERS": "zp-gateway-api-key: <your-ai-gateway-app-api-key>",
+    "ANTHROPIC_MODEL": "anthropic/claude-sonnet-5",
+    "ANTHROPIC_SMALL_FAST_MODEL": "anthropic/claude-haiku-4-5",
+    "ANTHROPIC_DEFAULT_OPUS_MODEL": "anthropic/claude-opus-5",
+    "ANTHROPIC_DEFAULT_SONNET_MODEL": "anthropic/claude-sonnet-5",
+    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "anthropic/claude-haiku-4-5",
+    "ANTHROPIC_DEFAULT_FABLE_MODEL": "anthropic/claude-fable-5-1"
+  },
+  "modelOverrides": {
+    "claude-opus-5": "anthropic/claude-opus-5",
+    "claude-sonnet-5": "anthropic/claude-sonnet-5",
+    "claude-haiku-4-5-20251001": "anthropic/claude-haiku-4-5-20251001",
+    "claude-fable-5-1": "anthropic/claude-fable-5-1"
+  }
+}
+```
+
+`ANTHROPIC_CUSTOM_HEADERS` adds the `zp-gateway-api-key` header to every request
+Claude Code makes, while Claude Code keeps sending its own `Authorization`
+header from your login. The gateway consumes those incoming headers, uses the
+login credential to authenticate the Anthropic request, and never sends your app
+key to Anthropic.
+
+### Verify the subscription setup
+
+Restart Claude Code, then confirm which credential it's using and send one
+request through the gateway:
+
+```bash
+claude auth status --text
+claude -p "Reply with the single word OK"
+```
+
+The first command should report that you're signed in with your `claude.ai`
+account rather than an API key or auth token. The second returns a short reply,
+and the request appears in the app's usage in the Zuplo Portal. In an
+interactive session, `/status` shows the same login information.
+
+If the request fails:
+
+- `401` with `Invalid Authorization Scheme` — `authScheme` still has its
+  `Bearer` default. Set it to an explicit empty value in the policy.
+- `401` with `Header configured by options.authHeader is missing` — Claude Code
+  didn't send `zp-gateway-api-key`. Check `ANTHROPIC_CUSTOM_HEADERS`.
+- `401` with `credentialPassthrough requires a non-empty Authorization header` —
+  Claude Code isn't signed in. Run `claude` and use `/login`.
+- An authentication error from Anthropic — Anthropic rejected the forwarded
+  login credential. Sign in to Claude Code again.
+
+## Configure every Claude Code model variable
 
 The model ids in these examples reflect what was current when this page was
 written, and ids differ across providers — a Bedrock provider serves different
@@ -91,23 +258,27 @@ it currently serves, and use those ids.
 None of Claude Code's built-in model names carry a provider prefix, so each of
 the model variables above must be set to a prefixed reference:
 
-- `ANTHROPIC_MODEL` — the main model. Required: without it Claude Code sends its
-  built-in default model unprefixed and the first request fails.
+- `ANTHROPIC_MODEL` — the startup model. Set it to a prefixed reference so the
+  gateway can route the first request.
 - `ANTHROPIC_SMALL_FAST_MODEL` — the model for background tasks.
 - `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`,
   `ANTHROPIC_DEFAULT_HAIKU_MODEL`, `ANTHROPIC_DEFAULT_FABLE_MODEL` — what the
   `opus`/`sonnet`/`haiku`/`fable` aliases resolve to, so `claude --model opus`
   and `/model sonnet` keep working. In these examples,
-  `ANTHROPIC_DEFAULT_FABLE_MODEL` maps `fable` to `anthropic/claude-fable-5`.
+  `ANTHROPIC_DEFAULT_FABLE_MODEL` maps `fable` to `anthropic/claude-fable-5-1`.
+
+Claude Code's `/model` picker can select either an alias or an exact model ID.
+`ANTHROPIC_DEFAULT_*_MODEL` maps aliases to gateway model names;
+[`modelOverrides`](https://code.claude.com/docs/en/model-config#override-model-ids-per-version)
+maps exact IDs. The examples configure both so either selection works through
+the gateway.
 
 :::caution{title='HTTP 400: model must use "providerName/model"'}
 
-If Claude Code fails immediately with
-`The request body model must use "providerName/model"`, the request carried a
-model name without a provider prefix. The tier alias variables
-(`ANTHROPIC_DEFAULT_*_MODEL`) alone don't prevent this — they don't cover Claude
-Code's built-in default model. Always set `ANTHROPIC_MODEL` to a prefixed model
-reference.
+This error means the selected model lacks its provider prefix. At startup, check
+`ANTHROPIC_MODEL`. After choosing a picker entry, check its `modelOverrides`
+entry, or type `/model fable` to use the configured alias. Restart Claude Code
+after editing the settings file.
 
 :::
 

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

@@ -0,0 +1,165 @@
+---
+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.
+---
+
+[GitHub Copilot](https://github.com/features/copilot) can use your own model
+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.
+
+## 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
+
+3. Create an [app](../managing-apps.mdx) for Copilot and assign it to the team
+
+4. Copy the **API URL** and **API Key** shown at the top of the app page
+
+</Stepper>
+
+The gateway names models as `providerName/model`, where `providerName` is the
+name you gave the provider. The examples below use `openai` and `anthropic`;
+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
+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_TYPE="openai"
+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
+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_TYPE="anthropic"
+export COPILOT_MODEL="anthropic/claude-sonnet-4-6"
+```
+
+The CLI speaks Chat Completions and the Messages API and sets a `temperature` on
+every request. GPT-4.1, GPT-4o, Claude Sonnet 4.6, and Claude Haiku 4.5 all
+accept that; OpenAI's GPT-5.x reasoning models and Claude Sonnet 5 don't, so use
+them from VS Code instead.
+
+## VS Code
+
+Add the gateway as a Custom Endpoint provider, then describe your models in the
+configuration file VS Code opens.
+
+<Stepper>
+
+1. Run **Chat: Manage Language Models** from the Command Palette
+
+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
+
+4. Select **Chat Completions** as the API type
+
+5. Replace the `models` array in the `chatLanguageModels.json` file that opens
+   with the models you want in the picker
+
+</Stepper>
+
+This configuration offers a GPT model and a Claude model from one app:
+
+```json
+[
+  {
+    "name": "Zuplo AI Gateway",
+    "vendor": "customendpoint",
+    "apiKey": "${input:chat.lm.secret.321f64a2}",
+    "models": [
+      {
+        "id": "openai/gpt-5.6",
+        "name": "GPT-5.6 (Zuplo)",
+        "apiType": "responses",
+        "url": "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1/responses",
+        "toolCalling": true,
+        "vision": true,
+        "maxInputTokens": 128000,
+        "maxOutputTokens": 16000,
+        "requestHeaders": { "Authorization": "Bearer ${apiKey}" }
+      },
+      {
+        "id": "anthropic/claude-sonnet-5",
+        "name": "Claude Sonnet 5 (Zuplo)",
+        "apiType": "messages",
+        "url": "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1/messages",
+        "toolCalling": true,
+        "vision": true,
+        "maxInputTokens": 200000,
+        "maxOutputTokens": 64000,
+        "requestHeaders": { "Authorization": "Bearer ${apiKey}" }
+      }
+    ]
+  }
+]
+```
+
+Three lines carry the integration:
+
+- **`apiKey`** is a reference to the key you pasted, which VS Code keeps in its
+  secret storage and reads at request time. Leave it as written; to change the
+  key, use **Chat: Manage Language Models**.
+- **`requestHeaders`** sends the key as `Authorization: Bearer <key>`, the
+  header the gateway's
+  [Authentication policy](../../policies/ai-gateway-auth-v2-inbound.mdx) reads.
+  VS Code's default header depends on the API type, so set it on every model.
+- **`apiType`** and the `url` path select the API the model speaks: `responses`
+  for OpenAI's reasoning models such as GPT-5.x, `messages` for Claude through
+  the gateway's native Messages passthrough, and `chat-completions` with a
+  `/v1/chat/completions` URL for other chat models. Set it on each model so
+  models with different APIs share one entry in the picker.
+
+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
+[Model Filtering](../../policies/ai-gateway-model-filtering-v2-inbound.mdx)
+policy decides which models Copilot may use.
+
+## Troubleshooting
+
+Copilot reports gateway errors as a retry failure, such as
+`502 token expired or invalid: 401`. The gateway's own response is in the
+**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             |

package/docs/ai-gateway/providers.mdx

@@ -38,7 +38,7 @@ The following capabilities are supported across providers:
 | Google                     | ✅               | ✅         | ❌        | ❌       |
 | Mistral                    | ✅               | ✅         | ❌        | ❌       |
 | xAI                        | ✅               | ✅         | ❌        | ❌       |
-| Azure AI                   | ✅               | ✅         | ❌        | ✅       |
+| Azure AI                   | ✅               | ✅         | ✅        | ✅       |
 | Bedrock Mantle             | ✅               | ❌         | ✅        | ✅       |
 | Vertex AI                  | ✅               | ✅         | ❌        | ✅       |
 | Zuplo Demo                 | ✅               | ❌         | ❌        | ❌       |
@@ -54,8 +54,12 @@ Messages (plus chat completions through translation), while its other models
 serve chat completions and—per model—Responses. See
 [Using Bedrock Mantle](./bedrock-mantle.mdx#supported-endpoints-by-model-family).
 
-Azure AI's Messages support needs a Microsoft Foundry resource, since Claude
-can't be deployed on an Azure OpenAI resource. Azure also addresses models by
+Azure AI's capabilities split by model family, and within the OpenAI-compatible
+family they split per deployed model: a chat model serves chat completions and—
+per model and version—Responses, while an embedding model serves embeddings and
+neither of the others. Claude serves Messages (plus chat completions through
+translation) and needs a Microsoft Foundry resource, since Claude can't be
+deployed on an Azure OpenAI resource. Azure also addresses models by
 **deployment name** rather than by published model ID, so a deployment named
 differently from the model it serves needs mapping for the gateway to price it.
 See [Using Azure AI](./azure-ai.mdx#azure-serves-deployments-not-model-names).
@@ -76,8 +80,8 @@ name you give the provider configuration. See the
 configuration covers both kinds of resource, and which capabilities apply
 depends on the resource and the model:
 
-- An **Azure OpenAI** resource deploys OpenAI models and serves chat completions
-  and embeddings.
+- An **Azure OpenAI** resource deploys OpenAI models and serves chat
+  completions, embeddings, and the Responses API.
 - A **Microsoft Foundry** resource serves those plus every Foundry model
   family—Grok, DeepSeek, Llama, Mistral, Phi, Kimi and more—and serves **Claude
   models** on the native Anthropic Messages API, with chat completions through

package/docs/ai-gateway/universal-api.mdx

@@ -67,5 +67,5 @@ list—so clients that can't set a model still work.
 | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `/v1/chat/completions` | Chat completions for every provider                                                                                                                             |
 | `/v1/embeddings`       | Embeddings for the providers marked in the [capability matrix](./providers.mdx#supported-providers)                                                             |
-| `/v1/responses`        | OpenAI Responses API: OpenAI, and [Bedrock Mantle](./bedrock-mantle.mdx) OpenAI-compatible models that serve it                                                 |
+| `/v1/responses`        | OpenAI Responses API: OpenAI, and the OpenAI-compatible models that serve it on [Azure AI](./azure-ai.mdx) and [Bedrock Mantle](./bedrock-mantle.mdx)           |
 | `/v1/messages`         | Anthropic Messages API: Anthropic, and the Claude models of [Azure AI](./azure-ai.mdx), [Bedrock Mantle](./bedrock-mantle.mdx) and [Vertex AI](./vertex-ai.mdx) |

package/docs/ai-gateway/vertex-ai.mdx

@@ -129,7 +129,12 @@ send your traffic and your spend to someone else's Google Cloud project.
 | `/v1/chat/completions` | ✅ Forwarded                   | ❌            |
 | `/v1/embeddings`       | ✅ Translated                  | ❌            |
 | `/v1/responses`        | ❌                             | ❌            |
-| `/v1/messages`         | ❌                             | ✅ Native     |
+| `/v1/messages`         | ❌                             | ✅ Forwarded  |
+
+**Forwarded** means the gateway sends your request on in the shape you wrote it.
+**Translated** means it converts between two API shapes—for embeddings, from the
+OpenAI shape onto Vertex's own embedding APIs, which is invisible from your
+side.
 
 Streaming (`stream: true`) works on chat completions and on Messages.