> ## Documentation Index
> Fetch the complete documentation index at: https://doc.featherhq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List selectable models plus per-role runtime model defaults

> Selectable models + the code-default model each runtime role falls back to.

The role defaults mirror the runtime constants (single-sourced via
``src.runtime.model_defaults.ROLE_DEFAULTS``, which imports the SAME constants
the runtime applies) so the UI can show what's actually used — model + effort +
max_tokens + temperature + thinking budget — when an entity leaves a setting
unset. Imported lazily inside the handler: ``model_router`` deliberately never
imports ``src.runtime`` at module scope (the runtime imports
``model_router.service`` — a top-level import here risks a cycle).



## OpenAPI

````yaml /api-reference/openapi.json get /v1/model-router/catalog
openapi: 3.1.0
info:
  title: Feather API
  description: >-
    Unified customer experience platform API. Manages identity, conversations,
    memory, agents, procedures, policies, model routing, knowledge bases,
    integrations, and runtime execution.
  version: 1.21.0
servers:
  - url: https://api-sandbox.featherhq.com
    description: Sandbox
  - url: http://localhost:8000
    description: Local dev
security: []
paths:
  /v1/model-router/catalog:
    get:
      tags:
        - model-router
      summary: List selectable models plus per-role runtime model defaults
      description: >-
        Selectable models + the code-default model each runtime role falls back
        to.


        The role defaults mirror the runtime constants (single-sourced via

        ``src.runtime.model_defaults.ROLE_DEFAULTS``, which imports the SAME
        constants

        the runtime applies) so the UI can show what's actually used — model +
        effort +

        max_tokens + temperature + thinking budget — when an entity leaves a
        setting

        unset. Imported lazily inside the handler: ``model_router`` deliberately
        never

        imports ``src.runtime`` at module scope (the runtime imports

        ``model_router.service`` — a top-level import here risks a cycle).
      operationId: getModelCatalog
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelCatalogResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - APIKeyHeader: []
components:
  schemas:
    ModelCatalogResponse:
      properties:
        models:
          items:
            $ref: '#/components/schemas/AvailableModel'
          type: array
          title: Models
        role_defaults:
          items:
            $ref: '#/components/schemas/RoleModelDefault'
          type: array
          title: Role Defaults
      type: object
      required:
        - models
        - role_defaults
      title: ModelCatalogResponse
      description: >-
        Selectable models plus the per-role code defaults the runtime falls back
        to.
    ErrorResponse:
      properties:
        error:
          type: string
          title: Error
        message:
          type: string
          title: Message
      type: object
      required:
        - error
        - message
      title: ErrorResponse
      description: Standard error response returned by all API error handlers.
    AvailableModel:
      properties:
        model_identifier:
          type: string
          title: Model Identifier
        provider:
          type: string
          title: Provider
        supports_streaming:
          type: boolean
          title: Supports Streaming
        supports_tools:
          type: boolean
          title: Supports Tools
          default: true
        supports_vision:
          type: boolean
          title: Supports Vision
          default: false
        max_context_window:
          type: integer
          title: Max Context Window
        regions:
          items:
            type: string
          type: array
          title: Regions
        family:
          type: string
          title: Family
          default: default
        supports_json_schema:
          type: boolean
          title: Supports Json Schema
          default: true
        supports_reasoning_effort:
          type: boolean
          title: Supports Reasoning Effort
          default: false
        supports_temperature:
          type: boolean
          title: Supports Temperature
          default: true
        supports_thinking:
          type: boolean
          title: Supports Thinking
          default: false
        supports_audio:
          type: boolean
          title: Supports Audio
          default: false
        compliance_tags:
          items:
            type: string
          type: array
          title: Compliance Tags
        input_price_per_1m:
          type: number
          title: Input Price Per 1M
        output_price_per_1m:
          type: number
          title: Output Price Per 1M
      type: object
      required:
        - model_identifier
        - provider
        - supports_streaming
        - max_context_window
        - input_price_per_1m
        - output_price_per_1m
      title: AvailableModel
    RoleModelDefault:
      properties:
        role:
          type: string
          title: Role
        model:
          type: string
          title: Model
        reasoning_effort:
          anyOf:
            - type: string
            - type: 'null'
          title: Reasoning Effort
        max_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Max Tokens
        temperature:
          anyOf:
            - type: number
            - type: 'null'
          title: Temperature
        thinking_budget:
          anyOf:
            - type: integer
            - type: 'null'
          title: Thinking Budget
      type: object
      required:
        - role
        - model
      title: RoleModelDefault
      description: >-
        A runtime role and its code-default model + generation settings.


        Surfaces the constants the runtime uses when an entity
        (agent/team/workflow)

        has not configured a model, so the UI can show "uses default: <model>".
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-api-key

````