Skip to content

SharePoint backup ​

Atlas backs up the document libraries of a SharePoint site incrementally: after the first run, each run reads only what changed. One run covers every document library in the site. Every file is encrypted before it leaves the machine, and each unique file is stored once. A run that changes something records a snapshot, and you restore, verify, or export from those snapshots.

For per-user drives, see OneDrive backup.

Quick start ​

bash
# Find the site
atlas sharepoint list-sites

# Back up a site by URL, incrementally
atlas sharepoint backup --site https://contoso.sharepoint.com/sites/Engineering

# Force a full backup, ignoring the saved sync checkpoint
atlas sharepoint backup --site https://contoso.sharepoint.com/sites/Engineering --full

# Verify a snapshot
atlas sharepoint verify --site https://contoso.sharepoint.com/sites/Engineering \
  -s sp-snap-1735689600000-a1b2c3

--site accepts a site URL or a Microsoft Graph site ID. The ID can include the hostname (contoso.sharepoint.com,<site-guid>,<web-guid>) or omit it (<site-guid>,<web-guid>). Snapshot IDs have the form sp-snap-<milliseconds>-<6-hex>, and backup prints the ID of each snapshot it creates.

What is backed up ​

ItemCoverage
Files in every document libraryCurrent content, each unique file stored once within the site
Version historyEarlier versions Microsoft 365 returns for each file
Library and folder pathsRecorded in the snapshot
OneNote notebooksSection files and table of contents, as ordinary files (details)
SubsitesOnly with --include-subsites, one snapshot per subsite
Moves, renames, deletionsRecorded as changes on the next run
SharingEach file's and folder's own permissions, without link URLs (details)
Folder coloursEach folder's colour, captured but not restored (details)

Site and library permissions are not captured. Restores do not recreate file authors or folder colours, and reapply sharing only when asked. See what a drive restore rebuilds, and what it cannot.

Sites that belong to SharePoint Embedded apps are not backed up. See SharePoint Embedded containers.

OneNote notebooks ​

A OneNote notebook is stored as its section files (.one) and its table of contents (.onetoc2), each backed up byte for byte as an ordinary file. The run reports how many notebooks it found, and warns when a notebook is captured incompletely, because a table of contents without its sections restores into a notebook that will not open.

Restored sections arrive as ordinary files. Dropping them back into a library does not rebuild a notebook OneNote will open. Treat notebook restore as recovering the section data, let OneNote import it, and verify the result before relying on it.

Permissions ​

Add these application permissions to the Atlas app registration in Microsoft Entra ID, and grant admin consent:

PermissionUsed for
Sites.Read.AllListing sites and reading library metadata
Files.Read.AllReading file content for backup, verify, and save
Sites.ReadWrite.AllRestore, including sharing

If a permission is missing, the run stops before it touches any files with MissingGraphPermissionsError (ATLAS_AUTH_DENIED, exit 4). The message names the HTTP status, the Microsoft Graph error code, and the permissions to grant:

text
Microsoft Graph returned HTTP 403 accessDenied for site <site-id> and for the tenant's root site. The app registration needs the SharePoint application permissions Sites.Read.All with admin consent, or a Sites.Selected grant on this site.

If the app's credentials work but Microsoft 365 refuses this one site, the run fails with GraphAccessRefusedError (ATLAS_ACCESS_REFUSED, exit 4) instead, and other sites are unaffected. An app that relies on Sites.Selected grants can also see this error when the refused site lacks its own grant, and the message names that remedy. See SharePoint: site refused while the root site is readable.

How Atlas tells a missing grant from a refused site

Microsoft Graph answers both with the same 403 accessDenied. After a listing call is refused, Atlas makes one request, GET /sites/root?$select=id. If the app can read the tenant's root site, its credentials work and the refusal is about this site alone. An app on Sites.Selected grants can read the root site only if it was granted it. The answer is reused for 10 minutes per Graph client, so a run that meets several refused sites checks once.

SharePoint Embedded containers ​

