diff --git a/docs/api/providers.md b/docs/api/providers.md
index aabf10f068..8887c417c5 100644
--- a/docs/api/providers.md
+++ b/docs/api/providers.md
@@ -2,6 +2,8 @@
 
 ::: pydantic_ai.providers.Provider
 
+::: pydantic_ai.providers.gateway
+
 ::: pydantic_ai.providers.google
 
 ::: pydantic_ai.providers.openai
diff --git a/docs/gateway.md b/docs/gateway.md
index da9198b4b5..bc1c284379 100644
--- a/docs/gateway.md
+++ b/docs/gateway.md
@@ -119,18 +119,63 @@ export PYDANTIC_AI_GATEWAY_API_KEY="YOUR_PYDANTIC_AI_GATEWAY_API_KEY"
 
 You can access multiple models with the same API key, as shown in the code snippet below.
 
-```python {title="hello_world.py"}
-from pydantic_ai import Agent
+=== "Hello World"
 
-agent = Agent('gateway/openai:gpt-5')
+    ```python {title="hello_world.py"}
+    from pydantic_ai import Agent
 
-result = agent.run_sync('Where does "hello world" come from?')
-print(result.output)
-"""
-The first known use of "hello, world" was in a 1974 textbook about the C programming language.
-"""
-```
+    agent = Agent('gateway/openai:gpt-5')
+
+    result = agent.run_sync('Where does "hello world" come from?')
+    print(result.output)
+    """
+    The first known use of "hello, world" was in a 1974 textbook about the C programming language.
+    """
+    ```
 
+=== "Passing API Key directly"
+
+    Pass your API key directly using the [gateway_provider](https://ai.pydantic.dev/api/providers/#pydantic_ai.providers.gateway):
+
+    ```python {title="passing_api_key.py"}
+    from pydantic_ai import Agent
+    from pydantic_ai.models.openai import OpenAIChatModel
+    from pydantic_ai.providers.gateway import gateway_provider
+
+    provider = gateway_provider('openai', api_key='PYDANTIC_AI_GATEWAY_API_KEY')
+    model = OpenAIChatModel('gpt-5', provider=provider)
+    agent = Agent(model)
+
+    result = agent.run_sync('Where does "hello world" come from?')
+    print(result.output)
+    """
+    The first known use of "hello, world" was in a 1974 textbook about the C programming language.
+    """
+    ```
+
+=== "Using a different upstream provider"
+
+    If you're using a different upstream provider, you can specify it in the route parameter:
+
+    ```python {title="routing_via_provider.py"}
+    from pydantic_ai import Agent
+    from pydantic_ai.models.openai import OpenAIChatModel
+    from pydantic_ai.providers.gateway import gateway_provider
+
+    provider = gateway_provider(
+        'openai',
+        api_key='PYDANTIC_AI_GATEWAY_API_KEY',
+        route='modal-ai'
+    )
+    model = OpenAIChatModel('gpt-5', provider=provider)
+    agent = Agent(model)
+
+    result = agent.run_sync('Where does "hello world" come from?')
+    print(result.output)
+    """
+    The first known use of "hello, world" was in a 1974 textbook about the C programming language.
+    """
+    ```
 
 ### Claude Code