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));

​
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
);

​
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

SDK Benefits

• Higher-level abstractions
• Type safety and autocomplete
• Built-in error handling
• Automatic retries and caching
• Simplified authentication
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.