Copy page

Documentation

Version Support Policy

Applies to

Gatewayruntime for API, AI, and MCP gateways

Hosting

Managed EdgeManaged DedicatedSelf-Hosted

Zuplo runs production traffic for its customers, so backward compatibility is a design constraint rather than an aspiration. This document describes how Zuplo versions each part of the platform, what counts as a breaking change, and what support window applies.

At a glance

What counts as a breaking change

The compatibility promise focuses on the parts of Zuplo that a production API depends on. Other parts of the platform, such as diagnostics and tooling, keep improving between releases.

Breaking changes

Zuplo treats these as breaking and gates them behind a compatibility date:

• Request handling. A change that materially affects how the gateway handles a request: which policies and handlers run and in what order, the status code, headers, or body a client receives, how a request is routed, validated, authenticated, rate limited, or forwarded.
• Exported code APIs. The documented, public exports of @zuplo/runtime that custom code imports, such as ZuploRequest, ZuploContext, and HttpProblems. Removing an export, changing a signature, or changing what a documented API returns is breaking.
• Configuration. A change that makes a valid zuplo.jsonc, route file, or policy configuration fail to build, or that changes what an existing option does. Stricter validation of invalid configuration is covered separately below.

Not breaking changes

These can change from release to release without a compatibility date. Tests and integrations hold up best when they don't depend on them:

• Error messages. The human-readable text of errors throughout Zuplo, in runtime responses, build and deployment output, and the CLI, can be reworded, expanded, or localized. For example, the title and detail fields of a Problem Details response can change. Match on stable identifiers such as the status code and the problem type instead.
• Additive changes. New APIs, new policies, new optional configuration properties, new response headers, and new fields in a response body or a Problem Details object. Clients and tests should ignore fields and headers they don't recognize.
• Logs, traces, and metrics. Log messages and their wording, which operations emit logs or spans, span names and attributes, and which metrics and analytics Zuplo collects all change over time. New log entries appear and existing ones change, so avoid parsing log text to drive automation.
• Local development. The local development experience, including zuplo dev, the local Route Designer, and locally mocked or emulated services, changes as the tooling improves. Behavior in local development can differ from a deployed gateway. Treat a preview environment as the source of truth for production behavior.
• Undocumented behavior and internal APIs. Anything not described in the documentation: exports not documented as public, imports from internal paths of a Zuplo package, internal headers, and incidental behavior such as the order of headers or the exact timing of a request.
• Performance. Latency, memory use, and throughput improve or shift between releases. Platform limits are documented separately.
• Stricter build validation. Zuplo continues to add checks that catch invalid configuration and code at build time instead of at request time. For example, a policy that's misconfigured so that it fails on every request might build and deploy today, then fail the build after a new check ships. Catching these problems before deployment keeps them out of production, though it means a project that built before can occasionally need a fix to build again. The build error explains what's wrong and how to fix it.

Gateway runtime

Runtime versions don't change behavior

The version of the Zuplo runtime a project builds against doesn't determine how that project behaves. Zuplo ships runtime updates continuously, and every release runs against an extensive automated test suite covering the request lifecycle, policies, handlers, and the programmable API. A newer runtime brings fixes, performance improvements, and new APIs. It doesn't change how existing routes, policies, and handlers behave.

Behavior changes are gated by compatibility dates instead.

Compatibility dates

A compatibility date locks in the behavior of the runtime as of a specific day. When a change would alter existing behavior, Zuplo puts that change behind a new compatibility date. Projects keep the previous behavior until they opt in by raising the date in zuplo.jsonc:

Code
{
  "version": 1,
  "compatibilityDate": "2026-03-01",
}

New projects default to a recent compatibility date. Existing projects stay on the date they set until someone changes it. Zuplo supports each compatibility date for at least 12 months after it's released, and likely much longer. To date, Zuplo hasn't retired any compatibility date.

Every compatibility date and the behavior it changes is documented in Compatibility Dates. Each entry describes the old behavior, the new behavior, and the migration required.

Compatibility flags

Each behavior change in the runtime is implemented as a compatibility flag. A compatibility date is a named set of flags: setting a date turns on every flag that shipped with that date or an earlier one. Flags only ever turn new behavior on. A project can't use a flag to turn off a behavior that its compatibility date includes.

Zuplo occasionally ships a flag before it belongs to any compatibility date, to resolve a specific customer issue or bug ahead of the next date. A project can turn on such a flag with compatibilityFlags in zuplo.jsonc.

Until a flag becomes part of a compatibility date, it's considered unstable:

• Its behavior can change between releases while the change is refined.
• It can be removed. When a flag's behavior becomes standard or moves to another flag, listing the old flag fails the build with a message explaining what to use instead.
• Stability guarantees apply to compatibility dates only. While a project sets any compatibilityFlags, the guarantees on this page don't apply to it, even when the flags it sets are already part of its compatibility date.

