DOC-API-MODEL-schema-1g69v4vltg#overview
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.
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-1g69v4vltg#meaning
See the definition above.
Usage profiles
Section ID: DOC-API-MODEL-schema-1g69v4vltg#fields
| Usage | Fields and validation |
|---|---|
| In requests | View fields |
| In responses | View fields |
In requests
Section ID: DOC-API-MODEL-schema-1g69v4vltg#request
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
Section ID: DOC-API-MODEL-schema-1g69v4vltg#request-field-jsonobjectjsonObject | boolean | Optional | See meaning below. |
Section ID: DOC-API-MODEL-schema-1g69v4vltg#request-field-jsonschemajsonSchema | Map from string to JSON value | Optional | See meaning below. |
Section ID: DOC-API-MODEL-schema-1g69v4vltg#request-field-schemanameschemaName | string | Optional | Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json_schema.name. |
Section ID: DOC-API-MODEL-schema-1g69v4vltg#request-field-validatevalidate | 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). |
Section ID: DOC-API-MODEL-schema-1g69v4vltg#request-field-maxvalidationretriesmaxValidationRetries | string (int64) | 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). Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-1g69v4vltg#request-field-responsehealingresponseHealing | boolean | Optional; explicit presence | Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json_schema unless explicitly disabled. |
jsonObject
Whether the model provider is requested to return a valid JSON object.
enforce valid JSON object
jsonSchema
JSON Schema describing the requested structured model output.
optional JSON Schema (draft-07+)
Request validation
Section ID: DOC-API-MODEL-schema-1g69v4vltg#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
Section ID: DOC-API-MODEL-schema-1g69v4vltg#response
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
Section ID: DOC-API-MODEL-schema-1g69v4vltg#field-jsonobjectSection ID: DOC-API-MODEL-schema-1g69v4vltg#response-field-jsonobjectjsonObject | boolean | Optional | See meaning below. |
Section ID: DOC-API-MODEL-schema-1g69v4vltg#field-jsonschemaSection ID: DOC-API-MODEL-schema-1g69v4vltg#response-field-jsonschemajsonSchema | Map from string to JSON value | Optional | See meaning below. |
Section ID: DOC-API-MODEL-schema-1g69v4vltg#field-schemanameSection ID: DOC-API-MODEL-schema-1g69v4vltg#response-field-schemanameschemaName | string | Optional | Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json_schema.name. |
Section ID: DOC-API-MODEL-schema-1g69v4vltg#field-validateSection ID: DOC-API-MODEL-schema-1g69v4vltg#response-field-validatevalidate | 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). |
Section ID: DOC-API-MODEL-schema-1g69v4vltg#field-maxvalidationretriesSection ID: DOC-API-MODEL-schema-1g69v4vltg#response-field-maxvalidationretriesmaxValidationRetries | string (int64) | 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). Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-1g69v4vltg#field-responsehealingSection ID: DOC-API-MODEL-schema-1g69v4vltg#response-field-responsehealingresponseHealing | boolean | Optional; explicit presence | Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json_schema unless explicitly disabled. |
jsonObject
Whether the model provider is requested to return a valid JSON object.
enforce valid JSON object
jsonSchema
JSON Schema describing the requested structured model output.
optional JSON Schema (draft-07+)
Section ID:DOC-API-MODEL-schema-1g69v4vltg#validation
Request validation
Section ID: DOC-API-MODEL-schema-1g69v4vltg#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 to | Rule | Requirement |
|---|---|---|
maxValidationRetries | At most | 3 |
maxValidationRetries | At least | 0 |
Where used
Section ID: DOC-API-MODEL-schema-1g69v4vltg#where-used
| Reference | Relationship |
|---|---|
| Create an agent profile | POST /api/v1/agent-profiles/create |
| Get an agent profile | POST /api/v1/agent-profiles/get |
| Import a prompt library | POST /api/v1/agent-profiles/import |
| List agent profiles | POST /api/v1/agent-profiles/list |
| Update an agent profile | POST /api/v1/agent-profiles/update |
| 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 |
| Send a message and wait for the result | POST /api/v1/llm/send-message-sync |
| Submit client-side tool results and wait for the next segment | POST /api/v1/llm/submit-client-tool-results-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 |
| Get the caller's end-user profile | POST /api/v1/enduser/get |
| 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 |
| Update the caller's default generation config | POST /api/v1/enduser/update-generation-config |
| ReceiveMessageRequest | API JSON uses JSON field names (camelCase). |
| ClientToolDispatch | API JSON uses JSON field names (camelCase). |
Models containing this value
| Model | Relationship |
|---|---|
| GenerationConfig | Nested in model |
| GenerationConfig | Nested in model |
Download the public reference contract.
Document ID: DOC-API-MODEL-schema-1g69v4vltg