Build with nuFS · 0.2.0

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

Python 3.10+ · synchronous httpx. Install the supplied 0.2.0 release artifact:

Installation

python -m pip install /path/to/nufs_sdk-0.2.0-py3-none-any.whl

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.

Environment

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.

Code

import os
import uuid
from nufs_sdk import Client

with Client(os.environ["NUFS_ENDPOINT"], os.environ["NUFS_TOKEN"]) as client:
    file = client.create_entry(os.environ["NUFS_DRIVE_ID"],
                               "notes-" + uuid.uuid4().hex + ".txt", "file")
    first = client.write_file(file["id"], b"hello", None)
    saved = client.write_at(file["id"], 0, b"H", first["version"]["id"])
    original = client.read_version_range(file["id"], saved["version"]["id"], 0, 5)
    assert original == b"Hello"
    print(client.versions(file["id"]))

Method reference

84 Python methods, grouped by task.

Connect and authenticate

__init__ init .

Code

__init__(endpoint: str, credential: str) -> Client

Parameters

Name	Type / default	Meaning
`endpoint`	`str`	API origin without /v1; HTTPS outside local development.
`credential`	`str`	Credential for this operation. Use interactive, machine or recipient authority as applicable; keep it private.

Returns

Code

Client

Call example

Code

Client(endpoint, credential)

refreshRotate a refresh token

Code

refresh(endpoint: str, refresh_token: str) -> RefreshedSession

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

Code

RefreshedSession

Call example

Code

Client.refresh(endpoint, refresh_token)

Input and result fields

RefreshedSession

{
  "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

Request and response contract

{
  "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.

Code

logout() -> None

Parameters

No explicit arguments.

Returns

Code

None

Call example

Code

client.logout()

HTTP requests

POST /auth/logout

Request and response contract

{
  "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"
          }
        }
      }
    }
  }
}

closeClose the underlying HTTP client.

Code

close() -> None

Parameters

No explicit arguments.

Returns

Code

None

Call example

Code

client.close()

create_deviceCreate device.

Code

create_device(name: str, platform: str) -> Device

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

Code

Device

Call example

Code

client.create_device(name, platform)

HTTP requests

POST /devices

Request and response contract

{
  "id": "post-devices",
  "path": "/devices",
  "method": "POST",
  "security": [
    {
      "bearer": []
    }
  ],
  "responses": {
    "201": {
      "description": "Device registered"
    }
  }
}

delete_deviceDelete device.

Code

delete_device(device_id: str) -> None

Parameters

Name	Type / default	Meaning
`device_id`	`str`	Caller-supplied value of the declared type. See the linked operation or model for field constraints.

Returns

Code

None

Call example

Code

client.delete_device(device_id)

HTTP requests

DELETE /devices/{device}

Request and response contract

{
  "id": "delete-devices-device",
  "path": "/devices/{device}",
  "method": "DELETE",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "device",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "204": {
      "description": "Device revoked, including bound sessions and mount credentials"
    },
    "404": {
      "description": "Device not found"
    }
  }
}

access_keysList active machine credentials

Code

access_keys() -> list[dict[str, object]]

Parameters

No explicit arguments.

Returns

Code

list[dict[str, object]]

Call example

Code

client.access_keys()

HTTP requests

GET /access-keys

List active machine credentials

Request and response contract

{
  "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"
    }
  }
}

create_access_keyCreate a machine credential; its secret is returned exactly once

Code

create_access_key(label: str, access: str, expires_at: str | None = None, *, scope_type: str = 'account', scope_id: str | None = None) -> AccessKeyResult

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.
`expires_at`	`str \| None`Optional · None	Expiry in the declared timestamp format; server policy bounds the grant.
`scope_type`	`str`Optional · 'account'	Account/drive/drive scope as accepted by this credential operation.
`scope_id`	`str \| None`Optional · None	Account/drive/drive scope as accepted by this credential operation.

Returns

Code

AccessKeyResult

Call example

Code

client.create_access_key(label, access, expires_at, scope_type=scope_type, scope_id=scope_id)

HTTP requests

POST /access-keys

Create a machine credential; its secret is returned exactly once

Request and response contract

{
  "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"
    }
  }
}

revoke_access_keyRevoke a machine credential

Code

revoke_access_key(key_id: str) -> None

Parameters

Name	Type / default	Meaning
`key_id`	`str`	Caller-supplied value of the declared type. See the linked operation or model for field constraints.

Returns

Code

None

Call example

Code

client.revoke_access_key(key_id)

HTTP requests

DELETE /access-keys/{key}

Revoke a machine credential

Request and response contract

{
  "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

Code

mount_credentials(drive_id: str, access: str = 'write') -> dict[str, object]

Parameters

Name	Type / default	Meaning
`drive_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`access`	`str`Optional · 'write'	Requested authority within the caller’s current permitted scope.

Returns

Code

dict[str, object]

Call example

Code

client.mount_credentials(drive_id, access)

HTTP requests

POST /drives/{drive}/mount-credentials

Issue a short-lived read or write credential for one drive

Request and response contract

{
  "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"
    }
  }
}

Find and read files

search_filesSearch live names and bounded UTF-8 file text within one accessible drive

Code

search_files(drive_id: str, query: str, limit: int = 50, cursor: str | None = None) -> SearchPage

Parameters

Name	Type / default	Meaning
`drive_id`	`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`	`int`Optional · 50	Bounded page size; endpoint-specific limits apply.
`cursor`	`str \| None`Optional · None	Opaque cursor returned by this same operation and scope. Omit for the first page.

Returns

Code

SearchPage

Call example

Code

client.search_files(drive_id, query, limit, cursor)

Input and result fields

SearchPage

{
  "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.

Request and response contract

{
  "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.

Code

entries(drive: str, parent: str | None = None) -> list[Entry]

Parameters

Name	Type / default	Meaning
`drive`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`parent`	`str \| None`Optional · None	Parent folder identity, or the language’s absent value for the drive root.

Returns

Code

list[Entry]

Call example

Code

client.entries(drive, parent)

Input and result fields

Entry

{
  "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

Request and response contract

{
  "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.

Code

entry(entry_id: str) -> Entry

Parameters

Name	Type / default	Meaning
`entry_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code

Entry

Call example

Code

client.entry(entry_id)

Input and result fields

Entry

{
  "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}

Request and response contract

{
  "id": "get-entries-entry",
  "path": "/entries/{entry}",
  "method": "GET",
  "security": [
    {
      "bearer": []
    }
  ],
  "responses": {
    "200": {
      "description": "Entry metadata"
    }
  }
}

create_entryCreate entry.

Code

create_entry(drive: str, name: str, kind: str, parent: str | None = None) -> Entry

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`	`str \| None`Optional · None	Parent folder identity, or the language’s absent value for the drive root.

Returns

Code

Entry

Call example

Code

client.create_entry(drive, name, kind, parent)

Input and result fields

Entry

{
  "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

Request and response contract

{
  "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.

Code

rename_entry(entry_id: str, name: str, expected_revision: int, parent: str | None = None, *, replace: bool = True) -> Entry

Parameters

Name	Type / default	Meaning
`entry_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.
`expected_revision`	`int`	Reviewed entry or policy revision. Do not substitute a file version ID.
`parent`	`str \| None`Optional · None	Parent folder identity, or the language’s absent value for the drive root.
`replace`	`bool`Optional · True	Explicit namespace replacement behavior for the reviewed rename/move operation.

Returns

Code

Entry

Call example

Code

client.rename_entry(entry_id, name, expected_revision, parent, replace=replace)

Input and result fields

Entry

{
  "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}

Request and response contract

{
  "id": "patch-entries-entry",
  "path": "/entries/{entry}",
  "method": "PATCH",
  "security": [
    {
      "bearer": []
    }
  ],
  "responses": {
    "200": {
      "description": "Renamed or moved"
    },
    "409": {
      "description": "Revision conflict"
    }
  }
}

delete_entryDelete entry.

Code

delete_entry(entry_id: str, expected_revision: int) -> None

Parameters

Name	Type / default	Meaning
`entry_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`expected_revision`	`int`	Reviewed entry or policy revision. Do not substitute a file version ID.

Returns

Code

None

Call example

Code

client.delete_entry(entry_id, expected_revision)

HTTP requests

DELETE /entries/{entry}

Request and response contract

{
  "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"
    }
  }
}

browser_downloadAuthorize a native browser download with an interactive session.

Code

browser_download(file_id: str, version: str) -> BrowserDownloadGrant

Parameters

Name	Type / default	Meaning
`file_id`	`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

Code

BrowserDownloadGrant

Call example

Code

client.browser_download(file_id, version)

Input and result fields

BrowserDownloadGrant

{
  "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

Request and response contract

{
  "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"
    }
  }
}

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.

Code

read_range(file_id: str, offset: int, length: int) -> bytes

Parameters

Name	Type / default	Meaning
`file_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`offset`	`int`	Non-negative byte offset, not a character offset.
`length`	`int`	Byte count or logical byte size; non-negative and bounded by the operation.

Returns

Code

bytes

Call example

Code

client.read_range(file_id, offset, length)

HTTP requests

GET /files/{file}/bytes

Stream current file bytes, optionally as one HTTP byte range

Request and response contract

{
  "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"
    }
  }
}

read_range_legacyDeprecated protocol-1 chunk reader kept for data migration tools.

Code

read_range_legacy(file_id: str, offset: int, length: int) -> bytes

Parameters

Name	Type / default	Meaning
`file_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`offset`	`int`	Non-negative byte offset, not a character offset.
`length`	`int`	Byte count or logical byte size; non-negative and bounded by the operation.

Returns

Code

bytes

Call example

Code

client.read_range_legacy(file_id, offset, length)

HTTP requests

GET /files/{file}/versions/{version}/content

Resolve a version to a legacy blob URL or chunk manifest

Request and response contract

{
  "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"
    }
  }
}

