DOC-API-MODEL-schema-1j3dcf7kvu#overview
Message
Chat message
At least one of content or tool_calls must contain an entry; both lists may be nonempty. role must select a listed message role. Requiredness and allowed values are declared separately.
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-1j3dcf7kvu#meaning
See the definition above.
Usage profiles
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#fields
| Usage | Fields and validation |
|---|---|
| In requests | View fields |
| In responses | View fields |
In requests
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#request
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#request-field-rolerole | string (ROLE_SYSTEM, ROLE_USER, ROLE_ASSISTANT, ROLE_TOOL) or integer (int32) (0, 1, 2, 3) | Required in requests | Role of the participant that produced the chat message. |
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#request-field-contentcontent | Array of ContentPart | Optional | Content parts composing the chat message. |
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#request-field-toolcallstoolCalls | Array of ToolCall | Optional | Assistant-to-tool invocations. |
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#request-field-namename | string | Optional | See meaning below. |
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#request-field-timestamptimestamp | string (date-time) | Optional | Timestamp associated with the conversation message or event. |
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#request-field-messageidmessageId | string | Optional | Unique message identifier. |
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#request-field-annotationsannotations | Array of Annotation | Optional | Structured annotations (e.g., standardized web search URL citations, PDF reuse tokens) |
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#request-field-sequencesequence | string (int64) | Optional | Monotonic, per-conversation sequence number for stable ordering (1-based) Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#request-field-generatedbygeneratedBy | string | Optional | Workflow run id or generator key that produced this message (e.g., workflow run key) |
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#request-field-usageusage | Usage | Optional | Token usage for this generation (populated for assistant messages) |
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#request-field-modelmodel | string | Optional | Model that generated this message (e.g., "anthropic/claude-sonnet-4") |
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#request-field-generationcontextgenerationContext | GenerationContext | Optional | Dynamic context that shaped this generation (memories, search params, turn info) |
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#request-field-clientcontextclientContext | ClientContext | Optional | Arbitrary client-supplied context attached by the client for this message |
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#request-field-feedbackfeedback | Array of MessageFeedback | Optional | Feedback on an assistant message, with one entry per rater identified by rated_by. A later rating by the same rater replaces their earlier entry. |
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#request-field-sourceusermessageidsourceUserMessageId | string | Optional | See meaning below. |
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#request-field-finishreasonfinishReason | string | Optional | Why the model stopped, verbatim from the provider: "stop", "tool_calls", "length", "error". Empty for historical messages. |
name
Name identifying the sender of the chat message.
optional sender name
sourceUserMessageId
Identifier of the user message that opened this conversation turn. Generated messages in the same turn share this value; a user message carries its own message_id. Empty on historical messages that predate turn attribution.
Use this field for turn attribution rather than inferring it from message adjacency or a client-supplied message_id. The generated_by identifier groups messages by generation run but does not identify the user message that opened the turn.
Values of role
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#request-values-role
Participant role attached to a conversation message and forwarded in model context.
| Value | No. | Form | Meaning |
|---|---|---|---|
ROLE_SYSTEM | 0 | Canonical | Instructions or context provided as a system message. |
ROLE_USER | 1 | Canonical | Input supplied by the user or customer application. |
ROLE_ASSISTANT | 2 | Canonical | Content produced by the assistant, including its tool-call requests. |
ROLE_TOOL | 3 | Canonical | A tool result supplied back to the assistant. |
Request validation
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#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 |
|---|---|---|
| Message | native.group.message_content | content or tool_calls required |
role | Required value | true |
role | Defined enum value | true |
In responses
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#response
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#field-roleSection ID: DOC-API-MODEL-schema-1j3dcf7kvu#response-field-rolerole | string (ROLE_SYSTEM, ROLE_USER, ROLE_ASSISTANT, ROLE_TOOL) or integer (int32) | Required in requests | Role of the participant that produced the chat message. |
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#field-contentSection ID: DOC-API-MODEL-schema-1j3dcf7kvu#response-field-contentcontent | Array of ContentPart | Optional | Content parts composing the chat message. |
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#field-toolcallsSection ID: DOC-API-MODEL-schema-1j3dcf7kvu#response-field-toolcallstoolCalls | Array of ToolCall | Optional | Assistant-to-tool invocations. |
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#field-nameSection ID: DOC-API-MODEL-schema-1j3dcf7kvu#response-field-namename | string | Optional | See meaning below. |
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#field-timestampSection ID: DOC-API-MODEL-schema-1j3dcf7kvu#response-field-timestamptimestamp | string (date-time) | Optional | Timestamp associated with the conversation message or event. |
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#field-messageidSection ID: DOC-API-MODEL-schema-1j3dcf7kvu#response-field-messageidmessageId | string | Optional | Unique message identifier. |
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#field-annotationsSection ID: DOC-API-MODEL-schema-1j3dcf7kvu#response-field-annotationsannotations | Array of Annotation | Optional | Structured annotations (e.g., standardized web search URL citations, PDF reuse tokens) |
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#field-sequenceSection ID: DOC-API-MODEL-schema-1j3dcf7kvu#response-field-sequencesequence | string (int64) | Optional | Monotonic, per-conversation sequence number for stable ordering (1-based) Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#field-generatedbySection ID: DOC-API-MODEL-schema-1j3dcf7kvu#response-field-generatedbygeneratedBy | string | Optional | Workflow run id or generator key that produced this message (e.g., workflow run key) |
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#field-usageSection ID: DOC-API-MODEL-schema-1j3dcf7kvu#response-field-usageusage | Usage | Optional | Token usage for this generation (populated for assistant messages) |
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#field-modelSection ID: DOC-API-MODEL-schema-1j3dcf7kvu#response-field-modelmodel | string | Optional | Model that generated this message (e.g., "anthropic/claude-sonnet-4") |
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#field-generationcontextSection ID: DOC-API-MODEL-schema-1j3dcf7kvu#response-field-generationcontextgenerationContext | GenerationContext | Optional | Dynamic context that shaped this generation (memories, search params, turn info) |
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#field-clientcontextSection ID: DOC-API-MODEL-schema-1j3dcf7kvu#response-field-clientcontextclientContext | ClientContext | Optional | Arbitrary client-supplied context attached by the client for this message |
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#field-feedbackSection ID: DOC-API-MODEL-schema-1j3dcf7kvu#response-field-feedbackfeedback | Array of MessageFeedback | Optional | Feedback on an assistant message, with one entry per rater identified by rated_by. A later rating by the same rater replaces their earlier entry. |
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#field-sourceusermessageidSection ID: DOC-API-MODEL-schema-1j3dcf7kvu#response-field-sourceusermessageidsourceUserMessageId | string | Optional | See meaning below. |
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#field-finishreasonSection ID: DOC-API-MODEL-schema-1j3dcf7kvu#response-field-finishreasonfinishReason | string | Optional | Why the model stopped, verbatim from the provider: "stop", "tool_calls", "length", "error". Empty for historical messages. |
name
Name identifying the sender of the chat message.
optional sender name
sourceUserMessageId
Identifier of the user message that opened this conversation turn. Generated messages in the same turn share this value; a user message carries its own message_id. Empty on historical messages that predate turn attribution.
Use this field for turn attribution rather than inferring it from message adjacency or a client-supplied message_id. The generated_by identifier groups messages by generation run but does not identify the user message that opened the turn.
Values of role
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#response-values-role
Participant role attached to a conversation message and forwarded in model context.
| Value | No. | Form | Meaning |
|---|---|---|---|
ROLE_SYSTEM | 0 | Canonical | Instructions or context provided as a system message. |
ROLE_USER | 1 | Canonical | Input supplied by the user or customer application. |
ROLE_ASSISTANT | 2 | Canonical | Content produced by the assistant, including its tool-call requests. |
ROLE_TOOL | 3 | Canonical | A tool result supplied back to the assistant. |
DOC-API-MODEL-schema-1j3dcf7kvu#validation
Request validation
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#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 |
|---|---|---|
| Message | native.group.message_content | content or tool_calls required |
role | Required value | true |
role | Defined enum value | true |
Where used
Section ID: DOC-API-MODEL-schema-1j3dcf7kvu#where-used
| Reference | Relationship |
|---|---|
| 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 |
| Append a message without generating | POST /api/v1/llm/append-message |
| Send a message to a conversation | POST /api/v1/llm/send-message |
| ReceiveMessageRequest | API JSON uses JSON field names (camelCase). |
| ClientToolDispatch | API JSON uses JSON field names (camelCase). |
Models containing this value
| Model | Relationship |
|---|---|
| ReceiveMessageRequest | Nested in model |
| ReceiveMessageRequest | Nested in model |
| LLMMessagePublishedEvent | Nested in model |
| LLMMessagePublishedEvent | Nested in model |
| ClientToolDispatch | Nested in model |
| ClientToolDispatch | Nested in model |
Download the public reference contract.
Document ID: DOC-API-MODEL-schema-1j3dcf7kvu