Sessions API

Manage conversation history with session listing and loading.

The Sessions API provides endpoints for managing conversation history, allowing users to view and load past conversations.

Overview

The Sessions API provides two main endpoints:

GET /sessions - List all user conversations
GET /sessions/[id] - Get messages from a specific conversation

List Sessions

src/app/api/lens/agent/sessions/route.ts

import { NextResponse } from "next/server";
import { auth } from "@/auth";
import { LensClient } from "@lens-os/sdk";

const client = new LensClient({ apiKey: process.env.LENS_OS_API_KEY! });

export async function GET() {
  const session = await auth();
  if (!session?.user) {
    return NextResponse.json(
      { success: false, error: "Unauthorized" },
      { status: 401 }
    );
  }

  const userId = session.user.id || "default-user";

  try {
    const sessions = await client.listSessions(userId);

    // Add title for each session (first user message)
    const enriched = await Promise.all(
      sessions.map(async (s) => {
        try {
          const messages = await client.getMessages(s.id);
          const firstUserMsg = messages.find((m) => m.role === "user");
          const title = typeof firstUserMsg?.content === "string"
            ? firstUserMsg.content.slice(0, 60)
            : "New Conversation";

          return {
            ...s,
            title,
            messageCount: messages.length,
          };
        } catch {
          return { ...s, title: "New Conversation", messageCount: 0 };
        }
      })
    );

    return NextResponse.json({ success: true, sessions: enriched });
  } catch (err) {
    console.error("[Sessions API] Error:", err);
    return NextResponse.json(
      { success: false, error: "Failed to list sessions" },
      { status: 500 }
    );
  }
}

Get Session Messages

src/app/api/lens/agent/sessions/[id]/route.ts

import { NextRequest, NextResponse } from "next/server";
import { auth } from "@/auth";
import { LensClient } from "@lens-os/sdk";

const client = new LensClient({ apiKey: process.env.LENS_OS_API_KEY! });

export async function GET(
  _request: NextRequest,
  { params }: { params: Promise<{ id: string }> }
) {
  const session = await auth();
  if (!session?.user) {
    return NextResponse.json(
      { success: false, error: "Unauthorized" },
      { status: 401 }
    );
  }

  const { id: sessionId } = await params;

  try {
    const messages = await client.getMessages(sessionId);
    return NextResponse.json({ success: true, messages });
  } catch (err) {
    console.error("[Sessions API] Error:", err);
    return NextResponse.json(
      { success: false, error: "Failed to load messages" },
      { status: 500 }
    );
  }
}

Response Format

List Sessions

Response

{
  success: true,
  sessions: [
    {
      id: "session-123",
      created_at: "2024-01-15T10:30:00Z",
      title: "Help me find TypeScript books",
      messageCount: 8
    },
    // ...
  ]
}

Get Messages

Response

{
  success: true,
  messages: [
    { role: "user", content: "Help me find TypeScript books" },
    { role: "assistant", content: "Let me search for you..." },
    // ...
  ]
}

Tip

Sessions are automatically created and saved by the SDK. You don't need to manually manage session creation or storage.