POST /chunks/download-urls

Authorize reads of chunks referenced by a specific version

Request and response contract

{
  "id": "post-chunks-download-urls",
  "path": "/chunks/download-urls",
  "method": "POST",
  "summary": "Authorize reads of chunks referenced by a specific version",
  "security": [
    {
      "bearer": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "file_id",
            "version_id",
            "sha256"
          ],
          "properties": {
            "file_id": {
              "type": "string",
              "format": "uuid"
            },
            "version_id": {
              "type": "string",
              "format": "uuid"
            },
            "sha256": {
              "type": "array",
              "maxItems": 1000,
              "items": {
                "type": "string",
                "pattern": "^[0-9a-f]{64}$"
              }
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Short-lived authorized chunk URLs"
    },
    "404": {
      "description": "Chunk is not referenced by this version"
    }
  }
}

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`

upload_file_bytesUpload up to 100 MiB; retain the same body, guards and identity for retry.

Code

upload_file_bytes(file_id: str, data: bytes, expected_version: str | None, sha256: str, idempotency_key: str) -> MutationResult

Parameters

Name	Type / default	Meaning
`file_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`data`	`bytes`	Raw byte input in the declared language type; binary identities must describe these exact bytes.
`expected_version`	`str \| None`	File version precondition. None/null/empty (according to language) means no committed version, not any version.
`sha256`	`str`	Lowercase hexadecimal SHA-256 of the exact content bytes.
`idempotency_key`	`str`	Stable operation identity for exact replay. Reuse only with the same payload and preconditions.

Returns

Code

MutationResult

Call example

Code

client.upload_file_bytes(file_id, data, expected_version, sha256, idempotency_key)

Input and result fields

MutationResult

{
  "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.

Request and response contract

{
  "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"
    }
  }
}

upload_bytesUpload bytes.

Code

upload_bytes(file_id: str, expected_revision: int, content: bytes) -> Entry

Parameters

Name	Type / default	Meaning
`file_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`expected_revision`	`int`	Reviewed entry or policy revision. Do not substitute a file version ID.
`content`	`bytes`	Raw byte input in the declared language type; binary identities must describe these exact bytes.

Returns

Code

Entry

Call example

Code

client.upload_bytes(file_id, expected_revision, content)

Input and result fields

Entry

{
  "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}/uploads

Request and response contract

{
  "id": "post-files-file-uploads",
  "path": "/files/{file}/uploads",
  "method": "POST",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "file",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "201": {
      "description": "Signed PUT authorization"
    },
    "409": {
      "description": "Revision conflict"
    }
  }
}

POST /uploads/{upload}/complete

Request and response contract

{
  "id": "post-uploads-upload-complete",
  "path": "/uploads/{upload}/complete",
  "method": "POST",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "upload",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Immutable version committed"
    },
    "409": {
      "description": "Object or revision conflict"
    }
  }
}

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.

Code

write_file(file_id: str, data: bytes, if_version: str | None, *, idempotency_key: str | None = None) -> MutationResult

Parameters

Name	Type / default	Meaning
`file_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`data`	`bytes`	Raw byte input in the declared language type; binary identities must describe these exact bytes.
`if_version`	`str \| None`	File version precondition. None/null/empty (according to language) means no committed version, not any version.
`idempotency_key`	`str \| None`Optional · None	Stable operation identity for exact replay. Reuse only with the same payload and preconditions.

Returns

Code

MutationResult

Call example

Code

client.write_file(file_id, data, if_version, idempotency_key=idempotency_key)

Input and result fields

MutationResult

