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.
Base path and permissions
Section titled “Base path and permissions”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.
Endpoint object
Section titled “Endpoint object”{ "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. |
List and read
Section titled “List and read”GET /endpoints
Section titled “GET /endpoints”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. |
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.
GET /endpoints/{ref}
Section titled “GET /endpoints/{ref}”Permission: identity:read
One endpoint. Unknown: 404.
GET /endpoints/{ref}/context
Section titled “GET /endpoints/{ref}/context”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"]}}GET /endpoints/stats
Section titled “GET /endpoints/stats”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.
GET /endpoints/attribute-keys
Section titled “GET /endpoints/attribute-keys”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}Create and update
Section titled “Create and update”POST /endpoints
Section titled “POST /endpoints”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.
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""ornulldeletes a key.statuswithstatus_reason: moving toDisabledrecords the attributesDisabled By(the administrator) andDisabled Reason; leavingDisabledrecordsEnabled ByandEnabled Reason.- A change to
category,familyordevice_namebecomes a manual profile. - A request that would add a key beyond 256 attributes answers
400; updating or deleting existing keys always works.
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.
DELETE /endpoints/{ref}
Section titled “DELETE /endpoints/{ref}”Permission: identity:write
Response 204. Audited.
Bulk actions
Section titled “Bulk actions”POST /endpoints/bulk
Section titled “POST /endpoints/bulk”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. |
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>.
Export and import
Section titled “Export and import”GET /endpoints/export.csv
Section titled “GET /endpoints/export.csv”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.
curl -s -o endpoints.csv "$AIRGATE/api/v1/t/$TENANT/endpoints/export.csv?status=Known" \ -H "Authorization: Bearer $TOKEN"POST /endpoints/import
Section titled “POST /endpoints/import”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.
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.csvResponse 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.
Webhook events
Section titled “Webhook events”| 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.
Automatic cleanup
Section titled “Automatic cleanup”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).