Endpoint API

Endpoint API

Issue enrollment tokens, inspect identities and capabilities, and retire device management.

Endpoint records reference an asset and a separate agent identity. Enrollment and local uninstall explain what the management API can verify.

Use the shared API contract for authentication, pagination, request headers, idempotency, and error responses.

Create an enrollment token

POST/organizations/{organization_id}/endpoint-enrollment-tokens
Scope
endpoints:write
Auth
Bearer API key

Creates an enrollment token for the selected group. Requires Administrator authority for that group. The token is returned once and cannot be read later.

Request body
group_idstringrequired

Target group for initial assignment.

platformstringrequired

Exact platform identifier from the signed package catalog.

expires_in_secondsintegeroptional

Token validity interval.

default900rule60–86400 seconds
max_enrollmentsintegeroptional

Maximum successful enrollments.

default1rule1–1000
201Created

Returns the token ID, one-time secret, expiry, and remaining enrollment count. Do not log the secret.

Revoke an enrollment token

DELETE/organizations/{organization_id}/endpoint-enrollment-tokens/{token_id}
Scope
endpoints:write
Auth
Bearer API key

Revokes further use of an enrollment token. Requires the current If-Match value from its creation response or enrollment-token inventory. Already enrolled identities remain enrolled.

204Removed

No response body.

List endpoints

GET/organizations/{organization_id}/endpoints
Scope
endpoints:read
Auth
Bearer API key

Returns endpoint, asset, and agent IDs plus platform, last contact, capabilities, and applied policy revision. Standard limit and cursor apply. Unknown filters return 422.

Query parameters
group_idstringoptional

Filter by visible asset group.

healthstringoptional

The current reporting status.

one ofhealthy, degraded, offline
200Result

Returns a data array and pagination.next_cursor. Entries include stable IDs and the resource fields described for this collection.

Read endpoint state

GET/organizations/{organization_id}/endpoints/{endpoint_id}
Scope
endpoints:read
Auth
Bearer API key

Returns observed isolation, compliance, queue gaps, and the last acknowledged action. Missing contact does not prove an action succeeded.

200Result

The response is similar to the following:

JSON
{
  "data": {
    "id": "end_laptop01",
    "asset_id": "ast_laptop01",
    "agent_id": "agt_001",
    "health": "offline",
    "assigned_policy_revision": 5,
    "applied_policy_revision": 4,
    "isolation": "unknown",
    "last_contact_at": "2026-03-23T10:00:00Z"
  },
  "request_id": "req_endpoint01"
}

Retire an endpoint

POST/organizations/{organization_id}/endpoints/{endpoint_id}/retire
Scope
endpoints:write
Auth
Bearer API key

Starts endpoint retirement and stops new assignments. Requires If-Match. Retirement does not establish that an offline device was uninstalled.

Request body
reasonstringrequired

Audited justification. Empty values are invalid.

rule1–2000 characters
202Accepted

Returns the endpoint and retirement operation. Preserve outstanding quarantine and containment references until reconciled.