Beta
Download

nuFS Public Beta. Compatibility changes and release notes.

Build with nuFS · 0.2.0

SDKs

Install a client, run the first-file example, then browse the methods by task. Signatures, parameters, return values and call examples are included below.

Install and configure

Go 1.24+ · context-aware HTTP client. Install the supplied 0.2.0 release artifact:

Installation
# Use the supplied local module proxy directory.
GOPROXY=file:///absolute/path/to/go go get github.com/nufs/nufs-sdk-go@v0.2.0

Create a drive-scoped access key in your drive. Use its REST bearer token, your API origin without /v1, and the drive ID for the example.

Environment
export NUFS_ENDPOINT='https://api.example.test'
export NUFS_TOKEN='REPLACE_WITH_REST_BEARER'
export NUFS_DRIVE_ID='REPLACE_WITH_DRIVE_ID'

Create, update and read a file

This example creates a new file, saves its contents, edits the first byte with a version guard and reads the saved contents.

Code
package main

import (
    "context"
    "fmt"
    "os"
    "time"
    "github.com/nufs/nufs-sdk-go/nufs"
)

func run() error {
    ctx := context.Background()
    client := nufs.New(os.Getenv("NUFS_ENDPOINT"), os.Getenv("NUFS_TOKEN"))
    name := fmt.Sprintf("notes-%d.txt", time.Now().UnixNano())
    file, err := client.CreateEntry(ctx, os.Getenv("NUFS_DRIVE_ID"), name, "file", nil)
    if err != nil { return err }
    first, err := client.WriteFile(ctx, file.ID, []byte("hello"), "", "")
    if err != nil { return err }
    saved, err := client.WriteAt(ctx, file.ID, 0, []byte("H"), first.Version.ID, "")
    if err != nil { return err }
    original, err := client.ReadVersionRange(ctx, file.ID, saved.Version.ID, 0, 5)
    if err != nil { return err }
    fmt.Println(string(original)) // Hello
    return nil
}
func main() {
    if err := run(); err != nil { fmt.Fprintln(os.Stderr, err); os.Exit(1) }
}

Method reference

70 Go methods, grouped by task.

Connect and authenticate

NewConstruct an authorized client for a nuFS endpoint.
Code
func New(endpoint, credential string) *Client

Parameters

NameType / defaultMeaning
endpointstringAPI origin without /v1; HTTPS outside local development.
credentialstringCredential for this operation. Use interactive, machine or recipient authority as applicable; keep it private.

Returns

Code
*Client

Call example

Code
nufs.New(endpoint, credential)
NewWithHTTPClientConstruct a client with a caller-supplied HTTP transport.
Code
func NewWithHTTPClient(endpoint, credential string, client *http.Client) *Client

Parameters

NameType / defaultMeaning
endpointstringAPI origin without /v1; HTTPS outside local development.
credentialstringCredential for this operation. Use interactive, machine or recipient authority as applicable; keep it private.
client*http.ClientCaller-supplied HTTP transport of the declared type.

Returns

Code
*Client

Call example

Code
nufs.NewWithHTTPClient(endpoint, credential, client)
RefreshRotate a refresh token
Code
func Refresh(ctx context.Context, endpoint, refreshToken string) (RefreshedSession, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
endpointstringAPI origin without /v1; HTTPS outside local development.
refreshTokenstringCredential for this operation. Use interactive, machine or recipient authority as applicable; keep it private.

Returns

Code
(RefreshedSession, error)

Call example

Code
nufs.Refresh(ctx, endpoint, refreshToken)
Input and result fields
RefreshedSession
{
  "type": "object",
  "required": [
    "access_token",
    "access_expires_at",
    "refresh_token",
    "refresh_expires_at"
  ],
  "properties": {
    "access_token": {
      "type": "string",
      "minLength": 1
    },
    "access_expires_at": {
      "type": "string",
      "format": "date-time"
    },
    "refresh_token": {
      "type": "string",
      "minLength": 1
    },
    "refresh_expires_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}
HTTP requests

POST /auth/refresh

Rotate a refresh token

Request and response contract
{
  "id": "post-auth-refresh",
  "path": "/auth/refresh",
  "method": "POST",
  "summary": "Rotate a refresh token",
  "security": [],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "refresh_token"
          ],
          "properties": {
            "refresh_token": {
              "type": "string",
              "minLength": 1
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Rotated session",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/RefreshedSession"
          }
        }
      }
    },
    "401": {
      "description": "invalid_session",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "500": {
      "description": "Session rotation or reuse revocation could not be committed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    }
  }
}
LogoutLogout.
Code
func (c *Client) Logout(ctx context.Context) error

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.

Returns

Code
error

Call example

Code
client.Logout(ctx)
HTTP requests

POST /auth/logout

Request and response contract
{
  "id": "post-auth-logout",
  "path": "/auth/logout",
  "method": "POST",
  "security": [
    {
      "bearer": []
    }
  ],
  "responses": {
    "204": {
      "description": "Current interactive session revoked"
    },
    "401": {
      "description": "Interactive session required; machine keys return unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "500": {
      "description": "Session revocation could not be committed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    }
  }
}
CreateAccessKeyCreate a machine credential; its secret is returned exactly once
Code
func (c *Client) CreateAccessKey(ctx context.Context, label, access, scopeType string, scopeID *string, expiresAt *string) (AccessKeyResult, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
labelstringName or label accepted by this operation; it must meet server constraints.
accessstringRequested authority within the caller’s current permitted scope.
scopeTypestringAccount/drive/drive scope as accepted by this credential operation.
scopeID*stringAccount/drive/drive scope as accepted by this credential operation.
expiresAt*stringExpiry in the declared timestamp format; server policy bounds the grant.

Returns

Code
(AccessKeyResult, error)

Call example

Code
client.CreateAccessKey(ctx, label, access, scopeType, scopeID, expiresAt)
HTTP requests

POST /access-keys

Create a machine credential; its secret is returned exactly once

Request and response contract
{
  "id": "post-access-keys",
  "path": "/access-keys",
  "method": "POST",
  "summary": "Create a machine credential; its secret is returned exactly once",
  "security": [
    {
      "bearer": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "label",
            "access"
          ],
          "properties": {
            "label": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100
            },
            "access": {
              "enum": [
                "read",
                "write",
                "admin"
              ]
            },
            "scope_type": {
              "enum": [
                "account",
                "drive"
              ],
              "default": "account"
            },
            "scope_id": {
              "type": [
                "string",
                "null"
              ],
              "format": "uuid"
            },
            "expires_at": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            }
          }
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Access key, one-time bearer secret, and separate S3 access-key ID/signing secret"
    },
    "401": {
      "description": "Interactive session required"
    }
  }
}
AccessKeysList active machine credentials
Code
func (c *Client) AccessKeys(ctx context.Context) ([]map[string]any, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.

Returns

Code
([]map[string]any, error)

Call example

Code
client.AccessKeys(ctx)
HTTP requests

GET /access-keys

List active machine credentials

Request and response contract
{
  "id": "get-access-keys",
  "path": "/access-keys",
  "method": "GET",
  "summary": "List active machine credentials",
  "security": [
    {
      "bearer": []
    }
  ],
  "responses": {
    "200": {
      "description": "Active access keys"
    },
    "401": {
      "description": "Interactive session required"
    }
  }
}

POST /access-keys

Create a machine credential; its secret is returned exactly once

Request and response contract
{
  "id": "post-access-keys",
  "path": "/access-keys",
  "method": "POST",
  "summary": "Create a machine credential; its secret is returned exactly once",
  "security": [
    {
      "bearer": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "label",
            "access"
          ],
          "properties": {
            "label": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100
            },
            "access": {
              "enum": [
                "read",
                "write",
                "admin"
              ]
            },
            "scope_type": {
              "enum": [
                "account",
                "drive"
              ],
              "default": "account"
            },
            "scope_id": {
              "type": [
                "string",
                "null"
              ],
              "format": "uuid"
            },
            "expires_at": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            }
          }
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Access key, one-time bearer secret, and separate S3 access-key ID/signing secret"
    },
    "401": {
      "description": "Interactive session required"
    }
  }
}
RevokeAccessKeyRevoke a machine credential
Code
func (c *Client) RevokeAccessKey(ctx context.Context, id string) error

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
idstringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code
error

Call example

Code
client.RevokeAccessKey(ctx, id)
HTTP requests

DELETE /access-keys/{key}

Revoke a machine credential

Request and response contract
{
  "id": "delete-access-keys-key",
  "path": "/access-keys/{key}",
  "method": "DELETE",
  "summary": "Revoke a machine credential",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "key",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "204": {
      "description": "Revoked"
    },
    "404": {
      "description": "Access key not found"
    }
  }
}
MountCredentialsIssue a short-lived read or write credential for one drive
Code
func (c *Client) MountCredentials(ctx context.Context, drive, access string) (map[string]any, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
drivestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
accessstringRequested authority within the caller’s current permitted scope.

Returns

Code
(map[string]any, error)

Call example

Code
client.MountCredentials(ctx, drive, access)
HTTP requests

POST /drives/{drive}/mount-credentials

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

Request and response contract
{
  "id": "post-drives-drive-mount-credentials",
  "path": "/drives/{drive}/mount-credentials",
  "method": "POST",
  "summary": "Issue a short-lived read or write credential for one drive",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "drive",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "access": {
              "type": "string",
              "enum": [
                "read",
                "write"
              ],
              "default": "write"
            },
            "ttl_seconds": {
              "type": "integer",
              "minimum": 60,
              "maximum": 86400,
              "default": 3600
            }
          }
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Temporary credential and one-time secret"
    },
    "403": {
      "description": "Authority cannot be delegated"
    }
  }
}

Find and read files

SearchFilesSearch live names and bounded UTF-8 file text within one accessible drive
Code
func (c *Client) SearchFiles(ctx context.Context, drive, text string, limit int, cursor string) (SearchPage, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
drivestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
textstringLiteral search text, encoded as request data.
limitintBounded page size; endpoint-specific limits apply.
cursorstringOpaque cursor returned by this same operation and scope. Omit for the first page.

Returns

Code
(SearchPage, error)

Call example

Code
client.SearchFiles(ctx, drive, text, limit, cursor)
Input and result fields
SearchPage
{
  "type": "object",
  "required": [
    "results",
    "next_cursor"
  ],
  "properties": {
    "results": {
      "type": "array",
      "maxItems": 100,
      "items": {
        "$ref": "#/components/schemas/SearchHit"
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ]
    }
  }
}
HTTP requests

GET /drives/{drive}/search

All query words must match. Results use file-ID order and live pagination. Names update transactionally; content extraction is asynchronous and restricted to 256 KiB UTF-8 text without binary control characters. Current drive permissions and live ancestors are checked on every page. Old content is hidden immediately after a version change. Unsupported content remains searchable by name. No external model or service receives queries or content.

Request and response contract
{
  "id": "get-drives-drive-search",
  "path": "/drives/{drive}/search",
  "method": "GET",
  "summary": "Search live names and bounded UTF-8 file text within one accessible drive",
  "description": "All query words must match. Results use file-ID order and live pagination. Names update transactionally; content extraction is asynchronous and restricted to 256 KiB UTF-8 text without binary control characters. Current drive permissions and live ancestors are checked on every page. Old content is hidden immediately after a version change. Unsupported content remains searchable by name. No external model or service receives queries or content.",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "in": "path",
      "name": "drive",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "in": "query",
      "name": "q",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 1,
        "maxLength": 256
      },
      "description": "Query is limited to 256 UTF-8 bytes"
    },
    {
      "in": "query",
      "name": "limit",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 50
      }
    },
    {
      "in": "query",
      "name": "cursor",
      "schema": {
        "type": "string",
        "maxLength": 512
      },
      "description": "Continuation bound to this drive and query"
    }
  ],
  "responses": {
    "200": {
      "description": "Permission-filtered live results",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SearchPage"
          }
        }
      }
    },
    "400": {
      "description": "Invalid query or cursor"
    },
    "401": {
      "description": "Authentication required"
    },
    "403": {
      "description": "Credential scope denied"
    },
    "404": {
      "description": "Drive unavailable"
    },
    "500": {
      "description": "Search unavailable"
    }
  }
}
EntriesEntries.
Code
func (c *Client) Entries(ctx context.Context, drive string, parent *string) ([]Entry, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
drivestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
parent*stringParent folder identity, or the language’s absent value for the drive root.

Returns

Code
([]Entry, error)

Call example

Code
client.Entries(ctx, drive, parent)
Input and result fields
Entry
{
  "type": "object",
  "required": [
    "id",
    "drive_id",
    "name",
    "kind",
    "logical_size",
    "revision",
    "created_at",
    "modified_at",
    "deleted"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "parent_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "kind": {
      "enum": [
        "file",
        "folder"
      ]
    },
    "current_version_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "logical_size": {
      "type": "integer",
      "format": "int64"
    },
    "checksum_sha256": {
      "type": [
        "string",
        "null"
      ]
    },
    "revision": {
      "type": "integer",
      "format": "int64"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "modified_at": {
      "type": "string",
      "format": "date-time"
    },
    "deleted": {
      "type": "boolean"
    }
  }
}
HTTP requests

