ProviderPreferences

Routing preferences restricting and ordering the model providers eligible for a request.

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
order	Array of string	Optional	Preferred ordering of model providers for routing.
allowFallbacks	boolean	Optional	Whether provider routing may fall back beyond the preferred order.
requireParameters	boolean	Optional	Whether routing requires providers to support the requested parameters.
dataCollection	string (DATA_COLLECTION_MODE_ALLOW, DATA_COLLECTION_MODE_DENY) or integer (int32)	Optional	Provider data-collection preference used when routing the request.
zdr	boolean	Optional	Whether routing requests providers offering zero data retention.
only	Array of string	Optional	Provider identifiers allowed by the routing preference.
ignore	Array of string	Optional	Provider identifiers excluded by the routing preference.
quantizations	Array of string	Optional	Model quantization formats allowed by the routing preference.
sort	string (PROVIDER_SORT_PRICE, PROVIDER_SORT_THROUGHPUT, PROVIDER_SORT_LATENCY) or integer (int32)	Optional	Metric used to order eligible model providers.
maxPrice	ProviderMaxPrice	Optional	Upper price bounds used when selecting a model provider.
enforceDistillableText	boolean	Optional	Embeddings: enforce distillable text.
preferredMinThroughput	PercentileThreshold	Optional	Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list.
preferredMaxLatency	PercentileThreshold	Optional	Deprioritize providers above this latency (ms).

Values of dataCollection

Provider-routing preference for whether providers may collect submitted data.

Value	No.	Form	Meaning
DATA_COLLECTION_MODE_ALLOW	1	Canonical	Allow routing to providers that may collect submitted data under their policies.
DATA_COLLECTION_MODE_DENY	2	Canonical	Request routing only to providers that do not collect submitted data under the routing policy.

Values of sort

Metric used to order eligible model providers.

Value	No.	Form	Meaning
PROVIDER_SORT_PRICE	1	Canonical	Prefer providers with lower price.
PROVIDER_SORT_THROUGHPUT	2	Canonical	Prefer providers with higher throughput.
PROVIDER_SORT_LATENCY	3	Canonical	Prefer providers with lower latency.

In responses

API JSON uses JSON field names (camelCase).

Field	Type	Presence	Meaning
order	Array of string	Optional	Preferred ordering of model providers for routing.
allowFallbacks	boolean	Optional	Whether provider routing may fall back beyond the preferred order.
requireParameters	boolean	Optional	Whether routing requires providers to support the requested parameters.
dataCollection	string (DATA_COLLECTION_MODE_ALLOW, DATA_COLLECTION_MODE_DENY) or integer (int32)	Optional	Provider data-collection preference used when routing the request.
zdr	boolean	Optional	Whether routing requests providers offering zero data retention.
only	Array of string	Optional	Provider identifiers allowed by the routing preference.
ignore	Array of string	Optional	Provider identifiers excluded by the routing preference.
quantizations	Array of string	Optional	Model quantization formats allowed by the routing preference.
sort	string (PROVIDER_SORT_PRICE, PROVIDER_SORT_THROUGHPUT, PROVIDER_SORT_LATENCY) or integer (int32)	Optional	Metric used to order eligible model providers.
maxPrice	ProviderMaxPrice	Optional	Upper price bounds used when selecting a model provider.
enforceDistillableText	boolean	Optional	Embeddings: enforce distillable text.
preferredMinThroughput	PercentileThreshold	Optional	Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list.
preferredMaxLatency	PercentileThreshold	Optional	Deprioritize providers above this latency (ms).

Values of dataCollection

Provider-routing preference for whether providers may collect submitted data.

Value	No.	Form	Meaning
DATA_COLLECTION_MODE_ALLOW	1	Canonical	Allow routing to providers that may collect submitted data under their policies.
DATA_COLLECTION_MODE_DENY	2	Canonical	Request routing only to providers that do not collect submitted data under the routing policy.

Values of sort

Metric used to order eligible model providers.

Value	No.	Form	Meaning
PROVIDER_SORT_PRICE	1	Canonical	Prefer providers with lower price.
PROVIDER_SORT_THROUGHPUT	2	Canonical	Prefer providers with higher throughput.
PROVIDER_SORT_LATENCY	3	Canonical	Prefer providers with lower latency.

In webhook payloads

Webhook JSON uses protobuf field names (snake_case).

Field	Type	Presence	Meaning
order	Array of string	Optional	Preferred ordering of model providers for routing.
allow_fallbacks	boolean	Optional	Whether provider routing may fall back beyond the preferred order.
require_parameters	boolean	Optional	Whether routing requires providers to support the requested parameters.
data_collection	string (DATA_COLLECTION_MODE_ALLOW, DATA_COLLECTION_MODE_DENY) or integer (int32)	Optional	Provider data-collection preference used when routing the request.
zdr	boolean	Optional	Whether routing requests providers offering zero data retention.
only	Array of string	Optional	Provider identifiers allowed by the routing preference.
ignore	Array of string	Optional	Provider identifiers excluded by the routing preference.
quantizations	Array of string	Optional	Model quantization formats allowed by the routing preference.
sort	string (PROVIDER_SORT_PRICE, PROVIDER_SORT_THROUGHPUT, PROVIDER_SORT_LATENCY) or integer (int32)	Optional	Metric used to order eligible model providers.
max_price	ProviderMaxPrice	Optional	Upper price bounds used when selecting a model provider.
enforce_distillable_text	boolean	Optional	Embeddings: enforce distillable text.
preferred_min_throughput	PercentileThreshold	Optional	Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list.
preferred_max_latency	PercentileThreshold	Optional	Deprioritize providers above this latency (ms).

Values of data_collection

Provider-routing preference for whether providers may collect submitted data.

Value	No.	Form	Meaning
DATA_COLLECTION_MODE_ALLOW	1	Canonical	Allow routing to providers that may collect submitted data under their policies.
DATA_COLLECTION_MODE_DENY	2	Canonical	Request routing only to providers that do not collect submitted data under the routing policy.

Values of sort

Metric used to order eligible model providers.

Value	No.	Form	Meaning
PROVIDER_SORT_PRICE	1	Canonical	Prefer providers with lower price.
PROVIDER_SORT_THROUGHPUT	2	Canonical	Prefer providers with higher throughput.
PROVIDER_SORT_LATENCY	3	Canonical	Prefer providers with lower latency.

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.

• agent-profiles OpenAPI
• conversations OpenAPI
• end-users OpenAPI

Document: DOC-API-MODEL-provider-preferences.