Skip to main content
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#overview

GenerationConfig

Canonical generation configuration

Set the language preference to a BCP-47 tag (for example, "fr" or "pt-BR"). The platform injects a "Respond only in [language]" instruction into every LLM call for this conversation. The instruction is not persisted to history.

See Generation configuration for how settings combine across scopes.

Type-reference view: API Schema 9frhv4euve, API Schema 9ftjkkjhfa. Request and response views describe this type; they do not declare an endpoint.

Meaning and usage​

Section ID: DOC-API-MODEL-schema-1h82h7ri5p#meaning

See the definition above.

Usage profiles​

Section ID: DOC-API-MODEL-schema-1h82h7ri5p#fields

UsageFields and validation
In requestsView fields
In responsesView fields

In requests​

Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request

API JSON uses JSON field names (camelCase).

FieldTypePresenceMeaning
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-modelmodelstringOptionalPrimary model identifier requested for generation.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-modelsmodelsArray of stringOptionalCandidate models for routing.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-systempromptsystemPromptstringOptional; explicit presenceOptional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-modelroutingfiltermodelRoutingFilterModelRoutingFilterOptionalOptional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-providerproviderProviderPreferencesOptionalProvider/multi-provider routing preferences
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-reasoningreasoningReasoningOptionsOptionalReasoning effort and output options passed to the model provider.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-usageusageUsageOptionsOptionalToken and cost accounting associated with the operation.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-transformstransformsArray of stringOptionalProvider transformations requested for the generation input.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-toolstoolsArray of ToolDefinitionOptionalTool definitions exposed to the model for server-side execution.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-toolchoicetoolChoiceToolChoiceOptionalPolicy controlling whether and which tool the model may call.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-clienttoolsclientToolsArray of ToolDefinitionOptionalClient-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-toolpolicytoolPolicyToolExecutionPolicyOptionalPer-run tool execution policy (approvals, ordering, limits, retries, timeouts)
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-temperaturetemperaturenumber (double) or string (NaN, Infinity, -Infinity)Optional; explicit presenceSampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-topptopPnumber (double) or string (NaN, Infinity, -Infinity)Optional; explicit presenceCumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-maxoutputtokensmaxOutputTokensstring (int64)Optional; explicit presenceMaximum output-token count requested from the model provider; corresponds to max_tokens in provider requests. Pattern: ^-?\d+$.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-frequencypenaltyfrequencyPenaltynumber (double) or string (NaN, Infinity, -Infinity)Optional; explicit presenceSampling penalty applied to tokens according to their prior frequency.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-presencepenaltypresencePenaltynumber (double) or string (NaN, Infinity, -Infinity)Optional; explicit presenceSampling penalty applied to tokens already present in generated content.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-stopsequencesstopSequencesArray of stringOptionalToken sequences at which the model should stop generation.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-seedseedstring (int64)Optional; explicit presenceDeterministic control where supported. Pattern: ^-?\d+$.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-responseformatresponseFormatResponseFormatOptionalStructured-output format and schema requested for the model response.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-allowparalleltoolcallsallowParallelToolCallsbooleanOptional; explicit presenceAllow the model to issue multiple tool calls in parallel where supported
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-topktopKstring (int64)Optional; explicit presenceMaximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-repetitionpenaltyrepetitionPenaltynumber (double) or string (NaN, Infinity, -Infinity)Optional; explicit presenceProvider sampling penalty used to discourage repeated output.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-logitbiaslogitBiasMap from string to number (double) or string (NaN, Infinity, -Infinity)OptionalPer-token adjustments applied to the provider token-selection logits.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-toplogprobstopLogprobsstring (int64)Optional; explicit presenceNumber of top token log probabilities requested from the provider. Pattern: ^-?\d+$.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-minpminPnumber (double) or string (NaN, Infinity, -Infinity)Optional; explicit presenceMinimum relative token probability used by supported sampling providers.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-topatopAnumber (double) or string (NaN, Infinity, -Infinity)Optional; explicit presenceAdaptive probability cutoff used by supported sampling providers.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-useruserstringOptional; explicit presenceUser identifier forwarded for provider-side request attribution.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-modalitiesmodalitiesArray of string (MODALITY_TEXT, MODALITY_IMAGE, MODALITY_AUDIO) or integer (int32)OptionalOutput modalities (e.g., [TEXT, IMAGE])
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-pluginspluginsArray of PluginConfigOptionalProvider plugins requested for pre-processing or post-processing.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-languagepreferencelanguagePreferencestringOptional; explicit presenceLanguage preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) Minimum length: 2. Pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-timeawaretimeAwareTimeAwareConfigOptionalTime-aware generation options (current time, message timestamps, file timestamps)
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-turncontextturnContextTurnContextConfigOptionalTurn context configuration for turn-aware generation
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-mem0mem0MemoryConfigOptionalConfiguration for semantic memory search, context injection and extraction during generation.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-requesttimeoutsecondsrequestTimeoutSecondsstring (int64)OptionalTimeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-fileresolutionfileResolutionFileResolutionConfigOptionalConfiguration for resolving FILE_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-cleartoolsclearToolsbooleanOptionalSet to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-field-clearclienttoolsclearClientToolsbooleanOptionalSet to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged.

