API reference

Policies

Device policies across platforms, how many devices each one manages, and which devices are assigned to it.

Import the whole API:OpenAPI 3.1 Postman collection

A policy is the configuration WeGuard applies to the devices assigned to it. Each device has at most one policy, shown in policy on the device object.

The policy object

AttributeDescription

id string: Unique policy id.
object string: Always policy.
platform string: Platform the policy targets. Mac policies are macos, Apple TV policies tvos.
One ofandroidiosmacostvoswindows
name stringnullable: Policy name as shown in the console. null only for malformed legacy records.
description stringnullable: Description entered in the console.
type stringnullable: Platform-specific policy variant as shown in the console, for example ANDROID_KIOSK. For information only. New values may appear.
deviceCount integer: Number of devices currently assigned to the policy. This is the same count the console shows.
createdAt timestamp: When the policy was created.
updatedAt timestampnullable: When the policy was last changed.

Example

{
  "id": "64ff0a1b2c3d4e5f60718293",
  "object": "policy",
  "platform": "android",
  "name": "Kiosk: Scanners",
  "description": "Locked-down scanner devices",
  "type": "ANDROID_KIOSK",
  "deviceCount": 128,
  "createdAt": "2026-01-09T11:00:00Z",
  "updatedAt": "2026-09-30T16:42:10Z"
}

List policies

GET/v1/policies

Requirespolicies:read

Returns the policies in your account, ordered by id (creation order), as a paginated list.

Query parameters

ParameterDescription

platform stringoptionaldefault all platforms: Only return items for these platforms. Pass a comma-separated list, for example android,ios. Values are case-insensitive. ios covers iPhone, iPad and iPod touch.
One or more ofandroidiosmacostvoswindows
limit integeroptionaldefault 25: Maximum number of items to return, from 1 to 100.
cursor stringoptional: The nextCursor from the previous page. Send it unchanged, together with the same filters. See Pagination.
includeTotal booleanoptionaldefault false: Set to true to also return totalCount. It runs an extra count, so request it only when you need it.

Example request

curl "https://api-gw.weguard.ai/core/v1/policies?platform=android&limit=1" \
  -H "Authorization: Bearer $WEGUARD_API_KEY"

const response = await fetch("https://api-gw.weguard.ai/core/v1/policies?platform=android&limit=1", {
  headers: { Authorization: `Bearer ${process.env.WEGUARD_API_KEY}` },
});

const body = await response.json();
if (!response.ok) {
  throw new Error(`${body.code}: ${body.detail} (requestId ${body.requestId})`);
}
console.log(body);

import os
import requests

