Guardian API reference

Version v1 · https://api.guarder.io

Read your Guardian account and act on what it finds, from your own code.

Authentication. Every route except /v1/health needs a token, sent as Authorization: Bearer gapi_.... Tokens are created by an admin in the Guardian app, under Config → API tokens. The secret is shown once, at creation, and Guardian keeps only a hash of it — if you lose it, revoke it and make another.

Scopes. A token is either read (GET only) or write (GET plus the write routes). A token also carries a role — viewer, operator or admin — which can never exceed the role of the admin who created it. The write routes need operator or better.

Your account only. A token is bound to one account. There is no account parameter anywhere in this API, and an identifier belonging to another account answers 404 — the same as one that does not exist.

Rate limit. 120 requests a minute per token, and 30 writes a minute. Over either, the API answers 429 with a Retry-After header. Back off for that long rather than retrying immediately.

Paging. Every list route takes limit and offset and answers {"items": [...], "total": N, "limit": N, "offset": N}. total counts everything that matched, so you can size the work before you start.

Errors. Non-2xx responses are {"detail": "what went wrong"}.

Scopes

A token carries one of these, and a role that can never exceed the role of the admin who created it.

Scope	What it allows
read	Every GET route. Cannot change anything.
write	Everything a read token can do, plus acknowledging, snoozing, resolving and reopening alerts, labelling and trusting devices, and asking for a scan or a speed test.

Quick start

Export your token as GUARDIAN_TOKEN and run any of these.

Confirm your token works

curl -s https://api.guarder.io/v1/whoami \
  -H "Authorization: Bearer $GUARDIAN_TOKEN"

List the untrusted devices on your network

curl -s "https://api.guarder.io/v1/devices?trusted=false&limit=100" \
  -H "Authorization: Bearer $GUARDIAN_TOKEN"

Page through every open alert

curl -s "https://api.guarder.io/v1/alerts?status=open&limit=50&offset=0" \
  -H "Authorization: Bearer $GUARDIAN_TOKEN"

Acknowledge an alert (needs a write token)

curl -s -X POST https://api.guarder.io/v1/alerts/$ALERT_KEY/ack \
  -H "Authorization: Bearer $GUARDIAN_TOKEN"

Snooze an alert for 24 hours

curl -s -X POST https://api.guarder.io/v1/alerts/$ALERT_KEY/snooze \
  -H "Authorization: Bearer $GUARDIAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hours": 24}'

Mark a device as one you recognise

curl -s -X POST https://api.guarder.io/v1/devices/$MAC \
  -H "Authorization: Bearer $GUARDIAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"trusted": true, "label": "Kitchen tablet"}'

Ask for a scan now, then follow it

JOB=$(curl -s -X POST https://api.guarder.io/v1/scans \
  -H "Authorization: Bearer $GUARDIAN_TOKEN" | jq -r .id)
curl -s https://api.guarder.io/v1/jobs/$JOB -H "Authorization: Bearer $GUARDIAN_TOKEN"

Getting started

Check the API is up and confirm what your token can do.

GET/v1/healthno token needed

Liveness check

Answers without a token, so a monitor can watch the API itself.

Request

curl -s "https://api.guarder.io/v1/health"

Response 200

{
  "ok": true,
  "product": "Guardian",
  "api": "v1"
}

GET/v1/whoamiscope readrole viewer

Describe this token

What account the presented token reads, and what it is allowed to do. A good first call when wiring up a client.

Request

curl -s "https://api.guarder.io/v1/whoami" \
  -H "Authorization: Bearer $GUARDIAN_TOKEN"

Response 200

{
  "account": "string",
  "account_slug": "string",
  "token_name": "string",
  "token_prefix": "string",
  "scope": "read",
  "role": "viewer",
  "expires": "string"
}

Overview

The headline picture of the account.

GET/v1/overviewscope readrole viewer

Account overview

The headline picture: score, alert counts, device counts, site and host health, and what Guardian would do next.

Request

curl -s "https://api.guarder.io/v1/overview" \
  -H "Authorization: Bearer $GUARDIAN_TOKEN"

Response 200

