Stat inode

GET

/v0/namespaces/{namespace_id}/inodes/{inode_id}

Returns the path entry for a visible inode from the current state or a live snapshot. Unknown or hidden inodes answer inode_not_found.

Authorizations

• bearer_auth

Parameters

Path Parameters

namespace_id

required

string

Namespace id

inode_id

required

string

/^ino_[1-9][0-9]*$/

Inode ID

Example

ino_123

Query Parameters

include_attributes

boolean

default: true

Project the inode’s attribute map and revision (true or false). Defaults to true: a stat answers for one path and a map is capped at 64 KiB.

snapshot_id

Durable pin identifier. The manifest number determines which namespace manifest it pins.

string

/^pin_[0-9]{20}-[0-9a-f]{16}$/

Example

pin_00000000000000000001-0000000000000002

Use the path state captured by this snapshot

Responses

200

Authoritative current inode entry

One of: discriminator: inode_kind

dir

dir

A directory without a revision payload.

object

attributes

The complete attribute map at attributes_revision_no, including an empty map for the initial state.

object

key

additional properties

A validated inode attribute value of at most 4,096 UTF-8 bytes.

Empty strings and control characters are valid, and only an explicit remove operation deletes an attribute.

string

Example

platform

attributes_revision_no

The attribute revision this projection represents.

integer format: int64

<= 9007199254740991

attributes_updated_at_ms

The latest attribute update time in Unix milliseconds, absent for the initial empty state.

integer format: int64

attributes_updated_by

The actor responsible for the latest attribute update, absent for the initial empty state.

string

/^[\x21-\x7E]{1,256}$/

Example

usr_8f3c

binding_version

The opaque ID for the current parent and name binding, absent for the namespace root.

string

/^[0-9a-f]+$/

created_at_ms

required

The inode creation time in Unix milliseconds.

integer format: int64

created_by

required

Actor that created this inode, as supplied by the application.

string

/^[\x21-\x7E]{1,256}$/

Example

usr_8f3c

display_name

Stored display name for this path component, absent for the nameless root.

string

Example

report.txt

head_seq

required

Namespace head sequence this answer was read from.

integer format: int64

<= 9007199254740991

inode_id

required

Stable inode identity for this item.

string

/^ino_[1-9][0-9]*$/

Example

ino_123

inode_kind

required

Whether the entry is a file or a directory.

string

Allowed values: dir

namespace_id

required

Namespace that was read.

string

/^[a-z0-9][a-z0-9._-]{0,127}$/

Example

demo

parent_inode_id

Parent directory inode, absent for the root.

string

/^ino_[1-9][0-9]*$/

Example

ino_123

path

required

Absolute path as rendered from stored display names.

string

Example

/docs/report.txt

file

file

A file and its current revision summary.

object

attributes

The complete attribute map at attributes_revision_no, including an empty map for the initial state.

object

key

additional properties

A validated inode attribute value of at most 4,096 UTF-8 bytes.

Empty strings and control characters are valid, and only an explicit remove operation deletes an attribute.

string

Example

platform

attributes_revision_no

The attribute revision this projection represents.

integer format: int64

<= 9007199254740991

attributes_updated_at_ms

The latest attribute update time in Unix milliseconds, absent for the initial empty state.

integer format: int64

attributes_updated_by

The actor responsible for the latest attribute update, absent for the initial empty state.

string

/^[\x21-\x7E]{1,256}$/

Example

usr_8f3c

binding_version

The opaque ID for the current parent and name binding, absent for the namespace root.

string

/^[0-9a-f]+$/

content_ref

required

Current content reference.

object

checksum

required

Mandatory checksum over the complete object.

object

algorithm

required

Algorithm that produced value.

string

Allowed values: sha256 crc64nvme crc32c

value

required

The canonical lowercase hexadecimal checksum without a prefix.

string

content_id

required

Immutable identity of the content; with the owner, it determines the object key.

