Documentation

API

Authenticate against the REST API and call the main endpoints for scans, findings, assets, agents and reports.

Basics

The Holistra dashboard is built entirely on a JSON REST API, and the same API is available to your own scripts. It lives under /api on your server, for example https://<your-server>/api/findings. Requests and responses are JSON unless noted.

Every call acts as a user and is limited by that user's role and organisation, exactly as in the dashboard. Changes made through the API appear in the audit log under that user.

Authentication

Sign in with an email and password to get an access token, then send it as a Bearer token. Access tokens last 15 minutes; sign in again when one expires. Long-lived API keys are not available yet, so create a dedicated user for automation with the least privileged role that works (Auditor for read-only reporting).

1. Sign in (form-encoded)

curl -s https://<your-server>/api/auth/login \
  -d "[email protected]" \
  --data-urlencode "password=<password>"

Response

{ "access_token": "eyJhbGciOi...", "token_type": "bearer", ... }

2. Call the API

curl -s https://<your-server>/api/findings?severity=Critical \
  -H "Authorization: Bearer <access_token>"

Accounts with two-factor authentication

If the account has two-factor authentication, the sign-in response is {"mfa_required": true, "mfa_token": "…"} instead. Send the token with a current code to finish:

curl -s https://<your-server>/api/auth/login/mfa \
  -H "Content-Type: application/json" \
  -d '{"mfa_token": "<mfa_token>", "code": "123456"}'

Things to know

Sign-in is rate limited per IP address and failed attempts count towards the account lockout, so reuse a token for its 15 minutes rather than signing in for every call.
Accounts that sign in only through SSO have no usable password, and when your organisation requires SSO, only Admins can use password sign-in.
Bearer requests don't need the X-Aetherion-CSRF header; only the browser's cookie-based sessions do.

Status codes

Code	Meaning
400	The request was invalid, for example a scan target that isn’t allowed. The detail field says why.
401	No token, or it has expired. Sign in again.
403	Your role can’t do this, your password has expired, or two-factor setup is required. On scans, it can also mean the instance has no valid licence.
404	Not found. Records from other organisations also answer 404.
429	Too many sign-in attempts, or the account is locked. Wait and retry.
503	The service is temporarily unavailable. Retry shortly.

Main endpoints

Paths are relative to https://<your-server>/api. “Write” means Admin or Security Engineer.

Scans

Endpoint	Role	Purpose
`POST /scans`	Write	Start a scan (body below)
`GET /scans`	Any	List scans and their status
`GET /scans/{id}`	Any	One scan
`GET /scans/{id}/findings`	Any	The scan’s findings
`DELETE /scans/{id}`	Write	Delete a scan

POST /scans

{
  "target": "https://staging.example.com",
  "name": "Staging web scan",
  "scan_type": "web",
  "options": {}
}

scan_type is one of network, web, owasp, pci_gdpr, cis_linux, cis_windows, host, sca, sast or cspm. Credentialed scans take their credentials in options: ssh_user with ssh_password or ssh_private_key for Linux, and winrm_user, winrm_password and optionally winrm_domain for Windows. CIS Linux scans require SSH credentials.

Findings, assets and reports

Endpoint	Role	Purpose
`GET /findings?severity=&status=&q=`	Any	List findings, filtered by severity (e.g. Critical), status (e.g. New) or text in the title
`GET /findings/{id}`	Any	One finding
`PATCH /findings/{id}`	Write	Change status or severity (triage)
`POST /findings/{id}/retest`	Write	Re-run the check that found it
`GET /assets`	Any	List assets, one row per host
`POST /assets`	Write	Add an asset
`PATCH /assets/{id}`	Write	Edit type, owner or tags
`GET /stats`	Any	Dashboard figures: posture score, counts by severity, KEV, MTTR
`GET /stats/trend`	Any	Findings over time
`GET /reports/{scan_id}/download`	Any	PDF report for a scan
`GET /compliance/overview`	Any	Compliance scores by baseline
`GET /compliance/reports/overview?format=pdf\|csv`	Any	Organisation compliance report

Agents and remediation

Endpoint	Role	Purpose
`GET /agents`	Write	List agents with status, version and posture
`POST /agents/{id}/approve`	Write	Approve a pending agent
`POST /agents/{id}/revoke`	Write	Revoke an agent
`GET /agents/{id}/inventory`	Any	Installed software and OS checks
`GET /agents/{id}/facts`	Any	Hardware, OS, users, network and posture
`POST /remediate/preview`	Write	Which agents a dispatch would reach
`POST /remediate`	Write	Send a script to agents
`GET /remediate/jobs`	Write, Auditor	Recent jobs with status, exit code and output

Administration

Endpoint	Role	Purpose
`GET /auth/me`	Any	The signed-in user
`GET /auth/users`	Admin	List users
`GET /audit-logs`	Admin, Auditor	The audit log
`GET /audit-logs/export`	Admin, Auditor	The audit log as CSV
`GET /audit-logs/verify`	Admin, Auditor	Check the audit log’s integrity
`GET /health`	None	Service health: healthy, degraded or unhealthy

User provisioning from an identity provider uses the separate SCIM 2.0 interface; see Provisioning with SCIM.

The API is evolving. Endpoints listed here are the ones the dashboard relies on, but response fields may be added between releases, so ignore fields you don't recognise.