Linux File & Folder Monitoring APIs

APIs for real-time Linux file/folder monitoring and permission checks.

Authentication

All endpoints require a valid Bearer token obtained from the /token endpoint.

Headers (required for all requests):

Authorization: Bearer {{token}}
Content-Type: application/json

1. File Action Monitoring API

Capture real-time file and folder events (Create, Modify, Delete)

Endpoint: GET {{base_url}}/base/fileAction

Query Parameters:

Parameter	Type	Required	Description
path	string	Yes	Absolute path of the file or folder to monitor

Example Request:

GET {{base_url}}/base/fileAction?path=/home/hiteshkumar/Documents/reports
Authorization: Bearer {{token}}

Success Response (200 OK):

[
  {
    "time": "2025-11-24T18:04:31.933000",
    "action": "CREATE",
    "path": "/home/hiteshkumar/Documents/reports/budget.xlsx",
    "user": "hiteshkumar"
  },
  {
    "time": "2025-11-24T18:15:22.104000",
    "action": "MODIFY",
    "path": "/home/hiteshkumar/Documents/reports/budget.xlsx",
    "user": "hiteshkumar"
  },
  {
    "time": "2025-11-24T19:02:11.567000",
    "action": "DELETE",
    "path": "/home/hiteshkumar/Desktop/old_backup.zip",
    "user": "hiteshkumar"
  }
]

Possible Action Values:

CREATE → New file or directory created
MODIFY → File content or metadata changed
DELETE → File or directory removed

Error Response (404 Not Found):

{
  "detail": "No events found"
}

2. File Permission API

Retrieve complete permission and ownership details

Endpoint: GET {{base_url}}/base/filePermissions

Query Parameters:

Parameter	Type	Required	Description
path	string	Yes	Absolute path of the file or folder to inspect

Example Request:

GET {{base_url}}/base/filePermissions?path=/home/hiteshkumar/shared/project_data
Authorization: Bearer {{token}}

Success Response (200 OK):

{
  "path": "/home/hiteshkumar/shared/project_data",
  "type": "directory",
  "owner": "hiteshkumar",
  "group": "developers",
  "permissions": {
    "owner": {
      "read": true,
      "write": true,
      "execute": true
    },
    "group": {
      "read": true,
      "write": true,
      "execute": false
    },
    "others": {
      "read": true,
      "write": false,
      "execute": false
    }
  },
  "users_with_access": [
    "hiteshkumar",
    "alice",
    "bob"
  ],
  "groups_with_access": {
    "developers": [
      "alice",
      "bob",
      "hiteshkumar"
    ]
  },
  "everyone_can_access": false
}

Response Fields Explanation:

Field	Description
type	"file" or "directory"
owner / group	System user and primary group owning the object
permissions	Boolean flags for read/write/execute per owner/group/others
users_with_access	List of individual users who have explicit access
groups_with_access	Groups and their members that grant access
everyone_can_access	true if "others" have any permission (world-readable etc.)

Error Response (404 Not Found):

{
  "detail": "Path does not exist."
}