Metadata REST API

Caution

This page documents an internal API. These endpoints are used by CLI utilities (analyze.flexfs, find.flexfs, dedup.flexfs). They are not intended for direct external use.

The metadata server exposes a REST API alongside its RPC protocol. The REST endpoints serve utilities and monitoring. All query parameters use kebab-case (e.g., volume-id, base-path).

Common Query Parameters

These parameters are accepted by most endpoints:

Parameter	Type	Description
volume-id	string	Volume UUID or name (required)
base-path	string	Base32-encoded base path to scope the query
at-time	uint64	Point-in-time in nanoseconds since epoch (for time-travel mounts)

Endpoints

Analyze Files

GET /analyze/files

Returns the top files by size, size_bin, or cost within a volume or subtree.

Parameter	Type	Default	Description
volume-id	string		Volume UUID or name (required)
base-path	string		Base32-encoded path prefix
at-time	uint64		Point-in-time (nanoseconds since epoch)
header	bool	false	Include column headers
limit	uint32	100	Maximum results (1-1000)
order-by	string	cost	Sort field: size, size_bin, or cost

Response: 200 OK with tab-separated text, one file per line.

Analyze Folders

GET /analyze/folders

Returns per-directory recursive size and cost.

Parameter	Type	Default	Description
volume-id	string		Volume UUID or name (required)
base-path	string		Base32-encoded path prefix
at-time	uint64		Point-in-time (nanoseconds since epoch)
header	bool	false	Include column headers
max-depth	uint32	0	Maximum depth (0 = unlimited)

Response: 200 OK with tab-separated text.

Analyze Users

GET /analyze/users

Returns per-user size and cost.

Parameter	Type	Default	Description
volume-id	string		Volume UUID or name (required)
base-path	string		Base32-encoded path prefix
at-time	uint64		Point-in-time (nanoseconds since epoch)
header	bool	false	Include column headers
limit	uint32	100	Maximum results (1-1000)
order-by	string	cost	Sort field: size or cost

Response: 200 OK with tab-separated text (UID, size, cost).

Find

GET /find

Searches the filesystem with filters on inode attributes.

Parameter	Type	Description
volume-id	string	Volume UUID or name (required)
base-path	string	Base32-encoded path prefix
fields	string	Comma-separated output fields
header	bool	Include column headers
name	string	Dentry name filter (supports glob)
type	string	Inode type: b, c, d, f, l, p, s
uid	uint32	UID filter
gid	uint32	GID filter
ino	uint64	Inode number filter
empty	bool	Empty file/directory filter
sparse	bool	Sparse file filter
perm	string	Permissions filter (octal)
perm-mask	string	Permissions mask (octal)
min-size, max-size	uint64	Byte size range
min-blocks, max-blocks	uint64	Block count range
min-cost, max-cost	float64	Monthly cost range
min-nlink, max-nlink	uint32	Hard link count range
min-depth, max-depth	uint32	Depth range
min-atime, max-atime	uint64	Access time range (nanoseconds)
min-btime, max-btime	uint64	Birth time range (nanoseconds)
min-ctime, max-ctime	uint64	Change time range (nanoseconds)
min-mtime, max-mtime	uint64	Modification time range (nanoseconds)
min-size-bin, max-size-bin	uint32	Size bin range (0-74)

Response: 200 OK with tab-separated text.

Duplicates

GET /duplicates

Returns groups of files that share the same size and block count, which are candidates for deduplication.

Parameter	Type	Description
volume-id	string	Volume UUID or name (required)
base-path	string	Base32-encoded path prefix
at-time	uint64	Point-in-time (nanoseconds since epoch)
min-size, max-size	uint64	Byte size range
min-blocks, max-blocks	uint64	Block count range

Response: 200 OK with JSON object. Keys are "{size}.{blocks}" and values are arrays of {path, nlink, btime} objects.

Metrics

GET /metrics

Returns Prometheus-format metrics for the metadata server.

Status

GET /status

Returns server health status.