Request Transformer Policy

This Policy lets you configure transformations of requests before AI Gateway forwards them to the upstream provider. These transformations can be simple substitutions or complex ones. For example, complex transformations can match portions of incoming requests using regular expressions, save those matched strings into variables, and substitute those strings into transformed requests using flexible templates.

This Policy operates on the raw HTTP request only: headers, query string, and body fields. To transform a request based on its meaning using an LLM (for example, rewriting a prompt), use the AI Request Transformer Policy instead.

Note: The X-Forwarded-* fields are non-standard header fields written by Nginx to inform the upstream about client details and can’t be overwritten by this Policy. If you need to overwrite these header fields, see the Post-Function Policy.

For more advanced features, see the Request Transformer Advanced Policy.

The Policy performs the transformations in the following order:

1. Remove
2. Rename
3. Replace
4. Add
5. Append
6. Allow

You can use any of the current request headers and query parameters as templates to populate supported configuration fields.

To escape a template, wrap it inside quotes and pass inside another template. For example:

$('$(something_that_needs_to_escaped)')

Note: The Policy creates a non-mutable table of request headers and query strings before transformation. Therefore, removing or updating any parameters used in a template doesn’t affect the rendered value of a template.

Advanced templates

The content of the placeholder $(...) is evaluated as a Lua expression, so you can use logical operators. For example:

$(query_params["user"] or "unknown")

This example looks for a query parameter named user. If it doesn’t exist, it returns the default value "unknown".

Constant parts can be specified as part of the template outside the dynamic placeholders. For example, this creates a basic-auth header from a query parameter called auth that only contains the base64-encoded part:

Basic $(query_params["auth"])

Lambdas are also supported if wrapped as an expression like this:

$((function() ... implementation here ... end)())

Here’s a complete Lambda example for prefixing a header value with Basic if it’s not already included:

$((function()
    local value = headers.Authorization
    if not value then
      return
    end
    if value:sub(1, 6) == "Basic " then
      return value            -- was already properly formed
    end
    return "Basic " .. value  -- added proper prefix
  end)())

The environment is sandboxed, meaning that Lambdas won’t have access to any library functions, except for the string methods (like sub() in this example).

Note: Make sure not to add any trailing whitespace or newlines, especially in multi-line templates. These would be outside the placeholders and would be considered part of the template, and hence would be appended to the generated value.

A common use for this Policy in AI Gateway is removing headers, query string parameters, or body fields that a client sends but that a specific upstream AI Model Provider rejects. For example, a client that sends Anthropic-specific beta fields to a provider whose API doesn’t support them:

ai_gateway_policies:
  - ref: strip-unsupported-beta-fields
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: Strip unsupported beta fields
    name: strip-unsupported-beta-fields
    type: request-transformer
    enabled: true
    global: false
    config:
      remove:
        headers:
        - anthropic-beta
        querystring:
        - beta
        body:
        - output_config
        - context_management
        - mcp_servers
        - container
        - service_tier

Make sure to replace the following placeholders with your own values:

• AI_GATEWAY_ID: The id of your AI Gateway.

Attach this Policy to an AI Model’s policies array so it applies before AI Gateway forwards the request upstream.