delete-snapshot

Permanently remove snapshots from your workspace. This action cannot be undone.

Overview

The delete-snapshot tool permanently removes a snapshot and all associated data from the database. This includes the content, embeddings, enrichment data, and metadata.

⚠️ Warning: Permanent Deletion

•This action is irreversible - deleted snapshots cannot be recovered
•All AI enrichment data (summary, key points, concepts) will be lost
•Vector embeddings will be removed from the search index
•All metadata (client, session, conversation, etc.) will be deleted
•Analytics records referencing this snapshot will lose the connection

When to Use

Use this tool when you need to:

• Remove sensitive information that was accidentally saved
• Clean up test or experimental snapshots
• Delete outdated or no longer relevant conversations
• Comply with data deletion requests (GDPR, etc.)
• Free up storage space (though Spaces has generous limits)
• Remove duplicate snapshots

Permissions

Who Can Delete Snapshots?

Private Scope

Only the snapshot owner can delete their private snapshots.

Workspace Scope

The snapshot owner and workspace administrators can delete workspace-scoped snapshots.

Global Scope

Only system administrators can delete globally-scoped snapshots.

Parameters

snapshotIdREQUIRED

Type: string

The UUID of the snapshot to delete.

Example: "550e8400-e29b-41d4-a716-446655440000"

confirmREQUIRED

Type: boolean

Must be set to true to confirm the deletion. This prevents accidental deletions.

Required value: true

Response

Success

{
  "success": true,
  "message": "Snapshot successfully deleted",
  "snapshotId": "550e8400-e29b-41d4-a716-446655440000",
  "deletedAt": "2025-10-17T15:45:00Z"
}

Error Responses

Missing Confirmation

{
  "success": false,
  "error": "Deletion must be confirmed with confirm: true",
  "code": "CONFIRMATION_REQUIRED"
}

Snapshot Not Found

{
  "success": false,
  "error": "Snapshot not found",
  "code": "NOT_FOUND"
}

Insufficient Permissions

{
  "success": false,
  "error": "You do not have permission to delete this snapshot",
  "code": "FORBIDDEN"
}

This occurs when trying to delete a snapshot you don't own or don't have admin rights for.

Examples

Basic Deletion

delete-snapshot({
  snapshotId: "550e8400-e29b-41d4-a716-446655440000",
  confirm: true
})

Safe Deletion Workflow

// 1. First, retrieve the snapshot to verify it's the right one
const snapshot = get-snapshot({
  snapshotId: "550e8400-e29b-41d4-a716-446655440000"
})

// 2. Review the summary or content
console.log(snapshot.summary)
// Output: "Discussed OAuth 2.0 implementation..."

// 3. Confirm it's the one you want to delete, then delete
const result = delete-snapshot({
  snapshotId: "550e8400-e29b-41d4-a716-446655440000",
  confirm: true
})

console.log(result.message)
// Output: "Snapshot successfully deleted"

Bulk Deletion

// Get all test snapshots
const snapshots = list-snapshots({
  category: "general",
  limit: 100
})

// Filter for ones tagged as "test"
const testSnapshots = snapshots.snapshots.filter(s =>
  s.metadata?.custom?.tags?.includes("test")
)

// Delete each one
for (const snapshot of testSnapshots) {
  const result = delete-snapshot({
    snapshotId: snapshot.id,
    confirm: true
  })
  console.log(`Deleted ${snapshot.id}`)
}

Note: Be very careful with bulk deletion scripts. Always verify before deleting multiple snapshots.

Best Practices

✓Always verify first: Use get-snapshot to review before deleting
✓Consider archiving: Instead of deleting, you could mark snapshots as archived using custom metadata
✓Export before deleting: For important data, export to a file before deletion
✓Be cautious with automation: Only automate deletion for well-defined, safe cases (like test data)
✓Log deletions: Keep an audit log of what was deleted and when
✓Respect scope permissions: Don't delete workspace snapshots unless you're an admin

Data Retention & Privacy

Immediate Deletion: When a snapshot is deleted, it is immediately removed from the database. There is no "soft delete" or recovery period.

Backups: Deleted snapshots may persist in database backups for up to 30 days according to Supabase's backup retention policy. However, they are not accessible via the API.

Analytics Impact: Deleting a snapshot does not delete analytics records that reference it, but those records will show the snapshot as "deleted".

GDPR Compliance: To fully comply with a data deletion request, you may need to contact support to ensure removal from all backups.