{
  "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

Request and response contract

{
  "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

Request and response contract

{
  "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.

Code

write_at(file_id: str, offset: int, data: bytes, if_version: str | None, *, idempotency_key: str | None = None) -> MutationResult

Parameters

Name	Type / default	Meaning
`file_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`offset`	`int`	Non-negative byte offset, not a character offset.
`data`	`bytes`	Raw byte input in the declared language type; binary identities must describe these exact bytes.
`if_version`	`str \| None`	File version precondition. None/null/empty (according to language) means no committed version, not any version.
`idempotency_key`	`str \| None`Optional · None	Stable operation identity for exact replay. Reuse only with the same payload and preconditions.

Returns

Code

MutationResult

Call example

Code

client.write_at(file_id, offset, data, if_version, idempotency_key=idempotency_key)

Input and result fields

MutationResult

{
  "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

Request and response contract

{
  "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.

Code

patch(file_id: str, changes: list[tuple[int, bytes]], if_version: str | None, *, idempotency_key: str | None = None) -> MutationResult

Parameters

Name	Type / default	Meaning
`file_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`changes`	`list[tuple[int, bytes]]`	Ordered collection of patch ranges or structured changes in the declared type.
`if_version`	`str \| None`	File version precondition. None/null/empty (according to language) means no committed version, not any version.
`idempotency_key`	`str \| None`Optional · None	Stable operation identity for exact replay. Reuse only with the same payload and preconditions.

Returns

Code

MutationResult

Call example

Code

client.patch(file_id, changes, if_version, idempotency_key=idempotency_key)

Input and result fields

MutationResult

{
  "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

Request and response contract

{
  "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.

Code

insert(file_id: str, offset: int, data: bytes, if_version: str | None, *, idempotency_key: str | None = None) -> MutationResult

Parameters

Name	Type / default	Meaning
`file_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`offset`	`int`	Non-negative byte offset, not a character offset.
`data`	`bytes`	Raw byte input in the declared language type; binary identities must describe these exact bytes.
`if_version`	`str \| None`	File version precondition. None/null/empty (according to language) means no committed version, not any version.
`idempotency_key`	`str \| None`Optional · None	Stable operation identity for exact replay. Reuse only with the same payload and preconditions.

Returns

Code

MutationResult

Call example

Code

client.insert(file_id, offset, data, if_version, idempotency_key=idempotency_key)

Input and result fields

MutationResult

{
  "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

Request and response contract

{
  "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.

Code

remove(file_id: str, offset: int, length: int, if_version: str | None, *, idempotency_key: str | None = None) -> MutationResult

Parameters

Name	Type / default	Meaning
`file_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`offset`	`int`	Non-negative byte offset, not a character offset.
`length`	`int`	Byte count or logical byte size; non-negative and bounded by the operation.
`if_version`	`str \| None`	File version precondition. None/null/empty (according to language) means no committed version, not any version.
`idempotency_key`	`str \| None`Optional · None	Stable operation identity for exact replay. Reuse only with the same payload and preconditions.

Returns

Code

MutationResult

Call example

Code

client.remove(file_id, offset, length, if_version, idempotency_key=idempotency_key)

Input and result fields

MutationResult

{
  "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

Request and response contract

{
  "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.

Code

splice(file_id: str, offset: int, length: int, data: bytes, if_version: str | None, *, idempotency_key: str | None = None) -> MutationResult

Parameters

Name	Type / default	Meaning
`file_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`offset`	`int`	Non-negative byte offset, not a character offset.
`length`	`int`	Byte count or logical byte size; non-negative and bounded by the operation.
`data`	`bytes`	Raw byte input in the declared language type; binary identities must describe these exact bytes.
`if_version`	`str \| None`	File version precondition. None/null/empty (according to language) means no committed version, not any version.
`idempotency_key`	`str \| None`Optional · None	Stable operation identity for exact replay. Reuse only with the same payload and preconditions.

Returns

Code

MutationResult

Call example

Code

client.splice(file_id, offset, length, data, if_version, idempotency_key=idempotency_key)

Input and result fields

MutationResult

{
  "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

Request and response contract

{
  "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.

Code

truncate(file_id: str, size: int, if_version: str | None, *, idempotency_key: str | None = None) -> MutationResult

Parameters

Name	Type / default	Meaning
`file_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`size`	`int`	Byte count or logical byte size; non-negative and bounded by the operation.
`if_version`	`str \| None`	File version precondition. None/null/empty (according to language) means no committed version, not any version.
`idempotency_key`	`str \| None`Optional · None	Stable operation identity for exact replay. Reuse only with the same payload and preconditions.

Returns

Code

MutationResult

Call example

Code

client.truncate(file_id, size, if_version, idempotency_key=idempotency_key)

Input and result fields

MutationResult

{
  "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

Request and response contract

{
  "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"
          }
        }
      }
    }
  }
}

resume_chunk_uploadRenew signed targets for an uncommitted chunk upload, omitting objects already present and valid

Code

resume_chunk_upload(upload_id: str) -> dict[str, object]

Parameters

Name	Type / default	Meaning
`upload_id`	`str`	Caller-supplied value of the declared type. See the linked operation or model for field constraints.

Returns

Code

dict[str, object]

Call example

Code

client.resume_chunk_upload(upload_id)

HTTP requests

POST /uploads/{upload}/resume-chunks

Renew signed targets for an uncommitted chunk upload, omitting objects already present and valid

Request and response contract

{
  "id": "post-uploads-upload-resume-chunks",
  "path": "/uploads/{upload}/resume-chunks",
  "method": "POST",
  "summary": "Renew signed targets for an uncommitted chunk upload, omitting objects already present and valid",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "upload",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Renewable upload targets"
    },
    "409": {
      "description": "Upload expired or already finalized"
    }
  }
}

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.

Code

policy = client.file_history(drive_id)
client.set_file_history(drive_id, True, policy["revision"])
# Future edits now retain earlier contents.
print(client.versions(file_id))
# Permanently remove older versions; the current file stays unchanged.
result = client.clear_file_history(file_id)
print(result["bytes_freed"])
# client.clear_drive_history(drive_id)

entries_atList a committed historical directory under current access permissions.

Code

entries_at(drive: str, sequence: int, parent: str | None = None) -> list[Entry]

Parameters

Name	Type / default	Meaning
`drive`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`sequence`	`int`	Committed drive sequence (non-negative int64). TypeScript uses bigint beyond safe integer precision.
`parent`	`str \| None`Optional · None	Parent folder identity, or the language’s absent value for the drive root.

Returns

Code

list[Entry]

Call example

Code

client.entries_at(drive, sequence, parent)

Input and result fields

Entry

{
  "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

Request and response contract

{
  "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

Code

file_history(drive_id: str) -> FileHistoryPolicy

Parameters

Name	Type / default	Meaning
`drive_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code

FileHistoryPolicy

Call example

Code

client.file_history(drive_id)

Input and result fields

FileHistoryPolicy

{
  "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

Request and response contract

{
  "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

Code

set_file_history(drive_id: str, enabled: bool, expected_revision: str) -> FileHistoryPolicy

Parameters

Name	Type / default	Meaning
`drive_id`	`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

Code

FileHistoryPolicy

Call example

Code

client.set_file_history(drive_id, enabled, expected_revision)

Input and result fields

FileHistoryPolicy

{
  "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

Request and response contract

{
  "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

Code

clear_drive_history(drive_id: str) -> HistoryCleanupResult

Parameters

Name	Type / default	Meaning
`drive_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code

HistoryCleanupResult

Call example

Code

client.clear_drive_history(drive_id)

Input and result fields

HistoryCleanupResult

{
  "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

Request and response contract

{
  "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

Code

clear_file_history(file_id: str) -> HistoryCleanupResult

Parameters

Name	Type / default	Meaning
`file_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code

HistoryCleanupResult

Call example

Code

client.clear_file_history(file_id)

Input and result fields

HistoryCleanupResult

{
  "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

Request and response contract

{
  "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.

Code

recent_versions(drive_id: str, limit: int = 30) -> list[VersionSummary]

Parameters

Name	Type / default	Meaning
`drive_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`limit`	`int`Optional · 30	Bounded page size; endpoint-specific limits apply.

Returns

Code

list[VersionSummary]

Call example

Code

client.recent_versions(drive_id, limit)

Input and result fields

VersionSummary

{
  "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

Request and response contract

{
  "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.

Code

versions(file_id: str) -> list[Version]

Parameters

Name	Type / default	Meaning
`file_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code

list[Version]

Call example

Code

client.versions(file_id)

Input and result fields

Version

{
  "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

Request and response contract

{
  "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.

Code

restore_version(file_id: str, version_id: str, expected_revision: int) -> Entry

Parameters

Name	Type / default	Meaning
`file_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`version_id`	`str`	Immutable committed version identity to read, restore or share.
`expected_revision`	`int`	Reviewed entry or policy revision. Do not substitute a file version ID.

Returns

Code

Entry

Call example

Code

client.restore_version(file_id, version_id, expected_revision)

Input and result fields

Entry

{
  "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

Request and response contract

{
  "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.

Code

read_version_range(file_id: str, version_id: str, offset: int, length: int) -> bytes

Parameters

Name	Type / default	Meaning
`file_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`version_id`	`str`	Immutable committed version identity to read, restore or share.
`offset`	`int`	Non-negative byte offset, not a character offset.
`length`	`int`	Byte count or logical byte size; non-negative and bounded by the operation.

Returns

Code

bytes

Call example

Code

client.read_version_range(file_id, version_id, offset, length)

HTTP requests

GET /files/{file}/versions/{version}/bytes

Stream bytes from one immutable historical version

Request and response contract

{
  "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

Code

request_otp(endpoint: str, email: str) -> OTPChallenge

Parameters

Name	Type / default	Meaning
`endpoint`	`str`	API origin without /v1; HTTPS outside local development.
`email`	`str`	Account or invitation email address.

Returns

Code

OTPChallenge

Call example

Code

Client.request_otp(endpoint, email)

Input and result fields

OTPChallenge

{
  "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.

Request and response contract

{
  "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

Code

verify_otp(endpoint: str, challenge_id: str, code: str) -> tuple['Client', AuthSession]

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

Code

tuple['Client', AuthSession]

Call example

Code

Client.verify_otp(endpoint, challenge_id, code)

Input and result fields

AuthSession

{
  "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

Request and response contract

{
  "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.

Code

drives() -> list[Drive]

Parameters

No explicit arguments.

Returns

Code

list[Drive]

Call example

Code

client.drives()

Input and result fields

Drive

{
  "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

Request and response contract

{
  "id": "get-drives",
  "path": "/drives",
  "method": "GET",
  "security": [
    {
      "bearer": []
    }
  ],
  "responses": {
    "200": {
      "description": "Drives visible to the current identity, filtered by key scope"
    }
  }
}

driveDrive.

Code

drive(drive_id: str) -> Drive

Parameters

Name	Type / default	Meaning
`drive_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code

Drive

Call example

Code

client.drive(drive_id)

Input and result fields

Drive

{
  "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}

Request and response contract

{
  "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

Code

platform_configuration() -> dict

Parameters

No explicit arguments.

Returns

Code

dict

Call example

Code

client.platform_configuration()

HTTP requests

GET /platform/config

Platform administrator draft and published configuration

Request and response contract

{
  "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

Code

save_platform_configuration(document: dict, expected_revision: str, publish: bool = False) -> dict

Parameters

Name	Type / default	Meaning
`document`	`dict`	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`Optional · False	Caller-supplied value of the declared type. See the linked operation or model for field constraints.

Returns

Code

dict

Call example

Code

client.save_platform_configuration(document, expected_revision, publish)

HTTP requests

PUT /platform/config

Save a draft or publish product settings; platform administrator only

Request and response contract

{
  "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

Code

plans() -> dict

Parameters

No explicit arguments.

Returns

Code

dict

Call example

Code

client.plans()

HTTP requests

GET /plans

Published monthly plans and add-on terms

Request and response contract

{
  "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

Code

subscription(drive: str) -> DriveSubscription

Parameters

Name	Type / default	Meaning
`drive`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code

DriveSubscription

Call example

Code

client.subscription(drive)

Input and result fields

DriveSubscription

{
  "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

Request and response contract

{
  "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

Code

change_subscription(drive: str, storage_bytes: int, seats: int, expected_revision: str, cancel_at_period_end: bool = False, plan_version_id: str | None = None) -> DriveSubscription

Parameters

Name	Type / default	Meaning
`drive`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`storage_bytes`	`int`	Caller-supplied value of the declared type. See the linked operation or model for field constraints.
`seats`	`int`	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.
`cancel_at_period_end`	`bool`Optional · False	Caller-supplied value of the declared type. See the linked operation or model for field constraints.
`plan_version_id`	`str \| None`Optional · None	Immutable committed version identity to read, restore or share.

Returns

Code

DriveSubscription

Call example

Code

client.change_subscription(drive, storage_bytes, seats, expected_revision, cancel_at_period_end, plan_version_id)

Input and result fields

DriveSubscription

{
  "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

PUT /drives/{drive}/subscription

Development checkout for subscription changes; production requires billing configuration

Request and response contract

{
  "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

Code

leave_drive(drive: str) -> None

Parameters

Name	Type / default	Meaning
`drive`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code

None

Call example

Code

client.leave_drive(drive)

HTTP requests

DELETE /drives/{drive}/membership

Leave a shared drive; the owner cannot leave

Request and response contract

{
  "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

Code

create_drive(name: str, storage_bytes: int, seats: int, plan_version_id: str | None = None) -> Drive

Parameters

Name	Type / default	Meaning
`name`	`str`	Name or label accepted by this operation; it must meet server constraints.
`storage_bytes`	`int`	Caller-supplied value of the declared type. See the linked operation or model for field constraints.
`seats`	`int`	Caller-supplied value of the declared type. See the linked operation or model for field constraints.
`plan_version_id`	`str \| None`Optional · None	Immutable committed version identity to read, restore or share.

Returns

Code

Drive

Call example

Code

client.create_drive(name, storage_bytes, seats, plan_version_id)

Input and result fields

Drive

{
  "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

Request and response contract

{
  "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.

Code

delete_drive(drive_id: str) -> None

Parameters

Name	Type / default	Meaning
`drive_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code

None

Call example

Code

client.delete_drive(drive_id)

HTTP requests

DELETE /drives/{drive}

Request and response contract

{
  "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"
    }
  }
}

create_snapshotCapture one immutable, complete drive state

Code

create_snapshot(drive_id: str) -> Snapshot

Parameters

Name	Type / default	Meaning
`drive_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code

Snapshot

Call example

Code

client.create_snapshot(drive_id)

Input and result fields

Snapshot

{
  "type": "object",
  "required": [
    "id",
    "drive_id",
    "created_by",
    "created_at",
    "entry_count"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "created_by": {
      "type": "string",
      "format": "uuid"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "entry_count": {
      "type": "integer",
      "format": "int64"
    }
  }
}

HTTP requests

POST /drives/{drive}/snapshots

Capture one immutable, complete drive state

Request and response contract

{
  "id": "post-drives-drive-snapshots",
  "path": "/drives/{drive}/snapshots",
  "method": "POST",
  "summary": "Capture one immutable, complete drive state",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "drive",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "201": {
      "description": "Snapshot created"
    },
    "404": {
      "description": "Drive not found"
    }
  }
}

snapshotRetrieve a snapshot and its exact namespace references

Code

snapshot(drive_id: str, snapshot_id: str) -> dict[str, object]

Parameters

Name	Type / default	Meaning
`drive_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`snapshot_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code

dict[str, object]

Call example

Code

client.snapshot(drive_id, snapshot_id)

HTTP requests

GET /drives/{drive}/snapshots/{snapshot}

Retrieve a snapshot and its exact namespace references

Request and response contract

{
  "id": "get-drives-drive-snapshots-snapshot",
  "path": "/drives/{drive}/snapshots/{snapshot}",
  "method": "GET",
  "summary": "Retrieve a snapshot and its exact namespace references",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "drive",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "snapshot",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Snapshot and entries"
    },
    "404": {
      "description": "Snapshot not found"
    }
  }
}

branchesBranches.

Code

branches(drive_id: str) -> list[Branch]

Parameters

Name	Type / default	Meaning
`drive_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code

list[Branch]

Call example

Code

client.branches(drive_id)

Input and result fields

Branch

{
  "type": "object",
  "required": [
    "id",
    "source_drive_id",
    "base_snapshot_id",
    "drive_id",
    "name",
    "status",
    "created_by",
    "created_at",
    "updated_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "source_drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "base_snapshot_id": {
      "type": "string",
      "format": "uuid"
    },
    "drive_id": {
      "type": "string",
      "format": "uuid",
      "description": "Filesystem scope to mount through nufs-engine"
    },
    "name": {
      "type": "string"
    },
    "task_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "status": {
      "enum": [
        "active",
        "integrated",
        "discarded"
      ]
    },
    "created_by": {
      "type": "string",
      "format": "uuid"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    },
    "integrated_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "discarded_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    }
  }
}

HTTP requests

GET /drives/{drive}/branches

Request and response contract

{
  "id": "get-drives-drive-branches",
  "path": "/drives/{drive}/branches",
  "method": "GET",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "drive",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Branches; an empty drive returns an empty array, never null",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "branches"
            ],
            "properties": {
              "branches": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Branch"
                }
              }
            }
          }
        }
      }
    }
  }
}

create_branchCreate an isolated branch from an explicit drive snapshot

Code

create_branch(drive_id: str, snapshot_id: str, name: str, task_id: str | None = None) -> Branch

Parameters

Name	Type / default	Meaning
`drive_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`snapshot_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.
`task_id`	`str \| None`Optional · None	Caller-supplied value of the declared type. See the linked operation or model for field constraints.

Returns

Code

Branch

Call example

Code

client.create_branch(drive_id, snapshot_id, name, task_id)

Input and result fields

Branch

{
  "type": "object",
  "required": [
    "id",
    "source_drive_id",
    "base_snapshot_id",
    "drive_id",
    "name",
    "status",
    "created_by",
    "created_at",
    "updated_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "source_drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "base_snapshot_id": {
      "type": "string",
      "format": "uuid"
    },
    "drive_id": {
      "type": "string",
      "format": "uuid",
      "description": "Filesystem scope to mount through nufs-engine"
    },
    "name": {
      "type": "string"
    },
    "task_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "status": {
      "enum": [
        "active",
        "integrated",
        "discarded"
      ]
    },
    "created_by": {
      "type": "string",
      "format": "uuid"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    },
    "integrated_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "discarded_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    }
  }
}

HTTP requests

POST /drives/{drive}/branches

Create an isolated branch from an explicit drive snapshot

Request and response contract

{
  "id": "post-drives-drive-branches",
  "path": "/drives/{drive}/branches",
  "method": "POST",
  "summary": "Create an isolated branch from an explicit drive snapshot",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "drive",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "base_snapshot_id",
            "name"
          ],
          "properties": {
            "base_snapshot_id": {
              "type": "string",
              "format": "uuid"
            },
            "name": {
              "type": "string"
            },
            "task_id": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Persistent branch created"
    },
    "404": {
      "description": "Snapshot not found"
    }
  }
}

branchBranch.

Code

branch(branch_id: str) -> Branch

Parameters

Name	Type / default	Meaning
`branch_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code

Branch

Call example

Code

client.branch(branch_id)

Input and result fields

Branch

{
  "type": "object",
  "required": [
    "id",
    "source_drive_id",
    "base_snapshot_id",
    "drive_id",
    "name",
    "status",
    "created_by",
    "created_at",
    "updated_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "source_drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "base_snapshot_id": {
      "type": "string",
      "format": "uuid"
    },
    "drive_id": {
      "type": "string",
      "format": "uuid",
      "description": "Filesystem scope to mount through nufs-engine"
    },
    "name": {
      "type": "string"
    },
    "task_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "status": {
      "enum": [
        "active",
        "integrated",
        "discarded"
      ]
    },
    "created_by": {
      "type": "string",
      "format": "uuid"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    },
    "integrated_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "discarded_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    }
  }
}

HTTP requests

GET /branches/{branch}

Request and response contract

{
  "id": "get-branches-branch",
  "path": "/branches/{branch}",
  "method": "GET",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "branch",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Branch metadata"
    },
    "404": {
      "description": "Branch not found"
    }
  }
}

create_branch_access_keyCreate an expiring machine credential scoped to one active branch

Code

create_branch_access_key(branch_id: str, label: str, access: str = 'write', expires_at: str | None = None) -> BranchAccessKeyResult

Parameters

Name	Type / default	Meaning
`branch_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`label`	`str`	Name or label accepted by this operation; it must meet server constraints.
`access`	`str`Optional · 'write'	Requested authority within the caller’s current permitted scope.
`expires_at`	`str \| None`Optional · None	Expiry in the declared timestamp format; server policy bounds the grant.

Returns

Code

BranchAccessKeyResult

Call example

Code

client.create_branch_access_key(branch_id, label, access, expires_at)

HTTP requests

POST /branches/{branch}/access-key

Create an expiring machine credential scoped to one active branch

Request and response contract

{
  "id": "post-branches-branch-access-key",
  "path": "/branches/{branch}/access-key",
  "method": "POST",
  "summary": "Create an expiring machine credential scoped to one active branch",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "branch",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "201": {
      "description": "Branch key and one-time secret"
    },
    "401": {
      "description": "Interactive session required"
    }
  }
}

branch_changesBranch changes.

Code

branch_changes(branch_id: str) -> list[BranchChange]

Parameters

Name	Type / default	Meaning
`branch_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code

list[BranchChange]

Call example

Code

client.branch_changes(branch_id)

Input and result fields

BranchChange

{
  "type": "object",
  "required": [
    "status",
    "branch_entry_id",
    "name",
    "path",
    "kind",
    "logical_size"
  ],
  "properties": {
    "status": {
      "enum": [
        "added",
        "modified",
        "deleted"
      ]
    },
    "base_entry_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "branch_entry_id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "path": {
      "type": "string",
      "description": "Current path in the branch"
    },
    "base_path": {
      "type": [
        "string",
        "null"
      ],
      "description": "Path in the immutable base snapshot"
    },
    "kind": {
      "enum": [
        "file",
        "folder"
      ]
    },
    "base_version_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "version_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "logical_size": {
      "type": "integer",
      "format": "int64"
    },
    "actor_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Latest authenticated actor for this branch entry when available"
    }
  }
}

HTTP requests

GET /branches/{branch}/changes

Request and response contract

{
  "id": "get-branches-branch-changes",
  "path": "/branches/{branch}/changes",
  "method": "GET",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "branch",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Added, modified, and deleted entries relative to the base snapshot",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "changes"
            ],
            "properties": {
              "changes": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/BranchChange"
                }
              }
            }
          }
        }
      }
    }
  }
}

integrate_branchAtomically integrate branch changes if target entries still match the base snapshot

Code

integrate_branch(branch_id: str) -> IntegrationResult

Parameters

Name	Type / default	Meaning
`branch_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code

IntegrationResult

Call example

Code

client.integrate_branch(branch_id)

HTTP requests

POST /branches/{branch}/integrate

Atomically integrate branch changes if target entries still match the base snapshot

Request and response contract

{
  "id": "post-branches-branch-integrate",
  "path": "/branches/{branch}/integrate",
  "method": "POST",
  "summary": "Atomically integrate branch changes if target entries still match the base snapshot",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "branch",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Changes integrated"
    },
    "409": {
      "description": "Integration conflict with both states preserved"
    }
  }
}

discard_branchMark an active branch discarded without deleting shared immutable content

Code

discard_branch(branch_id: str) -> Branch

Parameters

Name	Type / default	Meaning
`branch_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code

Branch

Call example

Code

client.discard_branch(branch_id)

Input and result fields

Branch

{
  "type": "object",
  "required": [
    "id",
    "source_drive_id",
    "base_snapshot_id",
    "drive_id",
    "name",
    "status",
    "created_by",
    "created_at",
    "updated_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "source_drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "base_snapshot_id": {
      "type": "string",
      "format": "uuid"
    },
    "drive_id": {
      "type": "string",
      "format": "uuid",
      "description": "Filesystem scope to mount through nufs-engine"
    },
    "name": {
      "type": "string"
    },
    "task_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "status": {
      "enum": [
        "active",
        "integrated",
        "discarded"
      ]
    },
    "created_by": {
      "type": "string",
      "format": "uuid"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    },
    "integrated_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "discarded_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    }
  }
}

HTTP requests

POST /branches/{branch}/discard

Mark an active branch discarded without deleting shared immutable content

Request and response contract

{
  "id": "post-branches-branch-discard",
  "path": "/branches/{branch}/discard",
  "method": "POST",
  "summary": "Mark an active branch discarded without deleting shared immutable content",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "branch",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Branch discarded"
    },
    "409": {
      "description": "Branch is no longer active"
    }
  }
}

Share files and accept uploads

public_configurationPublished plans, installer links and product availability

Code

public_configuration() -> dict

Parameters

No explicit arguments.

Returns

Code

dict

Call example

Code

client.public_configuration()

HTTP requests

GET /public/config

Published plans, installer links and product availability

Request and response contract

{
  "id": "get-public-config",
  "path": "/public/config",
  "method": "GET",
  "summary": "Published plans, installer links and product availability",
  "security": [],
  "responses": {
    "200": {
      "description": "Published plans, installer links and product availability",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PublicConfiguration"
          }
        }
      }
    },
    "503": {
      "description": "Configuration unavailable"
    }
  }
}

create_public_file_linkCreate public file link.

Code

create_public_file_link(file_id: str, version_id: str, expires_at: str) -> PublicFileLinkResult

Parameters

Name	Type / default	Meaning
`file_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`version_id`	`str`	Immutable committed version identity to read, restore or share.
`expires_at`	`str`	Expiry in the declared timestamp format; server policy bounds the grant.

Returns

Code

PublicFileLinkResult

Call example

Code

client.create_public_file_link(file_id, version_id, expires_at)

Input and result fields

PublicFileLinkResult

{
  "type": "object",
  "required": [
    "file_link",
    "secret"
  ],
  "properties": {
    "file_link": {
      "$ref": "#/components/schemas/PublicFileLink"
    },
    "secret": {
      "type": "string"
    }
  }
}

HTTP requests

POST /files/{file}/links

Interactive drive administrators select one immutable version. Required expiry is in the future and at most 90 days away. Active links pin that version against retention. The secret is returned once.

Request and response contract

{
  "id": "post-files-file-links",
  "path": "/files/{file}/links",
  "method": "POST",
  "security": [
    {
      "bearer": []
    }
  ],
  "description": "Interactive drive administrators select one immutable version. Required expiry is in the future and at most 90 days away. Active links pin that version against retention. The secret is returned once.",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "version_id",
            "expires_at"
          ],
          "properties": {
            "version_id": {
              "type": "string",
              "format": "uuid"
            },
            "expires_at": {
              "type": "string",
              "format": "date-time"
            }
          }
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Immutable link and one-time secret",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PublicFileLinkResult"
          }
        }
      }
    },
    "400": {
      "description": "Invalid version or expiry"
    },
    "401": {
      "description": "Interactive session required"
    },
    "404": {
      "description": "File or version unavailable to administrator"
    }
  }
}

public_file_linksPublic file links.

Code

public_file_links(file_id: str, after: str | None = None) -> PublicFileLinkPage

Parameters

Name	Type / default	Meaning
`file_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`after`	`str \| None`Optional · None	Opaque cursor returned by this same operation and scope. Omit for the first page.

Returns

Code

PublicFileLinkPage

Call example

Code

client.public_file_links(file_id, after)

HTTP requests

GET /files/{file}/links

Administrator-only keyset listing of at most 100 links. No secrets or digests are returned.

Request and response contract

{
  "id": "get-files-file-links",
  "path": "/files/{file}/links",
  "method": "GET",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "after",
      "in": "query",
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "description": "Administrator-only keyset listing of at most 100 links. No secrets or digests are returned.",
  "responses": {
    "200": {
      "description": "Link metadata page",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "file_links",
              "next_cursor"
            ],
            "properties": {
              "file_links": {
                "type": "array",
                "maxItems": 100,
                "items": {
                  "$ref": "#/components/schemas/PublicFileLink"
                }
              },
              "next_cursor": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uuid"
              }
            }
          }
        }
      }
    },
    "404": {
      "description": "File unavailable to administrator"
    }
  }
}