GET /drives/{drive}/entries

Request and response contract
{
  "id": "get-drives-drive-entries",
  "path": "/drives/{drive}/entries",
  "method": "GET",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "parent_id",
      "in": "query",
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "as_of",
      "in": "query",
      "description": "Committed drive sequence to resolve under current permissions; this read does not pin history",
      "schema": {
        "type": "integer",
        "format": "int64",
        "minimum": 0
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Directory entries"
    },
    "410": {
      "description": "history_expired — a visible historical file version required by this listing was reclaimed"
    }
  }
}
EntryEntry.
Code
func (c *Client) Entry(ctx context.Context, id string) (Entry, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
idstringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code
(Entry, error)

Call example

Code
client.Entry(ctx, id)
Input and result fields
Entry
{
  "type": "object",
  "required": [
    "id",
    "drive_id",
    "name",
    "kind",
    "logical_size",
    "revision",
    "created_at",
    "modified_at",
    "deleted"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "parent_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "kind": {
      "enum": [
        "file",
        "folder"
      ]
    },
    "current_version_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "logical_size": {
      "type": "integer",
      "format": "int64"
    },
    "checksum_sha256": {
      "type": [
        "string",
        "null"
      ]
    },
    "revision": {
      "type": "integer",
      "format": "int64"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "modified_at": {
      "type": "string",
      "format": "date-time"
    },
    "deleted": {
      "type": "boolean"
    }
  }
}
HTTP requests

GET /entries/{entry}

Request and response contract
{
  "id": "get-entries-entry",
  "path": "/entries/{entry}",
  "method": "GET",
  "security": [
    {
      "bearer": []
    }
  ],
  "responses": {
    "200": {
      "description": "Entry metadata"
    }
  }
}
CreateEntryCreate Entry.
Code
func (c *Client) CreateEntry(ctx context.Context, drive, name, kind string, parent *string) (Entry, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
drivestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
namestringName or label accepted by this operation; it must meet server constraints.
kindstringEntry kind: file or folder.
parent*stringParent folder identity, or the language’s absent value for the drive root.

Returns

Code
(Entry, error)

Call example

Code
client.CreateEntry(ctx, drive, name, kind, parent)
Input and result fields
Entry
{
  "type": "object",
  "required": [
    "id",
    "drive_id",
    "name",
    "kind",
    "logical_size",
    "revision",
    "created_at",
    "modified_at",
    "deleted"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "parent_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "kind": {
      "enum": [
        "file",
        "folder"
      ]
    },
    "current_version_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "logical_size": {
      "type": "integer",
      "format": "int64"
    },
    "checksum_sha256": {
      "type": [
        "string",
        "null"
      ]
    },
    "revision": {
      "type": "integer",
      "format": "int64"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "modified_at": {
      "type": "string",
      "format": "date-time"
    },
    "deleted": {
      "type": "boolean"
    }
  }
}
HTTP requests

POST /drives/{drive}/entries

Request and response contract
{
  "id": "post-drives-drive-entries",
  "path": "/drives/{drive}/entries",
  "method": "POST",
  "security": [
    {
      "bearer": []
    }
  ],
  "responses": {
    "201": {
      "description": "Entry created"
    },
    "409": {
      "description": "Name conflict"
    }
  }
}
RenameEntryRename Entry.
Code
func (c *Client) RenameEntry(ctx context.Context, id, name string, revision int64, parent *string, replace bool) (Entry, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
idstringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
namestringName or label accepted by this operation; it must meet server constraints.
revisionint64Reviewed entry or policy revision. Do not substitute a file version ID.
parent*stringParent folder identity, or the language’s absent value for the drive root.
replaceboolExplicit namespace replacement behavior for the reviewed rename/move operation.

Returns

Code
(Entry, error)

Call example

Code
client.RenameEntry(ctx, id, name, revision, parent, replace)
Input and result fields
Entry
{
  "type": "object",
  "required": [
    "id",
    "drive_id",
    "name",
    "kind",
    "logical_size",
    "revision",
    "created_at",
    "modified_at",
    "deleted"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "parent_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "kind": {
      "enum": [
        "file",
        "folder"
      ]
    },
    "current_version_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "logical_size": {
      "type": "integer",
      "format": "int64"
    },
    "checksum_sha256": {
      "type": [
        "string",
        "null"
      ]
    },
    "revision": {
      "type": "integer",
      "format": "int64"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "modified_at": {
      "type": "string",
      "format": "date-time"
    },
    "deleted": {
      "type": "boolean"
    }
  }
}
HTTP requests

PATCH /entries/{entry}

Request and response contract
{
  "id": "patch-entries-entry",
  "path": "/entries/{entry}",
  "method": "PATCH",
  "security": [
    {
      "bearer": []
    }
  ],
  "responses": {
    "200": {
      "description": "Renamed or moved"
    },
    "409": {
      "description": "Revision conflict"
    }
  }
}
DeleteEntryDelete Entry.
Code
func (c *Client) DeleteEntry(ctx context.Context, id string, revision int64) error

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
idstringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
revisionint64Reviewed entry or policy revision. Do not substitute a file version ID.

Returns

Code
error

Call example

Code
client.DeleteEntry(ctx, id, revision)
HTTP requests

DELETE /entries/{entry}

Request and response contract
{
  "id": "delete-entries-entry",
  "path": "/entries/{entry}",
  "method": "DELETE",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "expected_revision",
      "in": "query",
      "required": true,
      "schema": {
        "type": "integer"
      }
    }
  ],
  "responses": {
    "204": {
      "description": "Tombstoned"
    },
    "409": {
      "description": "Revision conflict"
    }
  }
}
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.

Code
func (c *Client) ReadRange(ctx context.Context, file string, offset, length int64) ([]byte, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
filestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
offsetint64Non-negative byte offset, not a character offset.
lengthint64Byte count or logical byte size; non-negative and bounded by the operation.

Returns

Code
([]byte, error)

Call example

Code
client.ReadRange(ctx, file, offset, length)
HTTP requests

GET /files/{file}/bytes

Stream current file bytes, optionally as one HTTP byte range

Request and response contract
{
  "id": "get-files-file-bytes",
  "path": "/files/{file}/bytes",
  "method": "GET",
  "summary": "Stream current file bytes, optionally as one HTTP byte range",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "file",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "Range",
      "in": "header",
      "schema": {
        "type": "string",
        "example": "bytes=0-1023"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Full content"
    },
    "206": {
      "description": "Exact requested range"
    },
    "416": {
      "description": "Unsatisfiable range"
    }
  }
}
BrowserDownloadIssue a file/version-scoped HttpOnly download cookie for the current session
Code
func (c *Client) BrowserDownload(ctx context.Context, file, version string) (BrowserDownloadGrant, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
filestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
versionstringSelected immutable version identity for this read, restore or sharing operation.

Returns

Code
(BrowserDownloadGrant, error)

Call example

Code
client.BrowserDownload(ctx, file, version)
Input and result fields
BrowserDownloadGrant
{
  "type": "object",
  "required": [
    "download_path",
    "expires_at"
  ],
  "additionalProperties": false,
  "properties": {
    "download_path": {
      "type": "string",
      "pattern": "^/v1/files/[0-9a-f-]{36}/versions/[0-9a-f-]{36}/browser-download$"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}
HTTP requests

POST /files/{file}/versions/{version}/browser-download

Issue a file/version-scoped HttpOnly download cookie for the current session

Request and response contract
{
  "id": "post-files-file-versions-version-browser-download",
  "path": "/files/{file}/versions/{version}/browser-download",
  "method": "POST",
  "summary": "Issue a file/version-scoped HttpOnly download cookie for the current session",
  "security": [
    {
      "bearer": []
    }
  ],
  "responses": {
    "200": {
      "description": "Native browser download path; 15-minute grant rechecks session and membership",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/BrowserDownloadGrant"
          }
        }
      }
    },
    "401": {
      "description": "Interactive session required"
    },
    "404": {
      "description": "Version inaccessible"
    }
  }
}

Write and update files

If you want to…Use
Replace a file's complete contentsWriteFile
Overwrite bytes at a known offsetWriteAt
Commit several offset edits togetherPatch
Add bytes and move the following contentInsert
Delete a range and close the gapRemove
Replace a section with content of another lengthSplice
Set a file's lengthTruncate
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.

Code
func (c *Client) WriteFile(ctx context.Context, file string, data []byte, ifVersion, key string) (MutationResult, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
filestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
data[]byteRaw byte input in the declared language type; binary identities must describe these exact bytes.
ifVersionstringFile version precondition. None/null/empty (according to language) means no committed version, not any version.
keystringStable operation identity for exact replay. Reuse only with the same payload and preconditions.

Returns

Code
(MutationResult, error)

Call example

Code
client.WriteFile(ctx, file, data, ifVersion, key)
Input and result fields
MutationResult
{
  "type": "object",
  "required": [
    "entry",
    "version"
  ],
  "properties": {
    "entry": {
      "$ref": "#/components/schemas/Entry"
    },
    "version": {
      "$ref": "#/components/schemas/Version"
    },
    "idempotent_replay": {
      "type": "boolean",
      "default": false
    }
  }
}
HTTP requests

PUT /files/{file}/content

Atomically replace a file through the canonical extent engine

Request and response contract
{
  "id": "put-files-file-content",
  "path": "/files/{file}/content",
  "method": "PUT",
  "summary": "Atomically replace a file through the canonical extent engine",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "file",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "If-Match",
      "in": "header",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Base version UUID or quoted `none`"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "schema": {
        "type": "string",
        "maxLength": 200
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ContentMutation"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "One committed immutable version",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MutationResult"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input or missing idempotency key",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "409": {
      "description": "Idempotency key belongs to another request",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "412": {
      "description": "version_precondition_failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "413": {
      "description": "mutation_too_large",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "428": {
      "description": "version_precondition_required",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    }
  }
}

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

Resolve a version to a legacy blob URL or chunk manifest

Request and response contract
{
  "id": "get-files-file-versions-version-content",
  "path": "/files/{file}/versions/{version}/content",
  "method": "GET",
  "summary": "Resolve a version to a legacy blob URL or chunk manifest",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "file",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "version",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Version content descriptor; chunked versions contain a manifest"
    }
  }
}
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.

