[Feature] Add API_REFERENCE_BASE_URL and API_REFERENCE_MODEL for control plane setups

[Copilot]

Problem

When setting up LiteLLM with a control plane/data plane architecture, the API Reference page incorrectly displays the control plane (admin) URL in code examples. Users need to see the data plane URL where LLM requests should actually be sent.

From the issue, customers wanted to control both:

1. The URL displayed in API Reference code examples
2. The model name shown in those examples

Before this change:

import openai
client = openai.OpenAI(
    api_key="your_api_key",
    base_url="https://control-plane-url"  # ❌ Wrong - this is the admin endpoint
)
response = client.chat.completions.create(
    model="gpt-3.5-turbo",  # Generic default
    messages=[...]
)

Solution

Added two new environment variables to allow users to customize the API Reference page:

API_REFERENCE_BASE_URL

• Overrides the URL shown in API Reference code examples
• Defaults to PROXY_BASE_URL if not set (backward compatible)
• Perfect for control plane setups where admin URL ≠ data plane URL

API_REFERENCE_MODEL

• Overrides the model name in code examples
• Defaults to gpt-3.5-turbo if not set
• Allows showing the actual model users should use

After this change:

# Admin instance configuration
PROXY_BASE_URL=https://admin.company.com
API_REFERENCE_BASE_URL=https://data-plane.company.com
API_REFERENCE_MODEL=gpt-4

import openai
client = openai.OpenAI(
    api_key="your_api_key",
    base_url="https://data-plane.company.com"  # ✅ Correct data plane URL
)
response = client.chat.completions.create(
    model="gpt-4",  # ✅ Actual deployed model
    messages=[...]
)

Changes

Backend

• Modified /sso/get/ui_settings endpoint to return API_REFERENCE_BASE_URL and API_REFERENCE_MODEL
• Added fallback logic: API_REFERENCE_BASE_URL defaults to PROXY_BASE_URL when not set

Frontend

• Updated APIReferenceView component to use the new configuration values
• Updated all code examples (OpenAI Python SDK, LlamaIndex, Langchain Py) to display the configured URL and model

Tests

• Added test_get_ui_settings_api_reference_config() with comprehensive coverage:
  • Verifies both environment variables are returned correctly
  • Tests fallback behavior when variables are not set
  • Confirms backward compatibility with existing PROXY_BASE_URL

Documentation

• Updated control_plane_and_data_plane.md with configuration examples
• Added detailed explanations of each environment variable's purpose and usage

Use Case: Control Plane Setup

This feature is specifically designed for the control plane and data plane architecture:

# Admin Instance (Control Plane) - Handles management operations
DISABLE_LLM_API_ENDPOINTS=true
PROXY_BASE_URL=https://admin.company.com
API_REFERENCE_BASE_URL=https://us-west.company.com  # Data plane URL
API_REFERENCE_MODEL=gpt-4                            # Your primary model

With this configuration:

• Admin operations use https://admin.company.com
• API Reference page shows https://us-west.company.com in all examples
• Code examples use model="gpt-4" instead of the default

Backward Compatibility

✅ Fully backward compatible:

• If neither environment variable is set, behavior is identical to before
• API_REFERENCE_BASE_URL falls back to PROXY_BASE_URL
• API_REFERENCE_MODEL defaults to gpt-3.5-turbo

Testing

All tests pass:

• ✅ New test: test_get_ui_settings_api_reference_config
• ✅ Existing test: test_get_ui_settings_spend_logs_threshold
• ✅ Manual verification confirms correct UI behavior

Fixes #[issue_number]

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• fonts.googleapis.com
  • Triggering command: /usr/local/bin/node /home/REDACTED/work/litellm/litellm/ui/litellm-dashboard/node_modules/next/dist/compiled/jest-worker/processChild.js (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Feature]: Control Plane - The API Reference should show the data plane URL</issue_title>
<issue_description>### The Feature

Users are setting up control plane through LiteLLM. The API ref shows URL to the management endpoint - but this is wrong

Customers wants to control both URL and model displayed on the page

Motivation, pitch

LiteLLM is hiring a founding backend engineer, are you interested in joining us and shipping to all our users?

No

Twitter / LinkedIn details

No response</issue_description>

Comments on the Issue (you are @copilot in this section)

@ishaan-jaff cc @superpoussin22 @ishaan-jaff

User showed how they want it to render </comment_new>
<comment_new>@ishaan-jaff
They are using this https://docs.litellm.ai/docs/proxy/control_plane_and_data_plane </comment_new>

Fixes #15738

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
litellm	Ready	Preview	Comment	Oct 20, 2025 4:36pm

💡 Enable Vercel Agent with $100 free credit for automated AI reviews

[superpoussin22]

having API_REFERENCE_MODEL is a great too