Chat Completions API

Pria exposes an OpenAI-compatible Chat Completions API that lets you interact with any Digital Twin using the standard OpenAI client libraries. If your application already uses the OpenAI SDK, connecting to a Praxis Digital Twin requires just two changes: the base URL and an authentication header.

Estimated setup time: under 5 minutes if you already have a Praxis account and a Digital Twin configured.

How It Works

Point

Set the OpenAI client’s base_url to your Praxis Chat Completions endpoint.

Authenticate

Pass your Praxis JWT via the x-access-token header to identify the user session.

Chat

Send OpenAI-format messages. Pria routes them to your Digital Twin — the one your token belongs to, or the one you name in the x-praxis-institution-public-id header (institution is the API’s word for a Digital Twin).

Prerequisites

Before you begin, make sure you have:

A Praxis AI account with access to at least one Digital Twin
The Digital Twin’s Public ID (a UUID like e455529a-4f51-479e-94fc-bbebb41d19a1) — found in the Digital Twin’s administration panel
A valid Praxis JWT token (x-access-token) — obtained when a user authenticates with Praxis (see Authentication)
Chat Completions enabled on the Digital Twin — this integration is off by default; an administrator must turn it on for the Digital Twin

The Chat Completions endpoint is part of the Pria platform itself — the base URL is your Pria server’s /api/ai path (e.g. https://pria.praxislxp.com/api/ai). It is disabled per Digital Twin by default; if requests return 403 chat_completion_disabled, ask the Digital Twin’s administrator to enable the Chat Completions endpoint in its configuration.

Quick Start

Install the OpenAI SDK

pip install openai

npm install openai

Configure the client

Point the SDK to your Praxis endpoint and pass your authentication token.

from openai import OpenAI

client = OpenAI(
    api_key="unused",  # required by SDK, but not used for auth
    base_url="https://pria.praxislxp.com/api/ai",
    default_headers={
        "x-access-token": "your-praxis-jwt-token"
    }
)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "unused",  // required by SDK, but not used for auth
  baseURL: "https://pria.praxislxp.com/api/ai",
  defaultHeaders: {
    "x-access-token": "your-praxis-jwt-token",
  },
});

The shortest version: put the JWT in api_key and drop the header. The SDK sends api_key as Authorization: Bearer …, which Praxis accepts, so OpenAI(api_key=your_jwt, base_url=…) is enough on its own. The x-access-token header above is shown because it’s the form every other Pria example uses; either works, and you never need both.What you cannot do is pass a personal pria_… API key here — exchange it for a JWT first (see Authentication below).

Send a message (streaming)

Pass your Digital Twin Public ID as the model parameter and set stream=True. The model value does not choose anything — Pria works out which Twin to use from your token (or from the x-praxis-institution-public-id header); the value is only echoed back in the response.

The endpoint always streams — responses are delivered as OpenAI-format SSE chunks regardless of the stream flag, so use your SDK’s streaming mode.

The model value is informational (it is echoed back in the SSE chunks): the request is served by the Digital Twin resolved from your token — the user’s current Digital Twin by default. If your user belongs to several Digital Twins, target one explicitly with the x-praxis-institution-public-id header (see Context Headers).

stream = client.chat.completions.create(
    model="e455529a-4f51-479e-94fc-bbebb41d19a1",
    messages=[
        {"role": "user", "content": "Explain your area of expertise."}
    ],
    stream=True
)

for chunk in stream:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)

const stream = await client.chat.completions.create({
  model: "e455529a-4f51-479e-94fc-bbebb41d19a1",
  messages: [
    { role: "user", content: "Explain your area of expertise." }
  ],
  stream: true,
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content;
  if (content) {
    process.stdout.write(content);
  }
}

curl -X POST https://pria.praxislxp.com/api/ai/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-access-token: your-praxis-jwt-token" \
  -N \
  -d '{
    "model": "e455529a-4f51-479e-94fc-bbebb41d19a1",
    "messages": [
      {"role": "user", "content": "Explain your area of expertise."}
    ],
    "stream": true
  }'

Authentication

Every request carries a Praxis JWT — the token that identifies the user and authorizes access to their Digital Twins. You can present it in either of two ways, whichever your client makes easier:

x-access-token: eyJhbGciOiJIUzI1NiIs...

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

The second is what the OpenAI SDK sends when you set api_key, which is why passing the JWT as the api_key works with no extra configuration.

A raw pria_… API key is not a JWT and is not accepted as one. Exchange it first — see below.

Getting a JWT from a personal API key (server-to-server)

