API reference

Walwarden Public API 1.0.0-alpha. Public REST API v1 for scoped machine clients. This alpha slice exposes database and destination reads, backup trigger/status, evidence metadata, and restore create/status for CLI-local execution. The restore create/status pair opens and tracks a CLI-local restore session; end-to-end execution runs through the CLI restore execute bridge, proven against a live disposable target (E2E run e2e-20260607T1941-8beaa08, audit chain reaching restore.completed; evidence in #320).

Base path: /api/v1. Send API keys as Authorization: Bearer <token>. Issue and scope a token from the dashboard — see Issue a dashboard API token.

The alpha surface is intentionally small. restore create opens a CLI-local restore session; restore execute is the proven end-to-end local execution bridge, verified against a live disposable target (E2E run e2e-20260607T1941-8beaa08, audit chain reaching restore.completed; evidence in #320).

Operations

Validate API key profile

GET /profile

Operation ID: getProfile

Required scope: none

Success responses: 200

Returns safe machine-client identity metadata for the active API key. Requires a valid Bearer API key but no resource scope.

Parameters: none

Request body: none

Error responses: 401

List protected databases

GET /databases

Operation ID: listDatabases

Required scope: databases:read

Success responses: 200

Parameters: none

Request body: none

Error responses: 401, 403

Read a protected database

GET /databases/{databaseId}

Operation ID: getDatabase

Required scope: databases:read

Success responses: 200

Parameters: databaseId in path required

Request body: none

Error responses: 401, 403, 404

List backup destinations

GET /destinations

Operation ID: listDestinations

Required scope: destinations:read

Success responses: 200

Lists backup destination summaries without returning credential material.

Parameters: none

Request body: none

Error responses: 401, 403

Read a backup destination

GET /destinations/{destinationId}

Operation ID: getDestination

Required scope: destinations:read

Success responses: 200

Reads one backup destination summary without returning credential material.

Parameters: destinationId in path required

Request body: none

Error responses: 401, 403, 404

List backup jobs for a database

GET /databases/{databaseId}/backups

Operation ID: listDatabaseBackups

Required scope: databases:read

Success responses: 200

Parameters: databaseId in path required

Request body: none

Error responses: 401, 403, 404

Trigger an ad-hoc backup

POST /databases/{databaseId}/backups

Operation ID: triggerBackup

Required scope: backups:trigger

Success responses: 202

Parameters: databaseId in path required, Idempotency-Key in header required

Request body: TriggerBackupRequest

Error responses: 400, 401, 403, 404, 409, 412

Read backup job status

GET /backups/{backupJobId}

Operation ID: getBackup

Required scope: databases:read

Success responses: 200

Parameters: backupJobId in path required

Request body: none

Error responses: 401, 403, 404

List evidence metadata

GET /evidence

Operation ID: listEvidence

Required scope: evidence:read

Success responses: 200

Parameters: databaseId in query

Request body: none

Error responses: 401, 403

Read evidence detail

GET /evidence/{backupJobId}

Operation ID: getEvidence

Required scope: evidence:read

Success responses: 200

Parameters: backupJobId in path required

Request body: none

Error responses: 401, 403, 404

Create restore job

POST /restores

Operation ID: createRestore

Required scope: restores:write

Success responses: 202

Creates a restore job for CLI-local execution from a completed backup. Raw target database credentials must remain client-side; the request sends only targetRedactedDsn. Do not claim this restore flow production-green until the #320 live disposable-target E2E proof is attached.

Parameters: Idempotency-Key in header required

Request body: CreateRestoreRequest

Error responses: 400, 401, 403, 404, 409, 412

Read restore job status

GET /restores/{restoreJobId}

Operation ID: getRestore

Required scope: restores:read

Success responses: 200

Parameters: restoreJobId in path required

Request body: none

Error responses: 401, 403, 404

Read recovery and custody summary

GET /databases/{databaseId}/recovery/summary

Operation ID: getRecoverySummary

Required scope: databases:read

Success responses: 200

Returns the latest decision-grade recovery window summary for a database.

Parameters: databaseId in path required

Request body: none

Error responses: 401, 403, 404

Find incident-time recovery candidate

GET /databases/{databaseId}/recovery/candidate

Operation ID: getRecoveryCandidate

Required scope: databases:read

Success responses: 200

Returns the closest restore-ready snapshot/cursor candidate before the requested incident time.

Parameters: databaseId in path required, incidentTime in query required

Request body: none

Error responses: 400, 401, 403, 404

Read recovery-window proof status

GET /recovery/windows/{windowId}/proof

Operation ID: getRecoveryWindowProof

Required scope: databases:read

Success responses: 200

Returns proof and custody status for a selected recovery window without exposing raw segment internals.

Parameters: windowId in path required

Request body: none

Error responses: 401, 403, 404

Contract Artifact

Download the OpenAPI artifact at /openapi/walwarden.v1.json.