Code
func (c *Client) WriteAt(ctx context.Context, file string, offset int64, data []byte, ifVersion, key string) (MutationResult, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
filestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
offsetint64Non-negative byte offset, not a character offset.
data[]byteRaw byte input in the declared language type; binary identities must describe these exact bytes.
ifVersionstringFile version precondition. None/null/empty (according to language) means no committed version, not any version.
keystringStable operation identity for exact replay. Reuse only with the same payload and preconditions.

Returns

Code
(MutationResult, error)

Call example

Code
client.WriteAt(ctx, file, offset, data, ifVersion, key)
Input and result fields
MutationResult
{
  "type": "object",
  "required": [
    "entry",
    "version"
  ],
  "properties": {
    "entry": {
      "$ref": "#/components/schemas/Entry"
    },
    "version": {
      "$ref": "#/components/schemas/Version"
    },
    "idempotent_replay": {
      "type": "boolean",
      "default": false
    }
  }
}
HTTP requests

POST /files/{file}/write-at

Overwrite bytes at a 64-bit logical offset without replacing unaffected content

Request and response contract
{
  "id": "post-files-file-write-at",
  "path": "/files/{file}/write-at",
  "method": "POST",
  "summary": "Overwrite bytes at a 64-bit logical offset without replacing unaffected content",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "file",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "If-Match",
      "in": "header",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/WriteAtMutation"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "One committed immutable version",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MutationResult"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input or missing idempotency key",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "409": {
      "description": "Idempotency key belongs to another request",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "412": {
      "description": "version_precondition_failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "413": {
      "description": "mutation_too_large",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "428": {
      "description": "version_precondition_required",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    }
  }
}
PatchCommit several offset edits together

Use this when one logical change touches several positions in a file. Supply offset/data pairs instead of making a separate call for each edit. The accepted patch is committed together as one version.

Code
func (c *Client) Patch(ctx context.Context, file string, changes []Patch, ifVersion, key string) (MutationResult, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
filestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
changes[]PatchOrdered collection of patch ranges or structured changes in the declared type.
ifVersionstringFile version precondition. None/null/empty (according to language) means no committed version, not any version.
keystringStable operation identity for exact replay. Reuse only with the same payload and preconditions.

Returns

Code
(MutationResult, error)

Call example

Code
client.Patch(ctx, file, changes, ifVersion, key)
Input and result fields
MutationResult
{
  "type": "object",
  "required": [
    "entry",
    "version"
  ],
  "properties": {
    "entry": {
      "$ref": "#/components/schemas/Entry"
    },
    "version": {
      "$ref": "#/components/schemas/Version"
    },
    "idempotent_replay": {
      "type": "boolean",
      "default": false
    }
  }
}
HTTP requests

POST /files/{file}/patch

Apply up to 10,000 non-overlapping overwrite edits as one version

Request and response contract
{
  "id": "post-files-file-patch",
  "path": "/files/{file}/patch",
  "method": "POST",
  "summary": "Apply up to 10,000 non-overlapping overwrite edits as one version",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "file",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "If-Match",
      "in": "header",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/PatchMutation"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "One committed immutable version",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MutationResult"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input or missing idempotency key",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "409": {
      "description": "Idempotency key belongs to another request",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "412": {
      "description": "version_precondition_failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "413": {
      "description": "mutation_too_large",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "428": {
      "description": "version_precondition_required",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    }
  }
}
InsertAdd bytes and move the following content

Use this when new content belongs between existing bytes. The supplied data is inserted at the offset and later content shifts to make room. Offsets are measured in bytes, including for UTF-8 text.

Code
func (c *Client) Insert(ctx context.Context, file string, offset int64, data []byte, ifVersion, key string) (MutationResult, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
filestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
offsetint64Non-negative byte offset, not a character offset.
data[]byteRaw byte input in the declared language type; binary identities must describe these exact bytes.
ifVersionstringFile version precondition. None/null/empty (according to language) means no committed version, not any version.
keystringStable operation identity for exact replay. Reuse only with the same payload and preconditions.

Returns

Code
(MutationResult, error)

Call example

Code
client.Insert(ctx, file, offset, data, ifVersion, key)
Input and result fields
MutationResult
{
  "type": "object",
  "required": [
    "entry",
    "version"
  ],
  "properties": {
    "entry": {
      "$ref": "#/components/schemas/Entry"
    },
    "version": {
      "$ref": "#/components/schemas/Version"
    },
    "idempotent_replay": {
      "type": "boolean",
      "default": false
    }
  }
}
HTTP requests

POST /files/{file}/insert

Insert bytes and shift the unchanged suffix through manifest path-copying

Request and response contract
{
  "id": "post-files-file-insert",
  "path": "/files/{file}/insert",
  "method": "POST",
  "summary": "Insert bytes and shift the unchanged suffix through manifest path-copying",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "file",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "If-Match",
      "in": "header",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/InsertMutation"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "One committed immutable version",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MutationResult"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input or missing idempotency key",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "409": {
      "description": "Idempotency key belongs to another request",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "412": {
      "description": "version_precondition_failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "413": {
      "description": "mutation_too_large",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "428": {
      "description": "version_precondition_required",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    }
  }
}
RemoveDelete a range and close the gap

Use this to remove a section while keeping the rest of the file. The length selects how many bytes to delete; following content shifts left. Read the reviewed version first when calculating offsets.

Code
func (c *Client) Remove(ctx context.Context, file string, offset, length int64, ifVersion, key string) (MutationResult, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
filestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
offsetint64Non-negative byte offset, not a character offset.
lengthint64Byte count or logical byte size; non-negative and bounded by the operation.
ifVersionstringFile version precondition. None/null/empty (according to language) means no committed version, not any version.
keystringStable operation identity for exact replay. Reuse only with the same payload and preconditions.

Returns

Code
(MutationResult, error)

Call example

Code
client.Remove(ctx, file, offset, length, ifVersion, key)
Input and result fields
MutationResult
{
  "type": "object",
  "required": [
    "entry",
    "version"
  ],
  "properties": {
    "entry": {
      "$ref": "#/components/schemas/Entry"
    },
    "version": {
      "$ref": "#/components/schemas/Version"
    },
    "idempotent_replay": {
      "type": "boolean",
      "default": false
    }
  }
}
HTTP requests

POST /files/{file}/remove

Remove a logical range and close the gap without copying the suffix

Request and response contract
{
  "id": "post-files-file-remove",
  "path": "/files/{file}/remove",
  "method": "POST",
  "summary": "Remove a logical range and close the gap without copying the suffix",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "file",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "If-Match",
      "in": "header",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/RemoveMutation"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "One committed immutable version",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MutationResult"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input or missing idempotency key",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "409": {
      "description": "Idempotency key belongs to another request",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "412": {
      "description": "version_precondition_failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "413": {
      "description": "mutation_too_large",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "428": {
      "description": "version_precondition_required",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    }
  }
}
SpliceReplace a section with content of another length

Use this when the replacement is shorter or longer than the original section. Supply the offset, deletion length and replacement bytes in one mutation. It avoids an intermediate state between a separate delete and insert.

Code
func (c *Client) Splice(ctx context.Context, file string, offset, length int64, data []byte, ifVersion, key string) (MutationResult, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
filestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
offsetint64Non-negative byte offset, not a character offset.
lengthint64Byte count or logical byte size; non-negative and bounded by the operation.
data[]byteRaw byte input in the declared language type; binary identities must describe these exact bytes.
ifVersionstringFile version precondition. None/null/empty (according to language) means no committed version, not any version.
keystringStable operation identity for exact replay. Reuse only with the same payload and preconditions.

Returns

Code
(MutationResult, error)

Call example

Code
client.Splice(ctx, file, offset, length, data, ifVersion, key)
Input and result fields
MutationResult
{
  "type": "object",
  "required": [
    "entry",
    "version"
  ],
  "properties": {
    "entry": {
      "$ref": "#/components/schemas/Entry"
    },
    "version": {
      "$ref": "#/components/schemas/Version"
    },
    "idempotent_replay": {
      "type": "boolean",
      "default": false
    }
  }
}
HTTP requests

POST /files/{file}/splice

Replace a logical range with different-length content atomically

Request and response contract
{
  "id": "post-files-file-splice",
  "path": "/files/{file}/splice",
  "method": "POST",
  "summary": "Replace a logical range with different-length content atomically",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "file",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "If-Match",
      "in": "header",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/SpliceMutation"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "One committed immutable version",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MutationResult"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input or missing idempotency key",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "409": {
      "description": "Idempotency key belongs to another request",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "412": {
      "description": "version_precondition_failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "413": {
      "description": "mutation_too_large",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "428": {
      "description": "version_precondition_required",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    }
  }
}
TruncateSet a file's length

Use this to drop a tail or extend the logical size. Shortening removes bytes beyond the new length; extension adds zero-filled space. Earlier retained versions still contain their original bytes.

Code
func (c *Client) Truncate(ctx context.Context, file string, size int64, ifVersion, key string) (MutationResult, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
filestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
sizeint64Byte count or logical byte size; non-negative and bounded by the operation.
ifVersionstringFile version precondition. None/null/empty (according to language) means no committed version, not any version.
keystringStable operation identity for exact replay. Reuse only with the same payload and preconditions.

Returns

Code
(MutationResult, error)

Call example

Code
client.Truncate(ctx, file, size, ifVersion, key)
Input and result fields
MutationResult
{
  "type": "object",
  "required": [
    "entry",
    "version"
  ],
  "properties": {
    "entry": {
      "$ref": "#/components/schemas/Entry"
    },
    "version": {
      "$ref": "#/components/schemas/Version"
    },
    "idempotent_replay": {
      "type": "boolean",
      "default": false
    }
  }
}
HTTP requests

POST /files/{file}/truncate

Truncate or sparse-extend a file atomically

Request and response contract
{
  "id": "post-files-file-truncate",
  "path": "/files/{file}/truncate",
  "method": "POST",
  "summary": "Truncate or sparse-extend a file atomically",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "file",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "If-Match",
      "in": "header",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/TruncateMutation"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "One committed immutable version",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MutationResult"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input or missing idempotency key",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "409": {
      "description": "Idempotency key belongs to another request",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "412": {
      "description": "version_precondition_failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "413": {
      "description": "mutation_too_large",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "428": {
      "description": "version_precondition_required",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    }
  }
}
UploadFileBytesAtomically replace file bytes with bounded binary ingestion
Code
func (c *Client) UploadFileBytes(ctx context.Context, file string, data []byte, expectedVersion, sha, idempotency string) (MutationResult, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
filestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
data[]byteRaw byte input in the declared language type; binary identities must describe these exact bytes.
expectedVersionstringFile version precondition. None/null/empty (according to language) means no committed version, not any version.
shastringLowercase hexadecimal SHA-256 of the exact content bytes.
idempotencystringStable operation identity for exact replay. Reuse only with the same payload and preconditions.

Returns

Code
(MutationResult, error)

Call example

Code
client.UploadFileBytes(ctx, file, data, expectedVersion, sha, idempotency)
Input and result fields
MutationResult
{
  "type": "object",
  "required": [
    "entry",
    "version"
  ],
  "properties": {
    "entry": {
      "$ref": "#/components/schemas/Entry"
    },
    "version": {
      "$ref": "#/components/schemas/Version"
    },
    "idempotent_replay": {
      "type": "boolean",
      "default": false
    }
  }
}
HTTP requests

PUT /files/{file}/bytes

Uploads up to 100 MiB in bounded server chunks. Retry the same body and identity after interruption. A new file entry may remain empty until content commits.

Request and response contract
{
  "id": "put-files-file-bytes",
  "path": "/files/{file}/bytes",
  "method": "PUT",
  "summary": "Atomically replace file bytes with bounded binary ingestion",
  "description": "Uploads up to 100 MiB in bounded server chunks. Retry the same body and identity after interruption. A new file entry may remain empty until content commits.",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "file",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "If-Match",
      "in": "header",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      }
    },
    {
      "name": "X-Content-SHA256",
      "in": "header",
      "required": true,
      "schema": {
        "type": "string",
        "pattern": "^[0-9a-f]{64}$"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/octet-stream": {
        "schema": {
          "type": "string",
          "format": "binary"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Exactly one committed version or its replay",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MutationResult"
          }
        }
      }
    },
    "400": {
      "description": "Invalid size or checksum or incomplete body"
    },
    "401": {
      "description": "Authentication required"
    },
    "403": {
      "description": "Credential scope or access denied"
    },
    "404": {
      "description": "File or write permission unavailable"
    },
    "409": {
      "description": "Idempotency identity conflict"
    },
    "412": {
      "description": "Base version changed"
    },
    "428": {
      "description": "Version precondition required"
    },
    "503": {
      "description": "Content storage unavailable"
    },
    "507": {
      "description": "Quota exhausted"
    }
  }
}

Read history and restore

File history is off by default. The drive owner can enable it for future edits, then clear earlier versions to free storage. These management calls require the owner’s session or an account-scoped admin key.

Code
policy, err := client.FileHistory(ctx, driveID)
if err != nil { return err }
_, err = client.SetFileHistory(ctx, driveID, true, policy.Revision)
if err != nil { return err }
// Future edits now retain earlier contents.
versions, err := client.Versions(ctx, fileID)
if err != nil { return err }
fmt.Println(versions)
// Permanently remove older versions; the current file stays unchanged.
result, err := client.ClearFileHistory(ctx, fileID)
if err != nil { return err }
fmt.Println(result.BytesFreed)
// client.ClearDriveHistory(ctx, driveID)
EntriesAtRead historical directory metadata at a committed sequence; current permissions and retention apply.
Code
func (c *Client) EntriesAt(ctx context.Context, drive string, sequence int64, parent *string) ([]Entry, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
drivestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
sequenceint64Committed drive sequence (non-negative int64). TypeScript uses bigint beyond safe integer precision.
parent*stringParent folder identity, or the language’s absent value for the drive root.

Returns

Code
([]Entry, error)

Call example

Code
client.EntriesAt(ctx, drive, sequence, parent)
Input and result fields
Entry
{
  "type": "object",
  "required": [
    "id",
    "drive_id",
    "name",
    "kind",
    "logical_size",
    "revision",
    "created_at",
    "modified_at",
    "deleted"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "parent_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "kind": {
      "enum": [
        "file",
        "folder"
      ]
    },
    "current_version_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "logical_size": {
      "type": "integer",
      "format": "int64"
    },
    "checksum_sha256": {
      "type": [
        "string",
        "null"
      ]
    },
    "revision": {
      "type": "integer",
      "format": "int64"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "modified_at": {
      "type": "string",
      "format": "date-time"
    },
    "deleted": {
      "type": "boolean"
    }
  }
}
HTTP requests

GET /drives/{drive}/entries

Request and response contract
{
  "id": "get-drives-drive-entries",
  "path": "/drives/{drive}/entries",
  "method": "GET",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "parent_id",
      "in": "query",
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "as_of",
      "in": "query",
      "description": "Committed drive sequence to resolve under current permissions; this read does not pin history",
      "schema": {
        "type": "integer",
        "format": "int64",
        "minimum": 0
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Directory entries"
    },
    "410": {
      "description": "history_expired — a visible historical file version required by this listing was reclaimed"
    }
  }
}
FileHistoryRead history settings and storage breakdown
Code
func (c *Client) FileHistory(ctx context.Context, drive string) (FileHistoryPolicy, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
drivestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code
(FileHistoryPolicy, error)

Call example

Code
client.FileHistory(ctx, drive)
Input and result fields
FileHistoryPolicy
{
  "type": "object",
  "description": "Drive-wide history is off by default. Used storage counts current and retained historical contents with content deduplication.",
  "required": [
    "drive_id",
    "enabled",
    "revision",
    "current_bytes",
    "history_bytes",
    "used_bytes",
    "historical_versions"
  ],
  "properties": {
    "drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "enabled": {
      "type": "boolean"
    },
    "revision": {
      "type": "string"
    },
    "current_bytes": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    },
    "history_bytes": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    },
    "used_bytes": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    },
    "historical_versions": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    }
  }
}
HTTP requests

