> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/agentgateway/agentgateway/llms.txt
> Use this file to discover all available pages before exploring further.

# Transformations

> Reference for request and response transformation policies — header modification, URL rewriting, redirects, mirroring, and body transformations.

Transformation policies allow you to modify requests and responses as they pass through Agentgateway. Transformations are applied at the route level under `binds[].listeners[].routes[].policies`.

Agentgateway supports the following transformation types:

* **`requestHeaderModifier`** — add, set, or remove request headers
* **`responseHeaderModifier`** — add, set, or remove response headers
* **`requestRedirect`** — respond directly with an HTTP redirect
* **`urlRewrite`** — modify the URL path or authority before forwarding
* **`requestMirror`** — mirror requests to a secondary backend
* **`directResponse`** — respond directly with a static body without forwarding
* **`transformations`** — modify request and response bodies and headers

## requestHeaderModifier

Modify headers on the inbound request before it is forwarded to the backend.

```yaml theme={null}
policies:
  requestHeaderModifier:
    add:
      x-request-source: agentgateway
    set:
      x-forwarded-host: gateway.example.com
    remove:
    - x-internal-debug
```

<ParamField body="requestHeaderModifier" type="object">
  Headers to be modified on the inbound request.

  <Expandable title="requestHeaderModifier fields">
    <ParamField body="requestHeaderModifier.add" type="object">
      Key-value pairs of headers to **add** to the request. If the header already exists, a new header with the same name is appended.

      ```yaml theme={null}
      requestHeaderModifier:
        add:
          x-custom-header: my-value
      ```
    </ParamField>

    <ParamField body="requestHeaderModifier.set" type="object">
      Key-value pairs of headers to **set** on the request. If the header already exists, its value is overwritten.

      ```yaml theme={null}
      requestHeaderModifier:
        set:
          x-forwarded-for: 10.0.0.1
      ```
    </ParamField>

    <ParamField body="requestHeaderModifier.remove" type="string[]">
      List of header names to **remove** from the request.

      ```yaml theme={null}
      requestHeaderModifier:
        remove:
        - x-debug-token
        - x-internal-id
      ```
    </ParamField>
  </Expandable>
</ParamField>

## responseHeaderModifier

Modify headers on the response from the backend before it is returned to the client.

```yaml theme={null}
policies:
  responseHeaderModifier:
    add:
      x-served-by: agentgateway
    remove:
    - server
    - x-powered-by
```

<ParamField body="responseHeaderModifier" type="object">
  Headers to be modified on the outbound response.

  <Expandable title="responseHeaderModifier fields">
    <ParamField body="responseHeaderModifier.add" type="object">
      Key-value pairs of headers to add to the response.
    </ParamField>

    <ParamField body="responseHeaderModifier.set" type="object">
      Key-value pairs of headers to set on the response, overwriting existing values.
    </ParamField>

    <ParamField body="responseHeaderModifier.remove" type="string[]">
      List of header names to remove from the response.

      ```yaml theme={null}
      responseHeaderModifier:
        remove:
        - server
        - x-powered-by
      ```
    </ParamField>
  </Expandable>
</ParamField>

## requestRedirect

Respond directly to the client with an HTTP redirect without forwarding the request to a backend.

```yaml theme={null}
policies:
  requestRedirect:
    scheme: https
    authority:
      host: api.example.com
    status: 301
```

<ParamField body="requestRedirect" type="object">
  Directly respond to the request with a redirect.

  <Expandable title="requestRedirect fields">
    <ParamField body="requestRedirect.scheme" type="string">
      The redirect scheme. Typically `http` or `https`.

      ```yaml theme={null}
      requestRedirect:
        scheme: https
      ```
    </ParamField>

    <ParamField body="requestRedirect.authority" type="object">
      The redirect authority (host and/or port). One of `full`, `host`, or `port`.

      <Expandable title="authority options">
        <ParamField body="requestRedirect.authority.full" type="string">
          Full authority string including host and port (e.g. `api.example.com:443`).
        </ParamField>

        <ParamField body="requestRedirect.authority.host" type="string">
          Host portion only.
        </ParamField>

        <ParamField body="requestRedirect.authority.port" type="integer">
          Port portion only.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="requestRedirect.path" type="object">
      The redirect path. One of `full` or `prefix`.

      <Expandable title="path options">
        <ParamField body="requestRedirect.path.full" type="string">
          Replace the entire path with this value.
        </ParamField>

        <ParamField body="requestRedirect.path.prefix" type="string">
          Replace the matched path prefix with this value.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="requestRedirect.status" type="integer">
      HTTP redirect status code. Common values: `301` (permanent), `302` (temporary), `307`, `308`.

      ```yaml theme={null}
      requestRedirect:
        status: 301
      ```
    </ParamField>
  </Expandable>
</ParamField>

## urlRewrite

Modify the URL path or authority before forwarding the request to the backend. Unlike `requestRedirect`, the client does not see the rewrite — it receives the backend's response as if the original URL was used.

```yaml theme={null}
policies:
  urlRewrite:
    authority:
      host: internal-backend.example.com
    path:
      prefix: /v2
```

