docs: clarify AI request protocol handling

docs/en/latest/plugins/ai-aliyun-content-moderation.md

@@ -45,6 +45,16 @@ Please ensure that the `access_key_secret` is correctly configured in the Plugin
 
 The `ai-aliyun-content-moderation` Plugin should be used with either [`ai-proxy`](./ai-proxy.md) or [`ai-proxy-multi`](./ai-proxy-multi.md) Plugin for proxying LLM requests.
 
+The Plugin moderates Chat Completions, Responses API, Embeddings, Anthropic Messages, and Bedrock Converse requests using each protocol's native content structure. For Responses, it moderates `input` and returns blocked non-streaming or streaming requests in Responses API format. For Embeddings, it moderates a string or an array of strings in `input` and returns rejected requests as OpenAI-style errors.
+
+APISIX checks URI-specific formats before body-only formats:
+
+- Bedrock Converse requires a URI ending in `/converse` and a `messages` array.
+- Anthropic Messages requires a URI ending in `/v1/messages`.
+- Responses API requires a URI ending in `/v1/responses` and an `input` field.
+- Chat Completions uses a `messages` array.
+- Embeddings uses `input` after the earlier rules do not match.
+
 ## Attributes
 
 | Name | Type | Required | Default | Valid values | Description |

docs/en/latest/plugins/ai-aws-content-moderation.md