GET /drives/{drive}/history

Read history settings and storage breakdown

Request and response contract
{
  "id": "get-drives-drive-history",
  "path": "/drives/{drive}/history",
  "method": "GET",
  "summary": "Read history settings and storage breakdown",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "drive",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/FileHistoryPolicy"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input"
    },
    "403": {
      "description": "Drive owner authority is required"
    },
    "404": {
      "description": "Drive or history not found"
    },
    "409": {
      "description": "Revision changed or selected content is protected"
    }
  }
}
SetFileHistoryEnable or disable history for future edits
Code
func (c *Client) SetFileHistory(ctx context.Context, drive string, enabled bool, revision string) (FileHistoryPolicy, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
drivestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
enabledboolCaller-supplied value of the declared type. See the linked operation or model for field constraints.
revisionstringReviewed entry or policy revision. Do not substitute a file version ID.

Returns

Code
(FileHistoryPolicy, error)

Call example

Code
client.SetFileHistory(ctx, drive, enabled, revision)
Input and result fields
FileHistoryPolicy
{
  "type": "object",
  "description": "Drive-wide history is off by default. Used storage counts current and retained historical contents with content deduplication.",
  "required": [
    "drive_id",
    "enabled",
    "revision",
    "current_bytes",
    "history_bytes",
    "used_bytes",
    "historical_versions"
  ],
  "properties": {
    "drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "enabled": {
      "type": "boolean"
    },
    "revision": {
      "type": "string"
    },
    "current_bytes": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    },
    "history_bytes": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    },
    "used_bytes": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    },
    "historical_versions": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    }
  }
}
HTTP requests

PUT /drives/{drive}/history

Enable or disable history for future edits

Request and response contract
{
  "id": "put-drives-drive-history",
  "path": "/drives/{drive}/history",
  "method": "PUT",
  "summary": "Enable or disable history for future edits",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "drive",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/FileHistoryPolicy"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input"
    },
    "403": {
      "description": "Drive owner authority is required"
    },
    "404": {
      "description": "Drive or history not found"
    },
    "409": {
      "description": "Revision changed or selected content is protected"
    }
  },
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/FileHistoryUpdate"
        }
      }
    }
  }
}
ClearDriveHistoryClear all earlier versions in this drive
Code
func (c *Client) ClearDriveHistory(ctx context.Context, drive string) (HistoryCleanupResult, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
drivestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code
(HistoryCleanupResult, error)

Call example

Code
client.ClearDriveHistory(ctx, drive)
Input and result fields
HistoryCleanupResult
{
  "type": "object",
  "description": "Clears earlier versions, keeps current files, and releases allowance immediately. Protected snapshots, forks and live links are skipped. Physical reclamation is asynchronous and preserves replay and active-save pins.",
  "required": [
    "versions_cleared",
    "versions_skipped",
    "bytes_freed",
    "used_bytes"
  ],
  "properties": {
    "versions_cleared": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    },
    "versions_skipped": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    },
    "bytes_freed": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    },
    "used_bytes": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    }
  }
}
HTTP requests

DELETE /drives/{drive}/history

Clear all earlier versions in this drive

Request and response contract
{
  "id": "delete-drives-drive-history",
  "path": "/drives/{drive}/history",
  "method": "DELETE",
  "summary": "Clear all earlier versions in this drive",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "drive",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HistoryCleanupResult"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input"
    },
    "403": {
      "description": "Drive owner authority is required"
    },
    "404": {
      "description": "Drive or history not found"
    },
    "409": {
      "description": "Revision changed or selected content is protected"
    }
  }
}
ClearFileHistoryClear earlier versions of one file
Code
func (c *Client) ClearFileHistory(ctx context.Context, file string) (HistoryCleanupResult, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
filestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code
(HistoryCleanupResult, error)

Call example

Code
client.ClearFileHistory(ctx, file)
Input and result fields
HistoryCleanupResult
{
  "type": "object",
  "description": "Clears earlier versions, keeps current files, and releases allowance immediately. Protected snapshots, forks and live links are skipped. Physical reclamation is asynchronous and preserves replay and active-save pins.",
  "required": [
    "versions_cleared",
    "versions_skipped",
    "bytes_freed",
    "used_bytes"
  ],
  "properties": {
    "versions_cleared": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    },
    "versions_skipped": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    },
    "bytes_freed": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    },
    "used_bytes": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    }
  }
}
HTTP requests

DELETE /files/{file}/versions

Clear earlier versions of one file

Request and response contract
{
  "id": "delete-files-file-versions",
  "path": "/files/{file}/versions",
  "method": "DELETE",
  "summary": "Clear earlier versions of one file",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "file",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HistoryCleanupResult"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input"
    },
    "403": {
      "description": "Drive owner authority is required"
    },
    "404": {
      "description": "Drive or history not found"
    },
    "409": {
      "description": "Revision changed or selected content is protected"
    }
  }
}
RecentVersionsRecent Versions.
Code
func (c *Client) RecentVersions(ctx context.Context, drive string, limit int) ([]VersionSummary, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
drivestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
limitintBounded page size; endpoint-specific limits apply.

Returns

Code
([]VersionSummary, error)

Call example

Code
client.RecentVersions(ctx, drive, limit)
Input and result fields
VersionSummary
{
  "type": "object",
  "description": "",
  "required": [
    "version_id",
    "file_id",
    "file_name",
    "logical_size",
    "checksum_sha256",
    "created_at",
    "current",
    "file_revision"
  ],
  "properties": {
    "version_id": {
      "type": "string",
      "format": "uuid"
    },
    "file_id": {
      "type": "string",
      "format": "uuid"
    },
    "file_name": {
      "type": "string"
    },
    "logical_size": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    },
    "checksum_sha256": {
      "type": "string"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "current": {
      "type": "boolean"
    },
    "file_revision": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    },
    "storage_format": {
      "type": "string"
    },
    "manifest_sha256": {
      "type": "string"
    },
    "operation": {
      "type": "string"
    },
    "drive_sequence": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    }
  }
}
HTTP requests

GET /drives/{drive}/versions

Request and response contract
{
  "id": "get-drives-drive-versions",
  "path": "/drives/{drive}/versions",
  "method": "GET",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "drive",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "limit",
      "in": "query",
      "schema": {
        "type": "integer",
        "maximum": 100
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Current and retained versions for drive history",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "versions"
            ],
            "properties": {
              "versions": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/VersionSummary"
                }
              }
            }
          }
        }
      }
    }
  }
}
VersionsInspect a file's saved history

List retained committed versions before choosing one to compare or restore. Keep the selected version ID, rather than assuming that the current file will still contain those bytes later.

Code
func (c *Client) Versions(ctx context.Context, file string) ([]Version, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
filestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code
([]Version, error)

Call example

Code
client.Versions(ctx, file)
Input and result fields
Version
{
  "type": "object",
  "required": [
    "id",
    "file_id",
    "logical_size",
    "checksum_sha256",
    "storage_format",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "file_id": {
      "type": "string",
      "format": "uuid"
    },
    "logical_size": {
      "type": "integer",
      "format": "int64"
    },
    "checksum_sha256": {
      "type": "string"
    },
    "manifest_sha256": {
      "type": "string"
    },
    "storage_format": {
      "enum": [
        "blob",
        "chunked_v1",
        "extent_v2"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "operation": {
      "enum": [
        "write",
        "write_at",
        "patch",
        "insert",
        "remove",
        "splice",
        "truncate",
        "restore",
        "conflict_preserved"
      ]
    },
    "drive_sequence": {
      "type": "integer",
      "format": "int64"
    }
  }
}
HTTP requests

GET /files/{file}/versions

Request and response contract
{
  "id": "get-files-file-versions",
  "path": "/files/{file}/versions",
  "method": "GET",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "file",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Immutable version history"
    }
  }
}
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.

Code
func (c *Client) RestoreVersion(ctx context.Context, file, version string, revision int64) (Entry, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
filestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
versionstringSelected immutable version identity for this read, restore or sharing operation.
revisionint64Reviewed entry or policy revision. Do not substitute a file version ID.

Returns

Code
(Entry, error)

Call example

Code
client.RestoreVersion(ctx, file, version, revision)
Input and result fields
Entry
{
  "type": "object",
  "required": [
    "id",
    "drive_id",
    "name",
    "kind",
    "logical_size",
    "revision",
    "created_at",
    "modified_at",
    "deleted"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "parent_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "kind": {
      "enum": [
        "file",
        "folder"
      ]
    },
    "current_version_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "logical_size": {
      "type": "integer",
      "format": "int64"
    },
    "checksum_sha256": {
      "type": [
        "string",
        "null"
      ]
    },
    "revision": {
      "type": "integer",
      "format": "int64"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "modified_at": {
      "type": "string",
      "format": "date-time"
    },
    "deleted": {
      "type": "boolean"
    }
  }
}
HTTP requests

POST /files/{file}/versions/{version}/restore

Request and response contract
{
  "id": "post-files-file-versions-version-restore",
  "path": "/files/{file}/versions/{version}/restore",
  "method": "POST",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "file",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "version",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "expected_revision"
          ],
          "properties": {
            "expected_revision": {
              "type": "integer",
              "format": "int64"
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "New immutable restore version committed, with updated entry and ETag",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MutationResult"
          }
        }
      }
    },
    "409": {
      "description": "Revision conflict"
    }
  }
}
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.

