Hosts

What it's for

A host represents a target to monitor: a server, a website, an API, a network device. It is the anchor point to which you attach checks. A host thus groups together all the probes for a given machine or service, and centralizes their results (uptime, latest state, logs, metrics).

The host model

Using it from the portal

The Hosts section lists all your hosts with their state. You can:

• Add a host: provide name, hostname/IP, type and tags.
• Open the details of a host to view:
  • its graphs and its ping uptime over 24 h, 7 d or 30 d;
  • its latest result per check;
  • its logs (if log correlation is available for your organization);
  • its SNMP metrics if the host is monitored via SNMP.
• Edit or delete a host.

Listing and viewing: all roles. Create, edit, delete: owner and admin.

Using it through the API

List hosts

GET /api/v2/hosts — optional active=true parameter to return only active hosts.

curl -s "https://api.secumon.secuaas.ovh/api/v2/hosts?active=true" \
  -H "Authorization: Bearer $SECUMON_TOKEN"

{
  "count": 1,
  "hosts": [
    {
      "id": "8f3b1c2a-2d44-4e1a-9b77-0a1b2c3d4e5f",
      "name": "web-prod-01",
      "hostname": "10.0.0.12",
      "host_type": "server",
      "tags": { "env": "prod", "role": "web" },
      "is_active": true,
      "created_at": "2026-06-23T12:00:00Z",
      "updated_at": "2026-06-23T12:00:00Z"
    }
  ]
}

Create a host

POST /api/v2/hosts — role owner or admin. name and hostname are required.

curl -s -X POST https://api.secumon.secuaas.ovh/api/v2/hosts \
  -H "Authorization: Bearer $SECUMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-prod-01",
    "hostname": "10.0.0.12",
    "host_type": "server",
    "tags": { "env": "prod", "role": "web" }
  }'

Response: 201 Created with the full host (see Getting started).

View, edit, delete

# Detail
curl -s https://api.secumon.secuaas.ovh/api/v2/hosts/8f3b1c2a-2d44-4e1a-9b77-0a1b2c3d4e5f \
  -H "Authorization: Bearer $SECUMON_TOKEN"

# Edit (only the provided fields are updated)
curl -s -X PUT https://api.secumon.secuaas.ovh/api/v2/hosts/8f3b1c2a-2d44-4e1a-9b77-0a1b2c3d4e5f \
  -H "Authorization: Bearer $SECUMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "tags": { "env": "prod", "role": "web", "owner": "team-web" } }'

# Delete
curl -s -X DELETE https://api.secumon.secuaas.ovh/api/v2/hosts/8f3b1c2a-2d44-4e1a-9b77-0a1b2c3d4e5f \
  -H "Authorization: Bearer $SECUMON_TOKEN"

Editing is partial: a field absent from the body keeps its current value. Deletion returns 204 No Content.

Ping uptime

GET /api/v2/hosts/:id/uptime?window=24h|7d|30d returns the availability percentage computed from the ping results.

curl -s "https://api.secumon.secuaas.ovh/api/v2/hosts/8f3b1c2a-2d44-4e1a-9b77-0a1b2c3d4e5f/uptime?window=7d" \
  -H "Authorization: Bearer $SECUMON_TOKEN"

{ "uptime_pct": 99.87, "samples": 10080, "window": "7d" }

Only the values 24h, 7d and 30d are accepted for window.

Latest result per check

GET /api/v2/hosts/:id/latest returns, for each check of the host, its most recent result.

curl -s https://api.secumon.secuaas.ovh/api/v2/hosts/8f3b1c2a-2d44-4e1a-9b77-0a1b2c3d4e5f/latest \
  -H "Authorization: Bearer $SECUMON_TOKEN"

[
  {
    "check_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "time": "2026-06-23T12:01:30Z",
    "status": 0,
    "latency_ms": 1.5,
    "output": "pong 1.5ms",
    "error_msg": ""
  }
]

Host SNMP metrics

GET /api/v2/hosts/:id/snmp-metrics?from=&to= returns the time series of the host's SNMP checks (by default, the last 6 hours). See the SNMP page.

Host logs

GET /api/v2/hosts/:id/logs?from=&to=&limit= returns the log entries associated with the hostname, when log correlation is enabled for your organization.

curl -s "https://api.secumon.secuaas.ovh/api/v2/hosts/8f3b1c2a-2d44-4e1a-9b77-0a1b2c3d4e5f/logs?limit=50" \
  -H "Authorization: Bearer $SECUMON_TOKEN"

{ "enabled": true, "count": 2, "entries": [ /* ... */ ] }

If the feature is not enabled, the response is {"enabled": false, "entries": []}. The maximum time range is 24 hours; limit is capped at 5000 (100 by default).

AI-assisted tagging

SecuMon can suggest tags for a host by analyzing its name, hostname, IP, the type of its checks and its latest SNMP output. Suggested tags are added under an ai: prefix and do not overwrite your manual tags.

• POST /api/v2/hosts/:id/ai-tag — tags a single host.
• POST /api/v2/hosts/ai-tag — tags all hosts (optional body {"active_only": true}, sequential processing, capped at 200 hosts).

Reserved for the owner and admin roles.

curl -s -X POST https://api.secumon.secuaas.ovh/api/v2/hosts/8f3b1c2a-2d44-4e1a-9b77-0a1b2c3d4e5f/ai-tag \
  -H "Authorization: Bearer $SECUMON_TOKEN"

{
  "host": { "id": "8f3b1c2a-2d44-4e1a-9b77-0a1b2c3d4e5f", "name": "web-prod-01", "...": "..." },
  "ai_tags": { "role": "web-server", "os": "linux" },
  "confidence": 0.82,
  "model_used": "souverain",
  "cost_usd": 0.0004,
  "tags": { "env": "prod", "role": "web", "ai:role": "web-server", "ai:os": "linux" }
}

If AI tagging is not configured for your instance, the endpoint responds 503 with {"error": "ai_unavailable"}.

Use cases

• Structured inventory: use tags (env, role, owner, region) to filter and group your hosts consistently.
• Availability reporting: GET /hosts/:id/uptime?window=30d provides the data for a monthly per-host SLA report.
• Temporary decommissioning: set is_active to false to stop scheduling a host's checks without deleting it.

Tips

• Prefer is_active: false to deletion in order to keep the history of a host you intend to reuse.
• Run POST /hosts/ai-tag after a bulk import to get an initial automatic taxonomy, then refine it by hand.
• The host_type is free-form: adopt a team convention (server, website, router, switch…) to make filtering easier.