revoke_public_file_linkRevoke public file link.

Code

revoke_public_file_link(file_id: str, link_id: str) -> None

Parameters

Name	Type / default	Meaning
`file_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`link_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code

None

Call example

Code

client.revoke_public_file_link(file_id, link_id)

HTTP requests

DELETE /files/{file}/links/{link}

Administrator revocation denies subsequent public requests. A stream already started may finish.

Request and response contract

{
  "id": "delete-files-file-links-link",
  "path": "/files/{file}/links/{link}",
  "method": "DELETE",
  "security": [
    {
      "bearer": []
    }
  ],
  "description": "Administrator revocation denies subsequent public requests. A stream already started may finish.",
  "responses": {
    "204": {
      "description": "Link revoked"
    },
    "404": {
      "description": "Link unavailable to administrator"
    }
  }
}

public_file_linkUse a separate Client with the public-link secret as its credential.

Code

public_file_link() -> PublicFileRead

Parameters

No explicit arguments.

Returns

Code

PublicFileRead

Call example

Code

client.public_file_link()

Input and result fields

PublicFileRead

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "file_name",
    "version_id",
    "logical_size",
    "checksum_sha256",
    "expires_at"
  ],
  "properties": {
    "file_name": {
      "type": "string"
    },
    "version_id": {
      "type": "string",
      "format": "uuid"
    },
    "logical_size": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9223372036854776000
    },
    "checksum_sha256": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9a-f]{64}$",
      "description": "Whole-file checksum when available; null for extent versions without a computed whole-file digest."
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}