string

/^con_[0-9a-f]{32}$/

Example

con_9f2a6c0e4b7d4a90b13f0d8c5e6a2b41

kind

required

Content strategy used by the referenced content.

string

Allowed values: blob_v1

owner_namespace_id

required

Namespace that originally wrote the bytes.

string

/^[a-z0-9][a-z0-9._-]{0,127}$/

Example

demo

size_bytes

required

Complete byte length of the referenced content.

integer format: int64

created_at_ms

required

The inode creation time in Unix milliseconds.

integer format: int64

created_by

required

Actor that created this inode, as supplied by the application.

string

/^[\x21-\x7E]{1,256}$/

Example

usr_8f3c

display_name

Stored display name for this path component, absent for the nameless root.

string

Example

report.txt

head_seq

required

Namespace head sequence this answer was read from.

integer format: int64

<= 9007199254740991

inode_id

required

Stable inode identity for this item.

string

/^ino_[1-9][0-9]*$/

Example

ino_123

inode_kind

required

Whether the entry is a file or a directory.

string

Allowed values: file

namespace_id

required

Namespace that was read.

string

/^[a-z0-9][a-z0-9._-]{0,127}$/

Example

demo

parent_inode_id

Parent directory inode, absent for the root.

string

/^ino_[1-9][0-9]*$/

Example

ino_123

path

required

Absolute path as rendered from stored display names.

string

Example

/docs/report.txt

revision_committed_at_ms

required

The current revision time in Unix milliseconds.

integer format: int64

revision_committed_by

required

Actor responsible for the current revision.

string

/^[\x21-\x7E]{1,256}$/

Example

usr_8f3c

revision_no

required

Current file revision number.

integer format: int64

<= 9007199254740991

size_bytes

required

The current file size in bytes.

integer format: int64

400

Invalid inode ID, include_attributes, snapshot id, or non-snapshot checkpoint

HTTP error body used by LoonFS APIs.

object

code

required

The stable machine-readable error code as a string.

string

details

The optional machine-readable context for the error code.

object

active_acquired_at_ms

The Unix-millisecond time when the current writer acquired its epoch, when available.

integer format: int64

active_writer_epoch

Epoch that currently owns the namespace.

integer format: int64

<= 9007199254740991

active_writer_id

The writer ID recorded for the current epoch, when available.

string

actual_access_revision_no

Access revision that is actually current for the inode.

integer format: int64

<= 9007199254740991

actual_attributes_revision_no

Attribute revision that is actually current for the inode.

integer format: int64

<= 9007199254740991

actual_binding_version

Current binding token; absent for the root, which has no binding.

string

/^[0-9a-f]+$/

actual_deletion_seq

Deletion sequence actually active for the inode.

integer format: int64

<= 9007199254740991

actual_head_seq

The actual namespace head sequence.

integer format: int64

<= 9007199254740991

actual_inode_id

The path actually contained this inode.

string

/^ino_[1-9][0-9]*$/

Example

ino_123

actual_revision_no

Revision that is actually current; absent when the inode has none.

integer format: int64

<= 9007199254740991

after_seq

Change-feed cursor the request asked to resume after.

integer format: int64

<= 9007199254740991

commit_id

Idempotency key of the commit the error concerns.

string

/^[a-z0-9][a-z0-9._-]{0,127}$/

Example

c_f3a9c2d4b6e8417a90c5d2f8e1b7a6c0

committed_fingerprint

The fingerprint of the mutation that landed under commit_id, present with committed_seq.

string

committed_seq

The sequence where this commit ID already landed, when recorded by a durable receipt.

integer format: int64

<= 9007199254740991

expected_access_revision_no

Access revision the request expected to be current.

integer format: int64

<= 9007199254740991

expected_attributes_revision_no

Attribute revision the request expected to be current.

integer format: int64

<= 9007199254740991

expected_binding_version

Opaque binding token supplied by the request.

string

/^[0-9a-f]+$/

expected_deletion_seq

Deletion sequence the undelete expected to be active.

integer format: int64

<= 9007199254740991

expected_head_seq

The head sequence required by the request.

integer format: int64

<= 9007199254740991

expected_inode_id

The request expected the path to contain this inode.

string

/^ino_[1-9][0-9]*$/

Example

ino_123

expected_revision_no

Revision the request expected to be current.

integer format: int64

<= 9007199254740991

fenced_writer_epoch

Epoch the failing writer session held when it was displaced.

integer format: int64

<= 9007199254740991

inode_id

Inode the failed precondition or operation targeted.

string

/^ino_[1-9][0-9]*$/

Example

ino_123

max_writer_sessions

Maximum writer sessions admitted by the node.

integer

namespace_id

The deleted namespace that caused the operation to fail.

string

/^[a-z0-9][a-z0-9._-]{0,127}$/

Example

demo

operation_index

The index of the failed operation in the request.

integer format: int32

precondition_index

Zero-based position of the failed request precondition.

integer format: int32

retention_floor_seq

Oldest sequence still promised for incremental replay.

integer format: int64

<= 9007199254740991

feature

The capability feature key for a not_supported error.

string

message

required

Human-readable error message.

string

param

The invalid JSON Pointer, parameter name, CLI flag, or CLI argument.

string

request_id

The request correlation ID also sent in the x-request-id response header.

string

401

Unauthorized

HTTP error body used by LoonFS APIs.

object

code

required

The stable machine-readable error code as a string.

string

details

The optional machine-readable context for the error code.

object

active_acquired_at_ms

The Unix-millisecond time when the current writer acquired its epoch, when available.

integer format: int64

active_writer_epoch

Epoch that currently owns the namespace.

integer format: int64

<= 9007199254740991

active_writer_id

The writer ID recorded for the current epoch, when available.

string

actual_access_revision_no

Access revision that is actually current for the inode.

integer format: int64

<= 9007199254740991

actual_attributes_revision_no

Attribute revision that is actually current for the inode.

integer format: int64

<= 9007199254740991

actual_binding_version

Current binding token; absent for the root, which has no binding.

string

/^[0-9a-f]+$/

actual_deletion_seq

Deletion sequence actually active for the inode.

integer format: int64

<= 9007199254740991

actual_head_seq

The actual namespace head sequence.

integer format: int64

<= 9007199254740991

actual_inode_id

The path actually contained this inode.

string

/^ino_[1-9][0-9]*$/

Example

ino_123

actual_revision_no

Revision that is actually current; absent when the inode has none.

integer format: int64

<= 9007199254740991

after_seq

Change-feed cursor the request asked to resume after.

integer format: int64

<= 9007199254740991

commit_id

Idempotency key of the commit the error concerns.

string

/^[a-z0-9][a-z0-9._-]{0,127}$/

Example

c_f3a9c2d4b6e8417a90c5d2f8e1b7a6c0

committed_fingerprint

The fingerprint of the mutation that landed under commit_id, present with committed_seq.

string

committed_seq

The sequence where this commit ID already landed, when recorded by a durable receipt.

integer format: int64

<= 9007199254740991

expected_access_revision_no

Access revision the request expected to be current.

integer format: int64

<= 9007199254740991

expected_attributes_revision_no

Attribute revision the request expected to be current.

integer format: int64

<= 9007199254740991

expected_binding_version

Opaque binding token supplied by the request.

string

/^[0-9a-f]+$/

expected_deletion_seq

Deletion sequence the undelete expected to be active.

integer format: int64

<= 9007199254740991

expected_head_seq

The head sequence required by the request.

integer format: int64

<= 9007199254740991

expected_inode_id

The request expected the path to contain this inode.

string

/^ino_[1-9][0-9]*$/

Example

ino_123

expected_revision_no

Revision the request expected to be current.

integer format: int64

<= 9007199254740991

fenced_writer_epoch

Epoch the failing writer session held when it was displaced.

integer format: int64

<= 9007199254740991

inode_id

Inode the failed precondition or operation targeted.

string

/^ino_[1-9][0-9]*$/

Example

ino_123

max_writer_sessions

Maximum writer sessions admitted by the node.

integer

namespace_id

The deleted namespace that caused the operation to fail.

string

/^[a-z0-9][a-z0-9._-]{0,127}$/

Example

demo

operation_index

The index of the failed operation in the request.

integer format: int32

precondition_index

Zero-based position of the failed request precondition.

integer format: int32

retention_floor_seq

Oldest sequence still promised for incremental replay.

integer format: int64

<= 9007199254740991

feature

The capability feature key for a not_supported error.

string

message

required

Human-readable error message.

string

param

The invalid JSON Pointer, parameter name, CLI flag, or CLI argument.

string

request_id

The request correlation ID also sent in the x-request-id response header.

string

404

Namespace, visible inode, or snapshot not found

HTTP error body used by LoonFS APIs.

object

code

required

The stable machine-readable error code as a string.

string

details

The optional machine-readable context for the error code.

object

active_acquired_at_ms

The Unix-millisecond time when the current writer acquired its epoch, when available.

integer format: int64

active_writer_epoch

Epoch that currently owns the namespace.

integer format: int64

<= 9007199254740991

active_writer_id

The writer ID recorded for the current epoch, when available.

string

actual_access_revision_no

Access revision that is actually current for the inode.

integer format: int64

<= 9007199254740991

actual_attributes_revision_no

Attribute revision that is actually current for the inode.

integer format: int64

<= 9007199254740991

actual_binding_version

Current binding token; absent for the root, which has no binding.

string

/^[0-9a-f]+$/

actual_deletion_seq

Deletion sequence actually active for the inode.

integer format: int64

<= 9007199254740991

actual_head_seq

The actual namespace head sequence.

integer format: int64

<= 9007199254740991

actual_inode_id

The path actually contained this inode.

string

/^ino_[1-9][0-9]*$/

Example

ino_123

actual_revision_no

Revision that is actually current; absent when the inode has none.

integer format: int64

<= 9007199254740991

after_seq

Change-feed cursor the request asked to resume after.

integer format: int64

<= 9007199254740991

commit_id

Idempotency key of the commit the error concerns.

string

/^[a-z0-9][a-z0-9._-]{0,127}$/

Example

c_f3a9c2d4b6e8417a90c5d2f8e1b7a6c0

committed_fingerprint

The fingerprint of the mutation that landed under commit_id, present with committed_seq.

string

committed_seq

The sequence where this commit ID already landed, when recorded by a durable receipt.

integer format: int64

<= 9007199254740991

expected_access_revision_no

Access revision the request expected to be current.

integer format: int64

<= 9007199254740991

expected_attributes_revision_no

Attribute revision the request expected to be current.

integer format: int64

<= 9007199254740991

expected_binding_version

Opaque binding token supplied by the request.

string

/^[0-9a-f]+$/

expected_deletion_seq

Deletion sequence the undelete expected to be active.

integer format: int64

<= 9007199254740991

expected_head_seq

The head sequence required by the request.

integer format: int64

<= 9007199254740991

expected_inode_id

The request expected the path to contain this inode.

string

/^ino_[1-9][0-9]*$/

Example

ino_123

expected_revision_no

Revision the request expected to be current.

integer format: int64

<= 9007199254740991

fenced_writer_epoch

Epoch the failing writer session held when it was displaced.

integer format: int64

<= 9007199254740991

inode_id

Inode the failed precondition or operation targeted.

string

/^ino_[1-9][0-9]*$/

Example

ino_123

max_writer_sessions

Maximum writer sessions admitted by the node.

integer

namespace_id

