Skip to main content

​
Snapshots

​
List Snapshots

Get a list of available snapshot files in the snapshot directory. 
curl http://localhost:8002/osm/api/snapshots \
  -H "Authorization: Bearer $TOKEN"
Response: 
{
  "data": [
    {
      "name": "example.com_1704067200.zip",
      "path": "/home/user/osmedeus-base/snapshot/example.com_1704067200.zip",
      "size": 15728640,
      "created_at": "2025-01-01T12:00:00Z"
    },
    {
      "name": "test.com_1704153600.zip",
      "path": "/home/user/osmedeus-base/snapshot/test.com_1704153600.zip",
      "size": 8388608,
      "created_at": "2025-01-02T12:00:00Z"
    }
  ],
  "count": 2,
  "path": "/home/user/osmedeus-base/snapshot"
}

​
Export Workspace Snapshot

Export a workspace to a compressed zip archive and download it. 
curl -X POST http://localhost:8002/osm/api/snapshots/export \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workspace": "example.com"}' \
  --output example.com_snapshot.zip
Request Body:
FieldTypeRequiredDescription
workspacestringYesName of the workspace to export
Response:
  • On success: Returns the zip file as a binary download
  • Response headers include:
    • Content-Disposition: attachment; filename=<workspace>_<timestamp>.zip
    • Content-Type: application/zip
    • X-Snapshot-Size: <size_in_bytes>
Error Response (404): 
{
  "error": true,
  "message": "Workspace not found: example.com"
}

​
Import Workspace Snapshot

Import a workspace from an uploaded zip file or URL. Import from file upload: 
curl -X POST http://localhost:8002/osm/api/snapshots/import \
  -H "Authorization: Bearer $TOKEN" \
  -F "[email protected]_1704067200.zip"
Import from URL: 
curl -X POST http://localhost:8002/osm/api/snapshots/import \
  -H "Authorization: Bearer $TOKEN" \
  -F "url=https://example.com/snapshots/workspace.zip"
Import with force overwrite: 
curl -X POST http://localhost:8002/osm/api/snapshots/import \
  -H "Authorization: Bearer $TOKEN" \
  -F "[email protected]_snapshot.zip" \
  -F "force=true"
Import files only (skip database): 
curl -X POST http://localhost:8002/osm/api/snapshots/import \
  -H "Authorization: Bearer $TOKEN" \
  -F "[email protected]_snapshot.zip" \
  -F "skip_db=true"
Form Parameters:
ParameterTypeRequiredDescription
filefileNo*Snapshot zip file to import
urlstringNo*URL of snapshot to download and import
forceboolNoOverwrite existing workspace if present (default: false)
skip_dbboolNoSkip database import, extract files only (default: false)
*Either file or url is required. Response (200): 
{
  "message": "Workspace imported successfully",
  "workspace": "example.com",
  "local_path": "/home/user/workspaces-osmedeus/example.com",
  "data_source": "imported",
  "files_count": 1523,
  "warning": "Imported workspace database state may be unstable. Only import from trusted sources."
}
Error Response (400): 
{
  "error": true,
  "message": "Either file or url is required"
}
Error Response (500 - workspace exists): 
{
  "error": true,
  "message": "Failed to import snapshot: workspace already exists: /home/user/workspaces-osmedeus/example.com (use --force to overwrite)"
}

​
Delete Snapshot

Delete a snapshot file by name. 
curl -X DELETE http://localhost:8002/osm/api/snapshots/example.com_1704067200.zip \
  -H "Authorization: Bearer $TOKEN"
Response: 
{
  "message": "Snapshot deleted successfully",
  "name": "example.com_1704067200.zip"
}
Error Response (404): 
{
  "error": true,
  "message": "Snapshot not found: example.com_1704067200.zip"
}

​
Legacy Endpoint

The legacy snapshot download endpoint is still available for backward compatibility: 
curl http://localhost:8002/osm/api/snapshot-download/example.com \
  -H "Authorization: Bearer $TOKEN" \
  --output snapshot.zip

​
Data Source Values

When a workspace is imported, its data_source field is set to indicate how it was created:
ValueDescription
localCreated locally via scan (default)
cloudSynced from cloud storage
importedImported from snapshot file

​
Security Considerations

Warning: Only import snapshots from trusted sources! Imported workspace data may contain:
  • Database records that could conflict with existing data
  • File paths that reference external resources
  • Configuration that may not be compatible
The imported workspace database state may be unstable. Use the skip_db=true parameter if you only need the files without database import.