{
  "ts": "string",
  "age_s": 1,
  "score": 1,
  "grade": "string",
  "potential": 1,
  "verdict": "string",
  "next_action": {
    "label": "Kitchen tablet",
    "method": "POST",
    "path": "string",
    "body": {}
  },
  "deductions": [
    {
      "category": "string",
      "points": 0,
      "why": "First seen 4 minutes ago, and it is not on the trusted list"
    }
  ],
  "strip": [
    {
      "kind": "string",
      "name": "Kitchen tablet",
      "ok": true,
      "blocks": [
        {}
      ]
    }
  ],
  "timeline": [
    {
      "ts": "string",
      "kind": "string",
      "title": "string",
      "detail": "string",
      "sev": "CRIT",
      "entity": "string",
      "href": "string"
    }
  ],
  "score_trend": {
    "name": "Kitchen tablet",
    "points": [
      {
        "ts": "string",
        "value": 1.0
      }
    ],
    "color": "string"
  },
  "questions": [
    {
      "question": "string",
      "answer": "string",
      "state": "ok"
    }
  ],
  "alerts": {
    "crit": 0,
    "warn": 0,
    "info": 0,
    "open": 0,
    "acked": 0,
    "snoozed": 0
  },
  "devices": {
    "total": 0,
    "online": 0,
    "sleeping": 0,
    "unverified": 0,
    "quarantined": 0
  },
  "sensor": {
    "name": "Kitchen tablet",
    "status": "pending",
    "last_seen": "2026-01-01T09:34:00Z",
    "age_s": 1,
    "platform": "string",
    "version": "string"
  },
  "networks": [
    {
      "id": "a1b2c3d4",
      "slug": "home",
      "name": "Kitchen tablet",
      "colour": "#1d6fe0",
      "state": "good",
      "status": "pending",
      "devices": 0,
      "online": 0,
      "unverified": 0,
      "cameras": 0,
      "cameras_online": 0,
      "crit": 0,
      "warn": 0,
      "sensor_ok": false,
      "is_primary": false
    }
  ],
  "score_trend_7d": {
    "name": "Kitchen tablet",
    "points": [
      {
        "ts": "string",
        "value": 1.0
      }
    ],
    "color": "string"
  },
  "assets": {
    "total": 0,
    "servers": 0,
    "sites": 0
  },
  "changed_24h": 0,
  "incidents": {
    "open": 0,
    "crit": 0,
    "warn": 0
  },
  "incident_briefs": [
    {
      "id": "a1b2c3d4",
      "title": "string",
      "sev": "CRIT",
      "entity": "string",
      "opened": "string",
      "alerts": 0,
      "href": "string"
    }
  ],
  "recs": {
    "open": 0,
    "critical": 0,
    "high": 0,
    "top": "string"
  },
  "health": {
    "sensor_state": "unknown",
    "run_seconds": 1,
    "scans_last_hour": 1,
    "sensors_active": 0,
    "sensors_total": 0,
    "feeds": [
      {
        "name": "Kitchen tablet",
        "ok": false
      }
    ],
    "last_event_ts": "string",
    "last_event_age_s": 1,
    "autofix_enabled": false,
    "autofix_24h": 0,
    "notify_channel": "string",
    "dns_filter_state": "off",
    "dns_blocked_24h": 0
  },
  "paths": [
    {
      "name": "Kitchen tablet",
      "ip": "192.168.1.42",
      "avg_ms": 1.0,
      "loss_pct": 1.0,
      "jitter_ms": 1.0,
      "state": "good"
    }
  ],
  "chat_example_ip": "string"
}

Networks, sites and servers

What Guardian is watching.

GET/v1/hostsscope readrole viewer

List monitored servers

Load, disk, memory, pending updates and hardening grade for each server.

Request

curl -s "https://api.guarder.io/v1/hosts" \
  -H "Authorization: Bearer $GUARDIAN_TOKEN"

Response 200

{
  "hosts": [
    {
      "name": "Kitchen tablet",
      "address": "string",
      "reachable": true,
      "hostname": "kitchen-tablet",
      "uptime": "string",
      "load1": 1.0,
      "load_per_core": 1.0,
      "disk_pct": 1.0,
      "mem_pct": 1.0,
      "failed_ssh_24h": 0,
      "banned": 0,
      "fail2ban": true,
      "reboot_required": false,
      "pending_updates": 0,
      "security_updates": 0,
      "cve_fixable": 0,
      "hardening": {
        "score": 0,
        "grade": "string",
        "checks": []
      },
      "ports": [
        {}
      ],
      "docker": [
        {}
      ],
      "services": [
        {}
      ],
      "gauges": [
        {}
      ]
    }
  ]
}

GET/v1/networksscope readrole viewer

List networks

Every monitored network, with its device counts and whether its sensor is reporting.

Request

curl -s "https://api.guarder.io/v1/networks" \
  -H "Authorization: Bearer $GUARDIAN_TOKEN"

Response 200

{
  "networks": [
    {
      "id": "a1b2c3d4",
      "slug": "home",
      "name": "Kitchen tablet",
      "kind": "wifi",
      "subnet_prefix": "string",
      "expected_gateway": "string",
      "ssid": "string",
      "sensor_id": "string",
      "sensor_name": "string",
      "colour": "#1d6fe0",
      "is_primary": false,
      "status": "pending",
      "devices": 0,
      "online": 0,
      "unverified": 0,
      "cameras": 0,
      "created": "2026-01-01T09:30:00Z"
    }
  ]
}

GET/v1/sitesscope readrole viewer

List monitored websites

Reachability, response time and certificate expiry for each website Guardian watches.

Request

curl -s "https://api.guarder.io/v1/sites" \
  -H "Authorization: Bearer $GUARDIAN_TOKEN"

Response 200

{
  "sites": [
    {
      "name": "Kitchen tablet",
      "url": "https://example.com",
      "ok": true,
      "code": 1,
      "ms": 1.0,
      "uptime_24h": 1.0,
      "uptime_7d": 1.0,
      "latency_spark": [
        1.0
      ],
      "cert_days": 1,
      "cert_expires": "string",
      "cert_issuer": "string",
      "dns_a": [
        "string"
      ],
      "headers": {
        "hsts": false,
        "nosniff": false,
        "frame": false,
        "csp": false,
        "https_redirect": false,
        "old_tls": false,
        "server": "string"
      },
      "incidents_7d": 0,
      "public": false
    }
  ]
}

Devices

Everything on the monitored networks.

GET/v1/devicesscope readrole viewer

List devices

Devices seen on the monitored networks, newest sighting first. Narrow with network, kind, trusted or q (a substring of the name, label, address or vendor).

Parameters

Name	In	Type	Notes
network	query	string
kind	query	string
trusted	query	boolean
q	query	string
limit	query	integer	default 50
offset	query	integer	default 0

Request

curl -s "https://api.guarder.io/v1/devices" \
  -H "Authorization: Bearer $GUARDIAN_TOKEN"

Response 200

{
  "items": [
    {
      "network": {
        "id": "a1b2c3d4",
        "slug": "home",
        "name": "Kitchen tablet",
        "colour": "#1d6fe0"
      },
      "mac": "a4:83:e7:2c:11:09",
      "ip": "192.168.1.42",
      "name": "Kitchen tablet",
      "vendor": "Apple, Inc.",
      "kind": "string",
      "label": "Kitchen tablet",
      "trusted": false,
      "always_on": false,
      "risk": 0,
      "presence": "string",
      "ports": {},
      "first_seen": "2026-01-01T09:30:00Z",
      "last_seen": "2026-01-01T09:34:00Z"
    }
  ],
  "total": 0,
  "limit": 50,
  "offset": 0
}

GET/v1/devices/{mac}scope readrole viewer

One device in full

Everything Guardian knows about one device: ports, timeline, DNS profile and presence.

Parameters

Name	In	Type	Notes
mac	path	string	required
network	query	string

Request

curl -s "https://api.guarder.io/v1/devices/$MAC" \
  -H "Authorization: Bearer $GUARDIAN_TOKEN"

Response 200

{
  "device": {
    "mac": "a4:83:e7:2c:11:09",
    "ip": "192.168.1.42",
    "name": "Kitchen tablet",
    "label": "Kitchen tablet",
    "vendor": "Apple, Inc.",
    "kind": "unknown",
    "group": "string",
    "trusted": false,
    "always_on": false,
    "quarantined": false,
    "parent": "string",
    "risk": 0,
    "presence": "NEW",
    "online": false,
    "first_seen": "2026-01-01T09:30:00Z",
    "last_seen": "2026-01-01T09:34:00Z",
    "ports": [
      {
        "port": 0,
        "since": "string",
        "risky": false,
        "service": "string"
      }
    ],
    "unverified": false,
    "randomized": false,
    "network": {
      "id": "a1b2c3d4",
      "slug": "home",
      "name": "Kitchen tablet",
      "colour": "#1d6fe0"
    },
    "camera_reasons": [
      "string"
    ]
  },
  "timeline": [
    {
      "ts": "string",
      "kind": "string",
      "title": "string",
      "detail": "string",
      "sev": "CRIT",
      "entity": "string",
      "href": "string"
    }
  ],
  "presence": {
    "online_pct_24h": 0.0,
    "online_pct_7d": 0.0,
    "hours": [
      1.0
    ],
    "typical_hours": [
      1
    ],
    "days": [
      {
        "day": "string",
        "hours": []
      }
    ],
    "strip": [
      {
        "hour": 0,
        "state": "none"
      }
    ]
  },
  "ports": [
    {
      "port": 0,
      "since": "string",
      "risky": false,
      "service": "string"
    }
  ],
  "dns": {
    "queries_24h": 0,
    "blocked_24h": 0,
    "top": [
      {
        "name": "Kitchen tablet",
        "count": 0
      }
    ],
    "blocked_top": [
      {
        "name": "Kitchen tablet",
        "count": 0
      }
    ]
  },
  "alerts": [
    {
      "id": "a1b2c3d4",
      "view": "alerts",
      "sev": "CRIT",
      "title": "string",
      "entity": "string",
      "why": "First seen 4 minutes ago, and it is not on the trusted list",
      "what_changed": "string",
      "status": "open",
      "first_seen": "2026-01-01T09:30:00Z",
      "last_seen": "2026-01-01T09:34:00Z",
      "count": 1,
      "actions": [
        {}
      ],
      "children": [
        {}
      ],
      "ticket_key": "string",
      "confidence": 1,
      "network": {
        "id": "a1b2c3d4",
        "slug": "home",
        "name": "Kitchen tablet",
        "colour": "#1d6fe0"
      },
      "remedy": {
        "kind": "none",
        "action": "string",
        "host": "string",
        "arg": "string",
        "tier": 0,
        "tool": "string",
        "min_role": "string",
        "can_run_now": false,
        "summary": "string",
        "need": "string",
        "opening": "string"
      }
    }
  ],
  "children": [
    {
      "mac": "a4:83:e7:2c:11:09",
      "ip": "192.168.1.42",
      "name": "Kitchen tablet",
      "label": "Kitchen tablet",
      "vendor": "Apple, Inc.",
      "kind": "unknown",
      "group": "string",
      "trusted": false,
      "always_on": false,
      "quarantined": false,
      "parent": "string",
      "risk": 0,
      "presence": "NEW",
      "online": false,
      "first_seen": "2026-01-01T09:30:00Z",
      "last_seen": "2026-01-01T09:34:00Z",
      "ports": [
        {}
      ],
      "unverified": false,
      "randomized": false,
      "network": {
        "id": "a1b2c3d4",
        "slug": "home",
        "name": "Kitchen tablet",
        "colour": "#1d6fe0"
      },
      "camera_reasons": [
        "string"
      ]
    }
  ],
  "events": [
    {
      "ts": "string",
      "type": "string",
      "entity": "string",
      "text": "string",
      "payload": {},
      "network": {
        "id": "a1b2c3d4",
        "slug": "home",
        "name": "Kitchen tablet",
        "colour": "#1d6fe0"
      }
    }
  ]
}

POST/v1/devices/{mac}scope writerole operator

Update a device

Set trusted, label or always_on. These are the only device fields v1 can change; removing or isolating a device is not exposed.

Parameters

Name	In	Type	Notes
mac	path	string	required
network	query	string

Request

curl -s -X POST "https://api.guarder.io/v1/devices/$MAC" \
  -H "Authorization: Bearer $GUARDIAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"trusted": true, "label": "Kitchen tablet", "always_on": true}'

Response 200

{
  "network": {
    "id": "a1b2c3d4",
    "slug": "home",
    "name": "Kitchen tablet",
    "colour": "#1d6fe0"
  },
  "mac": "a4:83:e7:2c:11:09",
  "ip": "192.168.1.42",
  "name": "Kitchen tablet",
  "vendor": "Apple, Inc.",
  "kind": "string",
  "label": "Kitchen tablet",
  "trusted": false,
  "always_on": false,
  "risk": 0,
  "presence": "string",
  "ports": {},
  "first_seen": "2026-01-01T09:30:00Z",
  "last_seen": "2026-01-01T09:34:00Z"
}

Findings

Alerts, incidents and recommendations — and acting on them.

GET/v1/alertsscope readrole viewer

List alerts

Alerts, most recently seen first. Narrow with status (open/acked/snoozed/resolved), sev (CRIT/WARN/INFO) or network.

Parameters

Name	In	Type	Notes
status	query	string
sev	query	string
network	query	string
limit	query	integer	default 50
offset	query	integer	default 0

Request

curl -s "https://api.guarder.io/v1/alerts" \
  -H "Authorization: Bearer $GUARDIAN_TOKEN"

Response 200

{
  "items": [
    {
      "key": "a1b2c3d4",
      "network": {
        "id": "a1b2c3d4",
        "slug": "home",
        "name": "Kitchen tablet",
        "colour": "#1d6fe0"
      },
      "sev": "INFO",
      "msg": "A new device joined the network",
      "why": "First seen 4 minutes ago, and it is not on the trusted list",
      "confidence": "high",
      "first_seen": "2026-01-01T09:30:00Z",
      "last_seen": "2026-01-01T09:34:00Z",
      "count": 1,
      "status": "open",
      "resolved_by": "string",
      "snoozed_until": "string",
      "fix": "string"
    }
  ],
  "total": 0,
  "limit": 50,
  "offset": 0
}

GET/v1/alerts/{key}scope readrole viewer

One alert

Parameters

Name	In	Type	Notes
key	path	string	required

Request

curl -s "https://api.guarder.io/v1/alerts/$KEY" \
  -H "Authorization: Bearer $GUARDIAN_TOKEN"

Response 200

{
  "key": "a1b2c3d4",
  "network": {
    "id": "a1b2c3d4",
    "slug": "home",
    "name": "Kitchen tablet",
    "colour": "#1d6fe0"
  },
  "sev": "INFO",
  "msg": "A new device joined the network",
  "why": "First seen 4 minutes ago, and it is not on the trusted list",
  "confidence": "high",
  "first_seen": "2026-01-01T09:30:00Z",
  "last_seen": "2026-01-01T09:34:00Z",
  "count": 1,
  "status": "open",
  "resolved_by": "string",
  "snoozed_until": "string",
  "fix": "string"
}

POST/v1/alerts/{key}/{op}scope writerole operator

Act on an alert

op is one of ack, snooze, resolve or reopen. All four are reversible, and all four are recorded against this token.

Parameters

Name	In	Type	Notes
key	path	string	required
op	path	string	required

Request

curl -s -X POST "https://api.guarder.io/v1/alerts/$KEY/$OP" \
  -H "Authorization: Bearer $GUARDIAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hours": 1}'

Response 200

{
  "key": "a1b2c3d4",
  "network": {
    "id": "a1b2c3d4",
    "slug": "home",
    "name": "Kitchen tablet",
    "colour": "#1d6fe0"
  },
  "sev": "INFO",
  "msg": "A new device joined the network",
  "why": "First seen 4 minutes ago, and it is not on the trusted list",
  "confidence": "high",
  "first_seen": "2026-01-01T09:30:00Z",
  "last_seen": "2026-01-01T09:34:00Z",
  "count": 1,
  "status": "open",
  "resolved_by": "string",
  "snoozed_until": "string",
  "fix": "string"
}

GET/v1/incidentsscope readrole viewer

List incidents

Groups of related alerts told as one story, newest first. open=true hides the ones already closed.

Parameters

Name	In	Type	Notes
open	query	boolean
limit	query	integer	default 50
offset	query	integer	default 0

Request

curl -s "https://api.guarder.io/v1/incidents" \
  -H "Authorization: Bearer $GUARDIAN_TOKEN"

Response 200

{
  "items": [
    {
      "iid": "string",
      "entity": "string",
      "sev": "INFO",
      "story": "string",
      "alert_keys": [
        "string"
      ],
      "opened": "string",
      "closed": "string"
    }
  ],
  "total": 0,
  "limit": 50,
  "offset": 0
}

GET/v1/recommendationsscope readrole viewer

List recommendations

Changes Guardian suggests, highest priority first. undecided=true shows only the ones nobody has answered yet.

Parameters

Name	In	Type	Notes
undecided	query	boolean
limit	query	integer	default 50
offset	query	integer	default 0

Request

curl -s "https://api.guarder.io/v1/recommendations" \
  -H "Authorization: Bearer $GUARDIAN_TOKEN"

Response 200

{
  "items": [
    {
      "key": "a1b2c3d4",
      "priority": "string",
      "title": "string",
      "why": "First seen 4 minutes ago, and it is not on the trusted list",
      "decision": "string",
      "decided_by": "string",
      "status": "open",
      "last_seen": "2026-01-01T09:34:00Z"
    }
  ],
  "total": 0,
  "limit": 50,
  "offset": 0
}

Activity

What has been happening.

GET/v1/eventsscope readrole viewer

List events

Devices joining and leaving, ports opening and closing, scans finishing — newest first. Narrow with type or network.

Parameters

Name	In	Type	Notes
type	query	string
network	query	string
limit	query	integer	default 50
offset	query	integer	default 0

Request

curl -s "https://api.guarder.io/v1/events" \
  -H "Authorization: Bearer $GUARDIAN_TOKEN"

Response 200

{
  "items": [
    {
      "ts": "string",
      "type": "string",
      "entity": "string",
      "network": {
        "id": "a1b2c3d4",
        "slug": "home",
        "name": "Kitchen tablet",
        "colour": "#1d6fe0"
      },
      "payload": {}
    }
  ],
  "total": 0,
  "limit": 50,
  "offset": 0
}

GET/v1/presencescope readrole viewer

Screen time

How long each device was online, per day and per hour, over the last days days.

Parameters

Name	In	Type	Notes
days	query	integer	default 7
network	query	string

Request

curl -s "https://api.guarder.io/v1/presence" \
  -H "Authorization: Bearer $GUARDIAN_TOKEN"

Response 200

{
  "days": 0,
  "scans": 0,
  "devices": [
    {
      "mac": "a4:83:e7:2c:11:09",
      "name": "Kitchen tablet",
      "ip": "192.168.1.42",
      "trusted": false,
      "total_h": 0.0,
      "pct": 0.0,
      "hours_per_day": 0.0,
      "hours": [
        1.0
      ],
      "network": {
        "id": "a1b2c3d4",
        "slug": "home",
        "name": "Kitchen tablet",
        "colour": "#1d6fe0"
      }
    }
  ],
  "heatmap": [
    {
      "row": "string",
      "col": 0,
      "value": 0.0
    }
  ]
}

DNS

Lookups, summaries and the current lists.

GET/v1/dnsscope readrole viewer

DNS summary

Totals, top and blocked domains, per-device breakdown and the current lists, over the last hours hours.

Parameters

Name	In	Type	Notes
hours	query	integer	default 24
network	query	string

Request

curl -s "https://api.guarder.io/v1/dns" \
  -H "Authorization: Bearer $GUARDIAN_TOKEN"

Response 200

{
  "status": {
    "enabled": false,
    "running": false,
    "queries_24h": 0,
    "blocked_24h": 0,
    "block_pct": 0.0,
    "cache": 0,
    "upstream_ms_avg": 1.0,
    "total_blocked_domains": 0,
    "family_filter": false,
    "uptime_s": 0,
    "ts": "string"
  },
  "top": [
    {
      "name": "Kitchen tablet",
      "count": 0
    }
  ],
  "blocked_top": [
    {
      "name": "Kitchen tablet",
      "count": 0
    }
  ],
  "clients": [
    {
      "mac": "a4:83:e7:2c:11:09",
      "ip": "192.168.1.42",
      "name": "Kitchen tablet",
      "queries": 0,
      "blocked": 0,
      "network": {
        "id": "a1b2c3d4",
        "slug": "home",
        "name": "Kitchen tablet",
        "colour": "#1d6fe0"
      }
    }
  ],
  "rules": {
    "allow": [
      "string"
    ],
    "block": [
      "string"
    ]
  },
  "lists": [
    {
      "name": "Kitchen tablet",
      "category": "string",
      "entries": 0,
      "blocked_24h": 0,
      "enabled": true
    }
  ],
  "beaconing": [
    {
      "name": "Kitchen tablet",
      "count": 0
    }
  ],
  "suspicious": [
    {
      "name": "Kitchen tablet",
      "count": 0
    }
  ],
  "wizard": {
    "resolver_ip": "string",
    "router_hint": "string",
    "working": false,
    "clients_using": 0,
    "checked_at": "string"
  }
}

GET/v1/dns/activityscope readrole viewer

DNS lookups

Individual DNS lookups over the last hours hours, newest first. Narrow with blocked, mac, domain or network. Older lookups are summarised rather than kept one by one — use /v1/dns for those.

Parameters

Name	In	Type	Notes
hours	query	integer	default 24
blocked	query	boolean
mac	query	string
domain	query	string
network	query	string
limit	query	integer	default 50
offset	query	integer	default 0

Request

curl -s "https://api.guarder.io/v1/dns/activity" \
  -H "Authorization: Bearer $GUARDIAN_TOKEN"

Response 200

{
  "items": [
    {
      "ts": "string",
      "client": "string",
      "mac": "a4:83:e7:2c:11:09",
      "name": "Kitchen tablet",
      "qtype": "string",
      "blocked": false,
      "list": "string",
      "ms": 0,
      "network": {
        "id": "a1b2c3d4",
        "slug": "home",
        "name": "Kitchen tablet",
        "colour": "#1d6fe0"
      }
    }
  ],
  "total": 0,
  "limit": 50,
  "offset": 0
}

GET/v1/dns/rulesscope readrole viewer

Read the DNS allow/block lists

Request

curl -s "https://api.guarder.io/v1/dns/rules" \
  -H "Authorization: Bearer $GUARDIAN_TOKEN"

Response 200

{
  "allow": [
    "string"
  ],
  "block": [
    "string"
  ]
}

Security

Posture, checks and the network map.

GET/v1/securityscope readrole viewer

Security posture

Scorecards, failed checks, exposure, Wi-Fi guard and recent attackers.

Parameters

Name	In	Type	Notes
network	query	string

Request

curl -s "https://api.guarder.io/v1/security" \
  -H "Authorization: Bearer $GUARDIAN_TOKEN"

Response 200

{
  "scorecards": [
    {
      "target": "string",
      "kind": "string",
      "grade": "string",
      "score": 0,
      "deductions": [
        {}
      ],
      "fix": "string"
    }
  ],
  "wifi": {
    "verdict": "string",
    "state": "ok",
    "ssid": "string",
    "security": "string",
    "channel": 1,
    "phy": "string",
    "signal": 1,
    "evil_twin": false,
    "twin_channels": [
      1
    ],
    "rogue_dhcp": false,
    "dhcp_server": "string",
    "expected_gateway": "string",
    "unknown_devices": 0,
    "rows": [
      {
        "key": "a1b2c3d4",
        "area": "string",
        "title": "string",
        "passed": true,
        "last_verified": "string",
        "evidence": "string",
        "autofix": "string",
        "target": "string"
      }
    ],
    "network": {
      "id": "a1b2c3d4",
      "slug": "home",
      "name": "Kitchen tablet",
      "colour": "#1d6fe0"
    }
  },
  "checks": [
    {
      "key": "a1b2c3d4",
      "area": "string",
      "title": "string",
      "passed": true,
      "last_verified": "string",
      "evidence": "string",
      "autofix": "string",
      "target": "string"
    }
  ],
  "attackers": [
    {
      "ip": "192.168.1.42",
      "host": "string",
      "fails": 0,
      "days": 0,
      "first_seen": "2026-01-01T09:30:00Z",
      "last_seen": "2026-01-01T09:34:00Z",
      "geo": {
        "country": "string",
        "country_code": "string",
        "city": "string",
        "org": "string",
        "isp": "string",
        "lat": 1.0,
        "lon": 1.0,
        "hosting": false,
        "reverse": "string"
      },
      "action": "string",
      "action_ts": "string",
      "alert_key": "string",
      "network": {
        "id": "a1b2c3d4",
        "slug": "home",
        "name": "Kitchen tablet",
        "colour": "#1d6fe0"
      }
    }
  ],
  "exposure": [
    {
      "label": "Kitchen tablet",
      "value": "string",
      "state": "ok",
      "detail": "string"
    }
  ],
  "attacker_method": "auto",
  "methods": [
    "string"
  ],
  "networks": [
    {
      "id": "a1b2c3d4",
      "slug": "home",
      "name": "Kitchen tablet",
      "colour": "#1d6fe0",
      "state": "good",
      "status": "pending",
      "devices": 0,
      "online": 0,
      "unverified": 0,
      "cameras": 0,
      "cameras_online": 0,
      "crit": 0,
      "warn": 0,
      "sensor_ok": false,
      "is_primary": false
    }
  ],
  "wifis": [
    {
      "verdict": "string",
      "state": "ok",
      "ssid": "string",
      "security": "string",
      "channel": 1,
      "phy": "string",
      "signal": 1,
      "evil_twin": false,
      "twin_channels": [
        1
      ],
      "rogue_dhcp": false,
      "dhcp_server": "string",
      "expected_gateway": "string",
      "unknown_devices": 0,
      "rows": [
        {}
      ],
      "network": {
        "id": "a1b2c3d4",
        "slug": "home",
        "name": "Kitchen tablet",
        "colour": "#1d6fe0"
      }
    }
  ],
  "extra_checks": [
    {
      "name": "Kitchen tablet",
      "type": "string",
      "target": "string",
      "port": 1,
      "ok": true,
      "latency_ms": 1,
      "detail": "string"
    }
  ],
  "heartbeats": [
    {
      "name": "Kitchen tablet",
      "every_min": 0,
      "last_ping": "string",
      "age_min": 1,
      "late": false,
      "note": "string"
    }
  ],
  "domains": [
    {
      "domain": "example.com",
      "expires": "string",
      "days_left": 1,
      "error": "string"
    }
  ]
}

GET/v1/topologyscope readrole viewer

Network map

Nodes and links for the network map, clustered by kind, area or network.

Parameters

Name	In	Type	Notes
cluster_by	query	string	default "kind"
network	query	string

Request

curl -s "https://api.guarder.io/v1/topology" \
  -H "Authorization: Bearer $GUARDIAN_TOKEN"

Response 200

