Skip to content

Get up and running with Kimi, GLM, MiniMax, DeepSeek, gpt-oss, Qwen, Gemma and other models.

docs: document thinking control discovery (#18501)

Parth Sareenc1737589973d
diff --git a/docs/api/anthropic-compatibility.mdx b/docs/api/anthropic-compatibility.mdx
index 676514817..b57bd26b6 100644
--- a/docs/api/anthropic-compatibility.mdx
+++ b/docs/api/anthropic-compatibility.mdx
@@ -303,6 +303,8 @@ See the [Claude Code guide](/integrations/claude-code) for Ollama Launch and [di
- [x] `stop_sequences`
- [x] `tools`
- [x] `thinking`
+- [x] `output_config`
+ - [x] `effort` (model-defined names)
- [ ] `tool_choice`
- [ ] `metadata`
@@ -327,6 +329,8 @@ See the [Claude Code guide](/integrations/claude-code) for Ollama Launch and [di
- [x] `ping`
- [x] `error`
+Use `/api/show` to discover a model's supported thinking values and default. `thinking.type: "enabled"` and `"disabled"` act as explicit on/off controls. When a model uses its metadata to resolve named levels, supported `output_config.effort` names are applied exactly and unsupported names resolve to the model default. Models without metadata keep the existing compatibility behavior, which trims and lowercases effort names and maps `"xhigh"` to `"high"`.
+
## Models
Ollama supports both local and cloud models.
diff --git a/docs/api/openai-compatibility.mdx b/docs/api/openai-compatibility.mdx
index c12bda912..272f98ea7 100644
--- a/docs/api/openai-compatibility.mdx
+++ b/docs/api/openai-compatibility.mdx
@@ -242,14 +242,16 @@ curl -X POST http://localhost:11434/v1/chat/completions \
- [x] `top_p`
- [x] `max_tokens`
- [x] `tools`
-- [x] `reasoning_effort` (`"high"`, `"medium"`, `"low"`, `"max"`, `"none"`)
+- [x] `reasoning_effort` (model-defined names and compatibility aliases)
- [x] `reasoning`
- - [x] `effort` (`"high"`, `"medium"`, `"low"`, `"max"`, `"none"`)
+ - [x] `effort` (model-defined names and compatibility aliases)
- [ ] `tool_choice`
- [ ] `logit_bias`
- [ ] `user`
- [ ] `n`
+`reasoning_effort` and `reasoning.effort` control model thinking. Use `/api/show` to discover each model's supported values and default. When a model uses its metadata to resolve named levels, supported names are applied exactly and unsupported names resolve to the model default. Boolean-only models that support enabling thinking map recognized compatibility efforts to `true`, while `"none"` requests `false`. Models without metadata retain the existing compatibility aliases: `"minimal"` maps to `"low"`, and `"xhigh"` or `"ultra"` map to `"max"`. GPT-OSS keeps its existing OpenAI compatibility conversion: `"minimal"` uses `"low"`, `"xhigh"` or `"ultra"` use `"high"`, and `"none"` requests no thinking output.
+
### `/v1/completions`
#### Supported features
@@ -338,6 +340,9 @@ Ollama supports the [OpenAI Responses API](https://platform.openai.com/docs/api-
- [x] `temperature`
- [x] `top_p`
- [x] `max_output_tokens`
+- [x] `reasoning`
+ - [x] `effort` (model-defined names and compatibility aliases)
+- [x] `think` (Ollama extension; boolean, model-defined string, or `null`)
- [ ] `previous_response_id` (stateful v1/responses not supported)
- [ ] `conversation` (stateful v1/responses not supported)
- [ ] `truncation`
diff --git a/docs/capabilities/thinking.mdx b/docs/capabilities/thinking.mdx
index 4e58c1d73..b357ccd86 100644
--- a/docs/capabilities/thinking.mdx
+++ b/docs/capabilities/thinking.mdx
@@ -6,21 +6,46 @@ Thinking-capable models emit a `thinking` field that separates their reasoning t
Use this capability to audit model steps, animate the model *thinking* in a UI, or hide the trace entirely when you only need the final response.
-## Supported models
+See the [full list of thinking models](https://ollama.com/search?c=thinking).
-- [Qwen 3](https://ollama.com/library/qwen3)
-- [GPT-OSS](https://ollama.com/library/gpt-oss) *(use `think` levels: `low`, `medium`, `high` — the trace cannot be fully disabled)*
-- [DeepSeek-v3.1](https://ollama.com/library/deepseek-v3.1)
-- [DeepSeek R1](https://ollama.com/library/deepseek-r1)
-- Browse the latest additions under [thinking models](https://ollama.com/search?c=thinking)
+## Discover a model's thinking controls
+
+Thinking controls vary by model. Use `/api/show` to discover the values a model supports and the value Ollama uses by default:
+
+```shell
+curl http://localhost:11434/api/show -d '{
+ "model": "gpt-oss"
+}'
+```
+
+The response includes a top-level `thinking` object:
+
+```json
+{
+ "thinking": {
+ "values": ["low", "medium", "high"],
+ "default": "medium"
+ }
+}
+```
+
+- `values` can contain booleans (`true` or `false`) for on/off controls. It can also contain model-defined strings for named levels.
+- `default` is used when `think` is not set.
+- `values: [false]` means the model does not support thinking.
+- If `thinking` is omitted, the model has no thinking metadata. The model might conduct thinking based on its existing behavior.
## Enable thinking in API calls
-Set the `think` field on chat or generate requests. Most models accept booleans (`true`/`false`) or levels (`low`, `medium`, `high`, `max`), where `max` requests the highest thinking level.
+Set the `think` field on a chat or generate request:
-GPT-OSS instead expects one of `low`, `medium`, or `high` to tune the trace length.
+- `true`: request thinking output.
+- `false`: request no thinking output, if the model permits it.
+- `null`: use the model default.
+- A string: select a supported level from `thinking.values`. Use the exact value from `/api/show`. Numbers are not supported.
-The `message.thinking` (chat endpoint) or `thinking` (generate endpoint) field contains the reasoning trace while `message.content` / `response` holds the final answer.
+If the model resolves named levels from `/api/show` metadata, Ollama applies supported names exactly. Unsupported names use the model default.
+
+The reasoning output and answer use separate fields. Chat returns `message.thinking` and `message.content`. Generate returns `thinking` and `response`.
<Tabs>
<Tab title="cURL">
@@ -68,10 +93,6 @@ The `message.thinking` (chat endpoint) or `thinking` (generate endpoint) field c
</Tab>
</Tabs>
-<Note>
- GPT-OSS requires `think` to be set to `"low"`, `"medium"`, or `"high"`. Passing `true`/`false` is ignored for that model.
-</Note>
-
## Stream the reasoning trace
Thinking streams interleave reasoning tokens before answer tokens. Detect the first `thinking` chunk to render a "thinking" section, then switch to the final reply once `message.content` arrives.
@@ -141,13 +162,3 @@ Thinking streams interleave reasoning tokens before answer tokens. Detect the fi
```
</Tab>
</Tabs>
-
-## CLI quick reference
-
-- Enable thinking for a single run: `ollama run deepseek-r1 --think "Where should I visit in Lisbon?"`
-- Disable thinking: `ollama run deepseek-r1 --think=false "Summarize this article"`
-- Hide the trace while still using a thinking model: `ollama run deepseek-r1 --hidethinking "Is 9.9 bigger or 9.11?"`
-- Inside interactive sessions, toggle with `/set think` or `/set nothink`.
-- GPT-OSS only accepts levels: `ollama run gpt-oss --think=low "Draft a headline"` (replace `low` with `medium` or `high` as needed).
-
-<Note>Thinking is enabled by default in the CLI and API for supported models.</Note>
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index 8ef988e18..86fc5e9dc 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -96,11 +96,7 @@ components:
type: boolean
default: true
think:
- oneOf:
- - type: boolean
- - type: string
- enum: [high, medium, low, max]
- description: When true, returns separate thinking output in addition to content. Can be a boolean (true/false) or a string ("high", "medium", "low", "max") for supported models, with "max" requesting the highest thinking level.
+ $ref: "#/components/schemas/ThinkValue"
raw:
type: boolean
description: When true, returns the raw response from the model without any prompt templating
@@ -294,11 +290,7 @@ components:
type: boolean
default: true
think:
- oneOf:
- - type: boolean
- - type: string
- enum: [high, medium, low, max]
- description: When true, returns separate thinking output in addition to content. Can be a boolean (true/false) or a string ("high", "medium", "low", "max") for supported models, with "max" requesting the highest thinking level.
+ $ref: "#/components/schemas/ThinkValue"
keep_alive:
oneOf:
- type: string
@@ -410,6 +402,29 @@ components:
done:
type: boolean
description: True for the final event in the stream
+ ThinkValue:
+ description: Controls a model's thinking output. Use `/api/show` to discover the supported values and default for the selected model. `true` requests thinking, `false` requests no thinking output, and `null` uses the model default. String values are model-defined; supported names must match `/api/show` exactly. Numbers are not supported.
+ oneOf:
+ - type: boolean
+ - type: string
+ - type: "null"
+ Thinking:
+ type: object
+ required: [values, default]
+ description: Thinking controls advertised by a model. Models without thinking metadata omit this field.
+ properties:
+ values:
+ type: array
+ description: Values explicitly supported by the model's `think` request field. Booleans represent on/off controls and strings represent model-defined levels. An array containing only `false` identifies a model without thinking support.
+ items:
+ oneOf:
+ - type: boolean
+ - type: string
+ default:
+ description: Value used when `think` is not set. For models that use this metadata for named thinking levels, unsupported names resolve to this default.
+ oneOf:
+ - type: boolean
+ - type: string
StatusEvent:
type: object
properties:
@@ -597,6 +612,8 @@ components:
ShowResponse:
type: object
properties:
+ thinking:
+ $ref: "#/components/schemas/Thinking"
parameters:
type: string
description: Model parameter settings serialized as text
@@ -836,6 +853,15 @@ paths:
"prompt": "Why is the sky blue?",
"stream": false
}'
+ - lang: bash
+ label: Thinking
+ source: |
+ curl http://localhost:11434/api/generate -d '{
+ "model": "gpt-oss",
+ "prompt": "What is 1+1?",
+ "think": "low",
+ "stream": false
+ }'
- lang: bash
label: With options
source: |
@@ -1245,6 +1271,18 @@ paths:
"model": "gemma4",
"verbose": true
}'
+ - lang: bash
+ label: Thinking controls
+ source: |
+ curl http://localhost:11434/api/show -d '{
+ "model": "gpt-oss"
+ }'
+ - lang: bash
+ label: Thinking controls
+ source: |
+ curl http://localhost:11434/api/show -d '{
+ "model": "gpt-oss"
+ }'
requestBody:
required: true
content:
@@ -1265,7 +1303,13 @@ paths:
license: "Gemma Terms of Use \n\nLast modified: February 21, 2024..."
capabilities:
- "completion"
+ - "thinking"
- "vision"
+ thinking:
+ values:
+ - false
+ - true
+ default: true
modified_at: "2025-08-14T15:49:43.634137516-07:00"
details:
parent_model: ""