Introduction

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

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

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.

Know your Base URLs

REST API base: https://hiimpria.ai/api
Socket.IO middleware (stream events): https://hiimpria.ai/socket.io
Keep these values in environment variables for dev/prod parity. You may use the domain pria.praxislxp.com as well.

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.

HTTP Streaming with Server-Sent Events (SSE)

As an alternative to Socket.IO, Praxis AI offers a pure HTTP streaming endpoint using Server-Sent Events (SSE). This approach is ideal for:

Server-side applications (Node.js, Python, Go, etc.)
Environments where WebSockets are restricted
Simpler integrations without persistent socket connections
SDK and CLI tool development

The SSE streaming endpoint uses the same JWT authentication as other REST endpoints. No Socket.IO connection is required.

Endpoint

POST /api/ai/personal-stream/qanda-stream

Request Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <jwt_token>` - Your authentication token
`Content-Type`	Yes	`application/json`

Request Body

{
  "inputs": ["Your prompt or question here"],
  "requestArgs": {
    "assistant_id": "optional-assistant-id",
    "selectedCourse": {
      "course_id": "optional-course-id",
      "course_name": "Optional Course Name"
    },
    "ragOnly": false
  }
}

Response Format

The endpoint returns text/event-stream content type with SSE-formatted chunks:

Event Type	Description
`connected`	Initial acknowledgment that stream is established
`stream`	Text chunks as they are generated by the AI
`tool`	Notification when a tool (RAG, web search, etc.) is being invoked
`complete`	Final response with usage statistics
`error`	Error information if something went wrong
`done`	Stream termination signal

Example SSE Response:

data: {"type":"connected","message":"Stream connected"}

data: {"type":"stream","prompt":"Hello! "}

data: {"type":"stream","prompt":"I'm here to help you today."}

data: {"type":"tool","name":"call_rag","status":"calling"}

data: {"type":"stream","prompt":" Based on the documentation..."}

data: {"type":"complete","success":true,"usage":1234,"outputs":["..."]}

data: {"type":"done"}

Node.js Client Example

// sseClient.js - Complete Node.js SSE streaming client
const https = require('https');

/**
 * Stream a chat request using HTTP SSE
 * @param {string} token - JWT authentication token
 * @param {string} prompt - User's question or prompt
 * @param {object} options - Optional configuration (assistantId, courseId, etc.)
 * @returns {Promise<object>} - Final response data
 */
async function streamChat(token, prompt, options = {}) {
  const baseUrl = 'https://hiimpria.ai';
  
  const requestBody = JSON.stringify({
    inputs: [prompt],
    requestArgs: {
      selectedCourse: options.selectedCourse || {},
      ragOnly: options.ragOnly || false,
      ...options.requestArgs
    }
  });

  return new Promise((resolve, reject) => {
    const req = https.request(
      `${baseUrl}/api/ai/personal-stream/qanda-stream`,
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${token}`,
          'Accept': 'text/event-stream'
        }
      },
      (res) => {
        if (res.statusCode !== 200) {
          reject(new Error(`HTTP ${res.statusCode}: ${res.statusMessage}`));
          return;
        }

        let buffer = '';
        let finalResponse = null;

        res.on('data', (chunk) => {
          buffer += chunk.toString();
          
          // Process complete SSE messages
          const lines = buffer.split('\n\n');
          buffer = lines.pop(); // Keep incomplete message in buffer
          
          for (const line of lines) {
            if (line.startsWith('data: ')) {
              try {
                const data = JSON.parse(line.slice(6));
                
                switch (data.type) {
                  case 'connected':
                    console.log('✓ Stream connected');
                    break;
                    
                  case 'stream':
                    // Print streaming text without newline
                    process.stdout.write(data.prompt || data.delta || '');
                    break;
                    
                  case 'tool':
                    console.log(`\n🔧 [Tool: ${data.name}]`);
                    break;
                    
                  case 'complete':
                    console.log(`\n\n✓ Complete - Tokens used: ${data.usage}`);
                    finalResponse = data;
                    break;
                    
                  case 'error':
                    console.error('\n❌ Error:', data.error);
                    reject(new Error(data.error?.message || 'Stream error'));
                    return;
                    
                  case 'done':
                    resolve(finalResponse);
                    return;
                }
              } catch (e) {
                // Skip malformed JSON
              }
            }
          }
        });

        res.on('end', () => {
          resolve(finalResponse);
        });

        res.on('error', reject);
      }
    );

    req.on('error', reject);
    req.write(requestBody);
    req.end();
  });
}

