[AIG]added header hierarchy docs (#18357)

* added header hierachy docs

* Minor edits

Author: daisyfaithauma

src/content/docs/ai-gateway/providers/universal.mdx

@@ -14,8 +14,6 @@ You can use the Universal Endpoint to contact every provider.
 https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}
 ```
 
-## Description
-
 AI Gateway offers multiple endpoints for each Gateway you create - one endpoint per provider, and one Universal Endpoint. The Universal Endpoint requires some adjusting to your schema, but supports additional features. Some of these features are, for example, retrying a request if it fails the first time, or configuring a [fallback model/provider](/ai-gateway/configuration/fallbacks/).
 
 You can use the Universal endpoint to contact every provider. The payload is expecting an array of message, and each message is an object with the following parameters:
@@ -25,17 +23,17 @@ You can use the Universal endpoint to contact every provider. The payload is exp
 - `authorization`: the content of the Authorization HTTP Header that should be used when contacting this provider. This usually starts with “Token” or “Bearer”.
 - `query`: the payload as the provider expects it in their official API.
 
-## Example
+## cURL example
 
 <Render file="universal-gateway-example" />
 
 The above will send a request to Workers AI Inference API, if it fails it will proceed to OpenAI. You can add as many fallbacks as you need, just by adding another JSON in the array.
 
-## Websockets API <Badge text="beta" variant="tip" size="small" />
+## WebSockets API <Badge text="beta" variant="tip" size="small" />
 
 The Universal Endpoint can also be accessed via a [WebSockets API](/ai-gateway/configuration/websockets-api/) which provides a single persistent connection, enabling continuous communication. This API supports all AI providers connected to AI Gateway, including those that do not natively support WebSockets.
 
-## Example request
+## WebSockets example
 
 ```javascript
 import WebSocket from "ws";
@@ -70,3 +68,75 @@ ws.on("message", function incoming(message) {
 	console.log(message.toString());
 });
 ```
+
+## Header configuration hierarchy
+
+The Universal Endpoint allows you to set fallback models or providers and customize headers for each provider or request. You can configure headers at three levels:
+
+1. **Provider level**: Headers specific to a particular provider.
+2. **Request level**: Headers included in individual requests.
+3. **Gateway settings**: Default headers configured in your gateway dashboard.
+
+Since the same settings can be configured in multiple locations, AI Gateway applies a hierarchy to determine which configuration takes precedence:
+
+- **Provider-level headers** override all other configurations.
+- **Request-level headers** are used if no provider-level headers are set.
+- **Gateway-level settings** are used only if no headers are configured at the provider or request levels.
+
+This hierarchy ensures consistent behavior, prioritizing the most specific configurations. Use provider-level and request-level headers for fine-tuned control, and gateway settings for general defaults.
+
+## Hierarchy example
+
+This example demonstrates how headers set at different levels impact caching behavior:
+
+- **Request-level header**: The `cf-aig-cache-ttl` is set to `3600` seconds, applying this caching duration to the request by default.
+- **Provider-level header**: For the fallback provider (OpenAI), `cf-aig-cache-ttl` is explicitly set to `0` seconds, overriding the request-level header and disabling caching for responses when OpenAI is used as the provider.
+
+This shows how provider-level headers take precedence over request-level headers, allowing for granular control of caching behavior.
+
+```bash
+curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id} \
+  --header 'Content-Type: application/json' \
+  --header 'cf-aig-cache-ttl: 3600' \
+  --data '[
+    {
+      "provider": "workers-ai",
+      "endpoint": "@cf/meta/llama-3.1-8b-instruct",
+      "headers": {
+        "Authorization": "Bearer {cloudflare_token}",
+        "Content-Type": "application/json"
+      },
+      "query": {
+        "messages": [
+          {
+            "role": "system",
+            "content": "You are a friendly assistant"
+          },
+          {
+            "role": "user",
+            "content": "What is Cloudflare?"
+          }
+        ]
+      }
+    },
+    {
+      "provider": "openai",
+      "endpoint": "chat/completions",
+      "headers": {
+        "Authorization": "Bearer {open_ai_token}",
+        "Content-Type": "application/json",
+        "cf-aig-cache-ttl": "0"
+      },
+      "query": {
+        "model": "gpt-4o-mini",
+        "stream": true,
+        "messages": [
+          {
+            "role": "user",
+            "content": "What is Cloudflare?"
+          }
+        ]
+      }
+    }
+  ]'
+```