From 1354a89f87a4120a06c7870a52a1758f547e5e71 Mon Sep 17 00:00:00 2001 From: kai Date: Wed, 5 Aug 2026 12:49:41 +0200 Subject: [PATCH] AI Gateway: clarify /compat is required for dynamic routing The Unified API (OpenAI compat) page tells readers the endpoint is deprecated and to use the REST API instead, but dynamic routes can only be invoked through /compat/chat/completions and the REST API page has no dynamic routing coverage at all. Scope the deprecation to single-model calls and add a dynamic routing carve-out on both sides. --- .../docs/ai-gateway/features/dynamic-routing/index.mdx | 8 +++++++- .../docs/ai-gateway/features/dynamic-routing/usage.mdx | 2 +- src/content/docs/ai-gateway/usage/chat-completion.mdx | 8 ++++++-- 3 files changed, 14 insertions(+), 4 deletions(-) diff --git a/src/content/docs/ai-gateway/features/dynamic-routing/index.mdx b/src/content/docs/ai-gateway/features/dynamic-routing/index.mdx index 4fd0ebafa61..299cf3f18fc 100644 --- a/src/content/docs/ai-gateway/features/dynamic-routing/index.mdx +++ b/src/content/docs/ai-gateway/features/dynamic-routing/index.mdx @@ -60,4 +60,10 @@ Ensure your gateway has [authentication](/ai-gateway/configuration/authenticatio - Click **Save** to save the state. You can always roll back to earlier versions from **Versions**. - Deploy the version to make it live. 5. Call the route from your code. - - Use the [OpenAI compatible](/ai-gateway/usage/chat-completion/) endpoint, and use the route name in place of the model, for example, `dynamic/support`. + - Use the [OpenAI compatible](/ai-gateway/usage/chat-completion/) endpoint (`/compat/chat/completions`), and use the route name in place of the model, for example, `dynamic/support`. See [Using a dynamic route](/ai-gateway/features/dynamic-routing/usage/) for examples. + +:::note + +The OpenAI-compatible endpoint is marked **Deprecated** for standard single-model chat completions, but it remains the required way to call dynamic routes. Dynamic routing is not currently available on the [REST API](/ai-gateway/usage/rest-api/). + +::: diff --git a/src/content/docs/ai-gateway/features/dynamic-routing/usage.mdx b/src/content/docs/ai-gateway/features/dynamic-routing/usage.mdx index 72c2fa37068..1dc01ad7401 100644 --- a/src/content/docs/ai-gateway/features/dynamic-routing/usage.mdx +++ b/src/content/docs/ai-gateway/features/dynamic-routing/usage.mdx @@ -1,7 +1,7 @@ --- pcx_content_type: how-to title: Using a dynamic route -description: Send requests through an AI Gateway dynamic route using the OpenAI SDK or REST API. +description: Send requests through an AI Gateway dynamic route using the OpenAI SDK, a direct HTTP request, or the Workers AI binding. sidebar: order: 2 products: diff --git a/src/content/docs/ai-gateway/usage/chat-completion.mdx b/src/content/docs/ai-gateway/usage/chat-completion.mdx index 44a1784dd80..71a8fd06462 100644 --- a/src/content/docs/ai-gateway/usage/chat-completion.mdx +++ b/src/content/docs/ai-gateway/usage/chat-completion.mdx @@ -18,8 +18,12 @@ import { } from "~/components"; import CodeSnippets from "~/components/ai-gateway/code-examples.astro"; -:::caution[Deprecated] -This endpoint is deprecated. Use the [REST API](/ai-gateway/usage/rest-api/) instead, which provides OpenAI-compatible endpoints at `api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/v1/chat/completions`. The `/compat/chat/completions` endpoint will continue to work for existing integrations. +:::caution[Deprecated for single-model calls] +For standard single-model chat completions, this endpoint is deprecated. Use the [REST API](/ai-gateway/usage/rest-api/) instead, which provides OpenAI-compatible endpoints at `api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/v1/chat/completions`. The `/compat/chat/completions` endpoint will continue to work for existing integrations. +::: + +:::note[Required for dynamic routing] +[Dynamic routes](/ai-gateway/features/dynamic-routing/) (`dynamic/{route}`) are invoked through this `/compat/chat/completions` endpoint. The REST API does not currently cover dynamic routing, so continue to use this endpoint when calling a dynamic route. See [Using a dynamic route](/ai-gateway/features/dynamic-routing/usage/) for examples. ::: Cloudflare's AI Gateway offers an OpenAI-compatible `/chat/completions` endpoint, enabling integration with multiple AI providers using a single URL. This feature simplifies the integration process, allowing for seamless switching between different models without significant code modifications.