API Reference

LiMon's web frontend, Admin UI and setup wizard are clients of one REST API. This page covers the access model and the endpoints integrations use most. Every route below lists the permission it needs when sign-in is enabled.

Base URL

Docker deployments expose the API through the bundled proxy, on HTTPS (port 443) and HTTP (port 80):

https://<your-server>/api/...

Package installs serve the API directly from Gunicorn:

http://<your-server>:8585/api/...

Responses and Errors

Every JSON endpoint uses the same envelope:

{ "success": true, "data": { } }
{ "success": false, "error": "Human-readable message" }

Sign-in and setup failures add a stable code field for programmatic handling.

Status	Meaning
400	Invalid input. The error field explains what to fix.
401	No valid credentials: missing or wrong API key, or no session when one is required.
402	The license does not cover this route: no valid key, the wrong tier, or no active subscription.
403	Signed in, but the account's role lacks the required permission.
404	Unknown resource.
429	Too many sign-in attempts. Honour Retry-After.
503	LiMon cannot verify the request right now, for example because the database is unreachable. It never answers with stale or guessed data instead.

Authentication

LiMon accepts two credentials:

• The admin API key, sent as X-API-KEY: <key>. It grants every permission, works in every access mode, needs no CSRF token and works across origins. Use it for scripts and integrations. Retrieve or rotate it with limon-manage show-api-key / limon-manage rotate-api-key, or under Admin → Settings → About. After a rotation the previous key keeps working for 24 hours.
• A browser session, created by POST /api/v1/auth/login. It carries the account's role. Sessions are for the web UI, not for scripts.

When a request carries a valid key, the key wins over any session cookie. An invalid key is rejected with 401; LiMon does not fall back to the cookie.

Access modes

Sign-in is off by default. The mode is chosen under Admin → Access; see Authentication.

Mode	Without credentials
Everyone — no sign-in (default)	Monitoring data and operator actions are open. Administration requires the API key.
Everyone can view — sign in to operate	Anonymous visitors get Viewer permissions. Operator and admin routes need a session or the key.
Signed-in accounts only	Only the public routes below answer. Everything else needs a session or the key.

Permissions

Roles build on each other: an Operator has every Viewer permission, and an Admin account (or the API key) has all of them.

Permission	Viewer	Operator	Admin	Covers
data.read	✓	✓	✓	Monitoring data, interactive report views, ledger status/verify/export
reports.read	✓	✓	✓	Existing PDFs, report status and artifact lookup
live.view		✓	✓	Live View and the Prometheus endpoint
import.run		✓	✓	Log import
reports.generate		✓	✓	Queue PDF generation
reports.schedule		✓	✓	Report schedules and audience delivery
notify.announce		✓	✓	Licence-user announcements
notify.manage			✓	Notification routes and delivery history
admin			✓	Configuration, accounts, catalog, servers, licensing, keys and commands

License entitlements apply on top of permissions: an Admin on Standard still gets 402 from a Professional-only route.

Public routes