Code
func (c *Client) ReadVersionRange(ctx context.Context, file, version string, offset, length int64) ([]byte, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
filestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
versionstringSelected immutable version identity for this read, restore or sharing operation.
offsetint64Non-negative byte offset, not a character offset.
lengthint64Byte count or logical byte size; non-negative and bounded by the operation.

Returns

Code
([]byte, error)

Call example

Code
client.ReadVersionRange(ctx, file, version, offset, length)
HTTP requests

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

Stream bytes from one immutable historical version

Request and response contract
{
  "id": "get-files-file-versions-version-bytes",
  "path": "/files/{file}/versions/{version}/bytes",
  "method": "GET",
  "summary": "Stream bytes from one immutable historical version",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "file",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "version",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "Range",
      "in": "header",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Full historical content"
    },
    "206": {
      "description": "Historical range"
    },
    "404": {
      "description": "Version does not belong to file"
    }
  }
}

Manage your drive and plan

RequestOTPEmail a sign-in code
Code
func RequestOTP(ctx context.Context, endpoint, email string) (OTPChallenge, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
endpointstringAPI origin without /v1; HTTPS outside local development.
emailstringAccount or invitation email address.

Returns

Code
(OTPChallenge, error)

Call example

Code
nufs.RequestOTP(ctx, endpoint, email)
Input and result fields
OTPChallenge
{
  "type": "object",
  "required": [
    "challenge_id",
    "expires_at",
    "resend_after"
  ],
  "properties": {
    "challenge_id": {
      "type": "string",
      "format": "uuid"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    },
    "resend_after": {
      "type": "integer",
      "minimum": 0
    },
    "code": {
      "type": "string",
      "description": "Only exposed by explicitly configured local integration fixtures. Never returned in production."
    }
  }
}
HTTP requests

POST /auth/otp/request

Codes expire after 10 minutes, are single use, and allow five attempts. Resending invalidates the previous code. Requests have a 60-second cooldown and a per-email and per-IP rate limit. Storage is activated separately.

Request and response contract
{
  "id": "post-auth-otp-request",
  "path": "/auth/otp/request",
  "method": "POST",
  "summary": "Email a sign-in code",
  "description": "Codes expire after 10 minutes, are single use, and allow five attempts. Resending invalidates the previous code. Requests have a 60-second cooldown and a per-email and per-IP rate limit. Storage is activated separately.",
  "security": [],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "email"
          ],
          "properties": {
            "email": {
              "type": "string",
              "format": "email",
              "maxLength": 254
            }
          }
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Challenge accepted",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/OTPChallenge"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input"
    },
    "401": {
      "description": "Invalid, expired, consumed or exhausted code"
    },
    "429": {
      "description": "Rate limited; wait before trying again"
    },
    "503": {
      "description": "Email delivery unavailable"
    }
  }
}
VerifyOTPSign in with an email code; create an account if needed
Code
func VerifyOTP(ctx context.Context, endpoint, challengeID, code string) (*Client, AuthSession, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
endpointstringAPI origin without /v1; HTTPS outside local development.
challengeIDstringIdentity returned by requestOTP, bound to the email address and its expiry.
codestringSix-digit code from the sign-in email; keep leading zeroes and never log it.

Returns

Code
(*Client, AuthSession, error)

Call example

Code
nufs.VerifyOTP(ctx, endpoint, challengeID, code)
Input and result fields
AuthSession
{
  "type": "object",
  "required": [
    "user",
    "access_token",
    "access_expires_at",
    "refresh_token",
    "refresh_expires_at"
  ],
  "properties": {
    "user": {
      "$ref": "#/components/schemas/User"
    },
    "access_token": {
      "type": "string",
      "minLength": 1
    },
    "access_expires_at": {
      "type": "string",
      "format": "date-time"
    },
    "refresh_token": {
      "type": "string",
      "minLength": 1
    },
    "refresh_expires_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}
HTTP requests

POST /auth/otp/verify

Codes expire after 10 minutes, are single use, and allow five attempts. Resending invalidates the previous code. Requests have a 60-second cooldown and a per-email and per-IP rate limit. Storage is activated separately.

Request and response contract
{
  "id": "post-auth-otp-verify",
  "path": "/auth/otp/verify",
  "method": "POST",
  "summary": "Sign in with an email code; create an account if needed",
  "description": "Codes expire after 10 minutes, are single use, and allow five attempts. Resending invalidates the previous code. Requests have a 60-second cooldown and a per-email and per-IP rate limit. Storage is activated separately.",
  "security": [],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "challenge_id",
            "code"
          ],
          "properties": {
            "challenge_id": {
              "type": "string",
              "format": "uuid"
            },
            "code": {
              "type": "string",
              "pattern": "^[0-9]{6}$"
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Session created",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AuthSession"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input"
    },
    "401": {
      "description": "Invalid, expired, consumed or exhausted code"
    },
    "429": {
      "description": "Rate limited; wait before trying again"
    },
    "503": {
      "description": "Email delivery unavailable"
    }
  }
}
DrivesDrives.
Code
func (c *Client) Drives(ctx context.Context) ([]Drive, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.

Returns

Code
([]Drive, error)

Call example

Code
client.Drives(ctx)
Input and result fields
Drive
{
  "type": "object",
  "required": [
    "id",
    "name",
    "quota_bytes",
    "used_bytes",
    "state",
    "plan",
    "role",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "quota_bytes": {
      "type": "integer",
      "format": "int64"
    },
    "used_bytes": {
      "type": "integer",
      "format": "int64"
    },
    "state": {
      "enum": [
        "active",
        "deleting",
        "deleted"
      ]
    },
    "source_drive_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "source_sequence": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int64"
    },
    "plan": {
      "enum": [
        "individual",
        "team",
        "enterprise"
      ]
    },
    "role": {
      "enum": [
        "viewer",
        "editor",
        "admin",
        "owner"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}
HTTP requests

GET /drives

Request and response contract
{
  "id": "get-drives",
  "path": "/drives",
  "method": "GET",
  "security": [
    {
      "bearer": []
    }
  ],
  "responses": {
    "200": {
      "description": "Drives visible to the current identity, filtered by key scope"
    }
  }
}
DriveDrive.
Code
func (c *Client) Drive(ctx context.Context, id string) (Drive, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
idstringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code
(Drive, error)

Call example

Code
client.Drive(ctx, id)
Input and result fields
Drive
{
  "type": "object",
  "required": [
    "id",
    "name",
    "quota_bytes",
    "used_bytes",
    "state",
    "plan",
    "role",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "quota_bytes": {
      "type": "integer",
      "format": "int64"
    },
    "used_bytes": {
      "type": "integer",
      "format": "int64"
    },
    "state": {
      "enum": [
        "active",
        "deleting",
        "deleted"
      ]
    },
    "source_drive_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "source_sequence": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int64"
    },
    "plan": {
      "enum": [
        "individual",
        "team",
        "enterprise"
      ]
    },
    "role": {
      "enum": [
        "viewer",
        "editor",
        "admin",
        "owner"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}
HTTP requests

GET /drives/{drive}

Request and response contract
{
  "id": "get-drives-drive",
  "path": "/drives/{drive}",
  "method": "GET",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "drive",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Drive"
    },
    "404": {
      "description": "Not found or inaccessible"
    }
  }
}
SubscriptionOwner-only subscription and storage/seat usage
Code
func (c *Client) Subscription(ctx context.Context, drive string) (DriveSubscription, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
drivestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code
(DriveSubscription, error)

Call example

Code
client.Subscription(ctx, drive)
Input and result fields
DriveSubscription
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "drive_id",
    "billing_user_id",
    "status",
    "storage_bytes",
    "seats",
    "members",
    "reserved_invitations",
    "used_bytes",
    "currency",
    "monthly_total_minor",
    "revision",
    "current_period_end",
    "current_period_start",
    "billing_anchor",
    "cycle_number",
    "access_until",
    "pending_monthly_total_minor",
    "cancel_at_period_end",
    "pending_storage_bytes",
    "pending_seats"
  ],
  "properties": {
    "drive_id": {
      "type": "string"
    },
    "billing_user_id": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "currency": {
      "type": "string"
    },
    "revision": {
      "type": "string"
    },
    "current_period_start": {
      "type": "string",
      "format": "date-time",
      "description": "Start of the current monthly cycle in UTC."
    },
    "billing_anchor": {
      "type": "string",
      "format": "date-time",
      "description": "UTC day and time used to calculate calendar-month boundaries. Reset to the new date when an administrator adjusts validity."
    },
    "cycle_number": {
      "type": "integer",
      "minimum": 1
    },
    "access_until": {
      "type": "string",
      "format": "date-time",
      "description": "Authoritative validity date and next renewal boundary. Free subscriptions renew when automatic renewal is enabled."
    },
    "pending_monthly_total_minor": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0
    },
    "current_period_end": {
      "type": "string"
    },
    "storage_bytes": {
      "type": "integer",
      "minimum": 0
    },
    "seats": {
      "type": "integer",
      "minimum": 0
    },
    "members": {
      "type": "integer",
      "minimum": 0
    },
    "reserved_invitations": {
      "type": "integer",
      "minimum": 0
    },
    "used_bytes": {
      "type": "integer",
      "minimum": 0
    },
    "monthly_total_minor": {
      "type": "integer",
      "minimum": 0
    },
    "cancel_at_period_end": {
      "type": "boolean"
    },
    "pending_storage_bytes": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1
    },
    "pending_seats": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1
    },
    "plan_version_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "pending_plan_version_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    }
  }
}
HTTP requests

GET /drives/{drive}/subscription

Owner-only subscription and storage/seat usage

Request and response contract
{
  "id": "get-drives-drive-subscription",
  "path": "/drives/{drive}/subscription",
  "method": "GET",
  "summary": "Owner-only subscription and storage/seat usage",
  "security": [
    {
      "bearer": []
    }
  ],
  "responses": {
    "200": {
      "description": "Drive subscription",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/DriveSubscription"
          }
        }
      }
    }
  }
}
ChangeSubscriptionDevelopment checkout for subscription changes; production requires billing configuration
Code
func (c *Client) ChangeSubscription(ctx context.Context, drive string, input SubscriptionChange) (DriveSubscription, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
drivestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
inputSubscriptionChangeStructured input of the declared type; use the linked schema for required fields and constraints.

Returns

Code
(DriveSubscription, error)

Call example

Code
client.ChangeSubscription(ctx, drive, input)
Input and result fields
DriveSubscription
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "drive_id",
    "billing_user_id",
    "status",
    "storage_bytes",
    "seats",
    "members",
    "reserved_invitations",
    "used_bytes",
    "currency",
    "monthly_total_minor",
    "revision",
    "current_period_end",
    "current_period_start",
    "billing_anchor",
    "cycle_number",
    "access_until",
    "pending_monthly_total_minor",
    "cancel_at_period_end",
    "pending_storage_bytes",
    "pending_seats"
  ],
  "properties": {
    "drive_id": {
      "type": "string"
    },
    "billing_user_id": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "currency": {
      "type": "string"
    },
    "revision": {
      "type": "string"
    },
    "current_period_start": {
      "type": "string",
      "format": "date-time",
      "description": "Start of the current monthly cycle in UTC."
    },
    "billing_anchor": {
      "type": "string",
      "format": "date-time",
      "description": "UTC day and time used to calculate calendar-month boundaries. Reset to the new date when an administrator adjusts validity."
    },
    "cycle_number": {
      "type": "integer",
      "minimum": 1
    },
    "access_until": {
      "type": "string",
      "format": "date-time",
      "description": "Authoritative validity date and next renewal boundary. Free subscriptions renew when automatic renewal is enabled."
    },
    "pending_monthly_total_minor": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0
    },
    "current_period_end": {
      "type": "string"
    },
    "storage_bytes": {
      "type": "integer",
      "minimum": 0
    },
    "seats": {
      "type": "integer",
      "minimum": 0
    },
    "members": {
      "type": "integer",
      "minimum": 0
    },
    "reserved_invitations": {
      "type": "integer",
      "minimum": 0
    },
    "used_bytes": {
      "type": "integer",
      "minimum": 0
    },
    "monthly_total_minor": {
      "type": "integer",
      "minimum": 0
    },
    "cancel_at_period_end": {
      "type": "boolean"
    },
    "pending_storage_bytes": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1
    },
    "pending_seats": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1
    },
    "plan_version_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "pending_plan_version_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    }
  }
}
SubscriptionChange
{
  "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

Request and response contract
{
  "id": "put-drives-drive-subscription",
  "path": "/drives/{drive}/subscription",
  "method": "PUT",
  "summary": "Development checkout for subscription changes; production requires billing configuration",
  "security": [
    {
      "bearer": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/SubscriptionChange"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Updated subscription; decreases take effect at renewal",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/DriveSubscription"
          }
        }
      }
    },
    "503": {
      "description": "Real billing is not configured; no charge or entitlement change"
    }
  }
}
PlatformConfigurationPlatform administrator draft and published configuration
Code
func (c *Client) PlatformConfiguration(ctx context.Context) (map[string]any, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.

Returns

Code
(map[string]any, error)

Call example

Code
client.PlatformConfiguration(ctx)
HTTP requests

GET /platform/config

Platform administrator draft and published configuration

Request and response contract
{
  "id": "get-platform-config",
  "path": "/platform/config",
  "method": "GET",
  "summary": "Platform administrator draft and published configuration",
  "security": [
    {
      "bearer": []
    }
  ],
  "responses": {
    "200": {
      "description": "Platform administrator draft and published configuration",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PlatformConfiguration"
          }
        }
      }
    },
    "401": {
      "description": "Session required"
    },
    "403": {
      "description": "Platform administrator access required"
    },
    "503": {
      "description": "Configuration unavailable"
    }
  }
}
SavePlatformConfigurationSave a draft or publish product settings; platform administrator only
Code
func (c *Client) SavePlatformConfiguration(ctx context.Context, document map[string]any, expectedRevision string, publish bool) (map[string]any, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
documentmap[string]anyCaller-supplied value of the declared type. See the linked operation or model for field constraints.
expectedRevisionstringReviewed entry or policy revision. Do not substitute a file version ID.
publishboolCaller-supplied value of the declared type. See the linked operation or model for field constraints.

Returns

Code
(map[string]any, error)

Call example

Code
client.SavePlatformConfiguration(ctx, document, expectedRevision, publish)
HTTP requests

PUT /platform/config

Save a draft or publish product settings; platform administrator only

Request and response contract
{
  "id": "put-platform-config",
  "path": "/platform/config",
  "method": "PUT",
  "summary": "Save a draft or publish product settings; platform administrator only",
  "security": [
    {
      "bearer": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "expected_revision",
            "document",
            "publish"
          ],
          "properties": {
            "expected_revision": {
              "type": "string",
              "pattern": "^[1-9][0-9]*$"
            },
            "document": {
              "$ref": "#/components/schemas/PlatformDocument"
            },
            "publish": {
              "type": "boolean"
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Updated configuration",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PlatformConfiguration"
          }
        }
      }
    },
    "400": {
      "description": "Invalid settings"
    },
    "401": {
      "description": "Session required"
    },
    "403": {
      "description": "Platform administrator access required"
    },
    "409": {
      "description": "Revision changed; reload before editing"
    }
  }
}
PlansPublished monthly plans and add-on terms
Code
func (c *Client) Plans(ctx context.Context) (map[string]any, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.

Returns

Code
(map[string]any, error)

Call example

Code
client.Plans(ctx)
HTTP requests

GET /plans

Published monthly plans and add-on terms

Request and response contract
{
  "id": "get-plans",
  "path": "/plans",
  "method": "GET",
  "summary": "Published monthly plans and add-on terms",
  "security": [],
  "responses": {
    "200": {
      "description": "Checkout mode, USD monthly prices, included seats and per-tier addon rules",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PlanCatalog"
          }
        }
      }
    }
  }
}
LeaveDriveLeave a shared drive; the owner cannot leave
Code
func (c *Client) LeaveDrive(ctx context.Context, drive string) error

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
drivestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code
error