HTTP requests

GET /public/file-link

Minimal immutable metadata. Unknown and expired or revoked bearers all return 404. Loss of creator administrative access also denies reads.

Request and response contract

{
  "id": "get-public-file-link",
  "path": "/public/file-link",
  "method": "GET",
  "security": [
    {
      "publicFileLink": []
    }
  ],
  "description": "Minimal immutable metadata. Unknown and expired or revoked bearers all return 404. Loss of creator administrative access also denies reads.",
  "responses": {
    "200": {
      "description": "Public file metadata",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PublicFileRead"
          }
        }
      }
    },
    "404": {
      "description": "Link unavailable"
    }
  }
}

read_public_file_rangeRead public file range.

Code

read_public_file_range(offset: int, length: int) -> bytes

Parameters

Name	Type / default	Meaning
`offset`	`int`	Non-negative byte offset, not a character offset.
`length`	`int`	Byte count or logical byte size; non-negative and bounded by the operation.

Returns

Code

bytes

Call example

Code

client.read_public_file_range(offset, length)

HTTP requests

GET /public/file-link/bytes

Streams the selected immutable version using canonical range reads. The bearer never permits namespace browsing or mutations.

Request and response contract

{
  "id": "get-public-file-link-bytes",
  "path": "/public/file-link/bytes",
  "method": "GET",
  "security": [
    {
      "publicFileLink": []
    }
  ],
  "description": "Streams the selected immutable version using canonical range reads. The bearer never permits namespace browsing or mutations.",
  "responses": {
    "200": {
      "description": "Complete immutable bytes",
      "content": {
        "application/octet-stream": {
          "schema": {
            "type": "string",
            "format": "binary"
          }
        }
      }
    },
    "206": {
      "description": "Immutable byte range",
      "content": {
        "application/octet-stream": {
          "schema": {
            "type": "string",
            "format": "binary"
          }
        }
      }
    },
    "404": {
      "description": "Link unavailable"
    },
    "416": {
      "description": "Unsatisfiable range"
    }
  }
}

