Skip to Content
SessionsOverview

Session Management Overview

The Nexus Platform provides a comprehensive session management API that enables tracking and managing multi-turn conversations with AI experiences. Sessions store conversation history, user context, and metadata across multiple interactions.

What is a Session?

A session represents a continuous conversation between a user and an AI experience. Each session:

  • Has a unique identifier (UUID)
  • Belongs to a specific experience within a workspace
  • Is associated with a user (flexible format: UUID, email, or custom string)
  • Stores conversation turns (query-response pairs)
  • Maintains conversation context and state
  • Can have custom metadata for tracking

Key Features

Multi-turn Conversations

Sessions enable contextual conversations where the AI remembers previous interactions:

  • Each turn stores the user’s query and the AI’s response
  • Conversation state is maintained across multiple turns
  • Full conversation history available for analysis and debugging

Flexible User Identification

Support for multiple userId formats:

  • UUID format: Standard UUID v4 identifiers
  • Email format: User email addresses (case-insensitive)
  • Custom strings: Any string up to 255 characters (e.g., “customer-12345”)

Session States

Three lifecycle states:

  • active: Session is open for new interactions
  • completed: Session explicitly marked as finished
  • expired: Session marked as expired by client application based on business rules

Session Metadata

Client-controlled key-value pairs for tracking and analytics:

  • Flexible JSON object for custom data
  • Shallow merge updates via PATCH endpoint
  • Ideal for source tracking, user info, and business logic

Security & Isolation

  • Workspace isolation: Sessions never cross workspace boundaries
  • Experience isolation: Sessions are scoped to a specific experience
  • Session hijack protection (userId validation on reuse)
  • Bearer token authentication with scope-based authorization

Common Use Cases

Chat Widget Integration

Pre-create sessions before the first query to track widget interactions:

// Create a new session
const response = await fetch("https://nexus-api.uat.knowbl.com/api/v2/sessions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer YOUR_ACCESS_TOKEN",
  },
  body: JSON.stringify({
    experienceId: "your-experience-id",
    userId: "user@example.com",
    metadata: {
      source: "mobile-app",
      version: "2.0.1",
    },
  }),
});

const session = await response.json();
console.log("Session created:", session.id);

Backend API Integration

Retrieve session details with full conversation history:

// Get session details with conversation history
const sessionId = "session-uuid";
const params = new URLSearchParams({
  experienceId: "your-experience-id",
});

const response = await fetch(`https://nexus-api.uat.knowbl.com/api/v2/sessions/${sessionId}?${params}`, {
  headers: {
    Authorization: "Bearer YOUR_ACCESS_TOKEN",
  },
});

const session = await response.json();
console.log(`Session status: ${session.status}`);
console.log(`Turn count: ${session.turns.length}`);

Analytics & Reporting

  • Track conversation length and completion rates
  • Analyze user engagement patterns
  • Monitor session metadata for business insights

Multi-turn Workflows

  • Guide users through multi-step processes
  • Track conversation progress and outcomes across interactions
  • Maintain context for complex queries

API Overview

The session API provides 5 RESTful endpoints under /v2/sessions:

EndpointMethodDescription
/v2/sessionsPOSTCreate a new session
/v2/sessionsGETList session IDs with filtering
/v2/sessions/:sessionIdGETGet session details with history
/v2/sessions/:sessionId/metadataPATCHUpdate session metadata
/v2/sessions/:sessionId/completePOSTMark session as completed/expired

All endpoints require bearer token authentication with appropriate scopes. See the Authentication Guide for details on obtaining access tokens.

Required Scopes:

  • sessions:read - List and retrieve session details
  • sessions:write - Create sessions and update metadata
  • sessions:complete - Mark sessions as completed
  • query:execute - Full session management (includes all above scopes)

Quick Start

1. Create a Session

const response = await fetch("https://nexus-api.uat.knowbl.com/api/v2/sessions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer YOUR_ACCESS_TOKEN",
  },
  body: JSON.stringify({
    experienceId: "your-experience-id",
    userId: "user@example.com",
    metadata: {
      source: "website",
      page: "/support",
    },
  }),
});

const session = await response.json();
// { id: 'session-uuid', status: 'active', ... }

2. Use Session with Query API

const queryResponse = await fetch("https://nexus-api.uat.knowbl.com/api/v2/query", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "How do I reset my password?",
    experienceId: "your-experience-id",
    sessionId: session.id, // Link query to session
  }),
});

For complete query API documentation, see the Query API guide.

3. Complete Session

await fetch(
  `https://nexus-api.uat.knowbl.com/api/v2/sessions/${session.id}/complete?experienceId=your-experience-id`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer YOUR_ACCESS_TOKEN",
    },
    body: JSON.stringify({ status: "completed" }),
  },
);

Next Steps

Query APISession Lifecycle