Folders

Folders serve as task lists and sections, with top-level folders as sidebar lists and child folders as kanban sections.

Service: tasks.folders

Folders serve as task lists and sections. A top-level folder (parent_id = null) appears in the sidebar as a list. A child folder (parent_id pointing to another folder) represents a section — displayed as a kanban column in board view.

Fields

Field	Type	Required	Description
id	string	—	Primary key. Read-only, auto-generated
parent_id	string?		Parent folder. null = sidebar list, non-null = section inside parent
is_folder	boolean		false = plain list, true = board container. Default false
position	float		Fractional drag-sort position
enc_name	string	✅	Encrypted folder name. Plain string after decryption
enc_color	string		Encrypted color identifier. Plain string after decryption. Values: primary · secondary · success · danger · warning · info · dark
enc_icon	string		Encrypted icon name. Plain string after decryption. Value is a Bootstrap Icons name (e.g. "list-task", "briefcase")
created_at	string	—	ISO 8601 creation timestamp. Read-only
updated_at	string	—	ISO 8601 last update timestamp. Read-only
folder_user_role	UserRole[]	✅	Access control + encryption keys

Filterable: parent_id · is_folder

find

List folders accessible to the authenticated user.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "tasks.folders.find",
  "params": {
    "limit": 100,
    "fields": [
      "id", "parent_id", "is_folder", "position",
      "enc_name", "enc_color", "enc_icon",
      "folder_user_role.user_id",
      "folder_user_role.wrapped_content_key"
    ]
  },
  "id": 10
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    "items": [
      {
        "id": "1920438291700",
        "parent_id": null,
        "is_folder": false,
        "position": 1000.0,
        "enc_name": "<base64>",
        "enc_color": "<base64>",
        "enc_icon": "<base64>",
        "folder_user_role": [
          { "user_id": "42", "wrapped_content_key": "<base64>" }
        ]
      }
    ],
    "total": 1
  },
  "id": 10
}

findOneById

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "tasks.folders.findOneById",
  "params": {
    "id": "1920438291700"
  },
  "id": 11
}

create

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "tasks.folders.create",
  "params": {
    "document": {
      "parent_id": null,
      "is_folder": false,
      "position": 3000.0,
      "enc_name": "<base64>",
      "enc_color": "<base64>",
      "enc_icon": "<base64>",
      "folder_user_role": [
        { "user_id": "42", "role": "owner", "wrapped_content_key": "<base64>" }
      ]
    }
  },
  "id": 12
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    "id": "1920438291720",
    "enc_name": "<base64>",
    "created_at": "2026-05-13T18:30:00Z"
  },
  "id": 12
}

updateOneById

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "tasks.folders.updateOneById",
  "params": {
    "id": "1920438291700",
    "document": {
      "position": 1500.0,
      "enc_name": "<base64-new>"
    }
  },
  "id": 13
}

replaceOneById

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

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "tasks.folders.replaceOneById",
  "params": {
    "id": "1920438291700",
    "document": {
      "parent_id": null,
      "is_folder": false,
      "position": 1500.0,
      "enc_name": "<base64>",
      "enc_color": "<base64>",
      "enc_icon": "<base64>"
    }
  },
  "id": 13
}

deleteOneById

Delete a folder. Child sections (folders with parent_id pointing here) are deleted with it. Tasks that belonged to this folder are moved to Inbox (folder_id becomes null).

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "tasks.folders.deleteOneById",
  "params": {
    "id": "1920438291700"
  },
  "id": 14
}

update

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

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "tasks.folders.update",
  "params": {
    "items": [
      { "id": "1920438291700", "document": { "position": 500.0 } },
      { "id": "1920438291705", "document": { "position": 1500.0 } }
    ]
  },
  "id": 15
}

delete

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

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "tasks.folders.delete",
  "params": {
    "items": [
      { "id": "1920438291700" },
      { "id": "1920438291705" }
    ]
  },
  "id": 16
}