Skip to content

Endpoints API

The Endpoints API manages the endpoint repository: every device Airgate has seen on your network, keyed by MAC address, with its status, device type, posture, guest MAC-caching expiry and custom attributes. It backs Devices › Devices and the device detail page in the console.

All routes are relative to /api/v1/t/{tenant}, where {tenant} is the tenant slug or ID. Reading needs identity:read; changes need identity:write. See API overview for authentication.

{ref} is the endpoint id (UUID) 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 answers 400.

Route Permission Purpose
GET /endpoints identity:read List, filter, sort and page.
POST /endpoints identity:write Create.
GET /endpoints/stats identity:read Counters.
GET /endpoints/attribute-keys identity:read Custom attribute names in use.
GET /endpoints/export.csv identity:read CSV export.
POST /endpoints/import identity:write CSV import.
POST /endpoints/bulk identity:write Bulk status, attributes, MAC-auth clear or delete.
GET /endpoints/{ref} identity:read One endpoint.
GET /endpoints/{ref}/context identity:read The policy attributes this endpoint contributes.
PUT /endpoints/{ref} identity:write Update; attributes is the complete set.
PATCH /endpoints/{ref} identity:write Update; attributes are merged.
DELETE /endpoints/{ref} identity:write Delete.

To re-run device profiling for an endpoint, use POST /endpoints/{ref}/reprofile in the Device profiling API.

{
"id": "6f0c1d1e-8a43-4a8e-9a55-4f1e0f0b9a11",
"tenant_id": "9eac1cf6-…",
"mac": "da:a1:19:3c:00:01",
"status": "Known",
"randomized_mac": true,
"description": "",
"owner": "alice@contoso.com",
"attributes": {"Username": "alice@contoso.com", "Guest Role ID": "2"},
"category": "SmartDevice",
"family": "Apple iOS",
"device_name": "iPhone",
"profile_confidence": 85,
"profile_source": "dhcp",
"profiled_at": "2026-11-19T08:10:02Z",
"mac_vendor": "",
"hostname": "alices-iphone",
"ip": "10.0.0.41",
"user_agent": "Mozilla/5.0 (iPhone; …)",
"dhcp_fingerprint": "1,121,3,6,15,108,114,119,252",
"dhcp_vendor": "",
"posture_token": "UNKNOWN",
"posture_checked_at": null,
"posture_expires_at": null,
"mac_auth_expires_at": "2026-11-20T12:00:00Z",
"guest_id": "1d7a3c2e-…",
"last_nad_id": "0a3c1f55-…",
"last_ssid": "Corp-Guest",
"last_auth_at": "2026-11-19T08:10:01Z",
"last_roles": ["[Guest]"],
"first_seen": "2026-11-18T17:02:11Z",
"last_seen": "2026-11-19T08:10:01Z",
"updated_at": "2026-11-19T08:10:01Z"
}
Field Meaning
status Known, Unknown or Disabled. A device first seen on the network is Unknown.
randomized_mac true for a private (locally administered) MAC address.
profile_source Where the device type came from. manual marks a profile set by an administrator: it is locked, and profiling no longer changes the category, family, device name or confidence until you release it with manual_profile: false.
posture_token HEALTHY, CHECKUP, TRANSITION, QUARANTINE, INFECTED or UNKNOWN.
mac_auth_expires_at Guest MAC caching: the device is accepted by MAC until this time.
updated_at Moves when content changes.
last_seen Moves when the device is seen on the network. Administrator edits never move it.

Permission: identity:read

All query parameters are optional and combine.

Query Type Meaning
q string Case-insensitive match on MAC (any notation), hostname, owner, device name, description, IP, MAC vendor, category and family.
status list Comma-separated: Known, Unknown, Disabled.
category, family list Comma-separated, exact match.
randomized boolean true or false.
profiled boolean true (category set) or false.
posture list Effective posture tokens; an expired token counts as UNKNOWN.
owner string Exact, case-insensitive.
mac_auth string active, expired or none.
seen_since, seen_before string RFC 3339, YYYY-MM-DD[ HH:MM:SS], or a look-back such as 24h, 90m, 7d.
attr.<name> string Custom attribute equals the value; attr.<name>=* means the attribute is present.
sort list Any of mac, status, category, family, device_name, hostname, ip, owner, mac_vendor, posture_token, profile_confidence, first_seen, last_seen, updated_at, last_auth_at, mac_auth_expires_at, randomized_mac. Prefix - (or suffix :desc) for descending. Default -last_seen.
limit, offset integer Paging. Default limit 50, at most 1000.
Terminal window
curl -s "$AIRGATE/api/v1/t/$TENANT/endpoints?status=Unknown&seen_since=24h&sort=-last_seen" \
-H "Authorization: Bearer $TOKEN"

Response 200: {"items": [Endpoint], "total": 1342}. An unknown sort column, status, posture token, boolean or time answers 400.

Permission: identity:read

One endpoint. Unknown: 404.

Permission: identity:read

The policy attributes this endpoint contributes to a sign-in, computed the same way as during authentication. Use it to troubleshoot rules.

{
"Endpoint": {"Status": ["Known"], "Category": ["Printer"], "OS Family": ["HP"],
"MAC-Address": ["00:1b:63:aa:bb:01"], "Randomized-MAC": ["false"],
"Posture-Token": ["UNKNOWN"], "Asset": ["P-1"]},
"Tips": {"Posture": ["UNKNOWN"]},
"Authorization:[Endpoints Repository]": {"Status": ["Known"], "Category": ["Printer"],
"IsProfiled": ["true"], "Unique-Device-Count": ["1"]}
}

Permission: identity:read

{
"total": 1342,
"by_status": {"Known": 410, "Unknown": 925, "Disabled": 7},
"by_posture": {"HEALTHY": 120, "QUARANTINE": 3, "UNKNOWN": 1219},
"by_category": {"Computer": 300, "SmartDevice": 610, "Unprofiled": 290},
"randomized": 702, "profiled": 1052, "mac_auth_active": 85,
"seen_last_24h": 640, "new_last_24h": 31
}

by_posture uses effective tokens; by_category lists the top 50.

Permission: identity:read

Custom attribute names in use, with how many endpoints carry each. q filters names; limit and offset page.

{"items": [{"key": "Guest Role ID", "count": 85}, {"key": "Username", "count": 91}], "total": 2}

Permission: identity:write

Field Type Meaning
mac string MAC address in any notation. Required.
status string Known (default for endpoints you add), Unknown or Disabled.
status_reason string Why the status changed.
description string Free text, may span lines.
owner string Single line.
category, family, device_name string Device type. Setting any of them creates a locked manual profile with confidence 100.
manual_profile boolean true locks the current profile; false releases it so profiling can classify the device again.
mac_auth_expires_at string RFC 3339, YYYY-MM-DD HH:MM:SS (UTC) or Unix seconds; null clears it.
attributes object Custom attributes. Values may be strings, booleans or numbers (stored as strings).

Limits: text must be valid UTF-8 without NUL characters, and single-line fields reject other control characters. At most 256 attributes per endpoint; names up to 128 bytes, values up to 8192 bytes. Values containing an unresolved %{…} reference are refused.

Terminal window
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/endpoints" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"mac":"00-1B-63-AA-BB-01","description":"Lobby printer","owner":"facilities",
"category":"Printer","family":"HP","device_name":"LaserJet M507",
"attributes":{"Asset":"P-1","Managed":true}}'

Response 201: the endpoint. 409 when the MAC already exists; 400 for an invalid MAC, status or field.

PUT /endpoints/{ref} and PATCH /endpoints/{ref}

Section titled “PUT /endpoints/{ref} and PATCH /endpoints/{ref}”

Permission: identity:write

Same body as create. mac may be left out or must be the same (changing it answers 400). Fields you leave out are unchanged, so you can send back the object you read; read-only fields are ignored.

  • attributes: with PUT the complete set (keys you do not send are deleted); with PATCH merged, and "" or null deletes a key.
  • status with status_reason: moving to Disabled records the attributes Disabled By (the administrator) and Disabled Reason; leaving Disabled records Enabled By and Enabled Reason.
  • A change to category, family or device_name becomes a manual profile.
  • A request that would add a key beyond 256 attributes answers 400; updating or deleting existing keys always works.
Terminal window
curl -s -X PATCH "$AIRGATE/api/v1/t/$TENANT/endpoints/00:1b:63:aa:bb:01" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"status":"Disabled","status_reason":"reported stolen","attributes":{"Managed":null,"Floor":"3"}}'

Response 200: the endpoint. 404 for an unknown endpoint. The change is audited with the list of changed fields.

Permission: identity:write

Response 204. Audited.

Permission: identity:write

Field Type Meaning
macs string[] MAC addresses, any notation.
ids UUID[] Endpoint IDs. At most 10 000 MACs and IDs together.
action string set_status, set_attributes, clear_mac_auth or delete.
value string The status, for set_status.
reason string Status reason, at most 8192 bytes.
attributes object For set_attributes: merged, "" deletes a key.
Terminal window
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/endpoints/bulk" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"macs":["00-00-00-00-00-01","000000000002"],"action":"set_status",
"value":"Disabled","reason":"quarterly audit"}'

Response 200:

{"action": "set_status", "requested": 2, "matched": 2, "changed": 1,
"not_found": [], "invalid": [], "limit_exceeded": []}