Call example

Code
client.LeaveDrive(ctx, drive)
HTTP requests

DELETE /drives/{drive}/membership

Leave a shared drive; the owner cannot leave

Request and response contract
{
  "id": "delete-drives-drive-membership",
  "path": "/drives/{drive}/membership",
  "method": "DELETE",
  "summary": "Leave a shared drive; the owner cannot leave",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "drive",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "204": {
      "description": "Access revoked; purchased seat quantity is unchanged"
    }
  }
}
CreateDriveActivate an owned drive from selected storage and seats
Code
func (c *Client) CreateDrive(ctx context.Context, input DrivePlanSelection) (Drive, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
inputDrivePlanSelectionStructured input of the declared type; use the linked schema for required fields and constraints.

Returns

Code
(Drive, error)

Call example

Code
client.CreateDrive(ctx, input)
Input and result fields
DrivePlanSelection
{
  "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."
}
Drive
{
  "type": "object",
  "required": [
    "id",
    "name",
    "quota_bytes",
    "used_bytes",
    "state",
    "plan",
    "role",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "quota_bytes": {
      "type": "integer",
      "format": "int64"
    },
    "used_bytes": {
      "type": "integer",
      "format": "int64"
    },
    "state": {
      "enum": [
        "active",
        "deleting",
        "deleted"
      ]
    },
    "source_drive_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "source_sequence": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int64"
    },
    "plan": {
      "enum": [
        "individual",
        "team",
        "enterprise"
      ]
    },
    "role": {
      "enum": [
        "viewer",
        "editor",
        "admin",
        "owner"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}
HTTP requests

POST /drives

Activate an owned drive from selected storage and seats

Request and response contract
{
  "id": "post-drives",
  "path": "/drives",
  "method": "POST",
  "summary": "Activate an owned drive from selected storage and seats",
  "security": [
    {
      "bearer": []
    }
  ],
  "responses": {
    "201": {
      "description": "Drive created"
    },
    "403": {
      "description": "Permission or entitlement limit"
    }
  },
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/DrivePlanSelection"
        }
      }
    }
  }
}
DeleteDriveDelete Drive.
Code
func (c *Client) DeleteDrive(ctx context.Context, id string) error

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
idstringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code
error

Call example

Code
client.DeleteDrive(ctx, id)
HTTP requests

DELETE /drives/{drive}

Request and response contract
{
  "id": "delete-drives-drive",
  "path": "/drives/{drive}",
  "method": "DELETE",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "drive",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "204": {
      "description": "Drive deleted"
    },
    "404": {
      "description": "Drive inaccessible"
    }
  }
}

Share files and accept uploads

PublicConfigurationPublished plans, installer links and product availability
Code
func (c *Client) PublicConfiguration(ctx context.Context) (map[string]any, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.

Returns

Code
(map[string]any, error)

Call example

Code
client.PublicConfiguration(ctx)
HTTP requests

GET /public/config

Published plans, installer links and product availability

Request and response contract
{
  "id": "get-public-config",
  "path": "/public/config",
  "method": "GET",
  "summary": "Published plans, installer links and product availability",
  "security": [],
  "responses": {
    "200": {
      "description": "Published plans, installer links and product availability",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PublicConfiguration"
          }
        }
      }
    },
    "503": {
      "description": "Configuration unavailable"
    }
  }
}
ReadPublicFileRangeRead Public File Range.
Code
func (c *Client) ReadPublicFileRange(ctx context.Context, offset, length int64) ([]byte, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
offsetint64Non-negative byte offset, not a character offset.
lengthint64Byte count or logical byte size; non-negative and bounded by the operation.

Returns

Code
([]byte, error)

Call example

Code
client.ReadPublicFileRange(ctx, offset, length)
HTTP requests

GET /public/file-link/bytes

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

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

HEAD /public/file-link/bytes

Request and response contract
{
  "id": "head-public-file-link-bytes",
  "path": "/public/file-link/bytes",
  "method": "HEAD",
  "security": [
    {
      "publicFileLink": []
    }
  ],
  "responses": {
    "200": {
      "description": "Immutable byte headers without body"
    },
    "206": {
      "description": "Range headers without body"
    },
    "404": {
      "description": "Link unavailable"
    },
    "416": {
      "description": "Unsatisfiable range"
    }
  }
}
CreateUploadRequestCreate Upload Request.
Code
func (c *Client) CreateUploadRequest(ctx context.Context, drive string, policy UploadRequestInput) (UploadRequestResult, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
drivestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
policyUploadRequestInputStructured input of the declared type; use the linked schema for required fields and constraints.

Returns

Code
(UploadRequestResult, error)

Call example

Code
client.CreateUploadRequest(ctx, drive, policy)
Input and result fields
UploadRequestInput
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "title",
    "max_files",
    "max_file_bytes",
    "max_total_bytes",
    "expires_at"
  ],
  "properties": {
    "parent_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "max_files": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "max_file_bytes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 104857600
    },
    "max_total_bytes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1073741824
    },
    "allowed_extensions": {
      "type": "array",
      "maxItems": 20,
      "items": {
        "type": "string",
        "pattern": "^\\.[a-z0-9]{1,15}$"
      }
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}
UploadRequestResult
{
  "type": "object",
  "required": [
    "upload_request",
    "secret"
  ],
  "properties": {
    "upload_request": {
      "$ref": "#/components/schemas/UploadRequest"
    },
    "secret": {
      "type": "string"
    }
  }
}
HTTP requests

POST /drives/{drive}/upload-requests

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

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

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
drivestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
after*stringOpaque cursor returned by this same operation and scope. Omit for the first page.

Returns

Code
(UploadRequestPage, error)

Call example

Code
client.UploadRequests(ctx, drive, after)
HTTP requests

GET /drives/{drive}/upload-requests

Request and response contract
{
  "id": "get-drives-drive-upload-requests",
  "path": "/drives/{drive}/upload-requests",
  "method": "GET",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "after",
      "in": "query",
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Secret-free metadata page",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "upload_requests",
              "next_cursor"
            ],
            "properties": {
              "upload_requests": {
                "type": "array",
                "maxItems": 100,
                "items": {
                  "$ref": "#/components/schemas/UploadRequest"
                }
              },
              "next_cursor": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uuid"
              }
            }
          }
        }
      }
    },
    "404": {
      "description": "Destination unavailable to administrator"
    }
  }
}
RevokeUploadRequestRevoke Upload Request.
Code
func (c *Client) RevokeUploadRequest(ctx context.Context, drive, request string) error

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
drivestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
requeststringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code
error

Call example

Code
client.RevokeUploadRequest(ctx, drive, request)
HTTP requests

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

Request and response contract
{
  "id": "delete-drives-drive-upload-requests-request",
  "path": "/drives/{drive}/upload-requests/{request}",
  "method": "DELETE",
  "security": [
    {
      "bearer": []
    }
  ],
  "responses": {
    "204": {
      "description": "Request revoked; pending publication also denied"
    },
    "404": {
      "description": "Request unavailable to administrator"
    }
  }
}
PublicUploadRequestPublic Upload Request.
Code
func (c *Client) PublicUploadRequest(ctx context.Context) (PublicUploadRequest, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.

Returns

Code
(PublicUploadRequest, error)

Call example

Code
client.PublicUploadRequest(ctx)
Input and result fields
PublicUploadRequest
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "title",
    "max_files",
    "max_file_bytes",
    "max_total_bytes",
    "allowed_extensions",
    "expires_at"
  ],
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "max_files": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "max_file_bytes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 104857600
    },
    "max_total_bytes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1073741824
    },
    "allowed_extensions": {
      "type": "array",
      "maxItems": 20,
      "items": {
        "type": "string",
        "pattern": "^\\.[a-z0-9]{1,15}$"
      }
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}
HTTP requests

