Skip to content

Device profiling API

The device profiling API classifies devices into category, family and device name with a confidence from 0 to 99, from DHCP fingerprints, HTTP User-Agents, the MAC vendor (OUI), RADIUS device-sensor data, CDP/LLDP and SNMP. It backs Devices › Device types and the profile tab of a device on Devices › Devices.

Tenant routes are relative to /api/v1/t/{tenant}, where {tenant} is the tenant slug or ID. The platform route is under /api/v1/platform. See API overview for authentication.

Method Path Permission Purpose
GET /profiler/summary identity:read Dashboard counters
GET /profiler/dhcp identity:read Recent DHCP observations
GET /profiler/history identity:read Profile changes, evidence and CoA log
GET /profiler/unknown-fingerprints identity:read Unprofiled devices grouped by DHCP fingerprint
POST /profiler/reprofile identity:write Start a bulk reprofile job
GET /profiler/reprofile identity:read Latest bulk reprofile job
GET /profiler/snmp policy:read Network devices with SNMP read enabled, with their last poll
POST /profiler/snmp/poll policy:write Poll one network device now
GET /fingerprint-rules policy:read List system and tenant rules
POST /fingerprint-rules policy:write Create a tenant rule
POST /fingerprint-rules/bulk policy:write Enable, disable or delete many rules
POST /fingerprint-rules/test policy:read Classify a set of facts, optionally with a candidate rule
GET /fingerprint-rules/{id} policy:read Read a rule
PUT /fingerprint-rules/{id} policy:write Update a tenant rule, or enable or disable a system rule
DELETE /fingerprint-rules/{id} policy:write Delete a tenant rule
POST /endpoints/{ref}/reprofile identity:write Re-run classification for one device
GET /endpoints/{ref}/profile identity:read Evidence, classification, history and DHCP for one device
GET /api/v1/platform/profiler/dhcp-listener platform:admin DHCP listener counters of the service instance

{ref} is the device ID or its MAC address in any notation (aa:bb:cc:dd:ee:ff, AA-BB-CC-DD-EE-FF, aabb.ccdd.eeff, aabbccddeeff). Anything else returns 400; an unknown device returns 404.

Lists return {"items": [...], "total": N} and accept limit (default 50, at most 1000) and offset. Errors use the standard envelope with codes bad_request, not_found, conflict, forbidden, internal or unavailable.

Other integrations send profiling data through internal endpoints that are not exposed to API clients.

Airgate keeps the latest value of each fact for a device: dhcp_fingerprint (option 55 in wire order), dhcp_options (option order), dhcp_vendor (option 60), hostname, user_agent, and attribute facts such as cdp.platform or lldp.sys_desc. Every enabled fingerprint rule whose conditions all hold produces one piece of evidence; a built-in User-Agent parser adds another.

  • Evidence is sorted by priority, then confidence. The first item fixes the category; later items must agree or are recorded as conflict.
  • The overall confidence combines the items used (at most 99). A device is profiled when it has a category and a confidence of at least 50; the device name is published from 60.
  • Randomized (private) MAC addresses have no vendor; OUI conditions never match them.
  • A new verdict replaces the current profile only when its confidence is at least 10 points above the current one (or a reprofile is forced). A profile set by an administrator (profile_source manual) is never changed.
  • When a device previously profiled as a headless type (for example Printer, VoIP Phone, Access Points) now looks like a Computer or SmartDevice with confidence 70 or more, the profile is kept and a conflict is raised: the device attributes Conflict = "true", Other Category, Other OS Family and Other Device Name are set, so policy can act on a likely MAC spoofer.

A profile change (category or family) or a conflict re-authorizes the device’s active sessions with a CoA when the session’s service has profiler enabled, is not in monitor mode, and its profiler categories are empty, contain ANY, or contain the old or the new category. Each device gets at most one such CoA per 60 seconds and three per hour.

