Files

Encrypted file and folder records with hierarchy, access roles, and tag assignments.

Encrypted file storage with directory hierarchy, tags, and streaming downloads. All user content (file names, MIME types, metadata) is encrypted client-side before reaching the server — the server only stores opaque AES-GCM blobs. Structural metadata (hierarchy, status, size) stays in the clear for query filtering and chunk management.

Files and folders share the same drive_file table — distinguished by kind. File content is stored as encrypted chunks in S3 using Segmented AEAD (AES-256-GCM, 256 KB plaintext frames), enabling random-access streaming and HTTP Range request support.

All methods use the JSON-RPC 2.0 protocol over WebSocket. See Enbox API for transport details, error codes, query operators, and encryption model.

Service: drive.files

Fields

Field	Type	Required	Description
`id`	`string`	—	Primary key. Read-only, auto-generated
`parent_id`	`string?`		Parent folder id. `null` = root level
`owner_id`	`string`	—	Owner user id. Read-only, auto-set on create
`owner_wrapped_key`	`string`	✅	Content key wrapped by owner’s account key (base64)
`folder_wrapped_key`	`string?`		Content key wrapped by parent folder key. `null` at root level
`kind`	`string`	✅	Node type. Values: `folder` · `file`
`size_bytes`	`integer`		Logical plaintext file size in bytes. `0` for folders
`status`	`string?`	—	Upload lifecycle state. Read-only. Values: `pending` (uploading) · `ready` (finalized). `null` for folders
`favorite`	`boolean`		Starred for quick access. Default `false`
`trashed`	`boolean`		Soft-deleted (in Trash). Default `false`
`thumbnail_128_id`	`string?`	—	Chunk id of the encrypted 128 px thumbnail. Read-only. `null` for non-image/video files and folders
`chunk_count`	`integer`	—	Number of uploaded content chunks. Read-only, computed
`enc_name`	`string`	✅	Encrypted file/folder name. Plain `string` after decryption
`enc_mime_type`	`string`		Encrypted MIME type. Plain `string` after decryption (e.g. `"image/png"`, `"video/mp4"`). `null` for folders
`enc_metadata`	`string?`		Encrypted JSON metadata (EXIF, descriptions, custom fields). Loaded only in detail view. Nullable
`created_at`	`string`	—	ISO 8601 creation timestamp. Read-only
`updated_at`	`string`	—	ISO 8601 last update timestamp. Read-only
`file_user_role`	UserRole[]	✅	Access control + encryption keys
`file_tag`	`string[]`		Assigned tag IDs

Filterable: parent_id · kind · favorite · trashed

Warning: When creating a folder, set kind: "folder", size_bytes: 0, and omit enc_mime_type. The server does not enforce these conventions — the client is responsible for consistent folder semantics.

UserRole

Access control entry. Each recipient gets their own copy of the record’s encryption key, wrapped with their public key.

Field	Type	Required	Description
`user_id`	`string`	✅	Recipient user id
`role`	`string`	✅	Role identifier. Values: `owner` · `editor` · `viewer`
`wrapped_content_key`	`string`	✅	Record key wrapped for this recipient (base64)

FileChunk

Ordered chunk reference for a file. Created by confirmChunk.

Field	Type	Required	Description
`id`	`string`	—	Primary key. Read-only
`file_id`	`string`	✅	Parent File id
`chunk_index`	`integer`	✅	0-based chunk order
`chunk_id`	`string`	✅	Reference to the stored encrypted blob

find

List files and folders with filtering, sorting, and pagination.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "drive.files.find",
  "params": {
    "filter": { "trashed": { "$eq": false } },
    "sort": [{ "field": "created_at", "dir": "desc" }],
    "limit": 200,
    "fields": [
      "id", "parent_id", "owner_id", "owner_wrapped_key", "folder_wrapped_key",
      "kind", "size_bytes", "status", "favorite", "trashed",
      "thumbnail_128_id", "chunk_count", "created_at", "updated_at",
      "enc_name", "enc_mime_type",
      "file_user_role.user_id", "file_user_role.wrapped_content_key",
      "file_tag.tag_id"
    ]
  },
  "id": 1
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    "items": [
      {
        "id": "1920438291500",
        "parent_id": null,
        "owner_id": "42",
        "owner_wrapped_key": "<base64>",
        "folder_wrapped_key": null,
        "kind": "folder",
        "size_bytes": 0,
        "status": null,
        "favorite": false,
        "trashed": false,
        "thumbnail_128_id": null,
        "chunk_count": 0,
        "created_at": "2026-05-01T10:00:00Z",
        "updated_at": "2026-05-01T10:00:00Z",
        "enc_name": "<base64>",
        "enc_mime_type": null,
        "file_user_role": [
          { "user_id": "42", "wrapped_content_key": "<base64>" }
        ],
        "file_tag": []
      },
      {
        "id": "1920438291510",
        "parent_id": "1920438291500",
        "owner_id": "42",
        "owner_wrapped_key": "<base64>",
        "folder_wrapped_key": null,
        "kind": "file",
        "size_bytes": 5242880,
        "status": "ready",
        "favorite": true,
        "trashed": false,
        "thumbnail_128_id": "1920438291590",
        "chunk_count": 2,
        "created_at": "2026-05-10T14:30:00Z",
        "updated_at": "2026-05-10T14:30:00Z",
        "enc_name": "<base64>",
        "enc_mime_type": "<base64>",
        "file_user_role": [
          { "user_id": "42", "wrapped_content_key": "<base64>" }
        ],
        "file_tag": ["1920438291600"]
      }
    ],
    "total": 2
  },
  "id": 1
}

