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 | | limit | uint64 | Maximum number of results (0 or omit for unlimited) | | empty | bool | Empty file/directory filter | | sparse | bool | Sparse file filter | | perm | string | Required permission bits (octal string, e.g. 0755). Matches when (mode & perm-mask) == perm. | | perm-mask | string | Bits of the file mode to test (octal string, default 0777, max 07777) | | 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 (seconds since epoch) | | min-btime, max-btime | uint64 | Birth time range (seconds since epoch) | | min-ctime, max-ctime | uint64 | Change time range (seconds since epoch) | | min-mtime, max-mtime | uint64 | Modification time range (seconds since epoch) | | 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) | | limit | uint64 | Maximum number of duplicate groups (0 or omit for unlimited). When set, the largest groups by file size are retained. | | min-size, max-size | uint64 | Byte size range | | min-blocks, max-blocks | uint64 | Block count range |

Response: 200 OK with a JSON array of group objects, ordered by size descending then blocks descending. Each group has size (uint64), blocks (uint64), and files (array of {path, ino, nlink, btime} objects). Multiple paths for the same inode (hard links) are included as separate entries. When limit is set, only the largest groups are returned.

Metrics

GET /metrics

Returns Prometheus-format metrics for the metadata server.

Status

GET /status

Returns server health status.