{
"id": "ff1ea0b9-...", "system": false, "code": "",
"name": "AcmeCam cameras", "description": "",
"enabled": true, "default_enabled": true,
"priority": 100, "confidence": 90,
"match": {
"dhcp_fingerprint": "", "dhcp_options": "",
"dhcp_vendor": "^AcmeCam (\\S+)", "hostname": "", "user_agent": "", "mac_vendor": "",
"oui": ["00:aa:bb"], "attributes": {}
},
"category": "Physical Security", "family": "Acme", "device_name": "AcmeCam $1",
"created_at": "...", "updated_at": "..."
}
Field Type Meaning
system boolean Read-only. System rules ship with Airgate (code like sys.prl.windows-10-11); only enabled can change, per tenant.
enabled, default_enabled boolean The rule’s state for this tenant, and the shipped state
name string Required, unique per tenant (case-insensitive)
priority integer 0 to 1000; higher wins. Tenant rules default to 100, so they outrank the system rules (system rules use 10 to 80).
confidence integer 1 to 100; default 80
match.dhcp_fingerprint, match.dhcp_options string Option lists: "1,3,6,15" exact (wire order), "1,3,6,*" prefix, "~43,150" contains all in any order; alternatives joined with |
match.dhcp_vendor, match.hostname, match.user_agent, match.mac_vendor string RE2 regular expression, at most 1024 characters (prefix (?i) for case-insensitive)
match.oui array 1 to 64 MAC prefixes of 6 to 11 hex digits, any notation
match.attributes object Up to 16 entries: fact attribute name to regular expression, for example {"cdp.platform": "^Cisco IP Phone"}
category, family, device_name string At most 128 characters; at least one is required. May use $1, $2 from the first regular expression with capture groups.

All non-empty conditions must hold. A regular expression never matches an empty fact.

Categories used by the system rules: Computer, SmartDevice, Printer, VoIP Phone, Video Conferencing, Physical Security, Access Points, Switches, Routers, Game Console, Home Audio/Video Equipment, Smart Home, Monitoring Devices, Datacenter Appliance, Thin Client, Digital Signage, Network Boot Agents.

Permission: policy:read

Query Meaning
scope all (default), system, tenant
enabled true or false
category One or more categories, comma-separated or repeated
q Case-insensitive search in name, code, description, verdict and every match condition (OUI prefixes in any notation)
sort Comma list of name, priority, confidence, category, family, device_name, code, created_at, updated_at, enabled, scope; - for descending. Default: tenant rules first, then priority, then name.
counts false omits the counts block

The response adds counts over every rule the tenant sees, independent of filters and paging:

{"items": ["..."], "total": 12,
"counts": {"total": 160, "enabled": 158, "disabled": 2,
"system": {"total": 154, "enabled": 153, "disabled": 1, "overridden": 1},
"tenant": {"total": 6, "enabled": 5, "disabled": 1, "limit": 1000},
"by_category": [{"category": "Computer", "total": 41, "enabled": 41}]}}

Permission: policy:write

Terminal window
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/fingerprint-rules" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name": "AcmeCam cameras", "confidence": 90, "category": "Physical Security",
"family": "Acme", "device_name": "AcmeCam $1",
"match": {"dhcp_vendor": "^AcmeCam (\\S+)", "oui": ["00-AA-BB"]}}'

Returns 201 with the rule. 400 names the invalid field (for example match.hostname: error parsing regexp: ...). 409 when the name exists or the tenant already has 1000 rules (a tenant can have at most 1000 fingerprint rules). New rules apply to the next observation; use POST /profiler/reprofile to apply them to existing devices.

Permission: policy:write

Absent fields are unchanged. For a tenant rule, any field can change. For a system rule only enabled may differ; any other change returns 400 (system fingerprint rules are read-only; only enabled can be changed ...). To override a system verdict, create a tenant rule with a higher priority. Returns 200 with the rule.

Permission: policy:write

Returns 204. System rules return 400; disable them instead.

Permission: policy:write

Field Type Meaning
ids array of UUID 1 to 1000 rule IDs
action string enable, disable or delete (delete applies to tenant rules only)

