Sessions

Update a session

Updates a session (called a "notebook" in the product UI): its name, attached knowledge files, tags, or retrieval settings. Set knowledgeIds and forceKnowledgeRetrieval: true together to enable grounded retrieval for POST /api/chat against this session - retrieval is gated by these session fields, not by the chat request. lakeScope narrows that retrieval to a chosen set of data lakes, and a non-empty list also turns forced retrieval on for a session that has never set it; omit it to leave the current choice unchanged, or send null to clear it so retrieval reaches every lake you can access. includeLibraryFiles sets whether the session grounds on your own library alongside its lakes; false confines it to lake content even when every lake is in scope (files attached to the session still reach the model and its knowledge-base tools), and is set aside (library included) while forceKnowledgeRetrieval is false. Authenticate with an API key (b4m_live_) or a JWT. Warning: adding to knowledgeIds shares those files with every member of every project containing this session by default (see propagateToProjects), and that sharing cannot be undone through the UI.

put/api/sessions/{id}

Request

  • Base URL: https://your-deployment.example.com
  • URL: https://your-deployment.example.com/api/sessions/{id}
  • Auth: one of:
    • HTTP bearer
    • API key in header x-api-key

Path parameters

idstring required

Request body

namestring
knowledgeIdsstring[]
artifactIdsstring[]
lastUsedModelstring nullable

Pin a specific model id, or omit/send null to leave the current pin unchanged. Sending null does NOT clear it.

forceKnowledgeRetrievalboolean
lakeScopestring[] nullable

The data lakes this session searches, as lake tags (the datalake_tag of each lake from GET /api/v1/data-lakes). Send a list to search only those lakes, [] to search no lake at all, or null to clear the choice so retrieval falls back to every lake you can reach. Omit to leave the current choice unchanged. Tags naming a lake you cannot reach are ignored at retrieval time rather than rejected here. A non-empty list also turns forced retrieval on for a session that has never set it, unless forceKnowledgeRetrieval is sent in the same request; a value the session already stores is left as it is. Conversely [] leaves a session with forced retrieval nothing to retrieve from, so its forced retrieval is skipped rather than run against every lake.

includeLibraryFilesboolean

Whether the session grounds on your own library (files you own, or that are shared with you or your groups) alongside its lakes. false confines retrieval to lake content, including when every lake is in scope; the session's attached files still reach the model and stay searchable by its knowledge-base tools. Omit to leave it unchanged; while never set, the library is excluded only when a lake was picked for the session (Data Lakes mode or an explicit lake scope), not when lake tags were derived from an attached file. While forceKnowledgeRetrieval is false the library is included regardless; the stored value applies again once it is turned back on.

propagateToProjectsboolean

Defaults to true when omitted. When knowledgeIds grows, the newly-added file ids are also appended to every project that contains this session, granting every member of that project access to those files. This propagation is append-only and cannot be undone through the UI - pass false if newly-attached files should not be shared with the project.

Example request

{
  "knowledgeIds": [
    "<fabFileId>"
  ],
  "forceKnowledgeRetrieval": true
}

Response

The updated session.

idstring required
_idstring
namestring required
userIdstring required
knowledgeIdsstring[]
artifactIdsstring[]
forceKnowledgeRetrievalboolean
retrievalTagsstring[]
lakeScopeExplicitboolean

True when retrievalTags is a deliberate choice, so an empty list means "no lake" rather than "any".

includeLibraryFilesboolean

Whether the session grounds on your own library alongside its lakes. Absent when never set.

lastUsedModelstring nullable
firstCreatedstring date-time required
lastUpdatedstring date-time required

Changes

No recorded changes to this operation across all 1 revision of this API.