Apps built on SharePoint Embedded, among them several Microsoft apps, store their files in container sites under https://contoso.sharepoint.com/contentstorage/. They appear in the tenant's site search, but Microsoft Graph refuses them to an app that holds only Sites permissions: they need FileStorageContainer.Selected and a grant from the app that owns the container type. Atlas does not request that permission and does not back these sites up.

Atlas lists them rather than hiding them, so a coverage report still shows they exist:

  • atlas sharepoint list-sites shows them with the kind container (not backed up).
  • atlas.sharepoint.listSites() returns them with kind: 'file_storage_container'. Every other site has kind: 'site'.
  • isFileStorageContainerSite(webUrl) applies the same rule to a URL from your own site discovery.

Leave them out of scheduled runs. A backup of one fails at once with GraphAccessRefusedError, and retrying returns the same answer. When the site was given by URL, the error's reason is file_storage_container. When it was given by site ID, reason is access_refused, because Microsoft Graph also refuses the lookup that would reveal the URL.

Commands ​

Every command except list-sites takes --site <url-or-id> (required), and every command takes -t, --tenant <id> (defaults to the configured tenant). Snapshot is -s, since -s is not used for the site. The CLI reference lists global flags and exit codes.

list-sites ​

bash
atlas sharepoint list-sites

Lists every site the tenant's site search returns, with its ID, name, kind, and URL. The kind is site, or container (not backed up) for a SharePoint Embedded container, and a final line counts the containers. Takes only -t, --tenant <id>. If Microsoft Graph refuses the search with 403, the command fails with MissingGraphPermissionsError (ATLAS_AUTH_DENIED, exit 4) naming Sites.Read.All, because the search covers the whole tenant rather than one site.

backup ​

FlagDescriptionDefault
--site <url-or-id>Site URL or Graph site IDRequired
--fullIgnore the saved sync checkpoint and read every libraryfalse
--include-subsitesAlso back up every subsite beneath the site, one snapshot eachfalse
--retention-days <n>Apply Object Lock retention to stored objectsOff
--lock-mode <mode>governance or compliance; requires --retention-daysNot set
-t, --tenant <id>Tenant identifierConfig default
bash
atlas sharepoint backup --site https://contoso.sharepoint.com/sites/Engineering --include-subsites

Each run picks up from a sync checkpoint (a Microsoft Graph delta link) saved by the previous one. Each library keeps its own checkpoint. See incremental sync.

Object Lock

Object Lock makes stored objects undeletable until the retention period ends. Use compliance mode only when no one, including tenant administrators, should be able to shorten it. See immutability.

restore ​

FlagDescriptionDefault
--site <url-or-id>Source siteRequired
-s, --snapshot <id>Snapshot to restoreRequired
--target-site <url-or-id>Restore into a different siteSource site
--destination <path>Folder to restore under; created when missing/Restore-<timestamp>
--in-placeRestore to the original pathsfalse
--name <filename>Rename the restored file; single-file restores onlyOriginal name
--file-filter <paths...>Restore only the given files, by ID or pathAll files
-c, --conflict <mode>rename, replace, or failrename
--restore-permissionsReapply captured grants and recreate sharing links, see Sharingfalse
-t, --tenant <id>Tenant identifierConfig default
bash
# Restore everything into a fresh Restore-<timestamp> folder in each library
atlas sharepoint restore --site https://contoso.sharepoint.com/sites/Engineering -s sp-snap-123

# Restore into a different site
atlas sharepoint restore --site https://contoso.sharepoint.com/sites/Engineering -s sp-snap-123 \
  --target-site https://contoso.sharepoint.com/sites/Staging

# Restore in place with the files' and folders' own sharing
atlas sharepoint restore --site https://contoso.sharepoint.com/sites/Engineering -s sp-snap-123 \
  --in-place --restore-permissions

# Restore two files, replacing any that exist at the destination
atlas sharepoint restore --site https://contoso.sharepoint.com/sites/Engineering -s sp-snap-123 \
  --file-filter /Documents/report.docx /Documents/budget.xlsx -c replace

For how --target-site picks a library, see where a cross-site restore lands.

Conflict modeBehavior
rename (default)Adds a numeric suffix, so existing files are never overwritten
replaceOverwrites the existing file
failSkips the file and logs an error

