Skip to main content

🧠 API Reference

RESTful API for authentication, parent settings, URL scanning, logging, dataset review, and periodic model training.

1. Authentication​

POST /api/auth/register​

Register a new user (Parent by default).

Request Body​

{
  "email": "parent@example.com",
  "password": "StrongPassword123!",
  "fullName": "John Doe"
}

Response​

{
  "id": 12,
  "email": "parent@example.com",
  "role": "Parent"
}

Status Codes

  • 201 Created
  • 400 Bad Request
  • 409 Conflict

POST /api/auth/login​

Authenticate user and return JWT token.

Request Body​

{
  "email": "parent@example.com",
  "password": "StrongPassword123!"
}

Response​

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "role": "Parent"
}

Status Codes

  • 200 OK
  • 401 Unauthorized

All protected endpoints require the HTTP header below:

Authorization: Bearer YOUR_JWT_TOKEN

2. Parent Endpoints​

GET /api/settings​

Retrieve parent protection settings.

Response​

{
  "mode": "Balanced",
  "whitelist": ["google.com"],
  "blacklist": ["example-bad.com"],
  "isProtectionEnabled": true
}

PUT /api/settings​

Update protection settings.

Request Body​

{
  "mode": "Strict",
  "whitelist": ["school.edu"],
  "blacklist": [],
  "isProtectionEnabled": true
}

3. Scan Endpoint​

POST /api/scan​

Used by Web Dashboard or Extension to evaluate a URL.

Request Body​

{
  "url": "http://suspicious-site.com",
  "source": "Extension"
}

Response​

{
  "label": "Phishing",
  "score": 0.92,
  "decision": "Block",
  "explanation": {
    "topFeatures": ["contains-ip", "long-url", "suspicious-tld"]
  }
}

4. Logs​

GET /api/logs?page=1&pageSize=10​

Retrieve paginated browsing logs.

Response​

{
  "total": 125,
  "page": 1,
  "pageSize": 10,
  "data": [
    {
      "url": "example.com",
      "label": "Benign",
      "decision": "Allow",
      "score": 0.12,
      "timestamp": "2026-02-26T10:12:00Z"
    }
  ]
}

5. Admin Endpoints (Role: Admin)​

Dataset Review​

GET /api/dataset?status=Pending|Approved|Rejected

Retrieve dataset entries by status.

POST /api/dataset/{id}/approve​

POST /api/dataset/{id}/reject​

GET /api/dataset/export?status=Approved​

Export dataset to CSV.

6. Training (Periodic)​

POST /api/train/trigger​

Trigger periodic training job.

Response​

{
  "jobId": "train_20260226_01",
  "status": "Running"
}

GET /api/train/jobs​

List training jobs history.

Response​

[
  {
    "jobId": "train_20260226_01",
    "status": "Completed",
    "startedAt": "2026-02-26T10:00:00Z",
    "completedAt": "2026-02-26T10:05:00Z",
    "metrics": {
      "accuracy": 0.94,
      "precision": 0.91,
      "recall": 0.89,
      "f1": 0.9
    }
  }
]

7. Role-Based Access​

Endpoint GroupParentAdmin
AuthYesYes
SettingsYesNo
ScanYesYes
LogsYesNo
DatasetNoYes
TrainingNoYes

8. Standard HTTP Status Codes​

  • 200 OK
  • 201 Created
  • 400 Bad Request
  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found
  • 409 Conflict
  • 500 Internal Server Error