findOneById

Fetch a single file or folder with full detail including metadata.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "drive.files.findOneById",
  "params": {
    "id": "1920438291510",
    "fields": [
      "id", "parent_id", "owner_id", "owner_wrapped_key", "folder_wrapped_key",
      "kind", "size_bytes", "status", "favorite", "trashed",
      "thumbnail_128_id", "chunk_count", "created_at", "updated_at",
      "enc_name", "enc_mime_type", "enc_metadata",
      "file_user_role.user_id", "file_user_role.wrapped_content_key",
      "file_tag.tag_id"
    ]
  },
  "id": 2
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    "id": "1920438291510",
    "parent_id": "1920438291500",
    "owner_id": "42",
    "owner_wrapped_key": "<base64>",
    "folder_wrapped_key": null,
    "kind": "file",
    "size_bytes": 5242880,
    "status": "ready",
    "favorite": true,
    "trashed": false,
    "thumbnail_128_id": "1920438291590",
    "chunk_count": 2,
    "created_at": "2026-05-10T14:30:00Z",
    "updated_at": "2026-05-10T14:30:00Z",
    "enc_name": "<base64>",
    "enc_mime_type": "<base64>",
    "enc_metadata": "<base64>",
    "file_user_role": [
      { "user_id": "42", "wrapped_content_key": "<base64>" }
    ],
    "file_tag": ["1920438291600"]
  },
  "id": 2
}

create

Create a new file or folder. The server assigns id, created_at, and updated_at.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "drive.files.create",
  "params": {
    "document": {
      "parent_id": "1920438291500",
      "kind": "file",
      "size_bytes": 5242880,
      "enc_name": "<base64>",
      "enc_mime_type": "<base64>",
      "owner_id": "42",
      "owner_wrapped_key": "<base64>",
      "file_user_role": [
        { "user_id": "42", "role": "owner", "wrapped_content_key": "<base64>" }
      ]
    }
  },
  "id": 3
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    "id": "1920438291510",
    "parent_id": "1920438291500",
    "kind": "file",
    "enc_name": "<base64>",
    "created_at": "2026-05-10T14:30:00Z"
  },
  "id": 3
}

updateOneById

Partial update — only specified fields change; omitted fields are untouched. Nested collections are updated automatically: items with id are updated, items without id are created, items missing from the array are deleted.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "drive.files.updateOneById",
  "params": {
    "id": "1920438291510",
    "document": {
      "favorite": true,
      "enc_name": "<base64-new>"
    }
  },
  "id": 4
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    "id": "1920438291510",
    "favorite": true,
    "enc_name": "<base64-new>",
    "updated_at": "2026-05-13T18:45:00Z"
  },
  "id": 4
}

replaceOneById

Full replacement — all writable fields must be provided. Unlike updateOneById, omitted fields are reset to defaults. Nested collections (file_user_role, file_tag) are not accepted in this method — use updateOneById to modify them.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "drive.files.replaceOneById",
  "params": {
    "id": "1920438291510",
    "document": {
      "parent_id": "1920438291500",
      "kind": "file",
      "size_bytes": 5242880,
      "favorite": true,
      "trashed": false,
      "enc_name": "<base64>",
      "enc_mime_type": "<base64>"
    }
  },
  "id": 4
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    "id": "1920438291510",
    "enc_name": "<base64>",
    "updated_at": "2026-05-13T18:45:00Z"
  },
  "id": 4
}

update

Batch update multiple files in a single transaction (all-or-nothing). See Batch operations.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "drive.files.update",
  "params": {
    "items": [
      { "id": "1920438291510", "document": { "trashed": true } },
      { "id": "1920438291511", "document": { "trashed": true } }
    ]
  },
  "id": 5
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    "affected": 2,
    "items": [
      { "id": "1920438291510", "trashed": true },
      { "id": "1920438291511", "trashed": true }
    ]
  },
  "id": 5
}

deleteOneById

Permanently delete a file or folder. All child nodes (files in a folder), tag assignments, chunks, and access roles are deleted with it.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "drive.files.deleteOneById",
  "params": {
    "id": "1920438291510"
  },
  "id": 6
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    "id": "1920438291510",
    "enc_name": "<base64>"
  },
  "id": 6
}

delete

Batch delete files in a single transaction (all-or-nothing). See Batch operations.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "drive.files.delete",
  "params": {
    "items": [
      { "id": "1920438291510" },
      { "id": "1920438291511" }
    ]
  },
  "id": 7
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    "affected": 2,
    "items": [
      { "id": "1920438291510" },
      { "id": "1920438291511" }
    ]
  },
  "id": 7
}