For scripts and server-to-server integrations, exchange a personal API key (prefixed pria_) for a JWT, then pass that JWT in the x-access-token header. The raw pria_… key is not accepted directly — exchange it first:

APIKEY=pria_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
JWT=$(curl -sS -X POST "https://pria.praxislxp.com/api/auth/api-key-signin" \
       -H "x-api-key: $APIKEY" \
       | python -c "import json,sys; print(json.load(sys.stdin)['token'])")

client = OpenAI(
    api_key="unused",
    base_url="https://pria.praxislxp.com/api/ai",
    default_headers={
        "x-access-token": jwt_from_api_key_exchange
    }
)

Context Headers

Optional headers let you pass conversation metadata to the Digital Twin. These enrich the interaction context without affecting authentication.

Header	Type	Description	Default
`x-access-token`	string	Required. Praxis JWT for user authentication	—
`x-praxis-institution-public-id`	string	Public ID of the target Digital Twin (when the user belongs to several)	User’s current Digital Twin
`x-praxis-conversation-id`	string	Numeric conversation/course identifier	`0`
`x-praxis-assistant-id`	string	Routes the request to a specific assistant persona	`""`
`x-praxis-timezone`	string	IANA timezone (e.g. `America/New_York`) for date-aware prompts	Server default

Context headers are useful when your application manages multiple conversations or needs to target a specific assistant within a Digital Twin.

client = OpenAI(
    api_key="unused",
    base_url="https://pria.praxislxp.com/api/ai",
    default_headers={
        "x-access-token": "your-praxis-jwt-token",
        "x-praxis-conversation-id": "48201",
        "x-praxis-assistant-id": "assistant-object-id-here",
    }
)

const client = new OpenAI({
  apiKey: "unused",
  baseURL: "https://pria.praxislxp.com/api/ai",
  defaultHeaders: {
    "x-access-token": "your-praxis-jwt-token",
    "x-praxis-conversation-id": "48201",
    "x-praxis-assistant-id": "assistant-object-id-here",
  },
});

Message Roles

The API accepts standard OpenAI message roles with the following behavior:

Role	Behavior
`user`	The last user message is the active turn sent to the Digital Twin. Earlier `user` messages are replayed as conversation history.
`assistant`	Replayed as conversation history alongside earlier user messages.
`system`	Ignored — the Digital Twin builds its own system instructions from its assistant and twin settings.
`tool`	Accepted in the shape but ignored — tool execution is managed server-side by Pria.

Send the turns in order, alternating. Pria tidies up what you send — consecutive messages from the same speaker are joined, and the history is trimmed so it reads as a proper back-and-forth ending on the user — because some providers reject anything else. You’ll get a sensible answer either way, but a clean alternating array is what you’ll see reflected back.

You can send only the current user message (Pria tracks the conversation via x-praxis-conversation-id), or pass your own running message array — prior user/assistant turns you include are replayed as history for the active turn.

Response Format

The endpoint always streams. Responses arrive as standard OpenAI SSE chunks:

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1700000000,"model":"e455529a-...","choices":[{"index":0,"delta":{"content":"I cover topics in"},"finish_reason":null}]}

data: [DONE]

Read them exactly as you would an OpenAI streaming response — iterate the stream and concatenate choices[0].delta.content.

Supported Parameters

Parameter	Supported	Notes
`model`	Yes	Informational — the effective model follows the Digital Twin’s configuration cascade (assistant override → the twin’s Chat Completions model override → the twin’s conversation model)
`messages`	Yes	Message array (required)
`stream`	Accepted	The response is always SSE — streaming is forced regardless of this flag
`temperature` / `max_tokens` / `top_p` / `response_format` and other tuning fields	Accepted	Accepted for SDK compatibility but not forwarded — these settings are managed by the Digital Twin’s configuration
`tools` / `tool_choice`	Not supported	The Twin’s own server-side tools run automatically; client-supplied function calling is not available

The Digital Twin’s administrator controls this endpoint, under Chat Completion in the twin’s settings. Turning on Enable Chat Completion endpoint reveals three overrides that apply to inbound requests only, leaving the twin’s in-app behaviour untouched:

Chat Completion Model — a different model for API traffic
Chat Completion Max Output Tokens — a ceiling on the length of each answer
Chat Completion Reasoning Effort — leave on Inherit, or pick a level; None is the usual choice for voice agents, where thinking time is silence

Leave an override unset and it follows the twin’s main conversation setting.

This same switch carries spoken conversation. Every ElevenLabs voice connection routes its turns through this endpoint, so turning it off to close the API also silences voice on that Digital Twin.

