Ai-gateway: add endpoint-model compatibility matrix to REST API docs.mdx

[dpiteira95]

The AI Gateway REST API documentation currently lists four endpoints (/ai/run, /ai/v1/chat/completions, /ai/v1/responses, /ai/v1/messages) without clarifying which endpoints support Workers AI models (@cf/) versus third-party models only.

This has led to user confusion, as the "/ai/v1/messages" endpoint (Anthropic SDK compatible) rejects Workers AI models with: "AiError: Anthropic Messages API is not supported for model" despite the "unified API" messaging implying broad compatibility.

Changes proposed:

• Add a compatibility matrix to the Endpoints section showing support for third-party models and Workers AI models per endpoint
• Add an explicit warning note below the matrix clarifying that /ai/v1/messages supports Anthropic/third-party models only, and Workers AI models should use /ai/run, /ai/v1/chat/completions, or /ai/v1/responses instead

Proposed matrix:

Endpoint	Format	Third-party models	Workers AI models (@cf/)
POST /ai/run	Universal envelope	Yes	Yes
POST /ai/v1/chat/completions	OpenAI SDK compatible	Yes	Yes
POST /ai/v1/responses	OpenAI Responses API compatible	Yes	Yes
POST /ai/v1/messages	Anthropic SDK compatible	Yes	No

This aligns the documentation with actual API behavior.

[cloudflare-docs-bot]

Review

✅ No issues found in commit 4cf8033.

Fan Out Code Review

This code review is in beta and may not always be helpful — use your judgment.

✅ No code review issues found.

Style Guide Review

✅ No style-guide issues found.

Commands

Only codeowners can run commands. Post a comment with the command to trigger it.

Command	Description
/review	Runs a review now. Incremental if a prior review exists, full if not.
/full-review	Re-reviews the entire PR diff from scratch, ignoring incremental history. Useful after a rebase, when you want a fresh review, or if the bot gets out of sync and reports issues that no longer exist.
/fan-out-review	Forces a full review using the per-file fan-out mode regardless of diff size. Each file is reviewed in its own session for maximum per-file detail. ⚠️ This may take a very long time on large PRs and may fail or time out — use only when you want the most thorough review and are willing to wait.
/holistic-review	Forces a full review using the holistic mode regardless of diff size. The entire diff is reviewed in one pass, enabling cross-file reasoning. Faster and more reliable on large PRs.
/ignore-review-limit	Permanently lifts the 2-review automatic limit for this PR. Future pushes will trigger reviews as normal.