create_upload_requestCreate upload request.

Code

create_upload_request(drive_id: str, policy: UploadRequestInput) -> UploadRequestResult

Parameters

Name	Type / default	Meaning
`drive_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`policy`	`UploadRequestInput`	Structured input of the declared type; use the linked schema for required fields and constraints.

Returns

Code

UploadRequestResult

Call example

Code

client.create_upload_request(drive_id, policy)

Input and result fields

UploadRequestInput

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "title",
    "max_files",
    "max_file_bytes",
    "max_total_bytes",
    "expires_at"
  ],
  "properties": {
    "parent_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "max_files": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "max_file_bytes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 104857600
    },
    "max_total_bytes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1073741824
    },
    "allowed_extensions": {
      "type": "array",
      "maxItems": 20,
      "items": {
        "type": "string",
        "pattern": "^\\.[a-z0-9]{1,15}$"
      }
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}

UploadRequestResult

{
  "type": "object",
  "required": [
    "upload_request",
    "secret"
  ],
  "properties": {
    "upload_request": {
      "$ref": "#/components/schemas/UploadRequest"
    },
    "secret": {
      "type": "string"
    }
  }
}

HTTP requests

POST /drives/{drive}/upload-requests

Interactive administrators create a fixed-destination request with expiry and file/byte/extension limits. Bearer is returned once. At most ten attempts per allowed file and three times the total byte budget may be reserved across failed attempts.

Request and response contract

{
  "id": "post-drives-drive-upload-requests",
  "path": "/drives/{drive}/upload-requests",
  "method": "POST",
  "security": [
    {
      "bearer": []
    }
  ],
  "description": "Interactive administrators create a fixed-destination request with expiry and file/byte/extension limits. Bearer is returned once. At most ten attempts per allowed file and three times the total byte budget may be reserved across failed attempts.",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/UploadRequestInput"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Request and one-time bearer",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/UploadRequestResult"
          }
        }
      }
    },
    "400": {
      "description": "Invalid limits or expiry"
    },
    "401": {
      "description": "Interactive session required"
    },
    "404": {
      "description": "Destination unavailable to administrator"
    }
  }
}

upload_requestsUpload requests.

Code

upload_requests(drive_id: str, after: str | None = None) -> UploadRequestPage

Parameters

Name	Type / default	Meaning
`drive_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`after`	`str \| None`Optional · None	Opaque cursor returned by this same operation and scope. Omit for the first page.

