AISIX 1.0.0

Release date: September 4, 2026

This release makes guardrail behavior visible and configurable at the point where operators need to tune it. Semantic guardrails report the similarity they measured, the console can test a saved rule before it is attached to production traffic, and fail-open decisions are recorded consistently across the gateway. The release also applies one client-header forwarding contract to model routes, MCP servers, passthrough routes, and Realtime, improves reasoning controls across provider protocols, and makes routing and configuration failures easier to diagnose.

Behavior Changes

• Model cooldown is now opt-in. A direct model with no cooldown block, or with a block whose enabled field is omitted, is no longer taken out of rotation after request failures. Set cooldown.enabled: true to retain the previous behavior; the default timeout and trigger settings inside an enabled block are unchanged. This is a breaking behavior change for existing models that relied on cooldown without enabling it explicitly.

• Guardrails no longer scan the Files API as one opaque blob. Upload bodies, upload responses, and file downloads under /v1/files now pass without input or output guardrail evaluation. The former whole-file scan could neither evaluate individual JSONL records nor write masked content back to the multipart body; it also decoded binary files with replacement characters. The request envelopes on /v1/batches and /v1/fine_tuning/jobs remain guarded; per-record file screening is not part of this release.

• A body the gateway cannot scan now follows the guardrail that governs that side. The gateway refuses unreadable content only when at least one guardrail in scope both reads that side of the exchange and fails closed on it. A chain that does not read that side does not cause a refusal, and the request continues with an unscannable_body record when every relevant guardrail is fail-open. The fail_open setting now applies to keyword and pii guardrails as well as remote guardrails. Held-back streamed output remains fail-closed when nothing scannable can be recovered, because the alternative would release buffered bytes that no guardrail evaluated.

• Audio transcription and translation responses that cannot be decoded now honor the output failure policy. With an output guardrail that fails closed, such a plain-text transcript returns 422 content_filter with guardrail_unavailable; with a fail-open guardrail, the original bytes are relayed and the bypass is recorded. Transcript content that can be decoded is still scanned.

• Unsupported streaming requests fail before reaching the provider. A request with stream: true to /v1/completions or /v1/images/generations now returns 400 invalid_request_error. These endpoints do not relay streaming responses; previously they sent the request upstream, could repeat billable work through the retry budget, and eventually returned a decode-related 502.

• Guardrail scope now treats reasoning by who supplied it. Reasoning content replayed by the caller is input and is scanned on Chat Completions, Responses, and Anthropic Messages, while reasoning generated by the model remains outside output scanning. Anthropic signed thinking blocks are inspected by block actions but are not rewritten by mask actions, because clients must replay those signed bytes unchanged.

• Streaming error events now use their endpoint's native envelope. Guardrail errors on /v1/messages streams use Anthropic's invalid_request_error type, and /v1/responses emits flat Responses API error events with top-level code, message, param, and sequence_number fields. HTTP error envelopes are unchanged.

• New release images use immutable full-version tags. Stable releases publish :X.Y.Z, :latest, and :sha-*; release candidates publish their full RC tag and SHA tag. New :X.Y and :X aliases are no longer created. Existing abbreviated tags remain in the registries but are not advanced by this or later releases.

New Features

• Semantic guardrails can be measured before and after deployment. The edit form has a dry-run panel that embeds probe text and shows the deny/allow score, configured threshold, closest example, and resulting verdict. Requests evaluated by a semantic guardrail add guardrail_scores to usage events, including requests that pass. The Logs page shows the score, threshold, direction, closest-example index, and embedding model; the usage API and CSV export carry the same record. Durable usage data contains the example index, never the example or screened text.

• Client-header forwarding now spans Provider Keys, MCP servers, passthrough routes, and Realtime. MCP servers and passthrough routes gain forward_client_headers; the existing Provider Key setting now also reaches Realtime and all translated provider paths. On MCP and standard model endpoints it is an allowlist; on passthrough routes it restores a header the route would otherwise strip. Because the field can pass caller credentials and trace context, credential slots, including the AWS SigV4 request-identity headers, and traceparent / tracestate require an exact name and cannot be selected by a glob. An exactly forwarded credential replaces the credential the gateway or default_headers would otherwise put in that slot, never adds a second value. Amazon Bedrock remains the exception: its signer owns authorization and the SigV4 headers and drops supplied values before signing.

• A direct model can normalize reasoning-effort values for its upstream. The new effort_mapping object performs one exact, case-sensitive string-to-string lookup after the final direct target is selected. Unlisted or absent values pass through unchanged, the mapping never adds a missing effort, and a mapped result is not looked up again. It covers Chat Completions, Responses, Anthropic Messages and token-count requests, native and cross-provider paths, streaming requests, Bedrock invocation modes, and direct targets selected through routing, semantic, or ensemble models. The setting is accepted only on direct models and is editable in the console.

Improvements

• Semantic guardrails require a threshold chosen for their embedding model. A non-empty deny_examples list now requires deny_threshold, and a non-empty allow_examples list requires allow_threshold; a direction with no examples requires no value. Existing rows that omitted a threshold are filled with 0.75, preserving what they already enforced. The Dashboard test panel and the per-request scores provide the measurements needed to tune a replacement value.

• Fail-open outcomes are visible on every guarded proxy surface. Success and error usage events carry guardrail_bypassed_reason, including a bypass that occurs before an individual guardrail executes. The aisix_guardrail_bypasses_total metric now includes reason="unscannable_body"; aisix_guardrail_blocks_total also includes fail-closed refusals raised before a timed guardrail execution. A2A and usage-less rerank or unsupported-capability paths emit zero-token usage events when needed to preserve guardrail attribution.

