zuplo 7.8.7 → 7.8.9

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

@@ -1,98 +1,104 @@
 ---
 title: Codex
 sidebar_label: Codex
-description:
-  Configure the Codex CLI to send its requests through an AI Gateway app, either
-  by rerouting the built-in OpenAI provider or by adding a Zuplo provider.
+description: Route Codex CLI requests through a Zuplo AI Gateway app.
 ---
 
-[Codex](https://developers.openai.com/codex) is a coding agent developed by
-OpenAI that you can run locally from your terminal and that can read, modify,
-and run code on your machine, in the chosen directory. It’s open-source, and
-built in Rust for speed and efficiency.
+[Codex](https://developers.openai.com/codex) is OpenAI's coding agent for the
+terminal. This guide routes its requests through the Zuplo AI Gateway.
 
 ## Prerequisites
 
-In order to use the AI Gateway with Codex you will need to complete these steps
-first:
-
 <Stepper>
 
-1. Create a [new provider](../managing-providers.mdx) in the AI Gateway for the
-   provider you want to use with Codex
+1. Create a [provider](../managing-providers.mdx) in the AI Gateway.
 
-2. [Set up a new team](../managing-teams.mdx)
+2. [Create a team](../managing-teams.mdx).
 
-3. Create a [new app](../managing-apps.mdx) to use specifically with Codex and
-   assign it to the team you created
+3. [Create an app](../managing-apps.mdx) for Codex and assign it to the team.
 
-4. Copy the **API URL** and **API Key** shown at the top of the app page
+4. Copy the **API URL** and **API Key** from the app page.
 
 </Stepper>
 
-## Configure Codex CLI
-
-There are two approaches you can take to using Codex with Zuplo's AI Gateway.
-
-1. **Route OpenAI through AI Gateway** - This would configure your OpenAI
-   provider in Codex to route requests through the AI Gateway rather than
-   directly to OpenAI
+## Configure Codex
 
-2. **Create a Zuplo specific provider** - Use Zuplo as a provider that be
-   selected in the Codex configuration and work with any OpenAI compatible
-   models
+:::warning{title="Replace the provider name"}
 
-Configuration steps for both options are below:
+The examples assume your provider is named `openai`. Replace that prefix with
+the name of **your** provider before copying anything. A provider named
+`my-openai` routes `my-openai/gpt-5`. The model part must be an ID that provider
+serves. Check [your provider's page](../managing-providers.mdx) in the Portal.
 
-### Route OpenAI through AI Gateway
+:::
 
-Open the [Codex configuration](https://developers.openai.com/codex/local-config)
-`~/.codex/config.toml` and modify the `model_providers.openai-chat-completions`
-entry so that the `base_url` points to your app's API URL with `/v1` appended,
-and set your `env_key` to the API Key of the app you created to use with Codex.
-The app page in the Zuplo Portal shows the API URL, which ends in the app's ID.
+Codex reads configuration from `~/.codex/config.toml`. Create this file (and the
+`~/.codex` directory if needed) if it does not exist. Add the following:
 
 ```toml
-[model_providers.openai-chat-completions]
-name = "OpenAI using Chat Completions"
+model_provider = "zuplo"
+model = "openai/gpt-5"
+
+[model_providers.zuplo]
+name = "Zuplo AI Gateway"
 base_url = "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1"
 env_key = "ZUPLO_AI_GATEWAY_API_KEY"
+wire_api = "responses"
 ```
 
-Save the file and reload Codex. Your OpenAI requests will now be routed through
-the Zuplo AI Gateway.
+- `base_url` is the app's API URL with `/v1` appended.
+- `model` is `providerName/model`.
 
-### Zuplo AI Gateway provider
+Set the API key in your environment:
 
-To add a specific provider for the AI Gateway you can add an additional entry to
-the Codex `config.toml` file.
-
-```toml
-[model_providers.zuplo]
-name = "Zuplo AI Gateway"
-base_url = "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1"
-env_key = "ZUPLO_AI_GATEWAY_API_KEY"
+```bash
+export ZUPLO_AI_GATEWAY_API_KEY="<your-app-api-key>"
 ```
 
-Save the file and reload Codex. Your Zuplo AI Gateway provider will now be
-available and you can switch Codex over to use it at any time by running:
+Restart Codex. All requests now go through the gateway.
+
+### Rules
+
+- `model_provider = "zuplo"` is required. Without it, Codex uses its built-in
+  `openai` provider and bypasses the gateway.
+- `wire_api` must be `responses`. Codex speaks only the Responses API; it
+  [removed](https://github.com/openai/codex/discussions/7782) support for
+  `/v1/chat/completions`, and `wire_api = "chat"` fails to load.
+- Put this configuration in the user-level file. Codex ignores `model_provider`
+  and `model_providers` in a project-level `.codex/config.toml`.
+
+## Switch models
+
+Set `model` in `config.toml`, or pass it on the command line:
 
 ```bash
-codex --config model_provider="zuplo"
+codex --config model_provider="zuplo" --model "openai/gpt-5.6-sol"
 ```
 
-### Choosing a model
+Do not use the `/model` picker. It sends model names without the provider
+prefix, and the gateway rejects them with a `400`.
+
+Codex warns that it has no metadata for a prefixed model name. Requests still
+succeed.
 
 The app's
 [Model Filtering](../../policies/ai-gateway-model-filtering-v2-inbound.mdx)
-policy controls which models the app may use. Codex names the model as
-`providerName/model`, where `providerName` is the provider name configured in
-your gateway:
+policy controls which models the app can use.
+
+## Verify
 
 ```bash
-codex --config model_provider="zuplo" --model "openai/gpt-5"
+codex exec "Reply with the single word OK"
 ```
 
-A request with no model, or a model without that prefix, gets a `400`. Adding
-[Model Filtering](../../policies/ai-gateway-model-filtering-v2-inbound.mdx) with
-an allow list also supplies a default, letting requests omit the model.
+The session header shows `provider: zuplo`. The request appears in the app's
+usage in the Zuplo Portal.
+
+## Troubleshooting
+
+| Error                                                                                      | Fix                                                                 |
+| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
+| `400` `The request body model must use "providerName/model"`                               | Add the provider prefix to `model`. Do not use the `/model` picker. |
+| `ERROR: Missing environment variable: ZUPLO_AI_GATEWAY_API_KEY`                            | Export the variable in the shell that runs Codex.                   |
+| `401` `Authorization Failed`                                                               | The API key is wrong. Copy it from the app's **API Key** tab.       |
+| Errors mention `api.openai.com` or `not supported when using Codex with a ChatGPT account` | Codex is not using your provider. Set `model_provider = "zuplo"`.   |

package/docs/ai-gateway/usage-limits.mdx

@@ -357,8 +357,8 @@ Each app, team, and the gateway show current usage against their limits:
 
 ## Related Resources
 
-- [Getting Started](./getting-started.mdx) - Set up your first AI Gateway
-  project with budget controls
+- [Getting Started](../getting-started/ai-gateway/portal.mdx) - Set up your
+  first AI Gateway project with budget controls
 - [Managing Teams](./managing-teams.mdx) - Configure team-level budgets
 - [Managing Apps](./managing-apps.mdx) - Configure app-level limits
 - [Fallback Models](./fallback.mdx) - Serve a cheaper model instead of blocking

package/docs/api-management/overview.md

@@ -11,8 +11,8 @@ designed for developers. It offers fast deployment, GitOps-friendly workflows,
 and unlimited environments. Whether you're an individual developer or part of an
 engineering team, Zuplo makes it easy to:
 
-- [Add authentication and access control](../articles/step-3-add-api-key-auth.mdx)
-- [Implement rate limiting](../articles/step-2-add-rate-limiting.mdx)
+- [Add authentication and access control](../getting-started/gateway/add-api-key-auth/index.mdx)
+- [Implement rate limiting](../getting-started/gateway/add-rate-limiting/index.mdx)
 - Write custom logic to run at the gateway layer
 - Build a [rich developer portal](../dev-portal/overview.mdx) with self-serve
   tools for auth and monetization

package/docs/articles/add-api-to-backstage.mdx

@@ -26,9 +26,10 @@ Add a new route with the path `/openapi`, and select the `OpenAPI Spec Handler`
 from the Request Handler selector. Save your changes and commit them to your
 production branch. If you haven't already connected your Zuplo API to a GitHub
 repository, you can follow
-[these instructions](./step-4-deploying-to-the-edge.mdx) to do so. Once your
-Zuplo API is redeployed, you should now be able to retrieve your public-ready
-OpenAPI file by hitting `https://<your-prod-zuplo-api-domain>/openapi`.
+[these instructions](../getting-started/gateway/deploy-to-the-edge/index.mdx) to
+do so. Once your Zuplo API is redeployed, you should now be able to retrieve
+your public-ready OpenAPI file by hitting
+`https://<your-prod-zuplo-api-domain>/openapi`.
 
 ![Zuplo route](../../public/media/add-api-to-backstage/image-3.png)
 

package/docs/articles/api-key-consumer-bucket-portal-ui.mdx

@@ -23,7 +23,7 @@ managers), see [Manage Keys in the Portal](./api-key-administration.mdx).
 ## Prerequisites
 
 - A Zuplo project with at least one deployed environment (see the
-  [getting started tutorial](./step-1-setup-basic-gateway.mdx))
+  [getting started tutorial](../getting-started/gateway/setup-a-basic-gateway/index.mdx))
 - The [API Key Authentication policy](../policies/api-key-inbound.mdx)
   configured on your routes
 - Permission to manage API key consumers in your project

package/docs/articles/api-key-management.mdx

@@ -11,7 +11,7 @@ your backend.
 :::tip
 
 To start using Zuplo API Keys in only a few minutes
-[see the quickstart](../articles/step-3-add-api-key-auth.mdx).
+[see the quickstart](../getting-started/gateway/add-api-key-auth/index.mdx).
 
 :::
 

package/docs/articles/custom-domains.mdx

@@ -22,8 +22,9 @@ Zuplo supports two types of custom domains that can be configured separately:
    `cname.zuplodocs.com`. Learn more about the Developer Portal in the
    [Developer Portal documentation](/docs/dev-portal/overview).
 
-Both types of custom domains can be managed from the same Custom Domains section
-in your project settings and follow a similar configuration process.
+Manage both types of custom domains in
+[**Account Settings → Custom Domains**](https://portal.zuplo.com/+/account/settings/custom-domains).
+They follow a similar configuration process.
 
 :::note
 

package/docs/articles/migrate-from-apigee.md

@@ -401,8 +401,8 @@ between both gateways.
 
 ## Next steps
 
-- [Set up your first Zuplo gateway](./step-1-setup-basic-gateway.md)
-- [Add rate limiting](./step-2-add-rate-limiting.md)
-- [Add API key authentication](./step-3-add-api-key-auth.md)
+- [Set up your first Zuplo gateway](../getting-started/gateway/setup-a-basic-gateway/index.mdx)
+- [Add rate limiting](../getting-started/gateway/add-rate-limiting/index.mdx)
+- [Add API key authentication](../getting-started/gateway/add-api-key-auth/index.mdx)
 - [Configure your developer portal](../dev-portal/overview.mdx)
 - [Set up source control](./source-control.md)

package/docs/articles/migrate-from-aws-api-gateway.md

@@ -241,8 +241,8 @@ secrets to secure the connection between Zuplo and your AWS backends.
 
 ## Next steps
 
-- [Set up your first Zuplo gateway](./step-1-setup-basic-gateway.md)
-- [Add rate limiting](./step-2-add-rate-limiting.md)
-- [Add API key authentication](./step-3-add-api-key-auth.md)
+- [Set up your first Zuplo gateway](../getting-started/gateway/setup-a-basic-gateway/index.mdx)
+- [Add rate limiting](../getting-started/gateway/add-rate-limiting/index.mdx)
+- [Add API key authentication](../getting-started/gateway/add-api-key-auth/index.mdx)
 - [Configure your developer portal](../dev-portal/overview.mdx)
 - [Set up source control](./source-control.md)

package/docs/articles/migrate-from-azure-apim.md

@@ -285,8 +285,8 @@ connection between Zuplo and your Azure backends.
 
 ## Next steps
 
-- [Set up your first Zuplo gateway](./step-1-setup-basic-gateway.md)
-- [Add rate limiting](./step-2-add-rate-limiting.md)
-- [Add API key authentication](./step-3-add-api-key-auth.md)
+- [Set up your first Zuplo gateway](../getting-started/gateway/setup-a-basic-gateway/index.mdx)
+- [Add rate limiting](../getting-started/gateway/add-rate-limiting/index.mdx)
+- [Add API key authentication](../getting-started/gateway/add-api-key-auth/index.mdx)
 - [Configure your developer portal](../dev-portal/overview.mdx)
 - [Set up source control](./source-control.md)

package/docs/articles/migrate-from-kong.md

@@ -293,8 +293,8 @@ configuration-as-code. Zuplo takes this further with native GitOps:
 
 ## Next steps
 
-- [Set up your first Zuplo gateway](./step-1-setup-basic-gateway.md)
-- [Add rate limiting](./step-2-add-rate-limiting.md)
-- [Add API key authentication](./step-3-add-api-key-auth.md)
+- [Set up your first Zuplo gateway](../getting-started/gateway/setup-a-basic-gateway/index.mdx)
+- [Add rate limiting](../getting-started/gateway/add-rate-limiting/index.mdx)
+- [Add API key authentication](../getting-started/gateway/add-api-key-auth/index.mdx)
 - [Configure your developer portal](../dev-portal/overview.mdx)
 - [Set up source control](./source-control.md)

package/docs/articles/source-control-setup-github.mdx

@@ -11,8 +11,8 @@ configuration required.
 
 This guide assumes you have a Zuplo project created. If you don't have one yet,
 follow the steps in
-[Step 1 - Setup a Basic Gateway](./step-1-setup-basic-gateway.mdx) to create a
-new Zuplo project.
+[Step 1 - Setup a Basic Gateway](../getting-started/gateway/setup-a-basic-gateway/index.mdx)
+to create a new Zuplo project.
 
 <Stepper>
 

package/docs/articles/source-control.mdx

@@ -65,9 +65,10 @@ If your code lives elsewhere but you want to use a specific CI/CD system:
 
 ## How Branch-Based Deployments Work
 
-Every Git branch maps to a Zuplo environment. Push to `main` and deploy to your
-main environment. Push to `feature-auth` and get a `feature-auth` environment
-automatically.
+With the GitHub integration, every Git branch maps to a Zuplo environment. Push
+to `main` and deploy to your main environment. Push to `feature-auth` and get a
+`feature-auth` environment automatically. For other providers, configure your
+CI/CD pipeline to deploy each branch.
 
 This enables powerful workflows like PR preview environments where reviewers can
 test changes against a live API before merging.

package/docs/articles/testing.mdx

@@ -140,11 +140,11 @@ and the same file supplies fixture values to `zuplo test`. See
 
 ## Test before merge
 
-Every branch pushed to your connected source control provider deploys as a
-preview environment: a full Zuplo deployment on the same edge network as
-production, at its own URL. Running your suite there is the highest-fidelity
-check available before a change merges, and it needs no shared staging
-environment.
+With the GitHub integration, pushing a feature branch automatically creates a
+preview environment at its own URL. For GitLab, Bitbucket, or Azure DevOps,
+configure a [CI/CD pipeline](./custom-ci-cd.mdx) to deploy the branch. Running
+your suite against a preview deployment lets you test changes before merging
+without a shared staging environment.
 
 - [Testing preview environments](./testing-preview-environments.mdx) — getting
   the URL into your tests, per-environment services and secrets, and what to

package/docs/articles/upstream-iam-auth.mdx

@@ -19,8 +19,8 @@ identity provider you control. For the alternatives, see
 
 ## Federated identity or stored credentials
 
-Every provider offers two paths, and the choice matters more than which cloud
-you're on.
+Zuplo offers federated identity and stored-credential policies. The available
+options depend on your cloud provider, as shown in the policy table below.
 
 **Federated identity** is the stronger option. Zuplo presents a short-lived,
 audience-bound OIDC token that proves which gateway is calling, and your cloud

package/docs/cli/create-zuplo-api.mdx

@@ -42,7 +42,7 @@ npx create-zuplo-api@latest
   (`claude`, `copilot`, `cursor`, `windsurf`, `codex`), or `none` to skip agent
   setup. See [Configuring AI coding agents](#configuring-ai-coding-agents)
 - `--template <template-name>` - A built-in template to bootstrap the API with
-  (`default`, `default-empty`, or `ai-gateway-v2`). Can't be combined with
+  (`default`, `default-empty`, or `ai-gateway`). Can't be combined with
   `--example` or `--empty`. See [Choosing a template](#choosing-a-template)
 - `-e, --example <example-name|github-url>` - An example to bootstrap the API
   with. You can use an example name from the official Zuplo repository or a
@@ -88,18 +88,18 @@ flag you get the `default` template.
 | --------------- | --------------------------------------------------------------------------------------------- |
 | `default`       | Sample `/todos` routes, a `hello-world` module, a dev portal in `docs/`, and VS Code settings |
 | `default-empty` | The same project with no routes defined and no VS Code settings                               |
-| `ai-gateway-v2` | An [AI Gateway](../ai-gateway/overview.mdx) project, without a dev portal                     |
+| `ai-gateway`    | An [AI Gateway](../ai-gateway/overview.mdx) project, without a dev portal                     |
 
 `--empty` is shorthand for `--template default-empty`.
 
-The `ai-gateway-v2` template scaffolds `config/ai.oas.json`, which routes
+The `ai-gateway` template scaffolds `config/ai.oas.json`, which routes
 `/:app_id/v1/*` to the AI Gateway handler, and `config/policies.json`, which
 declares the policies an application's policy chain can select. It ships no
 `docs/` directory, so the CLI skips the
 [dev portal](../dev-portal/overview.mdx) workspace:
 
 ```bash
-npx create-zuplo-api@latest my-gateway --template ai-gateway-v2
+npx create-zuplo-api@latest my-gateway --template ai-gateway
 ```
 
 `--template` names a built-in template, which is why it can't be combined with

package/docs/cli/openapi-merge.mdx

@@ -125,7 +125,7 @@ To rename the destination file, use the `--destination` option.
 ```bash
 zuplo openapi merge \
   --source https://example.com/path/to/openapi.json \
-  --destination new-name
+  --destination ./config/new-name.oas.json
 ```
 
 </CliCommand>

package/docs/cli/openapi-merge.partial.mdx

@@ -25,5 +25,5 @@ To rename the destination file, use the `--destination` option.
 ```bash
 zuplo openapi merge \
   --source https://example.com/path/to/openapi.json \
-  --destination new-name
+  --destination ./config/new-name.oas.json
 ```

package/docs/concepts/ai-gateway.mdx

@@ -64,7 +64,7 @@ are the same ones described in [How Zuplo Works](./how-zuplo-works.mdx).
 
 ## Next steps
 
-- [Get started with the AI Gateway](../ai-gateway/getting-started.mdx)
+- [Get started with the AI Gateway](../getting-started/ai-gateway/portal.mdx)
 - [Browse the SDK integrations](../ai-gateway/integrations/openai.mdx) for
   OpenAI, the Vercel AI SDK, LangChain, Claude Code, Codex, and Goose
 - Explore the [AI Gateway policies](../ai-gateway/policies/overview.mdx)

package/docs/concepts/how-zuplo-works.mdx

@@ -87,7 +87,8 @@ workflow is:
 
 1. **Develop** locally or in the Zuplo Portal
 2. **Push** to your Git repository (GitHub, GitLab, Bitbucket, or Azure DevOps)
-3. **Deploy** automatically - Zuplo builds and deploys your gateway globally
+3. **Deploy** automatically with the GitHub integration, or configure a CI/CD
+   pipeline to deploy from GitLab, Bitbucket, or Azure DevOps
 
 Deployments complete in seconds. Each Git branch gets its own isolated
 environment with its own URL, making it easy to test changes before merging to

package/docs/concepts/mcp.mdx

@@ -55,9 +55,9 @@ apply to any other route.
 
 ## Next steps
 
-- [MCP Gateway quickstart](../mcp-gateway/quickstart.mdx) — expose an upstream
-  MCP server and connect Claude Desktop
-- [MCP quickstart for the MCP Server handler](../articles/mcp-quickstart.mdx) —
-  turn an API into MCP tools
+- [MCP Gateway quickstart](../getting-started/mcp-gateway/portal.mdx) — expose
+  an upstream MCP server and connect Claude Desktop
+- [MCP quickstart for the MCP Server handler](../getting-started/mcp-server/portal.mdx)
+  — turn an API into MCP tools
 - [Connect MCP clients](../mcp-gateway/connect-clients/overview.mdx) — Claude,
   ChatGPT, Cursor, VS Code, and others

package/docs/dedicated/architecture.mdx

@@ -19,7 +19,7 @@ A managed dedicated instance of Zuplo consists of the following components:
   authorization, rate limiting, and other features.
 - **Gateway Services**: Zuplo, being a highly distributed gateway, uses services
   to facilitate features such as
-  [Rate Limiting](../articles/step-2-add-rate-limiting.mdx) and
+  [Rate Limiting](../getting-started/gateway/add-rate-limiting/index.mdx) and
   [API Key Authentication](../articles/api-key-management.mdx).
 - **Control Plane**: The Control Plane manages the configuration of the Zuplo
   Gateway. It deploys new configurations, manages the lifecycle of the Zuplo

package/docs/dev-portal/migration.mdx

@@ -125,8 +125,8 @@ process, continue with the manual migration steps below.
 
    :::caution
 
-   Currently, this migration must be done locally. It cannot be done in the
-   Zuplo Portal.
+   Follow these manual migration steps locally. To migrate in the Zuplo Portal,
+   use the [built-in migration tool](#migrate-in-the-portal).
 
    :::
 

package/docs/errors/not-found.mdx

@@ -40,4 +40,4 @@ response when no route matches. See
 ## Related resources
 
 - [Routes Designer](../articles/local-development-routes-designer.mdx)
-- [Deploying to the Edge](../articles/step-4-deploying-to-the-edge.mdx)
+- [Deploying to the Edge](../getting-started/gateway/deploy-to-the-edge/index.mdx)