Saving Snapshots

Overview

Save snapshots when deleting sessions to preserve browser state, authentication, and data for future use.

Snapshot Modes

Choose the right snapshot mode for your use case:

Memory

Fastest restoration
⚡ Quick to restore
⚠️ May be less reliable
💡 Good for temporary state

Filesystem

Most reliable
✅ Preserves all browser data
🔐 Best for authentication
💡 Recommended for production

None

No snapshot
🗑️ State is lost
💡 Default behavior

Save a Snapshot

Save a snapshot when deleting a session using the save_snapshot_mode parameter:

JavaScript
Python
HTTPie

// Save a memory snapshot (fast, less reliable)
await fetch(`https://api.agi.tech/v1/sessions/${sessionId}?save_snapshot_mode=memory`, {
  method: 'DELETE',
  headers: { 'Authorization': `Bearer ${apiKey}` }
});

// Save a filesystem snapshot (recommended for authentication)
await fetch(`https://api.agi.tech/v1/sessions/${sessionId}?save_snapshot_mode=filesystem`, {
  method: 'DELETE',
  headers: { 'Authorization': `Bearer ${apiKey}` }
});

// Delete without saving snapshot
await fetch(`https://api.agi.tech/v1/sessions/${sessionId}?save_snapshot_mode=none`, {
  method: 'DELETE',
  headers: { 'Authorization': `Bearer ${apiKey}` }
});

# Save a memory snapshot (fast, less reliable)
requests.delete(
    f"https://api.agi.tech/v1/sessions/{session_id}",
    headers={"Authorization": f"Bearer {api_key}"},
    params={"save_snapshot_mode": "memory"}
)

# Save a filesystem snapshot (recommended for authentication)
requests.delete(
    f"https://api.agi.tech/v1/sessions/{session_id}",
    headers={"Authorization": f"Bearer {api_key}"},
    params={"save_snapshot_mode": "filesystem"}
)

# Delete without saving snapshot
requests.delete(
    f"https://api.agi.tech/v1/sessions/{session_id}",
    headers={"Authorization": f"Bearer {api_key}"},
    params={"save_snapshot_mode": "none"}
)

# Save a memory snapshot
http DELETE "https://api.agi.tech/v1/sessions/$SESSION_ID?save_snapshot_mode=memory" \
  Authorization:"Bearer $AGI_API_KEY"

# Save a filesystem snapshot (recommended)
http DELETE "https://api.agi.tech/v1/sessions/$SESSION_ID?save_snapshot_mode=filesystem" \
  Authorization:"Bearer $AGI_API_KEY"

# Delete without saving snapshot
http DELETE "https://api.agi.tech/v1/sessions/$SESSION_ID?save_snapshot_mode=none" \
  Authorization:"Bearer $AGI_API_KEY"

Use filesystem mode for authentication-critical applications. It preserves all browser data including cookies, localStorage, and sessionStorage.

Set as Default Environment

Save a snapshot and set it as the default environment in one step:

JavaScript
Python
HTTPie

// Save snapshot and set as default
await fetch(`https://api.agi.tech/v1/sessions/${sessionId}?save_snapshot_mode=filesystem&save_as_default=true`, {
  method: 'DELETE',
  headers: { 'Authorization': `Bearer ${apiKey}` }
});

# Save snapshot and set as default
requests.delete(
    f"https://api.agi.tech/v1/sessions/{session_id}",
    headers={"Authorization": f"Bearer {api_key}"},
    params={
        "save_snapshot_mode": "filesystem",
        "save_as_default": "true"
    }
)

# Save snapshot and set as default
http DELETE "https://api.agi.tech/v1/sessions/$SESSION_ID?save_snapshot_mode=filesystem&save_as_default=true" \
  Authorization:"Bearer $AGI_API_KEY"

When save_as_default=true:

✅ The snapshot is saved to the environment associated with the session
✅ The environment is set as the user’s default environment
✅ Future session creations can automatically restore from this snapshot

Default Environments

How Default Environments Work

A default environment is an environment snapshot that is automatically restored when creating new sessions. The system uses the following precedence order:

restore_from_session_id - Explicitly restore from a specific session ID (highest priority)
restore_default_environment_from_user_id - Restore from user’s default environment (lower priority)
Fresh session - No restoration (default)