Always 200, with a result per ID:

{"action": "disable", "requested": 3, "succeeded": 2, "failed": 1, "changed": 2,
"items": [
{"id": "ff1e...", "name": "AcmeCam cameras", "ok": true, "changed": true},
{"id": "0d5c...", "name": "Windows 10/11 (DHCP)", "system": true, "ok": true, "changed": true},
{"id": "6f1c...", "ok": false, "code": "not_found", "error": "fingerprint rule not found"}]}

Permission: policy:read; also identity:read when mac is sent.

Classifies a set of facts without writing anything.

Field Type Meaning
mac string Start from this device’s stored evidence; facts override it
facts object dhcp_fingerprint, dhcp_options, dhcp_vendor, hostname, user_agent, mac_vendor, attributes
rule object An unsaved candidate rule, or edits applied over candidate_rule_id
candidate_rule_id UUID A stored rule to evaluate, even when disabled

Response 200 with classification, the effective facts, rule_matched and rule_used. With a candidate, it also returns candidate_rule_id, rule_decisive (the candidate set the category), rule_evidence, baseline (the verdict without the candidate) and verdict_changed.

{"classification": {"category": "Physical Security", "family": "Acme", "device_name": "AcmeCam X9",
"confidence": 90, "source": "dhcp", "profiled": true, "mac_vendor": "", "randomized_mac": false,
"evidence": [{"rule_id": "b68e...", "rule": "(candidate) AcmeCam", "kind": "dhcp_vendor",
"value": "AcmeCam X9", "confidence": 90, "priority": 100, "status": "used"}]},
"rule_matched": true, "rule_used": true}

Each evidence item has rule_id (a UUID or builtin:user-agent), rule, code (system rules), kind, value, source, the verdict fields, confidence after adjustments, priority, status (used, conflict or ignored) and note.

Permission: identity:write

Re-runs classification on the stored evidence with the current rules. Body optional: {"force": true} bypasses the confidence margin, weak-evidence and conflict holds, and clears the profile when the evidence is insufficient. A manual profile is never changed.

{"endpoint": {"...": "device object"}, "classification": {"...": "..."},
"decision": "changed", "reason": "new verdict Computer/Windows at 92% ..."}

decision is one of manual, insufficient, cleared, changed, refined, unchanged, held, conflict. The action is audited (reprofile).

Permission: identity:read

Returns the device, its stored facts (kind, value, source, first and last seen, count), the classification a reprofile would compute now with the previewed decision and reason, the conflict state, the last 50 history entries and the last 20 dhcp observations.

Permission: identity:read

Query recent (0 to 100, default 20) sizes the recent lists; days (1 to 90, default 30) sizes the daily series.

{"total": 3, "profiled": 2, "unprofiled": 1, "profiled_share": 0.6667,
"randomized": 0, "randomized_share": 0, "manual": 0, "conflicts": 0,
"profiled_last_24h": 2, "with_dhcp_fingerprint": 3,
"by_category": [{"label": "Computer", "count": 1}, {"label": "Unprofiled", "count": 1}],
"by_family": [], "by_vendor": [], "by_source": [],
"recently_profiled": [], "recent_changes": [],
"dhcp": {"observations_24h": 3, "listener_enabled": false, "listener_up": false, "packets": 0, "last_packet_at": null},
"rules": {"system": 154, "system_disabled": 0, "tenant": 1, "tenant_disabled": 0},
"oui": {"source": "embedded", "entries": 10427, "loaded_at": "...", "file_date": null},
"snmp": {"enabled": true, "interval_seconds": 3600, "devices": 3, "failed": 1, "last_poll_at": "..."},
"daily": [{"date": "2026-10-30", "profiled": 2, "changed": 1}]}

Permission: identity:read