{
  "nodes": [
    {
      "id": "a1b2c3d4",
      "kind": "string",
      "group": "string",
      "label": "Kitchen tablet",
      "ip": "192.168.1.42",
      "mac": "a4:83:e7:2c:11:09",
      "icon": "string",
      "state": "ok",
      "risk": 0,
      "ring": 0,
      "trusted": false,
      "quarantined": false,
      "pulse": false,
      "detail": "string",
      "network": {
        "id": "a1b2c3d4",
        "slug": "home",
        "name": "Kitchen tablet",
        "colour": "#1d6fe0"
      }
    }
  ],
  "links": [
    {
      "source": "string",
      "target": "string",
      "kind": "string",
      "pulse": false
    }
  ],
  "clusters": [
    {
      "id": "a1b2c3d4",
      "label": "Kitchen tablet",
      "members": [
        "string"
      ],
      "network_id": "string"
    }
  ],
  "networks": [
    {
      "id": "a1b2c3d4",
      "slug": "home",
      "name": "Kitchen tablet",
      "colour": "#1d6fe0",
      "state": "good",
      "status": "pending",
      "devices": 0,
      "online": 0,
      "unverified": 0,
      "cameras": 0,
      "cameras_online": 0,
      "crit": 0,
      "warn": 0,
      "sensor_ok": false,
      "is_primary": false
    }
  ]
}

Reports

Generated reports.

GET/v1/reportsscope readrole viewer

List reports

Reports Guardian has generated, newest first.

Parameters

Name	In	Type	Notes
limit	query	integer	default 50
offset	query	integer	default 0

Request

curl -s "https://api.guarder.io/v1/reports" \
  -H "Authorization: Bearer $GUARDIAN_TOKEN"

Response 200

{
  "items": [
    {
      "id": "a1b2c3d4",
      "kind": "string",
      "title": "string",
      "period_days": 0,
      "preset": "string",
      "sections": [
        "string"
      ],
      "created": "2026-01-01T09:30:00Z",
      "score": 1
    }
  ],
  "total": 0,
  "limit": 50,
  "offset": 0
}

GET/v1/reports/{report_id}scope readrole viewer

Fetch one report

The rendered report, as a standalone HTML document.

Parameters

Name	In	Type	Notes
report_id	path	string	required

Request

curl -s "https://api.guarder.io/v1/reports/$REPORT_ID" \
  -H "Authorization: Bearer $GUARDIAN_TOKEN"

Jobs

Work handed to the sensor.

GET/v1/jobs/{job_id}scope readrole viewer

Check queued work

The state of work an earlier write handed to the sensor.

Parameters

Name	In	Type	Notes
job_id	path	string	required

Request

curl -s "https://api.guarder.io/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $GUARDIAN_TOKEN"

Response 200

{
  "id": "a1b2c3d4",
  "status": "queued",
  "queued_at": "string",
  "finished_at": "string",
  "ok": true
}

POST/v1/scansscope writerole operator

Trigger a scan

Asks the sensor to scan now rather than waiting for its next cycle. Returns a job id — poll /v1/jobs/{id}.

Request

curl -s -X POST "https://api.guarder.io/v1/scans" \
  -H "Authorization: Bearer $GUARDIAN_TOKEN"

Response 202

{
  "id": "a1b2c3d4",
  "status": "queued"
}

POST/v1/speedtestscope writerole operator

Trigger a speed test

Asks the sensor to measure the internet connection now. Returns a job id — poll /v1/jobs/{id}.

Request

curl -s -X POST "https://api.guarder.io/v1/speedtest" \
  -H "Authorization: Bearer $GUARDIAN_TOKEN"

Response 202

{
  "id": "a1b2c3d4",
  "status": "queued"
}

Not in v1

These are left out deliberately, not by omission. Each one is available in the Guardian app, to a person who can see what will happen.

Rebooting or upgrading a serverGuardian classes a reboot, a full package upgrade and an SSH policy change as needing a person to confirm them, one at a time, because each can take a machine off the network. A long-lived token cannot confirm anything, so these stay in the app.

Blocking a subnet, or long-banning or rate-limiting an addressSame reason: a wide block can lock you out of your own network, and Guardian will not make one without a person looking at it.

Running a repair on a hostRepairs are approved per host and per action in the app, where you can see exactly what will run before it does. The API can tell you what Guardian recommends; approving it is a decision, not a call.

Isolating or removing a deviceIsolating a device cuts it off, and removing one loses its history. Both are reachable in the app, where they can be undone by someone who can see what happened.

Changing the DNS allow and block listsYou can read the lists. Changing them changes what every device on the network can reach, so it is an app action for now — tell us if you need it here.

Scheduling a reboot window, or changing how Guardian responds to attackersBoth set standing policy rather than doing one thing, and standing policy belongs where the person who owns it can see it.

Account settings, users, integrations, sensors and billingAdministration is done by a person in the app. A token exists to read your data and act on findings, never to reconfigure the account that issued it.