// Example usage
(async () => {
  const token = 'your_jwt_token_here';
  
  try {
    const result = await streamChat(token, 'What is machine learning?', {
      selectedCourse: {
        course_id: 'course-123',
        course_name: 'AI Fundamentals'
      }
    });
    
    console.log('\nFinal result:', result);
  } catch (error) {
    console.error('Error:', error.message);
  }
})();

Using Fetch API (Browser/Node.js 18+)

// Modern fetch-based SSE client
async function streamChatFetch(token, prompt, onChunk) {
  const response = await fetch('https://hiimpria.ai/api/ai/personal-stream/qanda-stream', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({
      inputs: [prompt],
      requestArgs: {}
    })
  });

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

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let buffer = '';

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    buffer += decoder.decode(value, { stream: true });
    const lines = buffer.split('\n\n');
    buffer = lines.pop();

    for (const line of lines) {
      if (line.startsWith('data: ')) {
        const data = JSON.parse(line.slice(6));
        
        // Call the chunk handler
        if (onChunk) onChunk(data);
        
        if (data.type === 'complete') {
          return data; // Return final response
        }
      }
    }
  }
}

// Usage with callback
await streamChatFetch(token, 'Explain quantum computing', (chunk) => {
  if (chunk.type === 'stream') {
    document.getElementById('output').textContent += chunk.prompt;
  }
});

Cancelling an HTTP Stream

To cancel an in-flight HTTP stream request, you can abort the fetch request:

const controller = new AbortController();

// Start the request with abort signal
const response = await fetch('/api/ai/personal-stream/qanda-stream', {
  method: 'POST',
  headers: { ... },
  body: JSON.stringify({ ... }),
  signal: controller.signal  // Pass the abort signal
});

// Later, to cancel:
controller.abort();

The HTTP SSE endpoint is stateless - each request is independent. This makes it ideal for serverless functions, CLI tools, and microservices where maintaining WebSocket connections is impractical.

Comparing Socket.IO vs HTTP SSE

Feature	Socket.IO	HTTP SSE
Connection type	Persistent WebSocket	Per-request HTTP
Setup complexity	Higher (connection management)	Lower (standard HTTP)
Bidirectional	Yes	No (server → client only)
Cancel mid-stream	`cancel_request` event	Abort controller
Best for	Real-time apps, browsers	APIs, CLIs, serverless
Proxy compatibility	May require configuration	Works everywhere

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.

API Documentation

Runtime API

Administrator API

API Structure

Authenticate

Runtime

Administration

Getting Started

Using the API

Streaming with Socket.IO

1 Install the Socket.IO Client

2 Connect and register your user

3 Listen for streaming and diagnostic events

4 Include socketId in your Q&A API requests

5 Manage reconnections

6 Abort requests

7 Stop streaming the current request

HTTP Streaming with Server-Sent Events (SSE)

Endpoint

Request Headers

Request Body

Response Format

Node.js Client Example

Using Fetch API (Browser/Node.js 18+)

Cancelling an HTTP Stream

Comparing Socket.IO vs HTTP SSE

API vs SDK

API Benefits

SDK Benefits

Error Handling

Next Steps

Authentication

AI Q&A

API Documentation

Runtime API

Administrator API

​API Structure

Authenticate

Runtime

Administration

​Getting Started

​Using the API

​Streaming with Socket.IO

​1 Install the Socket.IO Client

​2 Connect and register your user

​3 Listen for streaming and diagnostic events

​4 Include socketId in your Q&A API requests

​5 Manage reconnections

​6 Abort requests

​7 Stop streaming the current request

​HTTP Streaming with Server-Sent Events (SSE)

​Endpoint

​Request Headers

​Request Body

​Response Format

​Node.js Client Example

​Using Fetch API (Browser/Node.js 18+)

​Cancelling an HTTP Stream

​Comparing Socket.IO vs HTTP SSE

​API vs SDK

API Benefits

SDK Benefits

​Error Handling

​Next Steps

Authentication

AI Q&A

API Structure

Getting Started

Using the API

Streaming with Socket.IO

1 Install the Socket.IO Client

2 Connect and register your user

3 Listen for streaming and diagnostic events

4 Include socketId in your Q&A API requests

5 Manage reconnections

6 Abort requests

7 Stop streaming the current request

HTTP Streaming with Server-Sent Events (SSE)

Endpoint

Request Headers

Request Body

Response Format

Node.js Client Example

Using Fetch API (Browser/Node.js 18+)

Cancelling an HTTP Stream

Comparing Socket.IO vs HTTP SSE

API vs SDK

Error Handling

Next Steps