Skip to main content

​
List Models

GET /v1/models
Returns all available models from all connected providers. Compatible with the OpenAI Models API.

​
Request

No parameters required. Include authentication header. 
curl http://localhost:18080/v1/models \
  -H "Authorization: Bearer sk-test-123"

​
Response Format

​
object
string
Always list
​
data
array
Array of model objects

​
Response Example

{
  "object": "list",
  "data": [
    {
      "id": "gemini-2.5-pro",
      "object": "model",
      "created": 1709251200,
      "owned_by": "google"
    },
    {
      "id": "geminicli:gemini-2.5-pro",
      "object": "model",
      "created": 1709251200,
      "owned_by": "google-cli"
    },
    {
      "id": "claude-sonnet-4",
      "object": "model",
      "created": 1709251200,
      "owned_by": "anthropic"
    },
    {
      "id": "ollama:llama3.2",
      "object": "model",
      "created": 1709251200,
      "owned_by": "ollama"
    }
  ]
}

​
Examples

curl http://localhost:18080/v1/models \
  -H "Authorization: Bearer sk-test-123"

​
Model Naming Convention

​
With Provider Prefix

Models with provider prefixes explicitly route to that provider: 
geminicli:gemini-2.5-pro  → Gemini CLI
claudecli:claude-sonnet-4 → Claude CLI
ollama:llama3.2           → Ollama
switchai:auto             → switchAI with auto-routing

​
Without Provider Prefix

Models without prefixes allow auto-routing: 
gemini-2.5-pro   → Any Gemini provider (CLI, API, or switchAI)
claude-sonnet-4  → Any Claude provider
llama3.2         → Auto-detect local provider
See Provider Prefixes for details.

​
Refresh Models

POST /v1/models/refresh
Trigger model re-discovery from all providers. Useful after adding new providers or models.

​
Request

​
provider
string
Optional: Refresh only a specific provider (e.g., ollama, geminicli)

​
Examples

curl -X POST http://localhost:18080/v1/models/refresh \
  -H "Authorization: Bearer sk-test-123"

​
Response

{
  "message": "Model refresh completed",
  "provider": "ollama"
}

​
Gemini Native API

For Gemini-specific clients, use the native endpoint: 
GET /v1beta/models
Returns models in Gemini format with supportedGenerationMethods: 
{
  "models": [
    {
      "name": "models/gemini-2.5-pro",
      "displayName": "Gemini 2.5 Pro",
      "description": "Stable release of Gemini 2.5 Pro",
      "inputTokenLimit": 1048576,
      "outputTokenLimit": 65536,
      "supportedGenerationMethods": [
        "generateContent",
        "countTokens"
      ]
    }
  ]
}

​
Filter by Provider Type

Use the provider status endpoint to filter models: 
GET /v1/providers?filter=active
See Provider Prefixes for filtering options.

​
Model Capabilities

Different models support different features:
CapabilityGeminiClaudeOllamaswitchAI
Chat Completions✅✅✅✅
Streaming✅✅✅✅
Function Calling✅✅⚠️✅
Vision✅✅⚠️✅
JSON Mode✅✅✅✅
Embeddings✅❌✅✅
⚠️ = Model-dependent

​
Model Discovery

switchAILocal automatically discovers models from:
  1. Configuration File: Models defined in config.yaml
  2. CLI Providers: Models detected from installed CLI tools
  3. Local Servers: Models from Ollama, LM Studio
  4. API Providers: Models from authenticated API providers
  5. Dynamic Registration: Models registered at runtime

​
Discovery Sources

# Gemini CLI models discovered from:
gemini models list

# Claude CLI models discovered from:
claude models

# Results cached for performance

​
Troubleshooting

​
No Models Returned

Cause: No providers configured or authenticated Solution:
  1. Verify provider setup: Check config.yaml for API keys
  2. Test CLI tools: Run gemini --version, claude --version
  3. Check logs: Look for provider initialization errors
  4. Try refresh: POST /v1/models/refresh

​
Missing Specific Model

Cause: Provider not authenticated or model not available Solution:
  1. Verify provider access: Test CLI tool directly
  2. Check subscription: Ensure model is in your plan
  3. Refresh models: Force re-discovery
  4. Check spelling: Model IDs are case-sensitive

​
Stale Model List

Cause: Models cached from previous discovery Solution: 
# Force refresh all providers
curl -X POST http://localhost:18080/v1/models/refresh \
  -H "Authorization: Bearer sk-test-123"

​
Next Steps

Provider Prefixes

Learn model routing and provider selection

Chat Completions

Use models for chat completions

Auto-Routing

Let switchAILocal choose the best provider