Skip to main content
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 three changes: the base URL, the model ID, 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

Use your Digital Twin’s Public ID as the model parameter — that’s it.

​
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 your instance’s administration panel
  • A valid Praxis JWT token (x-access-token) — obtained when a user authenticates with Praxis
  • The Chat Completions API base URL — provided by your Praxis administrator (e.g. https://your-instance.example.com/api/v1)
The Chat Completions API is a separate middleware service. Ask your administrator for the endpoint URL and confirm it is deployed for your environment.

​
Quick Start

1

Install the OpenAI SDK

pip install openai
2

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://your-instance.example.com/api/v1",
    default_headers={
        "x-access-token": "your-praxis-jwt-token"
    }
)
The api_key field is required by the OpenAI SDK but is not used for authentication. Praxis authenticates via the x-access-token header. If your deployment also uses API keys, pass it as the api_key value instead (see Authentication below).
3

Send a message

Use your Digital Twin Public ID as the model parameter.
response = client.chat.completions.create(
    model="e455529a-4f51-479e-94fc-bbebb41d19a1",  # Digital Twin Public ID
    messages=[
        {"role": "user", "content": "What topics do you cover?"}
    ]
)

print(response.choices[0].message.content)
4

Enable streaming (optional)

Add stream=True for real-time token-by-token responses.
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)

​
Authentication

The API supports two authentication methods that can be used independently or together.

​
Praxis JWT (primary)

Pass the user’s Praxis session token via the x-access-token header. This is the primary authentication method — it identifies the user and authorizes access to their Digital Twins. 
x-access-token: eyJhbGciOiJIUzI1NiIs...
Chat completions always require a valid Praxis JWT in the x-access-token header. An API key alone is not sufficient.

​
API Key (optional)

For server-to-server integrations, your administrator may issue an API key (prefixed sk-). Pass it via the standard Authorization header. When used alongside x-access-token, the API key adds rate limiting and usage tracking. 
Authorization: Bearer sk-your-api-key-here

client = OpenAI(
    api_key="sk-your-api-key-here",
    base_url="https://your-instance.example.com/api/v1",
    default_headers={
        "x-access-token": "your-praxis-jwt-token"
    }
)

​
Context Headers

Optional headers let you pass conversation metadata to the Digital Twin. These enrich the interaction context without affecting authentication.
HeaderTypeDescriptionDefault
x-access-tokenstringRequired. Praxis JWT for user authentication—
x-praxis-conversation-idstringNumeric conversation/course identifier0
x-praxis-conversation-namestringHuman-readable conversation or course name""
x-praxis-assistant-idstringRoutes the request to a specific assistant persona""
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="sk-your-api-key-here",
    base_url="https://your-instance.example.com/api/v1",
    default_headers={
        "x-access-token": "your-praxis-jwt-token",
        "x-praxis-conversation-id": "48201",
        "x-praxis-conversation-name": "Biology 101 - Fall 2026",
        "x-praxis-assistant-id": "assistant-uuid-here",
    }
)

​
Discover Available Models

List all Digital Twins available to the authenticated user. 
models = client.models.list()

for model in models.data:
    print(f"{model.id}  {model.name}")
The model.id returned is the Digital Twin Public ID — use it as the model parameter in chat completions.

​
Message Roles

The API accepts standard OpenAI message roles with the following behavior:
RoleBehavior
userSent to the Digital Twin. Only the last user message is forwarded.
systemIgnored — the Digital Twin manages its own system instructions.
assistantIgnored — Praxis maintains conversation history internally.
toolTreated as user input. If tool_call_id is present, it is prefixed for context.
Since Praxis manages conversation history server-side, you only need to send the current user message. There is no need to maintain a local message array across turns.

​
Response Format

Responses follow the standard OpenAI Chat Completion format: 
{
  "id": "chatcmpl-abc123def456",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "e455529a-4f51-479e-94fc-bbebb41d19a1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "I cover topics in biology, chemistry, and..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 85,
    "total_tokens": 97
  }
}

​
Supported Parameters

ParameterSupportedNotes
modelYesDigital Twin Public ID (required)
messagesYesMessage array (required)
streamYestrue for SSE streaming
response_formatYestext (default), json_object, or json_schema
temperatureAcceptedAccepted for SDK compatibility but not forwarded
max_tokensAcceptedAccepted for SDK compatibility but not forwarded
tools / tool_choiceNot supportedFunction calling is not available
Parameters marked Accepted are validated and will not cause errors, but Praxis manages these settings through the Digital Twin’s configuration.

​
Error Handling

Errors follow the standard OpenAI error format: 
{
  "error": {
    "message": "Description of the error",
    "type": "auth_error",
    "param": null,
    "code": "missing_praxis_token"
  }
}

​
Common Errors

StatusCodeCauseFix
401missing_praxis_tokenNo x-access-token headerAdd the Praxis JWT header
401unauthorizedExpired or invalid JWTRefresh the user’s session token
401invalid_api_keyAPI key inactive or expiredCheck key status with your administrator
404model_not_foundInvalid Digital Twin Public IDVerify the ID via the models endpoint
429rate_limit_exceededToo many requestsReduce request frequency or request a higher limit
504timeoutDigital Twin took too long to respondRetry or enable streaming for long responses

​
V2 Endpoint (HTTP SSE)

An alternative endpoint is available at /v2/chat/completions for environments where WebSocket connections are restricted. It uses direct HTTP Server-Sent Events instead of Socket.IO. 
# Just change the base_url path
client = OpenAI(
    api_key="unused",
    base_url="https://your-instance.example.com/api/v2",
    default_headers={
        "x-access-token": "your-praxis-jwt-token"
    }
)
Both V1 and V2 produce identical OpenAI-compatible responses — choose based on your network requirements.
  • API Reference — Full REST API documentation with streaming details
  • Web SDK — Embed the full Digital Twin UI in your web app
  • MCP Server — Connect Pria to custom LLM workflows
  • JavaScript SDK — Programmatic control of the Pria interface