@@ -38,7 +38,7 @@ import TabItem from '@theme/TabItem';
 
 The `ai-aws-content-moderation` Plugin integrates with [AWS Comprehend](https://aws.amazon.com/comprehend/) to check request content for toxicity when proxying to LLMs, such as profanity, hate speech, insult, harassment, violence, and more, rejecting requests if the evaluated outcome exceeds the configured threshold.
 
-The Plugin is protocol-aware: it extracts the prompt content from the LLM request (for example `messages[].content`) and moderates only that decoded text, rather than the raw request body.
+The Plugin supports Chat Completions, Responses API, Embeddings, Anthropic Messages, and Bedrock Converse requests. It extracts text using the detected protocol's native content structure and moderates only that decoded text rather than the raw request body. Rejected requests use the detected protocol's response format.
 
 The `ai-aws-content-moderation` Plugin should be used with either [`ai-proxy`](./ai-proxy.md) or [`ai-proxy-multi`](./ai-proxy-multi.md) Plugin for proxying LLM requests.
 

docs/en/latest/plugins/ai-cache.md

@@ -45,6 +45,8 @@ This Plugin supports two cache layers:
 - **Exact (L1):** A SHA-256 fingerprint of the effective prompt is used as the Redis key. An identical prompt always hits the same entry.
 - **Semantic (L2):** When L1 misses, the prompt is embedded into a vector and a nearest-neighbour search retrieves a past response whose embedding is within the configured similarity threshold. L2 is disabled by default; enable it by adding `"semantic"` to `layers`.
 
+Exact caching supports Chat Completions, Responses API, Embeddings, Anthropic Messages, and Bedrock Converse requests and keeps the protocols in separate cache entries. Semantic caching applies only to Chat Completions requests; the other protocols can use the exact layer but bypass the semantic layer.
+
 The `ai-cache` Plugin must be used with the [`ai-proxy`](./ai-proxy.md) or [`ai-proxy-multi`](./ai-proxy-multi.md) Plugin.
 
 ### Streaming

docs/en/latest/plugins/ai-lakera-guard.md

@@ -43,7 +43,9 @@ The `ai-lakera-guard` Plugin integrates with the [Lakera Guard API (v2)](https:/
 
 Which detectors run and at what thresholds are controlled entirely by the **Lakera project policy**, selected with `project_id`. There is no gateway-side detector list; Lakera returns a single verdict per call.
 
-The `ai-lakera-guard` Plugin should be used with either the [`ai-proxy`](./ai-proxy.md) or [`ai-proxy-multi`](./ai-proxy-multi.md) Plugin for proxying LLM requests. It relies on the context that `ai-proxy` populates to extract chat content in a protocol-aware way.
+The `ai-lakera-guard` Plugin should be used with either the [`ai-proxy`](./ai-proxy.md) or [`ai-proxy-multi`](./ai-proxy-multi.md) Plugin for proxying LLM requests. It relies on the context that `ai-proxy` populates to extract request content in a protocol-aware way.
+
+Request scanning supports Chat Completions, Responses API, Embeddings, Anthropic Messages, and Bedrock Converse requests. For Responses, the Plugin converts `instructions` and text from `input` into conversation messages. For Embeddings, it scans text from `input`. Response scanning applies to the protocols that return generated text; Embeddings responses contain vectors rather than text.
 
 Requests that did not pass through `ai-proxy`/`ai-proxy-multi` (for example plain HTTP traffic when the Plugin is bound at the Consumer or Service level) cannot be inspected. By default such requests are passed through unchecked; this is configurable via `fail_mode`.
 
@@ -63,7 +65,7 @@ The Plugin can scan the request prompt (`direction: input`), the LLM response (`
 | timeout | integer | False | `5000` | >= 1 | Lakera request timeout in milliseconds. |
 | ssl_verify | boolean | False | `true` | | If `true`, verify the TLS certificate of the Lakera endpoint. |
 | reveal_failure_categories | boolean | False | `false` | | If `true`, append the matched Lakera `detector_type`s (with their confidence result) to the deny message returned to the client. The full per-detector `breakdown` is always requested from Lakera and written to the gateway logs regardless of this setting; this flag only controls client-facing exposure. |
-| deny_code | integer | False | `200` | 200 - 599 | HTTP status code returned when a request is blocked. Defaults to `200` so the body — a provider-compatible chat completion (or SSE) carrying `request_failure_message` — parses as a normal refusal in client SDKs (matching how Lakera Guard itself returns `200` with a verdict). Set a 4xx (e.g. `403`) if you prefer blocks to surface as HTTP errors. |
+| deny_code | integer | False | `200` | 200 - 599 | HTTP status code returned when a request is blocked. Defaults to `200` so the body in the detected protocol's format carrying `request_failure_message` parses as a normal refusal in client SDKs (matching how Lakera Guard itself returns `200` with a verdict). Set a 4xx (e.g. `403`) if you prefer blocks to surface as HTTP errors. |
 | request_failure_message | string | False | `Request blocked by Lakera Guard` | | Refusal text returned (as the assistant message of a provider-compatible response) when a request is blocked. |
 | response_failure_message | string | False | `Response blocked by Lakera Guard` | | Refusal text returned (as the assistant message of a provider-compatible response) when an LLM response is blocked (`direction` `output` or `both`). |
 

docs/en/latest/plugins/ai-prompt-decorator.md

@@ -38,6 +38,16 @@ import TabItem from '@theme/TabItem';
 
 The `ai-prompt-decorator` Plugin modifies user input prompts by prefixing and appending pre-engineered prompts to set contexts in content generation. This practice helps the model operate within desired guidelines during interactions.
 
+The Plugin decorates Chat Completions, Responses API, Anthropic Messages, and Bedrock Converse requests using each protocol's native prompt structure. For Responses, content from `prepend` is added to `instructions`, and content from `append` is added to `input`. The Plugin does not modify Embeddings requests because that format has no prompt roles to prepend or append.
+
+APISIX checks URI-specific formats before body-only formats:
+
+- Bedrock Converse requires a URI ending in `/converse` and a `messages` array.
+- Anthropic Messages requires a URI ending in `/v1/messages`.
+- Responses API requires a URI ending in `/v1/responses` and an `input` field.
+- Chat Completions uses a `messages` array.
+- Embeddings uses `input` after the earlier rules do not match.
+
 ## Plugin Attributes
 
 | Name | Type | Required | Default | Valid values | Description |

docs/en/latest/plugins/ai-prompt-guard.md

@@ -40,6 +40,16 @@ The `ai-prompt-guard` Plugin safeguards your LLM endpoints by inspecting and val
 
 When both `allow_patterns` and `deny_patterns` are configured, the Plugin first ensures that at least one `allow_patterns` is matched. If none match, the request is rejected. If an allowed pattern is matched, it then checks for any occurrences of denied patterns.
 
+The Plugin checks Chat Completions, Responses API, Embeddings, Anthropic Messages, and Bedrock Converse requests using each protocol's native content structure. For Responses, it checks user content in `input` and, when `match_all_roles` is `true`, system content in `instructions`. For Embeddings, it checks `input` when it is a string; an array of input strings is not inspected.
+
+APISIX checks URI-specific formats before body-only formats:
+
+- Bedrock Converse requires a URI ending in `/converse` and a `messages` array.
+- Anthropic Messages requires a URI ending in `/v1/messages`.
+- Responses API requires a URI ending in `/v1/responses` and an `input` field.
+- Chat Completions uses a `messages` array.
+- Embeddings uses `input` after the earlier rules do not match.
+
 ## Plugin Attributes
 
 | Name | Type | Required | Default | Valid values | Description |

docs/en/latest/plugins/ai-prompt-template.md

@@ -38,14 +38,16 @@ import TabItem from '@theme/TabItem';
 
 The `ai-prompt-template` Plugin supports pre-configuring prompt templates that only accept user inputs in designated template variables, in a "fill in the blank" fashion. It simplifies access to LLM providers, such as OpenAI and Anthropic, by letting you define reusable prompt structures.
 
+The Plugin replaces the incoming request body with the selected rendered JSON template. A template can use any request format supported by the downstream Plugin, including Chat Completions, Responses API, and Embeddings. Use [`ai-prompt-decorator`](./ai-prompt-decorator.md) instead when you need to add content to an existing request without replacing its body.
+
 ## Plugin Attributes
 
 | Name | Type | Required | Default | Valid values | Description |
 | --- | --- | --- | --- | --- | --- |
 | `max_req_body_size` | integer | False | 67108864 | >= 1 | Maximum request body size in bytes buffered into memory. Requests with a larger body are rejected. |
 | `templates` | array | True | | | An array of template objects. |
 | `templates.name` | string | True | | | Name of the template. When requesting the Route, the request should include the template name that corresponds to the configured template. |
-| `templates.template` | object | True | | | Template specification. |
+| `templates.template` | object | True | | | JSON request body template. It can contain any fields accepted by the downstream Plugin. |
 | `templates.template.model` | string | False | | | Name of the LLM model, such as `gpt-4` or `gpt-3.5`. See your LLM provider API documentation for more available models. |
 | `templates.template.messages` | array[object] | False | | | Template message specification. |
 | `templates.template.messages.role` | string | True | | [`system`, `user`, `assistant`] | Role of the message. |
@@ -601,3 +603,118 @@ You should receive a response similar to the following:
   ...
 }
 ```
+
+### Configure a Responses API Web Search Template
+
+The following example configures a Responses API template that searches only the official Apache APISIX website. The Route URI can have a custom prefix, but it must end in `/v1/responses` so that `ai-proxy` distinguishes the rendered body from an Embeddings request.
+
+Create a Route with the `ai-proxy` and `ai-prompt-template` Plugins:
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes/ai-prompt-template-responses" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "uri": "/template/v1/responses",
+    "methods": ["POST"],
+    "plugins": {
+      "ai-proxy": {
+        "provider": "openai",
+        "auth": {
+          "header": {
+            "Authorization": "Bearer '"$OPENAI_API_KEY"'"
+          }
+        }
+      },
+      "ai-prompt-template": {
+        "templates": [
+          {
+            "name": "Search APISIX documentation",
+            "template": {
+              "model": "gpt-4.1",
+              "tools": [
+                {
+                  "type": "web_search",
+                  "filters": {
+                    "allowed_domains": ["apisix.apache.org"]
+                  }
+                }
+              ],
+              "tool_choice": "required",
+              "input": "Search the official Apache APISIX website for {{topic}} and summarize the result in one sentence."
+            }
+          }
+        ]
+      }
+    }
+  }'
+```
+
+Send the template name and a value for `topic` to the Route:
+
+```shell
+curl "http://127.0.0.1:9080/template/v1/responses" -X POST \
+  -H "Content-Type: application/json" \
+  -d '{
+    "template_name": "Search APISIX documentation",
+    "topic": "what APISIX is"
+  }'
+```
+
+Before `ai-proxy` processes the request, `ai-prompt-template` replaces the incoming body with the rendered template:
+
+```json
+{
+  "model": "gpt-4.1",
+  "tools": [
+    {
+      "type": "web_search",
+      "filters": {
+        "allowed_domains": ["apisix.apache.org"]
+      }
+    }
+  ],
+  "tool_choice": "required",
+  "input": "Search the official Apache APISIX website for what APISIX is and summarize the result in one sentence."
+}
+```
+
+APISIX identifies the rendered request as Responses API from its `input` field and the Route URI suffix. You should receive an HTTP `200` response whose `output` contains a completed web search call and a message with URL citations:
+
+```json
+{
+  "status": "completed",
+  "output": [
+    {
+      "type": "web_search_call",
+      "status": "completed",
+      "action": {
+        "type": "search",
+        "queries": [
+          "site:apisix.apache.org what is Apache APISIX"
+        ],
+        "query": "site:apisix.apache.org what is Apache APISIX"
+      }
+    },
+    {
+      "type": "message",
+      "status": "completed",
+      "role": "assistant",
+      "content": [
+        {
+          "type": "output_text",
+          "text": "Apache APISIX is an open-source, high-performance API and AI gateway for managing traffic at scale through dynamic routing, load balancing, authentication, observability, rate limiting, and over 100 plugins. ([apisix.apache.org](https://apisix.apache.org/?utm_source=openai))",
+          "annotations": [
+            {
+              "type": "url_citation",
+              "start_index": 208,
+              "end_index": 275,
+              "title": "Apache APISIX - Open Source API Gateway & AI Gateway",
+              "url": "https://apisix.apache.org/?utm_source=openai"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```