Evidence API resources

Field-by-field reference for the v1alpha1 payloads. The transport, envelope, pagination, and error rules are in the evidence API reference.

The authoritative machine-readable definition is the generated api/evidence/v1alpha1/schema.json plus the Go types beside it and the wire goldens under testdata/wire. If this page and the schema ever disagree, the schema is right.

Two rules apply everywhere: a nullable field is present with a JSON null when it is unknown, never omitted and never zero; and omitting a field can never improve a state.

Capabilities

capabilities is a complete, unique, id-sorted array.

Field	Type	Rule
id	string enum	format-neutral capability identifier
support	supported, unsupported, unknown	unsupported or unknown support requires state: unknown
state	four-state enum	current evidence for this capability
reason	Reason	bounded typed explanation

The identifiers are exactly:

object-inventory, catalog-listing, structural-artifact-validation, dependency-chain-validation, wal-continuity, timeline-history-traversal, encrypted-metadata, observed-recovery-coverage, retention-expectation-comparison.

An unsupported, disabled, or failed capability stays visible and forces dependent conclusions to unknown. It never disappears from the payload and is never rendered as zero or healthy.

Inventory summary

Field	Type	Rule
known	boolean	false after an incomplete first scan; retained stale evidence stays known and is governed by the top-level stale/state
object_count	integer or null	exact only when known
stored_bytes	integer or null	exact visible object bytes, only when known
unscoped_object_count	integer or null	exact only when known; sidecar prefix confinement should normally make this zero
pages_examined	integer	bounded attempt fact
objects_examined	integer	bounded attempt fact
last_failure_category	string or null	stable redacted category only

Raw recent objects and custom object metadata are intentionally absent.

Typed details union

details is a closed, validated tagged union:

{
  "type": "barman-cloud/v1alpha1",
  "barman_cloud": {}
}

Exactly one payload matching type is allowed; map[string]any is forbidden. For an unrecognized type the types module keeps only the bounded tag, discards the payload, and marks format details unavailable/unknown while keeping a valid common envelope.

barman_cloud summary

Field	Type	Rule
backup_items	unsigned integer or null	exact number available through /backups
wal_range_items	unsigned integer or null	exact number available through /wal-ranges
wal_gap_items	unsigned integer or null	exact number available through /wal-gaps
recovery_path_items	unsigned integer or null	exact number available through /recovery-paths
structurally_usable_backups	unsigned integer or null	backups proven structurally usable by Barman rules
backup_states	StateCounts or null	all four state counts when known
wal_counts	BarmanWALCounts or null	all supported WAL class counts when known
wal	StateReason	WAL continuity state
timeline	StateReason	timeline-history state
coverage	StateReason	observed recovery-coverage state
retention	BarmanRetentionSummary	descriptive or expected retention result
latest_archive_receipt_at	timestamp or null	latest provider receipt/modification time, never transaction time
ranges_truncated	boolean	a safety ceiling was reached building ranges
diagnostics_truncated	boolean	a safety ceiling was reached retaining diagnostics

StateCounts has required unsigned integers healthy, warning, unhealthy, unknown. BarmanWALCounts has required unsigned integers segment, partial, history, backup_history, unknown, duplicate.

BarmanRetentionSummary has visible_backups and structurally_usable_backups (unsigned integer or null), oldest_completion_at and newest_completion_at (timestamp or null), minimum_configured and policy_configured (boolean), minimum_redundancy (unsigned integer or null, and null unless minimum_configured is true), plus required state and reason. A configured but unrecognized policy forces retention state to unknown.

Collection counts are null whenever the governing evidence is incomplete, and a truncation flag forces its dependent state to unknown.

Barman backup items

GET /api/v1alpha1/backups → BarmanBackupPage. Sorted by exact backup_id, then server. Backup IDs are case-sensitive opaque identifiers — do not parse timestamps out of them.

