Delete Session

Permanently delete a session and all its data

DELETE /api/v1/sessions/{session_id}

Delete Session

cURL

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

200

{
  "status": "<string>",
  "result": {
    "session_id": "<string>"
  },
  "time": 123
}

Delete a conversation session and all associated data including messages, archives, and usage records.

This operation is irreversible. All session data including message history and archives will be permanently deleted.

Request

Path Parameters

session_id · string · required

The session ID to delete

Headers

X-API-Key · string · required

Your OpenViking API key for authentication

Response

status · string

Response status (ok or error)

result · object

Deletion result

session_id · string

The deleted session identifier

time · number

Request processing time in seconds

Examples

cURL

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

Response Example

{
  "status": "ok",
  "result": {
    "session_id": "a1b2c3d4"
  },
  "time": 0.3
}

What Gets Deleted

Deleting a session removes:

1. Active messages - Current conversation messages
2. Message archives - All history/archive_N/ directories
3. Tool records - Tool execution data in tools/
4. Session metadata - .abstract.md, .overview.md, .meta.json
5. Relations - Links to contexts and skills used

Deleting a session does NOT delete:

• Extracted memories (stored in user/memories/ and agent/memories/)
• Resources referenced during the session
• Skills used in the session

Use Cases

Clean Up Old Sessions

import openviking as ov
from datetime import datetime, timedelta

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

# List all sessions
sessions = client.list_sessions()

# Delete sessions older than 30 days
for session in sessions:
    session_id = session['session_id']
    
    # Get session details
    sess = client.session(session_id=session_id)
    sess.load()
    
    # Check age
    age = datetime.now() - sess.created_at
    if age > timedelta(days=30):
        print(f"Deleting old session: {session_id}")
        client.delete_session(session_id)

Delete After Commit

If you want to keep only memories and discard conversation history:

session = client.session(session_id="a1b2c3d4")
session.load()

# Commit to extract memories first
result = session.commit()
print(f"Extracted {result['memories_extracted']} memories")

# Now safe to delete the session
client.delete_session(session.session_id)
print("Session deleted, memories preserved")

Batch Delete

import openviking as ov

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

# Delete multiple sessions
session_ids_to_delete = ["abc123", "def456", "ghi789"]

for session_id in session_ids_to_delete:
    try:
        client.delete_session(session_id)
        print(f"Deleted: {session_id}")
    except Exception as e:
        print(f"Failed to delete {session_id}: {e}")

Safe Delete with Confirmation

import openviking as ov

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

session_id = "a1b2c3d4"

# Load session to show details
session = client.session(session_id=session_id)
session.load()

print(f"Session: {session.session_id}")
print(f"Messages: {len(session.messages)}")
print(f"Turns: {session.stats.total_turns}")
print(f"Archives: {session.stats.compression_count}")

# Confirm before deleting
confirm = input("Are you sure you want to delete this session? (yes/no): ")

if confirm.lower() == 'yes':
    client.delete_session(session_id)
    print("Session deleted")
else:
    print("Deletion cancelled")

Error Responses

Session Not Found

{
  "status": "error",
  "error": {
    "code": "NOT_FOUND",
    "message": "Session a1b2c3d4 not found"
  }
}

Insufficient Permissions

{
  "status": "error",
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to delete this session"
  }
}

Best Practices

Always Commit Before Deleting

Extract memories before deletion:

# Good: Commit first to preserve memories
session.commit()
client.delete_session(session_id)

# Avoid: Deleting without committing loses all context
client.delete_session(session_id)

Check Session Content First

# Load session to review content
session = client.session(session_id="a1b2c3d4")
session.load()

if session.stats.memories_extracted == 0:
    print("Warning: No memories extracted yet")
    response = input("Commit before deleting? (yes/no): ")
    if response == 'yes':
        session.commit()

client.delete_session(session.session_id)

Implement Soft Delete

Instead of immediate deletion, mark sessions as deleted:

import openviking as ov
from datetime import datetime

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

# Add deletion marker instead of actual deletion
session_uri = f"viking://session/a1b2c3d4"
meta = {
    "deleted": True,
    "deleted_at": datetime.now().isoformat()
}

client._viking_fs.write_file(
    f"{session_uri}/.deleted.json",
    json.dumps(meta),
    ctx=client.ctx
)

print("Session marked as deleted")

# Later: Permanently delete marked sessions
sessions = client.list_sessions()
for sess in sessions:
    try:
        deleted_marker = client.read(f"{sess['uri']}/.deleted.json")
        if deleted_marker:
            client.delete_session(sess['session_id'])
            print(f"Permanently deleted: {sess['session_id']}")
    except:
        pass  # No deletion marker

Related Endpoints

• Create Session - Create a new session
• List Sessions - List all sessions
• Get Session - Get session details
• Commit Session - Archive and extract memories before deletion