Setting a Default Environment

Set a default environment by saving a snapshot during session deletion:

JavaScript
Python
HTTPie

await fetch(`https://api.agi.tech/v1/sessions/${sessionId}?save_snapshot_mode=filesystem&save_as_default=true`, {
  method: 'DELETE',
  headers: { 'Authorization': `Bearer ${apiKey}` }
});

requests.delete(
    f"https://api.agi.tech/v1/sessions/{session_id}",
    headers={"Authorization": f"Bearer {api_key}"},
    params={
        "save_snapshot_mode": "filesystem",
        "save_as_default": "true"
    }
)

http DELETE "https://api.agi.tech/v1/sessions/$SESSION_ID?save_snapshot_mode=filesystem&save_as_default=true" \
  Authorization:"Bearer $AGI_API_KEY"

This saves the snapshot and sets it as the user’s default environment. Future session creations can then automatically restore from this snapshot using restore_default_environment_from_user_id.

Best Practices

Use Filesystem Mode

Always use filesystem mode for authentication-critical applications

Save After Login

Save snapshots immediately after successful authentication

Set as Default

Use save_as_default=true for automatic restoration

Update Regularly

Refresh snapshots before authentication tokens expire

Complete Example

Save a snapshot after logging in:

JavaScript
Python
HTTPie

// Step 1: Create a session
const sessionResponse = await fetch('https://api.agi.tech/v1/sessions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ agent_name: 'agi-0' })
});
const { session_id } = await sessionResponse.json();

// Step 2: Use the session (login, navigate, etc.)
// ... perform actions that establish authentication ...

// Step 3: Save snapshot and set as default
await fetch(`https://api.agi.tech/v1/sessions/${session_id}?save_snapshot_mode=filesystem&save_as_default=true`, {
  method: 'DELETE',
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});

import requests

# Step 1: Create a session
session_response = requests.post(
    "https://api.agi.tech/v1/sessions",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={"agent_name": "agi-0"}
)
session_id = session_response.json()["session_id"]

# Step 2: Use the session (login, navigate, etc.)
# ... perform actions that establish authentication ...

# Step 3: Save snapshot and set as default
requests.delete(
    f"https://api.agi.tech/v1/sessions/{session_id}",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={
        "save_snapshot_mode": "filesystem",
        "save_as_default": "true"
    }
)

# Step 1: Create a session
SESSION_ID=$(http POST https://api.agi.tech/v1/sessions \
  Authorization:"Bearer $API_KEY" \
  agent_name=agi-0 | jq -r '.session_id')

# Step 2: Use the session (login, navigate, etc.)
# ... perform actions that establish authentication ...

# Step 3: Save snapshot and set as default
http DELETE "https://api.agi.tech/v1/sessions/$SESSION_ID?save_snapshot_mode=filesystem&save_as_default=true" \
  Authorization:"Bearer $API_KEY"

Session Snapshots Overview

Back to overview

Restoring Snapshots

Learn how to restore from snapshots

Authentication Management

Preserve authentication state

API Reference

Delete Session endpoint

Getting Started

Use Cases

Best Practices

Advanced

Troubleshooting

Overview

Snapshot Modes

Memory

Filesystem

None

Save a Snapshot

Set as Default Environment

Default Environments

How Default Environments Work

Setting a Default Environment

Best Practices

Use Filesystem Mode

Save After Login

Set as Default

Update Regularly

Complete Example

Session Snapshots Overview

Restoring Snapshots

Authentication Management

API Reference

Getting Started

Use Cases

Best Practices

Advanced

Troubleshooting

​Overview

​Snapshot Modes

Memory

Filesystem

None

​Save a Snapshot

​Set as Default Environment

​Default Environments

​How Default Environments Work

​Setting a Default Environment

​Best Practices

Use Filesystem Mode

Save After Login

Set as Default

Update Regularly

​Complete Example

​Related Guides

Session Snapshots Overview

Restoring Snapshots

Authentication Management

API Reference

Overview

Snapshot Modes

Save a Snapshot

Set as Default Environment

Default Environments

How Default Environments Work

Setting a Default Environment

Best Practices

Complete Example

Related Guides