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
Node.js 22+ toolchain · browser fetch · ESM. Install the supplied 0.2.0 release artifact:
npm install /path/to/nufs-sdk-0.2.0.tgzCreate a drive-scoped access key in your drive. Use its REST bearer token, your API origin without /v1, and the drive ID for the example.
export NUFS_ENDPOINT='https://api.example.test'
export NUFS_TOKEN='REPLACE_WITH_REST_BEARER'
export NUFS_DRIVE_ID='REPLACE_WITH_DRIVE_ID'Create, update and read a file
This example creates a new file, saves its contents, edits the first byte with a version guard and reads the saved contents.
import { Client } from "@nufs/sdk";
const endpoint = process.env.NUFS_ENDPOINT;
const token = process.env.NUFS_TOKEN;
const drive = process.env.NUFS_DRIVE_ID;
if (!endpoint || !token || !drive) throw new Error("Missing configuration");
const client = new Client(endpoint, token);
const file = await client.createEntry(drive, "notes-" + crypto.randomUUID() + ".txt", "file");
const first = await client.writeFile(file.id, new TextEncoder().encode("hello"), null);
const saved = await client.writeAt(file.id, 0, new TextEncoder().encode("H"), first.version.id);
const original = await client.readVersionRange(file.id, saved.version.id, 0, 5);
console.log(new TextDecoder().decode(original)); // Hello
console.log(await client.versions(file.id));Method reference
71 TypeScript methods, grouped by task.
Connect and authenticate
constructorConstruct an authorized client for a nuFS endpoint.+
constructor(endpoint: string, credential: string, fetcher?: typeof fetch)Parameters
| Name | Type / default | Meaning |
|---|---|---|
endpoint | string | API origin without /v1; HTTPS outside local development. |
credential | string | Credential for this operation. Use interactive, machine or recipient authority as applicable; keep it private. |
fetcher | typeof fetchOptional | Caller-supplied HTTP transport of the declared type. |
Returns
ClientCall example
new Client(endpoint, credential, fetcher);refreshRotate a refresh token+
static refresh(endpoint: string, refreshToken: string, fetcher?: typeof fetch): Promise<RefreshedSession>Parameters
| Name | Type / default | Meaning |
|---|---|---|
endpoint | string | API origin without /v1; HTTPS outside local development. |
refreshToken | string | Credential for this operation. Use interactive, machine or recipient authority as applicable; keep it private. |
fetcher | typeof fetchOptional | Caller-supplied HTTP transport of the declared type. |
Returns
Promise<RefreshedSession>Call example
await Client.refresh(endpoint, refreshToken, fetcher);Input and result fields
{
"type": "object",
"required": [
"access_token",
"access_expires_at",
"refresh_token",
"refresh_expires_at"
],
"properties": {
"access_token": {
"type": "string",
"minLength": 1
},
"access_expires_at": {
"type": "string",
"format": "date-time"
},
"refresh_token": {
"type": "string",
"minLength": 1
},
"refresh_expires_at": {
"type": "string",
"format": "date-time"
}
}
}HTTP requests
POST /auth/refresh
Rotate a refresh token
{
"id": "post-auth-refresh",
"path": "/auth/refresh",
"method": "POST",
"summary": "Rotate a refresh token",
"security": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"refresh_token"
],
"properties": {
"refresh_token": {
"type": "string",
"minLength": 1
}
}
}
}
}
},
"responses": {
"200": {
"description": "Rotated session",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RefreshedSession"
}
}
}
},
"401": {
"description": "invalid_session",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"500": {
"description": "Session rotation or reuse revocation could not be committed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
}logoutLogout.+
logout(signal?: AbortSignal): Promise<void>Parameters
| Name | Type / default | Meaning |
|---|---|---|
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<void>Call example
await client.logout(signal);HTTP requests
POST /auth/logout
{
"id": "post-auth-logout",
"path": "/auth/logout",
"method": "POST",
"security": [
{
"bearer": []
}
],
"responses": {
"204": {
"description": "Current interactive session revoked"
},
"401": {
"description": "Interactive session required; machine keys return unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"500": {
"description": "Session revocation could not be committed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
}accessKeysList active machine credentials+
accessKeys(signal?: AbortSignal): Promise<AccessKey[]>Parameters
| Name | Type / default | Meaning |
|---|---|---|
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<AccessKey[]>Call example
await client.accessKeys(signal);Input and result fields
{
"type": "object",
"required": [
"id",
"key_id",
"label",
"access",
"scope_type",
"created_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"key_id": {
"type": "string",
"description": "Non-secret public key identifier"
},
"label": {
"type": "string"
},
"access": {
"enum": [
"read",
"write",
"admin"
]
},
"scope_type": {
"enum": [
"account",
"drive"
]
},
"scope_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"parent_key_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"drive_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"expires_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"last_used_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}HTTP requests
GET /access-keys
List active machine credentials
{
"id": "get-access-keys",
"path": "/access-keys",
"method": "GET",
"summary": "List active machine credentials",
"security": [
{
"bearer": []
}
],
"responses": {
"200": {
"description": "Active access keys"
},
"401": {
"description": "Interactive session required"
}
}
}createAccessKeyCreate a machine credential; its secret is returned exactly once+
createAccessKey(label: string, access: Access, scopeType?: Scope, scopeId?: string | null, expiresAt?: string | null, signal?: AbortSignal): Promise<AccessKeyResult>Parameters
| Name | Type / default | Meaning |
|---|---|---|
label | string | Name or label accepted by this operation; it must meet server constraints. |
access | Access | Requested authority within the caller’s current permitted scope. |
scopeType | ScopeOptional | Account/drive/drive scope as accepted by this credential operation. |
scopeId | string | nullOptional | Account/drive/drive scope as accepted by this credential operation. |
expiresAt | string | nullOptional | Expiry in the declared timestamp format; server policy bounds the grant. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<AccessKeyResult>Call example
await client.createAccessKey(label, access, scopeType, scopeId, expiresAt, signal);HTTP requests
POST /access-keys
Create a machine credential; its secret is returned exactly once
{
"id": "post-access-keys",
"path": "/access-keys",
"method": "POST",
"summary": "Create a machine credential; its secret is returned exactly once",
"security": [
{
"bearer": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"label",
"access"
],
"properties": {
"label": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"access": {
"enum": [
"read",
"write",
"admin"
]
},
"scope_type": {
"enum": [
"account",
"drive"
],
"default": "account"
},
"scope_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"expires_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Access key, one-time bearer secret, and separate S3 access-key ID/signing secret"
},
"401": {
"description": "Interactive session required"
}
}
}revokeAccessKeyRevoke a machine credential+
revokeAccessKey(id: string, signal?: AbortSignal): Promise<void>Parameters
| Name | Type / default | Meaning |
|---|---|---|
id | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<void>Call example
await client.revokeAccessKey(id, signal);HTTP requests
DELETE /access-keys/{key}
Revoke a machine credential
{
"id": "delete-access-keys-key",
"path": "/access-keys/{key}",
"method": "DELETE",
"summary": "Revoke a machine credential",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "key",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Revoked"
},
"404": {
"description": "Access key not found"
}
}
}mountCredentialsIssue a short-lived read or write credential for one drive+
mountCredentials(drive: string, access?: "read" | "write", signal?: AbortSignal): Promise<any>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
access | "read" | "write"Optional | Requested authority within the caller’s current permitted scope. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<any>Call example
await client.mountCredentials(drive, access, signal);HTTP requests
POST /drives/{drive}/mount-credentials
Issue a short-lived read or write credential for one drive
{
"id": "post-drives-drive-mount-credentials",
"path": "/drives/{drive}/mount-credentials",
"method": "POST",
"summary": "Issue a short-lived read or write credential for one drive",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "drive",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"access": {
"type": "string",
"enum": [
"read",
"write"
],
"default": "write"
},
"ttl_seconds": {
"type": "integer",
"minimum": 60,
"maximum": 86400,
"default": 3600
}
}
}
}
}
},
"responses": {
"201": {
"description": "Temporary credential and one-time secret"
},
"403": {
"description": "Authority cannot be delegated"
}
}
}Find and read files
searchFilesSearch live names and bounded UTF-8 file text within one accessible drive+
searchFiles(drive: string, query: string, limit?: number, cursor?: string, signal?: AbortSignal): Promise<SearchPage>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
query | string | Literal search text, encoded as request data. |
limit | numberOptional | Bounded page size; endpoint-specific limits apply. |
cursor | stringOptional | Opaque cursor returned by this same operation and scope. Omit for the first page. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<SearchPage>Call example
await client.searchFiles(drive, query, limit, cursor, signal);Input and result fields
{
"type": "object",
"required": [
"results",
"next_cursor"
],
"properties": {
"results": {
"type": "array",
"maxItems": 100,
"items": {
"$ref": "#/components/schemas/SearchHit"
}
},
"next_cursor": {
"type": [
"string",
"null"
]
}
}
}HTTP requests
GET /drives/{drive}/search
All query words must match. Results use file-ID order and live pagination. Names update transactionally; content extraction is asynchronous and restricted to 256 KiB UTF-8 text without binary control characters. Current drive permissions and live ancestors are checked on every page. Old content is hidden immediately after a version change. Unsupported content remains searchable by name. No external model or service receives queries or content.
{
"id": "get-drives-drive-search",
"path": "/drives/{drive}/search",
"method": "GET",
"summary": "Search live names and bounded UTF-8 file text within one accessible drive",
"description": "All query words must match. Results use file-ID order and live pagination. Names update transactionally; content extraction is asynchronous and restricted to 256 KiB UTF-8 text without binary control characters. Current drive permissions and live ancestors are checked on every page. Old content is hidden immediately after a version change. Unsupported content remains searchable by name. No external model or service receives queries or content.",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"in": "path",
"name": "drive",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"in": "query",
"name": "q",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"description": "Query is limited to 256 UTF-8 bytes"
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
}
},
{
"in": "query",
"name": "cursor",
"schema": {
"type": "string",
"maxLength": 512
},
"description": "Continuation bound to this drive and query"
}
],
"responses": {
"200": {
"description": "Permission-filtered live results",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchPage"
}
}
}
},
"400": {
"description": "Invalid query or cursor"
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Credential scope denied"
},
"404": {
"description": "Drive unavailable"
},
"500": {
"description": "Search unavailable"
}
}
}entriesEntries.+
entries(drive: string, parent?: string, signal?: AbortSignal): Promise<Entry[]>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
parent | stringOptional | Parent folder identity, or the language’s absent value for the drive root. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<Entry[]>Call example
await client.entries(drive, parent, signal);Input and result fields
{
"type": "object",
"required": [
"id",
"drive_id",
"name",
"kind",
"logical_size",
"revision",
"created_at",
"modified_at",
"deleted"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"drive_id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"name": {
"type": "string"
},
"kind": {
"enum": [
"file",
"folder"
]
},
"current_version_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"logical_size": {
"type": "integer",
"format": "int64"
},
"checksum_sha256": {
"type": [
"string",
"null"
]
},
"revision": {
"type": "integer",
"format": "int64"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"modified_at": {
"type": "string",
"format": "date-time"
},
"deleted": {
"type": "boolean"
}
}
}HTTP requests
GET /drives/{drive}/entries
{
"id": "get-drives-drive-entries",
"path": "/drives/{drive}/entries",
"method": "GET",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "parent_id",
"in": "query",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "as_of",
"in": "query",
"description": "Committed drive sequence to resolve under current permissions; this read does not pin history",
"schema": {
"type": "integer",
"format": "int64",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Directory entries"
},
"410": {
"description": "history_expired — a visible historical file version required by this listing was reclaimed"
}
}
}entryEntry.+
entry(id: string, signal?: AbortSignal): Promise<Entry>Parameters
| Name | Type / default | Meaning |
|---|---|---|
id | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<Entry>Call example
await client.entry(id, signal);Input and result fields
{
"type": "object",
"required": [
"id",
"drive_id",
"name",
"kind",
"logical_size",
"revision",
"created_at",
"modified_at",
"deleted"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"drive_id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"name": {
"type": "string"
},
"kind": {
"enum": [
"file",
"folder"
]
},
"current_version_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"logical_size": {
"type": "integer",
"format": "int64"
},
"checksum_sha256": {
"type": [
"string",
"null"
]
},
"revision": {
"type": "integer",
"format": "int64"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"modified_at": {
"type": "string",
"format": "date-time"
},
"deleted": {
"type": "boolean"
}
}
}HTTP requests
GET /entries/{entry}
{
"id": "get-entries-entry",
"path": "/entries/{entry}",
"method": "GET",
"security": [
{
"bearer": []
}
],
"responses": {
"200": {
"description": "Entry metadata"
}
}
}createEntryCreate Entry.+
createEntry(drive: string, name: string, kind: "file" | "folder", parentId?: string | null, signal?: AbortSignal): Promise<Entry>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
name | string | Name or label accepted by this operation; it must meet server constraints. |
kind | "file" | "folder" | Entry kind: file or folder. |
parentId | string | nullOptional | Parent folder identity, or the language’s absent value for the drive root. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<Entry>Call example
await client.createEntry(drive, name, kind, parentId, signal);Input and result fields
{
"type": "object",
"required": [
"id",
"drive_id",
"name",
"kind",
"logical_size",
"revision",
"created_at",
"modified_at",
"deleted"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"drive_id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"name": {
"type": "string"
},
"kind": {
"enum": [
"file",
"folder"
]
},
"current_version_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"logical_size": {
"type": "integer",
"format": "int64"
},
"checksum_sha256": {
"type": [
"string",
"null"
]
},
"revision": {
"type": "integer",
"format": "int64"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"modified_at": {
"type": "string",
"format": "date-time"
},
"deleted": {
"type": "boolean"
}
}
}HTTP requests
POST /drives/{drive}/entries
{
"id": "post-drives-drive-entries",
"path": "/drives/{drive}/entries",
"method": "POST",
"security": [
{
"bearer": []
}
],
"responses": {
"201": {
"description": "Entry created"
},
"409": {
"description": "Name conflict"
}
}
}renameEntryRename Entry.+
renameEntry(id: string, name: string, expectedRevision: number, parentId?: string | null, replace?: boolean, signal?: AbortSignal): Promise<Entry>Parameters
| Name | Type / default | Meaning |
|---|---|---|
id | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
name | string | Name or label accepted by this operation; it must meet server constraints. |
expectedRevision | number | Reviewed entry or policy revision. Do not substitute a file version ID. |
parentId | string | nullOptional | Parent folder identity, or the language’s absent value for the drive root. |
replace | booleanOptional | Explicit namespace replacement behavior for the reviewed rename/move operation. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<Entry>Call example
await client.renameEntry(id, name, expectedRevision, parentId, replace, signal);Input and result fields
{
"type": "object",
"required": [
"id",
"drive_id",
"name",
"kind",
"logical_size",
"revision",
"created_at",
"modified_at",
"deleted"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"drive_id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"name": {
"type": "string"
},
"kind": {
"enum": [
"file",
"folder"
]
},
"current_version_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"logical_size": {
"type": "integer",
"format": "int64"
},
"checksum_sha256": {
"type": [
"string",
"null"
]
},
"revision": {
"type": "integer",
"format": "int64"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"modified_at": {
"type": "string",
"format": "date-time"
},
"deleted": {
"type": "boolean"
}
}
}HTTP requests
PATCH /entries/{entry}
{
"id": "patch-entries-entry",
"path": "/entries/{entry}",
"method": "PATCH",
"security": [
{
"bearer": []
}
],
"responses": {
"200": {
"description": "Renamed or moved"
},
"409": {
"description": "Revision conflict"
}
}
}deleteEntryDelete Entry.+
deleteEntry(id: string, expectedRevision: number, signal?: AbortSignal): Promise<void>Parameters
| Name | Type / default | Meaning |
|---|---|---|
id | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
expectedRevision | number | Reviewed entry or policy revision. Do not substitute a file version ID. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<void>Call example
await client.deleteEntry(id, expectedRevision, signal);HTTP requests
DELETE /entries/{entry}
{
"id": "delete-entries-entry",
"path": "/entries/{entry}",
"method": "DELETE",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "expected_revision",
"in": "query",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"204": {
"description": "Tombstoned"
},
"409": {
"description": "Revision conflict"
}
}
}readRangeRead 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.
readRange(file: string, offset: number, length: number, signal?: AbortSignal): Promise<Uint8Array>Parameters
| Name | Type / default | Meaning |
|---|---|---|
file | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
offset | number | Non-negative byte offset, not a character offset. |
length | number | Byte count or logical byte size; non-negative and bounded by the operation. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<Uint8Array>Call example
await client.readRange(file, offset, length, signal);HTTP requests
GET /files/{file}/bytes
Stream current file bytes, optionally as one HTTP byte range
{
"id": "get-files-file-bytes",
"path": "/files/{file}/bytes",
"method": "GET",
"summary": "Stream current file bytes, optionally as one HTTP byte range",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "Range",
"in": "header",
"schema": {
"type": "string",
"example": "bytes=0-1023"
}
}
],
"responses": {
"200": {
"description": "Full content"
},
"206": {
"description": "Exact requested range"
},
"416": {
"description": "Unsatisfiable range"
}
}
}HEAD /files/{file}/bytes
Read current logical size and version headers without content
{
"id": "head-files-file-bytes",
"path": "/files/{file}/bytes",
"method": "HEAD",
"summary": "Read current logical size and version headers without content",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "File metadata headers"
}
}
}PUT /files/{file}/bytes
Uploads up to 100 MiB in bounded server chunks. Retry the same body and identity after interruption. A new file entry may remain empty until content commits.
{
"id": "put-files-file-bytes",
"path": "/files/{file}/bytes",
"method": "PUT",
"summary": "Atomically replace file bytes with bounded binary ingestion",
"description": "Uploads up to 100 MiB in bounded server chunks. Retry the same body and identity after interruption. A new file entry may remain empty until content commits.",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
{
"name": "X-Content-SHA256",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"responses": {
"200": {
"description": "Exactly one committed version or its replay",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MutationResult"
}
}
}
},
"400": {
"description": "Invalid size or checksum or incomplete body"
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Credential scope or access denied"
},
"404": {
"description": "File or write permission unavailable"
},
"409": {
"description": "Idempotency identity conflict"
},
"412": {
"description": "Base version changed"
},
"428": {
"description": "Version precondition required"
},
"503": {
"description": "Content storage unavailable"
},
"507": {
"description": "Quota exhausted"
}
}
}browserDownloadIssue a file/version-scoped HttpOnly download cookie for the current session+
browserDownload(file: string, version: string, signal?: AbortSignal): Promise<BrowserDownloadGrant>Parameters
| Name | Type / default | Meaning |
|---|---|---|
file | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
version | string | Selected immutable version identity for this read, restore or sharing operation. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<BrowserDownloadGrant>Call example
await client.browserDownload(file, version, signal);Input and result fields
{
"type": "object",
"required": [
"download_path",
"expires_at"
],
"additionalProperties": false,
"properties": {
"download_path": {
"type": "string",
"pattern": "^/v1/files/[0-9a-f-]{36}/versions/[0-9a-f-]{36}/browser-download$"
},
"expires_at": {
"type": "string",
"format": "date-time"
}
}
}HTTP requests
POST /files/{file}/versions/{version}/browser-download
Issue a file/version-scoped HttpOnly download cookie for the current session
{
"id": "post-files-file-versions-version-browser-download",
"path": "/files/{file}/versions/{version}/browser-download",
"method": "POST",
"summary": "Issue a file/version-scoped HttpOnly download cookie for the current session",
"security": [
{
"bearer": []
}
],
"responses": {
"200": {
"description": "Native browser download path; 15-minute grant rechecks session and membership",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserDownloadGrant"
}
}
}
},
"401": {
"description": "Interactive session required"
},
"404": {
"description": "Version inaccessible"
}
}
}Write and update files
| If you want to… | Use |
|---|---|
| Replace a file's complete contents | writeFile |
| Overwrite bytes at a known offset | writeAt |
| 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 |
uploadFileBytesAtomically replace file bytes with bounded binary ingestion+
uploadFileBytes(file: string, data: Blob | Uint8Array, expectedVersion: string | null, sha256: string, idempotencyKey: string, signal?: AbortSignal): Promise<MutationResult>Parameters
| Name | Type / default | Meaning |
|---|---|---|
file | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
data | Blob | Uint8Array | Raw byte input in the declared language type; binary identities must describe these exact bytes. |
expectedVersion | string | null | File version precondition. None/null/empty (according to language) means no committed version, not any version. |
sha256 | string | Lowercase hexadecimal SHA-256 of the exact content bytes. |
idempotencyKey | string | Stable operation identity for exact replay. Reuse only with the same payload and preconditions. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<MutationResult>Call example
await client.uploadFileBytes(file, data, expectedVersion, sha256, idempotencyKey, signal);Input and result fields
{
"type": "object",
"required": [
"entry",
"version"
],
"properties": {
"entry": {
"$ref": "#/components/schemas/Entry"
},
"version": {
"$ref": "#/components/schemas/Version"
},
"idempotent_replay": {
"type": "boolean",
"default": false
}
}
}HTTP requests
PUT /files/{file}/bytes
Uploads up to 100 MiB in bounded server chunks. Retry the same body and identity after interruption. A new file entry may remain empty until content commits.
{
"id": "put-files-file-bytes",
"path": "/files/{file}/bytes",
"method": "PUT",
"summary": "Atomically replace file bytes with bounded binary ingestion",
"description": "Uploads up to 100 MiB in bounded server chunks. Retry the same body and identity after interruption. A new file entry may remain empty until content commits.",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
{
"name": "X-Content-SHA256",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"responses": {
"200": {
"description": "Exactly one committed version or its replay",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MutationResult"
}
}
}
},
"400": {
"description": "Invalid size or checksum or incomplete body"
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Credential scope or access denied"
},
"404": {
"description": "File or write permission unavailable"
},
"409": {
"description": "Idempotency identity conflict"
},
"412": {
"description": "Base version changed"
},
"428": {
"description": "Version precondition required"
},
"503": {
"description": "Content storage unavailable"
},
"507": {
"description": "Quota exhausted"
}
}
}writeFileReplace 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.
writeFile(file: string, data: Uint8Array, ifVersion: string | null, options?: RequestOptions): Promise<MutationResult>Parameters
| Name | Type / default | Meaning |
|---|---|---|
file | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
data | Uint8Array | Raw byte input in the declared language type; binary identities must describe these exact bytes. |
ifVersion | string | null | File version precondition. None/null/empty (according to language) means no committed version, not any version. |
options | RequestOptionsOptional | RequestOptions: signal for cancellation and idempotencyKey for stable mutation identity. |
Returns
Promise<MutationResult>Call example
await client.writeFile(file, data, ifVersion, options);Input and result fields
{
"type": "object",
"required": [
"entry",
"version"
],
"properties": {
"entry": {
"$ref": "#/components/schemas/Entry"
},
"version": {
"$ref": "#/components/schemas/Version"
},
"idempotent_replay": {
"type": "boolean",
"default": false
}
}
}HTTP requests
PUT /files/{file}/content
Atomically replace a file through the canonical extent engine
{
"id": "put-files-file-content",
"path": "/files/{file}/content",
"method": "PUT",
"summary": "Atomically replace a file through the canonical extent engine",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Base version UUID or quoted `none`"
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"maxLength": 200
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContentMutation"
}
}
}
},
"responses": {
"200": {
"description": "One committed immutable version",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MutationResult"
}
}
}
},
"400": {
"description": "Invalid input or missing idempotency key",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"409": {
"description": "Idempotency key belongs to another request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"412": {
"description": "version_precondition_failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"413": {
"description": "mutation_too_large",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"428": {
"description": "version_precondition_required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
}GET /files/{file}/versions/{version}/content
Resolve a version to a legacy blob URL or chunk manifest
{
"id": "get-files-file-versions-version-content",
"path": "/files/{file}/versions/{version}/content",
"method": "GET",
"summary": "Resolve a version to a legacy blob URL or chunk manifest",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "version",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Version content descriptor; chunked versions contain a manifest"
}
}
}writeAtOverwrite 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.
writeAt(file: string, offset: number, data: Uint8Array, ifVersion: string | null, options?: RequestOptions): Promise<MutationResult>Parameters
| Name | Type / default | Meaning |
|---|---|---|
file | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
offset | number | Non-negative byte offset, not a character offset. |
data | Uint8Array | Raw byte input in the declared language type; binary identities must describe these exact bytes. |
ifVersion | string | null | File version precondition. None/null/empty (according to language) means no committed version, not any version. |
options | RequestOptionsOptional | RequestOptions: signal for cancellation and idempotencyKey for stable mutation identity. |
Returns
Promise<MutationResult>Call example
await client.writeAt(file, offset, data, ifVersion, options);Input and result fields
{
"type": "object",
"required": [
"entry",
"version"
],
"properties": {
"entry": {
"$ref": "#/components/schemas/Entry"
},
"version": {
"$ref": "#/components/schemas/Version"
},
"idempotent_replay": {
"type": "boolean",
"default": false
}
}
}HTTP requests
POST /files/{file}/write-at
Overwrite bytes at a 64-bit logical offset without replacing unaffected content
{
"id": "post-files-file-write-at",
"path": "/files/{file}/write-at",
"method": "POST",
"summary": "Overwrite bytes at a 64-bit logical offset without replacing unaffected content",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WriteAtMutation"
}
}
}
},
"responses": {
"200": {
"description": "One committed immutable version",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MutationResult"
}
}
}
},
"400": {
"description": "Invalid input or missing idempotency key",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"409": {
"description": "Idempotency key belongs to another request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"412": {
"description": "version_precondition_failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"413": {
"description": "mutation_too_large",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"428": {
"description": "version_precondition_required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
}patchCommit several offset edits together+
Use this when one logical change touches several positions in a file. Supply offset/data pairs instead of making a separate call for each edit. The accepted patch is committed together as one version.
patch(file: string, changes: Patch[], ifVersion: string | null, options?: RequestOptions): Promise<MutationResult>Parameters
| Name | Type / default | Meaning |
|---|---|---|
file | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
changes | Patch[] | Ordered collection of patch ranges or structured changes in the declared type. |
ifVersion | string | null | File version precondition. None/null/empty (according to language) means no committed version, not any version. |
options | RequestOptionsOptional | RequestOptions: signal for cancellation and idempotencyKey for stable mutation identity. |
Returns
Promise<MutationResult>Call example
await client.patch(file, changes, ifVersion, options);Input and result fields
{
"type": "object",
"required": [
"entry",
"version"
],
"properties": {
"entry": {
"$ref": "#/components/schemas/Entry"
},
"version": {
"$ref": "#/components/schemas/Version"
},
"idempotent_replay": {
"type": "boolean",
"default": false
}
}
}HTTP requests
POST /files/{file}/patch
Apply up to 10,000 non-overlapping overwrite edits as one version
{
"id": "post-files-file-patch",
"path": "/files/{file}/patch",
"method": "POST",
"summary": "Apply up to 10,000 non-overlapping overwrite edits as one version",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PatchMutation"
}
}
}
},
"responses": {
"200": {
"description": "One committed immutable version",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MutationResult"
}
}
}
},
"400": {
"description": "Invalid input or missing idempotency key",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"409": {
"description": "Idempotency key belongs to another request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"412": {
"description": "version_precondition_failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"413": {
"description": "mutation_too_large",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"428": {
"description": "version_precondition_required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
}insertAdd bytes and move the following content+
Use this when new content belongs between existing bytes. The supplied data is inserted at the offset and later content shifts to make room. Offsets are measured in bytes, including for UTF-8 text.
insert(file: string, offset: number, data: Uint8Array, ifVersion: string | null, options?: RequestOptions): Promise<MutationResult>Parameters
| Name | Type / default | Meaning |
|---|---|---|
file | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
offset | number | Non-negative byte offset, not a character offset. |
data | Uint8Array | Raw byte input in the declared language type; binary identities must describe these exact bytes. |
ifVersion | string | null | File version precondition. None/null/empty (according to language) means no committed version, not any version. |
options | RequestOptionsOptional | RequestOptions: signal for cancellation and idempotencyKey for stable mutation identity. |
Returns
Promise<MutationResult>Call example
await client.insert(file, offset, data, ifVersion, options);Input and result fields
{
"type": "object",
"required": [
"entry",
"version"
],
"properties": {
"entry": {
"$ref": "#/components/schemas/Entry"
},
"version": {
"$ref": "#/components/schemas/Version"
},
"idempotent_replay": {
"type": "boolean",
"default": false
}
}
}HTTP requests
POST /files/{file}/insert
Insert bytes and shift the unchanged suffix through manifest path-copying
{
"id": "post-files-file-insert",
"path": "/files/{file}/insert",
"method": "POST",
"summary": "Insert bytes and shift the unchanged suffix through manifest path-copying",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InsertMutation"
}
}
}
},
"responses": {
"200": {
"description": "One committed immutable version",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MutationResult"
}
}
}
},
"400": {
"description": "Invalid input or missing idempotency key",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"409": {
"description": "Idempotency key belongs to another request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"412": {
"description": "version_precondition_failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"413": {
"description": "mutation_too_large",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"428": {
"description": "version_precondition_required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
}removeDelete a range and close the gap+
Use this to remove a section while keeping the rest of the file. The length selects how many bytes to delete; following content shifts left. Read the reviewed version first when calculating offsets.
remove(file: string, offset: number, length: number, ifVersion: string | null, options?: RequestOptions): Promise<MutationResult>Parameters
| Name | Type / default | Meaning |
|---|---|---|
file | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
offset | number | Non-negative byte offset, not a character offset. |
length | number | Byte count or logical byte size; non-negative and bounded by the operation. |
ifVersion | string | null | File version precondition. None/null/empty (according to language) means no committed version, not any version. |
options | RequestOptionsOptional | RequestOptions: signal for cancellation and idempotencyKey for stable mutation identity. |
Returns
Promise<MutationResult>Call example
await client.remove(file, offset, length, ifVersion, options);Input and result fields
{
"type": "object",
"required": [
"entry",
"version"
],
"properties": {
"entry": {
"$ref": "#/components/schemas/Entry"
},
"version": {
"$ref": "#/components/schemas/Version"
},
"idempotent_replay": {
"type": "boolean",
"default": false
}
}
}HTTP requests
POST /files/{file}/remove
Remove a logical range and close the gap without copying the suffix
{
"id": "post-files-file-remove",
"path": "/files/{file}/remove",
"method": "POST",
"summary": "Remove a logical range and close the gap without copying the suffix",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RemoveMutation"
}
}
}
},
"responses": {
"200": {
"description": "One committed immutable version",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MutationResult"
}
}
}
},
"400": {
"description": "Invalid input or missing idempotency key",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"409": {
"description": "Idempotency key belongs to another request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"412": {
"description": "version_precondition_failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"413": {
"description": "mutation_too_large",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"428": {
"description": "version_precondition_required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
}spliceReplace a section with content of another length+
Use this when the replacement is shorter or longer than the original section. Supply the offset, deletion length and replacement bytes in one mutation. It avoids an intermediate state between a separate delete and insert.
splice(file: string, offset: number, length: number, data: Uint8Array, ifVersion: string | null, options?: RequestOptions): Promise<MutationResult>Parameters
| Name | Type / default | Meaning |
|---|---|---|
file | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
offset | number | Non-negative byte offset, not a character offset. |
length | number | Byte count or logical byte size; non-negative and bounded by the operation. |
data | Uint8Array | Raw byte input in the declared language type; binary identities must describe these exact bytes. |
ifVersion | string | null | File version precondition. None/null/empty (according to language) means no committed version, not any version. |
options | RequestOptionsOptional | RequestOptions: signal for cancellation and idempotencyKey for stable mutation identity. |
Returns
Promise<MutationResult>Call example
await client.splice(file, offset, length, data, ifVersion, options);Input and result fields
{
"type": "object",
"required": [
"entry",
"version"
],
"properties": {
"entry": {
"$ref": "#/components/schemas/Entry"
},
"version": {
"$ref": "#/components/schemas/Version"
},
"idempotent_replay": {
"type": "boolean",
"default": false
}
}
}HTTP requests
POST /files/{file}/splice
Replace a logical range with different-length content atomically
{
"id": "post-files-file-splice",
"path": "/files/{file}/splice",
"method": "POST",
"summary": "Replace a logical range with different-length content atomically",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SpliceMutation"
}
}
}
},
"responses": {
"200": {
"description": "One committed immutable version",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MutationResult"
}
}
}
},
"400": {
"description": "Invalid input or missing idempotency key",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"409": {
"description": "Idempotency key belongs to another request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"412": {
"description": "version_precondition_failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"413": {
"description": "mutation_too_large",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"428": {
"description": "version_precondition_required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
}truncateSet a file's length+
Use this to drop a tail or extend the logical size. Shortening removes bytes beyond the new length; extension adds zero-filled space. Earlier retained versions still contain their original bytes.
truncate(file: string, size: number, ifVersion: string | null, options?: RequestOptions): Promise<MutationResult>Parameters
| Name | Type / default | Meaning |
|---|---|---|
file | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
size | number | Byte count or logical byte size; non-negative and bounded by the operation. |
ifVersion | string | null | File version precondition. None/null/empty (according to language) means no committed version, not any version. |
options | RequestOptionsOptional | RequestOptions: signal for cancellation and idempotencyKey for stable mutation identity. |
Returns
Promise<MutationResult>Call example
await client.truncate(file, size, ifVersion, options);Input and result fields
{
"type": "object",
"required": [
"entry",
"version"
],
"properties": {
"entry": {
"$ref": "#/components/schemas/Entry"
},
"version": {
"$ref": "#/components/schemas/Version"
},
"idempotent_replay": {
"type": "boolean",
"default": false
}
}
}HTTP requests
POST /files/{file}/truncate
Truncate or sparse-extend a file atomically
{
"id": "post-files-file-truncate",
"path": "/files/{file}/truncate",
"method": "POST",
"summary": "Truncate or sparse-extend a file atomically",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TruncateMutation"
}
}
}
},
"responses": {
"200": {
"description": "One committed immutable version",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MutationResult"
}
}
}
},
"400": {
"description": "Invalid input or missing idempotency key",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"409": {
"description": "Idempotency key belongs to another request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"412": {
"description": "version_precondition_failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"413": {
"description": "mutation_too_large",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"428": {
"description": "version_precondition_required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
}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.
const policy = await client.fileHistory(driveId);
await client.setFileHistory(driveId, true, policy.revision);
// Future edits now retain earlier contents.
console.log(await client.versions(fileId));
// Permanently remove older versions; the current file stays unchanged.
const result = await client.clearFileHistory(fileId);
console.log(result.bytes_freed);
// await client.clearDriveHistory(driveId);entriesAtRead historical directory metadata at a committed sequence; current permissions and retention apply.+
entriesAt(drive: string, sequence: number | bigint, parent?: string, signal?: AbortSignal): Promise<Entry[]>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
sequence | number | bigint | Committed drive sequence (non-negative int64). TypeScript uses bigint beyond safe integer precision. |
parent | stringOptional | Parent folder identity, or the language’s absent value for the drive root. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<Entry[]>Call example
await client.entriesAt(drive, sequence, parent, signal);Input and result fields
{
"type": "object",
"required": [
"id",
"drive_id",
"name",
"kind",
"logical_size",
"revision",
"created_at",
"modified_at",
"deleted"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"drive_id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"name": {
"type": "string"
},
"kind": {
"enum": [
"file",
"folder"
]
},
"current_version_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"logical_size": {
"type": "integer",
"format": "int64"
},
"checksum_sha256": {
"type": [
"string",
"null"
]
},
"revision": {
"type": "integer",
"format": "int64"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"modified_at": {
"type": "string",
"format": "date-time"
},
"deleted": {
"type": "boolean"
}
}
}HTTP requests
GET /drives/{drive}/entries
{
"id": "get-drives-drive-entries",
"path": "/drives/{drive}/entries",
"method": "GET",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "parent_id",
"in": "query",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "as_of",
"in": "query",
"description": "Committed drive sequence to resolve under current permissions; this read does not pin history",
"schema": {
"type": "integer",
"format": "int64",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Directory entries"
},
"410": {
"description": "history_expired — a visible historical file version required by this listing was reclaimed"
}
}
}fileHistoryRead history settings and storage breakdown+
fileHistory(drive: string, signal?: AbortSignal): Promise<FileHistoryPolicy>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<FileHistoryPolicy>Call example
await client.fileHistory(drive, signal);Input and result fields
{
"type": "object",
"description": "Drive-wide history is off by default. Used storage counts current and retained historical contents with content deduplication.",
"required": [
"drive_id",
"enabled",
"revision",
"current_bytes",
"history_bytes",
"used_bytes",
"historical_versions"
],
"properties": {
"drive_id": {
"type": "string",
"format": "uuid"
},
"enabled": {
"type": "boolean"
},
"revision": {
"type": "string"
},
"current_bytes": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"history_bytes": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"used_bytes": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"historical_versions": {
"type": "integer",
"format": "int64",
"minimum": 0
}
}
}HTTP requests
GET /drives/{drive}/history
Read history settings and storage breakdown
{
"id": "get-drives-drive-history",
"path": "/drives/{drive}/history",
"method": "GET",
"summary": "Read history settings and storage breakdown",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "drive",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileHistoryPolicy"
}
}
}
},
"400": {
"description": "Invalid input"
},
"403": {
"description": "Drive owner authority is required"
},
"404": {
"description": "Drive or history not found"
},
"409": {
"description": "Revision changed or selected content is protected"
}
}
}setFileHistoryEnable or disable history for future edits+
setFileHistory(drive: string, enabled: boolean, expectedRevision: string, signal?: AbortSignal): Promise<FileHistoryPolicy>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
enabled | boolean | Caller-supplied value of the declared type. See the linked operation or model for field constraints. |
expectedRevision | string | Reviewed entry or policy revision. Do not substitute a file version ID. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<FileHistoryPolicy>Call example
await client.setFileHistory(drive, enabled, expectedRevision, signal);Input and result fields
{
"type": "object",
"description": "Drive-wide history is off by default. Used storage counts current and retained historical contents with content deduplication.",
"required": [
"drive_id",
"enabled",
"revision",
"current_bytes",
"history_bytes",
"used_bytes",
"historical_versions"
],
"properties": {
"drive_id": {
"type": "string",
"format": "uuid"
},
"enabled": {
"type": "boolean"
},
"revision": {
"type": "string"
},
"current_bytes": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"history_bytes": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"used_bytes": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"historical_versions": {
"type": "integer",
"format": "int64",
"minimum": 0
}
}
}HTTP requests
PUT /drives/{drive}/history
Enable or disable history for future edits
{
"id": "put-drives-drive-history",
"path": "/drives/{drive}/history",
"method": "PUT",
"summary": "Enable or disable history for future edits",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "drive",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileHistoryPolicy"
}
}
}
},
"400": {
"description": "Invalid input"
},
"403": {
"description": "Drive owner authority is required"
},
"404": {
"description": "Drive or history not found"
},
"409": {
"description": "Revision changed or selected content is protected"
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileHistoryUpdate"
}
}
}
}
}clearDriveHistoryClear all earlier versions in this drive+
clearDriveHistory(drive: string, signal?: AbortSignal): Promise<HistoryCleanupResult>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<HistoryCleanupResult>Call example
await client.clearDriveHistory(drive, signal);Input and result fields
{
"type": "object",
"description": "Clears earlier versions, keeps current files, and releases allowance immediately. Protected snapshots, forks and live links are skipped. Physical reclamation is asynchronous and preserves replay and active-save pins.",
"required": [
"versions_cleared",
"versions_skipped",
"bytes_freed",
"used_bytes"
],
"properties": {
"versions_cleared": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"versions_skipped": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"bytes_freed": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"used_bytes": {
"type": "integer",
"format": "int64",
"minimum": 0
}
}
}HTTP requests
DELETE /drives/{drive}/history
Clear all earlier versions in this drive
{
"id": "delete-drives-drive-history",
"path": "/drives/{drive}/history",
"method": "DELETE",
"summary": "Clear all earlier versions in this drive",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "drive",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HistoryCleanupResult"
}
}
}
},
"400": {
"description": "Invalid input"
},
"403": {
"description": "Drive owner authority is required"
},
"404": {
"description": "Drive or history not found"
},
"409": {
"description": "Revision changed or selected content is protected"
}
}
}clearFileHistoryClear earlier versions of one file+
clearFileHistory(file: string, signal?: AbortSignal): Promise<HistoryCleanupResult>Parameters
| Name | Type / default | Meaning |
|---|---|---|
file | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<HistoryCleanupResult>Call example
await client.clearFileHistory(file, signal);Input and result fields
{
"type": "object",
"description": "Clears earlier versions, keeps current files, and releases allowance immediately. Protected snapshots, forks and live links are skipped. Physical reclamation is asynchronous and preserves replay and active-save pins.",
"required": [
"versions_cleared",
"versions_skipped",
"bytes_freed",
"used_bytes"
],
"properties": {
"versions_cleared": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"versions_skipped": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"bytes_freed": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"used_bytes": {
"type": "integer",
"format": "int64",
"minimum": 0
}
}
}HTTP requests
DELETE /files/{file}/versions
Clear earlier versions of one file
{
"id": "delete-files-file-versions",
"path": "/files/{file}/versions",
"method": "DELETE",
"summary": "Clear earlier versions of one file",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HistoryCleanupResult"
}
}
}
},
"400": {
"description": "Invalid input"
},
"403": {
"description": "Drive owner authority is required"
},
"404": {
"description": "Drive or history not found"
},
"409": {
"description": "Revision changed or selected content is protected"
}
}
}recentVersionsRecent Versions.+
recentVersions(drive: string, limit?: number, signal?: AbortSignal): Promise<VersionSummary[]>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
limit | numberOptional | Bounded page size; endpoint-specific limits apply. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<VersionSummary[]>Call example
await client.recentVersions(drive, limit, signal);Input and result fields
{
"type": "object",
"description": "",
"required": [
"version_id",
"file_id",
"file_name",
"logical_size",
"checksum_sha256",
"created_at",
"current",
"file_revision"
],
"properties": {
"version_id": {
"type": "string",
"format": "uuid"
},
"file_id": {
"type": "string",
"format": "uuid"
},
"file_name": {
"type": "string"
},
"logical_size": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"checksum_sha256": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"current": {
"type": "boolean"
},
"file_revision": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"storage_format": {
"type": "string"
},
"manifest_sha256": {
"type": "string"
},
"operation": {
"type": "string"
},
"drive_sequence": {
"type": "integer",
"format": "int64",
"minimum": 0
}
}
}HTTP requests
GET /drives/{drive}/versions
{
"id": "get-drives-drive-versions",
"path": "/drives/{drive}/versions",
"method": "GET",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "drive",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"maximum": 100
}
}
],
"responses": {
"200": {
"description": "Current and retained versions for drive history",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"versions"
],
"properties": {
"versions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/VersionSummary"
}
}
}
}
}
}
}
}
}versionsInspect a file's saved history+
List retained committed versions before choosing one to compare or restore. Keep the selected version ID, rather than assuming that the current file will still contain those bytes later.
versions(file: string, signal?: AbortSignal): Promise<Version[]>Parameters
| Name | Type / default | Meaning |
|---|---|---|
file | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<Version[]>Call example
await client.versions(file, signal);Input and result fields
{
"type": "object",
"required": [
"id",
"file_id",
"logical_size",
"checksum_sha256",
"storage_format",
"created_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"file_id": {
"type": "string",
"format": "uuid"
},
"logical_size": {
"type": "integer",
"format": "int64"
},
"checksum_sha256": {
"type": "string"
},
"manifest_sha256": {
"type": "string"
},
"storage_format": {
"enum": [
"blob",
"chunked_v1",
"extent_v2"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"operation": {
"enum": [
"write",
"write_at",
"patch",
"insert",
"remove",
"splice",
"truncate",
"restore",
"conflict_preserved"
]
},
"drive_sequence": {
"type": "integer",
"format": "int64"
}
}
}HTTP requests
GET /files/{file}/versions
{
"id": "get-files-file-versions",
"path": "/files/{file}/versions",
"method": "GET",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Immutable version history"
}
}
}restoreVersionMake 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.
restoreVersion(file: string, version: string, expectedRevision: number, signal?: AbortSignal): Promise<Entry>Parameters
| Name | Type / default | Meaning |
|---|---|---|
file | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
version | string | Selected immutable version identity for this read, restore or sharing operation. |
expectedRevision | number | Reviewed entry or policy revision. Do not substitute a file version ID. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<Entry>Call example
await client.restoreVersion(file, version, expectedRevision, signal);Input and result fields
{
"type": "object",
"required": [
"id",
"drive_id",
"name",
"kind",
"logical_size",
"revision",
"created_at",
"modified_at",
"deleted"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"drive_id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"name": {
"type": "string"
},
"kind": {
"enum": [
"file",
"folder"
]
},
"current_version_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"logical_size": {
"type": "integer",
"format": "int64"
},
"checksum_sha256": {
"type": [
"string",
"null"
]
},
"revision": {
"type": "integer",
"format": "int64"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"modified_at": {
"type": "string",
"format": "date-time"
},
"deleted": {
"type": "boolean"
}
}
}HTTP requests
POST /files/{file}/versions/{version}/restore
{
"id": "post-files-file-versions-version-restore",
"path": "/files/{file}/versions/{version}/restore",
"method": "POST",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "version",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"expected_revision"
],
"properties": {
"expected_revision": {
"type": "integer",
"format": "int64"
}
}
}
}
}
},
"responses": {
"200": {
"description": "New immutable restore version committed, with updated entry and ETag",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MutationResult"
}
}
}
},
"409": {
"description": "Revision conflict"
}
}
}readVersionRangeRead 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.
readVersionRange(file: string, version: string, offset: number, length: number, signal?: AbortSignal): Promise<Uint8Array>Parameters
| Name | Type / default | Meaning |
|---|---|---|
file | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
version | string | Selected immutable version identity for this read, restore or sharing operation. |
offset | number | Non-negative byte offset, not a character offset. |
length | number | Byte count or logical byte size; non-negative and bounded by the operation. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<Uint8Array>Call example
await client.readVersionRange(file, version, offset, length, signal);HTTP requests
GET /files/{file}/versions/{version}/bytes
Stream bytes from one immutable historical version
{
"id": "get-files-file-versions-version-bytes",
"path": "/files/{file}/versions/{version}/bytes",
"method": "GET",
"summary": "Stream bytes from one immutable historical version",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "file",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "version",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "Range",
"in": "header",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Full historical content"
},
"206": {
"description": "Historical range"
},
"404": {
"description": "Version does not belong to file"
}
}
}Manage your drive and plan
requestOTPEmail a sign-in code+
static requestOTP(endpoint: string, email: string, signal?: AbortSignal): Promise<OTPChallenge>Parameters
| Name | Type / default | Meaning |
|---|---|---|
endpoint | string | API origin without /v1; HTTPS outside local development. |
email | string | Account or invitation email address. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<OTPChallenge>Call example
await Client.requestOTP(endpoint, email, signal);Input and result fields
{
"type": "object",
"required": [
"challenge_id",
"expires_at",
"resend_after"
],
"properties": {
"challenge_id": {
"type": "string",
"format": "uuid"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"resend_after": {
"type": "integer",
"minimum": 0
},
"code": {
"type": "string",
"description": "Only exposed by explicitly configured local integration fixtures. Never returned in production."
}
}
}HTTP requests
POST /auth/otp/request
Codes expire after 10 minutes, are single use, and allow five attempts. Resending invalidates the previous code. Requests have a 60-second cooldown and a per-email and per-IP rate limit. Storage is activated separately.
{
"id": "post-auth-otp-request",
"path": "/auth/otp/request",
"method": "POST",
"summary": "Email a sign-in code",
"description": "Codes expire after 10 minutes, are single use, and allow five attempts. Resending invalidates the previous code. Requests have a 60-second cooldown and a per-email and per-IP rate limit. Storage is activated separately.",
"security": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"format": "email",
"maxLength": 254
}
}
}
}
}
},
"responses": {
"202": {
"description": "Challenge accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OTPChallenge"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Invalid, expired, consumed or exhausted code"
},
"429": {
"description": "Rate limited; wait before trying again"
},
"503": {
"description": "Email delivery unavailable"
}
}
}verifyOTPSign in with an email code; create an account if needed+
static verifyOTP(endpoint: string, challenge_id: string, code: string, signal?: AbortSignal): Promise<{
client: Client;
session: AuthSession;
}>Parameters
| Name | Type / default | Meaning |
|---|---|---|
endpoint | string | API origin without /v1; HTTPS outside local development. |
challenge_id | string | Identity returned by requestOTP, bound to the email address and its expiry. |
code | string | Six-digit code from the sign-in email; keep leading zeroes and never log it. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<{
client: Client;
session: AuthSession;
}>Call example
await Client.verifyOTP(endpoint, challenge_id, code, signal);Input and result fields
{
"type": "object",
"required": [
"user",
"access_token",
"access_expires_at",
"refresh_token",
"refresh_expires_at"
],
"properties": {
"user": {
"$ref": "#/components/schemas/User"
},
"access_token": {
"type": "string",
"minLength": 1
},
"access_expires_at": {
"type": "string",
"format": "date-time"
},
"refresh_token": {
"type": "string",
"minLength": 1
},
"refresh_expires_at": {
"type": "string",
"format": "date-time"
}
}
}HTTP requests
POST /auth/otp/verify
Codes expire after 10 minutes, are single use, and allow five attempts. Resending invalidates the previous code. Requests have a 60-second cooldown and a per-email and per-IP rate limit. Storage is activated separately.
{
"id": "post-auth-otp-verify",
"path": "/auth/otp/verify",
"method": "POST",
"summary": "Sign in with an email code; create an account if needed",
"description": "Codes expire after 10 minutes, are single use, and allow five attempts. Resending invalidates the previous code. Requests have a 60-second cooldown and a per-email and per-IP rate limit. Storage is activated separately.",
"security": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"challenge_id",
"code"
],
"properties": {
"challenge_id": {
"type": "string",
"format": "uuid"
},
"code": {
"type": "string",
"pattern": "^[0-9]{6}$"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Session created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthSession"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Invalid, expired, consumed or exhausted code"
},
"429": {
"description": "Rate limited; wait before trying again"
},
"503": {
"description": "Email delivery unavailable"
}
}
}drivesDrives.+
drives(signal?: AbortSignal): Promise<Drive[]>Parameters
| Name | Type / default | Meaning |
|---|---|---|
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<Drive[]>Call example
await client.drives(signal);Input and result fields
{
"type": "object",
"required": [
"id",
"name",
"quota_bytes",
"used_bytes",
"state",
"plan",
"role",
"created_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"quota_bytes": {
"type": "integer",
"format": "int64"
},
"used_bytes": {
"type": "integer",
"format": "int64"
},
"state": {
"enum": [
"active",
"deleting",
"deleted"
]
},
"source_drive_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"source_sequence": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"plan": {
"enum": [
"individual",
"team",
"enterprise"
]
},
"role": {
"enum": [
"viewer",
"editor",
"admin",
"owner"
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}HTTP requests
GET /drives
{
"id": "get-drives",
"path": "/drives",
"method": "GET",
"security": [
{
"bearer": []
}
],
"responses": {
"200": {
"description": "Drives visible to the current identity, filtered by key scope"
}
}
}driveDrive.+
drive(id: string, signal?: AbortSignal): Promise<Drive>Parameters
| Name | Type / default | Meaning |
|---|---|---|
id | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<Drive>Call example
await client.drive(id, signal);Input and result fields
{
"type": "object",
"required": [
"id",
"name",
"quota_bytes",
"used_bytes",
"state",
"plan",
"role",
"created_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"quota_bytes": {
"type": "integer",
"format": "int64"
},
"used_bytes": {
"type": "integer",
"format": "int64"
},
"state": {
"enum": [
"active",
"deleting",
"deleted"
]
},
"source_drive_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"source_sequence": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"plan": {
"enum": [
"individual",
"team",
"enterprise"
]
},
"role": {
"enum": [
"viewer",
"editor",
"admin",
"owner"
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}HTTP requests
GET /drives/{drive}
{
"id": "get-drives-drive",
"path": "/drives/{drive}",
"method": "GET",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "drive",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Drive"
},
"404": {
"description": "Not found or inaccessible"
}
}
}administrationAdministration.+
administration(method: "GET" | "PUT" | "POST", path: string, body?: unknown, signal?: AbortSignal): Promise<any>Parameters
| Name | Type / default | Meaning |
|---|---|---|
method | "GET" | "PUT" | "POST" | Caller-supplied value of the declared type. See the linked operation or model for field constraints. |
path | string | Caller-supplied value of the declared type. See the linked operation or model for field constraints. |
body | unknownOptional | Caller-supplied value of the declared type. See the linked operation or model for field constraints. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<any>Call example
await client.administration(method, path, body, signal);platformConfigurationPlatform administrator draft and published configuration+
platformConfiguration(signal?: AbortSignal): Promise<PlatformConfiguration>Parameters
| Name | Type / default | Meaning |
|---|---|---|
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<PlatformConfiguration>Call example
await client.platformConfiguration(signal);Input and result fields
{
"type": "object",
"required": [
"revision",
"published",
"draft"
],
"properties": {
"revision": {
"type": "string"
},
"published": {
"$ref": "#/components/schemas/PlatformDocument"
},
"draft": {
"$ref": "#/components/schemas/PlatformDocument"
}
}
}HTTP requests
GET /platform/config
Platform administrator draft and published configuration
{
"id": "get-platform-config",
"path": "/platform/config",
"method": "GET",
"summary": "Platform administrator draft and published configuration",
"security": [
{
"bearer": []
}
],
"responses": {
"200": {
"description": "Platform administrator draft and published configuration",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PlatformConfiguration"
}
}
}
},
"401": {
"description": "Session required"
},
"403": {
"description": "Platform administrator access required"
},
"503": {
"description": "Configuration unavailable"
}
}
}savePlatformConfigurationSave a draft or publish product settings; platform administrator only+
savePlatformConfiguration(document: PlatformDocument, expectedRevision: string, publish?: boolean, signal?: AbortSignal): Promise<PlatformConfiguration>Parameters
| Name | Type / default | Meaning |
|---|---|---|
document | PlatformDocument | Caller-supplied value of the declared type. See the linked operation or model for field constraints. |
expectedRevision | string | Reviewed entry or policy revision. Do not substitute a file version ID. |
publish | booleanOptional | Caller-supplied value of the declared type. See the linked operation or model for field constraints. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<PlatformConfiguration>Call example
await client.savePlatformConfiguration(document, expectedRevision, publish, signal);Input and result fields
{
"type": "object",
"required": [
"plans",
"settings"
],
"properties": {
"plans": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PlanOption"
}
},
"settings": {
"$ref": "#/components/schemas/PlatformSettings"
}
}
}{
"type": "object",
"required": [
"revision",
"published",
"draft"
],
"properties": {
"revision": {
"type": "string"
},
"published": {
"$ref": "#/components/schemas/PlatformDocument"
},
"draft": {
"$ref": "#/components/schemas/PlatformDocument"
}
}
}HTTP requests
PUT /platform/config
Save a draft or publish product settings; platform administrator only
{
"id": "put-platform-config",
"path": "/platform/config",
"method": "PUT",
"summary": "Save a draft or publish product settings; platform administrator only",
"security": [
{
"bearer": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"expected_revision",
"document",
"publish"
],
"properties": {
"expected_revision": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
},
"document": {
"$ref": "#/components/schemas/PlatformDocument"
},
"publish": {
"type": "boolean"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Updated configuration",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PlatformConfiguration"
}
}
}
},
"400": {
"description": "Invalid settings"
},
"401": {
"description": "Session required"
},
"403": {
"description": "Platform administrator access required"
},
"409": {
"description": "Revision changed; reload before editing"
}
}
}plansPublished monthly plans and add-on terms+
plans(signal?: AbortSignal): Promise<PlanCatalog>Parameters
| Name | Type / default | Meaning |
|---|---|---|
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<PlanCatalog>Call example
await client.plans(signal);Input and result fields
{
"type": "object",
"required": [
"plans",
"currency",
"billing_interval",
"checkout_mode"
],
"properties": {
"revision": {
"type": "string"
},
"plans": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PlanOption"
}
},
"currency": {
"type": "string",
"const": "USD"
},
"billing_interval": {
"type": "string",
"const": "month"
},
"checkout_mode": {
"type": "string",
"enum": [
"disabled",
"development"
]
}
}
}HTTP requests
GET /plans
Published monthly plans and add-on terms
{
"id": "get-plans",
"path": "/plans",
"method": "GET",
"summary": "Published monthly plans and add-on terms",
"security": [],
"responses": {
"200": {
"description": "Checkout mode, USD monthly prices, included seats and per-tier addon rules",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PlanCatalog"
}
}
}
}
}
}subscriptionOwner-only subscription and storage/seat usage+
subscription(drive: string, signal?: AbortSignal): Promise<DriveSubscription>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<DriveSubscription>Call example
await client.subscription(drive, signal);Input and result fields
{
"type": "object",
"additionalProperties": false,
"required": [
"drive_id",
"billing_user_id",
"status",
"storage_bytes",
"seats",
"members",
"reserved_invitations",
"used_bytes",
"currency",
"monthly_total_minor",
"revision",
"current_period_end",
"current_period_start",
"billing_anchor",
"cycle_number",
"access_until",
"pending_monthly_total_minor",
"cancel_at_period_end",
"pending_storage_bytes",
"pending_seats"
],
"properties": {
"drive_id": {
"type": "string"
},
"billing_user_id": {
"type": "string"
},
"status": {
"type": "string"
},
"currency": {
"type": "string"
},
"revision": {
"type": "string"
},
"current_period_start": {
"type": "string",
"format": "date-time",
"description": "Start of the current monthly cycle in UTC."
},
"billing_anchor": {
"type": "string",
"format": "date-time",
"description": "UTC day and time used to calculate calendar-month boundaries. Reset to the new date when an administrator adjusts validity."
},
"cycle_number": {
"type": "integer",
"minimum": 1
},
"access_until": {
"type": "string",
"format": "date-time",
"description": "Authoritative validity date and next renewal boundary. Free subscriptions renew when automatic renewal is enabled."
},
"pending_monthly_total_minor": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"current_period_end": {
"type": "string"
},
"storage_bytes": {
"type": "integer",
"minimum": 0
},
"seats": {
"type": "integer",
"minimum": 0
},
"members": {
"type": "integer",
"minimum": 0
},
"reserved_invitations": {
"type": "integer",
"minimum": 0
},
"used_bytes": {
"type": "integer",
"minimum": 0
},
"monthly_total_minor": {
"type": "integer",
"minimum": 0
},
"cancel_at_period_end": {
"type": "boolean"
},
"pending_storage_bytes": {
"type": [
"integer",
"null"
],
"minimum": 1
},
"pending_seats": {
"type": [
"integer",
"null"
],
"minimum": 1
},
"plan_version_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"pending_plan_version_id": {
"type": [
"string",
"null"
],
"format": "uuid"
}
}
}HTTP requests
GET /drives/{drive}/subscription
Owner-only subscription and storage/seat usage
{
"id": "get-drives-drive-subscription",
"path": "/drives/{drive}/subscription",
"method": "GET",
"summary": "Owner-only subscription and storage/seat usage",
"security": [
{
"bearer": []
}
],
"responses": {
"200": {
"description": "Drive subscription",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DriveSubscription"
}
}
}
}
}
}changeSubscriptionDevelopment checkout for subscription changes; production requires billing configuration+
changeSubscription(drive: string, input: SubscriptionChange, signal?: AbortSignal): Promise<DriveSubscription>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
input | SubscriptionChange | Structured input of the declared type; use the linked schema for required fields and constraints. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<DriveSubscription>Call example
await client.changeSubscription(drive, input, signal);Input and result fields
{
"type": "object",
"additionalProperties": false,
"required": [
"drive_id",
"billing_user_id",
"status",
"storage_bytes",
"seats",
"members",
"reserved_invitations",
"used_bytes",
"currency",
"monthly_total_minor",
"revision",
"current_period_end",
"current_period_start",
"billing_anchor",
"cycle_number",
"access_until",
"pending_monthly_total_minor",
"cancel_at_period_end",
"pending_storage_bytes",
"pending_seats"
],
"properties": {
"drive_id": {
"type": "string"
},
"billing_user_id": {
"type": "string"
},
"status": {
"type": "string"
},
"currency": {
"type": "string"
},
"revision": {
"type": "string"
},
"current_period_start": {
"type": "string",
"format": "date-time",
"description": "Start of the current monthly cycle in UTC."
},
"billing_anchor": {
"type": "string",
"format": "date-time",
"description": "UTC day and time used to calculate calendar-month boundaries. Reset to the new date when an administrator adjusts validity."
},
"cycle_number": {
"type": "integer",
"minimum": 1
},
"access_until": {
"type": "string",
"format": "date-time",
"description": "Authoritative validity date and next renewal boundary. Free subscriptions renew when automatic renewal is enabled."
},
"pending_monthly_total_minor": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"current_period_end": {
"type": "string"
},
"storage_bytes": {
"type": "integer",
"minimum": 0
},
"seats": {
"type": "integer",
"minimum": 0
},
"members": {
"type": "integer",
"minimum": 0
},
"reserved_invitations": {
"type": "integer",
"minimum": 0
},
"used_bytes": {
"type": "integer",
"minimum": 0
},
"monthly_total_minor": {
"type": "integer",
"minimum": 0
},
"cancel_at_period_end": {
"type": "boolean"
},
"pending_storage_bytes": {
"type": [
"integer",
"null"
],
"minimum": 1
},
"pending_seats": {
"type": [
"integer",
"null"
],
"minimum": 1
},
"plan_version_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"pending_plan_version_id": {
"type": [
"string",
"null"
],
"format": "uuid"
}
}
}{
"type": "object",
"additionalProperties": false,
"required": [
"storage_bytes",
"seats",
"expected_revision",
"cancel_at_period_end"
],
"properties": {
"storage_bytes": {
"type": "integer",
"minimum": 1,
"maximum": 1000000000000000
},
"seats": {
"type": "integer",
"minimum": 1,
"maximum": 100000
},
"expected_revision": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
},
"cancel_at_period_end": {
"type": "boolean"
},
"plan_version_id": {
"type": "string",
"format": "uuid",
"description": "Version returned by GET /plans. Rejects stale terms with 409; omit when cancelling an existing subscription."
}
},
"description": "Storage and member allowances are validated against the published plan catalog. Retrieve /plans before selecting a plan; prices and add-on increments can change."
}HTTP requests
PUT /drives/{drive}/subscription
Development checkout for subscription changes; production requires billing configuration
{
"id": "put-drives-drive-subscription",
"path": "/drives/{drive}/subscription",
"method": "PUT",
"summary": "Development checkout for subscription changes; production requires billing configuration",
"security": [
{
"bearer": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubscriptionChange"
}
}
}
},
"responses": {
"200": {
"description": "Updated subscription; decreases take effect at renewal",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DriveSubscription"
}
}
}
},
"503": {
"description": "Real billing is not configured; no charge or entitlement change"
}
}
}leaveDriveLeave a shared drive; the owner cannot leave+
leaveDrive(drive: string, signal?: AbortSignal): Promise<void>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<void>Call example
await client.leaveDrive(drive, signal);HTTP requests
DELETE /drives/{drive}/membership
Leave a shared drive; the owner cannot leave
{
"id": "delete-drives-drive-membership",
"path": "/drives/{drive}/membership",
"method": "DELETE",
"summary": "Leave a shared drive; the owner cannot leave",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "drive",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Access revoked; purchased seat quantity is unchanged"
}
}
}createDriveActivate an owned drive from selected storage and seats+
createDrive(input: DrivePlanSelection, signal?: AbortSignal): Promise<Drive>Parameters
| Name | Type / default | Meaning |
|---|---|---|
input | DrivePlanSelection | Structured input of the declared type; use the linked schema for required fields and constraints. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<Drive>Call example
await client.createDrive(input, signal);Input and result fields
{
"type": "object",
"additionalProperties": false,
"required": [
"name",
"storage_bytes",
"seats"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"storage_bytes": {
"type": "integer",
"minimum": 1,
"maximum": 1000000000000000
},
"seats": {
"type": "integer",
"minimum": 1,
"maximum": 100000
},
"plan_version_id": {
"type": "string",
"format": "uuid",
"description": "Version returned by GET /plans. Rejects stale terms with 409; omit when cancelling an existing subscription."
}
},
"description": "Storage and member allowances are validated against the published plan catalog. Retrieve /plans before selecting a plan; prices and add-on increments can change."
}{
"type": "object",
"required": [
"id",
"name",
"quota_bytes",
"used_bytes",
"state",
"plan",
"role",
"created_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"quota_bytes": {
"type": "integer",
"format": "int64"
},
"used_bytes": {
"type": "integer",
"format": "int64"
},
"state": {
"enum": [
"active",
"deleting",
"deleted"
]
},
"source_drive_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"source_sequence": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"plan": {
"enum": [
"individual",
"team",
"enterprise"
]
},
"role": {
"enum": [
"viewer",
"editor",
"admin",
"owner"
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}HTTP requests
POST /drives
Activate an owned drive from selected storage and seats
{
"id": "post-drives",
"path": "/drives",
"method": "POST",
"summary": "Activate an owned drive from selected storage and seats",
"security": [
{
"bearer": []
}
],
"responses": {
"201": {
"description": "Drive created"
},
"403": {
"description": "Permission or entitlement limit"
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DrivePlanSelection"
}
}
}
}
}deleteDriveDelete Drive.+
deleteDrive(id: string, signal?: AbortSignal): Promise<void>Parameters
| Name | Type / default | Meaning |
|---|---|---|
id | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<void>Call example
await client.deleteDrive(id, signal);HTTP requests
DELETE /drives/{drive}
{
"id": "delete-drives-drive",
"path": "/drives/{drive}",
"method": "DELETE",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "drive",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Drive deleted"
},
"404": {
"description": "Drive inaccessible"
}
}
}Manage members and audit activity
memberPolicyRead explicit drive member limit and occupied seats+
memberPolicy(drive: string, signal?: AbortSignal): Promise<DriveMemberPolicy>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<DriveMemberPolicy>Call example
await client.memberPolicy(drive, signal);Input and result fields
{
"type": "object",
"additionalProperties": false,
"required": [
"drive_id",
"max_members",
"members",
"reserved_invitations",
"revision"
],
"properties": {
"drive_id": {
"type": "string",
"format": "uuid"
},
"max_members": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 100000
},
"members": {
"type": "integer",
"minimum": 1
},
"reserved_invitations": {
"type": "integer",
"minimum": 0
},
"revision": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
}
}
}HTTP requests
GET /drives/{drive}/members/policy
Interactive owner or admin only. Null means no configured cap. The owner counts as a member. Distinct active invitation emails reserve seats until accepted or unusable.
{
"id": "get-drives-drive-members-policy",
"path": "/drives/{drive}/members/policy",
"method": "GET",
"summary": "Read explicit drive member limit and occupied seats",
"description": "Interactive owner or admin only. Null means no configured cap. The owner counts as a member. Distinct active invitation emails reserve seats until accepted or unusable.",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "drive",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Member policy",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DriveMemberPolicy"
}
}
}
},
"400": {
"description": "Invalid drive ID"
},
"401": {
"description": "Interactive session required"
},
"404": {
"description": "Administration unavailable"
},
"500": {
"description": "Policy read failed"
}
}
}accountAuditRead a bounded page of account audit history+
accountAudit(limit?: number, cursor?: string, signal?: AbortSignal): Promise<AuditPage>Parameters
| Name | Type / default | Meaning |
|---|---|---|
limit | numberOptional | Bounded page size; endpoint-specific limits apply. |
cursor | stringOptional | Opaque cursor returned by this same operation and scope. Omit for the first page. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<AuditPage>Call example
await client.accountAudit(limit, cursor, signal);Input and result fields
{
"type": "object",
"additionalProperties": false,
"required": [
"events",
"next_cursor"
],
"properties": {
"events": {
"type": "array",
"maxItems": 200,
"items": {
"$ref": "#/components/schemas/AuditEvent"
}
},
"next_cursor": {
"type": [
"string",
"null"
],
"maxLength": 256
}
}
}HTTP requests
GET /account/audit
Interactive account session required on every page. The authenticated user is the account subject; no supplied account ID is accepted. Drive events and unattributed unknown login attempts are excluded. Anonymous recovery and reuse events retain null actors. Events descend by identity rather than timestamp. Continue with next_cursor until null; refresh without a cursor for new events. This live traversal is not a database snapshot and late commits may require a refresh. Raw metadata and credential material are omitted.
{
"id": "get-account-audit",
"path": "/account/audit",
"method": "GET",
"summary": "Read a bounded page of account audit history",
"description": "Interactive account session required on every page. The authenticated user is the account subject; no supplied account ID is accepted. Drive events and unattributed unknown login attempts are excluded. Anonymous recovery and reuse events retain null actors. Events descend by identity rather than timestamp. Continue with next_cursor until null; refresh without a cursor for new events. This live traversal is not a database snapshot and late commits may require a refresh. Raw metadata and credential material are omitted.",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 50
}
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string",
"maxLength": 256
}
}
],
"responses": {
"200": {
"description": "Audit page",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuditPage"
}
}
}
},
"400": {
"description": "Invalid page limit or account cursor"
},
"401": {
"description": "Interactive session required"
},
"404": {
"description": "Account administration unavailable"
},
"500": {
"description": "Audit history could not be read"
}
}
}accountAuditRetentionPolicyRead account audit retention policy+
accountAuditRetentionPolicy(signal?: AbortSignal): Promise<AccountAuditRetentionPolicy>Parameters
| Name | Type / default | Meaning |
|---|---|---|
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<AccountAuditRetentionPolicy>Call example
await client.accountAuditRetentionPolicy(signal);Input and result fields
{
"type": "object",
"additionalProperties": false,
"required": [
"user_id",
"keep_days",
"legal_hold",
"revision"
],
"properties": {
"user_id": {
"type": "string",
"format": "uuid"
},
"keep_days": {
"type": [
"integer",
"null"
],
"minimum": 7,
"maximum": 36500,
"description": "Null retains account audit history indefinitely"
},
"legal_hold": {
"type": "boolean",
"description": "Account legal hold blocks cleanup and cannot be changed by this endpoint"
},
"revision": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
}
}
}HTTP requests
GET /account/audit/retention
Requires an interactive account owner session. Null keep_days means indefinite retention. Account legal hold blocks cleanup.
{
"id": "get-account-audit-retention",
"path": "/account/audit/retention",
"method": "GET",
"summary": "Read account audit retention policy",
"description": "Requires an interactive account owner session. Null keep_days means indefinite retention. Account legal hold blocks cleanup.",
"security": [
{
"bearer": []
}
],
"responses": {
"200": {
"description": "Audit retention policy",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountAuditRetentionPolicy"
}
}
}
},
"400": {
"description": "Invalid account ID"
},
"401": {
"description": "Interactive session required"
},
"404": {
"description": "Account administration unavailable"
}
}
}updateAccountAuditRetentionPolicyConfigure account audit retention with a displayed revision guard+
updateAccountAuditRetentionPolicy(keepDays: number | null, expectedRevision: string, signal?: AbortSignal): Promise<AccountAuditRetentionPolicy>Parameters
| Name | Type / default | Meaning |
|---|---|---|
keepDays | number | null | Retention interval in days; absent/null retains indefinitely where the policy permits it. |
expectedRevision | string | Reviewed entry or policy revision. Do not substitute a file version ID. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<AccountAuditRetentionPolicy>Call example
await client.updateAccountAuditRetentionPolicy(keepDays, expectedRevision, signal);Input and result fields
{
"type": "object",
"additionalProperties": false,
"required": [
"user_id",
"keep_days",
"legal_hold",
"revision"
],
"properties": {
"user_id": {
"type": "string",
"format": "uuid"
},
"keep_days": {
"type": [
"integer",
"null"
],
"minimum": 7,
"maximum": 36500,
"description": "Null retains account audit history indefinitely"
},
"legal_hold": {
"type": "boolean",
"description": "Account legal hold blocks cleanup and cannot be changed by this endpoint"
},
"revision": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
}
}
}HTTP requests
PUT /account/audit/retention
Requires an interactive account owner session. Setting 7–36500 days enables bounded background retirement; null disables retirement. Existing legal hold remains unchanged. Cleanup already committed cannot be undone by a later hold or policy extension.
{
"id": "put-account-audit-retention",
"path": "/account/audit/retention",
"method": "PUT",
"summary": "Configure account audit retention with a displayed revision guard",
"description": "Requires an interactive account owner session. Setting 7–36500 days enables bounded background retirement; null disables retirement. Existing legal hold remains unchanged. Cleanup already committed cannot be undone by a later hold or policy extension.",
"security": [
{
"bearer": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuditRetentionUpdate"
}
}
}
},
"responses": {
"200": {
"description": "Updated audit retention policy",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountAuditRetentionPolicy"
}
}
}
},
"400": {
"description": "Invalid retention days or displayed revision"
},
"401": {
"description": "Interactive session required"
},
"404": {
"description": "Account administration unavailable"
},
"409": {
"description": "Displayed policy revision is stale"
}
}
}auditRetentionPolicyRead drive audit retention policy+
auditRetentionPolicy(drive: string, signal?: AbortSignal): Promise<AuditRetentionPolicy>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<AuditRetentionPolicy>Call example
await client.auditRetentionPolicy(drive, signal);Input and result fields
{
"type": "object",
"additionalProperties": false,
"required": [
"drive_id",
"keep_days",
"legal_hold",
"revision"
],
"properties": {
"drive_id": {
"type": "string",
"format": "uuid"
},
"keep_days": {
"type": [
"integer",
"null"
],
"minimum": 7,
"maximum": 36500,
"description": "Null retains audit history indefinitely"
},
"legal_hold": {
"type": "boolean",
"description": "Shared drive legal hold blocks audit cleanup"
},
"revision": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
}
}
}HTTP requests
GET /drives/{drive}/audit/retention
Requires an interactive owner or admin session. Null keep_days means indefinite retention. Shared drive legal hold blocks cleanup.
{
"id": "get-drives-drive-audit-retention",
"path": "/drives/{drive}/audit/retention",
"method": "GET",
"summary": "Read drive audit retention policy",
"description": "Requires an interactive owner or admin session. Null keep_days means indefinite retention. Shared drive legal hold blocks cleanup.",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "drive",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Audit retention policy",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuditRetentionPolicy"
}
}
}
},
"400": {
"description": "Invalid drive ID"
},
"401": {
"description": "Interactive session required"
},
"404": {
"description": "Drive administration unavailable"
}
}
}updateAuditRetentionPolicyConfigure drive audit retention with a displayed revision guard+
updateAuditRetentionPolicy(drive: string, keepDays: number | null, expectedRevision: string, signal?: AbortSignal): Promise<AuditRetentionPolicy>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
keepDays | number | null | Retention interval in days; absent/null retains indefinitely where the policy permits it. |
expectedRevision | string | Reviewed entry or policy revision. Do not substitute a file version ID. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<AuditRetentionPolicy>Call example
await client.updateAuditRetentionPolicy(drive, keepDays, expectedRevision, signal);Input and result fields
{
"type": "object",
"additionalProperties": false,
"required": [
"drive_id",
"keep_days",
"legal_hold",
"revision"
],
"properties": {
"drive_id": {
"type": "string",
"format": "uuid"
},
"keep_days": {
"type": [
"integer",
"null"
],
"minimum": 7,
"maximum": 36500,
"description": "Null retains audit history indefinitely"
},
"legal_hold": {
"type": "boolean",
"description": "Shared drive legal hold blocks audit cleanup"
},
"revision": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
}
}
}HTTP requests
PUT /drives/{drive}/audit/retention
Requires an interactive owner or admin session. Setting 7–36500 days enables bounded background retirement; null disables retirement. Existing legal hold remains unchanged. Cleanup already committed cannot be undone by a later hold or policy extension.
{
"id": "put-drives-drive-audit-retention",
"path": "/drives/{drive}/audit/retention",
"method": "PUT",
"summary": "Configure drive audit retention with a displayed revision guard",
"description": "Requires an interactive owner or admin session. Setting 7–36500 days enables bounded background retirement; null disables retirement. Existing legal hold remains unchanged. Cleanup already committed cannot be undone by a later hold or policy extension.",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "drive",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuditRetentionUpdate"
}
}
}
},
"responses": {
"200": {
"description": "Updated audit retention policy",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuditRetentionPolicy"
}
}
}
},
"400": {
"description": "Invalid retention days or displayed revision"
},
"401": {
"description": "Interactive session required"
},
"404": {
"description": "Drive administration unavailable"
},
"409": {
"description": "Displayed policy revision is stale"
}
}
}exportDriveAuditWrite ordered audit records to a sink and emit a completion record only after successful output.+
exportDriveAudit(drive: string, writeLine: (line: string) => Promise<void>, pageLimit?: number, signal?: AbortSignal): Promise<bigint>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
writeLine | (line: string) => Promise<void> | Caller-owned output destination. Output failures prevent successful completion. |
pageLimit | numberOptional | Bounded page size; endpoint-specific limits apply. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<bigint>Call example
await client.exportDriveAudit(drive, writeLine, pageLimit, signal);driveAuditRead a bounded page of drive audit history+
driveAudit(drive: string, limit?: number, cursor?: string, signal?: AbortSignal): Promise<AuditPage>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
limit | numberOptional | Bounded page size; endpoint-specific limits apply. |
cursor | stringOptional | Opaque cursor returned by this same operation and scope. Omit for the first page. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<AuditPage>Call example
await client.driveAudit(drive, limit, cursor, signal);Input and result fields
{
"type": "object",
"additionalProperties": false,
"required": [
"events",
"next_cursor"
],
"properties": {
"events": {
"type": "array",
"maxItems": 200,
"items": {
"$ref": "#/components/schemas/AuditEvent"
}
},
"next_cursor": {
"type": [
"string",
"null"
],
"maxLength": 256
}
}
}HTTP requests
GET /drives/{drive}/audit
Interactive owner or admin session required on every page. Events descend by identity rather than timestamp. Continue with next_cursor until null; refresh without a cursor for new events. This live traversal is not a database snapshot and late commits may require a refresh. Raw metadata and credential material are omitted.
{
"id": "get-drives-drive-audit",
"path": "/drives/{drive}/audit",
"method": "GET",
"summary": "Read a bounded page of drive audit history",
"description": "Interactive owner or admin session required on every page. Events descend by identity rather than timestamp. Continue with next_cursor until null; refresh without a cursor for new events. This live traversal is not a database snapshot and late commits may require a refresh. Raw metadata and credential material are omitted.",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "drive",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 50
}
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string",
"maxLength": 256
}
}
],
"responses": {
"200": {
"description": "Audit page",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuditPage"
}
}
}
},
"400": {
"description": "Invalid page limit or drive cursor"
},
"401": {
"description": "Interactive session required"
},
"404": {
"description": "Drive administration unavailable"
},
"500": {
"description": "Audit history could not be read"
}
}
}driveMembersDrive Members.+
driveMembers(drive: string, signal?: AbortSignal): Promise<DriveMember[]>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<DriveMember[]>Call example
await client.driveMembers(drive, signal);Input and result fields
{
"type": "object",
"required": [
"user_id",
"email",
"role",
"created_at"
],
"additionalProperties": false,
"properties": {
"user_id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"role": {
"type": "string",
"enum": [
"owner",
"admin",
"editor",
"viewer"
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}HTTP requests
GET /drives/{drive}/members
{
"id": "get-drives-drive-members",
"path": "/drives/{drive}/members",
"method": "GET",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "drive",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Drive members",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"members"
],
"properties": {
"members": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DriveMember"
}
}
}
}
}
}
}
}
}updateDriveMemberChange a non-owner member role using interactive admin authority+
updateDriveMember(drive: string, member: string, role: "admin" | "editor" | "viewer", expectedRole: DriveMember["role"], signal?: AbortSignal): Promise<DriveMember>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
member | string | Target member identity; owner changes use the dedicated ownership operation. |
role | "admin" | "editor" | "viewer" | Requested member role. The drive owner cannot be changed. |
expectedRole | DriveMember["role"] | Member role you reviewed; rejects a stale administrative change. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<DriveMember>Call example
await client.updateDriveMember(drive, member, role, expectedRole, signal);Input and result fields
{
"type": "object",
"required": [
"user_id",
"email",
"role",
"created_at"
],
"additionalProperties": false,
"properties": {
"user_id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"role": {
"type": "string",
"enum": [
"owner",
"admin",
"editor",
"viewer"
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}HTTP requests
PATCH /drives/{drive}/members/{member}
Change a non-owner member role using interactive admin authority
{
"id": "patch-drives-drive-members-member",
"path": "/drives/{drive}/members/{member}",
"method": "PATCH",
"summary": "Change a non-owner member role using interactive admin authority",
"security": [
{
"bearer": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DriveMemberChange"
}
}
}
},
"responses": {
"200": {
"description": "Updated member",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DriveMember"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Interactive session required"
},
"403": {
"description": "Owner is protected"
},
"404": {
"description": "Drive or member inaccessible"
},
"409": {
"description": "Displayed role no longer matches"
}
}
}removeDriveMemberRemove non-owner access and invalidate outstanding invitations+
removeDriveMember(drive: string, member: string, expectedRole: DriveMember["role"], signal?: AbortSignal): Promise<void>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
member | string | Target member identity; owner changes use the dedicated ownership operation. |
expectedRole | DriveMember["role"] | Member role you reviewed; rejects a stale administrative change. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<void>Call example
await client.removeDriveMember(drive, member, expectedRole, signal);Input and result fields
{
"type": "object",
"required": [
"user_id",
"email",
"role",
"created_at"
],
"additionalProperties": false,
"properties": {
"user_id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"role": {
"type": "string",
"enum": [
"owner",
"admin",
"editor",
"viewer"
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}HTTP requests
DELETE /drives/{drive}/members/{member}
Remove non-owner access and invalidate outstanding invitations
{
"id": "delete-drives-drive-members-member",
"path": "/drives/{drive}/members/{member}",
"method": "DELETE",
"summary": "Remove non-owner access and invalidate outstanding invitations",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "expected_role",
"in": "query",
"required": true,
"schema": {
"type": "string",
"enum": [
"viewer",
"editor",
"admin",
"owner"
]
}
}
],
"responses": {
"204": {
"description": "Membership removed; files remain unchanged"
},
"400": {
"description": "Missing or invalid displayed role"
},
"401": {
"description": "Interactive session required"
},
"403": {
"description": "Owner is protected"
},
"404": {
"description": "Drive or member inaccessible"
},
"409": {
"description": "Displayed role no longer matches"
}
}
}inviteDriveMemberInvite Drive Member.+
inviteDriveMember(drive: string, email: string, role: "admin" | "editor" | "viewer", signal?: AbortSignal): Promise<InvitationResult>Parameters
| Name | Type / default | Meaning |
|---|---|---|
drive | string | Target identity or structured input of the declared type. Current authority and endpoint constraints apply. |
email | string | Account or invitation email address. |
role | "admin" | "editor" | "viewer" | Requested member role. The drive owner cannot be changed. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<InvitationResult>Call example
await client.inviteDriveMember(drive, email, role, signal);Input and result fields
{
"type": "object",
"required": [
"invitation"
],
"additionalProperties": false,
"properties": {
"invitation": {
"$ref": "#/components/schemas/DriveInvitation"
},
"token": {
"type": "string",
"minLength": 1,
"description": "One-time token exposed only by configured local development delivery"
}
}
}HTTP requests
POST /drives/{drive}/invitations
{
"id": "post-drives-drive-invitations",
"path": "/drives/{drive}/invitations",
"method": "POST",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "drive",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"201": {
"description": "Invitation created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InvitationResult"
}
}
}
},
"409": {
"description": "Configured member limit reached"
},
"500": {
"description": "Invitation and audit could not be committed"
}
}
}acceptDriveInvitationAccept Drive Invitation.+
acceptDriveInvitation(token: string, signal?: AbortSignal): Promise<Drive>Parameters
| Name | Type / default | Meaning |
|---|---|---|
token | string | Credential for this operation. Use interactive, machine or recipient authority as applicable; keep it private. |
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<Drive>Call example
await client.acceptDriveInvitation(token, signal);Input and result fields
{
"type": "object",
"required": [
"id",
"name",
"quota_bytes",
"used_bytes",
"state",
"plan",
"role",
"created_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"quota_bytes": {
"type": "integer",
"format": "int64"
},
"used_bytes": {
"type": "integer",
"format": "int64"
},
"state": {
"enum": [
"active",
"deleting",
"deleted"
]
},
"source_drive_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"source_sequence": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"plan": {
"enum": [
"individual",
"team",
"enterprise"
]
},
"role": {
"enum": [
"viewer",
"editor",
"admin",
"owner"
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}HTTP requests
POST /invitations/accept
{
"id": "post-invitations-accept",
"path": "/invitations/accept",
"method": "POST",
"security": [
{
"bearer": []
}
],
"responses": {
"200": {
"description": "Membership added or existing role preserved",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Drive"
}
}
}
},
"404": {
"description": "Invitation expired or revoked or issuer no longer has admin authority"
},
"409": {
"description": "Configured member limit reached"
},
"500": {
"description": "Membership and audit could not be committed"
}
}
}platformAuditLatest 100 product configuration changes; platform administrator only+
platformAudit(signal?: AbortSignal): Promise<PlatformAuditEntry[]>Parameters
| Name | Type / default | Meaning |
|---|---|---|
signal | AbortSignalOptional | Optional AbortSignal for cancellation. |
Returns
Promise<PlatformAuditEntry[]>Call example
await client.platformAudit(signal);Input and result fields
{
"type": "object",
"required": [
"id",
"user_id",
"action",
"revision",
"before",
"after",
"created_at"
],
"properties": {
"id": {
"type": "string"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"action": {
"type": "string"
},
"revision": {
"type": "string"
},
"before": {},
"after": {},
"created_at": {
"type": "string",
"format": "date-time"
},
"resource_type": {
"type": "string"
},
"resource_id": {
"type": "string"
},
"reason": {
"type": "string"
}
}
}HTTP requests
GET /platform/audit
Latest 100 product configuration changes; platform administrator only
{
"id": "get-platform-audit",
"path": "/platform/audit",
"method": "GET",
"summary": "Latest 100 product configuration changes; platform administrator only",
"security": [
{
"bearer": []
}
],
"responses": {
"200": {
"description": "Audit records, newest first",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PlatformAuditEntry"
}
}
}
}
}
}
},
"401": {
"description": "Session required"
},
"403": {
"description": "Platform administrator access required"
}
}
}Errors and exact retries
Handle a failed version guard without silently overwriting a newer edit. This fragment uses an existing client and your pending input.
import { PreconditionError, AuthorizationError } from "@nufs/sdk";
try {
await client.writeAt(fileId, 0, data, reviewedVersion,
{ idempotencyKey: operationId });
} catch (error) {
if (error instanceof PreconditionError) {
// Preserve data and inspect the newer head before another edit.
} else if (error instanceof AuthorizationError) {
// Check current authority; do not report the edit as saved.
}
throw error;
}