Documentation menu

Docs

Endpoints

Manage monitored endpoints (servers identified by IP address or hostname).

Manage monitored endpoints (servers identified by IP address or hostname). Endpoints created here behave exactly like endpoints provisioned through WHMCS; pass whmcs_customer_id to scope reads and writes to one customer.

Endpoint detail with scan data

GET/api/v1/endpoints/{endpoint}/detail
Auth: Bearer API keyRate limit: 100 requests / minute (platform default)

Everything the client-area endpoint page shows in one call: the endpoint, its latest scan, up to 10 open alerts, currently allowed ports, and which ports appeared or disappeared between the last two scans.

  • latest_scan is null until the first scan completes; new_ports/closed_ports are empty until at least two scans exist.
  • whitelisted_ports entries are "port:protocol" strings; rules covering both protocols appear once per protocol.
  • Unlike the other reads in this group, this response has no meta envelope.

Query parameters

NameTypeRequiredNotes
whmcs_customer_idintegerOptionalCustomer making the request, for ownership checks.
Example request
curl -X GET 'https://portal.example.com/api/v1/endpoints/9f2c1e4a-5b6d-4e7f-8a9b-0c1d2e3f4a5b/detail?whmcs_customer_id=1042' \
  -H 'Authorization: Bearer $AEGIS_API_KEY'
Response: 200
{
  "data": {
    "id": "9f2c1e4a-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "ip_address": "203.0.113.10",
    "hostname": "web01.example.com",
    "nickname": "Web server",
    "platform": null,
    "status": "active",
    "nmap_cooldown_seconds": 0,
    "last_scan_at": "2026-07-12T06:00:00+00:00",
    "next_scan_at": "2026-07-13T06:00:00+00:00",
    "created_at": "2026-06-01T12:00:00+00:00",
    "updated_at": "2026-07-12T06:00:00+00:00",
    "whmcs_customer_id": 1042
  },
  "latest_scan": {
    "open_ports": [22, 80, 443],
    "status": "completed",
    "scan_duration_ms": 8425,
    "scanned_at": "2026-07-12T06:00:00+00:00"
  },
  "alerts": [
    {
      "id": "4d3c2b1a-0f9e-4d8c-7b6a-5f4e3d2c1b0a",
      "port": 22,
      "protocol": "tcp",
      "service": "ssh",
      "severity": "high",
      "risk_level": "high",
      "status": "open",
      "title": "SSH port 22 exposed",
      "first_detected_at": "2026-07-10T06:00:00+00:00",
      "last_detected_at": "2026-07-12T06:00:00+00:00"
    }
  ],
  "whitelisted_ports": ["80:tcp", "443:tcp"],
  "new_ports": [],
  "closed_ports": [8080]
}

Errors

CodeStatusMeaning
404404No endpoint with that ID in your account.

List endpoints

GET/api/v1/endpoints
Auth: Bearer API keyRate limit: 100 requests / minute (platform default)

List monitored endpoints as pages of endpoint resources. meta carries the plan's endpoint limit, current usage and per-status counts alongside the pagination fields.

  • This group returns standard Laravel resource envelopes (data / links / meta), not the success envelope used by the provisioning and alerts groups.

Query parameters

NameTypeRequiredNotes
whmcs_customer_idintegerOptionalLimit results to one customer's endpoints.
statusstringOptionalFilter by endpoint status.one of: active, paused
per_pageintegerOptionalPage size.
pageintegerOptionalPage number.
Example request
curl -X GET 'https://portal.example.com/api/v1/endpoints?whmcs_customer_id=1042&per_page=15&page=1' \
  -H 'Authorization: Bearer $AEGIS_API_KEY'
Response: 200
{
  "data": [
    {
      "id": "9f2c1e4a-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
      "ip_address": "203.0.113.10",
      "hostname": "web01.example.com",
      "nickname": "Web server",
      "platform": null,
      "status": "active",
      "nmap_cooldown_seconds": 0,
      "last_scan_at": "2026-07-12T06:00:00+00:00",
      "next_scan_at": "2026-07-13T06:00:00+00:00",
      "created_at": "2026-06-01T12:00:00+00:00",
      "updated_at": "2026-07-12T06:00:00+00:00",
      "whmcs_customer_id": 1042
    }
  ],
  "links": {
    "first": "…",
    "last": "…",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "per_page": 15,
    "total": 1,
    "endpoint_limit": 10,
    "current_endpoint_count": 1,
    "status_counts": {
      "active": 1
    }
  }
}

Create an endpoint

POST/api/v1/endpoints
Auth: Bearer API keyRate limit: 100 requests / minute (platform default)

Add a server to monitoring by IP address or hostname (hostnames are resolved at creation). Deduplicated per customer: re-adding an existing or previously deleted IP returns the existing endpoint with 200 instead of creating a duplicate.

Body parameters