Field	Type	Rule
server	string	exact configured Barman server
backup_id	string	exact case-sensitive Barman backup ID, ≤ 256 bytes
status	string or null	allowlisted format-native status, ≤ 64 bytes
backup_type	string or null	allowlisted format-native type, ≤ 64 bytes; an unknown type is null and forces state unknown
state	four-state enum	structural evidence for this backup
reason	Reason	required typed reason
system_id	decimal string or null	PostgreSQL system identifier, never a JSON number
postgresql_version	unsigned integer or null	format-declared version
timeline	unsigned integer or null	timeline ID; zero is invalid
wal_segment_size_bytes	unsigned integer or null	format-declared; no 16 MiB default
begin_wal / end_wal	string or null	allowlisted WAL segment names, not object keys
begin_lsn / end_lsn	string or null	validated uppercase PostgreSQL LSN
begin_at / end_at	timestamp or null	format-declared begin and completion time
logical_bytes	unsigned integer or null	logical backup size
deduplicated_bytes	unsigned integer or null	only when explicitly declared by the format
stored_artifact_bytes	unsigned integer or null	exact visible bytes of validated artifacts
compression	string or null	allowlisted classification, not provider metadata
encryption	string or null	allowlisted classification; unknown never becomes none
artifact_count	unsigned integer or null	count only — artifact keys are forbidden
tablespace_count	unsigned integer or null	count only — OIDs and paths are forbidden

An item's state is the last complete evidence for that backup. If the parent snapshot is stale or unknown, render the item as retained historical evidence, not as currently healthy.

WAL range items

GET /api/v1alpha1/wal-ranges → BarmanWALRangePage. Sorted by server, timeline, then start position.

Field	Type	Rule
server	string	exact configured Barman server
timeline	unsigned integer	timeline ID; zero is invalid
start_position	unsigned integer	format-derived segment position
end_position	unsigned integer	inclusive position, not an LSN
segment_count	unsigned integer	exact count in the compact range
first_wal / last_wal	string	allowlisted WAL names
latest_receipt_at	timestamp or null	latest provider receipt/modification time in the range
end_receipt_at	timestamp or null	receipt/modification time of the ending segment

WAL gap items

GET /api/v1alpha1/wal-gaps → BarmanWALGapPage. Sorted by server, timeline, then start position.

Field	Type	Rule
server	string	exact configured Barman server
timeline	unsigned integer	timeline ID; zero is invalid
start_position	unsigned integer	first missing position
end_position	unsigned integer	last missing position, inclusive
segment_count	unsigned integer	exact number of missing positions
first_wal / last_wal	string	first and last missing WAL name
status	string enum	exactly candidate or confirmed
first_observed_generation	unsigned integer	complete generation that first observed the candidate
last_observed_generation	unsigned integer	most recent complete generation observing it

A confirmed gap must have passed the gap lifecycle; a failed or incomplete scan cannot advance either generation.

WAL names are format-native segment identifiers, never object keys. Provider receipt timestamps are never transaction timestamps or PITR endpoints. Diagnostics that contain object keys stay in the standalone viewer and are not part of this API version.

Recovery-path items

GET /api/v1alpha1/recovery-paths → BarmanRecoveryPathPage. Sorted by backup ID, then target timeline.

Field	Type	Rule
server	string	exact configured Barman server
backup_id	string	exact case-sensitive Barman backup ID
target_timeline	unsigned integer	requested or derived target timeline
state	four-state enum	conservative observed-coverage state
reason	Reason	required typed reason
stop	string enum	frontier, candidate-limited, gap-limited, or unknown-limited
lower_bound_at	timestamp or null	conservative lower bound, never an exact PITR endpoint
start_timeline	unsigned integer or null	proven starting timeline
start_position	unsigned integer or null	proven starting segment position
start_wal	string or null	proven starting WAL name
frontier_timeline	unsigned integer or null	timeline at the observed frontier
frontier_position	unsigned integer or null	position at the observed frontier
frontier_wal	string or null	WAL name at the observed frontier
frontier_receipt_at	timestamp or null	provider receipt/modification time, not transaction time
assumption_codes	array of string enums	sorted, unique, ≤ 32 allowlisted codes of ≤ 64 bytes each

Timeline-history keys, content, and graph edges are not exported in v1alpha1. The summary still exposes timeline capability and state, and every stop caused by missing or invalid ancestry is preserved in the path.

The API and its consumers say "observed recovery coverage". They never return or render "exact PITR window", "restorable until", "restore guaranteed", or "restore verified".