Skip to main content
POST
/
converse
Python
import os
from datagrid_ai import Datagrid

client = Datagrid(
    api_key=os.environ.get("DATAGRID_API_KEY"),  # This is the default and can be omitted
)
converse_response = client.converse(
    prompt="string",
)
print(converse_response)
{
  "object": "conversation.message",
  "id": "<string>",
  "agent_id": "<string>",
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "<string>"
    }
  ],
  "created_at": "2023-11-07T05:31:56Z",
  "conversation_id": "<string>",
  "credits": {
    "consumed": 123
  },
  "citations": [
    {
      "citation": "<string>",
      "sources": [
        {
          "type": "image",
          "source_name": "<string>",
          "confirmations": [
            "<string>"
          ],
          "source_id": "<string>",
          "source_uri": "<string>"
        }
      ]
    }
  ],
  "tool_calls": [
    {
      "type": "tool_call",
      "id": "<string>",
      "status": "in_progress",
      "tool": {
        "object": "tool",
        "name": "<string>",
        "label": "<string>",
        "description": "<string>"
      },
      "output": "<string>",
      "executed_in_parallel": true
    }
  ],
  "reasoning": [
    {
      "id": "<string>",
      "status": "in_progress",
      "type": "reasoning",
      "task": "<string>",
      "output": "<string>",
      "execution_time_ms": 123,
      "executed_in_parallel": true
    }
  ]
}

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

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.

​
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).

​
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

Contains the format property used to specify the structured output schema. Structured output is supported by the following agent models: magpie-2.0 (default), magpie-2.5, and magpie-1.1. It is not supported by magpie-1.1-flash (Ask mode) or llm-only (Fastest mode).

​
user
object

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.

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

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