Skip to content

[AI Gateway] Add Workers AI REST API docs and migrate examples to new… #30828

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ethulia wants to merge 4 commits into
base: production
Choose a base branch
from
Open

[AI Gateway] Add Workers AI REST API docs and migrate examples to new… #30828

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b9e9fa9
[AI Gateway] Add Workers AI REST API docs and migrate examples to new…
ethulia May 14, 2026
d7d0208
[AI Gateway] Fix auth docs conflict and wrap Worker example in TypeSc…
ethulia May 14, 2026
08760cc
[AI Gateway] Rename Workers AI REST API to REST API across all pages
ethulia May 14, 2026
e2a3e1b
[AI Gateway] Fix PR review feedback: auth steps, model name, provider…
ethulia May 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions public/__redirects
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -242,6 +242,7 @@
/ai-gateway/universal/ /ai-gateway/usage/universal/ 301
/ai-gateway/chat-completion/ /ai-gateway/usage/chat-completion/ 301
/ai-gateway/legacy-models/ /ai-gateway/supported-models/ 301
/ai-gateway/tutorials/deploy-aig-worker/ /ai-gateway/integrations/aig-workers-ai-binding/ 301

# analytics
/analytics/migration-guides/zone-analytics/ /analytics/graphql-api/migration-guides/zone-analytics/ 301
Expand Down
45 changes: 21 additions & 24 deletions src/content/docs/ai-gateway/configuration/authentication.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,29 +9,26 @@ products:
- ai-gateway
---

Using an Authenticated Gateway in AI Gateway adds security by requiring a valid authorization token for each request. This feature is especially useful when storing logs, as it prevents unauthorized access and protects against invalid requests that can inflate log storage usage and make it harder to find the data you need. With Authenticated Gateway enabled, only requests with the correct token are processed.
AI Gateway requires a valid Cloudflare API token for each request. This prevents unauthorized access and protects against invalid requests that can inflate log storage usage.

:::note
We recommend enabling Authenticated Gateway when opting to store logs with AI Gateway.

If Authenticated Gateway is enabled but a request does not include the required `cf-aig-authorization` header, the request will fail. This setting ensures that only verified requests pass through the gateway. To bypass the need for the `cf-aig-authorization` header, make sure to disable Authenticated Gateway.
:::
When using the [REST API](/ai-gateway/usage/rest-api/), pass your Cloudflare API token in the standard `Authorization` header. When using [provider-native endpoints](/ai-gateway/usage/providers/) at `gateway.ai.cloudflare.com`, use the `cf-aig-authorization` header instead.
Copy link
Copy Markdown
Contributor

@mchenco mchenco May 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the unified Cloudflare REST API?

Copy link
Copy Markdown
Contributor Author

@ethulia ethulia May 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO qualifiers like "unified" only makes sense to people who knew that it was not unified before? but if you're looking at this fresh, it's just the REST API. And if you check the Workers AI docs seeing that it's the same just makes sense.

Copy link
Copy Markdown
Contributor

@mchenco mchenco May 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i do think we should add a Deprecation note

about how gateway.ai.cloudflare.com will still work, but we suggest everyone migrate to the new REST API endpoint?


## Setting up Authenticated Gateway using the Dashboard
## Setting up Authenticated Gateway using the dashboard

1. Go to the Settings for the specific gateway you want to enable authentication for.
2. Select **Create authentication token** to generate a custom token with the required `Run` permissions. Be sure to securely save this token, as it will not be displayed again.
3. Include the `cf-aig-authorization` header with your API token in each request for this gateway.
3. Include the API token in each request:
- If using the REST API (`/ai/run`), include your Cloudflare API token in the standard `Authorization` header.
- If using [provider-native endpoints](/ai-gateway/usage/providers/) at `gateway.ai.cloudflare.com`, use the `cf-aig-authorization` header.
4. Return to the settings page and toggle on Authenticated Gateway.

## Example requests with OpenAI
## Example requests

```bash
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions \
--header 'cf-aig-authorization: Bearer {CF_AIG_TOKEN}' \
--header 'Authorization: Bearer OPENAI_TOKEN' \
--header 'Content-Type: application/json' \
--data '{"model": "gpt-5-mini", "messages": [{"role": "user", "content": "What is Cloudflare?"}]}'
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions" \
Comment thread
mchenco marked this conversation as resolved.
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{"model": "openai/gpt-4.1-mini", "messages": [{"role": "user", "content": "What is Cloudflare?"}]}'
```

