SDKs
Install a client, run the first-file example, then browse the methods by task. Signatures, parameters, return values and call examples are included below.
Install and configure
Edition 2024 · blocking HTTP client. Install the supplied 0.2.0 release artifact:
# Extract the supplied crate into your project, then add to Cargo.toml:
[dependencies]
nufs-sdk = { path = "vendor/nufs-sdk-0.2.0" }Create a drive-scoped access key in your drive. Use its REST bearer token, your API origin without /v1, and the drive ID for the example.
export NUFS_ENDPOINT='https://api.example.test'
export NUFS_TOKEN='REPLACE_WITH_REST_BEARER'
export NUFS_DRIVE_ID='REPLACE_WITH_DRIVE_ID'Create, update and read a file
This example creates a new file, saves its contents, edits the first byte with a version guard and reads the saved contents.
use nufs_sdk::Client;
use std::{env, time::{SystemTime, UNIX_EPOCH}};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let endpoint = env::var("NUFS_ENDPOINT")?;
let token = env::var("NUFS_TOKEN")?;
let drive = env::var("NUFS_DRIVE_ID")?;
let client = Client::new(&endpoint, &token)?;
let stamp = SystemTime::now().duration_since(UNIX_EPOCH)?.as_nanos();
let file = client.create_entry(&drive, &format!("notes-{stamp}.txt"), "file", None)?;
let first = client.write_file(&file.id, b"hello", None, None)?;
let saved = client.write_at(&file.id, 0, b"H", Some(&first.version.id), None)?;
let original = client.read_version_range(&file.id, &saved.version.id, 0, 5)?;
println!("{}", String::from_utf8(original)?); // Hello
Ok(())
}Method reference
73 Rust methods, grouped by task.
Connect and authenticate
newConstruct an authorized client for a nuFS endpoint.+
pub fn new(endpoint: impl Into<String>, credential: impl Into<String>) -> Result<Self, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
endpoint | impl Into<String> | API origin without /v1; HTTPS outside local development. |
credential | impl Into<String> | Credential for this operation. Use interactive, machine or recipient authority as applicable; keep it private. |
Returns
Result<Self, Error>Call example
nufs_sdk::Client::new(endpoint, credential)with_http_clientConstruct a client with a caller-supplied HTTP transport.+
pub fn with_http_client(endpoint: impl Into<String>, credential: impl Into<String>, http: HttpClient) -> SelfParameters
| Name | Type / default | Meaning |
|---|---|---|
endpoint | impl Into<String> | API origin without /v1; HTTPS outside local development. |
credential | impl Into<String> | Credential for this operation. Use interactive, machine or recipient authority as applicable; keep it private. |
http | HttpClient | Caller-supplied HTTP transport of the declared type. |
Returns
SelfCall example
nufs_sdk::Client::with_http_client(endpoint, credential, http)refreshRotate a refresh token+
pub fn refresh(endpoint: &str, refresh_token: &str) -> Result<RefreshedSession, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
endpoint | &str | API origin without /v1; HTTPS outside local development. |
refresh_token | &str | Credential for this operation. Use interactive, machine or recipient authority as applicable; keep it private. |
Returns
Result<RefreshedSession, Error>Call example
nufs_sdk::Client::refresh(endpoint, refresh_token)Input and result fields
{
"type": "object",
"required": [
"access_token",
"access_expires_at",
"refresh_token",
"refresh_expires_at"
],
"properties": {
"access_token": {
"type": "string",
"minLength": 1
},
"access_expires_at": {
"type": "string",
"format": "date-time"
},
"refresh_token": {
"type": "string",
"minLength": 1
},
"refresh_expires_at": {
"type": "string",
"format": "date-time"
}
}
}HTTP requests
POST /auth/refresh
Rotate a refresh token
{
"id": "post-auth-refresh",
"path": "/auth/refresh",
"method": "POST",
"summary": "Rotate a refresh token",
"security": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"refresh_token"
],
"properties": {
"refresh_token": {
"type": "string",
"minLength": 1
}
}
}
}
}
},
"responses": {
"200": {
"description": "Rotated session",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RefreshedSession"
}
}
}
},
"401": {
"description": "invalid_session",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"500": {
"description": "Session rotation or reuse revocation could not be committed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
}logoutLogout.+
pub fn logout() -> Result<(), Error>Parameters
No explicit arguments.
Returns
Result<(), Error>Call example
client.logout()HTTP requests
POST /auth/logout
{
"id": "post-auth-logout",
"path": "/auth/logout",
"method": "POST",
"security": [
{
"bearer": []
}
],
"responses": {
"204": {
"description": "Current interactive session revoked"
},
"401": {
"description": "Interactive session required; machine keys return unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"500": {
"description": "Session revocation could not be committed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
}register_deviceRegister device.+
pub fn register_device(name: &str, platform: &str) -> Result<Value, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
name | &str | Name or label accepted by this operation; it must meet server constraints. |
platform | &str | Device or client platform label. |
Returns
Result<Value, Error>Call example
client.register_device(name, platform)HTTP requests
POST /devices
{
"id": "post-devices",
"path": "/devices",
"method": "POST",
"security": [
{
"bearer": []
}
],
"responses": {
"201": {
"description": "Device registered"
}
}
}create_access_keyCreate a machine credential; its secret is returned exactly once+
pub fn create_access_key(label: &str, access: &str, scope_type: &str, scope_id: Option<&str>, expires_at: Option<&str>) -> Result<AccessKeyResult, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
label | &str | Name or label accepted by this operation; it must meet server constraints. |
access | &str | Requested authority within the caller’s current permitted scope. |
scope_type | &str | Account/drive/drive scope as accepted by this credential operation. |
scope_id | Option<&str> | Account/drive/drive scope as accepted by this credential operation. |
expires_at | Option<&str> | Expiry in the declared timestamp format; server policy bounds the grant. |
Returns
Result<AccessKeyResult, Error>Call example
client.create_access_key(label, access, scope_type, scope_id, expires_at)HTTP requests
POST /access-keys
Create a machine credential; its secret is returned exactly once
{
"id": "post-access-keys",
"path": "/access-keys",
"method": "POST",
"summary": "Create a machine credential; its secret is returned exactly once",
"security": [
{
"bearer": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"label",
"access"
],
"properties": {
"label": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"access": {
"enum": [
"read",
"write",
"admin"
]
},
"scope_type": {
"enum": [
"account",
"drive"
],
"default": "account"
},
"scope_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"expires_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Access key, one-time bearer secret, and separate S3 access-key ID/signing secret"
},
"401": {
"description": "Interactive session required"
}
}
}access_keysList active machine credentials+
pub fn access_keys() -> Result<Vec<Value>, Error>Parameters
No explicit arguments.
Returns
Result<Vec<Value>, Error>Call example
client.access_keys()HTTP requests
GET /access-keys
List active machine credentials
{
"id": "get-access-keys",
"path": "/access-keys",
"method": "GET",
"summary": "List active machine credentials",
"security": [
{
"bearer": []
}
],
"responses": {
"200": {
"description": "Active access keys"
},
"401": {
"description": "Interactive session required"
}
}
}revoke_access_keyRevoke a machine credential+
pub fn revoke_access_key(id: &str) -> Result<(), Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
id | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
Returns
Result<(), Error>Call example
client.revoke_access_key(id)HTTP requests
DELETE /access-keys/{key}
Revoke a machine credential
{
"id": "delete-access-keys-key",
"path": "/access-keys/{key}",
"method": "DELETE",
"summary": "Revoke a machine credential",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "key",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Revoked"
},
"404": {
"description": "Access key not found"
}
}
}mount_credentialsIssue a short-lived read or write credential for one drive+
pub fn mount_credentials(drive: &str, access: &str) -> Result<Value, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
access | &str | Requested authority within the caller’s current permitted scope. |
Returns
Result<Value, Error>Call example
client.mount_credentials(drive, access)HTTP requests
POST /drives/{drive}/mount-credentials
Issue a short-lived read or write credential for one drive
{
"id": "post-drives-drive-mount-credentials",
"path": "/drives/{drive}/mount-credentials",
"method": "POST",
"summary": "Issue a short-lived read or write credential for one drive",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "drive",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"access": {
"type": "string",
"enum": [
"read",
"write"
],
"default": "write"
},
"ttl_seconds": {
"type": "integer",
"minimum": 60,
"maximum": 86400,
"default": 3600
}
}
}
}
}
},
"responses": {
"201": {
"description": "Temporary credential and one-time secret"
},
"403": {
"description": "Authority cannot be delegated"
}
}
}mount_credentials_with_ttlIssue a short-lived read or write credential for one drive+
pub fn mount_credentials_with_ttl(drive: &str, access: &str, ttl_seconds: i64) -> Result<Value, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
access | &str | Requested authority within the caller’s current permitted scope. |
ttl_seconds | i64 | Requested lifetime in seconds, bounded by current grant policy. |
Returns
Result<Value, Error>Call example
client.mount_credentials_with_ttl(drive, access, ttl_seconds)HTTP requests
POST /drives/{drive}/mount-credentials
Issue a short-lived read or write credential for one drive
{
"id": "post-drives-drive-mount-credentials",
"path": "/drives/{drive}/mount-credentials",
"method": "POST",
"summary": "Issue a short-lived read or write credential for one drive",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "drive",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"access": {
"type": "string",
"enum": [
"read",
"write"
],
"default": "write"
},
"ttl_seconds": {
"type": "integer",
"minimum": 60,
"maximum": 86400,
"default": 3600
}
}
}
}
}
},
"responses": {
"201": {
"description": "Temporary credential and one-time secret"
},
"403": {
"description": "Authority cannot be delegated"
}
}
}revoke_mount_credentialRevoke an owned temporary credential; scoped parents can revoke only their own direct children+
pub fn revoke_mount_credential(drive: &str, id: &str) -> Result<(), Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
id | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
Returns
Result<(), Error>Call example
client.revoke_mount_credential(drive, id)HTTP requests
DELETE /drives/{drive}/mount-credentials/{credential}
Revoke an owned temporary credential; scoped parents can revoke only their own direct children
{
"id": "delete-drives-drive-mount-credentials-credential",
"path": "/drives/{drive}/mount-credentials/{credential}",
"method": "DELETE",
"summary": "Revoke an owned temporary credential; scoped parents can revoke only their own direct children",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "drive",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "credential",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Revoked, including repeated delivery"
},
"403": {
"description": "A mount credential cannot manage credentials"
},
"404": {
"description": "Credential not found or not owned by this parent"
}
}
}Find and read files
search_filesSearch live names and bounded UTF-8 file text within one accessible drive+
pub fn search_files(drive: &str, query: &str, limit: u16, cursor: Option<&str>) -> Result<SearchPage, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
query | &str | Literal search text, encoded as request data. |
limit | u16 | Bounded page size; endpoint-specific limits apply. |
cursor | Option<&str> | Opaque cursor returned by this same operation and scope. Omit for the first page. |
Returns
Result<SearchPage, Error>Call example
client.search_files(drive, query, limit, cursor)Input and result fields
{
"type": "object",
"required": [
"results",
"next_cursor"
],
"properties": {
"results": {
"type": "array",
"maxItems": 100,
"items": {
"$ref": "#/components/schemas/SearchHit"
}
},
"next_cursor": {
"type": [
"string",
"null"
]
}
}
}HTTP requests
GET /drives/{drive}/search
All query words must match. Results use file-ID order and live pagination. Names update transactionally; content extraction is asynchronous and restricted to 256 KiB UTF-8 text without binary control characters. Current drive permissions and live ancestors are checked on every page. Old content is hidden immediately after a version change. Unsupported content remains searchable by name. No external model or service receives queries or content.
{
"id": "get-drives-drive-search",
"path": "/drives/{drive}/search",
"method": "GET",
"summary": "Search live names and bounded UTF-8 file text within one accessible drive",
"description": "All query words must match. Results use file-ID order and live pagination. Names update transactionally; content extraction is asynchronous and restricted to 256 KiB UTF-8 text without binary control characters. Current drive permissions and live ancestors are checked on every page. Old content is hidden immediately after a version change. Unsupported content remains searchable by name. No external model or service receives queries or content.",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"in": "path",
"name": "drive",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"in": "query",
"name": "q",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"description": "Query is limited to 256 UTF-8 bytes"
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
}
},
{
"in": "query",
"name": "cursor",
"schema": {
"type": "string",
"maxLength": 512
},
"description": "Continuation bound to this drive and query"
}
],
"responses": {
"200": {
"description": "Permission-filtered live results",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchPage"
}
}
}
},
"400": {
"description": "Invalid query or cursor"
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Credential scope denied"
},
"404": {
"description": "Drive unavailable"
},
"500": {
"description": "Search unavailable"
}
}
}entriesEntries.+
pub fn entries(drive: &str, parent: Option<&str>) -> Result<Vec<Entry>, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
parent | Option<&str> | Parent folder identity, or the language’s absent value for the drive root. |
Returns
Result<Vec<Entry>, Error>Call example
client.entries(drive, parent)Input and result fields
{
"type": "object",
"required": [
"id",
"drive_id",
"name",
"kind",
"logical_size",
"revision",
"created_at",
"modified_at",
"deleted"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"drive_id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"name": {
"type": "string"
},
"kind": {
"enum": [
"file",
"folder"
]
},
"current_version_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"logical_size": {
"type": "integer",
"format": "int64"
},
"checksum_sha256": {
"type": [
"string",
"null"
]
},
"revision": {
"type": "integer",
"format": "int64"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"modified_at": {
"type": "string",
"format": "date-time"
},
"deleted": {
"type": "boolean"
}
}
}HTTP requests
GET /drives/{drive}/entries
{
"id": "get-drives-drive-entries",
"path": "/drives/{drive}/entries",
"method": "GET",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "parent_id",
"in": "query",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "as_of",
"in": "query",
"description": "Committed drive sequence to resolve under current permissions; this read does not pin history",
"schema": {
"type": "integer",
"format": "int64",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Directory entries"
},
"410": {
"description": "history_expired — a visible historical file version required by this listing was reclaimed"
}
}
}entryEntry.+
pub fn entry(id: &str) -> Result<Entry, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
id | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
Returns
Result<Entry, Error>Call example
client.entry(id)Input and result fields
{
"type": "object",
"required": [
"id",
"drive_id",
"name",
"kind",
"logical_size",
"revision",
"created_at",
"modified_at",
"deleted"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"drive_id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"name": {
"type": "string"
},
"kind": {
"enum": [
"file",
"folder"
]
},
"current_version_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"logical_size": {
"type": "integer",
"format": "int64"
},
"checksum_sha256": {
"type": [
"string",
"null"
]
},
"revision": {
"type": "integer",
"format": "int64"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"modified_at": {
"type": "string",
"format": "date-time"
},
"deleted": {
"type": "boolean"
}
}
}HTTP requests
GET /entries/{entry}
{
"id": "get-entries-entry",
"path": "/entries/{entry}",
"method": "GET",
"security": [
{
"bearer": []
}
],
"responses": {
"200": {
"description": "Entry metadata"
}
}
}create_entryCreate entry.+
pub fn create_entry(drive: &str, name: &str, kind: &str, parent: Option<&str>) -> Result<Entry, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
name | &str | Name or label accepted by this operation; it must meet server constraints. |
kind | &str | Entry kind: file or folder. |
parent | Option<&str> | Parent folder identity, or the language’s absent value for the drive root. |
Returns
Result<Entry, Error>Call example
client.create_entry(drive, name, kind, parent)Input and result fields
{
"type": "object",
"required": [
"id",
"drive_id",
"name",
"kind",
"logical_size",
"revision",
"created_at",
"modified_at",
"deleted"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"drive_id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"name": {
"type": "string"
},
"kind": {
"enum": [
"file",
"folder"
]
},
"current_version_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"logical_size": {
"type": "integer",
"format": "int64"
},
"checksum_sha256": {
"type": [
"string",
"null"
]
},
"revision": {
"type": "integer",
"format": "int64"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"modified_at": {
"type": "string",
"format": "date-time"
},
"deleted": {
"type": "boolean"
}
}
}HTTP requests
POST /drives/{drive}/entries
{
"id": "post-drives-drive-entries",
"path": "/drives/{drive}/entries",
"method": "POST",
"security": [
{
"bearer": []
}
],
"responses": {
"201": {
"description": "Entry created"
},
"409": {
"description": "Name conflict"
}
}
}rename_entryRename entry.+
pub fn rename_entry(id: &str, name: &str, revision: i64, parent: Option<&str>, replace: bool) -> Result<Entry, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
id | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
name | &str | Name or label accepted by this operation; it must meet server constraints. |
revision | i64 | Reviewed entry or policy revision. Do not substitute a file version ID. |
parent | Option<&str> | Parent folder identity, or the language’s absent value for the drive root. |
replace | bool | Explicit namespace replacement behavior for the reviewed rename/move operation. |
Returns
Result<Entry, Error>Call example
client.rename_entry(id, name, revision, parent, replace)Input and result fields
{
"type": "object",
"required": [
"id",
"drive_id",
"name",
"kind",
"logical_size",
"revision",
"created_at",
"modified_at",
"deleted"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"drive_id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"name": {
"type": "string"
},
"kind": {
"enum": [
"file",
"folder"
]
},
"current_version_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"logical_size": {
"type": "integer",
"format": "int64"
},
"checksum_sha256": {
"type": [
"string",
"null"
]
},
"revision": {
"type": "integer",
"format": "int64"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"modified_at": {
"type": "string",
"format": "date-time"
},
"deleted": {
"type": "boolean"
}
}
}HTTP requests
PATCH /entries/{entry}
{
"id": "patch-entries-entry",
"path": "/entries/{entry}",
"method": "PATCH",
"security": [
{
"bearer": []
}
],
"responses": {
"200": {
"description": "Renamed or moved"
},
"409": {
"description": "Revision conflict"
}
}
}delete_entryDelete entry.+
pub fn delete_entry(id: &str, revision: i64) -> Result<(), Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
id | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
revision | i64 | Reviewed entry or policy revision. Do not substitute a file version ID. |
Returns
Result<(), Error>Call example
client.delete_entry(id, revision)HTTP requests
DELETE /entries/{entry}
{
"id": "delete-entries-entry",
"path": "/entries/{entry}",
"method": "DELETE",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "expected_revision",
"in": "query",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"204": {
"description": "Tombstoned"
},
"409": {
"description": "Revision conflict"
}
}
}read_rangeRead a selected part of the current file+
Use this for a header, record or bounded preview. Specify a byte offset and length. If the result must stay tied to a saved input despite later edits, use a version-specific read instead.
pub fn read_range(file: &str, offset: i64, length: i64) -> Result<Vec<u8>, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
file | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
offset | i64 | Non-negative byte offset, not a character offset. |
length | i64 | Byte count or logical byte size; non-negative and bounded by the operation. |
Returns
Result<Vec<u8>, Error>Call example
client.read_range(file, offset, length)HTTP requests
GET /files/{file}/bytes
Stream current file bytes, optionally as one HTTP byte range
{
"id": "get-files-file-bytes",
"path": "/files/{file}/bytes",
"method": "GET",
"summary": "Stream current file bytes, optionally as one HTTP byte range",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "Range",
"in": "header",
"schema": {
"type": "string",
"example": "bytes=0-1023"
}
}
],
"responses": {
"200": {
"description": "Full content"
},
"206": {
"description": "Exact requested range"
},
"416": {
"description": "Unsatisfiable range"
}
}
}HEAD /files/{file}/bytes
Read current logical size and version headers without content
{
"id": "head-files-file-bytes",
"path": "/files/{file}/bytes",
"method": "HEAD",
"summary": "Read current logical size and version headers without content",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "File metadata headers"
}
}
}PUT /files/{file}/bytes
Uploads up to 100 MiB in bounded server chunks. Retry the same body and identity after interruption. A new file entry may remain empty until content commits.
{
"id": "put-files-file-bytes",
"path": "/files/{file}/bytes",
"method": "PUT",
"summary": "Atomically replace file bytes with bounded binary ingestion",
"description": "Uploads up to 100 MiB in bounded server chunks. Retry the same body and identity after interruption. A new file entry may remain empty until content commits.",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
{
"name": "X-Content-SHA256",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"responses": {
"200": {
"description": "Exactly one committed version or its replay",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MutationResult"
}
}
}
},
"400": {
"description": "Invalid size or checksum or incomplete body"
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Credential scope or access denied"
},
"404": {
"description": "File or write permission unavailable"
},
"409": {
"description": "Idempotency identity conflict"
},
"412": {
"description": "Base version changed"
},
"428": {
"description": "Version precondition required"
},
"503": {
"description": "Content storage unavailable"
},
"507": {
"description": "Quota exhausted"
}
}
}browser_downloadIssue a file/version-scoped HttpOnly download cookie for the current session+
pub fn browser_download(file: &str, version: &str) -> Result<BrowserDownloadGrant, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
file | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
version | &str | Selected immutable version identity for this read, restore or sharing operation. |
Returns
Result<BrowserDownloadGrant, Error>Call example
client.browser_download(file, version)Input and result fields
{
"type": "object",
"required": [
"download_path",
"expires_at"
],
"additionalProperties": false,
"properties": {
"download_path": {
"type": "string",
"pattern": "^/v1/files/[0-9a-f-]{36}/versions/[0-9a-f-]{36}/browser-download$"
},
"expires_at": {
"type": "string",
"format": "date-time"
}
}
}HTTP requests
POST /files/{file}/versions/{version}/browser-download
Issue a file/version-scoped HttpOnly download cookie for the current session
{
"id": "post-files-file-versions-version-browser-download",
"path": "/files/{file}/versions/{version}/browser-download",
"method": "POST",
"summary": "Issue a file/version-scoped HttpOnly download cookie for the current session",
"security": [
{
"bearer": []
}
],
"responses": {
"200": {
"description": "Native browser download path; 15-minute grant rechecks session and membership",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserDownloadGrant"
}
}
}
},
"401": {
"description": "Interactive session required"
},
"404": {
"description": "Version inaccessible"
}
}
}Write and update files
| If you want to… | Use |
|---|---|
| Replace a file's complete contents | write_file |
| Overwrite bytes at a known offset | write_at |
| Commit several offset edits together | patch |
| Add bytes and move the following content | insert |
| Delete a range and close the gap | remove |
| Replace a section with content of another length | splice |
| Set a file's length | truncate |
write_fileReplace a file's complete contents+
Use this when your application has produced a complete replacement, such as a newly generated report. Send the full byte sequence. A successful mutation returns the new committed version; save its ID for later reads and guarded edits.
pub fn write_file(file: &str, data: &[u8], version: Option<&str>, key: Option<&str>) -> Result<MutationResult, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
file | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
data | &[u8] | Raw byte input in the declared language type; binary identities must describe these exact bytes. |
version | Option<&str> | File version precondition. None/null/empty (according to language) means no committed version, not any version. |
key | Option<&str> | Stable operation identity for exact replay. Reuse only with the same payload and preconditions. |
Returns
Result<MutationResult, Error>Call example
client.write_file(file, data, version, key)Input and result fields
{
"type": "object",
"required": [
"entry",
"version"
],
"properties": {
"entry": {
"$ref": "#/components/schemas/Entry"
},
"version": {
"$ref": "#/components/schemas/Version"
},
"idempotent_replay": {
"type": "boolean",
"default": false
}
}
}HTTP requests
PUT /files/{file}/content
Atomically replace a file through the canonical extent engine
{
"id": "put-files-file-content",
"path": "/files/{file}/content",
"method": "PUT",
"summary": "Atomically replace a file through the canonical extent engine",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Base version UUID or quoted `none`"
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"maxLength": 200
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContentMutation"
}
}
}
},
"responses": {
"200": {
"description": "One committed immutable version",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MutationResult"
}
}
}
},
"400": {
"description": "Invalid input or missing idempotency key",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"409": {
"description": "Idempotency key belongs to another request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"412": {
"description": "version_precondition_failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"413": {
"description": "mutation_too_large",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"428": {
"description": "version_precondition_required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
}GET /files/{file}/versions/{version}/content
Resolve a version to a legacy blob URL or chunk manifest
{
"id": "get-files-file-versions-version-content",
"path": "/files/{file}/versions/{version}/content",
"method": "GET",
"summary": "Resolve a version to a legacy blob URL or chunk manifest",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "version",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Version content descriptor; chunked versions contain a manifest"
}
}
}write_atOverwrite bytes at a known offset+
Use this for a fixed-position change, such as updating a header or a record. The supplied bytes replace that range without shifting later bytes. Pass the version you read so a concurrent edit cannot be silently overwritten.
pub fn write_at(file: &str, offset: i64, data: &[u8], version: Option<&str>, key: Option<&str>) -> Result<MutationResult, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
file | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
offset | i64 | Non-negative byte offset, not a character offset. |
data | &[u8] | Raw byte input in the declared language type; binary identities must describe these exact bytes. |
version | Option<&str> | File version precondition. None/null/empty (according to language) means no committed version, not any version. |
key | Option<&str> | Stable operation identity for exact replay. Reuse only with the same payload and preconditions. |
Returns
Result<MutationResult, Error>Call example
client.write_at(file, offset, data, version, key)Input and result fields
{
"type": "object",
"required": [
"entry",
"version"
],
"properties": {
"entry": {
"$ref": "#/components/schemas/Entry"
},
"version": {
"$ref": "#/components/schemas/Version"
},
"idempotent_replay": {
"type": "boolean",
"default": false
}
}
}HTTP requests
POST /files/{file}/write-at
Overwrite bytes at a 64-bit logical offset without replacing unaffected content
{
"id": "post-files-file-write-at",
"path": "/files/{file}/write-at",
"method": "POST",
"summary": "Overwrite bytes at a 64-bit logical offset without replacing unaffected content",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WriteAtMutation"
}
}
}
},
"responses": {
"200": {
"description": "One committed immutable version",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MutationResult"
}
}
}
},
"400": {
"description": "Invalid input or missing idempotency key",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"409": {
"description": "Idempotency key belongs to another request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"412": {
"description": "version_precondition_failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"413": {
"description": "mutation_too_large",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"428": {
"description": "version_precondition_required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
}patchCommit several offset edits together+
Use this when one logical change touches several positions in a file. Supply offset/data pairs instead of making a separate call for each edit. The accepted patch is committed together as one version.
pub fn patch(file: &str, changes: &[Patch<'_>], version: Option<&str>, key: Option<&str>) -> Result<MutationResult, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
file | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
changes | &[Patch<'_>] | Ordered collection of patch ranges or structured changes in the declared type. |
version | Option<&str> | File version precondition. None/null/empty (according to language) means no committed version, not any version. |
key | Option<&str> | Stable operation identity for exact replay. Reuse only with the same payload and preconditions. |
Returns
Result<MutationResult, Error>Call example
client.patch(file, changes, version, key)Input and result fields
{
"type": "object",
"required": [
"entry",
"version"
],
"properties": {
"entry": {
"$ref": "#/components/schemas/Entry"
},
"version": {
"$ref": "#/components/schemas/Version"
},
"idempotent_replay": {
"type": "boolean",
"default": false
}
}
}HTTP requests
POST /files/{file}/patch
Apply up to 10,000 non-overlapping overwrite edits as one version
{
"id": "post-files-file-patch",
"path": "/files/{file}/patch",
"method": "POST",
"summary": "Apply up to 10,000 non-overlapping overwrite edits as one version",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PatchMutation"
}
}
}
},
"responses": {
"200": {
"description": "One committed immutable version",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MutationResult"
}
}
}
},
"400": {
"description": "Invalid input or missing idempotency key",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"409": {
"description": "Idempotency key belongs to another request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"412": {
"description": "version_precondition_failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"413": {
"description": "mutation_too_large",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"428": {
"description": "version_precondition_required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
}insertAdd bytes and move the following content+
Use this when new content belongs between existing bytes. The supplied data is inserted at the offset and later content shifts to make room. Offsets are measured in bytes, including for UTF-8 text.
pub fn insert(file: &str, offset: i64, data: &[u8], version: Option<&str>, key: Option<&str>) -> Result<MutationResult, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
file | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
offset | i64 | Non-negative byte offset, not a character offset. |
data | &[u8] | Raw byte input in the declared language type; binary identities must describe these exact bytes. |
version | Option<&str> | File version precondition. None/null/empty (according to language) means no committed version, not any version. |
key | Option<&str> | Stable operation identity for exact replay. Reuse only with the same payload and preconditions. |
Returns
Result<MutationResult, Error>Call example
client.insert(file, offset, data, version, key)Input and result fields
{
"type": "object",
"required": [
"entry",
"version"
],
"properties": {
"entry": {
"$ref": "#/components/schemas/Entry"
},
"version": {
"$ref": "#/components/schemas/Version"
},
"idempotent_replay": {
"type": "boolean",
"default": false
}
}
}HTTP requests
POST /files/{file}/insert
Insert bytes and shift the unchanged suffix through manifest path-copying
{
"id": "post-files-file-insert",
"path": "/files/{file}/insert",
"method": "POST",
"summary": "Insert bytes and shift the unchanged suffix through manifest path-copying",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InsertMutation"
}
}
}
},
"responses": {
"200": {
"description": "One committed immutable version",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MutationResult"
}
}
}
},
"400": {
"description": "Invalid input or missing idempotency key",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"409": {
"description": "Idempotency key belongs to another request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"412": {
"description": "version_precondition_failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"413": {
"description": "mutation_too_large",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"428": {
"description": "version_precondition_required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
}removeDelete a range and close the gap+
Use this to remove a section while keeping the rest of the file. The length selects how many bytes to delete; following content shifts left. Read the reviewed version first when calculating offsets.
pub fn remove(file: &str, offset: i64, length: i64, version: Option<&str>, key: Option<&str>) -> Result<MutationResult, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
file | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
offset | i64 | Non-negative byte offset, not a character offset. |
length | i64 | Byte count or logical byte size; non-negative and bounded by the operation. |
version | Option<&str> | File version precondition. None/null/empty (according to language) means no committed version, not any version. |
key | Option<&str> | Stable operation identity for exact replay. Reuse only with the same payload and preconditions. |
Returns
Result<MutationResult, Error>Call example
client.remove(file, offset, length, version, key)Input and result fields
{
"type": "object",
"required": [
"entry",
"version"
],
"properties": {
"entry": {
"$ref": "#/components/schemas/Entry"
},
"version": {
"$ref": "#/components/schemas/Version"
},
"idempotent_replay": {
"type": "boolean",
"default": false
}
}
}HTTP requests
POST /files/{file}/remove
Remove a logical range and close the gap without copying the suffix
{
"id": "post-files-file-remove",
"path": "/files/{file}/remove",
"method": "POST",
"summary": "Remove a logical range and close the gap without copying the suffix",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RemoveMutation"
}
}
}
},
"responses": {
"200": {
"description": "One committed immutable version",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MutationResult"
}
}
}
},
"400": {
"description": "Invalid input or missing idempotency key",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"409": {
"description": "Idempotency key belongs to another request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"412": {
"description": "version_precondition_failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"413": {
"description": "mutation_too_large",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"428": {
"description": "version_precondition_required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
}spliceReplace a section with content of another length+
Use this when the replacement is shorter or longer than the original section. Supply the offset, deletion length and replacement bytes in one mutation. It avoids an intermediate state between a separate delete and insert.
pub fn splice(file: &str, offset: i64, length: i64, data: &[u8], version: Option<&str>, key: Option<&str>) -> Result<MutationResult, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
file | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
offset | i64 | Non-negative byte offset, not a character offset. |
length | i64 | Byte count or logical byte size; non-negative and bounded by the operation. |
data | &[u8] | Raw byte input in the declared language type; binary identities must describe these exact bytes. |
version | Option<&str> | File version precondition. None/null/empty (according to language) means no committed version, not any version. |
key | Option<&str> | Stable operation identity for exact replay. Reuse only with the same payload and preconditions. |
Returns
Result<MutationResult, Error>Call example
client.splice(file, offset, length, data, version, key)Input and result fields
{
"type": "object",
"required": [
"entry",
"version"
],
"properties": {
"entry": {
"$ref": "#/components/schemas/Entry"
},
"version": {
"$ref": "#/components/schemas/Version"
},
"idempotent_replay": {
"type": "boolean",
"default": false
}
}
}HTTP requests
POST /files/{file}/splice
Replace a logical range with different-length content atomically
{
"id": "post-files-file-splice",
"path": "/files/{file}/splice",
"method": "POST",
"summary": "Replace a logical range with different-length content atomically",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SpliceMutation"
}
}
}
},
"responses": {
"200": {
"description": "One committed immutable version",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MutationResult"
}
}
}
},
"400": {
"description": "Invalid input or missing idempotency key",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"409": {
"description": "Idempotency key belongs to another request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"412": {
"description": "version_precondition_failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"413": {
"description": "mutation_too_large",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"428": {
"description": "version_precondition_required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
}truncateSet a file's length+
Use this to drop a tail or extend the logical size. Shortening removes bytes beyond the new length; extension adds zero-filled space. Earlier retained versions still contain their original bytes.
pub fn truncate(file: &str, size: i64, version: Option<&str>, key: Option<&str>) -> Result<MutationResult, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
file | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
size | i64 | Byte count or logical byte size; non-negative and bounded by the operation. |
version | Option<&str> | File version precondition. None/null/empty (according to language) means no committed version, not any version. |
key | Option<&str> | Stable operation identity for exact replay. Reuse only with the same payload and preconditions. |
Returns
Result<MutationResult, Error>Call example
client.truncate(file, size, version, key)Input and result fields
{
"type": "object",
"required": [
"entry",
"version"
],
"properties": {
"entry": {
"$ref": "#/components/schemas/Entry"
},
"version": {
"$ref": "#/components/schemas/Version"
},
"idempotent_replay": {
"type": "boolean",
"default": false
}
}
}HTTP requests
POST /files/{file}/truncate
Truncate or sparse-extend a file atomically
{
"id": "post-files-file-truncate",
"path": "/files/{file}/truncate",
"method": "POST",
"summary": "Truncate or sparse-extend a file atomically",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TruncateMutation"
}
}
}
},
"responses": {
"200": {
"description": "One committed immutable version",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MutationResult"
}
}
}
},
"400": {
"description": "Invalid input or missing idempotency key",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"409": {
"description": "Idempotency key belongs to another request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"412": {
"description": "version_precondition_failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"413": {
"description": "mutation_too_large",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"428": {
"description": "version_precondition_required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
}upload_file_bytesAtomically replace file bytes with bounded binary ingestion+
pub fn upload_file_bytes(file: &str, data: &[u8], expected_version: Option<&str>, sha: &str, idempotency: &str) -> Result<MutationResult, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
file | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
data | &[u8] | Raw byte input in the declared language type; binary identities must describe these exact bytes. |
expected_version | Option<&str> | File version precondition. None/null/empty (according to language) means no committed version, not any version. |
sha | &str | Lowercase hexadecimal SHA-256 of the exact content bytes. |
idempotency | &str | Stable operation identity for exact replay. Reuse only with the same payload and preconditions. |
Returns
Result<MutationResult, Error>Call example
client.upload_file_bytes(file, data, expected_version, sha, idempotency)Input and result fields
{
"type": "object",
"required": [
"entry",
"version"
],
"properties": {
"entry": {
"$ref": "#/components/schemas/Entry"
},
"version": {
"$ref": "#/components/schemas/Version"
},
"idempotent_replay": {
"type": "boolean",
"default": false
}
}
}HTTP requests
PUT /files/{file}/bytes
Uploads up to 100 MiB in bounded server chunks. Retry the same body and identity after interruption. A new file entry may remain empty until content commits.
{
"id": "put-files-file-bytes",
"path": "/files/{file}/bytes",
"method": "PUT",
"summary": "Atomically replace file bytes with bounded binary ingestion",
"description": "Uploads up to 100 MiB in bounded server chunks. Retry the same body and identity after interruption. A new file entry may remain empty until content commits.",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
{
"name": "X-Content-SHA256",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"responses": {
"200": {
"description": "Exactly one committed version or its replay",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MutationResult"
}
}
}
},
"400": {
"description": "Invalid size or checksum or incomplete body"
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Credential scope or access denied"
},
"404": {
"description": "File or write permission unavailable"
},
"409": {
"description": "Idempotency identity conflict"
},
"412": {
"description": "Base version changed"
},
"428": {
"description": "Version precondition required"
},
"503": {
"description": "Content storage unavailable"
},
"507": {
"description": "Quota exhausted"
}
}
}Read history and restore
File history is off by default. The drive owner can enable it for future edits, then clear earlier versions to free storage. These management calls require the owner’s session or an account-scoped admin key.
let policy = client.file_history(&drive_id)?;
client.set_file_history(&drive_id, true, &policy.revision)?;
// Future edits now retain earlier contents.
println!("{:?}", client.versions(&file_id)?);
// Permanently remove older versions; the current file stays unchanged.
let result = client.clear_file_history(&file_id)?;
println!("{}", result.bytes_freed);
// client.clear_drive_history(&drive_id)?;entries_atRead historical directory metadata at a committed sequence; current permissions and retention apply.+
pub fn entries_at(drive: &str, sequence: i64, parent: Option<&str>) -> Result<Vec<Entry>, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
sequence | i64 | Committed drive sequence (non-negative int64). TypeScript uses bigint beyond safe integer precision. |
parent | Option<&str> | Parent folder identity, or the language’s absent value for the drive root. |
Returns
Result<Vec<Entry>, Error>Call example
client.entries_at(drive, sequence, parent)Input and result fields
{
"type": "object",
"required": [
"id",
"drive_id",
"name",
"kind",
"logical_size",
"revision",
"created_at",
"modified_at",
"deleted"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"drive_id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"name": {
"type": "string"
},
"kind": {
"enum": [
"file",
"folder"
]
},
"current_version_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"logical_size": {
"type": "integer",
"format": "int64"
},
"checksum_sha256": {
"type": [
"string",
"null"
]
},
"revision": {
"type": "integer",
"format": "int64"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"modified_at": {
"type": "string",
"format": "date-time"
},
"deleted": {
"type": "boolean"
}
}
}HTTP requests
GET /drives/{drive}/entries
{
"id": "get-drives-drive-entries",
"path": "/drives/{drive}/entries",
"method": "GET",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "parent_id",
"in": "query",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "as_of",
"in": "query",
"description": "Committed drive sequence to resolve under current permissions; this read does not pin history",
"schema": {
"type": "integer",
"format": "int64",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Directory entries"
},
"410": {
"description": "history_expired — a visible historical file version required by this listing was reclaimed"
}
}
}file_historyRead history settings and storage breakdown+
pub fn file_history(drive: &str) -> Result<FileHistoryPolicy, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
Returns
Result<FileHistoryPolicy, Error>Call example
client.file_history(drive)Input and result fields
{
"type": "object",
"description": "Drive-wide history is off by default. Used storage counts current and retained historical contents with content deduplication.",
"required": [
"drive_id",
"enabled",
"revision",
"current_bytes",
"history_bytes",
"used_bytes",
"historical_versions"
],
"properties": {
"drive_id": {
"type": "string",
"format": "uuid"
},
"enabled": {
"type": "boolean"
},
"revision": {
"type": "string"
},
"current_bytes": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"history_bytes": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"used_bytes": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"historical_versions": {
"type": "integer",
"format": "int64",
"minimum": 0
}
}
}HTTP requests
GET /drives/{drive}/history
Read history settings and storage breakdown
{
"id": "get-drives-drive-history",
"path": "/drives/{drive}/history",
"method": "GET",
"summary": "Read history settings and storage breakdown",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "drive",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileHistoryPolicy"
}
}
}
},
"400": {
"description": "Invalid input"
},
"403": {
"description": "Drive owner authority is required"
},
"404": {
"description": "Drive or history not found"
},
"409": {
"description": "Revision changed or selected content is protected"
}
}
}set_file_historyEnable or disable history for future edits+
pub fn set_file_history(drive: &str, enabled: bool, expected_revision: &str) -> Result<FileHistoryPolicy, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
enabled | bool | Caller-supplied value of the declared type. See the linked operation or model for field constraints. |
expected_revision | &str | Reviewed entry or policy revision. Do not substitute a file version ID. |
Returns
Result<FileHistoryPolicy, Error>Call example
client.set_file_history(drive, enabled, expected_revision)Input and result fields
{
"type": "object",
"description": "Drive-wide history is off by default. Used storage counts current and retained historical contents with content deduplication.",
"required": [
"drive_id",
"enabled",
"revision",
"current_bytes",
"history_bytes",
"used_bytes",
"historical_versions"
],
"properties": {
"drive_id": {
"type": "string",
"format": "uuid"
},
"enabled": {
"type": "boolean"
},
"revision": {
"type": "string"
},
"current_bytes": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"history_bytes": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"used_bytes": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"historical_versions": {
"type": "integer",
"format": "int64",
"minimum": 0
}
}
}HTTP requests
PUT /drives/{drive}/history
Enable or disable history for future edits
{
"id": "put-drives-drive-history",
"path": "/drives/{drive}/history",
"method": "PUT",
"summary": "Enable or disable history for future edits",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "drive",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileHistoryPolicy"
}
}
}
},
"400": {
"description": "Invalid input"
},
"403": {
"description": "Drive owner authority is required"
},
"404": {
"description": "Drive or history not found"
},
"409": {
"description": "Revision changed or selected content is protected"
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileHistoryUpdate"
}
}
}
}
}clear_drive_historyClear all earlier versions in this drive+
pub fn clear_drive_history(drive: &str) -> Result<HistoryCleanupResult, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
Returns
Result<HistoryCleanupResult, Error>Call example
client.clear_drive_history(drive)Input and result fields
{
"type": "object",
"description": "Clears earlier versions, keeps current files, and releases allowance immediately. Protected snapshots, forks and live links are skipped. Physical reclamation is asynchronous and preserves replay and active-save pins.",
"required": [
"versions_cleared",
"versions_skipped",
"bytes_freed",
"used_bytes"
],
"properties": {
"versions_cleared": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"versions_skipped": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"bytes_freed": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"used_bytes": {
"type": "integer",
"format": "int64",
"minimum": 0
}
}
}HTTP requests
DELETE /drives/{drive}/history
Clear all earlier versions in this drive
{
"id": "delete-drives-drive-history",
"path": "/drives/{drive}/history",
"method": "DELETE",
"summary": "Clear all earlier versions in this drive",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "drive",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HistoryCleanupResult"
}
}
}
},
"400": {
"description": "Invalid input"
},
"403": {
"description": "Drive owner authority is required"
},
"404": {
"description": "Drive or history not found"
},
"409": {
"description": "Revision changed or selected content is protected"
}
}
}clear_file_historyClear earlier versions of one file+
pub fn clear_file_history(file: &str) -> Result<HistoryCleanupResult, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
file | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
Returns
Result<HistoryCleanupResult, Error>Call example
client.clear_file_history(file)Input and result fields
{
"type": "object",
"description": "Clears earlier versions, keeps current files, and releases allowance immediately. Protected snapshots, forks and live links are skipped. Physical reclamation is asynchronous and preserves replay and active-save pins.",
"required": [
"versions_cleared",
"versions_skipped",
"bytes_freed",
"used_bytes"
],
"properties": {
"versions_cleared": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"versions_skipped": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"bytes_freed": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"used_bytes": {
"type": "integer",
"format": "int64",
"minimum": 0
}
}
}HTTP requests
DELETE /files/{file}/versions
Clear earlier versions of one file
{
"id": "delete-files-file-versions",
"path": "/files/{file}/versions",
"method": "DELETE",
"summary": "Clear earlier versions of one file",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HistoryCleanupResult"
}
}
}
},
"400": {
"description": "Invalid input"
},
"403": {
"description": "Drive owner authority is required"
},
"404": {
"description": "Drive or history not found"
},
"409": {
"description": "Revision changed or selected content is protected"
}
}
}recent_versionsRecent versions.+
pub fn recent_versions(drive: &str, limit: i64) -> Result<Vec<VersionSummary>, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
limit | i64 | Bounded page size; endpoint-specific limits apply. |
Returns
Result<Vec<VersionSummary>, Error>Call example
client.recent_versions(drive, limit)Input and result fields
{
"type": "object",
"description": "",
"required": [
"version_id",
"file_id",
"file_name",
"logical_size",
"checksum_sha256",
"created_at",
"current",
"file_revision"
],
"properties": {
"version_id": {
"type": "string",
"format": "uuid"
},
"file_id": {
"type": "string",
"format": "uuid"
},
"file_name": {
"type": "string"
},
"logical_size": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"checksum_sha256": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"current": {
"type": "boolean"
},
"file_revision": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"storage_format": {
"type": "string"
},
"manifest_sha256": {
"type": "string"
},
"operation": {
"type": "string"
},
"drive_sequence": {
"type": "integer",
"format": "int64",
"minimum": 0
}
}
}HTTP requests
GET /drives/{drive}/versions
{
"id": "get-drives-drive-versions",
"path": "/drives/{drive}/versions",
"method": "GET",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "drive",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"maximum": 100
}
}
],
"responses": {
"200": {
"description": "Current and retained versions for drive history",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"versions"
],
"properties": {
"versions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/VersionSummary"
}
}
}
}
}
}
}
}
}versionsInspect a file's saved history+
List retained committed versions before choosing one to compare or restore. Keep the selected version ID, rather than assuming that the current file will still contain those bytes later.
pub fn versions(file: &str) -> Result<Vec<Version>, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
file | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
Returns
Result<Vec<Version>, Error>Call example
client.versions(file)Input and result fields
{
"type": "object",
"required": [
"id",
"file_id",
"logical_size",
"checksum_sha256",
"storage_format",
"created_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"file_id": {
"type": "string",
"format": "uuid"
},
"logical_size": {
"type": "integer",
"format": "int64"
},
"checksum_sha256": {
"type": "string"
},
"manifest_sha256": {
"type": "string"
},
"storage_format": {
"enum": [
"blob",
"chunked_v1",
"extent_v2"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"operation": {
"enum": [
"write",
"write_at",
"patch",
"insert",
"remove",
"splice",
"truncate",
"restore",
"conflict_preserved"
]
},
"drive_sequence": {
"type": "integer",
"format": "int64"
}
}
}HTTP requests
GET /files/{file}/versions
{
"id": "get-files-file-versions",
"path": "/files/{file}/versions",
"method": "GET",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Immutable version history"
}
}
}restore_versionMake earlier contents current again+
Select a retained version and pass the current entry revision you reviewed. Restoration replaces the current contents with a retained version. Earlier contents are kept only while file history is enabled.
pub fn restore_version(file: &str, version: &str, revision: i64) -> Result<Entry, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
file | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
version | &str | Selected immutable version identity for this read, restore or sharing operation. |
revision | i64 | Reviewed entry or policy revision. Do not substitute a file version ID. |
Returns
Result<Entry, Error>Call example
client.restore_version(file, version, revision)Input and result fields
{
"type": "object",
"required": [
"id",
"drive_id",
"name",
"kind",
"logical_size",
"revision",
"created_at",
"modified_at",
"deleted"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"drive_id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"name": {
"type": "string"
},
"kind": {
"enum": [
"file",
"folder"
]
},
"current_version_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"logical_size": {
"type": "integer",
"format": "int64"
},
"checksum_sha256": {
"type": [
"string",
"null"
]
},
"revision": {
"type": "integer",
"format": "int64"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"modified_at": {
"type": "string",
"format": "date-time"
},
"deleted": {
"type": "boolean"
}
}
}HTTP requests
POST /files/{file}/versions/{version}/restore
{
"id": "post-files-file-versions-version-restore",
"path": "/files/{file}/versions/{version}/restore",
"method": "POST",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "version",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"expected_revision"
],
"properties": {
"expected_revision": {
"type": "integer",
"format": "int64"
}
}
}
}
}
},
"responses": {
"200": {
"description": "New immutable restore version committed, with updated entry and ETag",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MutationResult"
}
}
}
},
"409": {
"description": "Revision conflict"
}
}
}read_version_rangeRead the exact input used by an earlier task+
Use the saved version ID to read immutable bytes after the current file has changed. This is useful for reproducible reports, reviewing an agent's input or comparing outputs. Normal access checks still apply.
pub fn read_version_range(file: &str, version: &str, offset: i64, length: i64) -> Result<Vec<u8>, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
file | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
version | &str | Selected immutable version identity for this read, restore or sharing operation. |
offset | i64 | Non-negative byte offset, not a character offset. |
length | i64 | Byte count or logical byte size; non-negative and bounded by the operation. |
Returns
Result<Vec<u8>, Error>Call example
client.read_version_range(file, version, offset, length)HTTP requests
GET /files/{file}/versions/{version}/bytes
Stream bytes from one immutable historical version
{
"id": "get-files-file-versions-version-bytes",
"path": "/files/{file}/versions/{version}/bytes",
"method": "GET",
"summary": "Stream bytes from one immutable historical version",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "version",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "Range",
"in": "header",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Full historical content"
},
"206": {
"description": "Historical range"
},
"404": {
"description": "Version does not belong to file"
}
}
}Manage your drive and plan
request_otpEmail a sign-in code+
pub fn request_otp(endpoint: &str, email: &str) -> Result<OTPChallenge, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
endpoint | &str | API origin without /v1; HTTPS outside local development. |
email | &str | Account or invitation email address. |
Returns
Result<OTPChallenge, Error>Call example
nufs_sdk::Client::request_otp(endpoint, email)Input and result fields
{
"type": "object",
"required": [
"challenge_id",
"expires_at",
"resend_after"
],
"properties": {
"challenge_id": {
"type": "string",
"format": "uuid"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"resend_after": {
"type": "integer",
"minimum": 0
},
"code": {
"type": "string",
"description": "Only exposed by explicitly configured local integration fixtures. Never returned in production."
}
}
}HTTP requests
POST /auth/otp/request
Codes expire after 10 minutes, are single use, and allow five attempts. Resending invalidates the previous code. Requests have a 60-second cooldown and a per-email and per-IP rate limit. Storage is activated separately.
{
"id": "post-auth-otp-request",
"path": "/auth/otp/request",
"method": "POST",
"summary": "Email a sign-in code",
"description": "Codes expire after 10 minutes, are single use, and allow five attempts. Resending invalidates the previous code. Requests have a 60-second cooldown and a per-email and per-IP rate limit. Storage is activated separately.",
"security": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"format": "email",
"maxLength": 254
}
}
}
}
}
},
"responses": {
"202": {
"description": "Challenge accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OTPChallenge"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Invalid, expired, consumed or exhausted code"
},
"429": {
"description": "Rate limited; wait before trying again"
},
"503": {
"description": "Email delivery unavailable"
}
}
}verify_otpSign in with an email code; create an account if needed+
pub fn verify_otp(endpoint: &str, challenge_id: &str, code: &str) -> Result<(Self, AuthSession), Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
endpoint | &str | API origin without /v1; HTTPS outside local development. |
challenge_id | &str | Identity returned by requestOTP, bound to the email address and its expiry. |
code | &str | Six-digit code from the sign-in email; keep leading zeroes and never log it. |
Returns
Result<(Self, AuthSession), Error>Call example
nufs_sdk::Client::verify_otp(endpoint, challenge_id, code)Input and result fields
{
"type": "object",
"required": [
"user",
"access_token",
"access_expires_at",
"refresh_token",
"refresh_expires_at"
],
"properties": {
"user": {
"$ref": "#/components/schemas/User"
},
"access_token": {
"type": "string",
"minLength": 1
},
"access_expires_at": {
"type": "string",
"format": "date-time"
},
"refresh_token": {
"type": "string",
"minLength": 1
},
"refresh_expires_at": {
"type": "string",
"format": "date-time"
}
}
}HTTP requests
POST /auth/otp/verify
Codes expire after 10 minutes, are single use, and allow five attempts. Resending invalidates the previous code. Requests have a 60-second cooldown and a per-email and per-IP rate limit. Storage is activated separately.
{
"id": "post-auth-otp-verify",
"path": "/auth/otp/verify",
"method": "POST",
"summary": "Sign in with an email code; create an account if needed",
"description": "Codes expire after 10 minutes, are single use, and allow five attempts. Resending invalidates the previous code. Requests have a 60-second cooldown and a per-email and per-IP rate limit. Storage is activated separately.",
"security": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"challenge_id",
"code"
],
"properties": {
"challenge_id": {
"type": "string",
"format": "uuid"
},
"code": {
"type": "string",
"pattern": "^[0-9]{6}$"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Session created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthSession"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Invalid, expired, consumed or exhausted code"
},
"429": {
"description": "Rate limited; wait before trying again"
},
"503": {
"description": "Email delivery unavailable"
}
}
}drivesDrives.+
pub fn drives() -> Result<Vec<Drive>, Error>Parameters
No explicit arguments.
Returns
Result<Vec<Drive>, Error>Call example
client.drives()Input and result fields
{
"type": "object",
"required": [
"id",
"name",
"quota_bytes",
"used_bytes",
"state",
"plan",
"role",
"created_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"quota_bytes": {
"type": "integer",
"format": "int64"
},
"used_bytes": {
"type": "integer",
"format": "int64"
},
"state": {
"enum": [
"active",
"deleting",
"deleted"
]
},
"source_drive_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"source_sequence": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"plan": {
"enum": [
"individual",
"team",
"enterprise"
]
},
"role": {
"enum": [
"viewer",
"editor",
"admin",
"owner"
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}HTTP requests
GET /drives
{
"id": "get-drives",
"path": "/drives",
"method": "GET",
"security": [
{
"bearer": []
}
],
"responses": {
"200": {
"description": "Drives visible to the current identity, filtered by key scope"
}
}
}driveDrive.+
pub fn drive(id: &str) -> Result<Drive, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
id | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
Returns
Result<Drive, Error>Call example
client.drive(id)Input and result fields
{
"type": "object",
"required": [
"id",
"name",
"quota_bytes",
"used_bytes",
"state",
"plan",
"role",
"created_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"quota_bytes": {
"type": "integer",
"format": "int64"
},
"used_bytes": {
"type": "integer",
"format": "int64"
},
"state": {
"enum": [
"active",
"deleting",
"deleted"
]
},
"source_drive_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"source_sequence": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"plan": {
"enum": [
"individual",
"team",
"enterprise"
]
},
"role": {
"enum": [
"viewer",
"editor",
"admin",
"owner"
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}HTTP requests
GET /drives/{drive}
{
"id": "get-drives-drive",
"path": "/drives/{drive}",
"method": "GET",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "drive",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Drive"
},
"404": {
"description": "Not found or inaccessible"
}
}
}platform_configurationPlatform administrator draft and published configuration+
pub fn platform_configuration() -> Result<serde_json::Value, Error>Parameters
No explicit arguments.
Returns
Result<serde_json::Value, Error>Call example
client.platform_configuration()HTTP requests
GET /platform/config
Platform administrator draft and published configuration
{
"id": "get-platform-config",
"path": "/platform/config",
"method": "GET",
"summary": "Platform administrator draft and published configuration",
"security": [
{
"bearer": []
}
],
"responses": {
"200": {
"description": "Platform administrator draft and published configuration",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PlatformConfiguration"
}
}
}
},
"401": {
"description": "Session required"
},
"403": {
"description": "Platform administrator access required"
},
"503": {
"description": "Configuration unavailable"
}
}
}save_platform_configurationSave a draft or publish product settings; platform administrator only+
pub fn save_platform_configuration(document: &serde_json::Value, expected_revision: &str, publish: bool) -> Result<serde_json::Value, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
document | &serde_json::Value | Caller-supplied value of the declared type. See the linked operation or model for field constraints. |
expected_revision | &str | Reviewed entry or policy revision. Do not substitute a file version ID. |
publish | bool | Caller-supplied value of the declared type. See the linked operation or model for field constraints. |
Returns
Result<serde_json::Value, Error>Call example
client.save_platform_configuration(document, expected_revision, publish)HTTP requests
PUT /platform/config
Save a draft or publish product settings; platform administrator only
{
"id": "put-platform-config",
"path": "/platform/config",
"method": "PUT",
"summary": "Save a draft or publish product settings; platform administrator only",
"security": [
{
"bearer": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"expected_revision",
"document",
"publish"
],
"properties": {
"expected_revision": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
},
"document": {
"$ref": "#/components/schemas/PlatformDocument"
},
"publish": {
"type": "boolean"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Updated configuration",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PlatformConfiguration"
}
}
}
},
"400": {
"description": "Invalid settings"
},
"401": {
"description": "Session required"
},
"403": {
"description": "Platform administrator access required"
},
"409": {
"description": "Revision changed; reload before editing"
}
}
}plansPublished monthly plans and add-on terms+
pub fn plans() -> Result<serde_json::Value, Error>Parameters
No explicit arguments.
Returns
Result<serde_json::Value, Error>Call example
client.plans()HTTP requests
GET /plans
Published monthly plans and add-on terms
{
"id": "get-plans",
"path": "/plans",
"method": "GET",
"summary": "Published monthly plans and add-on terms",
"security": [],
"responses": {
"200": {
"description": "Checkout mode, USD monthly prices, included seats and per-tier addon rules",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PlanCatalog"
}
}
}
}
}
}subscriptionOwner-only subscription and storage/seat usage+
pub fn subscription(drive: &str) -> Result<DriveSubscription, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
Returns
Result<DriveSubscription, Error>Call example
client.subscription(drive)Input and result fields
{
"type": "object",
"additionalProperties": false,
"required": [
"drive_id",
"billing_user_id",
"status",
"storage_bytes",
"seats",
"members",
"reserved_invitations",
"used_bytes",
"currency",
"monthly_total_minor",
"revision",
"current_period_end",
"current_period_start",
"billing_anchor",
"cycle_number",
"access_until",
"pending_monthly_total_minor",
"cancel_at_period_end",
"pending_storage_bytes",
"pending_seats"
],
"properties": {
"drive_id": {
"type": "string"
},
"billing_user_id": {
"type": "string"
},
"status": {
"type": "string"
},
"currency": {
"type": "string"
},
"revision": {
"type": "string"
},
"current_period_start": {
"type": "string",
"format": "date-time",
"description": "Start of the current monthly cycle in UTC."
},
"billing_anchor": {
"type": "string",
"format": "date-time",
"description": "UTC day and time used to calculate calendar-month boundaries. Reset to the new date when an administrator adjusts validity."
},
"cycle_number": {
"type": "integer",
"minimum": 1
},
"access_until": {
"type": "string",
"format": "date-time",
"description": "Authoritative validity date and next renewal boundary. Free subscriptions renew when automatic renewal is enabled."
},
"pending_monthly_total_minor": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"current_period_end": {
"type": "string"
},
"storage_bytes": {
"type": "integer",
"minimum": 0
},
"seats": {
"type": "integer",
"minimum": 0
},
"members": {
"type": "integer",
"minimum": 0
},
"reserved_invitations": {
"type": "integer",
"minimum": 0
},
"used_bytes": {
"type": "integer",
"minimum": 0
},
"monthly_total_minor": {
"type": "integer",
"minimum": 0
},
"cancel_at_period_end": {
"type": "boolean"
},
"pending_storage_bytes": {
"type": [
"integer",
"null"
],
"minimum": 1
},
"pending_seats": {
"type": [
"integer",
"null"
],
"minimum": 1
},
"plan_version_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"pending_plan_version_id": {
"type": [
"string",
"null"
],
"format": "uuid"
}
}
}HTTP requests
GET /drives/{drive}/subscription
Owner-only subscription and storage/seat usage
{
"id": "get-drives-drive-subscription",
"path": "/drives/{drive}/subscription",
"method": "GET",
"summary": "Owner-only subscription and storage/seat usage",
"security": [
{
"bearer": []
}
],
"responses": {
"200": {
"description": "Drive subscription",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DriveSubscription"
}
}
}
}
}
}change_subscriptionDevelopment checkout for subscription changes; production requires billing configuration+
pub fn change_subscription(drive: &str, input: &SubscriptionChange) -> Result<DriveSubscription, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
input | &SubscriptionChange | Structured input of the declared type; use the linked schema for required fields and constraints. |
Returns
Result<DriveSubscription, Error>Call example
client.change_subscription(drive, input)Input and result fields
{
"type": "object",
"additionalProperties": false,
"required": [
"drive_id",
"billing_user_id",
"status",
"storage_bytes",
"seats",
"members",
"reserved_invitations",
"used_bytes",
"currency",
"monthly_total_minor",
"revision",
"current_period_end",
"current_period_start",
"billing_anchor",
"cycle_number",
"access_until",
"pending_monthly_total_minor",
"cancel_at_period_end",
"pending_storage_bytes",
"pending_seats"
],
"properties": {
"drive_id": {
"type": "string"
},
"billing_user_id": {
"type": "string"
},
"status": {
"type": "string"
},
"currency": {
"type": "string"
},
"revision": {
"type": "string"
},
"current_period_start": {
"type": "string",
"format": "date-time",
"description": "Start of the current monthly cycle in UTC."
},
"billing_anchor": {
"type": "string",
"format": "date-time",
"description": "UTC day and time used to calculate calendar-month boundaries. Reset to the new date when an administrator adjusts validity."
},
"cycle_number": {
"type": "integer",
"minimum": 1
},
"access_until": {
"type": "string",
"format": "date-time",
"description": "Authoritative validity date and next renewal boundary. Free subscriptions renew when automatic renewal is enabled."
},
"pending_monthly_total_minor": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"current_period_end": {
"type": "string"
},
"storage_bytes": {
"type": "integer",
"minimum": 0
},
"seats": {
"type": "integer",
"minimum": 0
},
"members": {
"type": "integer",
"minimum": 0
},
"reserved_invitations": {
"type": "integer",
"minimum": 0
},
"used_bytes": {
"type": "integer",
"minimum": 0
},
"monthly_total_minor": {
"type": "integer",
"minimum": 0
},
"cancel_at_period_end": {
"type": "boolean"
},
"pending_storage_bytes": {
"type": [
"integer",
"null"
],
"minimum": 1
},
"pending_seats": {
"type": [
"integer",
"null"
],
"minimum": 1
},
"plan_version_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"pending_plan_version_id": {
"type": [
"string",
"null"
],
"format": "uuid"
}
}
}{
"type": "object",
"additionalProperties": false,
"required": [
"storage_bytes",
"seats",
"expected_revision",
"cancel_at_period_end"
],
"properties": {
"storage_bytes": {
"type": "integer",
"minimum": 1,
"maximum": 1000000000000000
},
"seats": {
"type": "integer",
"minimum": 1,
"maximum": 100000
},
"expected_revision": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
},
"cancel_at_period_end": {
"type": "boolean"
},
"plan_version_id": {
"type": "string",
"format": "uuid",
"description": "Version returned by GET /plans. Rejects stale terms with 409; omit when cancelling an existing subscription."
}
},
"description": "Storage and member allowances are validated against the published plan catalog. Retrieve /plans before selecting a plan; prices and add-on increments can change."
}HTTP requests
PUT /drives/{drive}/subscription
Development checkout for subscription changes; production requires billing configuration
{
"id": "put-drives-drive-subscription",
"path": "/drives/{drive}/subscription",
"method": "PUT",
"summary": "Development checkout for subscription changes; production requires billing configuration",
"security": [
{
"bearer": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubscriptionChange"
}
}
}
},
"responses": {
"200": {
"description": "Updated subscription; decreases take effect at renewal",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DriveSubscription"
}
}
}
},
"503": {
"description": "Real billing is not configured; no charge or entitlement change"
}
}
}leave_driveLeave a shared drive; the owner cannot leave+
pub fn leave_drive(drive: &str) -> Result<(), Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
Returns
Result<(), Error>Call example
client.leave_drive(drive)HTTP requests
DELETE /drives/{drive}/membership
Leave a shared drive; the owner cannot leave
{
"id": "delete-drives-drive-membership",
"path": "/drives/{drive}/membership",
"method": "DELETE",
"summary": "Leave a shared drive; the owner cannot leave",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "drive",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Access revoked; purchased seat quantity is unchanged"
}
}
}create_driveActivate an owned drive from selected storage and seats+
pub fn create_drive(input: &DrivePlanSelection) -> Result<Drive, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
input | &DrivePlanSelection | Structured input of the declared type; use the linked schema for required fields and constraints. |
Returns
Result<Drive, Error>Call example
client.create_drive(input)Input and result fields
{
"type": "object",
"additionalProperties": false,
"required": [
"name",
"storage_bytes",
"seats"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"storage_bytes": {
"type": "integer",
"minimum": 1,
"maximum": 1000000000000000
},
"seats": {
"type": "integer",
"minimum": 1,
"maximum": 100000
},
"plan_version_id": {
"type": "string",
"format": "uuid",
"description": "Version returned by GET /plans. Rejects stale terms with 409; omit when cancelling an existing subscription."
}
},
"description": "Storage and member allowances are validated against the published plan catalog. Retrieve /plans before selecting a plan; prices and add-on increments can change."
}{
"type": "object",
"required": [
"id",
"name",
"quota_bytes",
"used_bytes",
"state",
"plan",
"role",
"created_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"quota_bytes": {
"type": "integer",
"format": "int64"
},
"used_bytes": {
"type": "integer",
"format": "int64"
},
"state": {
"enum": [
"active",
"deleting",
"deleted"
]
},
"source_drive_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"source_sequence": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"plan": {
"enum": [
"individual",
"team",
"enterprise"
]
},
"role": {
"enum": [
"viewer",
"editor",
"admin",
"owner"
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}HTTP requests
POST /drives
Activate an owned drive from selected storage and seats
{
"id": "post-drives",
"path": "/drives",
"method": "POST",
"summary": "Activate an owned drive from selected storage and seats",
"security": [
{
"bearer": []
}
],
"responses": {
"201": {
"description": "Drive created"
},
"403": {
"description": "Permission or entitlement limit"
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DrivePlanSelection"
}
}
}
}
}delete_driveDelete drive.+
pub fn delete_drive(id: &str) -> Result<(), Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
id | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
Returns
Result<(), Error>Call example
client.delete_drive(id)HTTP requests
DELETE /drives/{drive}
{
"id": "delete-drives-drive",
"path": "/drives/{drive}",
"method": "DELETE",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "drive",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Drive deleted"
},
"404": {
"description": "Drive inaccessible"
}
}
}Manage members and audit activity
member_policyRead explicit drive member limit and occupied seats+
pub fn member_policy(drive: &str) -> Result<DriveMemberPolicy, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
Returns
Result<DriveMemberPolicy, Error>Call example
client.member_policy(drive)Input and result fields
{
"type": "object",
"additionalProperties": false,
"required": [
"drive_id",
"max_members",
"members",
"reserved_invitations",
"revision"
],
"properties": {
"drive_id": {
"type": "string",
"format": "uuid"
},
"max_members": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 100000
},
"members": {
"type": "integer",
"minimum": 1
},
"reserved_invitations": {
"type": "integer",
"minimum": 0
},
"revision": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
}
}
}HTTP requests
GET /drives/{drive}/members/policy
Interactive owner or admin only. Null means no configured cap. The owner counts as a member. Distinct active invitation emails reserve seats until accepted or unusable.
{
"id": "get-drives-drive-members-policy",
"path": "/drives/{drive}/members/policy",
"method": "GET",
"summary": "Read explicit drive member limit and occupied seats",
"description": "Interactive owner or admin only. Null means no configured cap. The owner counts as a member. Distinct active invitation emails reserve seats until accepted or unusable.",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "drive",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Member policy",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DriveMemberPolicy"
}
}
}
},
"400": {
"description": "Invalid drive ID"
},
"401": {
"description": "Interactive session required"
},
"404": {
"description": "Administration unavailable"
},
"500": {
"description": "Policy read failed"
}
}
}account_audit_retention_policyRead account audit retention policy+
pub fn account_audit_retention_policy() -> Result<AccountAuditRetentionPolicy, Error>Parameters
No explicit arguments.
Returns
Result<AccountAuditRetentionPolicy, Error>Call example
client.account_audit_retention_policy()Input and result fields
{
"type": "object",
"additionalProperties": false,
"required": [
"user_id",
"keep_days",
"legal_hold",
"revision"
],
"properties": {
"user_id": {
"type": "string",
"format": "uuid"
},
"keep_days": {
"type": [
"integer",
"null"
],
"minimum": 7,
"maximum": 36500,
"description": "Null retains account audit history indefinitely"
},
"legal_hold": {
"type": "boolean",
"description": "Account legal hold blocks cleanup and cannot be changed by this endpoint"
},
"revision": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
}
}
}HTTP requests
GET /account/audit/retention
Requires an interactive account owner session. Null keep_days means indefinite retention. Account legal hold blocks cleanup.
{
"id": "get-account-audit-retention",
"path": "/account/audit/retention",
"method": "GET",
"summary": "Read account audit retention policy",
"description": "Requires an interactive account owner session. Null keep_days means indefinite retention. Account legal hold blocks cleanup.",
"security": [
{
"bearer": []
}
],
"responses": {
"200": {
"description": "Audit retention policy",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountAuditRetentionPolicy"
}
}
}
},
"400": {
"description": "Invalid account ID"
},
"401": {
"description": "Interactive session required"
},
"404": {
"description": "Account administration unavailable"
}
}
}update_account_audit_retention_policyConfigure account audit retention with a displayed revision guard+
pub fn update_account_audit_retention_policy(keep_days: Option<i64>, expected_revision: &str) -> Result<AccountAuditRetentionPolicy, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
keep_days | Option<i64> | Retention interval in days; absent/null retains indefinitely where the policy permits it. |
expected_revision | &str | Reviewed entry or policy revision. Do not substitute a file version ID. |
Returns
Result<AccountAuditRetentionPolicy, Error>Call example
client.update_account_audit_retention_policy(keep_days, expected_revision)Input and result fields
{
"type": "object",
"additionalProperties": false,
"required": [
"user_id",
"keep_days",
"legal_hold",
"revision"
],
"properties": {
"user_id": {
"type": "string",
"format": "uuid"
},
"keep_days": {
"type": [
"integer",
"null"
],
"minimum": 7,
"maximum": 36500,
"description": "Null retains account audit history indefinitely"
},
"legal_hold": {
"type": "boolean",
"description": "Account legal hold blocks cleanup and cannot be changed by this endpoint"
},
"revision": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
}
}
}HTTP requests
PUT /account/audit/retention
Requires an interactive account owner session. Setting 7–36500 days enables bounded background retirement; null disables retirement. Existing legal hold remains unchanged. Cleanup already committed cannot be undone by a later hold or policy extension.
{
"id": "put-account-audit-retention",
"path": "/account/audit/retention",
"method": "PUT",
"summary": "Configure account audit retention with a displayed revision guard",
"description": "Requires an interactive account owner session. Setting 7–36500 days enables bounded background retirement; null disables retirement. Existing legal hold remains unchanged. Cleanup already committed cannot be undone by a later hold or policy extension.",
"security": [
{
"bearer": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuditRetentionUpdate"
}
}
}
},
"responses": {
"200": {
"description": "Updated audit retention policy",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountAuditRetentionPolicy"
}
}
}
},
"400": {
"description": "Invalid retention days or displayed revision"
},
"401": {
"description": "Interactive session required"
},
"404": {
"description": "Account administration unavailable"
},
"409": {
"description": "Displayed policy revision is stale"
}
}
}audit_retention_policyRead drive audit retention policy+
pub fn audit_retention_policy(drive: &str) -> Result<AuditRetentionPolicy, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
Returns
Result<AuditRetentionPolicy, Error>Call example
client.audit_retention_policy(drive)Input and result fields
{
"type": "object",
"additionalProperties": false,
"required": [
"drive_id",
"keep_days",
"legal_hold",
"revision"
],
"properties": {
"drive_id": {
"type": "string",
"format": "uuid"
},
"keep_days": {
"type": [
"integer",
"null"
],
"minimum": 7,
"maximum": 36500,
"description": "Null retains audit history indefinitely"
},
"legal_hold": {
"type": "boolean",
"description": "Shared drive legal hold blocks audit cleanup"
},
"revision": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
}
}
}HTTP requests
GET /drives/{drive}/audit/retention
Requires an interactive owner or admin session. Null keep_days means indefinite retention. Shared drive legal hold blocks cleanup.
{
"id": "get-drives-drive-audit-retention",
"path": "/drives/{drive}/audit/retention",
"method": "GET",
"summary": "Read drive audit retention policy",
"description": "Requires an interactive owner or admin session. Null keep_days means indefinite retention. Shared drive legal hold blocks cleanup.",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "drive",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Audit retention policy",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuditRetentionPolicy"
}
}
}
},
"400": {
"description": "Invalid drive ID"
},
"401": {
"description": "Interactive session required"
},
"404": {
"description": "Drive administration unavailable"
}
}
}update_audit_retention_policyConfigure drive audit retention with a displayed revision guard+
pub fn update_audit_retention_policy(drive: &str, keep_days: Option<i64>, expected_revision: &str) -> Result<AuditRetentionPolicy, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
keep_days | Option<i64> | Retention interval in days; absent/null retains indefinitely where the policy permits it. |
expected_revision | &str | Reviewed entry or policy revision. Do not substitute a file version ID. |
Returns
Result<AuditRetentionPolicy, Error>Call example
client.update_audit_retention_policy(drive, keep_days, expected_revision)Input and result fields
{
"type": "object",
"additionalProperties": false,
"required": [
"drive_id",
"keep_days",
"legal_hold",
"revision"
],
"properties": {
"drive_id": {
"type": "string",
"format": "uuid"
},
"keep_days": {
"type": [
"integer",
"null"
],
"minimum": 7,
"maximum": 36500,
"description": "Null retains audit history indefinitely"
},
"legal_hold": {
"type": "boolean",
"description": "Shared drive legal hold blocks audit cleanup"
},
"revision": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
}
}
}HTTP requests
PUT /drives/{drive}/audit/retention
Requires an interactive owner or admin session. Setting 7–36500 days enables bounded background retirement; null disables retirement. Existing legal hold remains unchanged. Cleanup already committed cannot be undone by a later hold or policy extension.
{
"id": "put-drives-drive-audit-retention",
"path": "/drives/{drive}/audit/retention",
"method": "PUT",
"summary": "Configure drive audit retention with a displayed revision guard",
"description": "Requires an interactive owner or admin session. Setting 7–36500 days enables bounded background retirement; null disables retirement. Existing legal hold remains unchanged. Cleanup already committed cannot be undone by a later hold or policy extension.",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "drive",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuditRetentionUpdate"
}
}
}
},
"responses": {
"200": {
"description": "Updated audit retention policy",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuditRetentionPolicy"
}
}
}
},
"400": {
"description": "Invalid retention days or displayed revision"
},
"401": {
"description": "Interactive session required"
},
"404": {
"description": "Drive administration unavailable"
},
"409": {
"description": "Displayed policy revision is stale"
}
}
}export_drive_auditWrite ordered audit records to a sink and emit a completion record only after successful output.+
pub fn export_drive_audit(drive: &str, output: &mut impl std::io::Write, page_limit: u16) -> Result<u64, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
output | &mut impl std::io::Write | Caller-owned output destination. Output failures prevent successful completion. |
page_limit | u16 | Bounded page size; endpoint-specific limits apply. |
Returns
Result<u64, Error>Call example
client.export_drive_audit(drive, output, page_limit)drive_auditRead a bounded page of drive audit history+
pub fn drive_audit(drive: &str, limit: u16, cursor: Option<&str>) -> Result<AuditPage, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
limit | u16 | Bounded page size; endpoint-specific limits apply. |
cursor | Option<&str> | Opaque cursor returned by this same operation and scope. Omit for the first page. |
Returns
Result<AuditPage, Error>Call example
client.drive_audit(drive, limit, cursor)Input and result fields
{
"type": "object",
"additionalProperties": false,
"required": [
"events",
"next_cursor"
],
"properties": {
"events": {
"type": "array",
"maxItems": 200,
"items": {
"$ref": "#/components/schemas/AuditEvent"
}
},
"next_cursor": {
"type": [
"string",
"null"
],
"maxLength": 256
}
}
}HTTP requests
GET /drives/{drive}/audit
Interactive owner or admin session required on every page. Events descend by identity rather than timestamp. Continue with next_cursor until null; refresh without a cursor for new events. This live traversal is not a database snapshot and late commits may require a refresh. Raw metadata and credential material are omitted.
{
"id": "get-drives-drive-audit",
"path": "/drives/{drive}/audit",
"method": "GET",
"summary": "Read a bounded page of drive audit history",
"description": "Interactive owner or admin session required on every page. Events descend by identity rather than timestamp. Continue with next_cursor until null; refresh without a cursor for new events. This live traversal is not a database snapshot and late commits may require a refresh. Raw metadata and credential material are omitted.",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "drive",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 50
}
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string",
"maxLength": 256
}
}
],
"responses": {
"200": {
"description": "Audit page",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuditPage"
}
}
}
},
"400": {
"description": "Invalid page limit or drive cursor"
},
"401": {
"description": "Interactive session required"
},
"404": {
"description": "Drive administration unavailable"
},
"500": {
"description": "Audit history could not be read"
}
}
}account_auditRead a bounded page of account audit history+
pub fn account_audit(limit: u16, cursor: Option<&str>) -> Result<AuditPage, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
limit | u16 | Bounded page size; endpoint-specific limits apply. |
cursor | Option<&str> | Opaque cursor returned by this same operation and scope. Omit for the first page. |
Returns
Result<AuditPage, Error>Call example
client.account_audit(limit, cursor)Input and result fields
{
"type": "object",
"additionalProperties": false,
"required": [
"events",
"next_cursor"
],
"properties": {
"events": {
"type": "array",
"maxItems": 200,
"items": {
"$ref": "#/components/schemas/AuditEvent"
}
},
"next_cursor": {
"type": [
"string",
"null"
],
"maxLength": 256
}
}
}HTTP requests
GET /account/audit
Interactive account session required on every page. The authenticated user is the account subject; no supplied account ID is accepted. Drive events and unattributed unknown login attempts are excluded. Anonymous recovery and reuse events retain null actors. Events descend by identity rather than timestamp. Continue with next_cursor until null; refresh without a cursor for new events. This live traversal is not a database snapshot and late commits may require a refresh. Raw metadata and credential material are omitted.
{
"id": "get-account-audit",
"path": "/account/audit",
"method": "GET",
"summary": "Read a bounded page of account audit history",
"description": "Interactive account session required on every page. The authenticated user is the account subject; no supplied account ID is accepted. Drive events and unattributed unknown login attempts are excluded. Anonymous recovery and reuse events retain null actors. Events descend by identity rather than timestamp. Continue with next_cursor until null; refresh without a cursor for new events. This live traversal is not a database snapshot and late commits may require a refresh. Raw metadata and credential material are omitted.",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 50
}
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string",
"maxLength": 256
}
}
],
"responses": {
"200": {
"description": "Audit page",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuditPage"
}
}
}
},
"400": {
"description": "Invalid page limit or account cursor"
},
"401": {
"description": "Interactive session required"
},
"404": {
"description": "Account administration unavailable"
},
"500": {
"description": "Audit history could not be read"
}
}
}drive_membersDrive members.+
pub fn drive_members(drive: &str) -> Result<Vec<DriveMember>, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
Returns
Result<Vec<DriveMember>, Error>Call example
client.drive_members(drive)Input and result fields
{
"type": "object",
"required": [
"user_id",
"email",
"role",
"created_at"
],
"additionalProperties": false,
"properties": {
"user_id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"role": {
"type": "string",
"enum": [
"owner",
"admin",
"editor",
"viewer"
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}HTTP requests
GET /drives/{drive}/members
{
"id": "get-drives-drive-members",
"path": "/drives/{drive}/members",
"method": "GET",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "drive",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Drive members",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"members"
],
"properties": {
"members": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DriveMember"
}
}
}
}
}
}
}
}
}invite_drive_memberInvite drive member.+
pub fn invite_drive_member(drive: &str, email: &str, role: &str) -> Result<InvitationResult, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
email | &str | Account or invitation email address. |
role | &str | Requested member role. The drive owner cannot be changed. |
Returns
Result<InvitationResult, Error>Call example
client.invite_drive_member(drive, email, role)Input and result fields
{
"type": "object",
"required": [
"invitation"
],
"additionalProperties": false,
"properties": {
"invitation": {
"$ref": "#/components/schemas/DriveInvitation"
},
"token": {
"type": "string",
"minLength": 1,
"description": "One-time token exposed only by configured local development delivery"
}
}
}HTTP requests
POST /drives/{drive}/invitations
{
"id": "post-drives-drive-invitations",
"path": "/drives/{drive}/invitations",
"method": "POST",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "drive",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"201": {
"description": "Invitation created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InvitationResult"
}
}
}
},
"409": {
"description": "Configured member limit reached"
},
"500": {
"description": "Invitation and audit could not be committed"
}
}
}accept_drive_invitationAccept drive invitation.+
pub fn accept_drive_invitation(token: &str) -> Result<Drive, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
token | &str | Credential for this operation. Use interactive, machine or recipient authority as applicable; keep it private. |
Returns
Result<Drive, Error>Call example
client.accept_drive_invitation(token)Input and result fields
{
"type": "object",
"required": [
"id",
"name",
"quota_bytes",
"used_bytes",
"state",
"plan",
"role",
"created_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"quota_bytes": {
"type": "integer",
"format": "int64"
},
"used_bytes": {
"type": "integer",
"format": "int64"
},
"state": {
"enum": [
"active",
"deleting",
"deleted"
]
},
"source_drive_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"source_sequence": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"plan": {
"enum": [
"individual",
"team",
"enterprise"
]
},
"role": {
"enum": [
"viewer",
"editor",
"admin",
"owner"
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}HTTP requests
POST /invitations/accept
{
"id": "post-invitations-accept",
"path": "/invitations/accept",
"method": "POST",
"security": [
{
"bearer": []
}
],
"responses": {
"200": {
"description": "Membership added or existing role preserved",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Drive"
}
}
}
},
"404": {
"description": "Invitation expired or revoked or issuer no longer has admin authority"
},
"409": {
"description": "Configured member limit reached"
},
"500": {
"description": "Membership and audit could not be committed"
}
}
}update_drive_memberChange a non-owner member role using interactive admin authority+
pub fn update_drive_member(drive: &str, member: &str, role: &str, expected_role: &str) -> Result<DriveMember, Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
member | &str | Target member identity; owner changes use the dedicated ownership operation. |
role | &str | Requested member role. The drive owner cannot be changed. |
expected_role | &str | Member role you reviewed; rejects a stale administrative change. |
Returns
Result<DriveMember, Error>Call example
client.update_drive_member(drive, member, role, expected_role)Input and result fields
{
"type": "object",
"required": [
"user_id",
"email",
"role",
"created_at"
],
"additionalProperties": false,
"properties": {
"user_id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"role": {
"type": "string",
"enum": [
"owner",
"admin",
"editor",
"viewer"
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}HTTP requests
PATCH /drives/{drive}/members/{member}
Change a non-owner member role using interactive admin authority
{
"id": "patch-drives-drive-members-member",
"path": "/drives/{drive}/members/{member}",
"method": "PATCH",
"summary": "Change a non-owner member role using interactive admin authority",
"security": [
{
"bearer": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DriveMemberChange"
}
}
}
},
"responses": {
"200": {
"description": "Updated member",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DriveMember"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Interactive session required"
},
"403": {
"description": "Owner is protected"
},
"404": {
"description": "Drive or member inaccessible"
},
"409": {
"description": "Displayed role no longer matches"
}
}
}remove_drive_memberRemove non-owner access and invalidate outstanding invitations+
pub fn remove_drive_member(drive: &str, member: &str, expected_role: &str) -> Result<(), Error>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | &str | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
member | &str | Target member identity; owner changes use the dedicated ownership operation. |
expected_role | &str | Member role you reviewed; rejects a stale administrative change. |
Returns
Result<(), Error>Call example
client.remove_drive_member(drive, member, expected_role)HTTP requests
DELETE /drives/{drive}/members/{member}
Remove non-owner access and invalidate outstanding invitations
{
"id": "delete-drives-drive-members-member",
"path": "/drives/{drive}/members/{member}",
"method": "DELETE",
"summary": "Remove non-owner access and invalidate outstanding invitations",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "expected_role",
"in": "query",
"required": true,
"schema": {
"type": "string",
"enum": [
"viewer",
"editor",
"admin",
"owner"
]
}
}
],
"responses": {
"204": {
"description": "Membership removed; files remain unchanged"
},
"400": {
"description": "Missing or invalid displayed role"
},
"401": {
"description": "Interactive session required"
},
"403": {
"description": "Owner is protected"
},
"404": {
"description": "Drive or member inaccessible"
},
"409": {
"description": "Displayed role no longer matches"
}
}
}platform_auditLatest 100 product configuration changes; platform administrator only+
pub fn platform_audit() -> Result<Vec<serde_json::Value>, Error>Parameters
No explicit arguments.
Returns
Result<Vec<serde_json::Value>, Error>Call example
client.platform_audit()HTTP requests
GET /platform/audit
Latest 100 product configuration changes; platform administrator only
{
"id": "get-platform-audit",
"path": "/platform/audit",
"method": "GET",
"summary": "Latest 100 product configuration changes; platform administrator only",
"security": [
{
"bearer": []
}
],
"responses": {
"200": {
"description": "Audit records, newest first",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PlatformAuditEntry"
}
}
}
}
}
}
},
"401": {
"description": "Session required"
},
"403": {
"description": "Platform administrator access required"
}
}
}Errors and exact retries
Handle a failed version guard without silently overwriting a newer edit. This fragment uses an existing client and your pending input.
if let Err(error) = result {
if error.is_precondition() {
// Preserve the edit and inspect the newer head.
} else if error.is_authorization() {
// Check current scope and session.
}
return Err(error);
}