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. Creating a protected database is currently dashboard-only and supports Supabase and Neon; REST, SDK, and CLI database-create operations are intentionally absent. 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).

Errors, correlation, and retries

Every authenticated operation can return a structured 429 rate_limited or 500 internal_error. Error bodies include a stable error.code and error.requestId; the same correlation value is returned in X-Request-ID. Internal failures are redacted, so use that request ID when contacting support.

Authenticated responses include RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset (whole seconds until the current window resets). A 429 also includes Retry-After as whole delta-seconds. Clients must wait at least Retry-After seconds before retrying and should add jitter when many workers share one API key.

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, 429, 500

List protected databases

GET /databases

Operation ID: listDatabases

Required scope: databases:read

Success responses: 200

Parameters: limit in query, cursor in query

Request body: none

Error responses: 400, 401, 403, 429, 500

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, 429, 500

List backup destinations

GET /destinations

Operation ID: listDestinations

Required scope: destinations:read

Success responses: 200

Lists backup destination summaries without returning credential material.

Parameters: limit in query, cursor in query

Request body: none

Error responses: 400, 401, 403, 429, 500

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, 429, 500

List backup jobs for a database

GET /databases/{databaseId}/backups

Operation ID: listDatabaseBackups

Required scope: databases:read

Success responses: 200

Returns a bounded, high-watermark keyset page. Database ownership is checked before cursor verification, so missing and foreign databases return the same 404.

Parameters: databaseId in path required, limit in query, cursor in query

Request body: none

Error responses: 400, 401, 403, 404, 429, 500

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, 429, 500

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, 429, 500

List evidence metadata

GET /evidence

Operation ID: listEvidence

Required scope: evidence:read

Success responses: 200

Returns a bounded, high-watermark keyset page. A missing or inaccessible databaseId is non-enumerating and returns a terminal 200 empty page before cursor verification.

Parameters: databaseId in query, limit in query, cursor in query

Request body: none

Error responses: 400, 401, 403, 429, 500

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, 429, 500

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, 429, 500

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, 429, 500

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, 429, 500

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, 429, 500

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, 429, 500

Read the live external-agent tool catalog

GET /mcp/tools

Operation ID: getMcpToolCatalog

Required scope: none

Success responses: 200

Returns the capability-registry-derived HTTP tool catalog for MCP-compatible and other external-agent clients. This is plain JSON discovery, not a native MCP JSON-RPC transport.

Parameters: none

Request body: none

Error responses: 401, 429, 500

Contract Artifact

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