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.
Base path and permissions
Section titled “Base path and permissions”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.
How classification works
Section titled “How classification works”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_sourcemanual) is never changed. - When a device previously profiled as a headless type (for example
Printer,VoIP Phone,Access Points) now looks like aComputerorSmartDevicewith confidence 70 or more, the profile is kept and a conflict is raised: the device attributesConflict = "true",Other Category,Other OS FamilyandOther Device Nameare 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.
Fingerprint rules
Section titled “Fingerprint rules”Rule object
Section titled “Rule object”{ "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.
GET /fingerprint-rules
Section titled “GET /fingerprint-rules”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}]}}POST /fingerprint-rules
Section titled “POST /fingerprint-rules”Permission: policy:write
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.
PUT /fingerprint-rules/{id}
Section titled “PUT /fingerprint-rules/{id}”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.
DELETE /fingerprint-rules/{id}
Section titled “DELETE /fingerprint-rules/{id}”Permission: policy:write
Returns 204. System rules return 400; disable them instead.
POST /fingerprint-rules/bulk
Section titled “POST /fingerprint-rules/bulk”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"}]}POST /fingerprint-rules/test
Section titled “POST /fingerprint-rules/test”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.
One device
Section titled “One device”POST /endpoints/{ref}/reprofile
Section titled “POST /endpoints/{ref}/reprofile”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).
GET /endpoints/{ref}/profile
Section titled “GET /endpoints/{ref}/profile”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.
GET /profiler/summary
Section titled “GET /profiler/summary”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}]}GET /profiler/dhcp
Section titled “GET /profiler/dhcp”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.
GET /profiler/history
Section titled “GET /profiler/history”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.
GET /profiler/unknown-fingerprints
Section titled “GET /profiler/unknown-fingerprints”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}Bulk reprofile
Section titled “Bulk reprofile”POST /profiler/reprofile
Section titled “POST /profiler/reprofile”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}GET /profiler/reprofile
Section titled “GET /profiler/reprofile”Permission: identity:read
Returns the latest job (404 when none). status is running, done, failed or interrupted.
SNMP polling
Section titled “SNMP polling”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.
GET /profiler/snmp
Section titled “GET /profiler/snmp”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}POST /profiler/snmp/poll
Section titled “POST /profiler/snmp/poll”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).
Platform
Section titled “Platform”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.
Tenant settings
Section titled “Tenant settings”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) |