Using the OpenAI SDK:
Expand All @@ -40,24 +37,24 @@ Using the OpenAI SDK:
import OpenAI from "openai";

const openai = new OpenAI({
apiKey: process.env.OPENAI_API_KEY,
baseURL: "https://gateway.ai.cloudflare.com/v1/account-id/gateway/openai",
defaultHeaders: {
"cf-aig-authorization": `Bearer {token}`,
},
apiKey: CLOUDFLARE_API_TOKEN,
Copy link
Copy Markdown
Contributor

@mchenco mchenco May 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is it not process.env.CLOUDFLARE_API_TOKEN? (idk)

baseURL: `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/ai/v1`,
});

const response = await openai.chat.completions.create({
model: "openai/gpt-4.1-mini",
messages: [{ role: "user", content: "What is Cloudflare?" }],
});
```

## Example requests with the Vercel AI SDK
Using the Vercel AI SDK:

```javascript
import { createOpenAI } from "@ai-sdk/openai";

const openai = createOpenAI({
baseURL: "https://gateway.ai.cloudflare.com/v1/account-id/gateway/openai",
headers: {
"cf-aig-authorization": `Bearer {token}`,
},
apiKey: CLOUDFLARE_API_TOKEN,
baseURL: `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/ai/v1`,
});
```

Expand Down
6 changes: 4 additions & 2 deletions src/content/docs/ai-gateway/configuration/manage-gateway.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,11 @@ You have several different options for managing an AI Gateway.

### Default gateway

AI Gateway can automatically create a gateway for you. When you use `default` as a gateway ID and no gateway with that ID exists in your account, AI Gateway creates it on the first authenticated request.
AI Gateway can automatically create a gateway for you. If you omit the gateway ID from your request entirely, AI Gateway defaults to using `default` as the gateway ID. When no gateway named `default` exists in your account, AI Gateway creates it on the first authenticated request.

The request that triggers auto-creation must include a valid `cf-aig-authorization` header. An unauthenticated request to a `default` gateway that does not yet exist does not create the gateway.
This means you can start sending requests without creating a gateway first — AI Gateway handles gateway creation for you.

The request that triggers auto-creation must be authenticated. When using the [REST API](/ai-gateway/usage/rest-api/), the standard `Authorization` header is sufficient. When using [provider-native endpoints](/ai-gateway/usage/providers/) at `gateway.ai.cloudflare.com`, include a valid `cf-aig-authorization` header. For Workers AI bindings, the account identity from the binding is used instead of a header.

The auto-created default gateway uses the following settings:

Expand Down
15 changes: 9 additions & 6 deletions src/content/docs/ai-gateway/configuration/request-handling.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,12 +33,15 @@ A timeout is set in milliseconds. The timeout is based on when the first part of

For a provider-specific endpoint, configure the timeout value by adding a `cf-aig-request-timeout` header.

```bash title="Provider-specific endpoint example" {4}
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/workers-ai/@cf/meta/llama-3.1-8b-instruct \
--header 'Authorization: Bearer {cf_api_token}' \
--header 'Content-Type: application/json' \
--header 'cf-aig-request-timeout: 5000'
--data '{"prompt": "What is Cloudflare?"}'
```bash title="Request with timeout" {4}
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions" \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--header "cf-aig-request-timeout: 5000" \
--data '{
"model": "openai/gpt-4.1-mini",
"messages": [{"role": "user", "content": "What is Cloudflare?"}]
}'
```

---
Expand Down
81 changes: 39 additions & 42 deletions src/content/docs/ai-gateway/features/caching.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,20 +96,19 @@ You can use the header **cf-aig-skip-cache** to bypass the cached version of the
As an example, when submitting a request to OpenAI, include the header in the following manner:

```bash title="Request skipping the cache"
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json' \
--header 'cf-aig-skip-cache: true' \
--data ' {
"model": "gpt-4o-mini",
"messages": [
{
"role": "user",
"content": "how to build a wooden spoon in 3 short steps? give as short as answer as possible"
}
]
}
'
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions" \
Comment thread
mchenco marked this conversation as resolved.
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--header "cf-aig-skip-cache: true" \
--data '{
"model": "openai/gpt-4.1-mini",
"messages": [
{
"role": "user",
"content": "how to build a wooden spoon in 3 short steps? give as short as answer as possible"
}
]
}'
```

### Cache TTL (cf-aig-cache-ttl)
Expand All @@ -121,20 +120,19 @@ For example, if you set a TTL of one hour, it means that a request is kept in th
As an example, when submitting a request to OpenAI, include the header in the following manner:

```bash title="Request to be cached for an hour"
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json' \
--header 'cf-aig-cache-ttl: 3600' \
--data ' {
"model": "gpt-4o-mini",
"messages": [
{
"role": "user",
"content": "how to build a wooden spoon in 3 short steps? give as short as answer as possible"
}
]
}
'
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions" \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--header "cf-aig-cache-ttl: 3600" \
--data '{
"model": "openai/gpt-4.1-mini",
"messages": [
{
"role": "user",
"content": "how to build a wooden spoon in 3 short steps? give as short as answer as possible"
}
]
}'
```

### Custom cache key (cf-aig-cache-key)
Expand All @@ -146,20 +144,19 @@ When you use the **cf-aig-cache-key** header for the first time, you will receiv
As an example, when submitting a request to OpenAI, include the header in the following manner:

```bash title="Request with custom cache key"
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions \
--header 'Authorization: Bearer {openai_token}' \
--header 'Content-Type: application/json' \
--header 'cf-aig-cache-key: responseA' \
--data ' {
"model": "gpt-4o-mini",
"messages": [
{
"role": "user",
"content": "how to build a wooden spoon in 3 short steps? give as short as answer as possible"
}
]
}
'
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions" \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--header "cf-aig-cache-key: responseA" \
--data '{
"model": "openai/gpt-4.1-mini",
"messages": [
{
"role": "user",
"content": "how to build a wooden spoon in 3 short steps? give as short as answer as possible"
}
]
}'
```

