ResponseFormat
Structured response control
When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version.
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 |
|---|---|---|---|
jsonObject | boolean | Optional | Whether the model provider is requested to return a valid JSON object. |
jsonSchema | Map from string to JSON value | Optional | JSON Schema describing the requested structured model output. |
schemaName | string | Optional | Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json_schema.name. |
validate | boolean | Optional; explicit presence | Enable server-side validation of the response against json_schema. Default: true when json_schema is set (applied in Go when not explicitly set). |
maxValidationRetries | integer (int32) | Optional; explicit presence | Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Minimum: 0. Maximum: 3. |
responseHealing | boolean | Optional; explicit presence | Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json_schema unless explicitly disabled. |
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 to | Rule | Requirement |
|---|---|---|
maxValidationRetries | At most | 3 |
maxValidationRetries | At least | 0 |
In responses
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
jsonObject | boolean | Optional | Whether the model provider is requested to return a valid JSON object. |
jsonSchema | Map from string to JSON value | Optional | JSON Schema describing the requested structured model output. |
schemaName | string | Optional | Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json_schema.name. |
validate | boolean | Optional; explicit presence | Enable server-side validation of the response against json_schema. Default: true when json_schema is set (applied in Go when not explicitly set). |
maxValidationRetries | integer (int32) | Optional; explicit presence | Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Minimum: -2147483648. Maximum: 2147483647. |
responseHealing | boolean | Optional; explicit presence | Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json_schema unless explicitly disabled. |
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 to | Rule | Requirement |
|---|---|---|
maxValidationRetries | At most | 3 |
maxValidationRetries | At least | 0 |
In webhook payloads
Webhook JSON uses protobuf field names (snake_case).
| Field | Type | Presence | Meaning |
|---|---|---|---|
json_object | boolean | Optional | Whether the model provider is requested to return a valid JSON object. |
json_schema | Map from string to JSON value | Optional | JSON Schema describing the requested structured model output. |
schema_name | string | Optional | Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json_schema.name. |
validate | boolean | Optional; explicit presence | Enable server-side validation of the response against json_schema. Default: true when json_schema is set (applied in Go when not explicitly set). |
max_validation_retries | integer (int32) | Optional; explicit presence | Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Minimum: -2147483648. Maximum: 2147483647. |
response_healing | boolean | Optional; explicit presence | Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json_schema unless explicitly disabled. |
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 to | Rule | Requirement |
|---|---|---|
max_validation_retries | At most | 3 |
max_validation_retries | At least | 0 |
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-response-format.