Update Passthrough Route

PATCH /environments/{env_id}/passthrough_routes/{passthrough_route_id}

Update Passthrough Route

Update selected fields on a passthrough route. The route name is fixed at creation — delete and recreate the route to change it. The create-time coupling rules apply to the PATCHED result: the route must keep at least one match dimension, exactly one target shape, and each mode's required companions. Changes take effect on new requests without a gateway restart.

Parameters

• env_id (path, string, required): Environment ID that scopes the request.
• passthrough_route_id (path, string, required): Passthrough route ID within the environment.

Request body

Content type: application/json

• path_prefix (string, optional): New gateway path prefix, or null to clear it.

• hosts (array, optional): New Host allowlist, or null to clear it.

• target_url (string, optional): New upstream base URL, or null to clear it.

• preserve_host (boolean, optional): Derive the target from the matched inbound host.

• auth_mode (object, optional): New gateway authentication mode.

• allOf variant 1

• auth_header_name (string, optional): New gateway-credential header for header_key mode (rejected when the patched result uses another mode), or null to clear it; credential-bearing names are rejected.

• anonymous_key_id (string, optional): New anonymous principal key (rejected when the patched result is not anonymous mode), or null to clear it.

• source_cidrs (array, optional): New source CIDR allowlist, or null to clear it.

• credential_mode (object, optional): New upstream credential handling.

• allOf variant 1

• provider_key_id (string, optional): New provider key to inject, or null to clear it.

• identity_header (string, optional): New end-user identity header, or null to clear it; credential-bearing names are rejected.

• timeout_ms (integer, optional): New total-exchange bound, or null to clear it.

• enabled (boolean, optional): Whether the route is active.

Responses

• 200: OK
• passthrough_route (object, required): An explicit passthrough binding from a gateway entry to one upstream target. Callers additionally need the route's name granted by their API key's allowed_routes patterns.

The body envelope (OpenAI-compatible chat / completions / Responses, or opaque) is not configured: the gateway detects it per request from the body's top-level keys, and guardrail extraction, audit capture, and token-usage recording follow the detection. Bodies are always relayed verbatim; SSE upstream responses are always relayed incrementally.

• passthrough_route.id (string, required): Unique passthrough route ID.

• passthrough_route.env_id (string, required): Environment the route belongs to.

• passthrough_route.name (string, required): Route name, unique within the environment and fixed at creation. Referenced by API keys' allowed_routes patterns and recorded on usage events for attribution.

• passthrough_route.path_prefix (string, optional): Gateway path prefix this route serves (segment-boundary match: /copilot matches /copilot and /copilot/x, never /copilotx). The prefix is stripped before the remainder joins the target URL. Must not claim a reserved gateway namespace (/v1, /mcp, /a2a, /admin, /livez, /readyz, /metrics). At least one of path_prefix / hosts is required; when both are set a request must satisfy both.

• passthrough_route.hosts (array, optional): Inbound Host values this route serves — the forward-proxy entry, where a TLS-terminating device delivers plaintext traffic with its original Host. Matched case-insensitively, ignoring any :port suffix. A leading *. wildcard matches exactly one extra label and must keep at least two literal labels (*.githubcopilot.com is accepted; *.com and a bare * are rejected). Host-matched requests keep their full path unless path_prefix also matched.

• passthrough_route.target_url (string, optional): Explicit upstream base URL; the matched remainder path and query are appended (a trailing /v1 on the target and a leading v1/ on the remainder de-duplicate). Exactly one of target_url / preserve_host: true must be configured.