Restored files keep their original created and modified timestamps. Each file is decrypted and checked against its SHA-256 checksum before upload. A file whose stored object is missing, fails AES-GCM authentication, or does not match the snapshot is reported as a restore error with the reason and is not created. The rest of the snapshot is restored, and the run exits 2. A wrong passphrase stops the run with exit 5 before anything is written.

To stop a restore safely, see stopping a run.

restore-version ​

Restores earlier versions of a file, or of every file as of a point in time. See rolling a file back to an earlier version.

FlagDescriptionDefault
--site <url-or-id>SiteRequired
-f, --file <ref>File ID or path; required with --versionOptional
--version <id>Exact stored version to restoreOptional
--before <iso>Newest version at or before this instant, per fileOptional
--path <prefix>Limit a --before rollback to one folderWhole site
--in-placeUpload over the original filefalse, writes a copy
-t, --tenant <id>Tenant identifierConfig default

save ​

Writes a snapshot to a local zip archive instead of uploading to Microsoft 365. The archive keeps the library folder hierarchy. Files larger than 4 MiB are verified in a first pass and then decrypted as a stream into the archive, so memory use does not grow with file size.

FlagDescriptionDefault
--site <url-or-id>SiteRequired
-s, --snapshot <id>Snapshot to save fromRequired
--file-filter <paths...>Save only the given files, by ID or pathAll files
--output <path>Output zip file pathAuto-generated
-y, --yesOverwrite existing output, no promptfalse
--skip-verifySkip SHA-256 checks while savingfalse
-t, --tenant <id>Tenant identifierConfig default
bash
atlas sharepoint save --site https://contoso.sharepoint.com/sites/Engineering -s sp-snap-123 \
  --output ~/Downloads/backup.zip

If --output names an existing file, Atlas asks Overwrite? [Y/n] before it contacts Microsoft 365 or reads storage. Answering n exits 0 and leaves the file as it was. Pass -y to overwrite without the question. The question exists because an earlier export can be the only copy of a snapshot that retention has since removed.

In unattended runs with stdin at EOF, as under cron or systemd with /dev/null, no answer is read. The command exits 1 and the existing file is untouched. Pass -y in scheduled jobs that overwrite their output.

Mark-of-the-Web on Windows

On Windows the archive is stamped with Mark-of-the-Web (Zone.Identifier, ZoneId=3), so extracted Office files open in Protected View and macros stay blocked. Clear the mark once you trust the content:

powershell
Get-ChildItem -Recurse <dir> | Unblock-File

Nothing is written on macOS or Linux. See exported archives in the CLI reference.

verify ​

Checks a snapshot's integrity without restoring anything.

FlagDescriptionDefault
--site <url-or-id>SiteRequired
-s, --snapshot <id>Snapshot to verifyRequired
-t, --tenant <id>Tenant identifierConfig default
bash
atlas sharepoint verify --site https://contoso.sharepoint.com/sites/Engineering -s sp-snap-1735689600000-a1b2c3

For each file, Atlas decrypts the stored copy, recomputes its SHA-256 over the plaintext, and compares it with the snapshot using a constant-time comparison. It also confirms the per-file version index has a record for the snapshot. Content is streamed, so memory use does not grow with file size.

Exit code 0 means every checked entry passed. Exit code 1 means a content mismatch or an index inconsistency was found.

list-snapshots, list-versions, and list-permissions ​

bash
atlas sharepoint list-snapshots --site https://contoso.sharepoint.com/sites/Engineering
atlas sharepoint list-versions --site https://contoso.sharepoint.com/sites/Engineering \
  -f "/Shared Documents/report.docx"

list-versions takes -f, --file <ref> (a file ID or path, required).

bash
atlas sharepoint list-permissions --site https://contoso.sharepoint.com/sites/Engineering

list-permissions shows who had access to which file or folder at a snapshot, the newest unless -s names one, and the colour of each coloured folder. It reads the backup alone.

status ​

bash
atlas sharepoint status --site https://contoso.sharepoint.com/sites/Engineering