response = requests.get(
    "https://api-gw.weguard.ai/core/v1/policies",
    params={"platform": "android", "limit": 1},
    headers={"Authorization": f"Bearer {os.environ['WEGUARD_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Response

A list object whose data holds policy objects.

200 OK

{
  "object": "list",
  "data": [
    {
      "id": "64ff0a1b2c3d4e5f60718293",
      "object": "policy",
      "platform": "android",
      "name": "Kiosk: Scanners",
      "description": "Locked-down scanner devices",
      "type": "ANDROID_KIOSK",
      "deviceCount": 128,
      "createdAt": "2026-01-09T11:00:00Z",
      "updatedAt": "2026-09-30T16:42:10Z"
    }
  ],
  "hasMore": true,
  "nextCursor": "YzE6NjUyM2YxYzJhN2I5ZDQwMDEyMzQ1Njc4"
}

Errors

400invalid_parameter
limit, includeTotal or a filter has an invalid value, or a parameter was sent twice.
400unknown_parameter
The request includes a query parameter this endpoint does not accept.
400invalid_cursor
The cursor is malformed or was issued for different filters.
403insufficient_scope
The key lacks policies:read.

Retrieve a policy

GET/v1/policies/{policyId}

Requirespolicies:read

Returns a single policy by id.

Path parameters

ParameterDescription

policyId stringrequired: Id of the policy. Case-insensitive.

Example request

curl https://api-gw.weguard.ai/core/v1/policies/64ff0a1b2c3d4e5f60718293 \
  -H "Authorization: Bearer $WEGUARD_API_KEY"

const response = await fetch("https://api-gw.weguard.ai/core/v1/policies/64ff0a1b2c3d4e5f60718293", {
  headers: { Authorization: `Bearer ${process.env.WEGUARD_API_KEY}` },
});

const body = await response.json();
if (!response.ok) {
  throw new Error(`${body.code}: ${body.detail} (requestId ${body.requestId})`);
}
console.log(body);

import os
import requests

response = requests.get(
    "https://api-gw.weguard.ai/core/v1/policies/64ff0a1b2c3d4e5f60718293",
    headers={"Authorization": f"Bearer {os.environ['WEGUARD_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Response

Returns a policy object.

200 OK

{
  "id": "64ff0a1b2c3d4e5f60718293",
  "object": "policy",
  "platform": "android",
  "name": "Kiosk: Scanners",
  "description": "Locked-down scanner devices",
  "type": "ANDROID_KIOSK",
  "deviceCount": 128,
  "createdAt": "2026-01-09T11:00:00Z",
  "updatedAt": "2026-09-30T16:42:10Z"
}

Errors

404resource_not_found
No policy with this id exists in your account.
400unknown_parameter
The request includes a query parameter. This endpoint takes none.
403insufficient_scope
The key lacks policies:read.

List a policy’s devices

GET/v1/policies/{policyId}/devices

Requires all ofpolicies:read devices:read

Returns the devices assigned to a policy, ordered by id, as a paginated list. Requires both policies:read and devices:read.

Path parameters

ParameterDescription

policyId stringrequired: Id of the policy. Case-insensitive.

Query parameters

ParameterDescription

limit integeroptionaldefault 25: Maximum number of items to return, from 1 to 100.
cursor stringoptional: The nextCursor from the previous page. Send it unchanged, together with the same filters. See Pagination.
includeTotal booleanoptionaldefault false: Set to true to also return totalCount. It runs an extra count, so request it only when you need it.

Example request

curl "https://api-gw.weguard.ai/core/v1/policies/64ff0a1b2c3d4e5f60718293/devices?limit=1" \
  -H "Authorization: Bearer $WEGUARD_API_KEY"

const response = await fetch("https://api-gw.weguard.ai/core/v1/policies/64ff0a1b2c3d4e5f60718293/devices?limit=1", {
  headers: { Authorization: `Bearer ${process.env.WEGUARD_API_KEY}` },
});

const body = await response.json();
if (!response.ok) {
  throw new Error(`${body.code}: ${body.detail} (requestId ${body.requestId})`);
}
console.log(body);

import os
import requests

response = requests.get(
    "https://api-gw.weguard.ai/core/v1/policies/64ff0a1b2c3d4e5f60718293/devices",
    params={"limit": 1},
    headers={"Authorization": f"Bearer {os.environ['WEGUARD_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Response

A list object whose data holds device objects.

200 OK

{
  "object": "list",
  "data": [
    {
      "id": "6523f1c2a7b9d40012345678",
      "object": "device",
      "platform": "android",
      "name": "Warehouse Scanner 12",
      "model": "SM-T505",
      "manufacturer": "samsung",
      "osVersion": "13",
      "serialNumber": "R9JN30ABCDE",
      "imei": "356938035643809",
      "phoneNumber": null,
      "agentVersion": "6.4.2",
      "policy": {
        "id": "64ff0a1b2c3d4e5f60718293",
        "name": "Kiosk: Scanners"
      },
      "enrollment": {
        "status": "enrolled",
        "enrolledAt": "2026-03-14T08:12:44Z"
      },
      "state": {
        "lost": false,
        "compromised": false,
        "locked": false
      },
      "compliance": {
        "policyCompliant": true,
        "appsCompliant": false
      },
      "tags": {
        "tag1": "Dock 4",
        "tag3": "Night shift"
      },
      "lastSeenAt": "2026-10-07T09:29:51Z",
      "connectivity": {
        "status": "online",
        "thresholdMinutes": 1440
      },
      "createdAt": "2026-03-14T08:10:02Z",
      "details": {
        "deviceIdType": "IMEI",
        "suspended": false,
        "wiped": false,
        "enterpriseEnrolled": true,
        "appliedPolicyVersion": 42,
        "mobileDataUsageBytes": 1288490188,
        "wifiDataUsageBytes": 9663676416,
        "batteryLevel": 87
      }
    }
  ],
  "hasMore": true,
  "nextCursor": "YzE6NjUyM2YxYzJhN2I5ZDQwMDEyMzQ1Njc4"
}

Errors

404resource_not_found
No policy with this id exists in your account.
400invalid_parameter
limit, includeTotal or a filter has an invalid value, or a parameter was sent twice.
400unknown_parameter
The request includes a query parameter this endpoint does not accept.
400invalid_cursor
The cursor is malformed or was issued for different filters.
403insufficient_scope
The key lacks policies:read or devices:read.

Common errors

Besides the errors listed for each endpoint, any request can fail authentication, exceed the rate limit, ask for a format other than JSON, or fail with a server error. See Errors for the response format and retry guidance.

401missing_credentials
The request has no Authorization header.
401invalid_authorization_header
The Authorization header does not use the Bearer scheme, or has no key after it. The WWW-Authenticate header carries error="invalid_request".
401invalid_api_key
The key is malformed, does not exist, or its secret does not match. The WWW-Authenticate header carries error="invalid_token".
401api_key_expired
The key is past its expiresAt.
401api_key_revoked
An account admin revoked the key. Revocation takes effect immediately and cannot be undone.
403account_inactive
The WeGuard account that owns the key has been deleted or disabled.
406not_acceptable
The Accept header excludes JSON.
429rate_limit_exceeded
The key has used up its request budget. See Rate limits.
500internal_error
An unexpected error occurred on our side.
503service_unavailable
A service WeGuard depends on is temporarily unavailable, or reading the data took longer than the time WeGuard allows for it. This can also happen while your key is being checked, so it can be returned before authentication completes. The response carries Retry-After.

The policy object

List policies

Query parameters

Example request

Response

Errors

Retrieve a policy

Path parameters

Example request

Response

Errors

List a policy’s devices

Path parameters

Query parameters

Example request

Response

Errors

Common errors

We use cookies