Skip to main content
POST
/
voice
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
)
voice_session_response = client.voice.start_session()
print(voice_session_response.agent_id)
{
  "object": "voice.session",
  "url": "<string>",
  "agent_id": "<string>",
  "start_message": {}
}

Authorizations

​
Authorization
string
header
required

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

Body

application/json
​
agent_id
string | null

The ID of the agent to use for the voice conversation. If not provided, the default agent is used.

​
conversation_id
string | null

The ID of an existing conversation to continue. If not provided, a new conversation will be created.

​
config
object

Override the agent config for this voice session. Only prompt overrides are supported — voice sessions always use Gemini Live, so LLM model, agent model, planning prompt, and tool settings are not applicable.

​
file_ids
string[] | null

Array of file IDs to attach to the voice conversation.

​
secret_ids
string[] | null

Array of secret IDs to include in the context.

​
knowledge_ids
string[] | null

Array of knowledge IDs to make accessible to the agent.

​
page_ids
string[] | null

Array of page IDs to make accessible to the agent. The page and all knowledge under it will be accessible.

​
user
object

Override user information for this voice session.

​
initial_context
string | null

Optional context text for the voice session. When provided, the AI will start by briefly explaining this content before listening for user input.

Maximum string length: 2000
​
initial_message
string | null

Optional initial user message. When provided, the system greeting is skipped and the AI responds directly to this text (e.g. a suggested prompt). Takes precedence over initial_context.

Maximum string length: 2000
​
ephemeral
boolean | null
default:false

When true, the session is ephemeral and will not save messages to conversation history.

​
voice_config
object

Voice session configuration options.

Response

Voice session prepared

​
object
enum<string>
required

Object type discriminator.

Available options:
voice.session
​
url
string
required

WebSocket URL to connect to. Includes the authentication token as a query parameter.

​
agent_id
string
required

The resolved agent ID. If no agent was specified in the request, this is the default agent.

​
start_message
object
required

Ready-made JSON message to send as the first WebSocket frame after connecting. Contains type: "start" and a payload with all session parameters.