Sessions

Endpoints for managing the lifecycle of a conversation. All three require authentication — see Authentication.

List sessions

Returns every session the authenticated user has created, newest first.

GET/v1/sessions

Response

sessionsSession[]

Array of sessions owned by the caller.

sessions[].sessionIdstring

The session identifier.

sessions[].createdAtnumber

Unix timestamp (ms) of when the session was created.

Example

curl "$BASE_URL/v1/sessions" \
  -H "Authorization: Bearer $TOKEN"

Create a session

Creates a new conversation session for the authenticated user. The recommended shape is to send a customizations body picking an agent and (optionally) its extensions. If you send no body, the backend falls back to the default agent at message time — see Concepts: Sessions — Default agent.

POST/v1/sessions

Request body

All configuration lives under a top-level customizations field. It accepts one of three variants:

Simple — pick a registered agent bundle by agentId and optionally attach extensions. This is the most common shape.
Full — bypass the bundle and specify a model directly along with extensions (advanced; lets you compose system prompts and tools manually).
Minimal — no agentId, just extensions and/or sessionData; the session resolves to the default agent at message time.

customizationsobject

Configures the session. All fields below live under this key.

customizations.productstring

Identifies which product is consuming the session. Used for prompt resolution, quota tracking, and analytics. Examples: "warehouse-agent", "smart-help".

customizations.agentIdstring

Which model bundle to use for this session. Determines the system prompt, tool providers, and inference parameters. See Models for available bundles. Required for the Simple variant.

customizations.modelstring

Foundation-model identifier for the Full variant. Mutually exclusive with agentId.

customizations.extensionsobject

Optional per-session capabilities. All fields below are optional.

customizations.extensions.toolsRecord<string, ToolDefinition>

Client-supplied tool definitions, keyed by tool name. Each tool has a name, description, requestArgs (JSON Schema for input), and responseShape (JSON Schema for output). See Tool Definitions.

customizations.extensions.ragobject

Retrieval-augmented generation configuration. When set, the model can query document indexes as part of its response.

customizations.extensions.rag.indexesstring[]

Which vector indexes to search. Example: ["platform-docs"].

customizations.extensions.rag.prefetchEnabledboolean

Whether to prefetch documents on session start.

customizations.extensions.rag.maxResultsnumber

Maximum number of documents to retrieve per query.

customizations.extensions.rag.tagFilterobject

Filter documents by metadata tags. Has include and exclude fields, each mapping tag names to arrays of accepted values.

customizations.extensions.mcpProvidersstring[]

List of MCP provider names to enable for this session. The platform will load tool definitions from these providers via its MCP gateway. Today the only registered provider is "netsuite".

Response

sessionIdstring

The new session's identifier. Save it — you'll need it for every subsequent message and tool call.

Examples

Simple (recommended starting point) — pick an agent:

curl -X POST "$BASE_URL/v1/sessions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customizations": {
      "agentId": "RfsAgent",
      "extensions": {}
    }
  }'

With extensions — tools, RAG, and MCP providers:

curl -X POST "$BASE_URL/v1/sessions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customizations": {
      "product": "warehouse-agent",
      "agentId": "RfsAgent",
      "extensions": {
        "tools": {
          "getLocations": {
            "name": "getLocations",
            "description": "Retrieves warehouse locations",
            "requestArgs": {
              "properties": {
                "includeInactive": { "type": "boolean" }
              }
            },
            "responseShape": {
              "properties": {
                "locations": { "type": "array" }
              }
            }
          }
        },
        "rag": {
          "indexes": ["platform-docs"],
          "maxResults": 10,
          "tagFilter": {
            "include": { "productCode": ["ns"] }
          }
        },
        "mcpProviders": ["netsuite"]
      }
    }
  }'

Delete a session

Hard-deletes a session and cascades to its messages and tool calls. There is no recovery.

DELETE/v1/sessions/:sessionId

Path parameters

sessionIdstringrequired

The session to delete. Must belong to the authenticated user.

Response

204 No Content on success. 404 if the session doesn't exist or is owned by another user.

Warning

Deletion is not reversible. If you need an audit trail, export messages first via GET /v1/messages/:sessionId.

Example

curl -X DELETE "$BASE_URL/v1/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $TOKEN"

Edit this page on GitHub

PreviousModels NextMessages