GET /public/upload-request

Request and response contract
{
  "id": "get-public-upload-request",
  "path": "/public/upload-request",
  "method": "GET",
  "security": [
    {
      "uploadRequest": []
    }
  ],
  "responses": {
    "200": {
      "description": "Public limits without private destination identifiers",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PublicUploadRequest"
          }
        }
      }
    },
    "404": {
      "description": "Request unavailable"
    }
  }
}
UploadRequestedFileUpload Requested File.
Code
func (c *Client) UploadRequestedFile(ctx context.Context, name string, data []byte, sha, idempotency string) (UploadReceipt, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
namestringName or label accepted by this operation; it must meet server constraints.
data[]byteRaw byte input in the declared language type; binary identities must describe these exact bytes.
shastringLowercase hexadecimal SHA-256 of the exact content bytes.
idempotencystringStable operation identity for exact replay. Reuse only with the same payload and preconditions.

Returns

Code
(UploadReceipt, error)

Call example

Code
client.UploadRequestedFile(ctx, name, data, sha, idempotency)
Input and result fields
UploadReceipt
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "receipt_id",
    "file_name",
    "size_bytes",
    "sha256",
    "idempotent_replay"
  ],
  "properties": {
    "receipt_id": {
      "type": "string",
      "format": "uuid"
    },
    "file_name": {
      "type": "string"
    },
    "size_bytes": {
      "type": "integer",
      "minimum": 0,
      "maximum": 104857600
    },
    "sha256": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$"
    },
    "idempotent_replay": {
      "type": "boolean"
    }
  }
}
HTTP requests

POST /public/upload-request/files

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

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

Manage members and audit activity

MemberPolicyRead explicit drive member limit and occupied seats
Code
func (c *Client) MemberPolicy(ctx context.Context, drive string) (DriveMemberPolicy, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
drivestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code
(DriveMemberPolicy, error)

Call example

Code
client.MemberPolicy(ctx, drive)
Input and result fields
DriveMemberPolicy
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "drive_id",
    "max_members",
    "members",
    "reserved_invitations",
    "revision"
  ],
  "properties": {
    "drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "max_members": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1,
      "maximum": 100000
    },
    "members": {
      "type": "integer",
      "minimum": 1
    },
    "reserved_invitations": {
      "type": "integer",
      "minimum": 0
    },
    "revision": {
      "type": "string",
      "pattern": "^[1-9][0-9]*$"
    }
  }
}
HTTP requests

GET /drives/{drive}/members/policy

Interactive owner or admin only. Null means no configured cap. The owner counts as a member. Distinct active invitation emails reserve seats until accepted or unusable.

Request and response contract
{
  "id": "get-drives-drive-members-policy",
  "path": "/drives/{drive}/members/policy",
  "method": "GET",
  "summary": "Read explicit drive member limit and occupied seats",
  "description": "Interactive owner or admin only. Null means no configured cap. The owner counts as a member. Distinct active invitation emails reserve seats until accepted or unusable.",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "drive",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Member policy",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/DriveMemberPolicy"
          }
        }
      }
    },
    "400": {
      "description": "Invalid drive ID"
    },
    "401": {
      "description": "Interactive session required"
    },
    "404": {
      "description": "Administration unavailable"
    },
    "500": {
      "description": "Policy read failed"
    }
  }
}
AccountAuditRetentionPolicyRead account audit retention policy
Code
func (c *Client) AccountAuditRetentionPolicy(ctx context.Context) (AccountAuditRetentionPolicy, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.

Returns

Code
(AccountAuditRetentionPolicy, error)

Call example

Code
client.AccountAuditRetentionPolicy(ctx)
Input and result fields
AccountAuditRetentionPolicy
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "user_id",
    "keep_days",
    "legal_hold",
    "revision"
  ],
  "properties": {
    "user_id": {
      "type": "string",
      "format": "uuid"
    },
    "keep_days": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 7,
      "maximum": 36500,
      "description": "Null retains account audit history indefinitely"
    },
    "legal_hold": {
      "type": "boolean",
      "description": "Account legal hold blocks cleanup and cannot be changed by this endpoint"
    },
    "revision": {
      "type": "string",
      "pattern": "^[1-9][0-9]*$"
    }
  }
}
HTTP requests

GET /account/audit/retention

Requires an interactive account owner session. Null keep_days means indefinite retention. Account legal hold blocks cleanup.

Request and response contract
{
  "id": "get-account-audit-retention",
  "path": "/account/audit/retention",
  "method": "GET",
  "summary": "Read account audit retention policy",
  "description": "Requires an interactive account owner session. Null keep_days means indefinite retention. Account legal hold blocks cleanup.",
  "security": [
    {
      "bearer": []
    }
  ],
  "responses": {
    "200": {
      "description": "Audit retention policy",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AccountAuditRetentionPolicy"
          }
        }
      }
    },
    "400": {
      "description": "Invalid account ID"
    },
    "401": {
      "description": "Interactive session required"
    },
    "404": {
      "description": "Account administration unavailable"
    }
  }
}
UpdateAccountAuditRetentionPolicyConfigure account audit retention with a displayed revision guard
Code
func (c *Client) UpdateAccountAuditRetentionPolicy(ctx context.Context, keepDays *int64, expectedRevision string) (AccountAuditRetentionPolicy, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
keepDays*int64Retention interval in days; absent/null retains indefinitely where the policy permits it.
expectedRevisionstringReviewed entry or policy revision. Do not substitute a file version ID.

Returns

Code
(AccountAuditRetentionPolicy, error)

Call example

Code
client.UpdateAccountAuditRetentionPolicy(ctx, keepDays, expectedRevision)
Input and result fields
AccountAuditRetentionPolicy
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "user_id",
    "keep_days",
    "legal_hold",
    "revision"
  ],
  "properties": {
    "user_id": {
      "type": "string",
      "format": "uuid"
    },
    "keep_days": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 7,
      "maximum": 36500,
      "description": "Null retains account audit history indefinitely"
    },
    "legal_hold": {
      "type": "boolean",
      "description": "Account legal hold blocks cleanup and cannot be changed by this endpoint"
    },
    "revision": {
      "type": "string",
      "pattern": "^[1-9][0-9]*$"
    }
  }
}
HTTP requests

PUT /account/audit/retention

Requires an interactive account owner session. Setting 7–36500 days enables bounded background retirement; null disables retirement. Existing legal hold remains unchanged. Cleanup already committed cannot be undone by a later hold or policy extension.

Request and response contract
{
  "id": "put-account-audit-retention",
  "path": "/account/audit/retention",
  "method": "PUT",
  "summary": "Configure account audit retention with a displayed revision guard",
  "description": "Requires an interactive account owner session. Setting 7–36500 days enables bounded background retirement; null disables retirement. Existing legal hold remains unchanged. Cleanup already committed cannot be undone by a later hold or policy extension.",
  "security": [
    {
      "bearer": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AuditRetentionUpdate"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Updated audit retention policy",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AccountAuditRetentionPolicy"
          }
        }
      }
    },
    "400": {
      "description": "Invalid retention days or displayed revision"
    },
    "401": {
      "description": "Interactive session required"
    },
    "404": {
      "description": "Account administration unavailable"
    },
    "409": {
      "description": "Displayed policy revision is stale"
    }
  }
}
AuditRetentionPolicyRead drive audit retention policy
Code
func (c *Client) AuditRetentionPolicy(ctx context.Context, drive string) (AuditRetentionPolicy, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
drivestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code
(AuditRetentionPolicy, error)

Call example

Code
client.AuditRetentionPolicy(ctx, drive)
Input and result fields
AuditRetentionPolicy
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "drive_id",
    "keep_days",
    "legal_hold",
    "revision"
  ],
  "properties": {
    "drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "keep_days": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 7,
      "maximum": 36500,
      "description": "Null retains audit history indefinitely"
    },
    "legal_hold": {
      "type": "boolean",
      "description": "Shared drive legal hold blocks audit cleanup"
    },
    "revision": {
      "type": "string",
      "pattern": "^[1-9][0-9]*$"
    }
  }
}
HTTP requests

GET /drives/{drive}/audit/retention

Requires an interactive owner or admin session. Null keep_days means indefinite retention. Shared drive legal hold blocks cleanup.

Request and response contract
{
  "id": "get-drives-drive-audit-retention",
  "path": "/drives/{drive}/audit/retention",
  "method": "GET",
  "summary": "Read drive audit retention policy",
  "description": "Requires an interactive owner or admin session. Null keep_days means indefinite retention. Shared drive legal hold blocks cleanup.",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "drive",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Audit retention policy",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AuditRetentionPolicy"
          }
        }
      }
    },
    "400": {
      "description": "Invalid drive ID"
    },
    "401": {
      "description": "Interactive session required"
    },
    "404": {
      "description": "Drive administration unavailable"
    }
  }
}
UpdateAuditRetentionPolicyConfigure drive audit retention with a displayed revision guard
Code
func (c *Client) UpdateAuditRetentionPolicy(ctx context.Context, drive string, keepDays *int64, expectedRevision string) (AuditRetentionPolicy, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
drivestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
keepDays*int64Retention interval in days; absent/null retains indefinitely where the policy permits it.
expectedRevisionstringReviewed entry or policy revision. Do not substitute a file version ID.

Returns

Code
(AuditRetentionPolicy, error)

Call example

Code
client.UpdateAuditRetentionPolicy(ctx, drive, keepDays, expectedRevision)
Input and result fields
AuditRetentionPolicy
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "drive_id",
    "keep_days",
    "legal_hold",
    "revision"
  ],
  "properties": {
    "drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "keep_days": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 7,
      "maximum": 36500,
      "description": "Null retains audit history indefinitely"
    },
    "legal_hold": {
      "type": "boolean",
      "description": "Shared drive legal hold blocks audit cleanup"
    },
    "revision": {
      "type": "string",
      "pattern": "^[1-9][0-9]*$"
    }
  }
}
HTTP requests

PUT /drives/{drive}/audit/retention

Requires an interactive owner or admin session. Setting 7–36500 days enables bounded background retirement; null disables retirement. Existing legal hold remains unchanged. Cleanup already committed cannot be undone by a later hold or policy extension.