<ParamField body="urlRewrite" type="object">
  Modify the URL path or authority before forwarding.

  <Expandable title="urlRewrite fields">
    <ParamField body="urlRewrite.authority" type="object">
      Override the request authority. One of `full`, `host`, or `port`.

      <Expandable title="authority options">
        <ParamField body="urlRewrite.authority.full" type="string">
          Full authority string.
        </ParamField>

        <ParamField body="urlRewrite.authority.host" type="string">
          Host portion only.
        </ParamField>

        <ParamField body="urlRewrite.authority.port" type="integer">
          Port portion only.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="urlRewrite.path" type="object">
      Override the request path. One of `full` or `prefix`.

      <Expandable title="path options">
        <ParamField body="urlRewrite.path.full" type="string">
          Replace the entire path.
        </ParamField>

        <ParamField body="urlRewrite.path.prefix" type="string">
          Replace the matched path prefix.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## requestMirror

Mirror (shadow) incoming requests to a secondary backend in addition to the primary backend. The client only receives the response from the primary backend. The mirror backend's response is discarded.

```yaml theme={null}
policies:
  requestMirror:
    backend: shadow-backend
    percentage: 10
```

<ParamField body="requestMirror" type="object">
  Mirror incoming requests to another destination.

  <Expandable title="requestMirror fields">
    <ParamField body="requestMirror.backend" type="object">
      The mirror destination. One of `service`, `host`, or `backend`.

      <Expandable title="backend options">
        <ParamField body="requestMirror.backend.service" type="object">
          Reference to a named service.

          <Expandable title="service fields">
            <ParamField body="service.name.namespace" type="string">Namespace of the service.</ParamField>
            <ParamField body="service.name.hostname" type="string">Hostname of the service.</ParamField>
            <ParamField body="service.port" type="integer">Port of the service.</ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="requestMirror.backend.host" type="string">
          Hostname or IP address of the mirror backend.
        </ParamField>

        <ParamField body="requestMirror.backend.backend" type="string">
          Name of a backend defined in the top-level `backends` list.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="requestMirror.percentage" type="integer">
      Percentage of requests to mirror (0–100). When omitted, all matching requests are mirrored.

      ```yaml theme={null}
      requestMirror:
        percentage: 10
      ```
    </ParamField>
  </Expandable>
</ParamField>

## directResponse

Respond directly to the client with a static response body and status code, without forwarding to any backend.

```yaml theme={null}
policies:
  directResponse:
    status: 200
    body: '{"status": "ok"}'
```

<ParamField body="directResponse" type="object">
  Directly respond to the request with a static response.

  <Expandable title="directResponse fields">
    <ParamField body="directResponse.status" type="integer" required>
      HTTP status code for the response.

      ```yaml theme={null}
      directResponse:
        status: 200
      ```
    </ParamField>

    <ParamField body="directResponse.body" type="string">
      Response body string.

      ```yaml theme={null}
      directResponse:
        status: 200
        body: '{"message": "Service unavailable"}'
      ```
    </ParamField>
  </Expandable>
</ParamField>

## transformations

Modify request and response bodies, headers, and metadata using structured transformation rules.

```yaml theme={null}
policies:
  transformations:
    request:
      add:
        x-request-id: some-value
      set:
        content-type: application/json
      remove:
      - x-debug
    response:
      add:
        x-proxy: agentgateway
      remove:
      - server
```

<ParamField body="transformations" type="object">
  Modify requests and responses sent to and from the backend.

  <Expandable title="transformations fields">
    <ParamField body="transformations.request" type="object">
      Transformations applied to the inbound request.

      <Expandable title="request transformation fields">
        <ParamField body="transformations.request.add" type="object">
          Headers to add to the request.
        </ParamField>

        <ParamField body="transformations.request.set" type="object">
          Headers to set on the request (overwriting existing values).
        </ParamField>

        <ParamField body="transformations.request.remove" type="string[]">
          Headers to remove from the request.
        </ParamField>

        <ParamField body="transformations.request.body" type="object">
          Modifications to apply to the request body.
        </ParamField>

        <ParamField body="transformations.request.metadata" type="object">
          Metadata to attach to the request.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="transformations.response" type="object">
      Transformations applied to the response from the backend.

      <Expandable title="response transformation fields">
        <ParamField body="transformations.response.add" type="object">
          Headers to add to the response.
        </ParamField>

        <ParamField body="transformations.response.set" type="object">
          Headers to set on the response.
        </ParamField>

        <ParamField body="transformations.response.remove" type="string[]">
          Headers to remove from the response.
        </ParamField>

        <ParamField body="transformations.response.body" type="object">
          Modifications to apply to the response body.
        </ParamField>

        <ParamField body="transformations.response.metadata" type="object">
          Metadata to attach to the response.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Combined example

```yaml theme={null}
binds:
- port: 3000
  listeners:
  - routes:
    - matches:
      - path:
          pathPrefix: /api/
      policies:
        requestHeaderModifier:
          add:
            x-request-source: agentgateway
          remove:
          - x-internal-token
        responseHeaderModifier:
          remove:
          - server
          - x-powered-by
        urlRewrite:
          path:
            prefix: /v2
        transformations:
          request:
            set:
              content-type: application/json
          response:
            add:
              x-proxy: agentgateway
      backends:
      - host: http://api-backend:8080
```

<Note>
  `requestHeaderModifier` and `responseHeaderModifier` operate on individual HTTP headers, while `transformations` provides a broader object with support for request/response body modifications. Both can be used together on the same route.
</Note>