Values of modalities​

Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-values-modalities

Output media requested from a model that supports that modality.

ValueNo.FormMeaning
MODALITY_TEXT0CanonicalRequest generated text output.
MODALITY_IMAGE1CanonicalRequest generated image output where the model supports it.
MODALITY_AUDIO2CanonicalRequest generated audio output where the model supports it.

Request validation​

Section ID: DOC-API-MODEL-schema-1h82h7ri5p#request-validation

These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules.

Applies toRuleRequirement
languagePreferenceMinimum length2
languagePreferencePattern^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$

In responses​

Section ID: DOC-API-MODEL-schema-1h82h7ri5p#response

API JSON uses JSON field names (camelCase).

FieldTypePresenceMeaning
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-modelSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-modelmodelstringOptionalPrimary model identifier requested for generation.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-modelsSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-modelsmodelsArray of stringOptionalCandidate models for routing.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-systempromptSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-systempromptsystemPromptstringOptional; explicit presenceOptional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-modelroutingfilterSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-modelroutingfiltermodelRoutingFilterModelRoutingFilterOptionalOptional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-providerSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-providerproviderProviderPreferencesOptionalProvider/multi-provider routing preferences
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-reasoningSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-reasoningreasoningReasoningOptionsOptionalReasoning effort and output options passed to the model provider.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-usageSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-usageusageUsageOptionsOptionalToken and cost accounting associated with the operation.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-transformsSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-transformstransformsArray of stringOptionalProvider transformations requested for the generation input.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-toolsSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-toolstoolsArray of ToolDefinitionOptionalTool definitions exposed to the model for server-side execution.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-toolchoiceSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-toolchoicetoolChoiceToolChoiceOptionalPolicy controlling whether and which tool the model may call.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-clienttoolsSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-clienttoolsclientToolsArray of ToolDefinitionOptionalClient-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-toolpolicySection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-toolpolicytoolPolicyToolExecutionPolicyOptionalPer-run tool execution policy (approvals, ordering, limits, retries, timeouts)
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-temperatureSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-temperaturetemperaturenumber (double) or string (NaN, Infinity, -Infinity)Optional; explicit presenceSampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-toppSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-topptopPnumber (double) or string (NaN, Infinity, -Infinity)Optional; explicit presenceCumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-maxoutputtokensSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-maxoutputtokensmaxOutputTokensstring (int64)Optional; explicit presenceMaximum output-token count requested from the model provider; corresponds to max_tokens in provider requests. Pattern: ^-?\d+$.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-frequencypenaltySection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-frequencypenaltyfrequencyPenaltynumber (double) or string (NaN, Infinity, -Infinity)Optional; explicit presenceSampling penalty applied to tokens according to their prior frequency.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-presencepenaltySection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-presencepenaltypresencePenaltynumber (double) or string (NaN, Infinity, -Infinity)Optional; explicit presenceSampling penalty applied to tokens already present in generated content.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-stopsequencesSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-stopsequencesstopSequencesArray of stringOptionalToken sequences at which the model should stop generation.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-seedSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-seedseedstring (int64)Optional; explicit presenceDeterministic control where supported. Pattern: ^-?\d+$.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-responseformatSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-responseformatresponseFormatResponseFormatOptionalStructured-output format and schema requested for the model response.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-allowparalleltoolcallsSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-allowparalleltoolcallsallowParallelToolCallsbooleanOptional; explicit presenceAllow the model to issue multiple tool calls in parallel where supported
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-topkSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-topktopKstring (int64)Optional; explicit presenceMaximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-repetitionpenaltySection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-repetitionpenaltyrepetitionPenaltynumber (double) or string (NaN, Infinity, -Infinity)Optional; explicit presenceProvider sampling penalty used to discourage repeated output.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-logitbiasSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-logitbiaslogitBiasMap from string to number (double) or string (NaN, Infinity, -Infinity)OptionalPer-token adjustments applied to the provider token-selection logits.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-toplogprobsSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-toplogprobstopLogprobsstring (int64)Optional; explicit presenceNumber of top token log probabilities requested from the provider. Pattern: ^-?\d+$.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-minpSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-minpminPnumber (double) or string (NaN, Infinity, -Infinity)Optional; explicit presenceMinimum relative token probability used by supported sampling providers.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-topaSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-topatopAnumber (double) or string (NaN, Infinity, -Infinity)Optional; explicit presenceAdaptive probability cutoff used by supported sampling providers.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-userSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-useruserstringOptional; explicit presenceUser identifier forwarded for provider-side request attribution.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-modalitiesSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-modalitiesmodalitiesArray of string (MODALITY_TEXT, MODALITY_IMAGE, MODALITY_AUDIO) or integer (int32)OptionalOutput modalities (e.g., [TEXT, IMAGE])
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-pluginsSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-pluginspluginsArray of PluginConfigOptionalProvider plugins requested for pre-processing or post-processing.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-languagepreferenceSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-languagepreferencelanguagePreferencestringOptional; explicit presenceLanguage preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware)
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-timeawareSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-timeawaretimeAwareTimeAwareConfigOptionalTime-aware generation options (current time, message timestamps, file timestamps)
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-turncontextSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-turncontextturnContextTurnContextConfigOptionalTurn context configuration for turn-aware generation
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-mem0Section ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-mem0mem0MemoryConfigOptionalConfiguration for semantic memory search, context injection and extraction during generation.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-requesttimeoutsecondsSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-requesttimeoutsecondsrequestTimeoutSecondsstring (int64)OptionalTimeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-fileresolutionSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-fileresolutionfileResolutionFileResolutionConfigOptionalConfiguration for resolving FILE_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-cleartoolsSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-cleartoolsclearToolsbooleanOptionalSet to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#field-clearclienttoolsSection ID: DOC-API-MODEL-schema-1h82h7ri5p#response-field-clearclienttoolsclearClientToolsbooleanOptionalSet to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged.

