Converse
Converse with an AI Agent
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
A text prompt to send to the agent.
Override the agent config for this converse call. This is applied as a partial override.
The ID of the agent that should be used for the converse. When omitted and a conversation_id is provided, the conversation's existing agent assignments are preserved. When omitted without a conversation_id, a new conversation is created with the default agent.
Controls how the API selects which agent to use when routing is needed. This field is mutually exclusive with agent_id. When both agent_id and agent_routing are omitted and a conversation_id is provided, the conversation's existing agent assignments are preserved.
- Auto routing
- Manual routing
The ID of the present conversation to use. If it's not provided - a new conversation will be created.
Determines the response type of the converse. Response is the Server-Sent Events if stream is set to true.
Determines whether the response should include citations. When enabled, the agent will generate citations for factual statements.
Determines whether generated_title metadata should be included. Defaults to false. generated_title is emitted only when this flag is explicitly true.
When set to false, tool call and reasoning step events are omitted from SSE streams. Non-streaming responses always include the tool_calls and reasoning fields (as null when empty).
Controls how the agent processes the request for this turn. Matches the chat mode selector in the Datagrid web app: Execute (full_agent), Extended (light_agent), Ask (llm_router). When set to auto, the router jointly predicts the best agent and concrete mode (full_agent / light_agent / llm_router) per message. When set to a concrete mode, that mode is used directly. When omitted, the mode is determined by the agent_model in config.
auto, full_agent, light_agent, llm_router Array of secret ID's to be included in the context. The secret value will be appended to the prompt but not stored in conversation history.
Contains the format property used to specify the structured output schema (text.format).
Structured output is supported for all agent_model values and chat_mode settings when text.format is provided (same JSON Schema mechanism everywhere). Ask in the web app maps to chat_mode magpie-2.5-flash;.
Override user information for this converse call. This allows you to override the first_name, last_name, and email that will be used in the conversation context.
A datagrid file URI pointing to content the user is currently viewing on screen (e.g., a web page, document, or dashboard rendered as markdown). The agent uses this context to resolve ambiguous queries like 'what is this about?' or 'review this'. The content is automatically summarized and made available to the agent.
Optional deterministic reference date override in YYYY-MM-DD format. Must be a real calendar date (for example, rejects impossible dates like 2026-02-31). When set, the agent treats this date as today for relative date resolution and date context rendering.
^[0-9]{4}-[0-9]{2}-[0-9]{2}$Response
Converse response
The conversation.message object represents a message in a conversation.
The object type, which is always conversation.message.
conversation.message The message identifier.
The ID of the agent that sent or responded to the message.
The role of the message sender - either 'user' or 'agent'.
user, agent Contents of the message.
Text content for a message.
- Option 1
- Option 2
- Option 3
The ISO string for when the message was created.
The ID of the conversation the message belongs to.
Credit consumption for this converse turn. null for user-role messages and when retrieving messages from conversation history.
Array of citations that provide sources for factual statements in the response. Each citation includes the referenced text and its sources.
The chat mode used for this response (web app: Execute = full_agent, Extended = light_agent, Ask = llm_router). For Auto mode conversations, this is the mode selected by the router for this turn.
full_agent, light_agent, llm_router Auto-generated conversation title for this turn. Null when title generation does not run or fails.
Array of tool calls that were executed during this response.
Array of reasoning steps that occurred during this response. Only includes steps with status completed or failed.