Reference

JSON API¶

Every dashboard interaction is built on a small set of JSON endpoints. They're not a separate "public" API — the dashboard uses them directly — but they're stable and documented here so you can script against them.

Authentication¶

The API uses the same Flask-Login session cookie as the dashboard. To call it from a script:

POST credentials to /login and capture the session cookie.
Include the cookie on subsequent requests.

There is no separate API key today. If you need automated access, create a service-account user with the Viewer role and use its session cookie.

Roles and access¶

Decorator	Allowed roles
`login_required`	Admin, Auditor, Viewer (any logged-in user)
`export_allowed`	Admin, Auditor (not Viewer)
`admin_required`	Admin only

Each endpoint below notes which decorator applies.

Logs¶

`GET /api/logs`¶

Query syslog entries with filters and pagination. Any logged-in user.

Parameter	Type	Default	Notes
`host`	string	—	Exact match
`severity`	string	—	One of Emergency / Alert / Critical / ...
`keyword`	string	—	FTS prefix match against `message`
`start_date`	string	—	`YYYY-MM-DDTHH:MM` or `YYYY-MM-DD HH:MM:SS`
`end_date`	string	—	Same format
`sort_column`	string	timestamp	timestamp / host / severity / message
`sort_direction`	string	desc	asc / desc
`page`	int	1	Offset-based pagination
`page_size`	int	150	Max 1000
`cursor_id`	int	—	Cursor-based pagination (constant-time)

Response:

{
  "logs": [
    {
      "id": 12345,
      "timestamp": "2026-05-26 13:00:00",
      "host": "10.27.50.16",
      "severity": "Error",
      "message": "..."
    }
  ],
  "page": 1,
  "page_size": 150,
  "total": 412,
  "total_pages": 3,
  "next_cursor": 12340
}

For deep pagination, prefer cursor_id — pass the last id from the previous response. It stays constant-time at any depth.

`GET /api/stats`¶

Quick stats for live refresh. Any logged-in user.

{
  "total": 9217843,
  "severity_counts": {
    "Emergency": 0,
    "Alert": 0,
    "Critical": 12,
    "Error": 4831,
    "Warning": 218400,
    "Notice": 18,
    "Informational": 8994577,
    "Debug": 1
  },
  "hosts": ["10.27.50.16", "10.27.50.17", "..."]
}

Charts¶

All chart endpoints are any logged-in user.

`GET /api/charts/volume`¶

Param	Default	Notes
`hours`	24	Max 168
`host`	—	Filter by hostname

Returns hourly log counts.

`GET /api/charts/top-hosts`¶

Param	Default	Notes
`limit`	10	Max 20

Returns hosts sorted by log count, descending.

`GET /api/charts/severity-timeline`¶

Param	Default	Notes
`hours`	24	Max 168

Returns severity counts per hour.

Export¶

`GET /export/csv`, `GET /export/json`¶

Admin or Auditor only. Accept the same filters as /api/logs. Capped at 10,000 rows per call.

Settings¶

These endpoints save settings via AJAX without requiring a service restart. Admin only.

Endpoint	Body
`POST /api/settings/email`	SMTP host/port/user/password/etc.
`POST /api/settings/notifications`	Severity/login rules, cooldown
`POST /api/settings/database`	Retention days, archive enabled

`GET /api/retention-preview?days=N`¶

Returns how many logs would be deleted at the new retention threshold.

{ "delete_count": 124983, "total_count": 9217843 }

TLS / HTTPS certificate management¶

Admin only.

Endpoint	Notes
`POST /api/tls-cert`	Upload PEM or set `path_only` to share a path
`POST /api/tls-cert-delete`	Delete a cert/key file from disk
`POST /api/tls-generate`	Generate self-signed cert for TLS syslog

The type field selects which slot: cert / key for TLS syslog, https_cert / https_key for the web dashboard.

License¶

Endpoint	Allowed
`POST /api/license/activate`	Admin
`POST /api/license/deactivate`	Admin
`GET /api/license/status`	Any logged-in user
`POST /api/license/recheck`	Admin

Status response:

{
  "licensed": true,
  "status": "active",
  "message": "License active.",
  "last_validated": "2026-05-19T13:00:00",
  "days_left": null,
  "needs_recheck": false
}

Users¶

Admin only for everything except your own profile.

Endpoint	Notes
`GET /api/users`	List all users
`POST /api/users`	Create a user
`PUT /api/users/<id>`	Update fields
`POST /api/users/<id>/reset-password`	Set new password + force change
`DELETE /api/users/<id>`	Delete user

Archives¶

Admin or Auditor for downloads; Admin only for run/delete.

Endpoint	Notes
`GET /api/archives`	List archive files
`POST /api/archives/run`	Manually trigger archival
`GET /archives/download/<filename>`	Download an archive
`DELETE /api/archives/<filename>`	Delete an archive

Maintenance¶

Admin only.

Endpoint	Notes
`POST /api/maintenance/vacuum`	Run VACUUM; returns MB reclaimed
`POST /api/maintenance/analyze`	Run ANALYZE
`POST /api/maintenance/rebuild-stats`	Rebuild the dashboard stats cache

Update check¶

`GET /api/check-update`¶

Any logged-in user. Force a check against https://lucedev.com/api/version/syslog and return the result.

{
  "update_available": true,
  "current_version": "1.0.3",
  "latest_version": "1.3.0",
  "download_url": "https://lucedev.com/products/lucedev-syslog",
  "release_notes": "..."
}

The server also runs this check silently once per day in the background for admin users; results are cached in memory for 24 hours.

Service restart¶

`POST /restart-server`¶

Admin only. Triggers a service restart. Linux uses systemctl; Windows schedules a Task Scheduler one-shot. Returns immediately with {"success": true}; the dashboard polls until the service is reachable again.

Errors¶

All endpoints return JSON errors with at minimum a success: false and a message or error field:

{ "success": false, "error": "License key is required." }

License-blocked endpoints return HTTP 403 with:

{ "error": "License required", "message": "..." }