Docs

Reference

Release Notes

TypeScript SDK · client.sdk.chat.sessions

Sessions

A session is the central unit of work in the Pdffillr SDK. It holds a persistent context scoped to your API secret, accumulates the full history of an interaction - including attached documents, messages, and all recorded activity - and remains active until you explicitly end it.

client.sdk.chat.sessionscreatelistend

What this page covers

What a session is and how its lifecycle works

Creating sessions with and without a title

Listing all sessions scoped to your API secret

Ending a specific session and what read-only means

1. What is a session?

A session is a conversation context scoped to your API secret. You create one to begin an interaction, list all sessions to see what exists under your key, retrieve the full history of a specific session - including attached documents, chat messages, and other activity - and end a specific session when the interaction is complete. Each session is isolated: its history belongs only to it and is never shared with other sessions.

Three things you can do with sessions

sessions.create()Create a session

Opens a new session scoped to your API secret. Every session starts empty - no messages, no history. You must create a session before you can do anything else.

sessions.list()List all sessions for your API secret

Returns every session created under your API secret, ordered newest first. Only your sessions are returned - other keys and accounts are never visible.

sessions.end(sessionID)End a specific session

Marks the specified session as ended. Only that session is affected. Once ended it becomes read-only - its history is preserved but no new messages can be sent.

All three methods at a glance

session-lifecycle.ts

import 'dotenv/config';
import Pdffillr from '@pdffillr/sdk';

const client = new Pdffillr({
  apiKey: process.env['PDFFILLR_API_KEY'],
});

// 1. create() - open a new session.
const session = await client.sdk.chat.sessions.create({ title: 'Due Diligence Review' });
console.log('Created:', session.session_id);

// 2. list() - see all sessions scoped to this API secret.
const all = await client.sdk.chat.sessions.list();
console.log(`${all.length} sessions under this API secret`);

// 3. end() - end this specific session. Only this session is affected.
await client.sdk.chat.sessions.end(session.session_id);
console.log('Session ended - now read-only.');

Sessions are persistent until ended

A session stays active until you explicitly call sessions.end(sessionID). There is no automatic timeout. Always end sessions you no longer need to free AI pipeline resources.

2. Create a Session

Creates a new session. This is the starting point for every interaction - you must have a session before you can send messages or retrieve its history. No arguments are required; the simplest call is a bare await client.sdk.chat.sessions.create(). Optionally pass a title to give the session a human-readable label you can identify when listing sessions later.

client.sdk.chat.sessions.create(body?, options?)POST /v1/sdk/chat/sessions

ReturnsPromise<Session>

Required argsNone

Body parameters - SessionCreateParams

Parameter	Type	Required	Description
title	string	No	A human-readable label for the session. Visible in sessions.list() output.

Example

sessions-create.ts

import Pdffillr from '@pdffillr/sdk';

const client = new Pdffillr({
  apiKey: process.env['PDFFILLR_API_KEY'],
});

// Create a session with no title (anonymous session).
const session = await client.sdk.chat.sessions.create();
console.log('Session ID:', session.session_id);

// Optionally provide a title to identify the session later.
const named = await client.sdk.chat.sessions.create({
  title: 'Q4 Contract Review',
});
console.log('Named session:', named.session_id, named.title);

Instantiate the client once

Create one Pdffillr instance at application startup and reuse it for every call. Creating a new instance per request is wasteful.

3. List Sessions

Lists all sessions belonging to the API secret used to initialise the client. The response is scoped strictly to your key - you will never see sessions created by other API secrets or accounts. Results are ordered by creation date descending (newest first). Each entry includes the session_id, title, status (active or ended), message count, and timestamps.

client.sdk.chat.sessions.list(options?)GET /v1/sdk/chat/sessions

ReturnsPromise<Session[]>

Required argsNone

Each session object includes

Field	Type	Description
session_id	string	Unique session identifier - pass this to all other session calls.
title	string \| null	The label provided at create time, or null if omitted.
status	"active" \| "ended"	Whether the session can still receive new messages.
message_count	number	Total history entries recorded in this session so far.
created_at	string (ISO 8601)	When the session was opened.

Example

sessions-list.ts

import Pdffillr from '@pdffillr/sdk';

const client = new Pdffillr({
  apiKey: process.env['PDFFILLR_API_KEY'],
});

// Lists all sessions scoped to this API secret - newest first.
const sessions = await client.sdk.chat.sessions.list();

sessions.forEach((s) => {
  console.log(`[${s.status}] ${s.session_id} - ${s.title ?? 'Untitled'}`);
  console.log(`  Messages: ${s.message_count}, Created: ${s.created_at}`);
});

4. End a Session

Ends the specific session identified by sessionID. Only that session is affected - all other sessions under your API secret continue running unchanged. Once ended, the session becomes read-only: its full history - attached documents, messages, and all other activity - remains accessible via getMessages(), but no new messages can be sent to it. Ending a session also releases the AI pipeline resources held by it.

client.sdk.chat.sessions.end(sessionID, options?)POST /v1/sdk/chat/sessions/{sessionId}/end

ReturnsPromise<void>

Required argssessionID: string

What changes after ending a session

Action	Active session	Ended session
Send a message	✓ Allowed	✗ Rejected
Retrieve session history	✓ Allowed	✓ Allowed
Appear in sessions.list()	✓ status: active	✓ status: ended

Example

sessions-end.ts

import Pdffillr from '@pdffillr/sdk';

const client = new Pdffillr({
  apiKey: process.env['PDFFILLR_API_KEY'],
});

// End the specific session - only this session is affected.
await client.sdk.chat.sessions.end('sess_abc123');

// The session is now read-only.
// You can still retrieve its full history via chat.sessions.getMessages() - see the Chat page.

Ending is permanent

There is no way to re-open an ended session. If you need to continue a conversation, create a new session with sessions.create().