• passthrough_route.preserve_host (boolean, required): Derive the target from the matched inbound host (https://<host>), for forward-proxy routes fanning one route over several official hosts. Only accepted together with hosts — the allowlist is what bounds the derived target.

• passthrough_route.auth_mode (object, required): How the gateway authenticates callers of this route. header_key requires auth_header_name; anonymous requires anonymous_key_id and a non-empty source_cidrs.

• allOf variant 1

• passthrough_route.auth_header_name (string, optional): Lowercase header carrying the gateway credential when auth_mode is header_key (for example x-aisix-api-key); stripped before forwarding. Rejected on any other auth_mode — the gateway never consults it there. Credential-bearing names (authorization, proxy-authorization, cookie, set-cookie, x-api-key) are rejected.

• passthrough_route.anonymous_key_id (string, optional): The environment API key this route's traffic runs as when auth_mode is anonymous. Its allowed_routes grant, rate limits, budget, and usage attribution apply unchanged, so anonymous traffic keeps a stable, governable principal. Rejected on any other auth_mode — the gateway never consults it there.

• passthrough_route.source_cidrs (array, optional): Client source CIDRs allowed to use this route. Required (non-empty) when auth_mode is anonymous; optional hardening for the other modes. Unset means no route-level source restriction.

• passthrough_route.credential_mode (object, required): How the upstream credential is produced. inject (the default) requires provider_key_id; forward_client forbids it.

• allOf variant 1

• passthrough_route.provider_key_id (string, optional): Provider key whose secret is injected upstream when credential_mode is inject; its header-strip list and TLS settings apply to the route's traffic. The provider key must be visible to this environment.

• passthrough_route.identity_header (string, optional): Optional lowercase header carrying the end-user identity injected by the upstream network device (for example x-aisix-user). Its value is recorded on usage events as client_identity for per-employee audit attribution and stripped before forwarding. Credential-bearing names are rejected.

• passthrough_route.timeout_ms (integer, optional): Upstream exchange bound in milliseconds. Bounds the response-header phase and any non-SSE body read, never a healthy SSE relay. When omitted, the gateway's default request timeout applies the same way.

• passthrough_route.enabled (boolean, required): Whether the route is active. A disabled route matches nothing.

• passthrough_route.created_at (string, required): Creation timestamp.

• passthrough_route.updated_at (string, required): Last update timestamp.

• warnings (array, optional): Data-plane compatibility warnings for this save, when any connected data plane predates a configured capability.

• warnings[].code (string, required): How affected nodes treat the saved resource. field_ignored: the resource stays in service on those nodes but the named field has no effect there — beware when the field is restrictive, since the restriction is silently not enforced. row_rejected: those nodes refuse the whole resource, so it stops serving there entirely (or, if a previously accepted version exists, they keep serving the old values).

• warnings[].field (string, required): Dot-separated path of the field that triggered the warning, as delivered to gateway nodes.

• warnings[].min_dp_version (string, required): Oldest gateway version that fully executes the field. The literal value unreleased means no released gateway version executes it yet.

• warnings[].affected_dp_count (integer, required): Number of currently registered nodes in the environment running an older gateway version than min_dp_version.

• warnings[].affected_dp_versions (array, required): Distinct gateway versions reported by the affected nodes, capped at five entries. Nodes that report no version appear as unknown.

• 400: Request body or parameters failed validation.

• error (object, required): Error details.

• error.code (string, required): Machine-readable identifier. Examples: UNAUTHENTICATED, INVALID_REQUEST, MASTER_KEY_UNSET, INTERNAL.

• error.message (string, required): Human-readable explanation; safe to surface to operators.

• 401: Missing or invalid bearer. Response fields (application/json): identical to PATCH /environments/{env_id}/passthrough_routes/{passthrough_route_id}, response 400 above.

• 403: Authenticated request is not permitted. Response fields (application/json): identical to PATCH /environments/{env_id}/passthrough_routes/{passthrough_route_id}, response 400 above.

• 404: Resource not found. Response fields (application/json): identical to PATCH /environments/{env_id}/passthrough_routes/{passthrough_route_id}, response 400 above.

• 409: Request conflicts with current resource state. Response fields (application/json): identical to PATCH /environments/{env_id}/passthrough_routes/{passthrough_route_id}, response 400 above.

cURL

curl -X PATCH '$AISIX_CP/environments/{env_id}/passthrough_routes/{passthrough_route_id}' -H 'Authorization: Bearer $AISIX_TOKEN'