Documentation menu

Docs

Alerts

Read and resolve port-exposure alerts ("security issues").

Read and resolve port-exposure alerts ("security issues"). These endpoints power the client-area alert pages: pass whmcs_customer_id to scope results to one customer. An alert is raised for every open port that is not covered by an Allowed Ports rule, and auto-resolves when the port closes.

Error responses in this group carry the HTTP status as error.code (a number) and a human-readable error.message, rather than the string codes used by the provisioning group.

List alerts

GET/api/v1/alerts
Auth: Bearer API keyRate limit: 60 requests / minute per API key

List port-exposure alerts, newest first. Filter by customer, endpoint, status or severity. Results are windowed with limit/offset; has_more tells you when to page again.

Query parameters

NameTypeRequiredNotes
whmcs_customer_idintegerOptionalLimit results to one customer's endpoints.
statusstringOptionalFilter by alert status.one of: open, acknowledged, resolved, false_positive
severitystringOptionalFilter by severity.one of: critical, high, medium, low
endpoint_iduuidOptionalLimit results to a single endpoint.
limitintegerOptionalPage size (default 20, max 100).min:1 · max:100
offsetintegerOptionalNumber of results to skip.min:0
sortstringOptionalSort column.one of: created_at, severity, last_detected_at
orderstringOptionalSort direction.one of: asc, desc
Example request
curl -X GET 'https://portal.example.com/api/v1/alerts?whmcs_customer_id=1042&status=open&severity=critical&endpoint_id=9f2c1e4a-5b6d-4e7f-8a9b-0c1d2e3f4a5b&limit=20&offset=0&sort=created_at&order=desc' \
  -H 'Authorization: Bearer $AEGIS_API_KEY'
Response: 200
{
  "success": true,
  "data": {
    "alerts": [
      {
        "id": "4d3c2b1a-0f9e-4d8c-7b6a-5f4e3d2c1b0a",
        "endpoint_id": "9f2c1e4a-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
        "ip_address": "203.0.113.10",
        "port": 3306,
        "protocol": "tcp",
        "service": "mysql",
        "severity": "critical",
        "status": "open",
        "risk_level": "critical",
        "title": "Database port 3306 (mysql) exposed",
        "explanation": "MySQL is reachable from the public internet…",
        "created_at": "2026-07-12T08:15:00+00:00",
        "first_detected_at": "2026-07-12T08:15:00+00:00",
        "last_detected_at": "2026-07-12T09:15:00+00:00"
      }
    ],
    "total": 1,
    "has_more": false
  },
  "meta": {
    "version": "v1",
    "timestamp": "2026-07-12T09:30:00+00:00"
  }
}

Alert counts by severity

GET/api/v1/alerts/summary
Auth: Bearer API keyRate limit: 60 requests / minute per API key

Open-alert counts for one customer, broken down by severity: the numbers behind a dashboard's severity tiles.

Query parameters

NameTypeRequiredNotes
whmcs_customer_idintegerRequiredThe customer to summarize.
statusstringOptionalStatus to count (defaults to open).one of: open, acknowledged, resolved, false_positive
Example request
curl -X GET 'https://portal.example.com/api/v1/alerts/summary?whmcs_customer_id=1042&status=open' \
  -H 'Authorization: Bearer $AEGIS_API_KEY'
Response: 200
{
  "success": true,
  "data": {
    "critical": 1,
    "high": 2,
    "medium": 0,
    "low": 3,
    "total": 6
  },
  "meta": {
    "version": "v1",
    "timestamp": "2026-07-12T09:30:00+00:00"
  }
}

Alert counts per endpoint

GET/api/v1/alerts/endpoint-summary
Auth: Bearer API keyRate limit: 60 requests / minute per API key

Open-alert counts for each of a customer's endpoints, plus an overall total, used to render a per-server issue overview.

Query parameters

NameTypeRequiredNotes
whmcs_customer_idintegerRequiredThe customer to summarize.
Example request
curl -X GET 'https://portal.example.com/api/v1/alerts/endpoint-summary?whmcs_customer_id=1042' \
  -H 'Authorization: Bearer $AEGIS_API_KEY'
Response: 200
{
  "success": true,
  "data": {
    "endpoints": [
      {
        "endpoint_id": "9f2c1e4a-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
        "ip_address": "203.0.113.10",
        "nickname": "Web server",
        "total_open": 3,
        "critical": 1,
        "high": 1,
        "medium": 0,
        "low": 1
      }
    ],
    "totals": {
      "port_alerts_open": 3
    }
  },
  "meta": {
    "version": "v1",
    "timestamp": "2026-07-12T09:30:00+00:00"
  }
}

Get an alert

GET/api/v1/alerts/{id}
Auth: Bearer API keyRate limit: 60 requests / minute per API key

Fetch one alert with its full explanation. Pass whmcs_customer_id when acting on a customer's behalf. The call is refused if the alert's endpoint does not belong to that customer.

Query parameters