Values of modalities​

Section ID: DOC-API-MODEL-schema-1h82h7ri5p#response-values-modalities

Output media requested from a model that supports that modality.

ValueNo.FormMeaning
MODALITY_TEXT0CanonicalRequest generated text output.
MODALITY_IMAGE1CanonicalRequest generated image output where the model supports it.
MODALITY_AUDIO2CanonicalRequest generated audio output where the model supports it.
Section ID: DOC-API-MODEL-schema-1h82h7ri5p#validation

Request validation​

Section ID: DOC-API-MODEL-schema-1h82h7ri5p#response-validation

These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules.

Applies toRuleRequirement
languagePreferenceMinimum length2
languagePreferencePattern^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$

Where used​

Section ID: DOC-API-MODEL-schema-1h82h7ri5p#where-used

ReferenceRelationship
Create an agent profilePOST /api/v1/agent-profiles/create
Get an agent profilePOST /api/v1/agent-profiles/get
Import a prompt libraryPOST /api/v1/agent-profiles/import
List agent profilesPOST /api/v1/agent-profiles/list
Update an agent profilePOST /api/v1/agent-profiles/update
Withdraw your rating on a messagePOST /api/v1/llm/delete-message-rating
Get full conversation statePOST /api/v1/llm/conversation-state
Rate an assistant messagePOST /api/v1/llm/rate-message
Send a message and wait for the resultPOST /api/v1/llm/send-message-sync
Submit client-side tool results and wait for the next segmentPOST /api/v1/llm/submit-client-tool-results-sync
Update context management settingsPOST /api/v1/llm/update-context-management-settings
Update default generation configPOST /api/v1/llm/update-default-generation-config
Get the caller's end-user profilePOST /api/v1/enduser/get
Append a message without generatingPOST /api/v1/llm/append-message
Create a new conversation threadPOST /api/v1/llm/create-thread
Send a message to a conversationPOST /api/v1/llm/send-message
Update the caller's default generation configPOST /api/v1/enduser/update-generation-config
ReceiveMessageRequestAPI JSON uses JSON field names (camelCase).
ClientToolDispatchAPI JSON uses JSON field names (camelCase).
Models containing this value
ModelRelationship
CompactionConfigNested in model
CompactionConfigNested in model
AgentProfileNested in model
AgentProfileNested in model
GenerationContextNested in model
GenerationContextNested in model
LLMGenerationStartedEventNested in model
LLMGenerationStartedEventNested in model
SourcePromptTemplateNested in model
EndUserStateNested in model

Download the public reference contract.

Document ID: DOC-API-MODEL-schema-1h82h7ri5p