Reports, per library, the file changes waiting for the next backup and the files in the list of failed files. It reads the sync checkpoint without moving it, so the next backup is unaffected. A library is up to date only when it has no pending file and no failed file, so a site with files still waiting for a retry is not reported as current. A Microsoft Graph 401 or 403 exits with code 4. See the status columns.

delete ​

FlagDescriptionDefault
--site <url-or-id>SiteRequired
-s, --snapshot <id>Delete the newest snapshot instead of all data for the siteAll data
-y, --yesSkip the confirmation promptfalse
-t, --tenant <id>Tenant identifierConfig default
bash
atlas sharepoint delete --site https://contoso.sharepoint.com/sites/Engineering -s sp-snap-123

-s accepts only the site's newest snapshot, because each snapshot builds on the ones before it. For an older snapshot Atlas exits with code 11 and deletes nothing. Deleting the newest snapshot also removes the sync checkpoint, so the next backup reads every library in full and captures again what that snapshot held. See what -s does.

Deletion is permanent

Deletion erases every version of each object, not just the latest. Objects still protected by Object Lock are reported as retained, separately from failures. See erasure. To remove all data for a tenant across every workload, use atlas delete --purge.

Where restored files land ​

A restore creates Restore-<timestamp> in each destination library and recreates the original folder structure beneath it. A file backed up from /Reports/2026/Report.docx restores to /Restore-2026-08-27T10-15-30/Reports/2026/Report.docx. Deleting that folder undoes the restore.

A separate folder is the default because the rename conflict mode alone would scatter suffixed copies through live library content. Use --in-place to restore to the original paths, and --destination to choose the folder name. With --in-place, each file returns to the library it came from, using the drive_id stored in the snapshot.

--name is rejected when a restore matches more than one file, so pair it with --file-filter. Nesting under a restore folder lengthens every path. A file that exceeds SharePoint's path length limit is reported as skipped and does not abort the run.

Where a cross-site restore lands ​

Each file in a snapshot records the library it came from, by its drive_id. That ID belongs to the source site, so a restore with --target-site picks a library in the target site for each file:

  1. Same library name. The target library with the same name, compared case-insensitively after Unicode NFC normalization and trimming whitespace. If two target libraries share the name, the restore fails rather than picking one.
  2. The only library. Used only when the snapshot came from a single library and the target site has one library. Snapshots from several libraries are never folded into a single destination library.
  3. Neither. The file is refused, the candidate libraries are named, and the run exits non-zero. Atlas never guesses a production library.

If the target site has no document libraries, the restore fails before uploading anything.

Snapshots taken before 2.1.0-beta

Older snapshots do not record library names, so rule 1 cannot apply. Such a snapshot restores cross-site only when it came from one library and the target has one library. Otherwise it fails under rule 3. Take a fresh backup to restore by name.

Sharing ​

Sharing on files and folders is captured and restored as for OneDrive. See Sharing and Restoring sharing.

  • Site and library permissions are not part of a backup.
  • A restore applies no permission unless you pass --restore-permissions.
  • The first backup after upgrading lists each library in full once, as described in First backup after upgrading.

Restoring sharing into another site

With --target-site and --restore-permissions, the original audience gets access to the copy in the target site. Check who should see it first.

Folder colours ​

Folder colours are captured as for OneDrive and are never restored. See Folder colours.

  • Microsoft Graph refuses every write to a folder's colour with 403 accessDenied, so a coloured folder restored into this or another site takes the library's default colour. Writing colours is tracked in #778.
  • The restore summary reports Folder colours not restored with a count, which does not change the exit code.
  • Reading colours adds 1 resource unit per folder the backup receives. See the cost of capturing folder colours.

Rolling a file back to an earlier version ​

Version restore brings back an earlier version of one file, or the state of a folder as of a point in time, from the stored version history.

bash
# List versions of one file
atlas sharepoint list-versions --site https://contoso.sharepoint.com/sites/Engineering \
  -f "/Shared Documents/report.docx"

# Restore one version as a copy beside the original
atlas sharepoint restore-version --site https://contoso.sharepoint.com/sites/Engineering \
  -f "/Shared Documents/report.docx" --version 3.0