NameTypeRequiredNotes
whmcs_customer_idintegerOptionalCustomer making the request, for ownership checks.
Example request
curl -X GET 'https://portal.example.com/api/v1/alerts/4d3c2b1a-0f9e-4d8c-7b6a-5f4e3d2c1b0a?whmcs_customer_id=1042' \
  -H 'Authorization: Bearer $AEGIS_API_KEY'
Response: 200
{
  "success": true,
  "data": {
    "alert": {
      "id": "4d3c2b1a-0f9e-4d8c-7b6a-5f4e3d2c1b0a",
      "endpoint_id": "9f2c1e4a-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
      "ip_address": "203.0.113.10",
      "port": 3306,
      "protocol": "tcp",
      "service": "mysql",
      "severity": "critical",
      "status": "open",
      "risk_level": "critical",
      "title": "Database port 3306 (mysql) exposed",
      "explanation": "MySQL is reachable from the public internet…",
      "created_at": "2026-07-12T08:15:00+00:00",
      "first_detected_at": "2026-07-12T08:15:00+00:00",
      "last_detected_at": "2026-07-12T09:15:00+00:00"
    }
  },
  "meta": {
    "version": "v1",
    "timestamp": "2026-07-12T09:30:00+00:00"
  }
}

Errors

CodeStatusMeaning
404404Alert not found in your account.
403403Access denied: the alert's endpoint does not belong to the given customer.

Get remediation commands

GET/api/v1/alerts/{id}/remediation
Auth: Bearer API keyRate limit: 60 requests / minute per API key

Ready-to-run commands that close the alerted port, for a chosen firewall platform. platform_options lists everything available; omit platform to get the default suggestion.

  • warning is set when closing the port could lock you out (for example SSH). Surface it to the user before they run the commands.

Query parameters

NameTypeRequiredNotes
platformstringOptionalFirewall platform to generate commands for.one of: ufw, iptables, aws_sg, gcp_fw, azure_nsg, generic
whmcs_customer_idintegerOptionalCustomer making the request, for ownership checks.
Example request
curl -X GET 'https://portal.example.com/api/v1/alerts/4d3c2b1a-0f9e-4d8c-7b6a-5f4e3d2c1b0a/remediation?platform=ufw&whmcs_customer_id=1042' \
  -H 'Authorization: Bearer $AEGIS_API_KEY'
Response: 200
{
  "success": true,
  "data": {
    "platform_options": {
      "ufw": "UFW (Ubuntu/Debian)",
      "iptables": "iptables",
      "aws_sg": "AWS Security Group",
      "gcp_fw": "GCP Firewall",
      "azure_nsg": "Azure NSG",
      "generic": "Generic"
    },
    "selected_platform": "ufw",
    "commands": {
      "deny_incoming_traffic": "sudo ufw deny 3306/tcp",
      "reload_firewall": "sudo ufw reload"
    },
    "warning": null,
    "docs_url": "https://help.ubuntu.com/community/UFW"
  },
  "meta": {
    "version": "v1",
    "timestamp": "2026-07-12T09:30:00+00:00"
  }
}

Errors

CodeStatusMeaning
404404Alert not found in your account.
403403Access denied: the alert's endpoint does not belong to the given customer.

Resolve an alert

POST/api/v1/alerts/{id}/resolve
Auth: Bearer API keyRate limit: 60 requests / minute per API key

Mark an alert as resolved ("I've fixed this"). If the port is still open on a later scan, a new alert is raised.

Body parameters

NameTypeRequiredNotes
whmcs_customer_idintegerOptionalCustomer making the request, for ownership checks.
Example request
curl -X POST 'https://portal.example.com/api/v1/alerts/4d3c2b1a-0f9e-4d8c-7b6a-5f4e3d2c1b0a/resolve' \
  -H 'Authorization: Bearer $AEGIS_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "whmcs_customer_id": 1042
}'
Response: 200
{
  "success": true,
  "data": {
    "alert": {
      "id": "4d3c2b1a-0f9e-4d8c-7b6a-5f4e3d2c1b0a",
      "endpoint_id": "9f2c1e4a-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
      "ip_address": "203.0.113.10",
      "port": 3306,
      "protocol": "tcp",
      "service": "mysql",
      "severity": "critical",
      "status": "resolved",
      "risk_level": "critical",
      "title": "Database port 3306 (mysql) exposed",
      "explanation": "MySQL is reachable from the public internet…",
      "created_at": "2026-07-12T08:15:00+00:00",
      "first_detected_at": "2026-07-12T08:15:00+00:00",
      "last_detected_at": "2026-07-12T09:15:00+00:00"
    },
    "message": "Alert resolved successfully"
  },
  "meta": {
    "version": "v1",
    "timestamp": "2026-07-12T09:30:00+00:00"
  }
}

Errors

CodeStatusMeaning
404404Alert not found in your account.
403403Access denied: the alert's endpoint does not belong to the given customer.

Compiled from the AegisWhite platform (build 6bffe04, module v1.7.3, 2026-07-14).