List Sessions

Retrieve all sessions for the current user

GET /api/v1/sessions

List Sessions

cURL

curl --request GET \
  --url https://api.example.com/api/v1/sessions \
  --header 'X-API-Key: <x-api-key>'

200

{
  "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

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()

Related Endpoints

• Create Session - Create a new session
• Get Session - Get details for a specific session
• Delete Session - Remove a session