Skip to main content
This page provides a quick, actionable path to authenticate, call REST endpoints, and capture streaming events from the middleware.

​
API Structure

The Praxis AI API is organized into three functional areas:

Authenticate

Sign in or authenticate to retrieve an access token.

Runtime

Endpoints for selecting a Digital Twin, creating conversations, developing assistants, and dialoguing with AI models.

Administration

Configure Digital Twins, set up permissions and entitlements, audit user history, and monitor activity.

​
Getting Started

1

Obtain an authorization token

All API requests require an authorization token issued after successful authentication. See the Authentication API for how to sign in and use the token in requests.
2

Know your Base URLs

3

Make a test request

Use your token and send a simple JSON request to verify connectivity and headers.
# Replace your_api_access_token and fields as needed
curl https://hiimpria.ai/api/user/refresh/profile \
  -H "x-access-token: your_api_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "welcome-message",
    "tag": "production"
  }'

​
Using the API

The Praxis API follows standard RESTful conventions:
  • JSON for all requests and responses
  • HTTP status codes communicate success/failure
  • Error responses return a consistent JSON shape with details
  • Rate limits protect service stability
If you’re building a browser client, ensure you include the correct auth header on every request. Authorization tokens are only valid for 24 hours.

​
Streaming with Socket.IO

You can connect to Praxis AI middleware to receive streaming events while REST requests are in-flight. The server emits stream chunks to your socket; you must include the current socket ID in Q&A requests to link streams to your session.

​
1 Install the Socket.IO Client

npm i socket.io-client

​
2 Connect and register your user

// socket.ts (client)
import { io } from 'socket.io-client';

const URL = 'https://hiimpria.ai/socket.io'; // Middleware streaming endpoint
localStorage.debug = '*'; // Optional: enable Socket.IO debug logs

// Keep a simple local state holder
const state = {};
state.socket = io(URL, { autoConnect: false });

// Mocked user profile (replace with your authenticated session values)
const user = {
  userId: profile?._id,
  email: profile?.email,
  profileName: `${profile?.fname} ${profile?.lname}`,
  institutionId: profile?.institution?._id,
  institutionName: profile?.institution?.name,
};

// Open the connection and register your user
state.socket.on('connect', () => {
  state.socket.emit('REGISTER', user);
});

// Handle graceful disconnect/unsubscribe
state.socket.on('disconnect', (e) => {
  console.log('SocketContext', 'Disconnect', e);
  state.socket.emit('UNSUBSCRIBE', user);
});

// Optional: initiate connection if autoConnect is false
state.socket.connect();

​
3 Listen for streaming and diagnostic events

// Stream chunks arrive while REST Q&A requests are processed
state.socket.on('RECEIVE_STREAM', (payload) => {
  console.log('SocketContext', 'RECEIVE_STREAM', payload);
});

// Error & connectivity diagnostics
state.socket.on('error', (e) => console.log('SocketContext', 'Error', e));
state.socket.on('connect_success', (e) => console.log('SocketContext', 'Connect Success', e));
state.socket.on('connect_timeout', (e) => console.log('SocketContext', 'Connect Timeout', e));
state.socket.on('connect_error', (e) => console.log('SocketContext', 'Connect Error', e));
These are typical events payload received from the stream 
{
    "prompt": " I'm doing great, thank you for asking! 😊 
    I'm here, energized, and ready to help you with whatever you need today.Since we last spoke just a minute ago when you checked if I was here, I'm curious—what's on your mind? Are you:
    - Looking to learn something new?
    - Working on a project or assignment?
    - Curious about a specific topic?
    - Just wanting to chat?
    
    I'm all ears and ready to assist! What would you like to explore",
    "delta": " What would you like to explore",
    "type": "STREAM"
}
prompt: Contains the full response from the begining ot the interaction. delta Contains only the last text segment reported type: “STREAM” for messages streamed by the LLM
Note that the final response may differ from the prompt returned while streaming.

​
4 Include socketId in your Q&A API requests

The server requires the active Socket.IO session ID to stream chunks to your client. Include socketId in requestArgs. 
// Example: POST Q&A request linking REST call to Socket.IO session
const payload = {
  inputs: [userMessage],
  requestArgs: {
    socketId: state.socket.id, // CRITICAL: links the streaming session
    assistantId: currentAssistantId,
    selectedCourse: {
      course_id: currentCourseId,
      course_name: currentCourseName,
    },
  },
};

const response = await fetch('https://pria.praxislxp.com/api/ai/personal/qanda', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    // If your deployment requires header-based auth for this endpoint, include your token here.
    // 'x-access-token': your_api_access_token
  },
  body: JSON.stringify(payload),
});

if (!response.ok) {
  throw new Error(`HTTP error! status: ${response.status}`);
}

const data = await response.json();
If you wrap Q&A calls, pass socketId from your Socket.IO context into the wrapper and expose a stream callback to consume RECEIVE_STREAM chunks.]
// Example wrapper usage
const { sessionId } = useSocketIO();

await priaApi.qanda(
  {
    inputs: [userMessage],
    requestArgs: {
      socketId: sessionId, // CRITICAL: Link to Socket.IO session
      assistantId: currentAssistantId,
      selectedCourse: {
        course_id: currentCourseId,
        course_name: currentCourseName,
      },
    },
  },
  onStreamCallback // handle incremental chunks
);

​
5 Manage reconnections

When the QANDA request response includes "streamingFailed": true, it indicates that the middleware has lost the backend Socket ID mapping (user email to client socket ID), preventing it from communicating response chunks back to the client. This typically occurs when multiple browser windows or tabs are open for the same user email, causing them to compete for the same backend session and overwriting each other’s socket registrations. To resolve this issue, you can re-establish the socket connection to re-register the most current client handle and restore proper communication between the middleware and the active client session. 
       
if (response?.streamingFailed){
       
  // reconnecting
  if (state.socket.connected){
    await state.socket.disconnect()
  }
  await state.socket.connect()
}

​
6 Abort requests

To abort a request while executing, emit a cancel_request event: 
state.socket.emit('cancel_request', user);
The cancel_request message signals the controller API to interrupt the ongoing communication and attempt a graceful termination of the conversation. While the controller works to terminate resources cleanly, there may be a slight delay before the process completes. You will only be charged for any partial response generated up to the point of cancellation.

​
7 Stop streaming the current request

To stop streaming the current response without aborting the request itself, emit a cancel_streaming event: 
state.socket.emit('cancel_streaming', user);
cancel_streaming applies only to the current response stream and is cleared automatically before the next interaction.

​
API vs SDK

While the API provides direct access to all capabilities, the TypeScript/JavaScript SDK simplifies most tasks.

API Benefits

• Direct access to all Praxis features
• Language-agnostic integration
• Fine-grained request/response control
• Ideal for custom platforms or gateways, mobile applications

SDK Benefits

• Higher-level abstractions
• Seamless SSO authentication • UI Ready to use
• Supports LMS Such as Canvas, Moodle, D2L, LTI
For most use cases, we recommend using our SDKs, while the API remains available for mobile applications, low-level or platform-neutral integrations.

​
Error Handling

The API uses standard HTTP status codes:
  • 2xx: Success
  • 4xx: Client error (invalid request, missing parameters, unauthorized)
  • 5xx: Server error
When an error occurs, the JSON body includes details to help diagnose and resolve issues.

​
Next Steps

Explore endpoint-specific docs:

Authentication

How to authenticate requests and attach tokens.

AI Q&A

Send conversation requests and receive streaming responses.