# Roll every file under /Shared Documents/Projects back to 10 March 2026, over the originals
atlas sharepoint restore-version --site https://contoso.sharepoint.com/sites/Engineering \
  --before 2026-03-10T00:00:00Z --path "/Shared Documents/Projects" --in-place
  • Content comes from the verified backup, not from the live file.
  • By default Atlas writes report (restored <timestamp>).docx beside the original and leaves the live file untouched. --in-place overwrites the original.
  • A file with no version before the cutoff is reported as skipped.
  • Versions return to the library they were captured from, so a site with several libraries needs no extra flag.
  • Version restore works only within the same tenant and site. To put files into another site, use restore --target-site, which restores snapshot state, not history.

Reading the result ​

Snapshot health ​

Each backup ends with a health status:

StatusMeaningExit code
HEALTHYEvery file's current content was backed up in every library. The snapshot is safe to rely on.0
UNHEALTHYAt least one file failed, a library failed, an encryption error occurred, or a subsite listing failed under --include-subsites. The run is partial.2
UNHEALTHYThe newest snapshot manifest cannot be read, and nothing else went wrong9

A hard failure that aborts the run exits 1. A rejected token on a subsite listing (401) is a hard failure and exits 4. For an unreadable manifest, the run names it; see damaged manifests. Warnings, such as advisory OneNote notes, print as [!] lines and leave the exit code at 0.

No snapshot is created ​

A run creates a snapshot only when something changed. Two outcomes end without one, and they mean different things:

summary.noSnapshotReasonMeaningRecovery pointCLI prints
no_changesThe site has content, and nothing changed since the last runAn earlier snapshot covers itNo SharePoint changes detected. Snapshot skipped.
no_contentThe site holds nothing to protectNoneNo SharePoint content found. Nothing was backed up and no snapshot exists.

The field is absent when a snapshot was created, and absent when the run was interrupted or ended UNHEALTHY. In those cases check errors and healthy. A run that stored nothing because it was interrupted, or because every changed file failed, exits 2 and prints:

text
No snapshot created: the run was interrupted or every change failed.

When a file cannot be backed up ​

One file that cannot be read never stops the rest of the library. Atlas keeps the files that succeeded, moves the sync checkpoint forward, and records the failure.

SituationWhat Atlas doesWhat you do
Download failsRecords the file in the list of failed files and retries it next runNothing, unless it reaches 5 attempts
Download link expiredFetches a fresh link and continuesNothing
Malware quarantineSkips the download and reports the file as permanently skipped by service policyResolve the file in Microsoft 365 if it should be backed up
Sensitivity label, IRM, or retention ruleRecords a permanent failure for that file, with the Graph error codeReview the policy on that file
Application permission missing (403)Stops the runGrant the permission, see Permissions
Any other unrecognised 403Fails that one file, not the runCheck the Graph error code in the output
File changes size during the downloadReads the file again at its current sizeNothing, unless it keeps changing
Earlier version cannot be downloadedMarks the run UNHEALTHY, or counts the version as unavailableSee version failures

Failed files ​

Each failed file is retried at the start of the next run, before new changes:

  • If the file downloads, it is stored and the failure clears.
  • If the file no longer exists, the failure is dropped.
  • If it fails again, its attempt count increases.

After 5 attempts the file is no longer retried, but every run reports it as PERMANENTLY SKIPPED after 5 attempts. The run stays UNHEALTHY until the file is fixed or removed in the source.

Some failures are not the file's fault and do not use an attempt: an expired download link, a file interrupted by Ctrl+C, and a malware quarantine, which retries cannot change.

Microsoft 365 gives Atlas a time-limited download link for each file. On a long run a link can expire before Atlas reaches the file or while it is reading it. Atlas fetches a fresh link and continues, resuming large files where they stopped. If the file still cannot be read, it is recorded as not backed up and retried on the next run without using an attempt.

How expired links are handled, by file size

A 401 or 403 from the download link means it expired.

