Skip to main content
POST
Execute realtime tool

Authorizations

x-access-token
string
header
required

JWT token passed in x-access-token header

Body

application/json
function
object
required
call_id
string

The provider's call id for this tool call; echoed onto TOOL_PROGRESS events.

assistantId
string

Assistant to scope the call to (verified against the caller's institution).

rtProvider
enum<string> | null

The realtime dialect this session was minted in. Required to resolve a bridged MCP connector tool (<serverLabel>__<toolName>); omit it — or send null, which means the same thing — and only built-in tools resolve. Any OTHER value off the list is rejected with 400 INVALID_RT_PROVIDER.

Available options:
openai_cli,
xai_cli,
google_cli
conversationId
number

The conversation thread this realtime session is bound to. Used only to key connector-approval decisions, so that Approve for this conversation can be offered and a standing grant consulted. Ignored unless it is a finite number greater than zero; a malformed value is never an error.

approvalSurface
boolean

Send true only when the client has an approval row host mounted and can show the decision to the user. Only the boolean true holds the request open for a human decision; absent, false or any other value means the call is answered immediately with the not-available-in-this-channel text.

backgroundJobs
boolean

Send true only when the client can deliver a background result on the next turn (it polls /api/ai/rtTools/jobs). Only the boolean true counts. The call then races the per-turn voice tool budget (VOICE_TOOL_BUDGET_MS, 6 s by default; RT_TOOL_BUDGET=0 switches it off on this lane) and, when it runs longer, keeps running in the background while the model is told it is underway. Needs a job conversation, conversationId or jobKey; without one the call runs as before.

jobKey
string

A session nonce minted by the client, the job conversation when there is no conversationId. Jobs stay filtered by the requesting user. A malformed value is ignored, never an error.

Pattern: ^rt:[A-Za-z0-9_-]{8,64}$
turnId
string

The user turn this call belongs to. Calls of one turn share one budget; without it each call gets its own. A malformed value is ignored.

Maximum string length: 80
Pattern: ^[A-Za-z0-9:_-]+$

Response

Tool executed successfully

success
boolean
callId
string

Call ID for correlation

result
object

Tool execution result

error
string

Error message if execution failed

approval
object

The connector-approval outcome, present only when this call went through the approval gate. Display and audit metadata for the saved tool record; the authoritative record is the approval row itself, whose id arrived on the TOOL_APPROVAL socket frame.

background
object

Present only when the call went to the background (backgroundJobs was sent). The data carries the text the model reads; the result is reported by /api/ai/rtTools/jobs for the next turn.