Listing Models

Every DeepFellow deployment exposes a different set of models, and every project reaches only the subset its permissions allow. The Models endpoints tell you which models the credential you hold will actually reach, and, on request, what each model supports.

Listing Available Models

To list the models available to your project, call the models endpoint:

curl -X 'GET' \
  'https://deepfellow-server-host/v1/models' \
  -H "Authorization: Bearer DEEPFELLOW-PROJECT-API-KEY"

from openai import OpenAI
client = OpenAI(
    base_url="https://deepfellow-server-host/v1",
    api_key="DEEPFELLOW-PROJECT-API-KEY"
)

response = client.models.list()

print(response.model_dump_json())

import OpenAI from 'openai';

const client = new OpenAI({
    baseURL: 'https://deepfellow-server-host/v1',
    apiKey: 'DEEPFELLOW-PROJECT-API-KEY'
});

const response = await client.models.list();

console.log(response);

The response is OpenAI-compatible, so every OpenAI client library reads it without modification:

{
    "object": "list",
    "data": [
        {
            "id": "gemma3:1b",
            "object": "model",
            "created": 0,
            "owned_by": "unknown"
        },
        {
            "id": "deepseek-r1:14b",
            "object": "model",
            "created": 0,
            "owned_by": "unknown"
        }
    ]
}

Retrieving a Single Model

To retrieve one model, append its identifier to the path:

curl -X 'GET' \
  'https://deepfellow-server-host/v1/models/gemma3:1b' \
  -H "Authorization: Bearer DEEPFELLOW-PROJECT-API-KEY"

The response holds a single model object in the same shape as one entry of the list.

Model identifiers that contain a slash, such as speaches-ai/Kokoro-82M, work in the path without escaping.

Requesting Extended Model Data

The OpenAI-compatible model object carries only id, object, created, and owned_by. It says nothing about what the model does. To learn a model's context window, the endpoints it serves, or the tools it exposes, set the additional_data query parameter to true:

curl -X 'GET' \
  'https://deepfellow-server-host/v1/models?additional_data=true' \
  -H "Authorization: Bearer DEEPFELLOW-PROJECT-API-KEY"

Each model object then carries an extra props object:

{
    "object": "list",
    "data": [
        {
            "id": "gemma3:1b",
            "object": "model",
            "created": 0,
            "owned_by": "unknown",
            "props": {
                "private": true,
                "type": "llm",
                "endpoints": [
                    "/v1/completions",
                    "/v1/chat/completions",
                    "/v1/responses",
                    "/v1/messages",
                    "/api/chat"
                ],
                "context_window": 4096,
                "max_context_window": 32768,
                "prefix": null,
                "transport": null,
                "tools": []
            }
        }
    ]
}

The parameter works the same way on a single model:

curl -X 'GET' \
  'https://deepfellow-server-host/v1/models/gemma3:1b?additional_data=true' \
  -H "Authorization: Bearer DEEPFELLOW-PROJECT-API-KEY"

A response with props is no longer OpenAI-compatible. Request it with a plain HTTP call rather than an OpenAI client library, which will drop the extra field. The parameter defaults to false, so a client that never sets it always receives the compatible shape.

Model Properties

The props object describes what a model supports:

Property	Type	Description
`private`	boolean	Whether the model runs inside your DeepFellow deployment. A private model never sends data to an external provider.
`type`	string	The kind of model: `llm`, `embedding`, `tts`, `stt`, `rerank`, `txt2img`, `mcp`, or `custom`. The `mcp` type marks an MCP server, and `custom` marks a custom endpoint.
`endpoints`	string[]	The API endpoints the model serves, for example `/v1/chat/completions` or `/v1/embeddings`.
`context_window`	integer \| null	The context window the model currently runs with, in tokens.
`max_context_window`	integer \| null	The largest context window the model supports, in tokens.
`prefix`	string \| null	The identifier prefix that groups the models coming from one MCP server or one custom endpoint.
`transport`	string \| null	The transport an MCP server communicates over, for example `streamable_http`.
`tools`	object[]	The tools an MCP server exposes, each with a `name`, a `description`, and an `input_schema`. Empty for every other model type.

Use type and endpoints together to decide where a model belongs. An embedding model serves the Embeddings endpoint, and an llm model serves chat completions. One deployment holds models of every type, so the plain list alone will not tell you which model fits your call.

Project Permissions

The list returns only the models the authorizing project reaches. A project restricts access through three settings, described in Authorization:

models limits the regular models the project reaches.
mcp_prefixes limits the MCP servers the project reaches.
custom_endpoints limits the custom endpoints the project reaches.

A setting of all places no restriction. When a setting holds a list instead, the endpoint filters the response down to that list, so two projects on one deployment will see two different sets of models.

Retrieving a single model follows the same rule. A model the project does not reach returns 404, exactly as a model that does not exist.

API Reference

For the full request and response schemas, see the API reference: