Apply a commit
Applies one commit: an ordered, non-empty list of path operations that commit together as one logical commit, under one commit id that makes retries idempotent. A single-operation call is the one-element case. The first operation that fails aborts the whole request and names its position in details.operation_index.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Namespace id
Request Body required
Section titled “Request Body required ”One commit: an idempotency key, an optional annotation, and an ordered list of path operations that commit together (API spec, section 5.1).
A one-operation request is the one-element case of this shape, not a different request: a convenience call and a batch produce the same commit and the same fingerprint.
object
Caller-supplied idempotency key for the whole request.
Proofs for any new external content refs introduced by this request. One proof covers every operation that names its content ref.
Stateless proof that a LoonFS server already validated a content ref.
object
Content identity the server attests it already verified.
object
Immutable identity of the referenced object.
Content strategy used by the referenced object.
Complete byte length of the referenced content.
Mandatory checksum over the complete object, used to verify the stored bytes against this reference without downloading them.
object
Algorithm that produced value.
Lowercase hex of the raw checksum bytes.
The algorithm is its own field, so the value carries no prefix. Provider APIs that report base64 are converted at the adapter.
SHA-256 over the complete payload, lowercase hex, when a trusted party computed it.
Present means the LoonFS write path hashed the whole stream itself, or a provider validated a signed whole-object SHA-256 on the write. There are no client-claimed digests: absent means nobody trustworthy hashed these bytes, never “the client did not tell us”.
Opaque, server-signed token. Clients must not parse it.
Caller annotation recorded on the commit and reported by the change
feed. Part of the commit’s identity: reusing commit_id with a
different message is a commit_id_reuse_conflict, exactly as it is
for an explicit commit.
Ordered operations to apply. Must be non-empty; they commit all together or not at all.
Create one directory.
object
Also create missing ancestor directories (the same auto-create
put_file performs). The final component must still be new.
Absolute destination path, rejected when invalid or already bound.
Create or replace one file with an already-durable content ref.
object
Whether an existing file may receive a new revision instead of causing a conflict.
Immutable bytes that must be covered by a valid preparation proof.
object
Immutable identity of the referenced object.
Content strategy used by the referenced object.
Complete byte length of the referenced content.
Mandatory checksum over the complete object, used to verify the stored bytes against this reference without downloading them.
object
Algorithm that produced value.
Lowercase hex of the raw checksum bytes.
The algorithm is its own field, so the value carries no prefix. Provider APIs that report base64 are converted at the adapter.
SHA-256 over the complete payload, lowercase hex, when a trusted party computed it.
Present means the LoonFS write path hashed the whole stream itself, or a provider validated a signed whole-object SHA-256 on the write. There are no client-claimed digests: absent means nobody trustworthy hashed these bytes, never “the client did not tell us”.
Absolute destination path; missing ancestors are created automatically.
Delete one path.
object
Whether a non-empty directory may be tombstoned recursively.
Absolute path that must resolve to a visible inode.
Move one path to another path.
object
Whether an existing destination file may be replaced.
Absolute source path that must resolve to a visible inode.
Absolute destination whose parent must be visible and writable.
Copy one file path to another path.
object
Whether an existing destination file may receive a copied revision.
Absolute source path that must resolve to a visible file.
Absolute destination whose parent must be visible and writable.
Recover a deleted file or subtree: revoke the deletion of
inode_id recorded at deleted_at_seq (both reported by the
delete and by the change feed) and re-bind it at path. Answers
not_deleted when that generation is not the live one, so a stale
request never cancels a later delete.
object
Observed deletion sequence, which prevents cancelling a newer tombstone generation.
Deleted inode to make reachable again.
Absolute destination path whose parent must be visible and whose name must be absent.
Restore an older revision as the current revision for a path.
object
Absolute path that must resolve to a visible file.
Existing historical revision whose content will be copied into a new current revision.
Responses
Section titled “ Responses ”Commit applied
Result of one commit.
Every commit resolves to this envelope — path-oriented operations and explicit commits, embedded or remote. The commit id is the caller’s reconciliation handle: resubmitting the same request with the same id replays this result instead of committing twice.
object
Idempotency key the commit landed under: caller-supplied, or generated on the caller’s behalf when the request carried none.
Sequence number where the commit became visible.
Namespace that changed.
Invalid commit
HTTP error body used by LoonFS APIs.
object
Stable machine-readable reason from the ErrorCode
registry.
Carried as a string so clients keep working when a newer server
introduces a code they do not know; use
ErrorCode::parse for typed access.
Structured context for the code, present when the failure carries machine-usable identity (API spec, “Standard error contract”). Boxed so the rare detailed error does not widen every error-carrying result.
object
Unix milliseconds at which the current epoch’s acquirer took it, when the head recorded one. Writer ids are process labels, so two runs on one machine can share one; the stamp is what tells them apart.
Writer id recorded by the current epoch’s acquirer, when the head recorded one.
Sequence at which that commit id already landed. Present when the failure was decided against a durable commit receipt, which is what holds the sequence; absent when nothing has committed under the id yet and two live requests are simply claiming it at once.
Position, in the request’s operation list, of the operation that failed. A commit applies all of its operations or none of them, so this names the one that stopped the whole request.
For not_supported errors, the capability-document feature key the
client should reconcile against.
Human-readable error message.
Correlation id the server assigned to the failed request; the same
value is sent as the x-request-id response header.
Unauthorized
HTTP error body used by LoonFS APIs.
object
Stable machine-readable reason from the ErrorCode
registry.
Carried as a string so clients keep working when a newer server
introduces a code they do not know; use
ErrorCode::parse for typed access.
Structured context for the code, present when the failure carries machine-usable identity (API spec, “Standard error contract”). Boxed so the rare detailed error does not widen every error-carrying result.
object
Unix milliseconds at which the current epoch’s acquirer took it, when the head recorded one. Writer ids are process labels, so two runs on one machine can share one; the stamp is what tells them apart.
Writer id recorded by the current epoch’s acquirer, when the head recorded one.
Sequence at which that commit id already landed. Present when the failure was decided against a durable commit receipt, which is what holds the sequence; absent when nothing has committed under the id yet and two live requests are simply claiming it at once.
Position, in the request’s operation list, of the operation that failed. A commit applies all of its operations or none of them, so this names the one that stopped the whole request.
For not_supported errors, the capability-document feature key the
client should reconcile against.
Human-readable error message.
Correlation id the server assigned to the failed request; the same
value is sent as the x-request-id response header.
Namespace or path not found
HTTP error body used by LoonFS APIs.
object
Stable machine-readable reason from the ErrorCode
registry.
Carried as a string so clients keep working when a newer server
introduces a code they do not know; use
ErrorCode::parse for typed access.
Structured context for the code, present when the failure carries machine-usable identity (API spec, “Standard error contract”). Boxed so the rare detailed error does not widen every error-carrying result.
object
Unix milliseconds at which the current epoch’s acquirer took it, when the head recorded one. Writer ids are process labels, so two runs on one machine can share one; the stamp is what tells them apart.
Writer id recorded by the current epoch’s acquirer, when the head recorded one.
Sequence at which that commit id already landed. Present when the failure was decided against a durable commit receipt, which is what holds the sequence; absent when nothing has committed under the id yet and two live requests are simply claiming it at once.
Position, in the request’s operation list, of the operation that failed. A commit applies all of its operations or none of them, so this names the one that stopped the whole request.
For not_supported errors, the capability-document feature key the
client should reconcile against.
Human-readable error message.
Correlation id the server assigned to the failed request; the same
value is sent as the x-request-id response header.
Operation conflict
HTTP error body used by LoonFS APIs.
object
Stable machine-readable reason from the ErrorCode
registry.
Carried as a string so clients keep working when a newer server
introduces a code they do not know; use
ErrorCode::parse for typed access.
Structured context for the code, present when the failure carries machine-usable identity (API spec, “Standard error contract”). Boxed so the rare detailed error does not widen every error-carrying result.
object
Unix milliseconds at which the current epoch’s acquirer took it, when the head recorded one. Writer ids are process labels, so two runs on one machine can share one; the stamp is what tells them apart.
Writer id recorded by the current epoch’s acquirer, when the head recorded one.
Sequence at which that commit id already landed. Present when the failure was decided against a durable commit receipt, which is what holds the sequence; absent when nothing has committed under the id yet and two live requests are simply claiming it at once.
Position, in the request’s operation list, of the operation that failed. A commit applies all of its operations or none of them, so this names the one that stopped the whole request.
For not_supported errors, the capability-document feature key the
client should reconcile against.
Human-readable error message.
Correlation id the server assigned to the failed request; the same
value is sent as the x-request-id response header.
Namespace deleted
HTTP error body used by LoonFS APIs.
object
Stable machine-readable reason from the ErrorCode
registry.
Carried as a string so clients keep working when a newer server
introduces a code they do not know; use
ErrorCode::parse for typed access.
Structured context for the code, present when the failure carries machine-usable identity (API spec, “Standard error contract”). Boxed so the rare detailed error does not widen every error-carrying result.
object
Unix milliseconds at which the current epoch’s acquirer took it, when the head recorded one. Writer ids are process labels, so two runs on one machine can share one; the stamp is what tells them apart.
Writer id recorded by the current epoch’s acquirer, when the head recorded one.
Sequence at which that commit id already landed. Present when the failure was decided against a durable commit receipt, which is what holds the sequence; absent when nothing has committed under the id yet and two live requests are simply claiming it at once.
Position, in the request’s operation list, of the operation that failed. A commit applies all of its operations or none of them, so this names the one that stopped the whole request.
For not_supported errors, the capability-document feature key the
client should reconcile against.
Human-readable error message.
Correlation id the server assigned to the failed request; the same
value is sent as the x-request-id response header.
Commit unavailable
HTTP error body used by LoonFS APIs.
object
Stable machine-readable reason from the ErrorCode
registry.
Carried as a string so clients keep working when a newer server
introduces a code they do not know; use
ErrorCode::parse for typed access.
Structured context for the code, present when the failure carries machine-usable identity (API spec, “Standard error contract”). Boxed so the rare detailed error does not widen every error-carrying result.
object
Unix milliseconds at which the current epoch’s acquirer took it, when the head recorded one. Writer ids are process labels, so two runs on one machine can share one; the stamp is what tells them apart.
Writer id recorded by the current epoch’s acquirer, when the head recorded one.
Sequence at which that commit id already landed. Present when the failure was decided against a durable commit receipt, which is what holds the sequence; absent when nothing has committed under the id yet and two live requests are simply claiming it at once.
Position, in the request’s operation list, of the operation that failed. A commit applies all of its operations or none of them, so this names the one that stopped the whole request.
For not_supported errors, the capability-document feature key the
client should reconcile against.
Human-readable error message.
Correlation id the server assigned to the failed request; the same
value is sent as the x-request-id response header.