File sizeLink at download startWhen the link expires mid-transfer
Up to 4 MiBLink from the change listingFetch a fresh link once, retry the whole file, then fall back to the Graph /content endpoint
Over 4 MiB, under 64 MiBLink from the change listingFetch a fresh link once, restart from byte zero, then fall back to /content
64 MiB and largerFresh link, one Graph requestFetch a fresh link and resume at the 4 MiB range that failed

For files of 64 MiB and larger, a run can refresh the link any number of times, as long as each fresh link delivers at least one more range. If three fresh links in a row expire before any new range arrives, Atlas records the file as not backed up, without counting an attempt. A Graph refusal while fetching a fresh link is handled like the other 403 cases: a missing grant stops the run, and a service refusal is recorded as permanent. The fresh link costs one Graph request per file of 64 MiB or more.

Version failures ​

SituationResult
Unexpected failure: throttling, 403 accessDenied, transient faultError. The run is UNHEALTHY.
Microsoft 365 reports the version gone (404 or 410, purged by the site's retention policy)Counted as unavailable. Health is unaffected.
Download delivers fewer or more bytes than listedFails with DownloadIntegrityError before anything is stored. The run is UNHEALTHY.

Only the HTTP status of the response decides between error and unavailable. An error whose message text happens to contain "404" or "Not Found" is an ordinary failure. A failed version is downloaded again by the next backup that picks up a change to the file.

Files that change size ​

Every download is checked against the size the change listing reported. A file can change between its listing and its download, and SharePoint can rewrite a file on its first download without creating a version. When the size differs, Atlas reads the file's details once more and downloads it again at its current size, and the snapshot records that size.

A file whose size still changes fails with DownloadIntegrityError, is recorded as a failed file, and leaves the run UNHEALTHY. After 5 failed attempts it is reported as PERMANENTLY SKIPPED.

Size check details

Each range of a chunked download also carries the file's total length in its Content-Range header, which is checked too. The refresh costs one item read per mismatching file, and a file gets at most one refresh per run. A truncated transfer or a wrong byte range is never refreshed and fails at once.

Stopping a run ​

Backup. Ctrl+C stops a backup at once, including in the middle of a download, during a Microsoft Graph call, and during a retry or throttle wait. A file interrupted this way is not recorded as failed, so it keeps its 5 attempts for the next run. Rerunning the backup is safe. With --include-subsites, Ctrl+C between two sites exits 2, and the next site is reported as not backed up.

Restore. The first Ctrl+C stops the restore at once, but lets a write already sent to Microsoft 365 finish, because Microsoft 365 may already have committed it. The command prints the files restored so far and exits 2. A file stopped before it was written is not reported as failed. restore-version behaves the same way.

Second Ctrl+C during a restore

A second Ctrl+C exits at once with status 130 and skips the safe stop. A file whose upload was in flight may or may not exist. Check the destination before retrying, especially with --in-place.

Which writes finish after Ctrl+C

A file up to 4 MiB is uploaded in one request. A larger file is created by the final chunk of its upload session, so that request finishes and the file counts as restored if Microsoft 365 accepted it. A larger file stopped before its final chunk is not created, and its upload session is deleted.

See reliability for retries and what is safe to rerun.

Limits ​

AreaLimit
DownloadsUp to 4 MiB in one request; 4 to 64 MiB in 4 MiB ranges; 64 MiB and larger streamed through a staging upload
Uploads on restoreUp to 4 MiB in one request; larger files in a resumable upload session in 10 MiB chunks
ThrottlingRetried with backoff, see below
Path lengthA restore folder adds path depth. Files over SharePoint's path length limit are skipped and reported.
ScopeFile authors and folder colours are not restored. Item sharing is restored only with --restore-permissions. Site and library permissions are not captured

When Microsoft 365 throttles requests or has a transient fault, Atlas waits and retries. See Graph rate limits for request budgets.

Retry and throttling details
  • Graph 429, transient 500, 502, 503 and 504 responses, and dropped connections are retried with backoff, up to 5 times per range for chunked downloads.
  • A file up to 4 MiB is read from its download link in one request. A 429 there is retried up to 3 times against the same link before Atlas falls back to the Graph /content endpoint.
  • A Retry-After on a download is honoured in either form, seconds or an HTTP date, and capped at one hour.

Storage layout ​

Site data lives in the per-tenant bucket, under the sharepoint/ prefix:

atlas-{tenant_id}/
  sharepoint/
    data/{site_id}/{content_name}        # Encrypted file blobs (keyed content names)
    manifests/{site_id}/{snapshot_id}.json
    index/{site_id}/files/{file_id}.json
    staging/{site_id}/{item_id}-{rand}   # In-flight large-file uploads
    _meta/{site_id}/delta.json           # Encrypted sync checkpoint per library

Object paths use the site ID without its hostname, for example <site-guid>,<web-guid>. Files of 64 MiB and larger pass through staging/ before they are copied to their final path. See storage layout for the whole bucket.

Upgrading from v5

v5 stored data under the full site ID, including the hostname. There is no migration, and old objects stay in the bucket until deleted. See Migrating to v6.

SDK usage ​

The SDK exposes the same operations on atlas.sharepoint. Options and results use camelCase. Site arguments accept a URL or a host,site-guid,web-guid ID.

ts
import { createAtlasInstance } from '@wisecom/atlas-sdk';

const atlas = createAtlasInstance({
  tenantId: '<tenant-id>',
  clientId: '<client-id>',
  clientSecret: '<client-secret>',
  s3Endpoint: 'http://localhost:9000',
  s3AccessKey: '<access-key>',
  s3SecretKey: '<secret-key>',
  encryptionPassphrase: '<passphrase>',
});

const site = 'https://contoso.sharepoint.com/sites/Engineering';

// backup() returns one result per site, root first
const [root] = await atlas.sharepoint.backup(site);
console.log(`Snapshot: ${root.snapshot?.snapshotId}, stored: ${root.summary.filesStored}`);

// Include subsites: one snapshot and one result per site
const tree = await atlas.sharepoint.backup(site, { includeSubsites: true });
console.log(`Backed up ${tree.length} site(s)`);

// Verify a snapshot
const verify = await atlas.sharepoint.verify(site, 'sp-snap-1735689600000-a1b2c3');
if (verify.failedFileIds.length > 0) {
  console.error('Failed files:', verify.failedFileIds);
}

// Restore into a Restore-<timestamp> folder in each library
const restored = await atlas.sharepoint.restore(site, {
  snapshotId: 'sp-snap-123',
  conflictBehavior: 'rename',
});
console.log(`Restored: ${restored.filesRestored} files`);

// Save to a local zip archive
const saved = await atlas.sharepoint.save(site, {
  snapshotId: 'sp-snap-123',
  outputPath: 'sharepoint-backup.zip',
});
console.log(`Saved: ${saved.filesSaved} files`);

// Erase all data for a site
const deletion = await atlas.sharepoint.deleteSiteData(site);
console.log(`Deleted: ${deletion.deletedObjects} objects`);

Other methods: restoreVersion, listSnapshots, listFileVersions, listPermissions, checkStatus, and deleteSnapshot. See the SDK reference.

Site discovery ​

List the tenant's sites, skip SharePoint Embedded containers, and handle sites Microsoft 365 refuses:

ts
import { GraphAccessRefusedError, isFileStorageContainerSite } from '@wisecom/atlas-sdk';

const sites = await atlas.sharepoint.listSites();
for (const s of sites) {
  if (s.kind === 'file_storage_container') continue; // SharePoint Embedded, not backed up
  try {
    await atlas.sharepoint.backup(s.siteId);
  } catch (err) {
    if (!(err instanceof GraphAccessRefusedError)) throw err;
    // Retrying returns the same answer. Containers were skipped above, so check this site's
    // per-site grant before treating it as unsupported.
    console.log(
      `Refused: ${err.site_id} (${err.reason}, HTTP ${err.status_code} ${err.graph_code})`,
    );
  }
}

// The same rule for sites found by your own discovery
isFileStorageContainerSite('https://contoso.sharepoint.com/contentstorage/CSP_example'); // true

const resolved = await atlas.sharepoint.resolveSite(site);
console.log(resolved.siteId, resolved.kind);

See also ​