Error Handling

Two shapes, depending on how far the request got. Errors raised by the endpoint itself use the OpenAI envelope your SDK already understands:

{
  "error": {
    "message": "No user message found in messages array",
    "type": "invalid_request_error",
    "code": "empty_user_message"
  }
}

Errors raised before the request reaches the endpoint — sign-in, membership, credits — are answered in Pria’s own format instead, because they are the same checks that guard every other Pria API:

{ "success": false, "message": "Authentication Required" }

Don’t rely on your SDK to raise a tidy error. An OpenAI client parsing error.message will find nothing in a Pria-shaped body and may report an unhelpful message instead of the real reason. Read the status code first, and fall back to message or error on the body when error.message is absent.

Common Errors

Status	Code	Cause	Fix
400	`empty_user_message`	No `user` message found in the `messages` array	Include at least one message with `role: "user"`
400	— (`Institution not found…`)	The `x-praxis-institution-public-id` header names an unknown Twin, or your user is not a member of it	Verify the Public ID in the Digital Twin’s administration panel and your user’s membership
401	—	The JWT is expired or invalid	Obtain a fresh one (exchange your `pria_…` key again)
403	— (`Authentication Required`)	No token was sent at all	Add the JWT — as `x-access-token`, `Authorization: Bearer`, or the SDK’s `api_key`
403	`chat_completion_disabled`	The Chat Completions endpoint is not enabled for the Digital Twin	Ask the Digital Twin’s administrator to enable it in its configuration
403	—	Out of credits, over a credit cap, or an inactive membership / Digital Twin	Top up credits, or contact the Digital Twin’s administrator

A missing token is 403, not 401. It’s an easy one to trip over when your retry logic keys on 401 — a client that only refreshes on 401 will loop on 403 forever without ever sending a token.

Multi-Provider Routing

The Chat Completions API is a front door to the Pria platform, not a thin proxy to a single model provider. Behind the URL, Pria selects the underlying provider and model based on the Digital Twin’s configuration. As of today, Pria can route to:

Provider	Model families
OpenAI	GPT‑6.x, GPT‑5.x, GPT‑4.1, o‑series reasoning, GPT Image, GPT‑Realtime
Anthropic	Claude — Fable, Opus, Sonnet, Haiku
Amazon Bedrock	Claude, Llama, Mistral, DeepSeek, Amazon Nova and Titan, Stability AI images
Google	Gemini — Pro, Flash, Live (Convo Mode); through the Gemini API or Google AI Platform
Mistral	Mistral Large, Medium, Small, Voxtral (TTS / STT), Codestral
xAI	Grok 4.x (reasoning and non‑reasoning variants), Grok image models
OpenRouter	Claude, Gemini and Grok models, plus open models such as Gemma, DeepSeek and Kimi

The model parameter you pass in the request is not a provider model ID — it does not select the model at all. The effective model follows the Digital Twin’s configuration cascade (assistant override → the twin’s Chat Completions model override → the twin’s conversation model). If the Twin’s admin changes the underlying model from Claude to GPT‑5, your code does not change. When the twin has a Fallback conversation model and its model fails before it has written anything, the fallback answers instead of an error.

Per‑Provider Behavioural Differences

Because Pria forwards to many providers, some advanced behaviours are provider‑dependent and respect the Twin’s configuration rather than the request payload:

Reasoning effort — honored by reasoning‑capable models (OpenAI GPT‑5 family and o‑series, xAI reasoning variants); models that always reason ignore the setting. Configured per Twin, with a Chat‑Completions‑specific override available.
Thinking tokens — Anthropic Claude and Google Gemini thinking models support extended thinking budgets, configured per Twin.
Image generation — supported through OpenAI (GPT Image 2.5), Google (Gemini image models), xAI (Grok Imagine), and Stability AI (Stable Image).
Prompt caching — applied automatically where the underlying provider supports it; cached reads are billed at a discount.
Tool calls — the Digital Twin’s server‑side tools (RAG, web search, charts, connectors, MCP) run automatically. Client‑supplied tools / tool_choice are not forwarded (see Supported Parameters).

For the full behaviour matrix, see AI Models.

Provider Authentication Errors

When the Twin is configured to use a provider that requires its own credentials (BYOT — Bring Your Own Tokens), errors from the underlying provider are surfaced back to you as standard OpenAI‑style errors:

Status	Likely cause
401 from chat completions	Your Praxis JWT has expired (a missing one is 403)
401 with provider name in message	The Twin’s underlying provider key (OpenAI, Anthropic, etc.) is missing or invalid — contact the Twin’s admin
429	Rate limited at the provider level — back off and retry