Returns

Code

UploadRequestPage

Call example

Code

client.upload_requests(drive_id, after)

HTTP requests

GET /drives/{drive}/upload-requests

Request and response contract

{
  "id": "get-drives-drive-upload-requests",
  "path": "/drives/{drive}/upload-requests",
  "method": "GET",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "after",
      "in": "query",
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Secret-free metadata page",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "upload_requests",
              "next_cursor"
            ],
            "properties": {
              "upload_requests": {
                "type": "array",
                "maxItems": 100,
                "items": {
                  "$ref": "#/components/schemas/UploadRequest"
                }
              },
              "next_cursor": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uuid"
              }
            }
          }
        }
      }
    },
    "404": {
      "description": "Destination unavailable to administrator"
    }
  }
}

revoke_upload_requestRevoke upload request.

Code

revoke_upload_request(drive_id: str, request_id: str) -> None

Parameters

Name	Type / default	Meaning
`drive_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`request_id`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code

None

Call example

Code

client.revoke_upload_request(drive_id, request_id)

HTTP requests

DELETE /drives/{drive}/upload-requests/{request}

Request and response contract

{
  "id": "delete-drives-drive-upload-requests-request",
  "path": "/drives/{drive}/upload-requests/{request}",
  "method": "DELETE",
  "security": [
    {
      "bearer": []
    }
  ],
  "responses": {
    "204": {
      "description": "Request revoked; pending publication also denied"
    },
    "404": {
      "description": "Request unavailable to administrator"
    }
  }
}

public_upload_requestUse a separate client carrying only the request bearer.

Code

public_upload_request() -> PublicUploadRequest

Parameters

No explicit arguments.

Returns

Code

PublicUploadRequest

Call example

Code

client.public_upload_request()

Input and result fields

PublicUploadRequest

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "title",
    "max_files",
    "max_file_bytes",
    "max_total_bytes",
    "allowed_extensions",
    "expires_at"
  ],
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "max_files": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "max_file_bytes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 104857600
    },
    "max_total_bytes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1073741824
    },
    "allowed_extensions": {
      "type": "array",
      "maxItems": 20,
      "items": {
        "type": "string",
        "pattern": "^\\.[a-z0-9]{1,15}$"
      }
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}

HTTP requests

GET /public/upload-request

Request and response contract

{
  "id": "get-public-upload-request",
  "path": "/public/upload-request",
  "method": "GET",
  "security": [
    {
      "uploadRequest": []
    }
  ],
  "responses": {
    "200": {
      "description": "Public limits without private destination identifiers",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PublicUploadRequest"
          }
        }
      }
    },
    "404": {
      "description": "Request unavailable"
    }
  }
}

upload_requested_fileUpload requested file.

Code

upload_requested_file(name: str, data: bytes, sha256: str, idempotency_key: str) -> UploadReceipt

Parameters

Name	Type / default	Meaning
`name`	`str`	Name or label accepted by this operation; it must meet server constraints.
`data`	`bytes`	Raw byte input in the declared language type; binary identities must describe these exact bytes.
`sha256`	`str`	Lowercase hexadecimal SHA-256 of the exact content bytes.
`idempotency_key`	`str`	Stable operation identity for exact replay. Reuse only with the same payload and preconditions.

Returns

Code

UploadReceipt

Call example

Code

client.upload_requested_file(name, data, sha256, idempotency_key)

Input and result fields

UploadReceipt

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "receipt_id",
    "file_name",
    "size_bytes",
    "sha256",
    "idempotent_replay"
  ],
  "properties": {
    "receipt_id": {
      "type": "string",
      "format": "uuid"
    },
    "file_name": {
      "type": "string"
    },
    "size_bytes": {
      "type": "integer",
      "minimum": 0,
      "maximum": 104857600
    },
    "sha256": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$"
    },
    "idempotent_replay": {
      "type": "boolean"
    }
  }
}

HTTP requests

POST /public/upload-request/files

Binary upload to the configured destination only. A stable identity binds encoded single filename, size and SHA-256. Active ten-minute reservations count toward limits. Publication rechecks expiry/revocation/authority/quota and atomically creates one new file/version. A committed retry returns the same receipt without ingesting another body.

Request and response contract

{
  "id": "post-public-upload-request-files",
  "path": "/public/upload-request/files",
  "method": "POST",
  "security": [
    {
      "uploadRequest": []
    }
  ],
  "description": "Binary upload to the configured destination only. A stable identity binds encoded single filename, size and SHA-256. Active ten-minute reservations count toward limits. Publication rechecks expiry/revocation/authority/quota and atomically creates one new file/version. A committed retry returns the same receipt without ingesting another body.",
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      }
    },
    {
      "name": "X-File-Name",
      "in": "header",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Percent-encoded single filename"
    },
    {
      "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",
          "maxLength": 104857600
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Original committed receipt",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/UploadReceipt"
          }
        }
      }
    },
    "201": {
      "description": "New file committed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/UploadReceipt"
          }
        }
      }
    },
    "400": {
      "description": "Invalid filename/length or incomplete/incorrect content"
    },
    "404": {
      "description": "Request unavailable"
    },
    "409": {
      "description": "Identity or filename conflict"
    },
    "413": {
      "description": "Request budget exceeded"
    },
    "429": {
      "description": "Active lease or request pacing; Retry-After is one second"
    },
    "503": {
      "description": "Storage unavailable; retry same identity"
    },
    "507": {
      "description": "Destination quota exceeded"
    }
  }
}

Manage members and audit activity

platform_auditLatest 100 product configuration changes; platform administrator only

Code

platform_audit() -> list[dict]

Parameters

No explicit arguments.

Returns

Code

list[dict]

Call example

Code

client.platform_audit()

HTTP requests

GET /platform/audit

Latest 100 product configuration changes; platform administrator only

Request and response contract

{
  "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"
    }
  }
}

member_policyRead explicit drive member limit and occupied seats

Code

member_policy(drive: str) -> DriveMemberPolicy

Parameters

Name	Type / default	Meaning
`drive`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code

DriveMemberPolicy

Call example

Code

client.member_policy(drive)

Input and result fields

DriveMemberPolicy

{
  "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.

Request and response contract

{
  "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_auditRead a bounded page of account audit history

Code

account_audit(limit: int = 50, cursor: str | None = None) -> AuditPage

Parameters

Name	Type / default	Meaning
`limit`	`int`Optional · 50	Bounded page size; endpoint-specific limits apply.
`cursor`	`str \| None`Optional · None	Opaque cursor returned by this same operation and scope. Omit for the first page.

Returns

Code

AuditPage

Call example

Code

client.account_audit(limit, cursor)

Input and result fields

AuditPage

{
  "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.

Request and response contract

{
  "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"
    }
  }
}

account_audit_retention_policyRead account audit retention policy

Code

account_audit_retention_policy() -> AccountAuditRetentionPolicy

Parameters

No explicit arguments.

Returns

Code

AccountAuditRetentionPolicy

Call example

Code

client.account_audit_retention_policy()

Input and result fields

AccountAuditRetentionPolicy

{
  "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.

Request and response contract

{
  "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

Code

update_account_audit_retention_policy(keep_days: int | None, expected_revision: str) -> AccountAuditRetentionPolicy

Parameters

Name	Type / default	Meaning
`keep_days`	`int \| None`	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

Code

AccountAuditRetentionPolicy

Call example

Code

client.update_account_audit_retention_policy(keep_days, expected_revision)

Input and result fields

AccountAuditRetentionPolicy

{
  "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.

Request and response contract

{
  "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

Code

audit_retention_policy(drive: str) -> AuditRetentionPolicy

Parameters

Name	Type / default	Meaning
`drive`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code

AuditRetentionPolicy

Call example

Code

client.audit_retention_policy(drive)

Input and result fields

AuditRetentionPolicy

{
  "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.

Request and response contract

{
  "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

Code

update_audit_retention_policy(drive: str, keep_days: int | None, expected_revision: str) -> AuditRetentionPolicy

Parameters

Name	Type / default	Meaning
`drive`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`keep_days`	`int \| None`	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

Code

AuditRetentionPolicy

Call example

Code

client.update_audit_retention_policy(drive, keep_days, expected_revision)

Input and result fields

AuditRetentionPolicy

{
  "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.

Request and response contract

{
  "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.

Code

export_drive_audit(drive: str, output: BinaryIO, page_limit: int = 200) -> int

Parameters

Name	Type / default	Meaning
`drive`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`output`	`BinaryIO`	Caller-owned output destination. Output failures prevent successful completion.
`page_limit`	`int`Optional · 200	Bounded page size; endpoint-specific limits apply.

Returns

Code

int

Call example

Code

client.export_drive_audit(drive, output, page_limit)

drive_auditRead a bounded page of drive audit history

Code

drive_audit(drive: str, limit: int = 50, cursor: str | None = None) -> AuditPage

Parameters

Name	Type / default	Meaning
`drive`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.
`limit`	`int`Optional · 50	Bounded page size; endpoint-specific limits apply.
`cursor`	`str \| None`Optional · None	Opaque cursor returned by this same operation and scope. Omit for the first page.

Returns

Code

AuditPage

Call example

Code

client.drive_audit(drive, limit, cursor)

Input and result fields

AuditPage

{
  "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.

Request and response contract

{
  "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"
    }
  }
}

drive_membersDrive members.

Code

drive_members(drive: str) -> list[DriveMember]

Parameters

Name	Type / default	Meaning
`drive`	`str`	Target identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code

list[DriveMember]

Call example

Code

client.drive_members(drive)

Input and result fields

DriveMember

{
  "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

Request and response contract

{
  "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.

Code

invite_drive_member(drive: str, email: str, role: Literal['viewer', 'editor', 'admin']) -> InvitationResult

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`	`Literal['viewer', 'editor', 'admin']`	Requested member role. The drive owner cannot be changed.

