Get capabilities

Authorizations

bearer_auth

200

Capability document

The API groups, features, and limits advertised by a deployment.

object

api_groups

required

The advertised group/version API groups, each with every required operation implemented.

Array<string>

features

Named features and whether this deployment supports them. An absent key means unsupported. Known keys are listed below; deployments may advertise additional keys. The response example is illustrative, not a guarantee of support.

object

filesystem.namespaces.create

Create namespaces.

boolean

filesystem.namespaces.fork

Fork namespaces.

boolean

filesystem.namespaces.delete

Permanently delete and retire namespaces.

boolean

filesystem.snapshots

Create, list, extend, delete, and read from leased snapshots.

boolean

filesystem.commits.inline_content

Send small file contents directly in a commit.

boolean

filesystem.uploads.direct_put

Upload an object through one presigned request.

boolean

filesystem.uploads.direct_multipart

Upload an object through presigned multipart requests.

boolean

filesystem.downloads.direct_get

Download an object through a presigned request.

boolean

query.grep

Search file contents with grep.

boolean

key

additional properties

boolean

limits

Advisory numeric limits clients may use to pre-validate requests. Known keys are listed below; deployments may advertise additional keys. Values vary by deployment: use the returned values rather than assuming the illustrative response example is universal.

object

upload.service_proxied.max_content_bytes

Largest service-proxied upload body, in bytes.

integer format: int64

upload.direct_put.max_content_bytes

Largest object accepted through one presigned direct_put request, in bytes. Provider-dependent; advertised only when known.

integer format: int64

upload.complete.max_request_body_bytes

Largest upload-completion JSON body, in bytes.

integer format: int64

download.service_proxied.max_content_bytes

Largest service-proxied content read, in bytes.

integer format: int64

upload.service_proxied.max_concurrent_requests

Maximum concurrent proxied uploads.

integer format: int64

download.service_proxied.max_concurrent_requests

Maximum concurrent proxied content reads.

integer format: int64

snapshot.max_ttl_ms

Maximum snapshot TTL per creation or extension, in milliseconds.

integer format: int64

snapshot.max_lifetime_ms

Maximum snapshot lifetime from creation, in milliseconds.

integer format: int64

snapshot.max_live_per_namespace

Maximum live snapshots per namespace.

integer format: int64

commit.max_operations

Maximum filesystem operations per commit.

integer format: int64

commit.max_preconditions

Maximum request-level preconditions per commit.

integer format: int64

commit.max_inline_content_bytes_per_operation

Maximum decoded bytes per inline file value.

integer format: int64

commit.max_content_tokens

Maximum content-preparation tokens per commit.

integer format: int64

commit.max_external_content_refs

Maximum distinct external content references per commit.

integer format: int64

commit.max_message_bytes

Maximum commit message size in UTF-8 bytes.

integer format: int64

access.max_principals_per_request

Maximum principal IDs in one request’s subject context.

integer format: int64

maintenance.gc.min_grace_window_ms

Minimum garbage-collection grace window, in milliseconds.

integer format: int64

pagination.default_limit

Page size used when a standard paged request omits limit.

integer format: int64

pagination.max_limit

Maximum standard page size.

integer format: int64

query.grep.default_limit

Grep match limit when omitted. Advertised when grep is supported.

integer format: int64

query.grep.max_limit

Maximum grep match limit. Advertised when grep is supported.

integer format: int64

query.grep.scan_budget_files

Maximum files scanned by a plan-less allow_scan query. Advertised when grep is supported.

integer format: int64

query.grep.tail_budget_files

Maximum unindexed revisions scanned before reporting index lag. Advertised when grep is supported.

integer format: int64

key

additional properties

integer format: int64

protocol_version

required

The protocol version, v0.

string

Example

{
  "protocol_version": "v0",
  "api_groups": [
    "filesystem/v0",
    "query/v0"
  ],
  "features": {
    "filesystem.namespaces.create": true,
    "filesystem.namespaces.fork": true,
    "filesystem.namespaces.delete": true,
    "filesystem.snapshots": true,
    "filesystem.commits.inline_content": true,
    "filesystem.uploads.direct_put": true,
    "filesystem.uploads.direct_multipart": true,
    "filesystem.downloads.direct_get": true,
    "query.grep": true
  },
  "limits": {
    "upload.service_proxied.max_content_bytes": 268435456,
    "upload.direct_put.max_content_bytes": 5368709120,
    "upload.complete.max_request_body_bytes": 8388608,
    "download.service_proxied.max_content_bytes": 268435456,
    "upload.service_proxied.max_concurrent_requests": 8,
    "download.service_proxied.max_concurrent_requests": 16,
    "snapshot.max_ttl_ms": 86400000,
    "snapshot.max_lifetime_ms": 604800000,
    "snapshot.max_live_per_namespace": 16,
    "commit.max_operations": 4096,
    "commit.max_preconditions": 1024,
    "commit.max_inline_content_bytes_per_operation": 65536,
    "commit.max_content_tokens": 4096,
    "commit.max_external_content_refs": 4096,
    "commit.max_message_bytes": 4096,
    "access.max_principals_per_request": 64,
    "maintenance.gc.min_grace_window_ms": 1335000,
    "pagination.default_limit": 1000,
    "pagination.max_limit": 1000,
    "query.grep.default_limit": 1000,
    "query.grep.max_limit": 1000,
    "query.grep.scan_budget_files": 4096,
    "query.grep.tail_budget_files": 512
  }
}

400

Unknown query parameter

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

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

Get capabilities

Authorizations

Responses

200

Example

400

Example

Example

Example

Example

Example

401

Example

Example

Example

Example

Example

503

Example

Example

Example

Example

Example