Sessions

Sessions maintain conversational context across multiple messages. Create a session explicitly to control its metadata, or allow Thinklio to create one automatically when you send the first message.

Session Lifecycle

A session is created when a conversation begins and remains active until it expires or is explicitly closed. Active sessions maintain message history and allow the agent to reference earlier context.

Sessions expire after a configurable period of inactivity (default: 24 hours). Expired sessions can be retrieved for history but cannot receive new messages — start a new session instead.

Session Metadata

Sessions accept a metadata object that you can use to attach your own identifiers — a user ID from your system, a support ticket number, or a conversation thread ID. This metadata is returned in session responses and can be used to correlate Thinklio sessions with your own records.

Creating Sessions Explicitly

Creating a session before sending messages lets you configure the session's agent, initial context, and metadata. This is useful when you want to control agent selection or pre-populate context.

Retrieving Sessions

Retrieve a session by ID to get its current state, message count, and metadata. Use the /messages endpoint to retrieve the full message history.

Endpoints

POST/v1/channels/{channel_id}/sessionsBeta

Create a session

Explicitly create a conversation session for a channel. Allows you to configure the agent, initial context, and metadata before sending the first message.

Parameters

Name	Type	In	Required	Description
channel_id	string	path	Yes	The unique identifier of the channel.

Request Body

{
  "agent_id": "string (optional — uses channel default if omitted)",
  "metadata": "object (optional)",
  "initial_context": "string (optional)"
}

Response

{
  "id": "ses_01hxyz",
  "channel_id": "ch_01hxyz",
  "agent_id": "agt_01hxyz",
  "status": "active",
  "message_count": 0,
  "metadata": {},
  "created_at": "2026-03-19T12:00:00Z",
  "expires_at": "2026-03-20T12:00:00Z"
}

GET/v1/sessions/{session_id}Beta

Get a session

Retrieve a session by ID. Returns current state, message count, and metadata.

Parameters

Name	Type	In	Required	Description
session_id	string	path	Yes	The unique identifier of the session.

Response

{
  "id": "ses_01hxyz",
  "channel_id": "ch_01hxyz",
  "agent_id": "agt_01hxyz",
  "status": "active",
  "message_count": 4,
  "metadata": {},
  "created_at": "2026-03-19T12:00:00Z",
  "expires_at": "2026-03-20T12:00:00Z",
  "last_message_at": "2026-03-19T12:10:00Z"
}