• Guardrail configuration failures are reported as configuration state. Rows that deserialize but cannot build at runtime now appear in /status/config, in rejection metrics, and in managed heartbeat status, and disappear after the row is repaired. Writes reject JSON null in PII, Presidio, keyword, and semantic configuration where the gateway could otherwise drop the whole guardrail. The upgrade migration repairs only stored nulls and missing values with safe defaults, validates the complete projected row, and leaves other malformed rows unchanged.

• Buffered output guardrails cover complete SSE frames. The Messages and Responses paths now handle CRLF framing, multi-line data: payloads, missing final terminators, and non-SSE JSON replies to streaming requests. Content that cannot be structurally masked is removed or refused instead of being released unread, while maskable multi-line frames retain their complete payload.

• Reasoning controls survive protocol translation. Anthropic output_config.effort and adaptive/disabled thinking map to the corresponding OpenAI reasoning_effort; OpenAI effort values map to Anthropic's current output_config.effort form. Anthropic structured-output declarations are also translated to OpenAI response_format with a strict JSON schema instead of being discarded.

• Routing and metrics expose more of the work the gateway performed. A routing target removed for cooldown or background health now produces a throttled warning naming the target and reason, and failed-attempt warnings are consistent across Chat Completions, Messages, token counting, and Responses. Native and translated Responses streams now report both TTFT metric families, and ensemble requests use one consistent usage estimate for quota, usage events, and token metrics.

• The console preserves resource references instead of asking operators to retype them. Existing-resource fields use searchable selectors, fields that may legitimately contain a new value keep editable suggestions, and a stale reference remains visible and is not silently cleared by an unrelated edit. In Logs, typing a requested-model filter remains a case-insensitive substring search, while selecting a known model performs case-sensitive equality in both the feed and CSV export.

Fixes

• Response model names are consistent on rerank and Realtime. A Jina-shaped /v1/rerank response and session.created / session.updated Realtime events now report the gateway model name the caller addressed rather than the provider's model id. A full Realtime session object sent back in session.update is translated to the upstream id again without changing a separately configured transcription model.

• Unsupported provider capabilities no longer spend the retry budget. Missing completions, embeddings, or image-generation support is classified explicitly and returns the existing 501 response without retrying an adapter capability that cannot change between attempts.

• Wildcard model references are validated before they become inert or widen access. Renaming a referenced model into a wildcard alias is refused when it would corrupt an exact-name reference or silently turn an API key's single-model grant into a namespace grant. A semantic guardrail cannot newly select a wildcard alias as its embedding model. A cache policy may select a concrete model name served by a wildcard alias, but cannot select the wildcard pattern itself. Previously stored references are validated again only when the referenced value changes.

API Changes

The OpenAPI structural comparison reports no breaking shape changes. However, several validation changes below are semantic breaking changes: a request that was previously accepted can now return 400. Callers should review them as well as the additive fields.

Upgrade Notes

These notes apply when you upgrade from any release earlier than 1.0.0, including an upgrade that passes over it on the way to a later release.

• Cooldown opt-in is a breaking behavior change. Before upgrading, set cooldown.enabled: true on every direct model that should retain the pre-1.0 implicit cooldown behavior.
• Treat /v1/files as outside guardrail coverage in this release. Do not rely on a whole-file keyword, PII, or remote-guardrail decision for uploads or downloads.
• Review the hooks and failure policy on every guardrail. A body that AISIX cannot scan and that a relevant fail-closed guardrail governs is still refused, but one that no relevant fail-closed guardrail governs can now continue. In particular, fail_open: true now takes effect for keyword and pii guardrails and can newly forward a request or response that AISIX cannot scan.
• Clients that replay reasoning content can now be blocked by input guardrails. Model-generated reasoning is no longer evaluated by output guardrails, and a mask action does not rewrite Anthropic signed thinking blocks.
• Handle 422 content_filter when transcription or translation response bytes cannot be decoded and an output guardrail fails closed. With fail-open, the original bytes can now be relayed without content evaluation.
• A stream: true request to /v1/completions or /v1/images/generations now returns 400 invalid_request_error without contacting the provider, instead of eventually returning a decode-related 502. Update status-code handling and retry policies.
• Update custom stream parsers for native guardrail error envelopes: Messages streams use Anthropic's invalid_request_error, while Responses streams put code, message, param, and sequence_number at the top level.
• Review stored guardrails containing JSON null before upgrade. A safely repairable row that the previous gateway skipped can begin enforcing after the migration; a semantic row missing only a threshold keeps its existing 0.75 behavior.
• API clients that create or replace semantic guardrail configs must include the threshold corresponding to every non-empty example list. The threshold and null checks are semantic breaking Admin API changes even though the OpenAPI shapes are not structurally breaking.
• Review automation that renames models or writes model references. A rename into a wildcard alias is rejected when it would corrupt an exact reference or widen an API key grant; semantic guardrails cannot newly use a wildcard alias as their embedding model; cache policies may name a concrete model served by an alias but not the wildcard pattern itself.
• Review Provider Key forward_client_headers patterns used with Realtime: 1.0.0 starts honoring the setting on that surface. Credential slots and traceparent / tracestate must be named exactly; broad globs do not select them. Remove rejected transport, x-stainless-*, anthropic-version, or x-aisix-* entries before saving a full overrides block. On Bedrock-compatible endpoints, a forwarded caller value now wins a collision with default_headers in the x-api-key, api-key, x-goog-api-key, proxy-authorization, and cookie slots. Bedrock's signer still owns authorization and the AWS SigV4 headers and discards caller-supplied values.
• Update image references or automation that expected a newly published :X.Y or :X alias to use the full version or :latest instead.
• If an alert is based on aisix_guardrail_bypasses_total, account for the new reason="unscannable_body" series and the additional events now included in the total.