ReasoningOptions
Reasoning options
Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set exclude to true. That controls the output you receive, not whether the model uses or bills reasoning tokens.
Usage profiles
| Usage | Fields and validation |
|---|---|
| In requests | View fields |
| In responses | View fields |
| In webhook payloads | View fields |
In requests
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
effort | string (EFFORT_HIGH, EFFORT_MEDIUM, EFFORT_LOW, EFFORT_XHIGH, EFFORT_MINIMAL, EFFORT_NONE) or integer (int32) | Optional | Requested model reasoning effort. |
maxTokens | integer (int32) | Optional | Maximum reasoning-token count requested from the model provider. Minimum: -2147483648. Maximum: 2147483647. |
exclude | boolean | Optional | Whether the provider should omit reasoning content from its response. |
includeReasoningHistory | boolean | Optional | When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. |
Values of effort
Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning |
|---|---|---|---|
EFFORT_HIGH | 1 | Canonical | Request the provider's high reasoning-effort level. |
EFFORT_MEDIUM | 2 | Canonical | Request the provider's medium reasoning-effort level. |
EFFORT_LOW | 3 | Canonical | Request the provider's low reasoning-effort level. |
EFFORT_XHIGH | 4 | Canonical | Request the provider's extra-high reasoning-effort level where supported. |
EFFORT_MINIMAL | 5 | Canonical | Request the provider's minimal reasoning-effort level where supported. |
EFFORT_NONE | 6 | Canonical | Request no reasoning effort where the provider supports disabling it. |
In responses
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
effort | string (EFFORT_HIGH, EFFORT_MEDIUM, EFFORT_LOW, EFFORT_XHIGH, EFFORT_MINIMAL, EFFORT_NONE) or integer (int32) | Optional | Requested model reasoning effort. |
maxTokens | integer (int32) | Optional | Maximum reasoning-token count requested from the model provider. Minimum: -2147483648. Maximum: 2147483647. |
exclude | boolean | Optional | Whether the provider should omit reasoning content from its response. |
includeReasoningHistory | boolean | Optional | When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. |
Values of effort
Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning |
|---|---|---|---|
EFFORT_HIGH | 1 | Canonical | Request the provider's high reasoning-effort level. |
EFFORT_MEDIUM | 2 | Canonical | Request the provider's medium reasoning-effort level. |
EFFORT_LOW | 3 | Canonical | Request the provider's low reasoning-effort level. |
EFFORT_XHIGH | 4 | Canonical | Request the provider's extra-high reasoning-effort level where supported. |
EFFORT_MINIMAL | 5 | Canonical | Request the provider's minimal reasoning-effort level where supported. |
EFFORT_NONE | 6 | Canonical | Request no reasoning effort where the provider supports disabling it. |
In webhook payloads
Webhook JSON uses protobuf field names (snake_case).
| Field | Type | Presence | Meaning |
|---|---|---|---|
effort | string (EFFORT_HIGH, EFFORT_MEDIUM, EFFORT_LOW, EFFORT_XHIGH, EFFORT_MINIMAL, EFFORT_NONE) or integer (int32) | Optional | Requested model reasoning effort. |
max_tokens | integer (int32) | Optional | Maximum reasoning-token count requested from the model provider. Minimum: -2147483648. Maximum: 2147483647. |
exclude | boolean | Optional | Whether the provider should omit reasoning content from its response. |
include_reasoning_history | boolean | Optional | When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. |
Values of effort
Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning |
|---|---|---|---|
EFFORT_HIGH | 1 | Canonical | Request the provider's high reasoning-effort level. |
EFFORT_MEDIUM | 2 | Canonical | Request the provider's medium reasoning-effort level. |
EFFORT_LOW | 3 | Canonical | Request the provider's low reasoning-effort level. |
EFFORT_XHIGH | 4 | Canonical | Request the provider's extra-high reasoning-effort level where supported. |
EFFORT_MINIMAL | 5 | Canonical | Request the provider's minimal reasoning-effort level where supported. |
EFFORT_NONE | 6 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Where used
| Reference | Relationship |
|---|---|
| Create an agent profile | POST /api/v1/agent-profiles/create |
| Import a prompt library | POST /api/v1/agent-profiles/import |
| Update an agent profile | POST /api/v1/agent-profiles/update |
| Append a message without generating | POST /api/v1/llm/append-message |
| Create a new conversation thread | POST /api/v1/llm/create-thread |
| Send a message to a conversation | POST /api/v1/llm/send-message |
| Send a message and wait for the result | POST /api/v1/llm/send-message-sync |
| Update context management settings | POST /api/v1/llm/update-context-management-settings |
| Update default generation config | POST /api/v1/llm/update-default-generation-config |
| Update the caller's default generation config | POST /api/v1/enduser/update-generation-config |
| Get an agent profile | POST /api/v1/agent-profiles/get |
| List agent profiles | POST /api/v1/agent-profiles/list |
| Withdraw your rating on a message | POST /api/v1/llm/delete-message-rating |
| Get full conversation state | POST /api/v1/llm/conversation-state |
| Rate an assistant message | POST /api/v1/llm/rate-message |
| Submit client-side tool results and wait for the next segment | POST /api/v1/llm/submit-client-tool-results-sync |
| Get the caller's end-user profile | POST /api/v1/enduser/get |
| Generation configuration | API JSON uses JSON field names (camelCase). |
| llm.generation_started | Webhook JSON uses protobuf field names (snake_case). |
| llm.message_published | Webhook JSON uses protobuf field names (snake_case). |
| GenerationConfig | Nested in model |
| GenerationConfig | Nested in model |
| GenerationConfig | Nested in model |
Download the public reference contract.
Document: DOC-API-MODEL-reasoning-options.