:::caution[AI Gateway caching behavior]
Expand Down
39 changes: 21 additions & 18 deletions src/content/docs/ai-gateway/features/unified-billing.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,26 +77,29 @@ Refer to the [binding reference](/ai-gateway/integrations/worker-binding-methods

### HTTP API

Call a supported provider through the AI Gateway REST API without passing a provider API key. Use the `cf-aig-authorization` header to authenticate with your Cloudflare API token.
Call a supported provider through the AI Gateway REST API without passing a provider API key.

#### REST API

Use the Cloudflare API to call third-party models. Pass your Cloudflare API token in the `Authorization` header:

```bash
curl -X POST https://gateway.ai.cloudflare.com/v1/$CLOUDFLARE_ACCOUNT_ID/default/compat/chat/completions \
--header "cf-aig-authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header 'Content-Type: application/json' \
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions" \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"model": "google-ai-studio/gemini-2.5-pro",
"messages": [
{
"role": "user",
"content": "What is Cloudflare?"
}
]
"model": "openai/gpt-4.1-mini",
"messages": [{"role": "user", "content": "What is Cloudflare?"}]
}'
```

The `default` gateway is created automatically on your first request. Replace `default` with a specific gateway ID if you have already created one.
Refer to [REST API](/ai-gateway/usage/rest-api/) for more details on all available endpoints.

#### AI Gateway provider-native endpoints

You can also call providers directly through [provider-native endpoints](/ai-gateway/usage/providers/) using the `cf-aig-authorization` header to authenticate:

The HTTP API supports the following providers through [provider-native endpoints](/ai-gateway/usage/providers/) and the [Unified API (chat completions)](/ai-gateway/usage/chat-completion/):
The HTTP API supports the following providers:

- [OpenAI](/ai-gateway/usage/providers/openai/)
- [Anthropic](/ai-gateway/usage/providers/anthropic/)
Expand Down Expand Up @@ -150,12 +153,12 @@ To set ZDR as the default for Unified Billing using the API:
Use the `cf-aig-zdr` header to override the gateway default for a single Unified Billing request. Set it to `true` to force ZDR, or `false` to disable ZDR for the request.

```bash title="Unified Billing request with ZDR"
curl -X POST https://gateway.ai.cloudflare.com/v1/$CLOUDFLARE_ACCOUNT_ID/{gateway_id}/openai/chat/completions \
--header "cf-aig-authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header 'Content-Type: application/json' \
--header 'cf-aig-zdr: true' \
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions" \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--header "cf-aig-zdr: true" \
--data '{
"model": "gpt-4o-mini",
"model": "openai/gpt-4.1-mini",
"messages": [
{
"role": "user",
Expand Down
47 changes: 18 additions & 29 deletions src/content/docs/ai-gateway/get-started.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,7 @@ import {
Render,
TabItem,
Tabs,
Badge,
} from "~/components";
import CodeSnippets from "~/components/ai-gateway/code-examples.astro";

In this guide, you will learn how to set up and use your first AI Gateway.

Expand All @@ -34,11 +32,12 @@ Before making requests, you need two things:
Run the following command to make your first request through AI Gateway:

```bash
curl -X POST https://gateway.ai.cloudflare.com/v1/$CLOUDFLARE_ACCOUNT_ID/default/compat/chat/completions \
--header "cf-aig-authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header 'Content-Type: application/json' \
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions" \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"model": "workers-ai/@cf/meta/llama-3.3-70b-instruct-fp8-fast",
"model": "moonshotai/kimi-k2.6",
"provider": "cloudflare",
"messages": [
{
"role": "user",
Expand All @@ -49,7 +48,7 @@ curl -X POST https://gateway.ai.cloudflare.com/v1/$CLOUDFLARE_ACCOUNT_ID/default
```

:::note
AI Gateway automatically creates a gateway for you on the first request. The gateway is created with [authentication](/ai-gateway/configuration/authentication/) turned on, so the `cf-aig-authorization` header is required for all requests. For more details on how the default gateway works, refer to [Default gateway](/ai-gateway/configuration/manage-gateway/#default-gateway).
You do not need to create a gateway before sending requests. When no gateway ID is specified, AI Gateway uses `default` as the gateway ID and automatically creates it on the first authenticated request. To use a specific gateway, add the `cf-aig-gateway-id` header to your request. For more details, refer to [Default gateway](/ai-gateway/configuration/manage-gateway/#default-gateway).
Copy link
Copy Markdown
Contributor

@ask-bonk ask-bonk Bot May 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This note says the default gateway is auto-created on the first authenticated request, but manage-gateway.mdx states auto-creation requires the cf-aig-authorization header. Please confirm that the Authorization header used here triggers auto-creation, and update manage-gateway.mdx accordingly if so.

:::

<Details header="Create a gateway manually">
Expand All @@ -70,31 +69,21 @@ Authenticate with your upstream AI provider using one of the following options:

## Integration options

### Unified API Endpoint
### REST API

<Badge text="OpenAI Compatible" variant="tip" size="small" /><Badge text="Recommended" variant="success" size="small" />
<br />
<br />

The easiest way to get started with AI Gateway is through our OpenAI-compatible `/chat/completions` endpoint. This allows you to use existing OpenAI SDKs and tools with minimal code changes while gaining access to multiple AI providers.

`
https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat/chat/completions
`

**Key benefits:**

- Drop-in replacement for OpenAI API, works with existing OpenAI SDKs and other OpenAI compliant clients
- Switch between providers by changing the `model` parameter
- Dynamic Routing - Define complex routing scenarios requiring conditional logic, conduct A/B tests, set rate / budget limits, etc


#### Example:

<CodeSnippets forceAPI="unified" />
Call any model — whether hosted on Cloudflare or by a third-party provider — through the same Cloudflare API. No provider SDKs or API keys needed — authentication and billing are handled through your Cloudflare account. Three endpoints are available: `/ai/run` for all modalities, `/ai/v1/chat/completions` for OpenAI SDK compatibility, and `/ai/v1/responses` for agentic workflows.

```bash
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions" \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"model": "openai/gpt-4.1-mini",
"messages": [{"role": "user", "content": "What is Cloudflare?"}]
}'
```

Refer to [Unified API](/ai-gateway/usage/chat-completion/) to learn more about OpenAI compatibility.
Refer to [REST API](/ai-gateway/usage/rest-api/) for details and examples.

### Provider-specific endpoints

Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/ai-gateway/integrations/worker-binding-methods.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@ const resp = await env.AI.run(
Third-party models require an AI Gateway and use [Unified Billing](/ai-gateway/features/unified-billing/). Cloudflare manages the provider credentials and deducts credits from your account. You do not need to supply your own API keys.

:::note
[BYOK (Bring Your Own Keys)](/ai-gateway/configuration/bring-your-own-keys/) is not supported for third-party models called through the AI binding. To use your own provider keys, use the [AI Gateway REST API](/ai-gateway/usage/providers/) or the [chat completions endpoint](/ai-gateway/usage/chat-completion/) instead.
[BYOK (Bring Your Own Keys)](/ai-gateway/configuration/bring-your-own-keys/) is not supported for third-party models called through the AI binding. To use your own provider keys, use the [provider-native endpoints](/ai-gateway/usage/providers/) instead.
:::

Browse available models in the [model catalog](/ai/models/).
Expand Down
Loading