> ## 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.
# OpenAI-compatible Chat Completions endpoint (inbound integration)
> OpenAI-compatible streaming chat completions endpoint. Accepts a `messages[]`
array, extracts the last user message as the active turn, replays any prior
user/assistant messages as conversation history (sanitized for Bedrock's
alternating-role requirement), runs the active turn through Praxis's
RAG/tool pipeline, and streams back OpenAI-format SSE chunks.
**Today's primary consumer:** the ElevenLabs Voice Agent in Convo (Direct)
mode — its custom-LLM webhook points at this endpoint.
**OpenAI compatibility surface (what Pria reads vs. ignores):**
Pria accepts the OpenAI shape but only reads `messages[]` and `model`.
`model` is informational — the effective model is determined by the
Praxis cascade (assistant > `chatCompletionModel` > institution
conversationModel). Fields commonly seen on OpenAI clients but
**silently ignored** here: `tools`, `tool_choice`, `temperature`,
`max_tokens`, `stream`, `stream_options`, `top_p`, `n`,
`frequency_penalty`, `presence_penalty`, `response_format`, `seed`,
`logit_bias`, `user`. The response is always SSE (server forces
streaming mode regardless of `stream`). Tool calls are executed
server-side by Pria's tool runtime — they are not surfaced as OpenAI
`tool_calls` deltas; tool acknowledgements appear inline as spoken
phrases in the `content` stream.
**Per-institution gate.** Disabled by default. The administrator must
set `institution.chatCompletionEnabled = true` to allow inbound traffic.
Disabled institutions receive `403 chat_completion_disabled`.
**Override fields** (institution-level, all optional):
- `chatCompletionModel` — overrides the conversation model and provider
routing for inbound requests. Priority: `assistant.conversationModel`
> `chatCompletionModel` > `institution.conversationModel`. Assistant
always wins — the override only applies when no assistant has
overridden the conversation model. Empty/unset = inherit from
existing cascade.
- `chatCompletionMaxCompletionTokens` — overrides `maxCompletionTokens`.
Sentinel: `-1` = inherit, `0` = Auto (catalog cap), `>0` = explicit.
- `chatCompletionReasoningEffort` — overrides `reasoningEffort`. Empty
string = inherit. Common voice-mode value: `'none'`.
Detection of "this is a chat-completion inbound request" is path-based —
any request landing here sets `requestArgs.isChatCompletion = true`,
which the override helpers in `rag.js` and `reasoning_effort_utils.js`
read to apply the cascade above.
## OpenAPI
````yaml /mdx/api-reference/runtime/runtime-api.json post /api/ai/chat/completions
openapi: 3.0.0
info:
title: Pria Runtime API
version: 2.0.1
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.
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/chat/completions:
post:
tags:
- AI
summary: OpenAI-compatible Chat Completions endpoint (inbound integration)
description: >
OpenAI-compatible streaming chat completions endpoint. Accepts a
`messages[]`
array, extracts the last user message as the active turn, replays any
prior
user/assistant messages as conversation history (sanitized for Bedrock's
alternating-role requirement), runs the active turn through Praxis's
RAG/tool pipeline, and streams back OpenAI-format SSE chunks.
**Today's primary consumer:** the ElevenLabs Voice Agent in Convo
(Direct)
mode — its custom-LLM webhook points at this endpoint.
**OpenAI compatibility surface (what Pria reads vs. ignores):**
Pria accepts the OpenAI shape but only reads `messages[]` and `model`.
`model` is informational — the effective model is determined by the
Praxis cascade (assistant > `chatCompletionModel` > institution
conversationModel). Fields commonly seen on OpenAI clients but
**silently ignored** here: `tools`, `tool_choice`, `temperature`,
`max_tokens`, `stream`, `stream_options`, `top_p`, `n`,
`frequency_penalty`, `presence_penalty`, `response_format`, `seed`,
`logit_bias`, `user`. The response is always SSE (server forces
streaming mode regardless of `stream`). Tool calls are executed
server-side by Pria's tool runtime — they are not surfaced as OpenAI
`tool_calls` deltas; tool acknowledgements appear inline as spoken
phrases in the `content` stream.
**Per-institution gate.** Disabled by default. The administrator must
set `institution.chatCompletionEnabled = true` to allow inbound traffic.
Disabled institutions receive `403 chat_completion_disabled`.
**Override fields** (institution-level, all optional):
- `chatCompletionModel` — overrides the conversation model and provider
routing for inbound requests. Priority: `assistant.conversationModel`
> `chatCompletionModel` > `institution.conversationModel`. Assistant
always wins — the override only applies when no assistant has
overridden the conversation model. Empty/unset = inherit from
existing cascade.
- `chatCompletionMaxCompletionTokens` — overrides `maxCompletionTokens`.
Sentinel: `-1` = inherit, `0` = Auto (catalog cap), `>0` = explicit.
- `chatCompletionReasoningEffort` — overrides `reasoningEffort`. Empty
string = inherit. Common voice-mode value: `'none'`.
Detection of "this is a chat-completion inbound request" is path-based —
any request landing here sets `requestArgs.isChatCompletion = true`,
which the override helpers in `rag.js` and `reasoning_effort_utils.js`
read to apply the cascade above.
parameters:
- in: header
name: x-access-token
schema:
type: string
required: true
description: Praxis JWT
- in: header
name: x-praxis-institution-public-id
schema:
type: string
required: false
description: >-
Public ID of the institution context (optional, defaults to user's
primary institution)
- in: header
name: x-praxis-conversation-id
schema:
type: string
required: false
description: Conversation/course ID
- in: header
name: x-praxis-assistant-id
schema:
type: string
required: false
description: Assistant ObjectId (24-char hex)
- in: header
name: x-praxis-timezone
schema:
type: string
required: false
description: >-
IANA timezone string (e.g. "America/New_York") for date-aware
prompts
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- messages
properties:
messages:
type: array
description: |
OpenAI-format messages array. The last `user` message is the
active turn; earlier `user` and `assistant` entries are
replayed as conversation history. `system` and `tool`
messages are accepted in the shape but ignored — Pria
builds its own system prompt from assistant + institution
settings, and tool execution is server-managed.
items:
type: object
required:
- role
properties:
role:
type: string
enum:
- system
- user
- assistant
- tool
content:
description: |
OpenAI content shape. String form is used as-is.
Array form (typed content parts) is normalized so that
`text` and `refusal` parts are joined while
`input_audio`, `image_url`, and `file` parts are
dropped.
oneOf:
- type: string
- type: array
items:
type: object
properties:
type:
type: string
enum:
- text
- image_url
- input_audio
- file
- refusal
text:
type: string
description: Present when the part type is text.
name:
type: string
description: Ignored. Accepted for OpenAI shape compatibility.
tool_call_id:
type: string
description: Ignored. Accepted for OpenAI shape compatibility.
tool_calls:
type: array
description: >-
Ignored. Tool calls are server-managed by Pria's tool
runtime.
items:
type: object
model:
type: string
description: |
Informational only — echoed back in SSE chunks as
`choices[].delta.model`. The actual model dispatched is
determined by the Praxis cascade
(`assistant.conversationModel` >
`institution.chatCompletionModel` >
`institution.conversationModel`).
example: pria
stream:
type: boolean
description: |
Ignored — the endpoint always returns `text/event-stream`.
Accepted for OpenAI shape compatibility.
example: true
responses:
'200':
description: >-
SSE stream of OpenAI-format completion chunks. Terminated with a
final `data: [DONE]` line.
content:
text/event-stream:
schema:
type: string
example: >
data:
{"id":"chatcmpl-1735...","object":"chat.completion.chunk","created":1735000000,"model":"pria","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null,"logprobs":null}]}
data:
{"id":"chatcmpl-1735...","object":"chat.completion.chunk","created":1735000000,"model":"pria","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null,"logprobs":null}]}
data: [DONE]
'400':
description: Empty / malformed request body (e.g. no user message).
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
message:
type: string
type:
type: string
example: invalid_request_error
code:
type: string
example: empty_user_message
'401':
description: Missing or invalid `x-access-token`.
'403':
description: |
Chat Completion endpoint is disabled for this institution. Returned
when `institution.chatCompletionEnabled !== true`. Admin must opt-in
per institution.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
message:
type: string
example: >-
Chat Completion endpoint is not enabled for this
institution.
type:
type: string
example: forbidden
code:
type: string
example: chat_completion_disabled
````