changed counts endpoints actually modified (those already in that state are skipped). not_found lists MACs or IDs not in the tenant, invalid lists MACs that could not be parsed, and limit_exceeded (set_attributes only) lists endpoints left unchanged because they would pass 256 attributes. The action is audited as bulk_<action>.

Permission: identity:read

Accepts every list filter and sort. Returns text/csv with Content-Disposition: attachment; filename="endpoints-<tenant>-<yyyymmdd-hhmmss>.csv".

Columns: mac, status, randomized_mac, description, owner, category, family, device_name, profile_source, profile_confidence, mac_vendor, hostname, ip, user_agent, dhcp_fingerprint, dhcp_vendor, posture_token, posture_expires_at, mac_auth_expires_at, last_ssid, last_auth_at, last_roles, first_seen, last_seen, updated_at, then one attr:<name> column per custom attribute. Times are RFC 3339 UTC; last_roles is joined with ;. Cells starting with =, +, -, @, tab or carriage return are prefixed with ' to prevent spreadsheet formula injection; the importer removes that prefix, so an export re-imports unchanged.

Terminal window
curl -s -o endpoints.csv "$AIRGATE/api/v1/t/$TENANT/endpoints/export.csv?status=Known" \
-H "Authorization: Bearer $TOKEN"

Permission: identity:write

Body: the CSV as text/csv, or multipart/form-data with a file part. At most 64 MiB and 200 000 rows. The delimiter (,, ; or tab) is detected from the header; a UTF-8 BOM is accepted.

Query Meaning
mode merge (default: update existing endpoints with non-empty cells, attributes merged), replace (as merge, but attributes replaced by the row’s) or skip (existing endpoints untouched).
dry_run true validates and counts without saving.
default_status Status of new endpoints when the row has none: Known (default), Unknown or Disabled.

Header names are matched ignoring case, spaces, _, - and .:

Column Field
mac, mac_address, MAC Address, endpoint, Calling-Station-Id MAC address (required).
status Known, Unknown or Disabled.
description, owner, hostname, ip / ip_address, mac_vendor The field.
category / device_category, family / os_family, device_name Device type. Without profile_source and profile_confidence columns, the row becomes a manual profile.
mac_auth_expires_at Guest MAC-auth expiry.
first_seen / added_at First seen, for new endpoints.
attributes A JSON object of attributes.
attr:<name>, attr.<name>, attributes.<name> A custom attribute (use this for names that clash with a field, such as attr:Status).
Read-only export columns (id, randomized_mac, last_seen, posture_*, last_*, user_agent, dhcp_*) Ignored.
Any other header A custom attribute named after the header.

Empty cells never clear a value. An invalid row (bad MAC, status, IP, time or confidence, text that is not UTF-8, or a row that would pass 256 attributes) fails on its own. When a MAC appears twice, the last row wins.

Terminal window
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/endpoints/import?mode=merge&dry_run=true" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: text/csv" \
--data-binary @endpoints.csv

Response 200:

{
"dry_run": true, "mode": "merge", "rows": 6,
"created": 2, "updated": 1, "unchanged": 0, "skipped": 0, "duplicates": 1, "failed": 2,
"dropped_values": 1,
"errors": [
{"line": 5, "mac": "00:00:00:00:00:03", "error": "invalid status \"Blocked\""}
]
}

errors lists at most 500 rows (then errors_truncated is true). 400 for a missing MAC column or malformed CSV, 413 over 64 MiB. Rows are written in batches; if the import fails part-way, the batches already written stay imported. Imports (not dry runs) are audited.

Topic When Data
endpoint.created A device is first seen, or an administrator creates it. id, mac, status, randomized_mac, category, family, device_name
endpoint.updated Content changes. The above plus changed (field names).
endpoint.profile_changed Category, family or device name changes. The above plus old, new, profile_source, profile_confidence.
endpoint.deleted An administrator deletes it. id, mac
endpoint.bulk Bulk action, CSV import or automatic cleanup. action, count, macs (first 100)

A plain sighting (only last_seen and similar times move) publishes nothing. Subscribe with a webhook.

Airgate deletes inactive endpoints once an hour according to these tenant settings (days; 0 or unset = off):

Setting Deletes
endpoint_cleanup_unknown_days Unknown endpoints not seen for that many days.
endpoint_cleanup_known_days Known endpoints not seen for that many days.
endpoint_cleanup_randomized_days Unknown endpoints with a private MAC address not seen for that many days.

Disabled endpoints and endpoints with an unexpired MAC-auth are never deleted. Each run is audited as cleanup (actor system).

© 2026 Airowire Networks Pvt. Ltd. Airgate is a product of Airowire.Product · Release notes · Security