NameTypeRequiredNotes
whmcs_customer_idintegerRequiredThe customer the endpoint belongs to.min:1
ip_addressstringRequiredIP address or hostname of the server to monitor.max:255
nicknamestringOptionalDisplay name for the endpoint.max:255
statusstringOptionalInitial status; defaults to active.one of: active, paused
client_namestringOptionalCustomer name, used to create their account if it does not exist yet.max:255
client_emailemailOptionalCustomer email, used to create their account if it does not exist yet.max:255
Example request
curl -X POST 'https://portal.example.com/api/v1/endpoints' \
  -H 'Authorization: Bearer $AEGIS_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "whmcs_customer_id": 1042,
  "ip_address": "203.0.113.10",
  "nickname": "Web server",
  "status": "active",
  "client_name": "Jane Doe",
  "client_email": "jane@example.com"
}'
Response: 201
{
  "data": {
    "id": "9f2c1e4a-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "ip_address": "203.0.113.10",
    "hostname": "web01.example.com",
    "nickname": "Web server",
    "platform": null,
    "status": "active",
    "nmap_cooldown_seconds": 0,
    "last_scan_at": null,
    "next_scan_at": "2026-07-13T06:00:00+00:00",
    "created_at": "2026-07-12T09:30:00+00:00",
    "updated_at": "2026-07-12T09:30:00+00:00",
    "whmcs_customer_id": 1042
  },
  "meta": {
    "timestamp": "2026-07-12T09:30:00+00:00",
    "version": "v1"
  }
}

Errors

CodeStatusMeaning
ENDPOINT_LIMIT_EXCEEDED403The customer's plan does not allow another endpoint.
DNS_RESOLUTION_FAILED422The hostname could not be resolved to an IP address.

Get an endpoint

GET/api/v1/endpoints/{endpoint}
Auth: Bearer API keyRate limit: 100 requests / minute (platform default)

Fetch one endpoint resource.

Query parameters

NameTypeRequiredNotes
whmcs_customer_idintegerOptionalCustomer making the request, for ownership checks.
Example request
curl -X GET 'https://portal.example.com/api/v1/endpoints/9f2c1e4a-5b6d-4e7f-8a9b-0c1d2e3f4a5b?whmcs_customer_id=1042' \
  -H 'Authorization: Bearer $AEGIS_API_KEY'
Response: 200
{
  "data": {
    "id": "9f2c1e4a-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "ip_address": "203.0.113.10",
    "hostname": "web01.example.com",
    "nickname": "Web server",
    "platform": null,
    "status": "active",
    "nmap_cooldown_seconds": 0,
    "last_scan_at": "2026-07-12T06:00:00+00:00",
    "next_scan_at": "2026-07-13T06:00:00+00:00",
    "created_at": "2026-06-01T12:00:00+00:00",
    "updated_at": "2026-07-12T06:00:00+00:00",
    "whmcs_customer_id": 1042
  },
  "meta": {
    "timestamp": "2026-07-12T09:30:00+00:00",
    "version": "v1"
  }
}

Errors

CodeStatusMeaning
404404No endpoint with that ID in your account.

Update an endpoint

PUT/api/v1/endpoints/{endpoint}
Auth: Bearer API keyRate limit: 100 requests / minute (platform default)

Rename an endpoint or switch it between active and paused. Only nickname and status can be changed. The IP address is fixed at creation.

Body parameters

NameTypeRequiredNotes
whmcs_customer_idintegerRequiredThe customer who owns the endpoint.min:1
nicknamestringOptionalNew display name.max:255
statusstringOptionalSet to paused to stop scanning, active to resume.one of: active, paused
Example request
curl -X PUT 'https://portal.example.com/api/v1/endpoints/9f2c1e4a-5b6d-4e7f-8a9b-0c1d2e3f4a5b' \
  -H 'Authorization: Bearer $AEGIS_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "whmcs_customer_id": 1042,
  "nickname": "Primary web server",
  "status": "paused"
}'
Response: 200
{
  "data": {
    "id": "9f2c1e4a-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "ip_address": "203.0.113.10",
    "hostname": "web01.example.com",
    "nickname": "Primary web server",
    "platform": null,
    "status": "paused",
    "nmap_cooldown_seconds": 0,
    "last_scan_at": "2026-07-12T06:00:00+00:00",
    "next_scan_at": null,
    "created_at": "2026-06-01T12:00:00+00:00",
    "updated_at": "2026-07-12T09:30:00+00:00",
    "whmcs_customer_id": 1042
  },
  "meta": {
    "timestamp": "2026-07-12T09:30:00+00:00",
    "version": "v1"
  }
}

Errors

CodeStatusMeaning
404404No endpoint with that ID in your account.

Delete an endpoint

DELETE/api/v1/endpoints/{endpoint}
Auth: Bearer API keyRate limit: 100 requests / minute (platform default)

Stop monitoring an endpoint and remove it from lists (soft delete: history is retained, and re-adding the same IP restores it).

  • The 204 response has an empty body.

Query parameters

NameTypeRequiredNotes
whmcs_customer_idintegerOptionalCustomer making the request, for ownership checks.
Example request
curl -X DELETE 'https://portal.example.com/api/v1/endpoints/9f2c1e4a-5b6d-4e7f-8a9b-0c1d2e3f4a5b?whmcs_customer_id=1042' \
  -H 'Authorization: Bearer $AEGIS_API_KEY'
Response: 204
null

Errors

CodeStatusMeaning
404404No endpoint with that ID in your account.

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