The deleted namespace that caused the operation to fail.

string

/^[a-z0-9][a-z0-9._-]{0,127}$/

Example

demo

operation_index

The index of the failed operation in the request.

integer format: int32

precondition_index

Zero-based position of the failed request precondition.

integer format: int32

retention_floor_seq

Oldest sequence still promised for incremental replay.

integer format: int64

<= 9007199254740991

feature

The capability feature key for a not_supported error.

string

message

required

Human-readable error message.

string

param

The invalid JSON Pointer, parameter name, CLI flag, or CLI argument.

string

request_id

The request correlation ID also sent in the x-request-id response header.

string

410

Namespace deleted or snapshot deleted or expired

HTTP error body used by LoonFS APIs.

object

code

required

The stable machine-readable error code as a string.

string

details

The optional machine-readable context for the error code.

object

active_acquired_at_ms

The Unix-millisecond time when the current writer acquired its epoch, when available.

integer format: int64

active_writer_epoch

Epoch that currently owns the namespace.

integer format: int64

<= 9007199254740991

active_writer_id

The writer ID recorded for the current epoch, when available.

string

actual_access_revision_no

Access revision that is actually current for the inode.

integer format: int64

<= 9007199254740991

actual_attributes_revision_no

Attribute revision that is actually current for the inode.

integer format: int64

<= 9007199254740991

actual_binding_version

Current binding token; absent for the root, which has no binding.

string

/^[0-9a-f]+$/

actual_deletion_seq

Deletion sequence actually active for the inode.

integer format: int64

<= 9007199254740991

actual_head_seq

The actual namespace head sequence.

integer format: int64

<= 9007199254740991

actual_inode_id

The path actually contained this inode.

string

/^ino_[1-9][0-9]*$/

Example

ino_123

actual_revision_no

Revision that is actually current; absent when the inode has none.

integer format: int64

<= 9007199254740991

after_seq

Change-feed cursor the request asked to resume after.

integer format: int64

<= 9007199254740991

commit_id

Idempotency key of the commit the error concerns.

string

/^[a-z0-9][a-z0-9._-]{0,127}$/

Example

c_f3a9c2d4b6e8417a90c5d2f8e1b7a6c0

committed_fingerprint

The fingerprint of the mutation that landed under commit_id, present with committed_seq.

string

committed_seq

The sequence where this commit ID already landed, when recorded by a durable receipt.

integer format: int64

<= 9007199254740991

expected_access_revision_no

Access revision the request expected to be current.

integer format: int64

<= 9007199254740991

expected_attributes_revision_no

Attribute revision the request expected to be current.

integer format: int64

<= 9007199254740991

expected_binding_version

Opaque binding token supplied by the request.

string

/^[0-9a-f]+$/

expected_deletion_seq

Deletion sequence the undelete expected to be active.

integer format: int64

<= 9007199254740991

expected_head_seq

The head sequence required by the request.

integer format: int64

<= 9007199254740991

expected_inode_id

The request expected the path to contain this inode.

string

/^ino_[1-9][0-9]*$/

Example

ino_123

expected_revision_no

Revision the request expected to be current.

integer format: int64

<= 9007199254740991

fenced_writer_epoch

Epoch the failing writer session held when it was displaced.

integer format: int64

<= 9007199254740991

inode_id

Inode the failed precondition or operation targeted.

string

/^ino_[1-9][0-9]*$/

Example

ino_123

max_writer_sessions

Maximum writer sessions admitted by the node.

integer

namespace_id

The deleted namespace that caused the operation to fail.

string

/^[a-z0-9][a-z0-9._-]{0,127}$/

Example

demo

operation_index

The index of the failed operation in the request.

integer format: int32

precondition_index

Zero-based position of the failed request precondition.

integer format: int32

retention_floor_seq

Oldest sequence still promised for incremental replay.

integer format: int64

<= 9007199254740991

feature

The capability feature key for a not_supported error.