A failure after the first byte arrives inside the stream, not as an HTTP status. Once the response has started, Pria can no longer change the status code, so a provider outage mid-answer is delivered as an error chunk followed by [DONE]:

data: {"error":{"message":"…","type":"api_error","code":"streaming_error"}}

data: [DONE]

A client that checks only the HTTP status sees 200 and a short answer. Watch for an error key on each chunk and treat a turn that carried one as failed — that’s the difference between retrying and silently showing the user half a sentence.

See BYOT (Bring Your Own Tokens) for how Twin admins configure provider keys.

Cost & Credits

Chat completions consume Pria credits, billed by token usage and the underlying provider’s price tier. Usage is metered server-side per turn — the SSE stream does not include an OpenAI-style usage block, so review consumption in Pria’s credit history rather than in the response payload.

Cached prompt tokens (when the provider supports caching) are billed at a discounted rate.
Streaming is the only mode, and it is billed like any conversation turn.
Embedded RAG retrieval runs as part of the Digital Twin’s response and is included in the credit cost — you do not pay separately for vector search.

For your account’s plan and credit balance, see Plans & Credits and Credit Management.

Chat Completions vs. the Pria Runtime API

Pria exposes two complementary APIs. They look similar but behave very differently — choose based on whether you want stateless OpenAI‑style requests or full Pria session semantics.

	Chat Completions API	Runtime API
Shape	OpenAI‑compatible	Pria‑native REST + WebSocket
State	Stateless — each call is independent	Stateful — Pria tracks the user’s conversation thread
History	Last user message is the active turn; earlier messages you include are replayed as history	Pria stores the full thread server‑side
RAG / KAG retrieval	Runs automatically as part of the response	Runs automatically as part of the response
Tool calls	The Twin’s tools run server‑side; not exposed to the caller	The Twin’s tools run server‑side; tool events streamed to the caller
Conversation continuity	Use `x-praxis-conversation-id` to group calls into a thread	Native; each call references a `historyId`
Streaming	OpenAI SSE format	Pria event stream (richer event types)
Best for	Drop‑in replacement for OpenAI in existing code	Building a full Pria‑powered chat experience from scratch

Rule of thumb: if your code already uses the OpenAI SDK and you want to point it at Pria with minimal changes, use the Chat Completions API. If you’re building a new client from scratch and want access to every Pria capability (per‑message tool events, citations, KAG augmentations, structured memory updates), use the Runtime API. See the API Reference for both.

API Reference — Full REST API documentation with streaming details
AI Models — Provider catalog, reasoning effort, thinking, and image generation behaviour per provider
API Keys — Issue and rotate the API keys used to obtain Praxis JWTs
BYOT (Bring Your Own Tokens) — How Twin admins configure per‑provider credentials
Plans & Credits — How token usage maps to credits
MCP Server — Connect Pria to custom LLM workflows
Web SDK — Embed the full Digital Twin UI in your web app
JavaScript SDK — Programmatic control of the Pria interface

Overview

Getting Started

Authentication

REST API

Runtime API

Administrator API

JavaScript SDK

Web & Chat Integrations

LMS Integrations

Voice & Avatars

MCP Server

Other Services

Chat Completions API

How It Works

Point

Authenticate

Chat

Prerequisites

Quick Start

Authentication

Getting a JWT from a personal API key (server-to-server)

Context Headers

Message Roles

Response Format

Supported Parameters

Error Handling

Common Errors

Multi-Provider Routing

Per‑Provider Behavioural Differences

Provider Authentication Errors

Cost & Credits

Chat Completions vs. the Pria Runtime API

​How It Works

Point

Authenticate

Chat

​Prerequisites

​Quick Start

​Authentication

​Getting a JWT from a personal API key (server-to-server)

​Context Headers

​Message Roles

​Response Format

​Supported Parameters

​Error Handling

​Common Errors

​Multi-Provider Routing

​Per‑Provider Behavioural Differences

​Provider Authentication Errors

​Cost & Credits

​Chat Completions vs. the Pria Runtime API

​Related

How It Works

Prerequisites

Quick Start

Authentication

Getting a JWT from a personal API key (server-to-server)

Context Headers

Message Roles

Response Format

Supported Parameters

Error Handling

Common Errors

Multi-Provider Routing

Per‑Provider Behavioural Differences

Provider Authentication Errors

Cost & Credits

Chat Completions vs. the Pria Runtime API

Related