diff --git a/docs/source/resources/configuration_reference.rst b/docs/source/resources/configuration_reference.rst
index 8e040f751..82cf74b52 100644
--- a/docs/source/resources/configuration_reference.rst
+++ b/docs/source/resources/configuration_reference.rst
@@ -7,6 +7,9 @@ The following is a complete reference of the ``plano_config.yml`` that controls
 the Plano gateway. This where you enable capabilities like routing to upstream LLm providers, defining prompt_targets
 where prompts get routed to, apply guardrails, and enable critical agent observability features.
 
+``model_providers`` entries support an optional ``headers`` map for extra string HTTP headers sent to the
+upstream provider. The deprecated ``llm_providers`` key accepts the same provider fields for legacy configs.
+
 .. literalinclude:: includes/plano_config_full_reference.yaml
     :language: yaml
     :linenos:
diff --git a/docs/source/resources/includes/plano_config_full_reference.yaml b/docs/source/resources/includes/plano_config_full_reference.yaml
index 99eb45101..cd03e64a9 100644
--- a/docs/source/resources/includes/plano_config_full_reference.yaml
+++ b/docs/source/resources/includes/plano_config_full_reference.yaml
@@ -42,10 +42,15 @@ model_providers:
     passthrough_auth: true
 
   # Custom/self-hosted endpoint with explicit http_host override
+  # headers: optional key-value map of extra HTTP headers sent to the upstream
+  # provider. Legacy llm_providers entries support the same provider fields.
   - model: openai/llama-3.3-70b
     base_url: https://api.custom-provider.com
     http_host: api.custom-provider.com
     access_key: $CUSTOM_API_KEY
+    headers:
+      User-Agent: "Plano/1.0"
+      X-Organization-Id: "org-example"
 
 # Model aliases - use friendly names instead of full provider model names
 model_aliases:
diff --git a/docs/source/resources/includes/plano_config_full_reference_rendered.yaml b/docs/source/resources/includes/plano_config_full_reference_rendered.yaml
index e2ab91103..535c0cd3e 100644
--- a/docs/source/resources/includes/plano_config_full_reference_rendered.yaml
+++ b/docs/source/resources/includes/plano_config_full_reference_rendered.yaml
@@ -82,6 +82,9 @@ listeners:
     base_url: https://api.custom-provider.com
     cluster_name: openai_api.custom-provider.com
     endpoint: api.custom-provider.com
+    headers:
+      User-Agent: Plano/1.0
+      X-Organization-Id: org-example
     http_host: api.custom-provider.com
     model: llama-3.3-70b
     name: openai/llama-3.3-70b
@@ -138,6 +141,9 @@ model_providers:
   base_url: https://api.custom-provider.com
   cluster_name: openai_api.custom-provider.com
   endpoint: api.custom-provider.com
+  headers:
+    User-Agent: Plano/1.0
+    X-Organization-Id: org-example
   http_host: api.custom-provider.com
   model: llama-3.3-70b
   name: openai/llama-3.3-70b