string

message

required

Human-readable error message.

string

param

The invalid JSON Pointer, parameter name, CLI flag, or CLI argument.

string

request_id

The request correlation ID also sent in the x-request-id response header.

string

503

The server cannot complete the request now. Inspect code to determine whether the cause is a deadline, shutdown, load, writer-session admission, required maintenance, or invalid storage credentials. A mutation may still complete after a deadline or lost acknowledgment, so determine its outcome before retrying.

HTTP error body used by LoonFS APIs.

object

code

required

The stable machine-readable error code as a string.

string

details

The optional machine-readable context for the error code.

object

active_acquired_at_ms

The Unix-millisecond time when the current writer acquired its epoch, when available.

integer format: int64

active_writer_epoch

Epoch that currently owns the namespace.

integer format: int64

<= 9007199254740991

active_writer_id

The writer ID recorded for the current epoch, when available.

string

actual_access_revision_no

Access revision that is actually current for the inode.

integer format: int64

<= 9007199254740991

actual_attributes_revision_no

Attribute revision that is actually current for the inode.

integer format: int64

<= 9007199254740991

actual_binding_version

Current binding token; absent for the root, which has no binding.

string

/^[0-9a-f]+$/

actual_deletion_seq

Deletion sequence actually active for the inode.

integer format: int64

<= 9007199254740991

actual_head_seq

The actual namespace head sequence.

integer format: int64

<= 9007199254740991

actual_inode_id

The path actually contained this inode.

string

/^ino_[1-9][0-9]*$/

Example

ino_123

actual_revision_no

Revision that is actually current; absent when the inode has none.

integer format: int64

<= 9007199254740991

after_seq

Change-feed cursor the request asked to resume after.

integer format: int64

<= 9007199254740991

commit_id

Idempotency key of the commit the error concerns.

string

/^[a-z0-9][a-z0-9._-]{0,127}$/

Example

c_f3a9c2d4b6e8417a90c5d2f8e1b7a6c0

committed_fingerprint

The fingerprint of the mutation that landed under commit_id, present with committed_seq.

string

committed_seq

The sequence where this commit ID already landed, when recorded by a durable receipt.

integer format: int64

<= 9007199254740991

expected_access_revision_no

Access revision the request expected to be current.

integer format: int64

<= 9007199254740991

expected_attributes_revision_no

Attribute revision the request expected to be current.

integer format: int64

<= 9007199254740991

expected_binding_version

Opaque binding token supplied by the request.

string

/^[0-9a-f]+$/

expected_deletion_seq

Deletion sequence the undelete expected to be active.

integer format: int64

<= 9007199254740991

expected_head_seq

The head sequence required by the request.

integer format: int64

<= 9007199254740991

expected_inode_id

The request expected the path to contain this inode.

string

/^ino_[1-9][0-9]*$/

Example

ino_123

expected_revision_no

Revision the request expected to be current.

integer format: int64

<= 9007199254740991

fenced_writer_epoch

Epoch the failing writer session held when it was displaced.

integer format: int64

<= 9007199254740991

inode_id

Inode the failed precondition or operation targeted.

string

/^ino_[1-9][0-9]*$/

Example

ino_123

max_writer_sessions

Maximum writer sessions admitted by the node.

integer

namespace_id

The deleted namespace that caused the operation to fail.

string

/^[a-z0-9][a-z0-9._-]{0,127}$/

Example

demo

operation_index

The index of the failed operation in the request.

integer format: int32

precondition_index

Zero-based position of the failed request precondition.

integer format: int32

retention_floor_seq

Oldest sequence still promised for incremental replay.

integer format: int64

<= 9007199254740991

feature

The capability feature key for a not_supported error.

string

message

required

Human-readable error message.

string

param

The invalid JSON Pointer, parameter name, CLI flag, or CLI argument.

string

request_id

The request correlation ID also sent in the x-request-id response header.

string