Returns

Code

InvitationResult

Call example

Code

client.invite_drive_member(drive, email, role)

Input and result fields

InvitationResult

{
  "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

Request and response contract

{
  "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.

Code

accept_drive_invitation(token: str) -> Drive

Parameters

Name	Type / default	Meaning
`token`	`str`	Credential for this operation. Use interactive, machine or recipient authority as applicable; keep it private.

Returns

Code

Drive

Call example

Code

client.accept_drive_invitation(token)

Input and result fields

Drive

{
  "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

Request and response contract

{
  "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

Code

update_drive_member(drive: str, member: str, role: Literal['viewer', 'editor', 'admin'], expected_role: Literal['viewer', 'editor', 'admin', 'owner']) -> DriveMember

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`	`Literal['viewer', 'editor', 'admin']`	Requested member role. The drive owner cannot be changed.
`expected_role`	`Literal['viewer', 'editor', 'admin', 'owner']`	Member role you reviewed; rejects a stale administrative change.

Returns

Code

DriveMember

Call example

Code

client.update_drive_member(drive, member, role, expected_role)

Input and result fields

DriveMember

{
  "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

Request and response contract

{
  "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

Code

remove_drive_member(drive: str, member: str, expected_role: Literal['viewer', 'editor', 'admin', 'owner']) -> None

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`	`Literal['viewer', 'editor', 'admin', 'owner']`	Member role you reviewed; rejects a stale administrative change.

Returns

Code

None

Call example

Code

client.remove_drive_member(drive, member, expected_role)

HTTP requests

DELETE /drives/{drive}/members/{member}

Remove non-owner access and invalidate outstanding invitations

Request and response contract

{
  "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"
    }
  }
}

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.

Code

from nufs_sdk import PreconditionError, AuthorizationError
try:
    saved = client.write_at(file_id, 0, b"H", reviewed_version,
                            idempotency_key=operation_id)
except PreconditionError:
    # Keep unsaved bytes; inspect the new head before a new operation.
    raise
except AuthorizationError:
    # Check current scope/session without claiming this edit committed.
    raise