Model Specs Object Structure

Overview

The modelSpecs object helps you provide a simpler UI experience for AI models within your application.

There are 3 main fields under modelSpecs:

• enforce (optional; default: false)
• prioritize (optional; default: true)
• list (required)
• addedEndpoints (optional)

Notes:

• If enforce is set to true, model specifications can potentially conflict with other interface settings such as modelSelect, presets, and parameters.
• The list array contains detailed configurations for each model, including presets that dictate specific behaviors, appearances, and capabilities.
• If interface fields are not specified in the configuration, having a list of model specs will disable the following interface elements:
  • modelSelect
  • parameters
  • presets
• If you would like to enable these interface elements along with model specs, you can set them to true in the interface object.

Example

modelSpecs:
  enforce: true
  prioritize: true
  list:
    - name: 'meeting-notes-gpt4'
      label: 'Meeting Notes Assistant (GPT4)'
      softDefault: true
      description: 'Generate meeting notes by simply pasting in the transcript from a Teams recording.'
      iconURL: 'https://example.com/icon.png'
      showOnLanding: true
      conversation_starters:
        - 'Summarize this meeting transcript'
        - 'Extract action items and owners'
      hideBadgeRow: true
      skills:
        - 'brand-guidelines'
        - 'meeting-notes'
      subagents:
        enabled: true
        allowSelf: true
        agent_ids: []
      preset:
        endpoint: 'azureOpenAI'
        model: 'gpt-4-turbo-1106-preview'
        maxContextTokens: 128000 # Maximum context tokens
        max_tokens: 4096 # Maximum output tokens
        temperature: 0.2
        modelLabel: 'Meeting Summarizer'
        greeting: |
          This assistant creates meeting notes based on transcripts of Teams recordings.
          To start, simply paste the transcript into the chat box.
        promptPrefix: |
          Based on the transcript, create coherent meeting minutes for a business meeting. Include the following sections:
          - Date and Attendees
          - Agenda
          - Minutes
          - Action Items

          Focus on what items were discussed and/or resolved. List any open action items.
          The format should be a bulleted list of high level topics in chronological order, and then one or more concise sentences explaining the details.
          Each high level topic should have at least two sub topics listed, but add as many as necessary to support the high level topic. 

          - Do not start items with the same opening words.

          Take a deep breath and be sure to think step by step.

Top-level Fields

enforce

Default: false

Example:

modelSpecs:
  enforce: true

prioritize

Default: true

Example:

modelSpecs:
  prioritize: false

addedEndpoints

Default: [] (empty list)

Note: Must be one of the following:

• openAI, azureOpenAI, google, anthropic, assistants, azureAssistants, bedrock, agents

Example:

modelSpecs:
  # ... other modelSpecs fields
  addedEndpoints:
    - openAI
    - google

list

Required

Model Spec (List Item)

Within each Model Spec, or each list item, you can configure the following fields:

name

Description: Unique identifier for the model.

label

Description: A user-friendly name or label for the model, shown in the header dropdown.

default

Description:
Specifies if this model spec is the default selection, to be auto-selected on every new chat.

softDefault

Description:

Specifies a first-run default without overriding a user's later selections. Use softDefault when you want to guide new users to a curated spec while preserving user choice after they pick another model, spec, or agent.

Viewing an older conversation that used a soft-default spec does not re-arm that spec as the user's default after they have made another selection.

Example:

modelSpecs:
  list:
    - name: 'general-assistant'
      label: 'General Assistant'
      softDefault: true
      preset:
        endpoint: 'openAI'
        model: 'gpt-4o-mini'

iconURL

Description:
URL or a predefined endpoint name for the model's icon in selector, header, and conversation branding. Use showIconInMenu and showIconInHeader to control where the icon appears.

description

Description: A brief description of the model and its intended use or role, shown in the model selector. If showOnLanding is true, the same description is also shown on the chat landing under the spec label.

Plain text descriptions render as text. Descriptions that start with < render through the config HTML sanitizer, allowing safe inline markup and media such as small icons.

conversation_starters