When a flag becomes part of a compatibility date, raise the date and remove the flag from zuplo.jsonc. Setting the date is the supported way to get the behavior.

Exceptions to the compatibility promise

Zuplo works to avoid breaking changes, and gates every change it can behind a compatibility date. In three situations, a change may need to ship outside a compatibility date. Even then, Zuplo keeps the change as small as possible and lets affected customers know.

Security

Protecting customer traffic comes first. To close a vulnerability, Zuplo may change runtime behavior without a compatibility date, even when the fix affects how some existing projects behave.

Zuplo scopes these changes as narrowly as the vulnerability allows and communicates them as directly as responsible disclosure permits. For Zuplo's security practices and how to report a vulnerability, see Security.

Protocol correctness

Some parts of the gateway implement specifications Zuplo doesn't control — most visibly the Model Context Protocol (MCP), along with OAuth, OpenID Connect, OpenAPI, JSON Schema, and HTTP itself. Zuplo aims to implement these specifications correctly, because correct behavior is what keeps the gateway working with the clients and servers customers depend on.

These features follow the lifecycle of the specification:

• Specification revisions. When a specification deprecates or removes a revision, Zuplo eventually ends support for that revision in line with the specification's deprecation policy.
• Specification changes. When a specification changes in a way that can't be both backward compatible and compliant, Zuplo follows the specification.
• Conformance fixes. From time to time, Zuplo finds a bug or behavior that's inconsistent with a specification. Zuplo fixes these so the gateway behaves as the specification describes.

Where a protocol change can be gated, Zuplo gates it. The MCP Gateway, for example, requires a compatibility date of 2026-03-01 or later — see MCP Gateway compatibility dates.

Official SDK dependencies

Some features are built on an official SDK for a protocol rather than a Zuplo implementation. For example, the MCP Server and MCP Gateway use the official MCP SDK for parts of their protocol handling.

When Zuplo updates an SDK to pick up a new protocol revision, a security fix, or a bug fix, behavior that comes from the SDK can change with it. SDK-driven changes follow the SDK's own release cycle rather than Zuplo's compatibility dates, and Zuplo calls out notable ones in the changelog.

MCP is evolving quickly, so the MCP Gateway and MCP Server track new protocol revisions and SDK releases as they publish. Testing MCP integrations against a preview environment before each production deployment is the best way to catch a change early.

Changes take effect when you deploy

Zuplo doesn't rebuild or redeploy a running gateway on your behalf. A new runtime, a raised compatibility date, or an updated dependency reaches an environment only when you deploy to it — by pushing to the branch that environment tracks, or by running zuplo deploy.

Two things follow from this:

• Timing is yours. Nothing changes underneath a production environment between deployments.
• Every upgrade is testable first. Preview environments deploy from a branch, so a runtime or compatibility date change runs on real infrastructure before it reaches production.

Because deployments are the moment behavior can change, Zuplo strongly recommends a comprehensive test suite that gates every deployment. The zuplo test command runs the same tests locally, against preview environments, and in CI/CD. See Testing Your API for the recommended setup.

Developer Portal

The Developer Portal is a web application built on Zudoku, and it evolves rapidly. Zuplo minimizes breaking changes where practical, but the UI, components, and configuration surface change over time. There's no long-term support release for the Developer Portal.

The supported version is the current version:

• Fixes ship in new versions. Bug fixes and security fixes are released in a new version of the zudoku package.
• Nothing is backported. Fixes aren't applied to older versions, including security fixes.
• Upgrading is how you pick up a fix. A project pinned to an old version stays on the behavior — and the bugs — of that version.

Stay on a recent version and upgrade in small, frequent increments rather than large jumps. Run npm install zudoku@latest in your project's /docs directory and test locally before deploying. See Updating Versions for the full process, and the Zudoku release notes for updates that need more than a dependency bump.

Breaking changes and notice

When Zuplo introduces a breaking change:

• Changes are communicated. Zuplo announces breaking changes through the changelog and documentation, and contacts affected customers directly where the impact is identifiable.
• Compatibility dates carry the change where possible. Gating a runtime change behind a compatibility date leaves the timing of adoption to you.
• The upgrade path is documented. Compatibility date entries and migration guides describe what changes and what to do about it.
• Enterprise customers get dedicated assistance. Customers on an enterprise plan work directly with the Zuplo team on upgrade planning, testing, and rollout. See Support.

For security, protocol, and SDK changes, the timing of notice depends on the situation, such as responsible disclosure for a vulnerability. See Exceptions to the compatibility promise.

Related resources

• Compatibility Dates — every runtime behavior change and the date that gates it
• Project Configuration (zuplo.jsonc) — where the compatibility date is set
• Testing Your API — local, preview, and CI/CD testing
• Problem Details Helper — the error format to assert on in tests
• Branch-Based Deployments — how branches map to environments
• Updating Versions — upgrading the Developer Portal
• Security — security practices and vulnerability reporting
• Support — support plans, contact methods, and response times