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

# Models Configuration

> Every provider, model, override, and compatibility field accepted in models.json, generated from the schema.

# Models Configuration

This reference lists the fields of `models.json`. See [Custom Models](/models) for examples and the file location (normally `~/.atomic/agent/models.json`).

Add `"$schema": "https://raw.githubusercontent.com/bastani-inc/atomic/main/packages/coding-agent/schemas/models.schema.json"` to `models.json` for editor validation and completion.

## Providers

Each key under `providers` is a provider ID. A built-in provider ID changes that provider. Any other ID adds a provider, which needs `baseUrl` and an `api` at provider or model level.

| Field | Type | Default | Description |
| - | - | - | - |
| `name` | string | | Display name. |
| `baseUrl` | string | | API base URL. Also applies to the provider's built-in models. |
| `apiKey` | string | | Literal key, "\$NAME" environment interpolation, or "!command" output. |
| `api` | string | | API for the provider's models, such as "openai-completions", "openai-responses", "anthropic-messages", or "google-generative-ai". |
| `oauth` | `"radius"` | | OAuth login flow. Requires baseUrl. |
| `headers` | object | | Request headers. Values resolve like apiKey. |
| `compat` | [object](#compatibility) | | Provider and model compatibility overrides. |
| `authHeader` | boolean | `false` | Whether to send the resolved API key as Authorization: Bearer. |
| `models` | [`object[]`](#models) | | |
| `modelOverrides` | [object](#model-overrides) | | |

## Models

Each `models` entry adds a model to the provider. An entry whose `id` matches an existing model replaces it.

| Field | Type | Default | Description |
| - | - | - | - |
| `id` | string | | Required. Model ID sent to the API. |
| `name` | string | | Display name, also matched by --model patterns. |
| `api` | string | | Overrides the provider api. |
| `baseUrl` | string | | Overrides the provider baseUrl. |
| `reasoning` | boolean | `false` | Whether the model supports thinking. |
| `thinkingLevelMap` | object | | Provider value sent for each thinking level. null marks a level unsupported. Levels the model does not map use the provider's default value through high; xhigh and max are unsupported. |
| `input` | `("text" \| "image" \| "pdf")[]` | `["text"]` | |
| `inputLimits` | [object](#input-limits) | | |
| `cost` | object | | |
| `cost.input` | number | | Required. Input cost in USD per million tokens. |
| `cost.output` | number | | Required. Output cost in USD per million tokens. |
| `cost.cacheRead` | number | | Required. Cache-read cost in USD per million tokens. |
| `cost.cacheWrite` | number | | Required. Cache-write cost in USD per million tokens. |
| `cost.tiers` | `object[]` | | Request-wide pricing tiers. The highest matching input threshold applies to the full request. |
| `cost.tiers[].inputTokensAbove` | number | | Required. Use this tier when total request input exceeds this token count. |
| `cost.tiers[].input` | number | | Required. Input cost in USD per million tokens. |
| `cost.tiers[].output` | number | | Required. Output cost in USD per million tokens. |
| `cost.tiers[].cacheRead` | number | | Required. Cache-read cost in USD per million tokens. |
| `cost.tiers[].cacheWrite` | number | | Required. Cache-write cost in USD per million tokens. |
| `promptCache` | object | | Best-effort prompt cache lifetime in seconds for the short and long retention tiers. Atomic warms only tiers with a known lifetime. |
| `contextWindow` | number | `128000` | Context window in tokens. |
| `maxTokens` | number | `16384` | Maximum output tokens. |
| `samplingParams` | object | | Fields merged into every request body. Applies only to OpenAI-compatible APIs. |
| `samplingParamsByThinkingLevel` | object | | samplingParams per thinking level, merged over samplingParams. |
| `headers` | object | | Request headers. Values resolve like apiKey. |
| `compat` | [object](#compatibility) | | Provider and model compatibility overrides. |

## Model overrides

Each `modelOverrides` key is the ID of a built-in or extension model. Unknown IDs are ignored. Object fields, such as `cost`, merge with the model's value field by field; other fields replace it.

| Field | Type | Default | Description |
| - | - | - | - |
| `name` | string | | Display name, also matched by --model patterns. |
| `reasoning` | boolean | | Whether the model supports thinking. |
| `thinkingLevelMap` | object | | Provider value sent for each thinking level. null marks a level unsupported. Levels the model does not map use the provider's default value through high; xhigh and max are unsupported. |
| `input` | `("text" \| "image" \| "pdf")[]` | | |
| `inputLimits` | [object](#input-limits) | | |
| `cost` | object | | |
| `cost.input` | number | | Input cost in USD per million tokens. |
| `cost.output` | number | | Output cost in USD per million tokens. |
| `cost.cacheRead` | number | | Cache-read cost in USD per million tokens. |
| `cost.cacheWrite` | number | | Cache-write cost in USD per million tokens. |
| `cost.tiers` | `object[]` | | Request-wide pricing tiers. The highest matching input threshold applies to the full request. |
| `cost.tiers[].inputTokensAbove` | number | | Required. Use this tier when total request input exceeds this token count. |
| `cost.tiers[].input` | number | | Required. Input cost in USD per million tokens. |
| `cost.tiers[].output` | number | | Required. Output cost in USD per million tokens. |
| `cost.tiers[].cacheRead` | number | | Required. Cache-read cost in USD per million tokens. |
| `cost.tiers[].cacheWrite` | number | | Required. Cache-write cost in USD per million tokens. |
| `promptCache` | object | | Best-effort prompt cache lifetime in seconds for the short and long retention tiers. Atomic warms only tiers with a known lifetime. |
| `contextWindow` | number | | Context window in tokens. |
| `maxTokens` | number | | Maximum output tokens. |
| `samplingParams` | object | | Fields merged into every request body. Applies only to OpenAI-compatible APIs. |
| `samplingParamsByThinkingLevel` | object | | samplingParams per thinking level, merged over samplingParams. |
| `headers` | object | | Request headers. Values resolve like apiKey. |
| `compat` | [object](#compatibility) | | Provider and model compatibility overrides. |

## Input limits

See [Image Input Limits](/models/reference#image-input-limits).

| Field | Type | Default | Description |
| - | - | - | - |
| `maxRequestBytes` | integer | | Maximum serialized provider request size in bytes. |
| `images` | object | | |
| `images.resize` | object | | Cache-safe resize profile applied before a new image enters conversation history. |
| `images.resize.maxWidth` | integer | | |
| `images.resize.maxHeight` | integer | | |
| `images.resize.maxBytes` | integer | | Maximum base64-encoded payload size in bytes. |
| `images.resize.jpegQuality` | integer | | |
| `images.maxPerMessage` | integer | | Maximum images accepted in one provider message. |
| `images.maxPerRequest` | integer | | Maximum images accepted across one provider request. |

## Compatibility

`compat` describes verified differences from an API's standard request and response behavior. Model values override provider values per field. The fields that apply depend on the model's `api`.

### `openai-completions`

| Field | Type | Default | Description |
| - | - | - | - |
| `supportsStore` | boolean | | Whether the provider supports the store field. Default: auto-detected from URL. |
| `supportsDeveloperRole` | boolean | | Whether the provider supports the developer role instead of system. Default: auto-detected from URL. |
| `supportsReasoningEffort` | boolean | | Whether the provider supports reasoning\_effort. Default: auto-detected from URL. |
| `supportsTemperature` | boolean | `true` | Whether the model accepts the temperature request field. When false, the provider omits temperature and also strips temperature, top\_p, and top\_k from samplingParams. |
| `supportsForcedToolChoice` | boolean | `true` | Whether the model accepts forced tool use (tool\_choice "required" or a specific function). When false, the provider rejects a forced choice with an error instead of sending a request the model cannot honor. "auto" and "none" are never altered. |
| `supportsUsageInStreaming` | boolean | `true` | Whether the provider supports stream\_options.include\_usage for token usage in streaming responses. |
| `supportsFinishReason` | boolean | `true` | Whether streamed responses include finish\_reason. When false, Atomic infers stop or toolUse when the stream ends. |
| `maxTokensField` | `"max_completion_tokens" \| "max_tokens"` | | Which field to use for max tokens. Default: auto-detected from URL. |
| `requiresToolResultName` | boolean | | Whether tool results require the name field. Default: auto-detected from URL. |
| `requiresAssistantAfterToolResult` | boolean | | Whether a user message after tool results requires an assistant message in between. Default: auto-detected from URL. |
| `requiresThinkingAsText` | boolean | | Whether thinking blocks must be converted to text blocks with \<thinking> delimiters. Default: auto-detected from URL. |
| `requiresReasoningContentOnAssistantMessages` | boolean | | Whether all replayed assistant messages must include an empty reasoning\_content field when reasoning is enabled. Default: auto-detected from URL. |
| `thinkingFormat` | `"openai" \| "openrouter" \| "deepseek" \| "together" \| "baseten" \| "zai" \| "qwen" \| "chat-template" \| "qwen-chat-template" \| "string-thinking" \| "ant-ling"` | | Format for reasoning or thinking parameters. When omitted, Atomic auto-detects the format from the provider URL. "openai" uses reasoning\_effort, "openrouter" uses reasoning.effort, "deepseek" uses thinking.type plus reasoning\_effort when supported, "together" uses reasoning.enabled plus reasoning\_effort when supported, "baseten" uses configurable chat\_template\_args plus reasoning\_effort when supported, "zai" uses thinking.type, "qwen" uses top-level enable\_thinking, "qwen-chat-template" uses chat\_template\_kwargs.enable\_thinking and preserve\_thinking, "chat-template" uses configurable chat\_template\_kwargs, "string-thinking" uses top-level thinking, and "ant-ling" uses reasoning.effort only when the mapped effort is non-null. |
| `chatTemplateKwargs` | object | | Kwargs sent as chat\_template\_kwargs when thinkingFormat is "chat-template". Use \$var with "thinking.enabled", "thinking.effort", or "thinking.budget" for Atomic-controlled values. |
| `chatTemplateArgs` | object | | Arguments sent as chat\_template\_args when thinkingFormat is "baseten". Use \$var with "thinking.enabled", "thinking.effort", or "thinking.budget" for Atomic-controlled values. |
| `openRouterRouting` | object | | OpenRouter provider routing preferences. Controls which upstream providers OpenRouter routes requests to. Sent as the provider field in the OpenRouter API request body. See [https://openrouter.ai/docs/guides/routing/provider-selection](https://openrouter.ai/docs/guides/routing/provider-selection). |
| `vercelGatewayRouting` | object | | Vercel AI Gateway routing preferences. Controls which upstream providers the gateway routes requests to. See [https://vercel.com/docs/ai-gateway/models-and-providers/provider-options](https://vercel.com/docs/ai-gateway/models-and-providers/provider-options). |
| `zaiToolStream` | boolean | `false` | Whether z.ai supports top-level tool\_stream for streaming tool call deltas. |
| `thinkingTokenBudgetField` | `"thinking_token_budget" \| "thinking_budget" \| "thinking_budget_tokens"` | | Top-level request field used to cap reasoning tokens from thinkingBudgets. Reasoning and the answer share max\_tokens on these endpoints. "thinking\_token\_budget" is vLLM, "thinking\_budget" is Qwen, DashScope, or SGLang, and "thinking\_budget\_tokens" is llama.cpp. Off by default and not set on the generated catalog. |
| `supportsThinkingTokenBudget` | boolean | `false` | Alias for thinkingTokenBudgetField: "thinking\_token\_budget" (vLLM). Prefer thinkingTokenBudgetField. |
| `supportsOpenAIGrammarTools` | boolean | `false` | Whether the provider supports OpenAI custom tools with Lark or regex grammar formats. When false, grammar-constrained tools fall back to normal function tools. The generated catalog enables this for capable models. |
| `supportsMidConvoSystemMessages` | boolean | `false` | Whether the exact model accepts system or developer messages after the conversation has started. When false, later system messages are folded into the leading system message. The generated catalog enables this for verified models. |
| `supportsMidConvoToolAdditions` | boolean | `false` | Whether system messages can introduce additional tools mid-conversation. Requires supportsMidConvoSystemMessages. The generated catalog enables this for capable models. |
| `supportsStrictMode` | boolean | `false` | Whether the provider supports the strict field in tool definitions. Generated capable models enable it explicitly. |
| `cacheControlFormat` | `"anthropic"` | | Cache control convention for prompt caching. Anthropic applies cache\_control markers to the system prompt, last tool definition, and last user, assistant, or tool-result text content. |
| `sendSessionAffinityHeaders` | boolean | | Whether to send session-affinity data from options.sessionId. Default: true for OpenRouter endpoints, false otherwise. |
| `sessionAffinityFormat` | `"openai" \| "openai-nosession" \| "openrouter"` | | Session-affinity header format. openai sends session\_id, x-client-request-id, and x-session-affinity; openai-nosession sends x-client-request-id and x-session-affinity; openrouter sends x-session-id. Does not affect prompt\_cache\_key. Default: auto-detected. |
| `supportsLongCacheRetention` | boolean | | Whether the provider supports long prompt cache retention (prompt\_cache\_retention: "24h" or Anthropic-style cache\_control.ttl: "1h", depending on format). Default: auto-detected from provider and URL. |
| `vllmPriority` | number | | vLLM scheduler priority sent as the top-level priority request field. Lower values are handled earlier and the server default is 0. Only meaningful with --scheduling-policy priority. Off by default and not set on the generated catalog. |

### `openai-responses`

Also applies to `azure-openai-responses` and `openai-codex-responses`.

| Field | Type | Default | Description |
| - | - | - | - |
| `supportsDeveloperRole` | boolean | `true` | Whether the provider supports the developer role instead of system. |
| `supportsMidConvoSystemMessages` | boolean | `false` | Whether the exact model accepts developer or system messages after the conversation has started. When false, later system messages are folded into the leading system message. The generated catalog enables this for verified models. |
| `sessionAffinityFormat` | `"openai" \| "openai-nosession" \| "openrouter"` | | Session-affinity header format. openai sends session\_id and x-client-request-id; openai-nosession sends x-client-request-id; openrouter sends x-session-id. Does not affect prompt\_cache\_key. Default: auto-detected. |
| `supportsLongCacheRetention` | boolean | `true` | Whether the provider supports long prompt cache retention. This uses prompt\_cache\_options.ttl: "30m" on GPT-5.6+ and prompt\_cache\_retention: "24h" on earlier models. |
| `supportsStrictMode` | boolean | | Whether the provider supports strict JSON-schema function tools. Defaults are API-specific; generated OpenAI models enable it explicitly. |
| `supportsOpenAIGrammarTools` | boolean | `false` | Whether to emit OpenAI custom tools with Lark or regex grammar formats. When false, grammar-constrained tools fall back to normal function tools. The generated catalog enables this for capable models. |
| `supportsAdditionalTools` | boolean | `false` | Whether the model supports message-anchored additional\_tools input items. |
| `supportsToolSearch` | boolean | `false` | Whether the model supports client-executed tool search for transcript-anchored additions. |
| `supportsExplicitPromptCacheMode` | boolean | `false` | Whether the model accepts prompt\_cache\_options. Older OpenAI models reject the parameter. |
| `supportsMidConvoEffort` | boolean | `false` | Whether thinking level changes are sent as configuration\_update input items instead of changing reasoning.effort, so a change keeps the prompt cache. Only used by the openai-responses API, and ignored with Sign in with ChatGPT on the openai provider. |
| `supportsMaxOutputTokens` | boolean | `true` | Whether the provider accepts max\_output\_tokens. Some Codex-protocol gateways reject it. |

### `anthropic-messages`

| Field | Type | Default | Description |
| - | - | - | - |
| `supportsEagerToolInputStreaming` | boolean | `true` | Whether the provider accepts per-tool eager\_input\_streaming. When false, the Anthropic provider omits tools\[].eager\_input\_streaming and sends the legacy fine-grained-tool-streaming-2025-05-14 beta header for tool-enabled requests. |
| `supportsLongCacheRetention` | boolean | `true` | Whether the provider supports Anthropic long cache retention through cache\_control.ttl. |
| `sendSessionAffinityHeaders` | boolean | | Whether to send x-session-affinity from options.sessionId when caching is enabled. Required for providers like Fireworks that use session affinity for prompt cache routing; requests to the same replica maximize cache hits. Default: true for OpenRouter endpoints, false otherwise. |
| `sessionAffinityFormat` | `"openrouter"` | | Session-affinity format. openrouter sends x-session-id; when unset, sends x-session-affinity. |
| `supportsCacheControlOnTools` | boolean | `true` | Whether the provider supports Anthropic-style cache\_control markers on tool definitions. When false, cache\_control is omitted from tool parameters. Some Anthropic-compatible providers, such as Fireworks, do not support this field on tools and may reject or ignore it. |
| `supportsTemperature` | boolean | `true` | Whether the model accepts the Anthropic temperature request field. Claude Opus 4.7+ rejects non-default values. |
| `forceAdaptiveThinking` | boolean | `false` | Whether to force adaptive thinking (thinking.type: adaptive plus output\_config.effort) regardless of model ID. Built-in models that require adaptive thinking set this in generated metadata. Custom Anthropic-compatible providers can set this to true for any model whose upstream requires the adaptive format. Set false to opt out on overridden built-in models. |
| `allowEmptySignature` | boolean | `false` | Whether to replay empty thinking signatures instead of converting thinking to text. |
| `supportsStrictTools` | boolean | `false` | Whether the provider supports Anthropic strict tool schemas. Generated Anthropic models enable it explicitly. |
| `supportsMidConvoEffort` | boolean | `false` | Whether the exact model transport supports effort-only system messages and thinking binding controls. |
| `supportsMidConvoSystemMessages` | boolean | `false` | Whether the exact model accepts system-role messages inside the conversation. When false, later system messages are folded into the top-level system prompt. |
| `supportsMidConvoToolChanges` | boolean | `false` | Whether the exact model accepts mid-conversation tool\_addition and tool\_removal blocks. Requires supportsMidConvoSystemMessages. |
| `allowedFallbackModels` | `object[]` | | Models Anthropic accepts for server-side refusal fallback, with local pricing metadata for returned fallback responses. When absent or empty, callers must omit fallbacks; Anthropic rejects the field for models with no permitted fallback targets. |
| `enforcesPreservedThinkingBinding` | boolean | `false` | Whether the model runs the Anthropic preserved-thinking conversation check, which rejects a request whose system prompt, tools, or earlier messages changed since a replayed thinking block was produced. When true, the provider sends the thinking-binding-controls-2026-08-01 beta header and thinking.block\_binding.prefix\_mismatch\_behavior: "drop\_block", so a changed prefix drops the affected thinking blocks instead of failing the request. |
| `delegatesThinkingModelBinding` | boolean | `false` | Whether the API adjudicates thinking-block model binding itself, always dropping a block the target model cannot read. When true, an assistant turn produced by a different model on the same provider and API replays its signed thinking and redacted\_thinking blocks unchanged instead of being rewritten into plain text. |
| `supportsForcedToolChoice` | boolean | `true` | Whether the model accepts forced tool use (tool\_choice "any" or a specific tool). When false, the provider rejects a forced choice with an error instead of sending a request the model is guaranteed to refuse. "auto" and "none" are never altered. |

### `bedrock-converse-stream`

| Field | Type | Default | Description |
| - | - | - | - |
| `supportsStrictMode` | boolean | `false` | Whether the model supports Bedrock strict tool schemas. |
| `supportsForcedToolChoice` | boolean | `true` | Whether the model accepts forced tool use (toolChoice "any" or a specific tool). When false, the provider rejects a forced choice with an error instead of sending a request that is guaranteed to fail. "auto" and "none" are never altered. |
| `supportsTemperature` | boolean | `true` | Whether the model accepts inferenceConfig.temperature. When false, the provider omits the field. |

### `mistral-conversations`

| Field | Type | Default | Description |
| - | - | - | - |
| `supportsMidConvoSystemMessages` | boolean | `false` | Whether the exact model accepts system messages after the conversation has started. When false, later system messages are folded into the leading system message. |

### Atomic compatibility aliases

| Field | Type | Default | Description |
| - | - | - | - |
| `supportsGrammarTools` | boolean | | Atomic alias for supportsOpenAIGrammarTools. The canonical field wins if both are set. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.