Sessions

Create a session

Creates a session (called a "notebook" in the product UI). Pass the returned id as sessionId to POST /api/chat, then poll GET /api/v1/quests/{id} for the reply. An API key needs notebooks:write for this call, so a chat round trip needs that scope as well as ai:chat. A key holding ai:generate without notebooks:write may create a bare session only (name, lastUsedModel, temperature, autoNamePlaceholder); any other field is a 403. Unknown body fields are ignored. Naming a data lake with dataLakeId (ids come from GET /api/v1/data-lakes) seeds the session with that lake's retrieval defaults and turns on forced retrieval.

post/api/v1/sessions

Request

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

Request body

namestring required
projectIdstring

Adds the new session to this project.

dataLakeIdstring nullable

Seeds retrieval defaults from this data lake and turns on forced retrieval. Get ids from GET /api/v1/data-lakes.

preauthorizedLakeIdsunknown
knowledgeIdsstring[]
artifactIdsstring[]
agentIdsstring[]
systemPromptTextstring

Write-only: never returned in a session response.

systemPromptIdstring
surfacestring
enabledToolsstring[]
disabledToolsstring[]
disableUserIntegrationsboolean
forceKnowledgeRetrievalboolean
retrievalTagsstring[]
lakeScopeExplicitboolean
includeLibraryFilesboolean
corpusGroundingMode'inline' | 'retrieve' | 'auto-by-size'

Honored only when a lake is named by retrievalTags without dataLakeId.

retrievalExcludeFilenameMarkersstring[]
retrievalVectorizedOnlyboolean
citationStyle'named' | 'indexed'
temperaturenumber
maxToolCallsinteger
autoNamePlaceholderstring
lastUsedModelstring nullable

Example request

{
  "name": "Quarterly analysis"
}

Response

The created 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.