Description: Conversation starters give users curated first prompts for a model spec. They are shown on the empty chat landing for the selected spec and are especially useful with showOnLanding branding. Clicking a starter submits it as the first message of a new conversation.

• A maximum of 4 starters are displayed, matching the agent/assistant limit.
• If the spec's preset points to an agent or assistant that defines its own conversation starters, those take precedence.

Example:

modelSpecs:
  list:
    - name: 'meeting-notes'
      label: 'Meeting Notes'
      showOnLanding: true
      conversation_starters:
        - 'Summarize this meeting transcript'
        - 'Create action items with owners and due dates'
      preset:
        endpoint: 'agents'
        model: 'gpt-4o'

showOnLanding

Default: false

Use this when a curated model spec should brand the first empty-chat screen. Existing model specs are unchanged unless showOnLanding is set to true.

Example:

modelSpecs:
  list:
    - name: 'branded-assistant'
      label: 'Acme Research'
      description: '<span><img src="/assets/acme.svg" alt="Acme" /> Research with approved sources</span>'
      showOnLanding: true
      iconURL: '/assets/acme.svg'
      preset:
        endpoint: 'openAI'
        model: 'gpt-4o'

group

Description: Optional group name for organizing model specs in the UI selector. The group field provides flexible control over how model specs are organized:

• If group matches an endpoint name (e.g., "openAI", "groq"): The model spec appears nested under that endpoint in the selector menu
• If group is a custom name (doesn't match any endpoint): Creates a separate collapsible section with that name. You can optionally use groupIcon to set a custom icon for this section (URL or built-in key like "openAI")
• If group is omitted: The model spec appears as a standalone item at the top level

This feature is particularly useful when you want to add descriptions to models without losing the organizational structure of the selector menu.

hideBadgeRow

Default: false

Use this when a curated model spec should not show the row of tool/capability badges beneath the composer.

Example:

modelSpecs:
  list:
    - name: 'general-assistant'
      label: 'General Assistant'
      hideBadgeRow: true
      preset:
        endpoint: 'openAI'
        model: 'gpt-4o-mini'

Example:

modelSpecs:
  list:
    # Example 1: Nested under an endpoint
    # When group matches an endpoint name, the spec appears under that endpoint
    - name: 'gpt-4o-optimized'
      label: 'GPT-4 Optimized'
      description: 'Most capable GPT-4 model with multimodal support'
      group: 'openAI' # Appears nested under the OpenAI endpoint
      preset:
        endpoint: 'openAI'
        model: 'gpt-4o'

    # Example 2: Custom group section with icon
    # When group is a custom name, it creates a separate collapsible section
    - name: 'coding-assistant'
      label: 'Coding Assistant'
      description: 'Specialized for coding tasks'
      group: 'My Assistants'
      groupIcon: 'https://example.com/icons/assistants.png' # Custom icon for the group
      preset:
        endpoint: 'openAI'
        model: 'gpt-4o'

    # Multiple specs with the same group name are grouped together
    - name: 'writing-assistant'
      label: 'Writing Assistant'
      description: 'Specialized for creative writing'
      group: 'My Assistants' # Grouped with coding-assistant, uses its icon
      preset:
        endpoint: 'anthropic'
        model: 'claude-sonnet-4'

    # Example 3: Custom group using built-in icon
    - name: 'fast-model'
      label: 'Fast Model'
      group: 'Fast Models'
      groupIcon: 'groq' # Uses built-in Groq icon
      preset:
        endpoint: 'groq'
        model: 'llama3-8b-8192'

    # Example 4: Standalone (no group)
    # When group is omitted, the spec appears at the top level
    - name: 'general-assistant'
      label: 'General Assistant'
      description: 'General purpose assistant'
      # No group field - appears as standalone item at top level
      preset:
        endpoint: 'openAI'
        model: 'gpt-4o-mini'

showIconInMenu

Description:
Controls whether the model's icon appears in the header dropdown menu. Defaults to true.

showIconInHeader

Description:
Controls whether the model's icon appears in the header dropdown button, left of its name. Defaults to true.

authType

Description:
Authentication type required for the model spec. Determines whether authentication is overridden, provided by the user, or defined by the system.

webSearch

Description:
Enables web search capability for this model spec. When set to true, the model can perform web searches to retrieve current information.

Example:

modelSpecs:
  list:
    - name: 'research-assistant'
      label: 'Research Assistant'
      webSearch: true
      preset:
        endpoint: 'openAI'
        model: 'gpt-4o'

fileSearch

Description:
Enables file search capability for this model spec. When set to true, the model can search through and reference uploaded files.

Example:

modelSpecs:
  list:
    - name: 'document-analyst'
      label: 'Document Analyst'
      fileSearch: true
      preset:
        endpoint: 'openAI'
        model: 'gpt-4o'

executeCode

Description:
Enables code execution capability for this model spec. When set to true, the model can execute code in a sandboxed environment.

Example:

modelSpecs:
  list:
    - name: 'code-assistant'
      label: 'Code Assistant'
      executeCode: true
      preset:
        endpoint: 'openAI'
        model: 'gpt-4o'

mcpServers

Description:
List of Model Context Protocol (MCP) server names to enable for this model spec. MCP servers extend the model's capabilities with custom tools and resources.

Example:

modelSpecs:
  list:
    - name: 'enhanced-assistant'
      label: 'Enhanced Assistant'
      mcpServers:
        - 'filesystem'
        - 'sequential-thinking'
        - 'fetch'
      preset:
        endpoint: 'openAI'
        model: 'gpt-4o'

skills

Description:

Controls Skills for this model spec when the Agents endpoint Skills capability is available.

• true: enables the user's active accessible Skill catalog.
• false: disables Skills for this spec.
• Array of Skill names: narrows catalog, manual invocation, and always-apply resolution to the named Skills.

Example:

modelSpecs:
  list:
    - name: 'brand-assistant'
      label: 'Brand Assistant'
      skills:
        - 'brand-guidelines'
        - 'approved-claims'
      preset:
        endpoint: 'agents'
        model: 'gpt-4o'

subagents

Description:

Controls Subagents for ephemeral agents created from this model spec. Use this when you want a curated model spec to expose delegation behavior without requiring users to create or select a persisted parent agent.

• enabled: adds the subagent spawn tool for this model spec.
• allowSelf: lets the ephemeral agent spawn a fresh isolated copy of itself.
• agent_ids: allows specific persisted agents as additional subagents. This list is capped by MAX_SUBAGENTS and remains server-side; startup config sent to clients only includes public enabled and allowSelf flags.

When model specs are enforced, the model spec's subagents settings are authoritative over request payload values.

Example:

modelSpecs:
  list:
    - name: 'research-assistant'
      label: 'Research Assistant'
      subagents:
        enabled: true
        allowSelf: true
        agent_ids: []
      preset:
        endpoint: 'agents'
        model: 'gpt-4o'

artifacts

Description:
Enables the Artifacts capability for this model spec, allowing the model to generate and display interactive artifacts such as React components, HTML, and Mermaid diagrams. When set to true, the default artifact mode is used. You can also specify a mode string directly.

Example:

modelSpecs:
  list:
    - name: 'artifact-assistant'
      label: 'Artifact Assistant'
      artifacts: true
      preset:
        endpoint: 'openAI'
        model: 'gpt-4o'

preset

Description:
Detailed preset configurations that define the behavior and capabilities of the model (see Preset Object Structure below).

Preset Fields

The preset field for a modelSpecs.list item is made up of a comprehensive configuration blueprint for AI models within the system. It is designed to specify the operational settings of AI models, tailoring their behavior, outputs, and interactions with other system components and endpoints.

System Options

endpoint

Required

Accepted Values:

• openAI
• azureOpenAI
• google
• anthropic
• assistants
• azureAssistants
• bedrock
• agents

Note: If you are using a custom endpoint, the endpoint value must match the defined custom endpoint name exactly.

Example:

preset:
  endpoint: 'openAI'

modelLabel

Default: None

Example:

preset:
  modelLabel: 'Customer Support Bot'

greeting

Default: None

Example:

preset:
  greeting: 'This assistant creates meeting notes based on transcripts of Teams recordings. To start, simply paste the transcript into the chat box.'

promptPrefix

Default: None

Example 1:

preset:
  promptPrefix: 'As a financial advisor, ...'

Example 2:

preset:
  promptPrefix: |
    Based on the transcript, create coherent meeting minutes for a business meeting. Include the following sections:
    - Date and Attendees
    - Agenda
    - Minutes
    - Action Items

    Focus on what items were discussed and/or resolved. List any open action items.
    The format should be a bulleted list of high level topics in chronological order, and then one or more concise sentences explaining the details.
    Each high level topic should have at least two sub topics listed, but add as many as necessary to support the high level topic. 

    - Do not start items with the same opening words.

    Take a deep breath and be sure to think step by step.

resendFiles

Default: true

Example:

preset:
  resendFiles: true

imageDetail

Accepted Values:

• low
• auto
• high

Default: "auto"

Example:

preset:
  imageDetail: 'high'

maxContextTokens

Example:

preset:
  maxContextTokens: 4096

Agent Options

Note that these options are only applicable when using the agents endpoint.

You should exclude any model options and defer to the agent's configuration as defined in the UI.

agent_id

Example:

preset:
  agent_id: 'agent_someUniqueId'

Assistant Options

Note that these options are only applicable when using the assistants or azureAssistants endpoint.

Similar to Agents, you should exclude any model options and defer to the assistant's configuration.

assistant_id

Example:

preset:
  assistant_id: 'asst_someUniqueId'

instructions

Note: this is distinct from promptPrefix, as this overrides existing assistant instructions for current runs.

Only use this if you want to override the assistant's core instructions.

Use promptPrefix for additional_instructions.

More information:

• https://platform.openai.com/docs/api-reference/models#runs-createrun-instructions
• https://platform.openai.com/docs/api-reference/runs/createRun#runs-createrun-additional_instructions

Example:

preset:
  instructions: 'Please handle customer queries regarding order status.'

append_current_datetime

Adds the current date and time to additional_instructions for each run. Does not overwrite promptPrefix, but adds to it.

Example:

preset:
  append_current_datetime: true

Model Options

Note: Each parameter below includes a note on which endpoints support it.
OpenAI / AzureOpenAI / Custom typically support temperature, presence_penalty, frequency_penalty, stop, top_p, max_tokens.
Google / Anthropic typically support topP, topK, maxOutputTokens; Google also supports url_context on supported Gemini text models. Anthropic / OpenRouter / Bedrock (Anthropic and Nova models) support promptCache and promptCacheTtl. Bedrock supports region, maxTokens, and a few others.

model

Supported by: All endpoints (except agents)

Default: None

Example:

preset:
  model: 'gpt-4-turbo'

temperature

Supported by: openAI, azureOpenAI, google (as temperature), anthropic (as temperature), and custom (OpenAI-like)

Example:

preset:
  temperature: 0.7

presence_penalty

Supported by: openAI, azureOpenAI, custom (OpenAI-like)
Not typically used by Google/Anthropic/Bedrock

Example:

preset:
  presence_penalty: 0.3

frequency_penalty

Supported by: openAI, azureOpenAI, custom (OpenAI-like)
Not typically used by Google/Anthropic/Bedrock

Example:

preset:
  frequency_penalty: 0.5

stop

Supported by: openAI, azureOpenAI, custom (OpenAI-like)
Not typically used by Google/Anthropic/Bedrock

Example:

preset:
  stop:
    - 'END'
    - 'STOP'

top_p

Supported by: openAI, azureOpenAI, custom (OpenAI-like)
Google/Anthropic often use topP (capital “P”) instead of top_p.

Example:

preset:
  top_p: 0.9

topP

Supported by: google & anthropic
(similar purpose to top_p, but named differently in those APIs)

Example:

preset:
  topP: 0.8

topK

Supported by: google & anthropic
(k-sampling limit on the next token distribution)

Example:

preset:
  topK: 40

max_tokens

Supported by: openAI, azureOpenAI, custom (OpenAI-like)
For Google/Anthropic, use maxOutputTokens or maxTokens (depending on the endpoint).

Example:

preset:
  max_tokens: 4096

maxOutputTokens

Supported by: google, anthropic
Equivalent to max_tokens for these providers.

Example:

preset:
  maxOutputTokens: 2048

promptCache

Supported by: anthropic, OpenRouter custom endpoints, bedrock (Anthropic and Nova models) (Toggle provider prompt caching)

Default: true

Example:

preset:
  promptCache: true

Note: For Bedrock endpoints, prompt caching is automatically enabled for Claude and Nova models. Set promptCache: false to explicitly disable it.

promptCacheTtl

Supported by: anthropic, OpenRouter custom endpoints, bedrock (Anthropic and Nova models) (Sets the prompt-cache lifetime when prompt caching is enabled)

Accepted Values:

• 5m
• 1h

Example:

preset:
  promptCache: true
  promptCacheTtl: '1h'

Note: promptCacheTtl is ignored when prompt caching is disabled. When omitted, the provider integration uses its default prompt-cache lifetime.

reasoning_effort

Accepted Values:

• "" (empty string — unset, uses API default)
• "none"
• "minimal"
• "low"
• "medium"
• "high"
• "xhigh" (extra high)

Supported by: openAI, azureOpenAI, custom (OpenAI-like), bedrock (ZAI, MoonshotAI models)

Default: "" (unset)

Example:

preset:
  reasoning_effort: 'low'

reasoning_summary

Accepted Values:

• "" (empty string — disables reasoning summaries)
• "auto"
• "concise"
• "detailed"

Supported by: openAI, azureOpenAI, custom (OpenAI-like)

Default: "" (disabled)

Example:

preset:
  reasoning_summary: 'detailed'

useResponsesApi

Supported by: openAI, azureOpenAI, custom (OpenAI-like)

Default: false

Example:

preset:
  useResponsesApi: true

verbosity

Accepted Values:

• "" (empty string — unset, uses API default)
• "low"
• "medium"
• "high"

Supported by: openAI, azureOpenAI, custom (OpenAI-like)

Default: "" (unset)

Example:

preset:
  verbosity: 'low'

web_search

Supported by: openAI, azureOpenAI, custom (OpenAI-like), google, anthropic

Default: false

Note: For Google endpoints, this parameter appears as Grounding with Google Search in the actual panel but controls web_search in the implementation.

Example:

preset:
  web_search: true

url_context

Supported by: google on supported Gemini text models, including Gemini 2.5+ and Gemini 3.x

Default: false

Example:

preset:
  url_context: true

disableStreaming

Supported by: openAI, azureOpenAI, custom (OpenAI-like)

Default: false

Example:

preset:
  disableStreaming: true

thinkingBudget

Supported by: google, anthropic, bedrock (Anthropic models)

Default: "Auto (-1)" (Google), 2000 (Anthropic, Bedrock (Anthropic models))

Example:

preset:
  thinkingBudget: '2000'

thinkingLevel

Supported by: google (Gemini 3+ models)

Accepted Values:

• "" (unset/auto)
• "minimal"
• "low"
• "medium"
• "high"

Default: "" (unset — model decides)

Example:

preset:
  thinkingLevel: 'medium'

effort

Supported by: anthropic, bedrock (Anthropic models)

Options: "" (unset/auto), "low", "medium", "high", "xhigh", "max"

Default: "" (unset — model decides)

Example:

preset:
  effort: 'high'

thinkingDisplay

Supported by: anthropic, bedrock (Anthropic models)

Options: "auto" (default), "summarized", "omitted"

• "auto" — LibreChat decides: opts in to "summarized" for models that omit thinking by default (Opus 4.7+ and Fable/Mythos-class), leaves the field off for older models
• "summarized" — always request a post-hoc summary of the reasoning
• "omitted" — always suppress reasoning content (slightly lower latency)

Default: "auto"

Example:

preset:
  thinkingDisplay: 'summarized'

thinking

Supported by: google, anthropic, bedrock (Anthropic models)

Default: true

Example:

preset:
  thinking: true

region

Supported by: bedrock
(Used to specify an AWS region for Amazon Bedrock)

Example:

preset:
  region: 'us-east-1'

maxTokens

Supported by: bedrock
(Used in place of max_tokens)

Example:

preset:
  maxTokens: 1024