> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praxis-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Report one voice turn-prediction outcome
> One record per predicted user turn: timings, verdict summaries and enums, and the
words the prediction worked on — the heard text as it grew (`heardTimeline`), the
final text, the text each check judged, each interruption's words and the twin's
last spoken words. `shadow` records (and any record when prediction is on) are kept
as a 30-day sample, used to improve the turn-taking model; the words are kept with
the same care as the conversation history and are never written to logs. `commit`,
`discard` and `blocked` are accepted and logged. One record per `turnKey` is kept,
with a daily per-user limit; a repeat or a record over the limit is still answered `204`.
Unknown enum values, out-of-range numbers, over-long arrays, over-long or non-string
text, tool names that are not `[a-z0-9_]` identifiers or bad ids reject the body
with `400` (text is not trimmed: send it within the limits). Unknown keys are dropped.
Keep the whole record under 48 KB.
## OpenAPI
````yaml /mdx/api-reference/runtime/runtime-api.json post /api/ai/rtProxy/voiceTurn/spec
openapi: 3.0.0
info:
title: Pria Runtime API
version: 2.0.262
description: >-
Pria API Documentation Praxis's developer platform is a core part of our
mission to empower organizations to grow better. Our APIs are designed to
enable teams of any shape or size to build robust integrations that help
them customize and get the most value out of Pria. All Pria APIs are built
using REST conventions and designed to have a predictable URL structure.
They use many standard HTTP features, including methods (POST,
GET, PUT, DELETE) and error response codes.
All API calls are
made under https://hiimpria.ai/api and all responses return standard JSON.
In these docs, you'll find lists of all available endpoints for a given API,
along with interactive code blocks for building requests. For walkthroughs
of basic usage for these APIs, check out the API guides.
A
session that a course page (Canvas) opened for an administrator — or that a
Digital Twin's sign-in provider opened for one of its people — starts with
user rights in that twin only: until the person confirms it's them with a
code (POST /api/user/launch-scope/challenge, then /api/auth/mfa-resend and
/api/auth/mfa-verify), every route outside that twin's day-to-day work
answers 403 with code LAUNCH_SCOPE_STEP_UP and the twin's id.
servers:
- url: https://pria.praxislxp.com
description: Pria API Server
security: []
tags:
- name: Authentication
description: User authentication, registration, and password management (/api/auth)
- name: OAuth
description: OAuth authentication providers - Google, GitHub, SSO (/api/auth/oauth)
- name: User
description: User profile management and account operations (/api/user)
- name: User Institutions
description: User institution memberships and switching (/api/user/institution)
- name: User Tools
description: Available tools for authenticated users (/api/user/tools)
- name: Institutions
description: Institution settings and configuration (/api/user/institution)
- name: Conversation
description: AI conversation and Q&A endpoints (/api/ai)
- name: Realtime
description: Real-time voice AI and WebRTC sessions (/api/ai/rt)
- name: Assistant
description: AI assistant configuration and management (/api/user/assistant)
- name: History
description: Conversation history and favorites (/api/user/history)
- name: RAG
description: >-
Document upload, embedding, and retrieval-augmented generation
(/api/user/files, /api/user/rag)
- name: Setting
description: Instance variables and settings management (/api/user/setting)
- name: Branding
description: Digital twin branding and customization (/api/agent/branding)
- name: Agent
description: Agent engagement and session management (/api/agent)
- name: SDK Launch
description: >-
SDK launch token signing and verification for secure iframe embedding
(/api/auth/sdk-sign, /api/auth/sdk-verify)
- name: Testing
description: Health checks, diagnostics, and test endpoints (/api/test)
- name: Admin Accounts
description: Account management for super admins (/api/admin/account)
- name: Admin Institutions
description: Institution management for admins (/api/admin/institution)
- name: Admin Users
description: User management for admins (/api/admin/user)
- name: Admin Entitlements
description: >-
User-institution relationships and permissions
(/api/admin/userInstitution)
- name: Admin Sessions
description: Session management for admins (/api/admin/session)
- name: Admin Histories
description: Conversation history management and analytics (/api/admin/history)
- name: Admin Assistants
description: AI assistant management for admins (/api/admin/assistant)
- name: Admin Questions
description: Institution question and prompt management (/api/admin/question)
- name: Admin Tools
description: Tool configuration management (/api/admin/tool)
- name: Admin AI Models
description: AI model configuration (/api/admin/aimodel)
- name: Admin MCP Servers
description: Model Context Protocol server management (/api/admin/mcpserver)
- name: Admin Feedbacks
description: User feedback management (/api/admin/feedback)
- name: Admin Uploads
description: Upload management (/api/admin/upload)
- name: Admin Charts
description: Analytics and visualization chart management (/api/admin/chart)
- name: Audio Notes
description: Capture and ingest spoken notes into the personal vault
- name: Memory
description: User-facing memory parameters (personal + shared instance memory).
- name: My Data
description: >-
GDPR controls — personal-scope counts, async ZIP-by-email export, and
scoped soft-delete. Every endpoint pins `user = req.user._id` AND
`institution: null`; institution-scoped data is governed by the
institution's own retention policy and never reached from here.
- name: Questions
description: >-
User-facing read of the onboarding question bank used by the "create a
digital twin" wizard.
- name: Transcription
description: >-
One-shot speech-to-text for in-place dictation. Audio blob in, transcript
out — no Upload / History / RAG embeddings are persisted. Use
`/audio-notes` for anything durable.
paths:
/api/ai/rtProxy/voiceTurn/spec:
post:
tags:
- Realtime
summary: Report one voice turn-prediction outcome
description: >
One record per predicted user turn: timings, verdict summaries and
enums, and the
words the prediction worked on — the heard text as it grew
(`heardTimeline`), the
final text, the text each check judged, each interruption's words and
the twin's
last spoken words. `shadow` records (and any record when prediction is
on) are kept
as a 30-day sample, used to improve the turn-taking model; the words are
kept with
the same care as the conversation history and are never written to logs.
`commit`,
`discard` and `blocked` are accepted and logged. One record per
`turnKey` is kept,
with a daily per-user limit; a repeat or a record over the limit is
still answered `204`.
Unknown enum values, out-of-range numbers, over-long arrays, over-long
or non-string
text, tool names that are not `[a-z0-9_]` identifiers or bad ids reject
the body
with `400` (text is not trimmed: send it within the limits). Unknown
keys are dropped.
Keep the whole record under 48 KB.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- turnKey
- result
properties:
specId:
type: string
pattern: ^[A-Za-z0-9_-]{1,64}$
turnKey:
type: string
pattern: ^[A-Za-z0-9_-]{1,64}$
result:
type: string
enum:
- shadow
- commit
- discard
- blocked
lane:
type: string
enum:
- anam
- cartesia
- embed
- elevenlabs
- gemini
- gpt_live
mode:
type: string
enum:
- shadow
- 'on'
bargeMode:
type: string
enum:
- shadow
- 'on'
description: >-
The predictor's moment C (barge) mode for this turn; `on`
when the lane acted on its barge decisions.
outcome:
type: string
enum:
- hit_fast
- hit_end
- miss_drift
- miss_end
- fresh
- blocked
- error
- none
reason:
type: string
enum:
- ttl
- mute
- stt
- ended
- nonce
- instruction
- same_miss
- drift
- cut
- refused
- blocked
- error
- deadline
- fingerprint
trigger:
type: string
enum:
- predict
- eager
- end
- flux
discard:
type: array
maxItems: 10
items:
type: string
finalText:
type: string
maxLength: 4000
description: The user's final text for the turn.
heardTimeline:
type: array
maxItems: 60
description: >-
Each heard update that changed the text (the text so far for
the turn).
items:
type: object
properties:
atMs:
type: number
description: Relative to the turn's decision time.
text:
type: string
maxLength: 2000
lastAssistant:
type: string
maxLength: 600
description: >-
The end of what the twin last said, as the prediction saw
it.
intervalMs:
type: number
decideMs:
type: number
fluxDecideMs:
type: number
finalT0Ms:
type: number
minimum: 0
description: >-
The t0 of the last decision's text, relative to the first
decision's t0 (0 when the turn did not reopen).
finalDecideMs:
type: number
minimum: 0
description: >-
The last decision's time, relative to the first decision's
t0.
leadMs:
type: number
maxSilenceTaken:
type: boolean
voiceEndSource:
type: string
enum:
- flux_conf
- flux_same
- fallback
lookupPredicted:
type: string
enum:
- none
- knowledge
- web
- memory
- files
reopens:
type: array
maxItems: 10
items:
type: object
properties:
afterMs:
type: number
minimum: 0
description: >-
The reopen time minus the t0 of the decided text it
reopened.
verdicts:
type: array
maxItems: 40
items:
type: object
properties:
phase:
type: string
enum:
- listen
- drift
- end
- barge
- react
cause:
type: string
enum:
- first
- beat
- resumed
- end
- barge
- react
text:
type: string
maxLength: 2000
description: The text this check judged.
barges:
type: array
maxItems: 10
items:
type: object
properties:
action:
type: string
enum:
- ignore
- cut
- lift
- drop
description: >-
What the predictor did with the onset. `lift` = the
twin went silent before any action (cause
`twin_stopped`); `drop` = a judged turn that ended
empty before any action (cause `empty`).
cause:
type: string
enum:
- noise
- lowconf
- echo
- backchannel
- stop
- jev
- sustained
- jevfail
- jevbusy
- 'off'
- twin_stopped
- empty
description: Why. `jevfail` is a real Jev failure only.
decideMs:
type: integer
minimum: 0
maximum: 60000
description: >-
The onset to the first action (cut or ignore), as
announced; for a `lift`, the onset to the lift.
firstWordMs:
type: integer
minimum: 0
maximum: 60000
description: The onset to the first words.
text:
type: string
maxLength: 2000
description: The interruption's words.
react:
type: object
description: >-
Voice reactions: the onset's emotion check, for an
ignored onset with words. `why` is the first condition
that stopped the reaction; a failed check carries no
`cue` or `p`.
properties:
cue:
type: string
enum:
- happy
- warm
- playful
- curious
- supportive
- concerned
- sad
- surprised
- angry
- distressed
- laughter
- none
p:
type: number
minimum: 0
maximum: 1
sent:
type: boolean
why:
type: string
enum:
- error
- none
- low
- late
- silent
- early
- recent
- same
- shadow
toolsUsed:
type: array
maxItems: 10
items:
type: string
pattern: ^[a-z0-9_]{1,64}$
toolsDropped:
type: number
example:
result: shadow
lane: anam
mode: shadow
turnKey: t_1700000000000_3
heardTimeline:
- atMs: -900
text: can you book
- atMs: -300
text: can you book a room for tomorrow
finalText: can you book a room for tomorrow
lastAssistant: Anything else I can help with?
outcome: hit_end
intervalMs: 1500
decideMs: 140
fluxDecideMs: 620
maxSilenceTaken: false
voiceEndSource: flux_conf
verdicts:
- phase: end
cause: end
atMs: 0
p: 0.92
ok: true
ms: 230
text: can you book a room for tomorrow
barges: []
reopens: []
toolsUsed:
- search_knowledge
toolsDropped: 0
responses:
'204':
description: >-
Accepted (also when prediction is off, for a repeated turnKey, or
over the daily limit).
'400':
description: Invalid record; nothing is kept.
'401':
description: Unauthorized
security:
- apiKeyAuth: []
components:
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: x-access-token
description: JWT token passed in x-access-token header
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.