Unified Models API¶
Cross-provider model discovery endpoint that aggregates models from all configured backends.
Endpoints Overview¶
| Method | URI | Description |
|---|---|---|
| GET | /olla/models | List all available models |
| GET | /olla/models/{id} | Get specific model by ID or alias |
| GET | /olla/models?format=unified | Unified format (default) |
| GET | /olla/models?format=openai | OpenAI format |
| GET | /olla/models?format=ollama | Ollama format |
| GET | /olla/models?format=lmstudio | LM Studio format |
| GET | /olla/models?format=vllm | vLLM format |
GET /olla/models¶
Returns all available models across all configured and healthy endpoints.
Query Parameters¶
| Parameter | Type | Default | Description |
|---|---|---|---|
format | string | unified | Response format (unified, openai, ollama, lmstudio, vllm) |
endpoint | string | all | Filter to models served by a specific endpoint name (e.g. local-ollama) |
family | string | all | Filter by model family (e.g. llama, qwen, mistral) |
type | string | all | Filter by model type (llm, vlm, embeddings, reranker, classifier) |
capability | string | all | Legacy filter. vision/multimodal map to type=vlm and embedding/embeddings/vector_search to type=embeddings. chat/text_generation/completion is a capability match, not a kind: it returns every model that can chat or generate text, vision models included |
available | bool | unset | When true, return only models reported available right now; when false, return only currently unavailable models |
include_unavailable | bool | false | When true, include models from endpoints that aren't currently healthy. The response then carries availability metadata per model |
Request Examples¶
Default Unified Format¶
OpenAI Format¶
Filter by Endpoint¶
Filter by Family or Type¶
curl -X GET 'http://localhost:40114/olla/models?family=llama'
curl -X GET 'http://localhost:40114/olla/models?type=vlm'
Filter by Capability (legacy)¶
curl -X GET 'http://localhost:40114/olla/models?capability=vision' # → type=vlm
curl -X GET 'http://localhost:40114/olla/models?capability=chat' # any model that can chat, vlms included
Include Unhealthy Endpoints¶
Response Formats¶
Unified Format (Default)¶
{
"models": [
{
"id": "llama3.2:latest",
"name": "llama3.2:latest",
"provider": "ollama",
"endpoint": "local-ollama",
"capabilities": ["chat", "completion"],
"context_window": 8192,
"max_tokens": 8192,
"vision": false,
"embedding": false,
"available": true,
"metadata": {
"size": "3.8GB",
"modified": "2024-01-15T08:00:00Z",
"family": "llama",
"parameter_size": "3B",
"quantization": "Q4_0"
}
},
{
"id": "phi-3-mini",
"name": "phi-3-mini",
"provider": "lm-studio",
"endpoint": "local-lm-studio",
"capabilities": ["chat", "completion"],
"context_window": 4096,
"max_tokens": 4096,
"vision": false,
"embedding": false,
"available": true,
"metadata": {
"loaded": true,
"gpu_layers": 32
}
}
],
"total": 2,
"providers": {
"ollama": 1,
"lm-studio": 1
}
}
OpenAI Format¶
{
"object": "list",
"data": [
{
"id": "llama3.2:latest",
"object": "model",
"created": 1705334400,
"owned_by": "ollama",
"permission": [],
"root": "llama3.2:latest",
"parent": null
},
{
"id": "phi-3-mini",
"object": "model",
"created": 1705334400,
"owned_by": "lm-studio",
"permission": [],
"root": "phi-3-mini",
"parent": null
}
]
}
Ollama Format¶
{
"models": [
{
"name": "llama3.2:latest",
"model": "llama3.2:latest",
"modified_at": "2024-01-15T08:00:00Z",
"size": 4089352192,
"digest": "sha256:abc123",
"details": {
"parent_model": "",
"format": "gguf",
"family": "llama",
"families": ["llama"],
"parameter_size": "3.2B",
"quantization_level": "Q4_0"
}
}
]
}
LM Studio Format¶
{
"data": [
{
"id": "phi-3-mini",
"object": "model",
"owned_by": "microsoft",
"permission": [],
"engines": {
"chat_completions": {
"context_length": 4096,
"max_tokens": 4096,
"tokenizer": "phi-3"
}
}
}
]
}
vLLM Format¶
{
"object": "list",
"data": [
{
"id": "meta-llama/Meta-Llama-3-8B",
"object": "model",
"created": 1705334400,
"owned_by": "vllm",
"max_model_len": 8192,
"permission": []
}
]
}
Model type¶
Each model reports its kind: llm, vlm, embeddings, reranker or classifier. It appears as olla.type on each entry of the unified format's data array, as type in the /olla/models/{id} response and as type in the LM Studio format, and ?type= filters on it, so ?type=llm returns exactly the models that report olla.type: "llm". A model the backend reports as vlm, or that carries the vision capability, is vlm, so ?type=llm excludes it; use ?capability=chat to list everything that can chat. A model reports one kind: an embedder whose name says instruct is embeddings, not llm. Olla takes the kind from the backend where it reports one (LM Studio and TEI) and otherwise infers it from the model's capabilities, which for backends such as vLLM come from the model name. A model with no reported kind that can generate text is llm. The field is left out of the unified format and the detail response when no kind can be told.
/internal/status/models reports type only when the backend reported a kind (LM Studio, TEI, or an Ollama embedding-only model); it does not infer one from capabilities or names, so a model that /olla/models lists as llm can have no type there. Provider-typed models (vLLM, SGLang, Lemonade, LMDeploy, llama.cpp, vLLM-MLX and Docker Model Runner) no longer carry the provider name as their type.
Response Fields (Unified Format)¶
| Field | Type | Description |
|---|---|---|
models | array | List of available models |
models[].id | string | Unique model identifier |
models[].name | string | Model display name |
models[].provider | string | Provider type (ollama/lmstudio/openai/vllm) |
models[].endpoint | string | Backend endpoint name |
models[].capabilities | array | Supported capabilities |
models[].context_window | integer | Maximum context size |
models[].max_tokens | integer | Maximum output tokens |
models[].vision | boolean | Vision support |
models[].embedding | boolean | Embedding support |
models[].available | boolean | Model availability |
models[].metadata | object | Provider-specific metadata |
total | integer | Total number of models |
providers | object | Model count by provider |
GET /olla/models/{id}¶
Get information about a specific model by its ID or alias.
Request¶
Everything after /olla/models/ is the ID, so IDs that contain slashes, such as Hugging Face style org/name IDs, work as they are:
curl -X GET http://localhost:40114/olla/models/BAAI/bge-small-en-v1.5
curl -X GET 'http://localhost:40114/olla/models/BAAI%2Fbge-small-en-v1.5' # same model, slash percent-encoded
A raw slash and %2F (or %2f) are equivalent, and the path is decoded once, so %252F is looked up as the literal ID %2F. Aliases resolve as well, so a slash-free alias such as qwen3:8b returns the model whose canonical ID is Qwen/Qwen3-8B. An empty ID (/olla/models/) or one ending in a slash returns 400, and an unknown ID returns 404.
Response¶
{
"id": "llama3.2:latest",
"name": "llama3.2:latest",
"provider": "ollama",
"endpoint": "local-ollama",
"capabilities": ["chat", "completion"],
"context_window": 8192,
"max_tokens": 8192,
"vision": false,
"embedding": false,
"available": true,
"metadata": {
"size": "3.8GB",
"modified": "2024-01-15T08:00:00Z",
"family": "llama",
"parameter_size": "3B",
"quantization": "Q4_0"
}
}
Error Responses¶
Model Not Found¶
{
"error": {
"message": "Model not found: unknown-model",
"type": "not_found",
"code": "MODEL_NOT_FOUND"
}
}
No Healthy Endpoints¶
{
"error": {
"message": "No healthy endpoints available",
"type": "service_unavailable",
"code": "NO_ENDPOINTS"
}
}
Invalid Format Parameter¶
{
"error": {
"message": "Invalid format: unsupported. Supported formats: unified, openai, ollama, lmstudio, vllm",
"type": "bad_request",
"code": "INVALID_FORMAT"
}
}
Model Discovery¶
Models are discovered automatically from healthy endpoints:
- Discovery Interval: Every 5 minutes (configurable)
- Discovery Timeout: 30 seconds per endpoint
- Concurrent Workers: 5 workers for parallel discovery
- Retry Policy: 3 attempts with exponential backoff
Caching¶
Model information is cached to improve performance:
- Cache Duration: 5 minutes
- Stale Threshold: 24 hours
- Cleanup Interval: 10 minutes
The cache is invalidated when: - An endpoint becomes unhealthy - Manual refresh is triggered - New endpoints are added