Skip to main content
POST
Python

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
prompt
required

A text prompt to send to the agent.

config
object | null

Override the agent config for this converse call. This is applied as a partial override.

agent_id
string | null

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.

agent_routing
Auto routing · object

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.

conversation_id
string | null

The ID of the present conversation to use. If it's not provided - a new conversation will be created.

stream
boolean | null
default:false

Determines the response type of the converse. Response is the Server-Sent Events if stream is set to true.

generate_citations
boolean | null
default:false

Determines whether the response should include citations. When enabled, the agent will generate citations for factual statements.

generate_title
boolean | null
default:false

Determines whether generated_title metadata should be included. Defaults to false. generated_title is emitted only when this flag is explicitly true.

include_steps
boolean | null
default: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).

chat_mode
enum<string> | null

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.

Available options:
auto,
full_agent,
light_agent,
llm_router
secret_ids
string[] | null

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.

text
object | null

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;.

user
object | null

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.

current_view_content
string | null

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.

reference_date
string<date> | null

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.

Pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

Response

Converse response

The conversation.message object represents a message in a conversation.

object
enum<string>
required

The object type, which is always conversation.message.

Available options:
conversation.message
id
string
required

The message identifier.

agent_id
string
required

The ID of the agent that sent or responded to the message.

role
enum<string>
required

The role of the message sender - either 'user' or 'agent'.

Available options:
user,
agent
content
object[]
required

Contents of the message.

Text content for a message.

created_at
string<date-time>
required

The ISO string for when the message was created.

conversation_id
string
required

The ID of the conversation the message belongs to.

credits
object | null
required

Credit consumption for this converse turn. null for user-role messages and when retrieving messages from conversation history.

citations
object[] | null
required

Array of citations that provide sources for factual statements in the response. Each citation includes the referenced text and its sources.

chat_mode
enum<string> | null

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.

Available options:
full_agent,
light_agent,
llm_router
generated_title
string | null

Auto-generated conversation title for this turn. Null when title generation does not run or fails.

tool_calls
object[] | null

Array of tool calls that were executed during this response.

reasoning
object[] | null

Array of reasoning steps that occurred during this response. Only includes steps with status completed or failed.