docs: clarify base URL format for custom OpenAI/Anthropic-compatible BYOM

[paveltiunov]

Check List

• Tests have been run in packages where changes have been made if available (docs only)
• Linter has been run for changed code (docs only)
• Tests for the changes have been added if not covered yet (n/a)
• Docs have been added / updated if required

Description of Changes Made

The Bring Your Own Model page already covered the custom OpenAI-compatible and Anthropic-compatible providers, but it didn't say how to write the base URL. The two providers expect different formats:

• OpenAI-compatible: requests go to <base URL>/chat/completions, so the base URL includes the version segment (https://gateway.acme.com/v1).
• Anthropic-compatible: requests go to <base URL>/v1/messages, so the base URL leaves the version out (https://gateway.acme.com). Copying the OpenAI-style URL here produces /v1/v1/messages.

Also documented, as implemented in getBYOMModel in ai-engineer:

• Custom providers use the same model for every request, including lightweight background calls that built-in models send to a smaller model.
• For Anthropic-compatible, the API key is sent in x-api-key, and extended thinking isn't available.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GPRe2XrbRzYUJVwtgDQWUW

---

Generated by Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
cubed3	🟢 Ready	View Preview	Sep 25, 2026, 6:37 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[claude]

Claude finished @paveltiunov's task in 1m 4s —— View job

---

Docs-only change, mostly good. Please confirm the Anthropic-compatible base-URL rule before merging: 1 medium, 2 low.

Review details

• Read diff and changed file
• Verify claims against the implementation (not possible here: getBYOMModel lives in ai-engineer, which isn't in this repo)
• Review-thread housekeeping
• Post review

Findings

Severity	Location	Issue
Medium	docs-mintlify/admin/ai/bring-your-own-model.mdx:154	I couldn't verify the "omit /v1" rule for Anthropic-compatible. If getBYOMModel uses @ai-sdk/anthropic, requests go to ${baseURL}/messages and the default base URL includes /v1, so the advice would be backwards and cause 404s. Please confirm against the ai-engineer code.
Low	docs-mintlify/admin/ai/bring-your-own-model.mdx:154	"The one difference is the base URL" is followed by two more differences. I posted a suggested rewording.
Low	docs-mintlify/admin/ai/bring-your-own-model.mdx:135	The "same model serves every request" note applies to both custom providers but only appears under OpenAI-compatible.

The OpenAI-compatible rule (keep /v1, requests go to /chat/completions) matches standard OpenAI client behaviour. Placement and length follow docs-mintlify/CLAUDE.md: surgical edits to an existing page, no new sections.

Review threads

The listing returned no prior threads, so none were resolved or re-affirmed. I posted all 3 findings as new inline comments.

[claude]

Claude finished @paveltiunov's task in 49s —— View job

---

LGTM. 0 high, 0 medium, 1 low (nit, not posted inline).

Review details

• Read diff and changed file
• Review content
• Handle prior review threads
• Post review

Findings

Low (nit): docs-mintlify/admin/ai/bring-your-own-model.mdx:154. The "same model serves every request" paragraph for Anthropic-compatible could go into the "Configuration is the same as…" paragraph at :150-152, for example "…optional custom headers with the same placeholders, and the same model serves every request." That saves a two-line paragraph and follows the "say it once" guidance in docs-mintlify/CLAUDE.md. It's optional.

Notes

• The base URL rules are stated clearly and match the implementation the author checked in the thread: OpenAI-compatible posts to <base>/chat/completions (include /v1), and Anthropic-compatible uses ChatAnthropic → @anthropic-ai/sdk, which posts to <base>/v1/messages (leave out /v1). The /v1/v1/messages mistake this prevents is the one users are most likely to hit.
• I couldn't check the claims about the model, x-api-key and extended thinking against the code, because ai-engineer isn't in this repo. They match the author's code references in the review threads.
• The page is docs only, so no tests, security or performance concerns apply. Tone, second person and length follow docs-mintlify/CLAUDE.md.

Review threads

The listing returned 0 of my own unresolved threads, so there are no prior threads: 0 resolved, 0 re-affirmed.