Sign in

v5

latestOpenAPI 3.1.02026-08-025631,1012.8 MB
Agent Sessions

Create Session

Create a new agent session.

A session represents a stateful conversation with an AI agent that can call tools to search data, filter results, and perform multi-step reasoning.

Args: request: FastAPI request with tenant context payload: Session creation request

Returns: CreateSessionResponse with session metadata

Example: bash curl -X POST http://localhost:8000/v1/agents/sessions \ -H "Authorization: Bearer {api_key}" \ -H "X-Namespace: {namespace_id}" \ -H "Content-Type: application/json" \ -d '{ "agent_config": { "model": "claude-3-5-sonnet-20241022", "temperature": 0.7, "available_tools": ["search_retrievers", "execute_retriever"] }, "quotas": { "max_messages": 100, "max_tokens_total": 100000 } }'

post/v1/agents/sessions

Request body

user_idstring nullable

User identifier (OPTIONAL)

user_memoryobject

Initial user memory/preferences (OPTIONAL)

metadataobject

Session metadata (OPTIONAL)

enable_memoryboolean

Enable semantic memory for conversation context (OPTIONAL, default: True)

Example request

{
  "agent_config": {
    "available_tools": [
      "search_retrievers",
      "execute_retriever",
      "list_collections"
    ],
    "max_tokens": 4096,
    "model": "claude-3-5-sonnet-20241022",
    "system_prompt": "You are a helpful video search assistant.",
    "temperature": 0.7
  },
  "quotas": {
    "max_messages": 100,
    "max_tokens_total": 100000,
    "max_tool_calls": 50
  },
  "user_id": "user_123",
  "user_memory": {
    "preferences": {
      "domain": "tech",
      "language": "en"
    }
  }
}

Response

Successful Response

session_idstring required

Unique session identifier

namespace_idstring required

Namespace identifier

internal_idstring required

Organization internal ID

session_namestring nullable

Auto-generated session name based on first conversation (set after first message)

status'active' | 'idle' | 'archived' | 'terminated' required

Session lifecycle states.

Attributes: ACTIVE: Session is actively processing messages IDLE: Session exists but no recent activity ARCHIVED: Session archived (read-only) TERMINATED: Session permanently closed

created_atstring date-time required

Session creation timestamp

expires_atstring date-time required

Session expiration timestamp