Skip to main content
The Sessions API allows you to create and manage agent sessions. Sessions represent individual conversation instances with agents, providing isolated contexts for interactions.

​
Key Features

  • Session Management: Create sessions from agent configurations or YAML
  • Flexible Creation: Use existing agents or provide inline configurations
  • Session Tracking: Unique session IDs for conversation management
  • Configuration Hashing: Track configuration changes

​
Authentication

All endpoints require authentication using your API key:
  • API Key: x-api-key: <key>

​
Available Endpoints

Create Session

Create a new session with YAML configuration

List Sessions

Retrieve all sessions for your account

Get Session

Retrieve details of a specific session

Create from Agent

Create session from existing agent configuration

​
Session Creation Methods

​
From YAML Configuration

Create sessions by providing a complete agent configuration in YAML or JSON format. This is useful for:
  • Testing new configurations
  • One-off conversations
  • Dynamic agent behavior

​
From Existing Agent

Create sessions from pre-configured agents for:
  • Production deployments
  • Consistent behavior
  • Reusing tested configurations

​
Session Lifecycle

  1. Creation: Session created with agent configuration
  2. Active: Ready to receive and process messages
  3. Runtime: Messages executed through Runtime API
  4. Tracking: Session state maintained throughout conversation
Sessions maintain their configuration throughout their lifecycle. To change agent behavior, create a new session.

​
Common Response Fields

​
session_id
string
Unique session identifier for runtime operations
​
config_hash
string
Hash of the agent configuration used for this session
​
success
boolean
Indicates whether the session was created successfully

​
Next Steps

Once you have a session, use the Runtime API to:
  • Execute messages
  • Retrieve conversation history
  • Monitor session status