These answer without credentials in every mode: /api/health, /api/v1/health/tasks*, and the /api/v1/auth/* sign-in routes. To limit who can read them, restrict the paths at your reverse proxy.

Browser sessions and CSRF

Session cookies are same-origin, HttpOnly, SameSite=Lax and Secure over HTTPS. A request that changes data using a session must send the X-CSRF-Token header (the token is returned by GET /api/v1/auth/status) and a same-origin Origin header. Requests authenticated with the API key need neither.

Health and Monitoring Checks

Method	Endpoint	Access	Description
GET	/api/health	Public	API process health, including the configuration revision this worker applied.
GET	/api/v1/health/tasks	Public	Status of every background task: license polling, directory sync, daily maintenance, report scheduling, report generation, email delivery and webhook delivery.
GET	/api/v1/health/tasks/{task}	Public	One task, so each check can be exposed or blocked by path. task is one of license-polling, directory-sync, daily-maintenance, report-scheduling, report-generation, email-delivery, webhook-delivery.

The task endpoints report status (ok, running, overdue, failed, unknown, disabled), last activity, age and, for queues, 24-hour counts. They never include error text; the reasons are in the Admin UI's Background activity panel.

LiMon ships a Nagios/Icinga plugin, check_limon_health.py, that reads these endpoints from your monitoring server. You will find it at /opt/limon/src/bin/ on package installs, and in the Docker bundle (installed next to docker-compose.yml). It needs only Python 3.6 or later.

check_limon_health.py --url https://limon.example.com --task license-polling
check_limon_health.py --url https://limon.example.com --task all -k

Task status	Exit code
ok, running	0 OK
overdue	1 WARNING
failed, or LiMon cannot read its database	2 CRITICAL
unknown, disabled, or LiMon unreachable	3 UNKNOWN

--task all reports the worst state of every enabled task. Use -k to accept the Docker appliance's self-signed certificate.

Monitoring Data

All routes in this section need data.read.

Method	Endpoint	Description
GET	/api/v1/dashboard/metrics	Dashboard KPIs as JSON (not Prometheus text).
GET	/api/v1/servers	Servers with status, inventory health and summary metrics.
GET	/api/v1/servers/{id}	Server detail: features, feature groups and active sessions.
GET	/api/v1/servers/{id}/history	License inventory change history.
GET	/api/v1/servers/{id}/uptime	Availability timeline.
GET	/api/v1/applications	Application rollups.
GET	/api/v1/applications/{id}	Application detail and deployments.
GET	/api/v1/applications/{id}/usage_history	Usage over time.
GET	/api/v1/applications/{id}/top_users	Heaviest users.
GET	/api/v1/applications/{id}/sessions	Sessions for the application.
GET	/api/v1/applications/{id}/feature-analytics	Per-feature usage analytics.
GET	/api/v1/applications/{id}/feature-coverage	Which features are mapped and observed.
GET	/api/v1/applications/{id}/unused-features	Features with no observed use.
GET	/api/v1/sites	Site rollups.
GET	/api/v1/sites/{id}	Site detail.
GET	/api/v1/users	License users, enriched when directory sync is enabled.
GET	/api/v1/users/{username}	One user's detail.
GET	/api/v1/users/{username}/activity	One user's activity.
GET	/api/v1/departments	Department rollups. Pro Sub
GET	/api/v1/departments/{name}/users	Users in a department. Pro Sub
GET	/api/v1/departments/{name}/activity	Department activity. Pro Sub
GET	/api/v1/sessions	Active or archived sessions, with filters.
GET	/api/v1/usage	Usage summaries grouped by feature, user, server or day.
GET	/api/v1/denials	Denial analysis from imported logs, including confirmed and potential cost of delay.
GET	/api/v1/licenses/search	Estate-wide license and feature search.
GET	/api/v1/expirations	Licenses expiring within a look-ahead window.
GET	/api/v1/expirations/scorecard	Renewal scorecard. Sub

System

Method	Endpoint	Access	Description
GET	/api/v1/system/capabilities	data.read	License tier, subscription state and enabled features.
GET	/api/v1/system/enrichment-summary	data.read	Directory enrichment status.
GET	/api/v1/system/schema-version	admin	Database schema version.
GET	/api/v1/system/installation-id	admin	Installation ID used to bind license keys.

Live View and Prometheus

Both routes need live.view.

Method	Endpoint	Description
GET	/api/v1/output/dashboard	Live View: the monitor's generated dashboard.
GET	/api/v1/output/prometheus	Prometheus text exposition of the monitor's operational metrics.

scrape_configs:
  - job_name: "limon"
    metrics_path: /api/v1/output/prometheus
    scheme: https
    static_configs:
      - targets:
          - limon.example.internal

With sign-in off, the endpoint is open. With sign-in on, anonymous visitors lack live.view, so the scraper must send the API key as X-API-KEY, or a reverse proxy in front of LiMon must add it. /api/v1/output/prometheus carries LiMon's own operational metrics, such as poll timings and command counters. For license KPIs, use /api/v1/dashboard/metrics.

Reports Sub

Method	Endpoint	Access	Description
GET	/api/v1/reports/view/estate	data.read	Estate report data.
GET	/api/v1/reports/view/app	data.read	Application report data.
GET	/api/v1/reports/view/site	data.read	Site report data.
GET	/api/v1/reports/view/money	data.read	Savings report data.
GET	/api/v1/reports/view/audit	data.read	Audit defense report data.
GET	/api/v1/reports/view/chargeback	data.read	Chargeback report data. Pro
GET	/api/v1/reports/chargeback	data.read	Chargeback CSV export. Pro
POST	/api/v1/reports/generate	reports.generate	Queue a PDF report. Returns a job ID; returns 429 when the queue is full.
GET	/api/v1/reports/status/{id}	reports.read	Report job status.
GET	/api/v1/reports/artifact	reports.read	Find an existing PDF for the same report and parameters.
GET	/api/v1/reports/list	reports.read	Generated reports.
GET	/api/v1/reports/download/{file}	reports.read	Download a PDF.
GET / POST	/api/v1/reports/schedules	reports.schedule	List or create recurring schedules.
PUT / DELETE	/api/v1/reports/schedules/{id}	reports.schedule	Update or delete a schedule.
POST	/api/v1/reports/schedules/{id}/run-now	reports.schedule	Run a schedule now.

Log Import

All routes need import.run.

Method	Endpoint	Description
POST	/api/v1/log-import/start	Upload vendor log files for asynchronous import.
GET	/api/v1/log-import/status/{id}	Import progress.
GET	/api/v1/log-import/history	Recent imports.
GET	/api/v1/log-import/timezone-info	Time zone used to interpret log timestamps.
GET	/api/v1/log-import/seat-counting	Seat-counting rule per server.

Notifications

See Notifications for how events, routes and recipients fit together.

Method	Endpoint	Access	Description
GET	/api/v1/notifications/catalogue	data.read	Notification events and the permission each needs.
GET	/api/v1/notifications/impact	data.read	Who an event would reach.
GET / POST	/api/v1/notifications/routes	notify.manage	List or create routes.
PUT / DELETE	/api/v1/notifications/routes/{id}	notify.manage	Update or delete a route.
GET	/api/v1/notifications/history	notify.manage	Email delivery history.
GET	/api/v1/notifications/recipients	reports.schedule	Recipients a route or schedule can address.
GET	/api/v1/notifications/audience	reports.schedule	Recent license users for an announcement.
GET	/api/v1/notifications/audience.csv	reports.schedule	The same audience as CSV.
POST	/api/v1/notifications/audience/email	reports.schedule	Email the audience list to LiMon accounts.
POST	/api/v1/notifications/announcements/preview	notify.announce	Preview an announcement and its recipient count. Requires directory sync. Pro Sub
POST	/api/v1/notifications/announcements	notify.announce	Send a previewed announcement. Pro Sub

Sign-In and Account

Method	Endpoint	Access	Description
GET	/api/v1/auth/status	Public	Access mode, current principal and permissions, and the CSRF token.
POST	/api/v1/auth/login	Public	Sign in with username, password and optionally provider (local or ldap) and remember_browser.
POST	/api/v1/auth/logout	Public	End the current session.
POST	/api/v1/auth/password	Public	Change your own password (current_password, new_password).
GET / POST	/api/v1/account/preferences	data.read	Your language and start page.
GET / PUT	/api/v1/account/notifications	data.read	What you receive, with opt-outs.

Configuration

All routes need admin.

Method	Endpoint	Description
GET / PUT	/api/v1/config/monitoring	Polling interval, retention and thresholds.
GET / PUT	/api/v1/config/tools	Vendor tool paths.
POST	/api/v1/config/tools/validate	Validate a vendor utility binary.
GET / PUT	/api/v1/config/smtp	SMTP settings.
POST	/api/v1/config/smtp/test	Send a test email.
GET / PUT	/api/v1/config/directory	Directory (AD/LDAP) connection. Pro
POST	/api/v1/config/directory/test	Test the directory connection. Pro
GET / PUT	/api/v1/config/auth	Access mode, account source and sign-in policy.
POST	/api/v1/config/auth/test	Validate a policy, including a test directory sign-in.
GET / PUT	/api/v1/config/feature-ignore	Feature ignore lists.
GET / PUT	/api/v1/config/reports	Report branding, output and defaults.
GET / PUT	/api/v1/config/privacy	Privacy and anonymization.
GET / PUT	/api/v1/config/compliance-ledger	Compliance Ledger settings. Pro
GET	/api/v1/config/system	Company and license details.
GET	/api/v1/config/about	Installation ID, schema and runtime metadata.
GET	/api/v1/config/timezones	IANA time zones.
GET	/api/v1/config/countries	Country list for sites.
POST	/api/v1/config/export	Export configuration as YAML.
POST	/api/v1/config/import	Import YAML configuration.

Administration

All routes need admin. Collections also have item routes (GET / PUT / DELETE …/{id}) and helper routes the Admin UI uses, which are not listed here.

Method	Endpoint	Description
GET	/api/v1/admin/stats	Admin dashboard counts.
GET	/api/v1/admin/background-activity	Background task health with failure detail (the Admin UI panel).
GET	/api/v1/admin/enrichment-status	Directory enrichment state.
GET / POST	/api/v1/admin/license	License status, or activate a key.
GET	/api/v1/admin/license-history	License inventory change log.
GET	/api/v1/admin/api-key	API key status.
POST	/api/v1/admin/api-key/rotate	Rotate the API key.
DELETE	/api/v1/admin/api-key/previous	End the 24-hour overlap of the previous key.
GET / POST	/api/v1/admin/auth/users	List or create web accounts.
PATCH	/api/v1/admin/auth/users/{id}	Edit, disable or reset an account.
POST	/api/v1/admin/auth/users/{id}/revoke	End every session of an account.
GET / POST	/api/v1/admin/servers	List or create monitored servers.
GET / PUT / DELETE	/api/v1/admin/servers/{id}	Read, update or delete a server.
POST	/api/v1/admin/servers/batch	Create servers in bulk.
POST	/api/v1/admin/servers/{id}/test	Poll a server once with its current settings.
POST	/api/v1/admin/servers/{id}/decommission	Stop polling while keeping history.
POST	/api/v1/admin/servers/{id}/reactivate	Resume a decommissioned server.
POST	/api/v1/admin/servers/{id}/replace	Retire a server and create a new identity for its replacement endpoint; returns the deployments to review.
GET / POST	/api/v1/admin/applications	List or create applications.
GET / PUT / DELETE	/api/v1/admin/applications/{id}	Read, update or delete an application.
GET	/api/v1/admin/applications/templates	Application templates from the vendor library.
PUT	/api/v1/admin/applications/{id}/keystone	Set the feature that measures an application's capacity.
GET / POST	/api/v1/admin/deployments	Link applications to servers.
GET / POST	/api/v1/admin/sites	List or create sites.
GET / POST	/api/v1/admin/feature-mappings	Feature display names and costs.
GET	/api/v1/admin/feature-mappings/export	Export feature mappings as CSV.
POST	/api/v1/admin/feature-mappings/import	Import feature mappings from CSV.
GET / POST	/api/v1/admin/webhooks	Manage webhooks. Pro
GET / POST	/api/v1/admin/webhooks/rules	Webhook alert rules. Pro
GET	/api/v1/admin/commands	Commands the monitor can run on demand.
POST	/api/v1/admin/command/{name}	Run a monitor command, such as a forced poll.

Compliance Ledger Pro Sub

See Compliance Ledger for sealing setup, interpreting results, independent verification and external checkpoints.

Method	Endpoint	Access	Description
GET	/api/v1/system/compliance-ledger/status	data.read	Sealing status and ledger health.
GET	/api/v1/system/compliance-ledger/verify	data.read	Verify the hash chain and signatures.
GET	/api/v1/system/compliance-ledger/export	data.read	Export a verification bundle.
GET	/api/v1/system/compliance-ledger/checkpoint	admin	Current checkpoint for external anchoring.
POST	/api/v1/system/compliance-ledger/checkpoint-receipt	admin	Record an external checkpoint receipt.
POST	/api/v1/system/compliance-ledger/corrections	admin	Record a signed correction.
POST	/api/v1/system/compliance-ledger/rotate-key	admin	Rotate the ledger signing key.

Setup Wizard

The wizard API exists only until setup completes. Every route except status and session requires the setup session that the installer's one-time setup code unlocks: POST /api/v1/wizard/session with {"code": "..."}.

Method	Endpoint	Description
GET	/api/v1/wizard/status	Whether setup is complete.
POST	/api/v1/wizard/session	Exchange the setup code for the setup session.
GET	/api/v1/wizard/defaults	Shipped defaults and detected values.
GET	/api/v1/wizard/timezones	IANA time zones.
GET / POST	/api/v1/wizard/state	Read or save wizard progress.
POST	/api/v1/wizard/test-db	Test database settings.
POST	/api/v1/wizard/run-migrations	Create the database schema.
POST	/api/v1/wizard/generate-secrets	Generate the API key and secrets.
POST	/api/v1/wizard/test-tool	Validate a vendor tool path.
POST	/api/v1/wizard/test-server	Poll a candidate license server.
POST	/api/v1/wizard/import-servers	Import servers from a file.
POST	/api/v1/wizard/test-smtp	Send a test email.
POST	/api/v1/wizard/prepare-activation	Prepare the installation identity for license activation.
POST	/api/v1/wizard/finalize	Save the configuration and leave setup mode.