Upsert a session

Idempotently opens a session under a caller-provided id: creates it if new, or returns the existing session unchanged. Sessions track interaction context across multiple MCP tool calls within a single agent run.

New ids are limited to [A-Za-z0-9][A-Za-z0-9.~:-]{0,127}, but you can keep referring to previous ids as they were defined.

Deprecated: a session no longer needs opening. Its first write — appending messages, a tool call's session_id, or POST …/ingestions/sessions — creates it.

Usage

import { ContextEngineClient } from "@clinia/context-engine-js";

// Initialize the client
const client = new ContextEngineClient({
  baseUrl: process.env.CLINIA_WORKSPACE,
  auth: {
    clientId: process.env.CLINIA_CLIENT_ID,
    clientSecret: process.env.CLINIA_CLIENT_SECRET,
  },
});

// Call the API
const { data, error } = await client.sessions.upsertSession("<patient-id>", "<session-id>");

// Print the response
console.log(data ?? error);

The environment variables are set in Install and authenticate, for JavaScript or Python.

API reference

PUT /v1/patients/{patientId}/sessions/{sessionId} documents the parameters, the request body and the responses.