TizonaHub

TizonaHub

Authentication

Login

POST /api/auth/login

Authenticates a user and returns a token.

Parameters (form-data):

  • username (string, required)
  • password (string, required)

Response:

  • userToken: JWT token (also stored in cookie)
  • userData: user information (name, username, role, profileImage, createdAt)

Get Authenticated User

GET /api/auth/me

Verifies the userToken cookie and returns the authenticated user's information.

Headers:

  • Cookie: must include userToken

Response (JSON):

{
 "id": "string", 
 "name": "string", 
 "username": "string", 
 "role": number,
 "avatar": { 
  "bgColor": "string", 
  "profileImage": "string | null", 
  "shadowFilter": number 
    }
}

Error Responses:

  • 400: missing or invalid token, or user not found

Logout

GET /api/auth/logout

Clears the userToken cookie and logs out the current user.

Headers:

  • Cookie: must include userToken

Response:

Empty response with status 200.

Users

Create User

POST /api/users

Creates a new user. The first user created will automatically become the administrator.

Parameters (form-data):

  • name (string, required)
  • username (string, required)
  • password (string, required, between 8 and 25 characters)

Response:

  • user: user object (id, name, username, role)
  • userToken: JWT token stored in cookie

Get Users

GET /api/users

Returns a list of users.

Parameters (query):

  • id (optional, string): filter by user ID

Response:

Array of user objects.

Update User

PUT /api/users

Updates the currently authenticated user's data, or another user if you have sufficient permissions.

Parameters (form-data):

  • name (string, optional)
  • username (string, optional)
  • password (string, optional)
  • file (file, optional): new avatar image
  • userId (string, optional): only required when updating another user (admin only)
  • avatar (string, JSON, optional): avatar configuration.
    Example: 
{

 "bgColor": "#800080",

 "profileImage": "./userProfileImages/1744077572.webp",

 "shadowFilter": 0 

}

Response:

Status 200 with empty body if successful. Otherwise:

  • 400: validation errors (array of error objects)
  • 401: invalid or missing token
  • 403: insufficient permissions
  • 500: server error

Delete User

DELETE /api/users/:id

Deletes a specific user (requires elevated role).

Parameters (URL path):

  • :id (string, required): user ID to delete

Response:

  • 200: user deleted successfully
  • 400: missing user ID
  • 401: invalid or missing token
  • 403: insufficient permissions
  • 404: user not found
  • 500: server error

System

Get Server Info

GET /api/system/info

Returns information about the TizonaServer version.

Response (JSON):

{ 

 "version": "1.0.0"


}

Ping Server

GET /api/system/ping

Tests if the server is reachable. Useful for connection checks.

Response:

Status 200 with empty body if successful.

Get System Charts

GET /api/system/charts

Executes a Python script to fetch disk usage data in bytes.

Response (JSON):

Example structure:

{
 "total": 1000203087872,
 "used": 66135257088,
 "free": 934067830784,
 "serverSize": 670 
}

Error Responses:

  • 500: if the Python script fails or throws an error

Resources

Upload Files

POST /api/resources/upload

Uploads one or more files to the server.

Parameters (form-data):

  • files[] (file[], required): files to upload

Response:

Status 200 if successful. Empty response body.

Rename Resource

PATCH /api/resources/rename

Renames a file or directory.

Parameters (query or form-data):

  • source (string, required): original path
  • newName (string, required): new name for the resource

Response:

  • 200: renamed successfully
  • 400: missing parameters
  • 404: access denied or path not found
  • 500: server error

Delete Resource

DELETE /api/resources

Deletes a file or directory.

Parameters (query or form-data):

  • resourceUrl (string, required): path to delete

Response:

  • 200: deleted successfully
  • 400: missing parameters
  • 404: access denied or not found
  • 500: error during deletion

Get Resource Info

GET /api/resources/info

Returns metadata and MIME type for a resource.

Query Parameters:

  • resourcePath (string, required): path of the resource

Response (JSON):

File system stats with an added mimeType field.

Get Directories

GET /api/resources/directories

Returns the contents of a directory. Supports public and private directories.

Query Parameters:

  • directory (string, optional): path to list. Defaults to directories/publicDirectories. To access a private directory, set it to directories/<userId>
  • recursive (boolean, optional): include subdirectories
  • privateDir (boolean, optional): include user's private directory if authenticated

Response:

Array of directory/file objects.

Create Directory

POST /api/resources/directories

Creates a new directory.

Parameters (query or form-data):

  • path (string, required): full path to create

Response:

  • 200: directory created
  • 400: path too long or missing
  • 403: access denied
  • 500: already exists or other error

Move Resource

PATCH /api/resources/move

Moves a file or directory to a new location.

Parameters (query or form-data):

  • source (string, required): current path
  • newLocation (string, required): target destination path

Response:

  • 200: moved successfully
  • 400: missing parameters
  • 404: access denied
  • 500: error moving resource
Previous Getting Started