Skip to main content
GET
/
api
/
v1
/
sessions
List Sessions
curl --request GET \
  --url https://api.example.com/api/v1/sessions \
  --header 'X-API-Key: <x-api-key>'
{
  "status": "<string>",
  "result": [
    {
      "session_id": "<string>",
      "uri": "<string>",
      "is_dir": true
    }
  ],
  "time": 123
}
List all conversation sessions associated with the authenticated user.

​
Request

​
Headers

​
X-API-Key
string
required
Your OpenViking API key for authentication

​
Response

​
status
string
Response status (ok or error)
​
result
array
Array of session objects
​
session_id
string
Session identifier
​
uri
string
Full Viking URI for the session
​
is_dir
boolean
Whether this is a directory entry
​
time
number
Request processing time in seconds

​
Examples

curl -X GET http://localhost:1933/api/v1/sessions \
  -H "X-API-Key: your-api-key"

​
Response Example

{
  "status": "ok",
  "result": [
    {
      "session_id": "a1b2c3d4",
      "uri": "viking://session/alice/a1b2c3d4",
      "is_dir": true
    },
    {
      "session_id": "e5f6g7h8",
      "uri": "viking://session/alice/e5f6g7h8",
      "is_dir": true
    }
  ],
  "time": 0.1
}

​
Use Cases

​
List and Resume Sessions

import openviking as ov

client = ov.OpenViking(path="./my_data")
client.initialize()

# List all sessions
sessions = client.list_sessions()

if sessions:
    # Resume the most recent session
    latest_session_id = sessions[0]['session_id']
    session = client.session(session_id=latest_session_id)
    session.load()
    
    print(f"Resumed session with {len(session.messages)} messages")
else:
    # Create new session if none exist
    session = client.session()
    print(f"Created new session: {session.session_id}")

​
Session Management Dashboard

import openviking as ov
from datetime import datetime

client = ov.OpenViking(path="./my_data")
client.initialize()

sessions = client.list_sessions()

print(f"Total sessions: {len(sessions)}\n")

for sess in sessions:
    session_id = sess['session_id']
    details = client.get_session(session_id)
    
    print(f"Session: {session_id}")
    print(f"  Messages: {details['message_count']}")
    print(f"  URI: {sess['uri']}")
    print()