Query mac, source (relay, mirror, edge, radius, …), since (RFC 3339, YYYY-MM-DD[ HH:MM:SS], or a look-back such as 24h, 90m, 7d), limit, offset. Newest first. Each item has mac, endpoint_id, at, source, nad_id, src_ip, giaddr, msg_type, fingerprint, vendor_class, hostname, option_order, client_ip, requested_ip and details (for example client_id_type, fqdn, circuit_id, remote_id). Observations are kept for the tenant setting profiler_dhcp_retention_days (default 30), at most 20 per MAC.

Permission: identity:read

Query mac, kind (comma list of changed, held, conflict, evidence, coa, reprofile), since, limit, offset. Newest first. Each item has the previous profile (old_category, old_family, old_device_name, old_confidence), the new one, a reason and details. History is kept for profiler_history_retention_days (default 365), at most 200 entries per device.

Permission: identity:read

Unprofiled devices with a DHCP fingerprint or vendor class, grouped by (dhcp_fingerprint, dhcp_vendor), largest groups first: candidates for new tenant rules. Query q, limit, offset.

{"items": [{"dhcp_fingerprint": "1,2,3,4,5", "dhcp_vendor": "", "count": 2,
"sample_macs": ["00:aa:bb:00:00:02"], "mac_vendors": [], "hostnames": ["mystery"], "last_seen": "..."}],
"total": 1}

Permission: identity:write

Field Type Meaning
scope string unprofiled (default) or all. Manual profiles are always skipped; at most 200 000 devices.
force boolean As for a single reprofile

Returns 202 with the job; 409 while a job of the tenant is running.

{"id": "3a55...", "scope": "unprofiled", "force": false, "status": "running",
"total": 120, "processed": 0, "changed": 0, "failed": 0, "error": "",
"started_by": "alice@contoso.com", "started_at": "...", "updated_at": "...", "finished_at": null}

Permission: identity:read

Returns the latest job (404 when none). status is running, done, failed or interrupted.

Network devices with SNMP read enabled are polled on a schedule (default every hour). Airgate only reads (GET, GETNEXT, GETBULK) the LLDP and CDP neighbour tables and, when enabled, the ARP table; it never writes to a device. LLDP and CDP neighbours become devices; ARP entries only update the IP address of existing devices. SNMP v1, v2c and v3 are supported. Devices reached through a site connector, defined as a subnet, or disabled are not polled.

Permission: policy:read

Query q (name or address prefix), limit, offset.

{"items": [
{"nad_id": "5b7c...", "nad_name": "access-sw1", "address": "10.0.0.2", "pollable": true, "reason": "",
"last_poll": {"polled_at": "...", "ok": true, "error": "", "duration_ms": 412, "sys_name": "access-sw1",
"sys_descr": "Cisco IOS Software ...", "lldp_neighbors": 1, "cdp_neighbors": 2,
"arp_entries": 3, "endpoints_updated": 4}},
{"nad_id": "0d6f...", "nad_name": "branch-net", "address": "10.0.1.0/24", "pollable": false,
"reason": "defined as a subnet, not a single address", "last_poll": null}],
"total": 2}

Permission: policy:write

Body {"nad_id": "<uuid>"}. Polls the device synchronously (at most 50 seconds) and returns the status object with 200, also when the poll failed (ok: false). 400 without nad_id, 404 for a device that is not the tenant’s, 409 when the device is not pollable or a poll of it is already running. The poll is audited (snmp_poll).

GET /api/v1/platform/profiler/dhcp-listener

Section titled “GET /api/v1/platform/profiler/dhcp-listener”

Permission: platform:admin

Counters of the DHCP listener of the service instance that answers: enabled, listening, addr, received, observed, deduped, ignored, malformed, no_tenant, giaddr_ignored, rate_limited, dropped, errors, last_error. The listener only receives (point an extra DHCP helper address at it or mirror DHCP); it never sends a packet.

Set through PUT /tenant/settings (see Administration API):

Key Default Meaning
profiler_dhcp_retention_days 30 Delete DHCP observations older than N days (1 to 3650)
profiler_history_retention_days 365 Delete profile history older than N days (1 to 3650)
© 2026 Airowire Networks Pvt. Ltd. Airgate is a product of Airowire.Product · Release notes · Security