Request and response contract
{
  "id": "put-drives-drive-audit-retention",
  "path": "/drives/{drive}/audit/retention",
  "method": "PUT",
  "summary": "Configure drive audit retention with a displayed revision guard",
  "description": "Requires an interactive owner or admin session. Setting 7–36500 days enables bounded background retirement; null disables retirement. Existing legal hold remains unchanged. Cleanup already committed cannot be undone by a later hold or policy extension.",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "drive",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AuditRetentionUpdate"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Updated audit retention policy",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AuditRetentionPolicy"
          }
        }
      }
    },
    "400": {
      "description": "Invalid retention days or displayed revision"
    },
    "401": {
      "description": "Interactive session required"
    },
    "404": {
      "description": "Drive administration unavailable"
    },
    "409": {
      "description": "Displayed policy revision is stale"
    }
  }
}
ExportDriveAuditWrite ordered audit records to a sink and emit a completion record only after successful output.
Code
func (c *Client) ExportDriveAudit(ctx context.Context, drive string, output io.Writer, pageLimit int) (int64, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
drivestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
outputio.WriterCaller-owned output destination. Output failures prevent successful completion.
pageLimitintBounded page size; endpoint-specific limits apply.

Returns

Code
(int64, error)

Call example

Code
client.ExportDriveAudit(ctx, drive, output, pageLimit)
DriveAuditRead a bounded page of drive audit history
Code
func (c *Client) DriveAudit(ctx context.Context, drive string, limit int, cursor string) (AuditPage, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
drivestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
limitintBounded page size; endpoint-specific limits apply.
cursorstringOpaque cursor returned by this same operation and scope. Omit for the first page.

Returns

Code
(AuditPage, error)

Call example

Code
client.DriveAudit(ctx, drive, limit, cursor)
Input and result fields
AuditPage
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "events",
    "next_cursor"
  ],
  "properties": {
    "events": {
      "type": "array",
      "maxItems": 200,
      "items": {
        "$ref": "#/components/schemas/AuditEvent"
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 256
    }
  }
}
HTTP requests

GET /drives/{drive}/audit

Interactive owner or admin session required on every page. Events descend by identity rather than timestamp. Continue with next_cursor until null; refresh without a cursor for new events. This live traversal is not a database snapshot and late commits may require a refresh. Raw metadata and credential material are omitted.

Request and response contract
{
  "id": "get-drives-drive-audit",
  "path": "/drives/{drive}/audit",
  "method": "GET",
  "summary": "Read a bounded page of drive audit history",
  "description": "Interactive owner or admin session required on every page. Events descend by identity rather than timestamp. Continue with next_cursor until null; refresh without a cursor for new events. This live traversal is not a database snapshot and late commits may require a refresh. Raw metadata and credential material are omitted.",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "drive",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "limit",
      "in": "query",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 200,
        "default": 50
      }
    },
    {
      "name": "cursor",
      "in": "query",
      "schema": {
        "type": "string",
        "maxLength": 256
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Audit page",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AuditPage"
          }
        }
      }
    },
    "400": {
      "description": "Invalid page limit or drive cursor"
    },
    "401": {
      "description": "Interactive session required"
    },
    "404": {
      "description": "Drive administration unavailable"
    },
    "500": {
      "description": "Audit history could not be read"
    }
  }
}
AccountAuditRead a bounded page of account audit history
Code
func (c *Client) AccountAudit(ctx context.Context, limit int, cursor string) (AuditPage, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
limitintBounded page size; endpoint-specific limits apply.
cursorstringOpaque cursor returned by this same operation and scope. Omit for the first page.

Returns

Code
(AuditPage, error)

Call example

Code
client.AccountAudit(ctx, limit, cursor)
Input and result fields
AuditPage
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "events",
    "next_cursor"
  ],
  "properties": {
    "events": {
      "type": "array",
      "maxItems": 200,
      "items": {
        "$ref": "#/components/schemas/AuditEvent"
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 256
    }
  }
}
HTTP requests

GET /account/audit

Interactive account session required on every page. The authenticated user is the account subject; no supplied account ID is accepted. Drive events and unattributed unknown login attempts are excluded. Anonymous recovery and reuse events retain null actors. Events descend by identity rather than timestamp. Continue with next_cursor until null; refresh without a cursor for new events. This live traversal is not a database snapshot and late commits may require a refresh. Raw metadata and credential material are omitted.

Request and response contract
{
  "id": "get-account-audit",
  "path": "/account/audit",
  "method": "GET",
  "summary": "Read a bounded page of account audit history",
  "description": "Interactive account session required on every page. The authenticated user is the account subject; no supplied account ID is accepted. Drive events and unattributed unknown login attempts are excluded. Anonymous recovery and reuse events retain null actors. Events descend by identity rather than timestamp. Continue with next_cursor until null; refresh without a cursor for new events. This live traversal is not a database snapshot and late commits may require a refresh. Raw metadata and credential material are omitted.",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "limit",
      "in": "query",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 200,
        "default": 50
      }
    },
    {
      "name": "cursor",
      "in": "query",
      "schema": {
        "type": "string",
        "maxLength": 256
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Audit page",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AuditPage"
          }
        }
      }
    },
    "400": {
      "description": "Invalid page limit or account cursor"
    },
    "401": {
      "description": "Interactive session required"
    },
    "404": {
      "description": "Account administration unavailable"
    },
    "500": {
      "description": "Audit history could not be read"
    }
  }
}
DriveMembersDrive Members.
Code
func (c *Client) DriveMembers(ctx context.Context, drive string) ([]DriveMember, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
drivestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.

Returns

Code
([]DriveMember, error)

Call example

Code
client.DriveMembers(ctx, drive)
Input and result fields
DriveMember
{
  "type": "object",
  "required": [
    "user_id",
    "email",
    "role",
    "created_at"
  ],
  "additionalProperties": false,
  "properties": {
    "user_id": {
      "type": "string",
      "format": "uuid"
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "role": {
      "type": "string",
      "enum": [
        "owner",
        "admin",
        "editor",
        "viewer"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}
HTTP requests

GET /drives/{drive}/members

Request and response contract
{
  "id": "get-drives-drive-members",
  "path": "/drives/{drive}/members",
  "method": "GET",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "drive",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Drive members",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "members"
            ],
            "properties": {
              "members": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/DriveMember"
                }
              }
            }
          }
        }
      }
    }
  }
}
InviteDriveMemberInvite Drive Member.
Code
func (c *Client) InviteDriveMember(ctx context.Context, drive, email, role string) (InvitationResult, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
drivestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
emailstringAccount or invitation email address.
rolestringRequested member role. The drive owner cannot be changed.

Returns

Code
(InvitationResult, error)

Call example

Code
client.InviteDriveMember(ctx, drive, email, role)
Input and result fields
InvitationResult
{
  "type": "object",
  "required": [
    "invitation"
  ],
  "additionalProperties": false,
  "properties": {
    "invitation": {
      "$ref": "#/components/schemas/DriveInvitation"
    },
    "token": {
      "type": "string",
      "minLength": 1,
      "description": "One-time token exposed only by configured local development delivery"
    }
  }
}
HTTP requests

POST /drives/{drive}/invitations

Request and response contract
{
  "id": "post-drives-drive-invitations",
  "path": "/drives/{drive}/invitations",
  "method": "POST",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "drive",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "201": {
      "description": "Invitation created",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/InvitationResult"
          }
        }
      }
    },
    "409": {
      "description": "Configured member limit reached"
    },
    "500": {
      "description": "Invitation and audit could not be committed"
    }
  }
}
AcceptDriveInvitationAccept Drive Invitation.
Code
func (c *Client) AcceptDriveInvitation(ctx context.Context, token string) (Drive, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
tokenstringCredential for this operation. Use interactive, machine or recipient authority as applicable; keep it private.

Returns

Code
(Drive, error)

Call example

Code
client.AcceptDriveInvitation(ctx, token)
Input and result fields
Drive
{
  "type": "object",
  "required": [
    "id",
    "name",
    "quota_bytes",
    "used_bytes",
    "state",
    "plan",
    "role",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "quota_bytes": {
      "type": "integer",
      "format": "int64"
    },
    "used_bytes": {
      "type": "integer",
      "format": "int64"
    },
    "state": {
      "enum": [
        "active",
        "deleting",
        "deleted"
      ]
    },
    "source_drive_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "source_sequence": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int64"
    },
    "plan": {
      "enum": [
        "individual",
        "team",
        "enterprise"
      ]
    },
    "role": {
      "enum": [
        "viewer",
        "editor",
        "admin",
        "owner"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}
HTTP requests

POST /invitations/accept

Request and response contract
{
  "id": "post-invitations-accept",
  "path": "/invitations/accept",
  "method": "POST",
  "security": [
    {
      "bearer": []
    }
  ],
  "responses": {
    "200": {
      "description": "Membership added or existing role preserved",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Drive"
          }
        }
      }
    },
    "404": {
      "description": "Invitation expired or revoked or issuer no longer has admin authority"
    },
    "409": {
      "description": "Configured member limit reached"
    },
    "500": {
      "description": "Membership and audit could not be committed"
    }
  }
}
UpdateDriveMemberChange a non-owner member role using interactive admin authority
Code
func (c *Client) UpdateDriveMember(ctx context.Context, drive, member, role, expectedRole string) (DriveMember, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
drivestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
memberstringTarget member identity; owner changes use the dedicated ownership operation.
rolestringRequested member role. The drive owner cannot be changed.
expectedRolestringMember role you reviewed; rejects a stale administrative change.

Returns

Code
(DriveMember, error)

Call example

Code
client.UpdateDriveMember(ctx, drive, member, role, expectedRole)
Input and result fields
DriveMember
{
  "type": "object",
  "required": [
    "user_id",
    "email",
    "role",
    "created_at"
  ],
  "additionalProperties": false,
  "properties": {
    "user_id": {
      "type": "string",
      "format": "uuid"
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "role": {
      "type": "string",
      "enum": [
        "owner",
        "admin",
        "editor",
        "viewer"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}
HTTP requests

PATCH /drives/{drive}/members/{member}

Change a non-owner member role using interactive admin authority

Request and response contract
{
  "id": "patch-drives-drive-members-member",
  "path": "/drives/{drive}/members/{member}",
  "method": "PATCH",
  "summary": "Change a non-owner member role using interactive admin authority",
  "security": [
    {
      "bearer": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/DriveMemberChange"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Updated member",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/DriveMember"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input"
    },
    "401": {
      "description": "Interactive session required"
    },
    "403": {
      "description": "Owner is protected"
    },
    "404": {
      "description": "Drive or member inaccessible"
    },
    "409": {
      "description": "Displayed role no longer matches"
    }
  }
}
RemoveDriveMemberRemove non-owner access and invalidate outstanding invitations
Code
func (c *Client) RemoveDriveMember(ctx context.Context, drive, member, expectedRole string) error

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.
drivestringTarget identity or structured input of the declared type. Current authority and endpoint constraints apply.
memberstringTarget member identity; owner changes use the dedicated ownership operation.
expectedRolestringMember role you reviewed; rejects a stale administrative change.

Returns

Code
error

Call example

Code
client.RemoveDriveMember(ctx, drive, member, expectedRole)
HTTP requests

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

Remove non-owner access and invalidate outstanding invitations

Request and response contract
{
  "id": "delete-drives-drive-members-member",
  "path": "/drives/{drive}/members/{member}",
  "method": "DELETE",
  "summary": "Remove non-owner access and invalidate outstanding invitations",
  "security": [
    {
      "bearer": []
    }
  ],
  "parameters": [
    {
      "name": "expected_role",
      "in": "query",
      "required": true,
      "schema": {
        "type": "string",
        "enum": [
          "viewer",
          "editor",
          "admin",
          "owner"
        ]
      }
    }
  ],
  "responses": {
    "204": {
      "description": "Membership removed; files remain unchanged"
    },
    "400": {
      "description": "Missing or invalid displayed role"
    },
    "401": {
      "description": "Interactive session required"
    },
    "403": {
      "description": "Owner is protected"
    },
    "404": {
      "description": "Drive or member inaccessible"
    },
    "409": {
      "description": "Displayed role no longer matches"
    }
  }
}
PlatformAuditLatest 100 product configuration changes; platform administrator only
Code
func (c *Client) PlatformAudit(ctx context.Context) ([]map[string]any, error)

Parameters

NameType / defaultMeaning
ctxcontext.ContextCaller-owned context for cancellation and deadlines.

Returns

Code
([]map[string]any, error)

Call example

Code
client.PlatformAudit(ctx)
HTTP requests

GET /platform/audit

Latest 100 product configuration changes; platform administrator only

Request and response contract
{
  "id": "get-platform-audit",
  "path": "/platform/audit",
  "method": "GET",
  "summary": "Latest 100 product configuration changes; platform administrator only",
  "security": [
    {
      "bearer": []
    }
  ],
  "responses": {
    "200": {
      "description": "Audit records, newest first",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "items": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/PlatformAuditEntry"
                }
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "Session required"
    },
    "403": {
      "description": "Platform administrator access required"
    }
  }
}

Errors and exact retries

Handle a failed version guard without silently overwriting a newer edit. This fragment uses an existing client and your pending input.

Code
import "errors"

var apiError *nufs.APIError
if errors.As(err, &apiError) {
    if apiError.IsPrecondition() {
        // Preserve the edit and inspect the newer head.
    }
    if apiError.IsAuthorization() {
        // Check current scope and session.
    }
}