{
  "openapi": "3.1.0",
  "info": {
    "title": "OxiCloud API",
    "description": "REST API for OxiCloud — self-hosted cloud storage, calendar & contacts",
    "license": {
      "name": "MIT"
    },
    "version": "0.5.3"
  },
  "paths": {
    "/api/favorites": {
      "get": {
        "tags": [
          "favorites"
        ],
        "summary": "Handler for favorite-related API endpoints",
        "operationId": "get_favorites",
        "responses": {
          "200": {
            "description": "List of favorites",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/FavoriteItemDto"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/favorites/batch": {
      "post": {
        "tags": [
          "favorites"
        ],
        "summary": "Add multiple items to favourites in a single transaction.\nPOST /api/favorites/batch",
        "operationId": "batch_add_favorites",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchFavoritesRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Batch add result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchFavoritesResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          }
        }
      }
    },
    "/api/favorites/{item_type}/{item_id}": {
      "post": {
        "tags": [
          "favorites"
        ],
        "summary": "Add an item to user's favorites",
        "operationId": "add_favorite",
        "parameters": [
          {
            "name": "item_type",
            "in": "path",
            "description": "Item type (file or folder)",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "item_id",
            "in": "path",
            "description": "Item ID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Item added to favorites"
          },
          "400": {
            "description": "Invalid item type"
          }
        }
      },
      "delete": {
        "tags": [
          "favorites"
        ],
        "summary": "Remove an item from user's favorites",
        "operationId": "remove_favorite",
        "parameters": [
          {
            "name": "item_type",
            "in": "path",
            "description": "Item type (file or folder)",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "item_id",
            "in": "path",
            "description": "Item ID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Item removed from favorites"
          },
          "404": {
            "description": "Item not in favorites"
          }
        }
      }
    },
    "/api/recent": {
      "get": {
        "tags": [
          "recent"
        ],
        "summary": "Get user's recent items",
        "operationId": "get_recent_items",
        "responses": {
          "200": {
            "description": "List of recent items",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/RecentItemDto"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/recent/clear": {
      "delete": {
        "tags": [
          "recent"
        ],
        "summary": "Clear all recent items",
        "operationId": "clear_recent_items",
        "responses": {
          "200": {
            "description": "Recent items cleared"
          }
        }
      }
    },
    "/api/recent/{item_type}/{item_id}": {
      "post": {
        "tags": [
          "recent"
        ],
        "summary": "Record access to an item",
        "operationId": "record_item_access",
        "parameters": [
          {
            "name": "item_type",
            "in": "path",
            "description": "Item type (file or folder)",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "item_id",
            "in": "path",
            "description": "Item ID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Access recorded"
          },
          "400": {
            "description": "Invalid item type"
          }
        }
      },
      "delete": {
        "tags": [
          "recent"
        ],
        "summary": "Remove an item from recents",
        "operationId": "remove_from_recent",
        "parameters": [
          {
            "name": "item_type",
            "in": "path",
            "description": "Item type (file or folder)",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "item_id",
            "in": "path",
            "description": "Item ID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Item removed from recents"
          },
          "404": {
            "description": "Item not in recents"
          }
        }
      }
    },
    "/api/s/{token}": {
      "get": {
        "tags": [
          "shares"
        ],
        "summary": "Access a shared item via its token",
        "operationId": "access_shared_item",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "description": "Share token",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Shared item details"
          },
          "401": {
            "description": "Password required"
          },
          "410": {
            "description": "Share expired"
          }
        }
      }
    },
    "/api/s/{token}/verify": {
      "post": {
        "tags": [
          "shares"
        ],
        "summary": "Verify password for a password-protected shared item",
        "operationId": "verify_shared_item_password",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "description": "Share token",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VerifyPasswordRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Password verified, item details returned"
          },
          "401": {
            "description": "Invalid password"
          },
          "410": {
            "description": "Share expired"
          }
        }
      }
    },
    "/api/shares": {
      "get": {
        "tags": [
          "shares"
        ],
        "summary": "Get all shared links created by the current user.\nSupports optional filtering by item_id + item_type query params.",
        "operationId": "get_user_shares",
        "responses": {
          "200": {
            "description": "List of shares",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ShareDto"
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "shares"
        ],
        "summary": "Create a new shared link",
        "operationId": "create_shared_link",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateShareDto"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Share created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShareDto"
                }
              }
            }
          },
          "400": {
            "description": "Bad request"
          }
        }
      }
    },
    "/api/shares/{id}": {
      "get": {
        "tags": [
          "shares"
        ],
        "summary": "Get information about a specific shared link by ID",
        "operationId": "get_shared_link",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Share ID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Share details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShareDto"
                }
              }
            }
          },
          "404": {
            "description": "Share not found"
          }
        }
      },
      "put": {
        "tags": [
          "shares"
        ],
        "summary": "Update a shared link's properties",
        "operationId": "update_shared_link",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Share ID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateShareDto"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Share updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShareDto"
                }
              }
            }
          },
          "404": {
            "description": "Share not found"
          }
        }
      },
      "delete": {
        "tags": [
          "shares"
        ],
        "summary": "Delete a shared link",
        "operationId": "delete_shared_link",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Share ID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Share deleted"
          },
          "404": {
            "description": "Share not found"
          }
        }
      }
    },
    "/api/trash": {
      "get": {
        "tags": [
          "trash"
        ],
        "summary": "Gets all items in the trash for the current user",
        "operationId": "get_trash_items",
        "responses": {
          "200": {
            "description": "List of trashed items"
          },
          "501": {
            "description": "Trash feature not enabled"
          }
        }
      }
    },
    "/api/trash/empty": {
      "delete": {
        "tags": [
          "trash"
        ],
        "summary": "Empties the trash completely for the current user",
        "operationId": "empty_trash",
        "responses": {
          "200": {
            "description": "Trash emptied successfully"
          },
          "501": {
            "description": "Trash feature not enabled"
          }
        }
      }
    },
    "/api/trash/files/{id}": {
      "delete": {
        "tags": [
          "trash"
        ],
        "summary": "Moves a file to the trash",
        "operationId": "move_file_to_trash",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "File ID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "File moved to trash"
          },
          "501": {
            "description": "Trash feature not enabled"
          }
        }
      }
    },
    "/api/trash/folders/{id}": {
      "delete": {
        "tags": [
          "trash"
        ],
        "summary": "Moves a folder to the trash",
        "operationId": "move_folder_to_trash",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Folder ID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Folder moved to trash"
          },
          "501": {
            "description": "Trash feature not enabled"
          }
        }
      }
    },
    "/api/trash/{id}": {
      "delete": {
        "tags": [
          "trash"
        ],
        "summary": "Permanently deletes an item from the trash",
        "operationId": "delete_permanently",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Trash item ID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Item permanently deleted"
          },
          "501": {
            "description": "Trash feature not enabled"
          }
        }
      }
    },
    "/api/trash/{id}/restore": {
      "post": {
        "tags": [
          "trash"
        ],
        "summary": "Restores an item from the trash to its original location",
        "operationId": "restore_from_trash",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Trash item ID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Item restored from trash"
          },
          "501": {
            "description": "Trash feature not enabled"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AuthResponseDto": {
        "type": "object",
        "required": [
          "user",
          "access_token",
          "refresh_token",
          "token_type",
          "expires_in"
        ],
        "properties": {
          "access_token": {
            "type": "string"
          },
          "expires_in": {
            "type": "integer",
            "format": "int64"
          },
          "refresh_token": {
            "type": "string"
          },
          "token_type": {
            "type": "string"
          },
          "user": {
            "$ref": "#/components/schemas/UserDto"
          }
        }
      },
      "BatchFavoriteItem": {
        "type": "object",
        "description": "Single item in a batch-add-favorites request.",
        "required": [
          "item_id",
          "item_type"
        ],
        "properties": {
          "item_id": {
            "type": "string"
          },
          "item_type": {
            "type": "string"
          }
        }
      },
      "BatchFavoritesRequest": {
        "type": "object",
        "description": "Request body for POST /api/favorites/batch",
        "required": [
          "items"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BatchFavoriteItem"
            }
          }
        }
      },
      "BatchFavoritesResult": {
        "type": "object",
        "description": "Result DTO for batch add-to-favorites.",
        "required": [
          "stats",
          "favorites"
        ],
        "properties": {
          "favorites": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FavoriteItemDto"
            },
            "description": "Full list of the user's favourites (enriched), so the client can\nreplace its local cache in a single round-trip."
          },
          "stats": {
            "$ref": "#/components/schemas/BatchFavoritesStats",
            "description": "Statistics about the batch operation"
          }
        }
      },
      "BatchFavoritesStats": {
        "type": "object",
        "required": [
          "requested",
          "inserted",
          "already_existed"
        ],
        "properties": {
          "already_existed": {
            "type": "integer",
            "format": "int64",
            "description": "How many were already favourites (skipped)",
            "minimum": 0
          },
          "inserted": {
            "type": "integer",
            "format": "int64",
            "description": "How many were actually inserted (new)",
            "minimum": 0
          },
          "requested": {
            "type": "integer",
            "description": "How many items were requested",
            "minimum": 0
          }
        }
      },
      "ChangePasswordDto": {
        "type": "object",
        "required": [
          "current_password",
          "new_password"
        ],
        "properties": {
          "current_password": {
            "type": "string"
          },
          "new_password": {
            "type": "string"
          }
        }
      },
      "CreateFolderDto": {
        "type": "object",
        "description": "DTO for folder creation requests",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Name of the folder to create"
          },
          "parent_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Parent folder ID (None for root level)"
          }
        }
      },
      "CreateShareDto": {
        "type": "object",
        "required": [
          "item_id",
          "item_type"
        ],
        "properties": {
          "expires_at": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "minimum": 0
          },
          "item_id": {
            "type": "string"
          },
          "item_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "item_type": {
            "type": "string"
          },
          "password": {
            "type": [
              "string",
              "null"
            ]
          },
          "permissions": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/SharePermissionsDto"
              }
            ]
          }
        }
      },
      "DeletePermanentlyRequest": {
        "type": "object",
        "description": "Request to permanently delete an item from trash",
        "required": [
          "trash_id"
        ],
        "properties": {
          "trash_id": {
            "type": "string"
          }
        }
      },
      "FavoriteItemDto": {
        "type": "object",
        "description": "DTO for favorites item, enriched with item metadata via SQL JOIN\nso the frontend does not need N+1 requests to resolve names/sizes.",
        "required": [
          "id",
          "user_id",
          "item_id",
          "item_type",
          "created_at",
          "icon_class",
          "icon_special_class",
          "category",
          "size_formatted"
        ],
        "properties": {
          "category": {
            "type": "string",
            "description": "Human-readable category (e.g. \"Image\", \"Folder\")"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the item was added to favorites"
          },
          "icon_class": {
            "type": "string",
            "description": "FontAwesome icon CSS class (e.g. \"fas fa-file-image\", \"fas fa-folder\")"
          },
          "icon_special_class": {
            "type": "string",
            "description": "Extra CSS class for icon styling (e.g. \"image-icon\", \"folder-icon\")"
          },
          "id": {
            "type": "string",
            "description": "Unique identifier for the favorite entry"
          },
          "item_id": {
            "type": "string",
            "description": "ID of the favorited item (file or folder)"
          },
          "item_mime_type": {
            "type": [
              "string",
              "null"
            ],
            "description": "MIME type (files only)"
          },
          "item_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Display name of the file or folder"
          },
          "item_size": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Size in bytes (files only; folders → None)"
          },
          "item_type": {
            "type": "string",
            "description": "Type of the item ('file' or 'folder')"
          },
          "modified_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Last modification timestamp of the item"
          },
          "parent_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Parent folder ID (folder_id for files, parent_id for folders)"
          },
          "size_formatted": {
            "type": "string",
            "description": "Formatted file size (e.g. \"3.27 MB\"); \"--\" for folders"
          },
          "user_id": {
            "type": "string",
            "description": "User ID who owns this favorite"
          }
        }
      },
      "FileDto": {
        "type": "object",
        "description": "DTO for file responses",
        "required": [
          "id",
          "name",
          "path",
          "size",
          "mime_type",
          "created_at",
          "modified_at",
          "icon_class",
          "icon_special_class",
          "category",
          "size_formatted"
        ],
        "properties": {
          "category": {
            "type": "string",
            "description": "Human-readable file category (e.g. \"Image\", \"Document\")"
          },
          "created_at": {
            "type": "integer",
            "format": "int64",
            "description": "Creation timestamp",
            "minimum": 0
          },
          "folder_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Parent folder ID"
          },
          "icon_class": {
            "type": "string",
            "description": "FontAwesome icon CSS class (e.g. \"fas fa-file-image\")"
          },
          "icon_special_class": {
            "type": "string",
            "description": "Extra CSS class for icon styling (e.g. \"image-icon\", \"\" when default)"
          },
          "id": {
            "type": "string",
            "description": "File ID"
          },
          "mime_type": {
            "type": "string",
            "description": "MIME type — `Arc<str>` because MIME values repeat across files\nand DTOs are cloned on every request (clone is O(1) atomic increment)."
          },
          "modified_at": {
            "type": "integer",
            "format": "int64",
            "description": "Last modification timestamp",
            "minimum": 0
          },
          "name": {
            "type": "string",
            "description": "File name"
          },
          "owner_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Owner user ID (omitted from JSON when None)"
          },
          "path": {
            "type": "string",
            "description": "Path to the file (relative)"
          },
          "size": {
            "type": "integer",
            "format": "int64",
            "description": "Size in bytes",
            "minimum": 0
          },
          "size_formatted": {
            "type": "string",
            "description": "Human-readable formatted size (e.g. \"3.27 MB\")"
          },
          "sort_date": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Sort date for Photos timeline — COALESCE(EXIF captured_at, created_at).\nOnly populated by the /api/photos endpoint.",
            "minimum": 0
          }
        }
      },
      "FolderDto": {
        "type": "object",
        "description": "DTO for folder responses",
        "required": [
          "id",
          "name",
          "path",
          "created_at",
          "modified_at",
          "is_root",
          "icon_class",
          "icon_special_class",
          "category"
        ],
        "properties": {
          "category": {
            "type": "string",
            "description": "Human-readable category (always \"Folder\")"
          },
          "created_at": {
            "type": "integer",
            "format": "int64",
            "description": "Creation timestamp",
            "minimum": 0
          },
          "icon_class": {
            "type": "string",
            "description": "FontAwesome icon CSS class (always \"fas fa-folder\")"
          },
          "icon_special_class": {
            "type": "string",
            "description": "Extra CSS class for icon styling (always \"folder-icon\")"
          },
          "id": {
            "type": "string",
            "description": "Folder ID"
          },
          "is_root": {
            "type": "boolean",
            "description": "Whether this is a root folder"
          },
          "modified_at": {
            "type": "integer",
            "format": "int64",
            "description": "Last modification timestamp",
            "minimum": 0
          },
          "name": {
            "type": "string",
            "description": "Folder name"
          },
          "owner_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Owner user ID (scopes visibility per user)"
          },
          "parent_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Parent folder ID"
          },
          "path": {
            "type": "string",
            "description": "Path to the folder (relative)"
          }
        }
      },
      "FolderListingDto": {
        "type": "object",
        "description": "Combined DTO that returns both sub-folders and files for a given folder\nin a single response, eliminating the double-fetch on every navigation.",
        "required": [
          "folders",
          "files"
        ],
        "properties": {
          "files": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FileDto"
            },
            "description": "Files inside the requested folder"
          },
          "folders": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FolderDto"
            },
            "description": "Sub-folders inside the requested folder"
          }
        }
      },
      "LoginDto": {
        "type": "object",
        "required": [
          "username",
          "password"
        ],
        "properties": {
          "password": {
            "type": "string"
          },
          "username": {
            "type": "string"
          }
        }
      },
      "MoveFilePayload": {
        "type": "object",
        "description": "Payload for moving a file",
        "properties": {
          "folder_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Target folder ID (None means root)"
          }
        }
      },
      "MoveFolderDto": {
        "type": "object",
        "description": "DTO for folder move requests",
        "properties": {
          "parent_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "New parent folder ID (None for root level)"
          }
        }
      },
      "MoveToTrashRequest": {
        "type": "object",
        "description": "Request to move an item to trash",
        "required": [
          "item_id",
          "item_type"
        ],
        "properties": {
          "item_id": {
            "type": "string"
          },
          "item_type": {
            "type": "string"
          }
        }
      },
      "PaginationDto": {
        "type": "object",
        "description": "A DTO to represent pagination information",
        "required": [
          "page",
          "page_size",
          "total_items",
          "total_pages",
          "has_next",
          "has_prev"
        ],
        "properties": {
          "has_next": {
            "type": "boolean",
            "description": "Indicates if there is a next page"
          },
          "has_prev": {
            "type": "boolean",
            "description": "Indicates if there is a previous page"
          },
          "page": {
            "type": "integer",
            "description": "Current page (starts at 0)",
            "minimum": 0
          },
          "page_size": {
            "type": "integer",
            "description": "Page size",
            "minimum": 0
          },
          "total_items": {
            "type": "integer",
            "description": "Total number of items",
            "minimum": 0
          },
          "total_pages": {
            "type": "integer",
            "description": "Total number of pages",
            "minimum": 0
          }
        }
      },
      "PaginationRequestDto": {
        "type": "object",
        "description": "A DTO to represent a pagination request",
        "properties": {
          "page": {
            "type": "integer",
            "description": "Requested page (starts at 0)",
            "minimum": 0
          },
          "page_size": {
            "type": "integer",
            "description": "Requested page size",
            "minimum": 0
          }
        }
      },
      "RecentItemDto": {
        "type": "object",
        "description": "DTO for recent items, enriched with item metadata via SQL JOIN\nso the frontend does not need N+1 requests to resolve names/sizes.",
        "required": [
          "id",
          "user_id",
          "item_id",
          "item_type",
          "accessed_at",
          "icon_class",
          "icon_special_class",
          "category",
          "size_formatted"
        ],
        "properties": {
          "accessed_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the item was accessed"
          },
          "category": {
            "type": "string",
            "description": "Human-readable category (e.g. \"Image\", \"Folder\")"
          },
          "icon_class": {
            "type": "string",
            "description": "FontAwesome icon CSS class (e.g. \"fas fa-file-image\", \"fas fa-folder\")"
          },
          "icon_special_class": {
            "type": "string",
            "description": "Extra CSS class for icon styling (e.g. \"image-icon\", \"folder-icon\")"
          },
          "id": {
            "type": "string",
            "description": "Unique identifier for the recent item"
          },
          "item_id": {
            "type": "string",
            "description": "Item ID (file or folder)"
          },
          "item_mime_type": {
            "type": [
              "string",
              "null"
            ],
            "description": "MIME type (files only)"
          },
          "item_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Display name of the file or folder"
          },
          "item_size": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Size in bytes (files only; folders → None)"
          },
          "item_type": {
            "type": "string",
            "description": "Item type ('file' or 'folder')"
          },
          "parent_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Parent folder ID (folder_id for files, parent_id for folders)"
          },
          "size_formatted": {
            "type": "string",
            "description": "Formatted file size (e.g. \"3.27 MB\"); \"--\" for folders"
          },
          "user_id": {
            "type": "string",
            "description": "Owner user ID"
          }
        }
      },
      "RefreshTokenDto": {
        "type": "object",
        "required": [
          "refresh_token"
        ],
        "properties": {
          "refresh_token": {
            "type": "string"
          }
        }
      },
      "RegisterDto": {
        "type": "object",
        "required": [
          "username",
          "email",
          "password"
        ],
        "properties": {
          "email": {
            "type": "string"
          },
          "password": {
            "type": "string"
          },
          "username": {
            "type": "string"
          }
        }
      },
      "RenameFolderDto": {
        "type": "object",
        "description": "DTO for folder rename requests",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "New name for the folder"
          }
        }
      },
      "RestoreFromTrashRequest": {
        "type": "object",
        "description": "Request to restore an item from trash",
        "required": [
          "trash_id"
        ],
        "properties": {
          "trash_id": {
            "type": "string"
          }
        }
      },
      "SearchCriteriaDto": {
        "type": "object",
        "description": "\n * Data Transfer Object for file search criteria.\n *\n * This structure represents all possible search parameters that can be used\n * to filter files and folders in the system. It supports various filter types\n * including name matching, file types, date ranges, and size constraints.",
        "properties": {
          "created_after": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Optional minimum creation date (seconds since epoch)",
            "minimum": 0
          },
          "created_before": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Optional maximum creation date (seconds since epoch)",
            "minimum": 0
          },
          "file_types": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "Optional list of file extensions to include (e.g., \"pdf\", \"jpg\")"
          },
          "folder_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional folder ID to limit search scope"
          },
          "limit": {
            "type": "integer",
            "description": "Maximum number of results to return",
            "minimum": 0
          },
          "max_size": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Optional maximum file size in bytes",
            "minimum": 0
          },
          "min_size": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Optional minimum file size in bytes",
            "minimum": 0
          },
          "modified_after": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Optional minimum modification date (seconds since epoch)",
            "minimum": 0
          },
          "modified_before": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Optional maximum modification date (seconds since epoch)",
            "minimum": 0
          },
          "name_contains": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional text to search in file/folder names"
          },
          "offset": {
            "type": "integer",
            "description": "Offset for pagination",
            "minimum": 0
          },
          "recursive": {
            "type": "boolean",
            "description": "Whether to search recursively within subfolders (default: true)"
          },
          "sort_by": {
            "type": "string",
            "description": "Sort order for results: \"relevance\", \"name\", \"name_desc\", \"date\", \"date_desc\", \"size\", \"size_desc\""
          }
        }
      },
      "SearchFileResultDto": {
        "type": "object",
        "description": "A file search result enriched with server-computed metadata",
        "required": [
          "id",
          "name",
          "path",
          "size",
          "mime_type",
          "created_at",
          "modified_at",
          "relevance_score",
          "size_formatted",
          "icon_class",
          "icon_special_class",
          "category"
        ],
        "properties": {
          "category": {
            "type": "string",
            "description": "Content category: \"document\", \"image\", \"video\", \"audio\", \"archive\", \"code\", \"other\""
          },
          "created_at": {
            "type": "integer",
            "format": "int64",
            "description": "Creation timestamp",
            "minimum": 0
          },
          "folder_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Parent folder ID"
          },
          "icon_class": {
            "type": "string",
            "description": "CSS icon class for the file type (e.g., \"fas fa-file-pdf\")"
          },
          "icon_special_class": {
            "type": "string",
            "description": "Extra CSS class for icon styling (e.g., \"pdf-icon\", \"code-icon js-icon\")"
          },
          "id": {
            "type": "string",
            "description": "File ID"
          },
          "mime_type": {
            "type": "string",
            "description": "MIME type"
          },
          "modified_at": {
            "type": "integer",
            "format": "int64",
            "description": "Last modification timestamp",
            "minimum": 0
          },
          "name": {
            "type": "string",
            "description": "File name"
          },
          "path": {
            "type": "string",
            "description": "Path to the file (relative)"
          },
          "relevance_score": {
            "type": "integer",
            "format": "int32",
            "description": "Relevance score (0-100) computed server-side",
            "minimum": 0
          },
          "size": {
            "type": "integer",
            "format": "int64",
            "description": "Size in bytes",
            "minimum": 0
          },
          "size_formatted": {
            "type": "string",
            "description": "Human-readable file size (e.g., \"2.5 MB\")"
          }
        }
      },
      "SearchFolderResultDto": {
        "type": "object",
        "description": "A folder search result enriched with server-computed metadata",
        "required": [
          "id",
          "name",
          "path",
          "created_at",
          "modified_at",
          "is_root",
          "relevance_score"
        ],
        "properties": {
          "created_at": {
            "type": "integer",
            "format": "int64",
            "description": "Creation timestamp",
            "minimum": 0
          },
          "id": {
            "type": "string",
            "description": "Folder ID"
          },
          "is_root": {
            "type": "boolean",
            "description": "Whether it is a root folder"
          },
          "modified_at": {
            "type": "integer",
            "format": "int64",
            "description": "Last modification timestamp",
            "minimum": 0
          },
          "name": {
            "type": "string",
            "description": "Folder name"
          },
          "parent_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Parent folder ID"
          },
          "path": {
            "type": "string",
            "description": "Path to the folder (relative)"
          },
          "relevance_score": {
            "type": "integer",
            "format": "int32",
            "description": "Relevance score (0-100) computed server-side",
            "minimum": 0
          }
        }
      },
      "SearchResultsDto": {
        "type": "object",
        "description": "\n * Data Transfer Object for search results.\n *\n * This structure encapsulates the results of a search operation, including\n * both files and folders that match the search criteria, along with pagination\n * information and server-computed metadata.",
        "required": [
          "files",
          "folders",
          "limit",
          "offset",
          "has_more",
          "query_time_ms",
          "sort_by"
        ],
        "properties": {
          "files": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchFileResultDto"
            },
            "description": "Files matching the search criteria (enriched with metadata)"
          },
          "folders": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchFolderResultDto"
            },
            "description": "Folders matching the search criteria (enriched with metadata)"
          },
          "has_more": {
            "type": "boolean",
            "description": "Whether there are more results available"
          },
          "limit": {
            "type": "integer",
            "description": "Limit used in the search",
            "minimum": 0
          },
          "offset": {
            "type": "integer",
            "description": "Offset used in the search",
            "minimum": 0
          },
          "query_time_ms": {
            "type": "integer",
            "format": "int64",
            "description": "Query execution time in milliseconds (server-side)",
            "minimum": 0
          },
          "sort_by": {
            "type": "string",
            "description": "Sort order used"
          },
          "total_count": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Total count of matching items (for pagination)",
            "minimum": 0
          }
        }
      },
      "SearchSuggestionItem": {
        "type": "object",
        "description": "Individual search suggestion item",
        "required": [
          "name",
          "item_type",
          "id",
          "path",
          "icon_class",
          "icon_special_class",
          "relevance_score"
        ],
        "properties": {
          "icon_class": {
            "type": "string",
            "description": "CSS icon class"
          },
          "icon_special_class": {
            "type": "string",
            "description": "Extra CSS class for icon styling"
          },
          "id": {
            "type": "string",
            "description": "Item ID for navigation"
          },
          "item_type": {
            "type": "string",
            "description": "Type: \"file\" or \"folder\""
          },
          "name": {
            "type": "string",
            "description": "The suggested name"
          },
          "path": {
            "type": "string",
            "description": "Path for context"
          },
          "relevance_score": {
            "type": "integer",
            "format": "int32",
            "description": "Relevance score",
            "minimum": 0
          }
        }
      },
      "SearchSuggestionsDto": {
        "type": "object",
        "description": "DTO for search suggestion results (quick prefix search)",
        "required": [
          "suggestions",
          "query_time_ms"
        ],
        "properties": {
          "query_time_ms": {
            "type": "integer",
            "format": "int64",
            "description": "Query execution time in milliseconds",
            "minimum": 0
          },
          "suggestions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchSuggestionItem"
            },
            "description": "Suggested file/folder names matching the query prefix"
          }
        }
      },
      "SetupAdminDto": {
        "type": "object",
        "description": "DTO for the one-time initial admin setup endpoint (`/api/setup`).\nAvailable only when the system is not yet initialized (no admin exists).",
        "required": [
          "username",
          "email",
          "password"
        ],
        "properties": {
          "email": {
            "type": "string"
          },
          "password": {
            "type": "string"
          },
          "username": {
            "type": "string"
          }
        }
      },
      "ShareDto": {
        "type": "object",
        "required": [
          "id",
          "item_id",
          "item_type",
          "token",
          "url",
          "has_password",
          "permissions",
          "created_at",
          "created_by",
          "access_count"
        ],
        "properties": {
          "access_count": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "created_at": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "created_by": {
            "type": "string"
          },
          "expires_at": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "minimum": 0
          },
          "has_password": {
            "type": "boolean"
          },
          "id": {
            "type": "string"
          },
          "item_id": {
            "type": "string"
          },
          "item_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "item_type": {
            "type": "string"
          },
          "permissions": {
            "$ref": "#/components/schemas/SharePermissionsDto"
          },
          "token": {
            "type": "string"
          },
          "url": {
            "type": "string"
          }
        }
      },
      "SharePermissionsDto": {
        "type": "object",
        "required": [
          "read",
          "write",
          "reshare"
        ],
        "properties": {
          "read": {
            "type": "boolean"
          },
          "reshare": {
            "type": "boolean"
          },
          "write": {
            "type": "boolean"
          }
        }
      },
      "TrashedItemDto": {
        "type": "object",
        "description": "DTO representing an item in the trash",
        "required": [
          "id",
          "original_id",
          "item_type",
          "name",
          "original_path",
          "trashed_at",
          "days_until_deletion",
          "category",
          "icon_class",
          "icon_special_class"
        ],
        "properties": {
          "category": {
            "type": "string",
            "description": "Human-readable category (e.g., \"Image\", \"Folder\", \"Document\")"
          },
          "days_until_deletion": {
            "type": "integer",
            "format": "int64"
          },
          "icon_class": {
            "type": "string",
            "description": "FontAwesome icon class for the file type"
          },
          "icon_special_class": {
            "type": "string",
            "description": "Special CSS class for icon styling (e.g., \"image-icon\", \"pdf-icon\")"
          },
          "id": {
            "type": "string"
          },
          "item_type": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "original_id": {
            "type": "string"
          },
          "original_path": {
            "type": "string"
          },
          "trashed_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "UpdateShareDto": {
        "type": "object",
        "properties": {
          "expires_at": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "minimum": 0
          },
          "password": {
            "type": [
              "string",
              "null"
            ]
          },
          "permissions": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/SharePermissionsDto"
              }
            ]
          }
        }
      },
      "UserDto": {
        "type": "object",
        "required": [
          "id",
          "username",
          "email",
          "role",
          "storage_quota_bytes",
          "storage_used_bytes",
          "created_at",
          "updated_at",
          "active",
          "auth_provider"
        ],
        "properties": {
          "active": {
            "type": "boolean"
          },
          "auth_provider": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "email": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "last_login_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "role": {
            "type": "string"
          },
          "storage_quota_bytes": {
            "type": "integer",
            "format": "int64"
          },
          "storage_used_bytes": {
            "type": "integer",
            "format": "int64"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "username": {
            "type": "string"
          }
        }
      },
      "VerifyPasswordRequest": {
        "type": "object",
        "required": [
          "password"
        ],
        "properties": {
          "password": {
            "type": "string"
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "folders",
      "description": "Folder management endpoints"
    },
    {
      "name": "files",
      "description": "File management endpoints"
    },
    {
      "name": "trash",
      "description": "Trash / recycle bin endpoints"
    },
    {
      "name": "search",
      "description": "Search endpoints"
    },
    {
      "name": "shares",
      "description": "Shared links endpoints"
    },
    {
      "name": "favorites",
      "description": "Favorites management endpoints"
    },
    {
      "name": "recent",
      "description": "Recent items endpoints"
    }
  ]
}