walwarden
Reference

SDK install and examples

Generated SDK install notes and examples for the public API v1 alpha surface.

Install the dependency-free TypeScript ESM client:

npm install @walwarden/sdk
import { createWalwardenClient } from '@walwarden/sdk';

const walwarden = createWalwardenClient({
  baseUrl: process.env.WALWARDEN_BASE_URL!,
  apiKey: process.env.WALWARDEN_API_KEY!,
  userAgent: 'my-service/1.0',
});

const { databases } = await walwarden.listDatabases();

Source: GitHub packages/sdk. Package: @walwarden/sdk on npm.

Methods

SDK methodAPI operationScopeNotes
getProfilegetProfilenoneValidate API key profile
listDatabaseslistDatabasesdatabases:readList protected databases
getDatabasegetDatabasedatabases:readRead a protected database
listDestinationslistDestinationsdestinations:readList backup destinations
getDestinationgetDestinationdestinations:readRead a backup destination
listDatabaseBackupslistDatabaseBackupsdatabases:readList backup jobs for a database
triggerBackuptriggerBackupbackups:triggerTrigger an ad-hoc backup
getBackupgetBackupdatabases:readRead backup job status
listEvidencelistEvidenceevidence:readList evidence metadata
getEvidencegetEvidenceevidence:readRead evidence detail
createRestorecreateRestorerestores:writeCreate restore job
getRestoregetRestorerestores:readRead restore job status
getRecoverySummarygetRecoverySummarydatabases:readRead recovery and custody summary
getRecoveryCandidategetRecoveryCandidatedatabases:readFind incident-time recovery candidate
getRecoveryWindowProofgetRecoveryWindowProofdatabases:readRead recovery-window proof status

Backup With Evidence Check

const triggered = await walwarden.triggerBackup(databaseId, {
  idempotencyKey: crypto.randomUUID(),
  trigger: 'adhoc',
});

const completed = await walwarden.pollBackup(triggered.backupJobId, { timeoutMs: 120_000 });
if (completed.state !== 'completed' || !completed.artifact) throw new Error('backup did not produce artifact evidence');

const evidence = await walwarden.listEvidence({ databaseId });
const item = evidence.evidence.find((candidate) => candidate.backupJobId === completed.id);
if (!item?.integrityVerification || item.integrityVerification.result !== 'passed') {
  throw new Error('backup does not have passed integrity evidence');
}

Do not report recoverability from backup completion alone. Treat evidence as successful only after checking the evidence response semantics.

Restore stays a two-step surface: use createRestore to open a CLI-local execution session and getRestore/pollRestore for status reads. End-to-end execution runs through restore execute on the CLI, which is proven against a live disposable target (E2E run e2e-20260607T1941-8beaa08, audit chain reaching restore.completed; evidence in #320).