---
title: "List models"
method: GET
path: "/api/v1/models"
tags: ["Models"]
---

# List models

`GET /api/v1/models`

## Request

- Base URL: `https://your-deployment.example.com`
- URL: `https://your-deployment.example.com/api/v1/models`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Lists the models the caller can use right now - the platform catalog filtered to the providers the caller has a key for, their own or the platform's. Use it to choose a `model` by capability before calling a generation endpoint: `context_window` and `max_output_tokens` for text models, and for image models the `image` block, which lists the accepted `size` values (or the rule they must meet) and whether `background`, `seed`, `quality`, `n` and reference images are honoured. To pick the cheapest text model, compare `credits_per_1m_tokens` - the rate a call is billed at. The list is cached for up to a minute per caller. Cursor-paginated (see the pagination convention): pass `next_cursor` back as `cursor` until it is `null`. Sorted by `id` ascending. Authenticate with an API key (`b4m_live_`) carrying `ai:chat` or `ai:generate`, or a JWT.

## Query parameters

- `limit` integer
- `cursor` string

## Response `200`

One page of models, ordered by `id`.

- ListModelsResponse200
  - `data` object[], required
    - `id` string, required: Pass as `model` on the generation endpoints.
    - `name` string, required
    - `type` 'text' | 'image' | 'speech-to-text' | 'video', required
    - `backend` 'openai' | 'bedrock' | 'anthropic' | 'gemini' | 'ollama' | 'bfl' | 'xai' | 'kimi' | 'deepseek' | 'voyageai' | 'aws' | 'local-image', required: The provider that serves the model.
    - `description` string, nullable, required
    - `context_window` integer, required: Input context, in tokens.
    - `max_output_tokens` integer, required
    - `supports_streaming` boolean, required
    - `supports_thinking` boolean, required
    - `reasons_within_output_budget` boolean, required: Whether reasoning tokens are spent inside `max_output_tokens` on every turn. When true, a small `max_tokens` can be used up by reasoning alone and return an empty reply, so leave room above the answer you expect.
    - `reasoning_efforts` string[], required: The `reasoningEffort` levels this model acts on, lowest first; empty when it ignores the option. `none` is listed only where it turns reasoning off. Each level is mapped to the nearest one the provider offers. A listed level can still be dropped on one request: some OpenAI models drop it on tool turns, and Claude models with a fixed thinking budget drop it when `max_tokens` leaves no room for the budget plus the answer.
    - `supports_tools` boolean, required
    - `supports_tool_search` boolean, required: Whether the model accepts the tool search server tool and `defer_loading: true` on tool definitions, so a large tool catalog is searched on demand instead of loaded into context up front. Describes the model: `/api/ai/v1/completions` honours it only for models whose `backend` is `anthropic`. A `bedrock` model with this flag set is not served with tool search there yet: a `serverTool` entry is refused with `errorCode: "tool_search_unsupported"` and `defer_loading` is ignored.
    - `supports_tool_changes` boolean, required: Whether a system-role message can carry `tool_addition` and `tool_removal` blocks, which add or remove a declared tool mid-conversation. Describes the model only: `/api/ai/v1/completions` does not accept these blocks yet, and will accept them first for models whose `backend` is `anthropic`.
    - `supports_vision` boolean, required
    - `deprecation_date` string, nullable, required: `YYYY-MM-DD`; null when no retirement is scheduled.
    - `replaced_by` string, nullable, required: The id of the recommended successor, when there is one.
    - `image` object, nullable, required: Size rules and supported parameters. Present on image models only; null for every other type.
      - `sizing` union, required
        - object
          - `kind` 'presets', required
          - `presets` string[], required: Accepted `size` values, as `WxH`.
          - `default_size` string, required
        - object
          - `kind` 'constrained', required
          - `presets` string[], required: Suggested `size` values; any `WxH` meeting `constraints` is accepted.
          - `default_size` string, required
          - `auto_size` string, required: The `size` value that lets the provider choose.
          - `constraints` object, required
            - `max_edge` integer, required
            - `min_total_pixels` integer, required
            - `max_total_pixels` integer, required
            - `edge_multiple` integer, required: Both edges must be a multiple of this.
            - `max_aspect_ratio` number, required: Longest edge divided by shortest edge.
        - object
          - `kind` 'dimensions', required
          - `presets` string[], required
          - `default_size` string, required
          - `min_width` integer, required
          - `max_width` integer, required
          - `min_height` integer, required
          - `max_height` integer, required
          - `step` integer, required: `width` and `height` are rounded to the nearest multiple of this.
        - object
          - `kind` 'aspect_ratio', required: Takes an `aspect_ratio` such as `16:9`, not a `size`.
        - object
          - `kind` 'input_image', required: Sized by the input image; takes no `size`.
          - `aspect_ratio` boolean, required: Whether an `aspect_ratio` override is honoured.
        - object
          - `kind` 'fixed', required: The provider takes no size at all.
      - `supports` object, required
        - `transparent_background` boolean, required: `background: 'transparent'` yields real alpha.
        - `seed` boolean, required
        - `qualities` string[], required: Accepted `quality` tiers; empty when none is taken.
        - `max_images` integer, required: Most images one request may ask for via `n`.
        - `max_reference_images` integer, required: Most `referenceImageFabFileIds` honoured; 0 when the model takes none.
        - `edit` boolean, required: Accepted by `POST /api/v1/image-edits`.
        - `requires_input_image` boolean, required
    - `credits_per_1m_tokens` object, nullable, required: What a call is billed, in credits per 1M tokens, at the base context tier. Use it to compare models by cost. Null on non-text models and on any model with no published price; never 0 for an unpriced model.
      - `input` number, required: Credits per 1M input tokens.
      - `output` number, required: Credits per 1M output tokens.
      - `cached_input` number, nullable, required: Credits per 1M input tokens served from the provider prompt cache. Null where cached tokens are not billed separately, so they cost the `input` rate.
  - `next_cursor` string, nullable, required

## Other responses

- `401`: Missing or invalid credentials.
- `403`: The API key does not hold any of the required scopes.
- `405`: The path does not serve this HTTP method.
- `422`: `limit` is out of range, or `cursor` is malformed or was issued by a different endpoint. A cursor is opaque: pass back exactly the `next_cursor` you were given.
- `429`: Per-user rate limit exceeded.

---

[API](https://skmtc.dev/bike4mind/apis/bike4mind-api.md) · [All operations](https://skmtc.dev/bike4mind/apis/bike4mind-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bike4mind/apis/bike4mind-api/revisions/db47495b892f?raw)