Skip to main content
API docs by Redocly

Entrosity Axis Portal API (0.5.0)

Download OpenAPI specification:Download

Entrosity Axis portal REST API. This file is the source of truth for the backend server interfaces (oapi-codegen), request validation, and the frontend types (openapi-typescript). Run make gen after editing.

Authentication: Authorization: Bearer <product token>: users sign in on Entrosity Hub, which issues five-minute product tokens for Axis (POST /api/platform/v1/auth/product-token {"product":"rmm"}, with the Hub's session cookie). Users, tenants (the Hub's organizations) and roles are managed on the Hub; Axis keeps a copy.

Every route's access rule (public, authenticated, global admin, tenant permission) is declared in backend/internal/http/portal/access.go and enforced before the handler runs.

system

Liveness probe

Responses

Response samples

Content type
application/json
{
  • "status": "ok"
}

screens

Rooms whose screens the caller may watch

The rooms of Entrosity Matrix with their computers: every room for technicians and administrators, the rooms granted on Matrix's Room rights page for teachers. banner says whether the computers show the session bar: always (technicians), never (teachers) or optional (administrators choose; on by default). 503 screen_wall_unavailable: Entrosity Matrix is not configured.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "banner": "always",
  • "max_screens": 0
}

Watch a room's screens (view only, up to 30)

Starts a small view-only remote desktop session (profile wall) on each online computer of the room, at most 30, without asking the users. Open each tile's viewer WebSocket at viewer_path?ticket=<viewer_ticket> within ticket_expires_in seconds; closing it ends the session. A tile without a picture says why in status: not_in_axis (no device with that name), offline, no_agent, busy (someone is in a remote session with it; the wall never ends it), agent_too_old (the agent updates itself), unsupported or unavailable. show_banner is used for administrators only. 404: the room does not exist or is not granted to the teacher.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
firewall_id
required
string <uuid>
room
required
string [ 1 .. 64 ] characters
show_banner
boolean

Administrators: show the session bar on the computers (default true).

Responses

Request samples

Content type
application/json
{
  • "firewall_id": "5b8ae62a-9fb0-43bd-91d3-a9c16b3ec753",
  • "room": "string",
  • "show_banner": true
}

Response samples

Content type
application/json
{
  • "room": {
    },
  • "show_banner": true,
  • "omitted": 0,
  • "tiles": [
    ]
}

auth

Short-lived token for a tenant event stream (EventSource)

Returns a token valid for 60 seconds that opens GET /tenants/{tenantID}/events?sse_token= for the given tenant and the caller's session. Access to the tenant is checked when the stream opens. Keeps the access token out of URLs (proxy logs, browser history).

Authorizations:
bearerAuth
Request Body schema: application/json
required
tenant_id
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0"
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "expires_in": 0
}

The signed-in user with their tenants and roles

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "string",
  • "display_name": "string",
  • "status": "active",
  • "is_global_admin": true,
  • "memberships": [
    ],
  • "created_at": "2019-08-24T14:15:22Z"
}

admin

Cross-tenant counters

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "devices_never_connected": 0,
  • "tenants": [
    ],
  • "tenants_total": 0,
  • "tenants_active": 0,
  • "global_admins": 0,
  • "tenant_users": 0,
  • "devices_online": 0,
  • "devices_offline": 0,
  • "deployments_running": 0,
  • "alerts_open": 0
}

List tenants

Authorizations:
bearerAuth
query Parameters
page
integer [ 1 .. 100000 ]
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50
q
string <= 200 characters
status
string (TenantStatus)
Enum: "active" "suspended"

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "page_size": 0,
  • "total": 0
}

Get any tenant (including suspended ones)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "slug": "string",
  • "status": "active",
  • "settings": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Change the settings of a tenant (name and status are the Hub's)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
object (TenantSettings)

Tenant-level toggles. Unknown keys are rejected.

default_timezone
string <= 64 characters

IANA time zone for deployment maintenance windows of devices without a site (default UTC).

update_channel
string
Enum: "stable" "beta"

Which agent/connector releases the tenant's installations update to (default stable).

object (TenantRetention)

Overrides of the server's retention windows for this tenant (sent as a whole; omitted fields use the server default).

Responses

Request samples

Content type
application/json
{
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "slug": "string",
  • "status": "active",
  • "settings": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Global admins (the platform admins of Entrosity Hub)

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "users": [
    ]
}

Cross-tenant audit log

Authorizations:
bearerAuth
query Parameters
page
integer [ 1 .. 100000 ]
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50
tenant_id
string <uuid>
actor_user_id
string <uuid>
action
string <= 100 characters
resource_type
string <= 100 characters
from
string <date-time>
to
string <date-time>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "page_size": 0,
  • "total": 0
}

Global packages (visible to every tenant)

Authorizations:
bearerAuth
query Parameters
page
integer [ 1 .. 100000 ]
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50
q
string <= 200 characters
kind
string (PackageKind)
Enum: "msi" "exe" "powershell" "winget"
ready_only
boolean

Only packages that can be deployed.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "page_size": 0,
  • "total": 0
}

Create a global package

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 200 ] characters
version
string <= 100 characters
publisher
string <= 200 characters
description
string <= 2000 characters
kind
required
string (PackageKind)
Enum: "msi" "exe" "powershell" "winget"
script_content
string <= 262144 characters

PowerShell packages without a file.

winget_id
string <= 128 characters
winget_version
string <= 64 characters
winget_source
string
Enum: "winget" "msstore"
install_args
string <= 2000 characters
uninstall_args
string <= 2000 characters
success_exit_codes
Array of integers <= 20 items
object (Detection)

Decides whether the package is installed (skip before install, verify after). msi_product_code {product_code}; registry {key, value?, op?, expected?} (op exists, ==, !=, >=, >, <=, <; versions compare numerically); file {path, min_version?}; winget {id}.

requires_reboot
boolean
timeout_seconds
integer [ 60 .. 86400 ]
run_as
string
Enum: "system" "logged_on_user"
arch
string
Enum: "any" "x64" "x86" "arm64"
min_os_build
integer [ 0 .. 1000000 ]

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "version": "string",
  • "publisher": "string",
  • "description": "string",
  • "kind": "msi",
  • "script_content": "string",
  • "winget_id": "string",
  • "winget_version": "string",
  • "winget_source": "winget",
  • "install_args": "string",
  • "uninstall_args": "string",
  • "success_exit_codes": [
    ],
  • "detection": {
    },
  • "requires_reboot": true,
  • "timeout_seconds": 60,
  • "run_as": "system",
  • "arch": "any",
  • "min_os_build": 0
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "scope": "tenant",
  • "name": "string",
  • "version": "string",
  • "publisher": "string",
  • "description": "string",
  • "kind": "msi",
  • "status": "draft",
  • "file_name": "string",
  • "size_bytes": 0,
  • "sha256": "string",
  • "script_content": "string",
  • "winget_id": "string",
  • "winget_version": "string",
  • "winget_source": "string",
  • "msi_product_code": "string",
  • "install_args": "string",
  • "uninstall_args": "string",
  • "success_exit_codes": [
    ],
  • "detection": {
    },
  • "requires_reboot": true,
  • "timeout_seconds": 0,
  • "run_as": "system",
  • "arch": "any",
  • "min_os_build": 0,
  • "used_by": 0,
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Global package detail

Authorizations:
bearerAuth
path Parameters
packageID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "scope": "tenant",
  • "name": "string",
  • "version": "string",
  • "publisher": "string",
  • "description": "string",
  • "kind": "msi",
  • "status": "draft",
  • "file_name": "string",
  • "size_bytes": 0,
  • "sha256": "string",
  • "script_content": "string",
  • "winget_id": "string",
  • "winget_version": "string",
  • "winget_source": "string",
  • "msi_product_code": "string",
  • "install_args": "string",
  • "uninstall_args": "string",
  • "success_exit_codes": [
    ],
  • "detection": {
    },
  • "requires_reboot": true,
  • "timeout_seconds": 0,
  • "run_as": "system",
  • "arch": "any",
  • "min_os_build": 0,
  • "used_by": 0,
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Edit a global package

Authorizations:
bearerAuth
path Parameters
packageID
required
string <uuid>
Request Body schema: application/json
required
name
string [ 1 .. 200 ] characters
version
string <= 100 characters
publisher
string <= 200 characters
description
string <= 2000 characters
script_content
string <= 262144 characters
winget_id
string <= 128 characters
winget_version
string <= 64 characters
winget_source
string
Enum: "winget" "msstore"
install_args
string <= 2000 characters
uninstall_args
string <= 2000 characters
success_exit_codes
Array of integers <= 20 items
object (Detection)

Decides whether the package is installed (skip before install, verify after). msi_product_code {product_code}; registry {key, value?, op?, expected?} (op exists, ==, !=, >=, >, <=, <; versions compare numerically); file {path, min_version?}; winget {id}.

clear_detection
boolean
requires_reboot
boolean
timeout_seconds
integer [ 60 .. 86400 ]
run_as
string
Enum: "system" "logged_on_user"
arch
string
Enum: "any" "x64" "x86" "arm64"
min_os_build
integer [ 0 .. 1000000 ]

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "version": "string",
  • "publisher": "string",
  • "description": "string",
  • "script_content": "string",
  • "winget_id": "string",
  • "winget_version": "string",
  • "winget_source": "winget",
  • "install_args": "string",
  • "uninstall_args": "string",
  • "success_exit_codes": [
    ],
  • "detection": {
    },
  • "clear_detection": true,
  • "requires_reboot": true,
  • "timeout_seconds": 60,
  • "run_as": "system",
  • "arch": "any",
  • "min_os_build": 0
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "scope": "tenant",
  • "name": "string",
  • "version": "string",
  • "publisher": "string",
  • "description": "string",
  • "kind": "msi",
  • "status": "draft",
  • "file_name": "string",
  • "size_bytes": 0,
  • "sha256": "string",
  • "script_content": "string",
  • "winget_id": "string",
  • "winget_version": "string",
  • "winget_source": "string",
  • "msi_product_code": "string",
  • "install_args": "string",
  • "uninstall_args": "string",
  • "success_exit_codes": [
    ],
  • "detection": {
    },
  • "requires_reboot": true,
  • "timeout_seconds": 0,
  • "run_as": "system",
  • "arch": "any",
  • "min_os_build": 0,
  • "used_by": 0,
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a global package (409 package_in_use)

Authorizations:
bearerAuth
path Parameters
packageID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Presigned PUT for a global package file

Authorizations:
bearerAuth
path Parameters
packageID
required
string <uuid>
Request Body schema: application/json
required
file_name
required
string [ 1 .. 255 ] characters
size_bytes
required
integer <int64> [ 1 .. 4294967296 ]
content_type
string <= 100 characters

Responses

Request samples

Content type
application/json
{
  • "file_name": "string",
  • "size_bytes": 1,
  • "content_type": "string"
}

Response samples

Content type
application/json
{
  • "url": "string",
  • "headers": {
    },
  • "object_key": "string",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Verify a global package upload and mark it ready

Authorizations:
bearerAuth
path Parameters
packageID
required
string <uuid>
Request Body schema: application/json
required
object_key
required
string <= 512 characters
sha256
required
string^[0-9a-fA-F]{64}$

Responses

Request samples

Content type
application/json
{
  • "object_key": "string",
  • "sha256": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "scope": "tenant",
  • "name": "string",
  • "version": "string",
  • "publisher": "string",
  • "description": "string",
  • "kind": "msi",
  • "status": "draft",
  • "file_name": "string",
  • "size_bytes": 0,
  • "sha256": "string",
  • "script_content": "string",
  • "winget_id": "string",
  • "winget_version": "string",
  • "winget_source": "string",
  • "msi_product_code": "string",
  • "install_args": "string",
  • "uninstall_args": "string",
  • "success_exit_codes": [
    ],
  • "detection": {
    },
  • "requires_reboot": true,
  • "timeout_seconds": 0,
  • "run_as": "system",
  • "arch": "any",
  • "min_os_build": 0,
  • "used_by": 0,
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Search the cached winget index (global package library)

Authorizations:
bearerAuth
query Parameters
q
string <= 100 characters

2-100 characters (optional in the schema so access checks run first; 422 when missing).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Agent and connector releases, version adoption and the release public key

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "adoption": [
    ],
  • "public_key": "string"
}

Declare a release and get a presigned upload for its MSI

Global admins, or release automation with Authorization: Bearer <RMM_RELEASE_TOKEN>. PUT the MSI to upload.url with upload.headers, then POST .../publish.

Authorizations:
bearerAuth
Request Body schema: application/json
required
component
required
string
Enum: "agent" "connector"
version
required
string <= 64 characters
channel
string
Enum: "stable" "beta"
notes
string <= 4000 characters
sha256
required
string^[0-9a-fA-F]{64}$
size_bytes
required
integer <int64> [ 1 .. 524288000 ]
rollout_pct
integer [ 0 .. 100 ]

Responses

Request samples

Content type
application/json
{
  • "component": "agent",
  • "version": "string",
  • "channel": "stable",
  • "notes": "string",
  • "sha256": "string",
  • "size_bytes": 1,
  • "rollout_pct": 0
}

Response samples

Content type
application/json
{
  • "release": {
    },
  • "upload": {
    }
}

Change rollout percentage, channel or notes

Authorizations:
bearerAuth
path Parameters
releaseID
required
string <uuid>
Request Body schema: application/json
required
channel
string
Enum: "stable" "beta"
notes
string <= 4000 characters
rollout_pct
integer [ 0 .. 100 ]

Responses

Request samples

Content type
application/json
{
  • "channel": "stable",
  • "notes": "string",
  • "rollout_pct": 0
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "component": "agent",
  • "version": "string",
  • "channel": "stable",
  • "status": "draft",
  • "size_bytes": 0,
  • "sha256": "string",
  • "signature": "string",
  • "notes": "string",
  • "rollout_pct": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "published_at": "2019-08-24T14:15:22Z"
}

Delete a release and its MSI

Authorizations:
bearerAuth
path Parameters
releaseID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Verify the uploaded MSI, sign the manifest and publish

409 codes: upload_missing, upload_mismatch, signing_key_missing, not_draft.

Authorizations:
bearerAuth
path Parameters
releaseID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "component": "agent",
  • "version": "string",
  • "channel": "stable",
  • "status": "draft",
  • "size_bytes": 0,
  • "sha256": "string",
  • "signature": "string",
  • "notes": "string",
  • "rollout_pct": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "published_at": "2019-08-24T14:15:22Z"
}

A one-hour download link for a release MSI

Global admins only (not the release automation token). The link is presigned for one hour and the browser saves the file as file_name (rmm-<component>-<version>.msi). Drafts can be downloaded once their MSI is uploaded. Each link is audited as release.download. 409 codes: upload_missing, storage_unavailable.

Authorizations:
bearerAuth
path Parameters
releaseID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "download_url": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "file_name": "string"
}

Global alert rules (evaluated for every tenant)

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create a global rule

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 200 ] characters
type
required
string (AlertRuleType)
Enum: "device_offline" "disk_free_pct" "agent_outdated" "cpu_pct" "mem_pct" "cpu_temp" "deployment_failed" "adsync_failed" "connector_offline"
object (AlertCondition)

Parameters by rule type — device_offline {minutes (default 60)}; disk_free_pct {below, drive?}; agent_outdated {min_version? (default: latest stable agent release)}; cpu_pct / mem_pct {above, minutes (default 15)}; cpu_temp {above_c (default 90), minutes (default 10)}; deployment_failed {threshold_pct (default 20)}; adsync_failed {}; connector_offline {minutes (default 15)}.

severity
string (AlertSeverity)
Enum: "info" "warning" "critical"
enabled
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "type": "device_offline",
  • "condition": {
    },
  • "severity": "info",
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "scope": "tenant",
  • "name": "string",
  • "type": "device_offline",
  • "condition": {
    },
  • "severity": "info",
  • "enabled": true,
  • "enabled_for_tenant": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Edit a global rule

Authorizations:
bearerAuth
path Parameters
ruleID
required
string <uuid>
Request Body schema: application/json
required
name
string [ 1 .. 200 ] characters
object (AlertCondition)

Parameters by rule type — device_offline {minutes (default 60)}; disk_free_pct {below, drive?}; agent_outdated {min_version? (default: latest stable agent release)}; cpu_pct / mem_pct {above, minutes (default 15)}; cpu_temp {above_c (default 90), minutes (default 10)}; deployment_failed {threshold_pct (default 20)}; adsync_failed {}; connector_offline {minutes (default 15)}.

severity
string (AlertSeverity)
Enum: "info" "warning" "critical"
enabled
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "condition": {
    },
  • "severity": "info",
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "scope": "tenant",
  • "name": "string",
  • "type": "device_offline",
  • "condition": {
    },
  • "severity": "info",
  • "enabled": true,
  • "enabled_for_tenant": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a global rule (and its alerts in every tenant)

Authorizations:
bearerAuth
path Parameters
ruleID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Global script library

Authorizations:
bearerAuth
query Parameters
page
integer [ 1 .. 100000 ]
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50
q
string <= 200 characters
language
string (ScriptLanguage)
Enum: "powershell" "pwsh" "cmd"

pwsh runs PowerShell 7 when installed, otherwise Windows PowerShell.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "page_size": 0,
  • "total": 0
}

Add a global script (every tenant can run it)

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 200 ] characters
description
string <= 2000 characters
language
required
string (ScriptLanguage)
Enum: "powershell" "pwsh" "cmd"

pwsh runs PowerShell 7 when installed, otherwise Windows PowerShell.

content
required
string [ 1 .. 262144 ] characters
object (ScriptParamsSchema)

JSON Schema (draft-07 subset): {"type":"object","properties":{name: spec},"required":[...],"x-order":[...]} where each spec has type string|number|integer|boolean and optional title, description, default, enum (strings and numbers), maxLength (strings), minimum/maximum (numbers). Names are PowerShell identifiers; values reach the script as -Name parameters (PowerShell) and RMM_PARAM_<NAME> variables.

run_as
string
Default: "system"
Enum: "system" "logged_on_user"
timeout_seconds
integer [ 10 .. 86400 ]
Default: 600

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "language": "powershell",
  • "content": "string",
  • "params_schema": { },
  • "run_as": "system",
  • "timeout_seconds": 600
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "scope": "tenant",
  • "name": "string",
  • "description": "string",
  • "language": "powershell",
  • "content": "string",
  • "params_schema": { },
  • "run_as": "system",
  • "timeout_seconds": 0,
  • "current_version": 0,
  • "last_run_at": "2019-08-24T14:15:22Z",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Global script detail

Authorizations:
bearerAuth
path Parameters
scriptID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "scope": "tenant",
  • "name": "string",
  • "description": "string",
  • "language": "powershell",
  • "content": "string",
  • "params_schema": { },
  • "run_as": "system",
  • "timeout_seconds": 0,
  • "current_version": 0,
  • "last_run_at": "2019-08-24T14:15:22Z",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Change a global script

Authorizations:
bearerAuth
path Parameters
scriptID
required
string <uuid>
Request Body schema: application/json
required
name
string [ 1 .. 200 ] characters
description
string <= 2000 characters
language
string (ScriptLanguage)
Enum: "powershell" "pwsh" "cmd"

pwsh runs PowerShell 7 when installed, otherwise Windows PowerShell.

content
string [ 1 .. 262144 ] characters
object (ScriptParamsSchema)

JSON Schema (draft-07 subset): {"type":"object","properties":{name: spec},"required":[...],"x-order":[...]} where each spec has type string|number|integer|boolean and optional title, description, default, enum (strings and numbers), maxLength (strings), minimum/maximum (numbers). Names are PowerShell identifiers; values reach the script as -Name parameters (PowerShell) and RMM_PARAM_<NAME> variables.

run_as
string
Enum: "system" "logged_on_user"
timeout_seconds
integer [ 10 .. 86400 ]

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "language": "powershell",
  • "content": "string",
  • "params_schema": { },
  • "run_as": "system",
  • "timeout_seconds": 10
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "scope": "tenant",
  • "name": "string",
  • "description": "string",
  • "language": "powershell",
  • "content": "string",
  • "params_schema": { },
  • "run_as": "system",
  • "timeout_seconds": 0,
  • "current_version": 0,
  • "last_run_at": "2019-08-24T14:15:22Z",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a global script

Authorizations:
bearerAuth
path Parameters
scriptID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Version history of a global script

Authorizations:
bearerAuth
path Parameters
scriptID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

tenant

Tenant profile

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "slug": "string",
  • "status": "active",
  • "settings": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Change the tenant's settings (the name is the Hub's)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
object (TenantSettings)

Tenant-level toggles. Unknown keys are rejected.

default_timezone
string <= 64 characters

IANA time zone for deployment maintenance windows of devices without a site (default UTC).

update_channel
string
Enum: "stable" "beta"

Which agent/connector releases the tenant's installations update to (default stable).

object (TenantRetention)

Overrides of the server's retention windows for this tenant (sent as a whole; omitted fields use the server default).

Responses

Request samples

Content type
application/json
{
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "slug": "string",
  • "status": "active",
  • "settings": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

My alert e-mail preferences for this tenant

Defaults for global admins who are not members of the tenant.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "alert_email": "off",
  • "min_severity": "info",
  • "digest_interval": "15m",
  • "digest_hour": 0,
  • "timezone": "string",
  • "offline_batch_minutes": 5,
  • "muted_types": [
    ],
  • "notify_resolved": true,
  • "quiet_hours": {
    }
}

Set my alert e-mail preferences for this tenant (members only; 409 not_a_member)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
alert_email
required
string
Enum: "off" "immediate" "digest"

immediate mails new alerts as they open (a storm becomes one summary); digest collects them and mails them every digest_interval. Offline devices are never mailed one by one (see offline_batch_minutes).

min_severity
required
string (AlertSeverity)
Enum: "info" "warning" "critical"
digest_interval
string
Enum: "15m" "hourly" "daily"

How often digest delivery mails (daily at digest_hour). Default 15m.

digest_hour
integer [ 0 .. 23 ]

Hour of the daily digest, in timezone. Default 8.

timezone
string <= 64 characters

IANA time zone for digest_hour and quiet_hours ("" = the tenant's default time zone).

offline_batch_minutes
integer
Enum: 5 15 30 60

Default 15. Devices going offline are collected for this long and mailed together: one e-mail lists the devices that went offline and every device that is currently offline.

muted_types
Array of strings (AlertRuleType) <= 32 items unique
Items Enum: "device_offline" "disk_free_pct" "agent_outdated" "cpu_pct" "mem_pct" "cpu_temp" "deployment_failed" "adsync_failed" "connector_offline"

Alert types that are never e-mailed. Default none.

notify_resolved
boolean

Also mail when alerts resolve (devices back online are listed in the offline e-mail). Default false.

object (QuietHours)

No e-mail is sent between start and end (in timezone; end before start spans midnight). What would have been sent goes out as one summary when the quiet hours end. Critical alerts are held too unless critical_bypass.

Responses

Request samples

Content type
application/json
{
  • "alert_email": "off",
  • "min_severity": "info",
  • "digest_interval": "15m",
  • "digest_hour": 0,
  • "timezone": "string",
  • "offline_batch_minutes": 5,
  • "muted_types": [
    ],
  • "notify_resolved": true,
  • "quiet_hours": {
    }
}

Response samples

Content type
application/json
{
  • "alert_email": "off",
  • "min_severity": "info",
  • "digest_interval": "15m",
  • "digest_hour": 0,
  • "timezone": "string",
  • "offline_batch_minutes": 5,
  • "muted_types": [
    ],
  • "notify_resolved": true,
  • "quiet_hours": {
    }
}

Tenant counters and device overview

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "deployments_active": [
    ],
  • "deployments_recent": [
    ],
  • "devices_never_connected": 0,
  • "jobs_open": 0,
  • "os_breakdown": [
    ],
  • "recently_seen": [
    ],
  • "long_offline": [
    ],
  • "users_total": 0,
  • "sites_total": 0,
  • "devices_total": 0,
  • "devices_online": 0,
  • "devices_offline": 0,
  • "deployments_running": 0,
  • "alerts_open": 0,
  • "alerts_critical": 0
}

Tenant members and their roles (managed on Entrosity Hub)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "users": [
    ]
}

Sites of the tenant

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create a site

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
name
required
string [ 1 .. 200 ] characters
description
string <= 2000 characters
timezone
string [ 1 .. 64 ] characters

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "timezone": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "name": "string",
  • "description": "string",
  • "timezone": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get a site

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
siteID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "name": "string",
  • "description": "string",
  • "timezone": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update a site

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
siteID
required
string <uuid>
Request Body schema: application/json
required
name
string [ 1 .. 200 ] characters
description
string <= 2000 characters
timezone
string [ 1 .. 64 ] characters

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "timezone": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "name": "string",
  • "description": "string",
  • "timezone": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a site

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
siteID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Audit log of the tenant

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
query Parameters
page
integer [ 1 .. 100000 ]
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50
actor_user_id
string <uuid>
action
string <= 100 characters
resource_type
string <= 100 characters
from
string <date-time>
to
string <date-time>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "page_size": 0,
  • "total": 0
}

Server-sent events for the tenant

text/event-stream of event: <type> / data: <json> frames (device.status, device.inventory, device.updated, device.event, job.update) plus a comment heartbeat every 25 s. Browsers cannot set headers on EventSource: instead of the Authorization header, pass a stream token from POST /auth/sse-token as ?sse_token= (valid for a minute, for this tenant only; the stream stays open after it expires).

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
query Parameters
sse_token
string <= 4096 characters

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

enrollment

Enrollment tokens of the tenant

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create an enrollment token (the secret is returned once)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
kind
string
Default: "agent"
Enum: "agent" "connector"
label
string <= 200 characters
site_id
string <uuid>
expires_at
string <date-time>
max_uses
integer [ 1 .. 100000 ]

Responses

Request samples

Content type
application/json
{
  • "kind": "agent",
  • "label": "string",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "max_uses": 1
}

Response samples

Content type
application/json
{
  • "token": {
    },
  • "secret": "string",
  • "install_command": "string",
  • "download_url": "string"
}

Revoke an enrollment token

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
tokenID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Delete an enrollment token permanently (global admins; requires the password)

Removes the token from the list for good. Unlike revoking, nothing of the token is kept except the audit entry. Agents and connectors that enrolled with it keep working (they have their own keys). Only global admins may delete tokens, and they must confirm with their own password: they send step_up_token, which Entrosity Hub issues for the password (POST /api/platform/v1/auth/step-up, product rmm); an invalid, expired or reused one is a 422 with a step_up_token field error. Deleting the token an Active Directory sync uses for agent pushes is allowed; a new one is made for the next push.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
tokenID
required
string <uuid>
Request Body schema: application/json
required
step_up_token
required
string [ 1 .. 4096 ] characters

Responses

Request samples

Content type
application/json
{
  • "step_up_token": "string"
}

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

devices

Devices of the tenant (filtered, sorted, paginated)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
query Parameters
page
integer [ 1 .. 100000 ]
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50
q
string <= 200 characters
sort
string <= 40 characters

Column, - prefix for descending: hostname, status, os_name, last_seen_at, agent_version, last_user, created_at.

status
Array of strings (DevicePresence) <= 3 items
Items Enum: "online" "offline" "never_connected"
os
Array of strings <= 20 items [ items <= 200 characters ]
ou
string <= 500 characters
tag
Array of strings <= 20 items [ items <= 64 characters ]
site_id
string <uuid>
source
string
Enum: "agent" "ad" "both"
software
string <= 200 characters
agent_version
string <= 64 characters
last_seen_before
string <date-time>
last_seen_after
string <date-time>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "page_size": 0,
  • "total": 0
}

Run an action on many devices (ids or filter, max 5000)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
action
required
string
Enum: "inventory" "reboot" "shutdown" "add_tag" "uninstall_software" "wake"
device_ids
Array of strings <uuid> [ 1 .. 5000 ] items [ items <uuid > ]
object (DeviceFilter)
object

inventory: {kind}; reboot/shutdown: {delay_seconds, message, force}; add_tag: {tag}; uninstall_software: {software_name, silent_args}; wake: none.

Responses

Request samples

Content type
application/json
{
  • "action": "inventory",
  • "device_ids": [
    ],
  • "filter": {
    },
  • "payload": {
    }
}

Response samples

Content type
application/json
{
  • "job_ids": [
    ],
  • "affected": 0,
  • "skipped": 0,
  • "skip_reasons": {
    }
}

Device detail

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
deviceID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "display_name": "string",
  • "hostname": "string",
  • "fqdn": "string",
  • "domain": "string",
  • "machine_sid": "string",
  • "machine_guid": "string",
  • "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  • "os_name": "string",
  • "os_version": "string",
  • "os_build": "string",
  • "os_arch": "string",
  • "manufacturer": "string",
  • "model": "string",
  • "serial_number": "string",
  • "cpu_model": "string",
  • "cpu_cores": 0,
  • "ram_bytes": 0,
  • "last_boot_at": "2019-08-24T14:15:22Z",
  • "last_user": "string",
  • "ip_addresses": [
    ],
  • "mac_addresses": [
    ],
  • "status": "online",
  • "source": "agent",
  • "agent_version": "string",
  • "pending_reboot": true,
  • "last_seen_at": "2019-08-24T14:15:22Z",
  • "last_inventory_at": "2019-08-24T14:15:22Z",
  • "ad_dn": "string",
  • "ad_ou": "string",
  • "ad_enabled": true,
  • "ad_last_logon_at": "2019-08-24T14:15:22Z",
  • "tags": [
    ],
  • "custom_fields": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Edit display name, tags, custom fields or site

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
deviceID
required
string <uuid>
Request Body schema: application/json
required
display_name
string <= 200 characters
tags
Array of strings <= 50 items [ items [ 1 .. 64 ] characters ]
object <= 50 properties
site_id
string <uuid>
clear_site
boolean

Remove the device from its site.

Responses

Request samples

Content type
application/json
{
  • "display_name": "string",
  • "tags": [
    ],
  • "custom_fields": {
    },
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "clear_site": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "display_name": "string",
  • "hostname": "string",
  • "fqdn": "string",
  • "domain": "string",
  • "machine_sid": "string",
  • "machine_guid": "string",
  • "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  • "os_name": "string",
  • "os_version": "string",
  • "os_build": "string",
  • "os_arch": "string",
  • "manufacturer": "string",
  • "model": "string",
  • "serial_number": "string",
  • "cpu_model": "string",
  • "cpu_cores": 0,
  • "ram_bytes": 0,
  • "last_boot_at": "2019-08-24T14:15:22Z",
  • "last_user": "string",
  • "ip_addresses": [
    ],
  • "mac_addresses": [
    ],
  • "status": "online",
  • "source": "agent",
  • "agent_version": "string",
  • "pending_reboot": true,
  • "last_seen_at": "2019-08-24T14:15:22Z",
  • "last_inventory_at": "2019-08-24T14:15:22Z",
  • "ad_dn": "string",
  • "ad_ou": "string",
  • "ad_enabled": true,
  • "ad_last_logon_at": "2019-08-24T14:15:22Z",
  • "tags": [
    ],
  • "custom_fields": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Decommission (soft delete, revoke the agent key, close its connection)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
deviceID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Installed software

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
deviceID
required
string <uuid>
query Parameters
q
string <= 200 characters

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Logical disks

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
deviceID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Network adapters

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
deviceID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Windows services

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
deviceID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Installed updates (hotfixes)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
deviceID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Local accounts

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
deviceID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Sign-ins on the device (newest first, last 7 days)

Windows sign-ins (console and Remote Desktop) reported by the agent. Entries are deleted 7 days after the sign-out; sign-ins that are still open are kept.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
deviceID
required
string <uuid>
query Parameters
limit
integer [ 1 .. 500 ]
Default: 200

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "retention_days": 0
}

Downsampled CPU, memory, disk and CPU temperature series

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
deviceID
required
string <uuid>
query Parameters
range
string
Default: "24h"
Enum: "1h" "24h" "7d" "30d"

Responses

Response samples

Content type
application/json
{
  • "range": "string",
  • "bucket_seconds": 0,
  • "points": [
    ]
}

Recent jobs of the device (newest first)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
deviceID
required
string <uuid>
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Request an inventory refresh

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
deviceID
required
string <uuid>
Request Body schema: application/json
optional
kind
string
Default: "full"
Enum: "full" "delta"

Responses

Request samples

Content type
application/json
{
  • "kind": "full"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
  • "type": "string",
  • "payload": { },
  • "status": "created",
  • "priority": 0,
  • "timeout_seconds": 0,
  • "expires_at": "2019-08-24T14:15:22Z",
  • "attempts": 0,
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "acked_at": "2019-08-24T14:15:22Z",
  • "started_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "progress_pct": 0,
  • "progress_message": "string",
  • "exit_code": 0,
  • "error_code": "string",
  • "error": "string",
  • "output_tail": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Reboot the device

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
deviceID
required
string <uuid>
Request Body schema: application/json
optional
delay_seconds
integer [ 0 .. 86400 ]
Default: 0
message
string <= 512 characters
force
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "delay_seconds": 0,
  • "message": "string",
  • "force": false
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
  • "type": "string",
  • "payload": { },
  • "status": "created",
  • "priority": 0,
  • "timeout_seconds": 0,
  • "expires_at": "2019-08-24T14:15:22Z",
  • "attempts": 0,
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "acked_at": "2019-08-24T14:15:22Z",
  • "started_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "progress_pct": 0,
  • "progress_message": "string",
  • "exit_code": 0,
  • "error_code": "string",
  • "error": "string",
  • "output_tail": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Shut the device down

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
deviceID
required
string <uuid>
Request Body schema: application/json
optional
delay_seconds
integer [ 0 .. 86400 ]
Default: 0
message
string <= 512 characters
force
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "delay_seconds": 0,
  • "message": "string",
  • "force": false
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
  • "type": "string",
  • "payload": { },
  • "status": "created",
  • "priority": 0,
  • "timeout_seconds": 0,
  • "expires_at": "2019-08-24T14:15:22Z",
  • "attempts": 0,
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "acked_at": "2019-08-24T14:15:22Z",
  • "started_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "progress_pct": 0,
  • "progress_message": "string",
  • "exit_code": 0,
  • "error_code": "string",
  • "error": "string",
  • "output_tail": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Uninstall a program from the device inventory

Uses the MSI product code (msiexec /x … /qn), the vendor's quiet uninstall string, winget, or the uninstall string with the given silent arguments. 409 codes: no_agent, software_not_found, needs_silent_args, no_uninstall_method.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
deviceID
required
string <uuid>
Request Body schema: application/json
required
software_id
required
integer <int64> >= 1

DeviceSoftware id.

silent_args
string <= 512 characters

Arguments that make the uninstall string silent (e.g. /S, /quiet, /VERYSILENT); required when the program has neither a product code nor a quiet uninstall string.

Responses

Request samples

Content type
application/json
{
  • "software_id": 1,
  • "silent_args": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
  • "type": "string",
  • "payload": { },
  • "status": "created",
  • "priority": 0,
  • "timeout_seconds": 0,
  • "expires_at": "2019-08-24T14:15:22Z",
  • "attempts": 0,
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "acked_at": "2019-08-24T14:15:22Z",
  • "started_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "progress_pct": 0,
  • "progress_message": "string",
  • "exit_code": 0,
  • "error_code": "string",
  • "error": "string",
  • "output_tail": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Wake the device (Wake-on-LAN through its site's connector)

409 codes: no_site, no_connector, no_mac_address.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
deviceID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
  • "type": "string",
  • "payload": { },
  • "status": "created",
  • "priority": 0,
  • "timeout_seconds": 0,
  • "expires_at": "2019-08-24T14:15:22Z",
  • "attempts": 0,
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "acked_at": "2019-08-24T14:15:22Z",
  • "started_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "progress_pct": 0,
  • "progress_message": "string",
  • "exit_code": 0,
  • "error_code": "string",
  • "error": "string",
  • "output_tail": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Start a remote desktop session on the device

Queues a remote_desktop job: the agent (after the signed-in user accepts, when require_consent is set) opens a stream to the server. Open the viewer WebSocket at viewer_path?ticket=<viewer_ticket> within ticket_expires_in seconds; the ticket works once. A newer session on the same device ends the older one. 403 code remote_unattended_forbidden: require_consent false or show_banner false without devices:remote_unattended (only tenant and global admins may skip the prompt or hide the session bar). 409 codes: offline, no_agent, remote_unsupported (the agent is too old or not on Windows), decommissioned.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
deviceID
required
string <uuid>
Request Body schema: application/json
required
mode
required
string
Enum: "control" "view"

view streams the screen only; the server drops input.

require_consent
boolean
Default: false

Ask the signed-in user to accept first (skipped at the sign-in screen). false needs devices:remote_unattended (administrators).

show_banner
boolean
Default: true

Show the on-screen session bar on the device (who is connected; the user can end the session). false needs devices:remote_unattended (administrators).

Responses

Request samples

Content type
application/json
{
  • "mode": "control",
  • "require_consent": false,
  • "show_banner": true
}

Response samples

Content type
application/json
{
  • "session": {
    },
  • "viewer_path": "string",
  • "viewer_ticket": "string",
  • "ticket_expires_in": 0
}

End a remote desktop session

Closes both sides of the stream. Ending a finished session is a no-op.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
sessionID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "mode": "control",
  • "require_consent": true,
  • "show_banner": true,
  • "status": "pending",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "started_at": "2019-08-24T14:15:22Z",
  • "ended_at": "2019-08-24T14:15:22Z",
  • "end_reason": "string"
}

Merge another device record into this one

This device is kept; the other one's history (jobs, deployment targets, script runs, alerts), AD link and, if it has one, its agent with inventory and metrics move over, and the other record is removed. 409 both_have_agents when both have an agent.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
deviceID
required
string <uuid>
Request Body schema: application/json
required
other_device_id
required
string <uuid>

The device merged into this one and removed.

Responses

Request samples

Content type
application/json
{
  • "other_device_id": "9d121359-236e-46b3-8432-4964dd179b14"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "display_name": "string",
  • "hostname": "string",
  • "fqdn": "string",
  • "domain": "string",
  • "machine_sid": "string",
  • "machine_guid": "string",
  • "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  • "os_name": "string",
  • "os_version": "string",
  • "os_build": "string",
  • "os_arch": "string",
  • "manufacturer": "string",
  • "model": "string",
  • "serial_number": "string",
  • "cpu_model": "string",
  • "cpu_cores": 0,
  • "ram_bytes": 0,
  • "last_boot_at": "2019-08-24T14:15:22Z",
  • "last_user": "string",
  • "ip_addresses": [
    ],
  • "mac_addresses": [
    ],
  • "status": "online",
  • "source": "agent",
  • "agent_version": "string",
  • "pending_reboot": true,
  • "last_seen_at": "2019-08-24T14:15:22Z",
  • "last_inventory_at": "2019-08-24T14:15:22Z",
  • "ad_dn": "string",
  • "ad_ou": "string",
  • "ad_enabled": true,
  • "ad_last_logon_at": "2019-08-24T14:15:22Z",
  • "tags": [
    ],
  • "custom_fields": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Job status and result

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
jobID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
  • "type": "string",
  • "payload": { },
  • "status": "created",
  • "priority": 0,
  • "timeout_seconds": 0,
  • "expires_at": "2019-08-24T14:15:22Z",
  • "attempts": 0,
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "acked_at": "2019-08-24T14:15:22Z",
  • "started_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "progress_pct": 0,
  • "progress_message": "string",
  • "exit_code": 0,
  • "error_code": "string",
  • "error": "string",
  • "output_tail": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Cancel an unfinished job (best effort on the agent)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
jobID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
  • "type": "string",
  • "payload": { },
  • "status": "created",
  • "priority": 0,
  • "timeout_seconds": 0,
  • "expires_at": "2019-08-24T14:15:22Z",
  • "attempts": 0,
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "acked_at": "2019-08-24T14:15:22Z",
  • "started_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "progress_pct": 0,
  • "progress_message": "string",
  • "exit_code": 0,
  • "error_code": "string",
  • "error": "string",
  • "output_tail": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

adsync

Site connectors of the tenant

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

One site connector

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
connectorID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "name": "string",
  • "hostname": "string",
  • "domain": "string",
  • "version": "string",
  • "capabilities": [
    ],
  • "status": "online",
  • "last_seen_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z"
}

Revoke a connector (its AD sync configurations are removed)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
connectorID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Test LDAP settings through the connector (waits up to 20 s)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
connectorID
required
string <uuid>
Request Body schema: application/json
required
ldap_host
required
string [ 1 .. 255 ] characters
ldap_port
integer [ 1 .. 65535 ]
tls_mode
required
string (TLSMode)
Enum: "ldaps" "starttls" "none"
skip_tls_verify
boolean
ca_pem
string <= 65536 characters
base_dn
required
string [ 1 .. 1024 ] characters
bind_dn
required
string [ 1 .. 1024 ] characters
bind_password
string <= 1024 characters
config_id
string <uuid>
computer_filter
string <= 1024 characters

Responses

Request samples

Content type
application/json
{
  • "ldap_host": "string",
  • "ldap_port": 1,
  • "tls_mode": "ldaps",
  • "skip_tls_verify": true,
  • "ca_pem": "string",
  • "base_dn": "string",
  • "bind_dn": "string",
  • "bind_password": "string",
  • "config_id": "d1d31429-d888-4f1c-b9c1-4e842f9bce5b",
  • "computer_filter": "string"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "error": "string",
  • "error_code": "string",
  • "computers_found": 0,
  • "server_info": "string",
  • "default_naming_context": "string"
}

List the directory's OUs with the given settings (waits up to 20 s)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
connectorID
required
string <uuid>
Request Body schema: application/json
required
ldap_host
required
string [ 1 .. 255 ] characters
ldap_port
integer [ 1 .. 65535 ]
tls_mode
required
string (TLSMode)
Enum: "ldaps" "starttls" "none"
skip_tls_verify
boolean
ca_pem
string <= 65536 characters
base_dn
required
string [ 1 .. 1024 ] characters
bind_dn
required
string [ 1 .. 1024 ] characters
bind_password
string <= 1024 characters
config_id
string <uuid>
computer_filter
string <= 1024 characters

Responses

Request samples

Content type
application/json
{
  • "ldap_host": "string",
  • "ldap_port": 1,
  • "tls_mode": "ldaps",
  • "skip_tls_verify": true,
  • "ca_pem": "string",
  • "base_dn": "string",
  • "bind_dn": "string",
  • "bind_password": "string",
  • "config_id": "d1d31429-d888-4f1c-b9c1-4e842f9bce5b",
  • "computer_filter": "string"
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

AD sync configurations

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create an AD sync configuration

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
name
required
string [ 1 .. 200 ] characters
connector_id
required
string <uuid>
site_id
string or null <uuid>
enabled
boolean
Default: true
ldap_host
required
string [ 1 .. 255 ] characters
ldap_port
integer [ 1 .. 65535 ]
tls_mode
required
string (TLSMode)
Enum: "ldaps" "starttls" "none"
skip_tls_verify
boolean
ca_pem
string <= 65536 characters
base_dn
required
string [ 1 .. 1024 ] characters
bind_dn
required
string [ 1 .. 1024 ] characters
bind_password
string <= 1024 characters

Required on create; omit on update to keep the stored password.

computer_filter
string <= 1024 characters
ou_include
Array of strings <= 500 items [ items <= 2048 characters ]
ou_exclude
Array of strings <= 500 items [ items <= 2048 characters ]
interval_minutes
integer [ 5 .. 10080 ]
Default: 60
auto_push_agent
boolean
push_username
string <= 256 characters
push_password
string <= 1024 characters

Omit on update to keep the stored password.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "enabled": true,
  • "ldap_host": "string",
  • "ldap_port": 1,
  • "tls_mode": "ldaps",
  • "skip_tls_verify": true,
  • "ca_pem": "string",
  • "base_dn": "string",
  • "bind_dn": "string",
  • "bind_password": "string",
  • "computer_filter": "string",
  • "ou_include": [
    ],
  • "ou_exclude": [
    ],
  • "interval_minutes": 60,
  • "auto_push_agent": true,
  • "push_username": "string",
  • "push_password": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "connector_hostname": "string",
  • "connector_status": "string",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "enabled": true,
  • "ldap_host": "string",
  • "ldap_port": 0,
  • "tls_mode": "ldaps",
  • "skip_tls_verify": true,
  • "ca_pem": "string",
  • "base_dn": "string",
  • "bind_dn": "string",
  • "bind_password_set": true,
  • "computer_filter": "string",
  • "ou_include": [
    ],
  • "ou_exclude": [
    ],
  • "interval_minutes": 0,
  • "auto_push_agent": true,
  • "push_username": "string",
  • "push_password_set": true,
  • "last_sync_at": "2019-08-24T14:15:22Z",
  • "last_sync_status": "string",
  • "consecutive_failures": 0,
  • "next_sync_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

One AD sync configuration

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
configID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "connector_hostname": "string",
  • "connector_status": "string",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "enabled": true,
  • "ldap_host": "string",
  • "ldap_port": 0,
  • "tls_mode": "ldaps",
  • "skip_tls_verify": true,
  • "ca_pem": "string",
  • "base_dn": "string",
  • "bind_dn": "string",
  • "bind_password_set": true,
  • "computer_filter": "string",
  • "ou_include": [
    ],
  • "ou_exclude": [
    ],
  • "interval_minutes": 0,
  • "auto_push_agent": true,
  • "push_username": "string",
  • "push_password_set": true,
  • "last_sync_at": "2019-08-24T14:15:22Z",
  • "last_sync_status": "string",
  • "consecutive_failures": 0,
  • "next_sync_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Replace an AD sync configuration (omitted passwords are kept)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
configID
required
string <uuid>
Request Body schema: application/json
required
name
required
string [ 1 .. 200 ] characters
connector_id
required
string <uuid>
site_id
string or null <uuid>
enabled
boolean
Default: true
ldap_host
required
string [ 1 .. 255 ] characters
ldap_port
integer [ 1 .. 65535 ]
tls_mode
required
string (TLSMode)
Enum: "ldaps" "starttls" "none"
skip_tls_verify
boolean
ca_pem
string <= 65536 characters
base_dn
required
string [ 1 .. 1024 ] characters
bind_dn
required
string [ 1 .. 1024 ] characters
bind_password
string <= 1024 characters

Required on create; omit on update to keep the stored password.

computer_filter
string <= 1024 characters
ou_include
Array of strings <= 500 items [ items <= 2048 characters ]
ou_exclude
Array of strings <= 500 items [ items <= 2048 characters ]
interval_minutes
integer [ 5 .. 10080 ]
Default: 60
auto_push_agent
boolean
push_username
string <= 256 characters
push_password
string <= 1024 characters

Omit on update to keep the stored password.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "enabled": true,
  • "ldap_host": "string",
  • "ldap_port": 1,
  • "tls_mode": "ldaps",
  • "skip_tls_verify": true,
  • "ca_pem": "string",
  • "base_dn": "string",
  • "bind_dn": "string",
  • "bind_password": "string",
  • "computer_filter": "string",
  • "ou_include": [
    ],
  • "ou_exclude": [
    ],
  • "interval_minutes": 60,
  • "auto_push_agent": true,
  • "push_username": "string",
  • "push_password": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "connector_hostname": "string",
  • "connector_status": "string",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "enabled": true,
  • "ldap_host": "string",
  • "ldap_port": 0,
  • "tls_mode": "ldaps",
  • "skip_tls_verify": true,
  • "ca_pem": "string",
  • "base_dn": "string",
  • "bind_dn": "string",
  • "bind_password_set": true,
  • "computer_filter": "string",
  • "ou_include": [
    ],
  • "ou_exclude": [
    ],
  • "interval_minutes": 0,
  • "auto_push_agent": true,
  • "push_username": "string",
  • "push_password_set": true,
  • "last_sync_at": "2019-08-24T14:15:22Z",
  • "last_sync_status": "string",
  • "consecutive_failures": 0,
  • "next_sync_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete an AD sync configuration and its mirrored computers

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
configID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Start a sync now (409 when the connector is offline or a run is active)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
configID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "config_id": "d1d31429-d888-4f1c-b9c1-4e842f9bce5b",
  • "trigger": "manual",
  • "status": "pending",
  • "seen": 0,
  • "created_count": 0,
  • "updated_count": 0,
  • "gone_count": 0,
  • "matched_count": 0,
  • "error_code": "string",
  • "error_text": "string",
  • "started_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z"
}

Recent runs of a configuration (newest first, max 100)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
configID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

The directory's OUs using the stored settings (waits up to 20 s)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
configID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Computers mirrored from Active Directory

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
query Parameters
page
integer [ 1 .. 100000 ]
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50
q
string <= 200 characters
config_id
string <uuid>
ou
string <= 2048 characters
enabled
boolean
gone
boolean
unmanaged
boolean

true for computers without an agent-managed device.

push
string
Enum: "none" "pending" "success" "failed"

Agent push state: none (never pushed), pending (queued or in progress), success, failed.

push_error_code
string <= 64 characters

Only failed pushes with this error code (see the error codes reference).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "page_size": 0,
  • "total": 0
}

How many AD computers run the agent, and why the others do not

Counts for an OU (and every OU below it) and/or a domain configuration, or the whole tenant. The push counts and the failures by error code cover present computers that still have no agent: the ones that need attention.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
query Parameters
config_id
string <uuid>
ou
string <= 2048 characters

Responses

Response samples

Content type
application/json
{
  • "present": 0,
  • "managed": 0,
  • "unmanaged": 0,
  • "disabled": 0,
  • "gone": 0,
  • "never_pushed": 0,
  • "pushing": 0,
  • "push_failed": 0,
  • "failures": [
    ]
}

OUs that contain synced computers (for filters)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Install the agent on AD computers through their connector

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
ad_computer_ids
Array of strings <uuid> <= 500 items [ items <uuid > ]
device_ids
Array of strings <uuid> <= 500 items [ items <uuid > ]

Responses

Request samples

Content type
application/json
{
  • "ad_computer_ids": [
    ],
  • "device_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "job_ids": [
    ],
  • "queued": 0,
  • "skipped": [
    ]
}

packages

Global packages (visible to every tenant)

Authorizations:
bearerAuth
query Parameters
page
integer [ 1 .. 100000 ]
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50
q
string <= 200 characters
kind
string (PackageKind)
Enum: "msi" "exe" "powershell" "winget"
ready_only
boolean

Only packages that can be deployed.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "page_size": 0,
  • "total": 0
}

Create a global package

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 200 ] characters
version
string <= 100 characters
publisher
string <= 200 characters
description
string <= 2000 characters
kind
required
string (PackageKind)
Enum: "msi" "exe" "powershell" "winget"
script_content
string <= 262144 characters

PowerShell packages without a file.

winget_id
string <= 128 characters
winget_version
string <= 64 characters
winget_source
string
Enum: "winget" "msstore"
install_args
string <= 2000 characters
uninstall_args
string <= 2000 characters
success_exit_codes
Array of integers <= 20 items
object (Detection)

Decides whether the package is installed (skip before install, verify after). msi_product_code {product_code}; registry {key, value?, op?, expected?} (op exists, ==, !=, >=, >, <=, <; versions compare numerically); file {path, min_version?}; winget {id}.

requires_reboot
boolean
timeout_seconds
integer [ 60 .. 86400 ]
run_as
string
Enum: "system" "logged_on_user"
arch
string
Enum: "any" "x64" "x86" "arm64"
min_os_build
integer [ 0 .. 1000000 ]

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "version": "string",
  • "publisher": "string",
  • "description": "string",
  • "kind": "msi",
  • "script_content": "string",
  • "winget_id": "string",
  • "winget_version": "string",
  • "winget_source": "winget",
  • "install_args": "string",
  • "uninstall_args": "string",
  • "success_exit_codes": [
    ],
  • "detection": {
    },
  • "requires_reboot": true,
  • "timeout_seconds": 60,
  • "run_as": "system",
  • "arch": "any",
  • "min_os_build": 0
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "scope": "tenant",
  • "name": "string",
  • "version": "string",
  • "publisher": "string",
  • "description": "string",
  • "kind": "msi",
  • "status": "draft",
  • "file_name": "string",
  • "size_bytes": 0,
  • "sha256": "string",
  • "script_content": "string",
  • "winget_id": "string",
  • "winget_version": "string",
  • "winget_source": "string",
  • "msi_product_code": "string",
  • "install_args": "string",
  • "uninstall_args": "string",
  • "success_exit_codes": [
    ],
  • "detection": {
    },
  • "requires_reboot": true,
  • "timeout_seconds": 0,
  • "run_as": "system",
  • "arch": "any",
  • "min_os_build": 0,
  • "used_by": 0,
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Global package detail

Authorizations:
bearerAuth
path Parameters
packageID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "scope": "tenant",
  • "name": "string",
  • "version": "string",
  • "publisher": "string",
  • "description": "string",
  • "kind": "msi",
  • "status": "draft",
  • "file_name": "string",
  • "size_bytes": 0,
  • "sha256": "string",
  • "script_content": "string",
  • "winget_id": "string",
  • "winget_version": "string",
  • "winget_source": "string",
  • "msi_product_code": "string",
  • "install_args": "string",
  • "uninstall_args": "string",
  • "success_exit_codes": [
    ],
  • "detection": {
    },
  • "requires_reboot": true,
  • "timeout_seconds": 0,
  • "run_as": "system",
  • "arch": "any",
  • "min_os_build": 0,
  • "used_by": 0,
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Edit a global package

Authorizations:
bearerAuth
path Parameters
packageID
required
string <uuid>
Request Body schema: application/json
required
name
string [ 1 .. 200 ] characters
version
string <= 100 characters
publisher
string <= 200 characters
description
string <= 2000 characters
script_content
string <= 262144 characters
winget_id
string <= 128 characters
winget_version
string <= 64 characters
winget_source
string
Enum: "winget" "msstore"
install_args
string <= 2000 characters
uninstall_args
string <= 2000 characters
success_exit_codes
Array of integers <= 20 items
object (Detection)

Decides whether the package is installed (skip before install, verify after). msi_product_code {product_code}; registry {key, value?, op?, expected?} (op exists, ==, !=, >=, >, <=, <; versions compare numerically); file {path, min_version?}; winget {id}.

clear_detection
boolean
requires_reboot
boolean
timeout_seconds
integer [ 60 .. 86400 ]
run_as
string
Enum: "system" "logged_on_user"
arch
string
Enum: "any" "x64" "x86" "arm64"
min_os_build
integer [ 0 .. 1000000 ]

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "version": "string",
  • "publisher": "string",
  • "description": "string",
  • "script_content": "string",
  • "winget_id": "string",
  • "winget_version": "string",
  • "winget_source": "winget",
  • "install_args": "string",
  • "uninstall_args": "string",
  • "success_exit_codes": [
    ],
  • "detection": {
    },
  • "clear_detection": true,
  • "requires_reboot": true,
  • "timeout_seconds": 60,
  • "run_as": "system",
  • "arch": "any",
  • "min_os_build": 0
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "scope": "tenant",
  • "name": "string",
  • "version": "string",
  • "publisher": "string",
  • "description": "string",
  • "kind": "msi",
  • "status": "draft",
  • "file_name": "string",
  • "size_bytes": 0,
  • "sha256": "string",
  • "script_content": "string",
  • "winget_id": "string",
  • "winget_version": "string",
  • "winget_source": "string",
  • "msi_product_code": "string",
  • "install_args": "string",
  • "uninstall_args": "string",
  • "success_exit_codes": [
    ],
  • "detection": {
    },
  • "requires_reboot": true,
  • "timeout_seconds": 0,
  • "run_as": "system",
  • "arch": "any",
  • "min_os_build": 0,
  • "used_by": 0,
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a global package (409 package_in_use)

Authorizations:
bearerAuth
path Parameters
packageID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Presigned PUT for a global package file

Authorizations:
bearerAuth
path Parameters
packageID
required
string <uuid>
Request Body schema: application/json
required
file_name
required
string [ 1 .. 255 ] characters
size_bytes
required
integer <int64> [ 1 .. 4294967296 ]
content_type
string <= 100 characters

Responses

Request samples

Content type
application/json
{
  • "file_name": "string",
  • "size_bytes": 1,
  • "content_type": "string"
}

Response samples

Content type
application/json
{
  • "url": "string",
  • "headers": {
    },
  • "object_key": "string",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Verify a global package upload and mark it ready

Authorizations:
bearerAuth
path Parameters
packageID
required
string <uuid>
Request Body schema: application/json
required
object_key
required
string <= 512 characters
sha256
required
string^[0-9a-fA-F]{64}$

Responses

Request samples

Content type
application/json
{
  • "object_key": "string",
  • "sha256": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "scope": "tenant",
  • "name": "string",
  • "version": "string",
  • "publisher": "string",
  • "description": "string",
  • "kind": "msi",
  • "status": "draft",
  • "file_name": "string",
  • "size_bytes": 0,
  • "sha256": "string",
  • "script_content": "string",
  • "winget_id": "string",
  • "winget_version": "string",
  • "winget_source": "string",
  • "msi_product_code": "string",
  • "install_args": "string",
  • "uninstall_args": "string",
  • "success_exit_codes": [
    ],
  • "detection": {
    },
  • "requires_reboot": true,
  • "timeout_seconds": 0,
  • "run_as": "system",
  • "arch": "any",
  • "min_os_build": 0,
  • "used_by": 0,
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Search the cached winget index (global package library)

Authorizations:
bearerAuth
query Parameters
q
string <= 100 characters

2-100 characters (optional in the schema so access checks run first; 422 when missing).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Packages of the tenant plus global packages (`scope` tells which)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
query Parameters
page
integer [ 1 .. 100000 ]
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50
q
string <= 200 characters
kind
string (PackageKind)
Enum: "msi" "exe" "powershell" "winget"
ready_only
boolean

Only packages that can be deployed.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "page_size": 0,
  • "total": 0
}

Create a package (file kinds start as draft until finalize)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
name
required
string [ 1 .. 200 ] characters
version
string <= 100 characters
publisher
string <= 200 characters
description
string <= 2000 characters
kind
required
string (PackageKind)
Enum: "msi" "exe" "powershell" "winget"
script_content
string <= 262144 characters

PowerShell packages without a file.

winget_id
string <= 128 characters
winget_version
string <= 64 characters
winget_source
string
Enum: "winget" "msstore"
install_args
string <= 2000 characters
uninstall_args
string <= 2000 characters
success_exit_codes
Array of integers <= 20 items
object (Detection)

Decides whether the package is installed (skip before install, verify after). msi_product_code {product_code}; registry {key, value?, op?, expected?} (op exists, ==, !=, >=, >, <=, <; versions compare numerically); file {path, min_version?}; winget {id}.

requires_reboot
boolean
timeout_seconds
integer [ 60 .. 86400 ]
run_as
string
Enum: "system" "logged_on_user"
arch
string
Enum: "any" "x64" "x86" "arm64"
min_os_build
integer [ 0 .. 1000000 ]

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "version": "string",
  • "publisher": "string",
  • "description": "string",
  • "kind": "msi",
  • "script_content": "string",
  • "winget_id": "string",
  • "winget_version": "string",
  • "winget_source": "winget",
  • "install_args": "string",
  • "uninstall_args": "string",
  • "success_exit_codes": [
    ],
  • "detection": {
    },
  • "requires_reboot": true,
  • "timeout_seconds": 60,
  • "run_as": "system",
  • "arch": "any",
  • "min_os_build": 0
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "scope": "tenant",
  • "name": "string",
  • "version": "string",
  • "publisher": "string",
  • "description": "string",
  • "kind": "msi",
  • "status": "draft",
  • "file_name": "string",
  • "size_bytes": 0,
  • "sha256": "string",
  • "script_content": "string",
  • "winget_id": "string",
  • "winget_version": "string",
  • "winget_source": "string",
  • "msi_product_code": "string",
  • "install_args": "string",
  • "uninstall_args": "string",
  • "success_exit_codes": [
    ],
  • "detection": {
    },
  • "requires_reboot": true,
  • "timeout_seconds": 0,
  • "run_as": "system",
  • "arch": "any",
  • "min_os_build": 0,
  • "used_by": 0,
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Package detail (tenant or global)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
packageID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "scope": "tenant",
  • "name": "string",
  • "version": "string",
  • "publisher": "string",
  • "description": "string",
  • "kind": "msi",
  • "status": "draft",
  • "file_name": "string",
  • "size_bytes": 0,
  • "sha256": "string",
  • "script_content": "string",
  • "winget_id": "string",
  • "winget_version": "string",
  • "winget_source": "string",
  • "msi_product_code": "string",
  • "install_args": "string",
  • "uninstall_args": "string",
  • "success_exit_codes": [
    ],
  • "detection": {
    },
  • "requires_reboot": true,
  • "timeout_seconds": 0,
  • "run_as": "system",
  • "arch": "any",
  • "min_os_build": 0,
  • "used_by": 0,
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Edit package metadata (omitted fields keep their value; global packages are read-only here)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
packageID
required
string <uuid>
Request Body schema: application/json
required
name
string [ 1 .. 200 ] characters
version
string <= 100 characters
publisher
string <= 200 characters
description
string <= 2000 characters
script_content
string <= 262144 characters
winget_id
string <= 128 characters
winget_version
string <= 64 characters
winget_source
string
Enum: "winget" "msstore"
install_args
string <= 2000 characters
uninstall_args
string <= 2000 characters
success_exit_codes
Array of integers <= 20 items
object (Detection)

Decides whether the package is installed (skip before install, verify after). msi_product_code {product_code}; registry {key, value?, op?, expected?} (op exists, ==, !=, >=, >, <=, <; versions compare numerically); file {path, min_version?}; winget {id}.

clear_detection
boolean
requires_reboot
boolean
timeout_seconds
integer [ 60 .. 86400 ]
run_as
string
Enum: "system" "logged_on_user"
arch
string
Enum: "any" "x64" "x86" "arm64"
min_os_build
integer [ 0 .. 1000000 ]

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "version": "string",
  • "publisher": "string",
  • "description": "string",
  • "script_content": "string",
  • "winget_id": "string",
  • "winget_version": "string",
  • "winget_source": "winget",
  • "install_args": "string",
  • "uninstall_args": "string",
  • "success_exit_codes": [
    ],
  • "detection": {
    },
  • "clear_detection": true,
  • "requires_reboot": true,
  • "timeout_seconds": 60,
  • "run_as": "system",
  • "arch": "any",
  • "min_os_build": 0
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "scope": "tenant",
  • "name": "string",
  • "version": "string",
  • "publisher": "string",
  • "description": "string",
  • "kind": "msi",
  • "status": "draft",
  • "file_name": "string",
  • "size_bytes": 0,
  • "sha256": "string",
  • "script_content": "string",
  • "winget_id": "string",
  • "winget_version": "string",
  • "winget_source": "string",
  • "msi_product_code": "string",
  • "install_args": "string",
  • "uninstall_args": "string",
  • "success_exit_codes": [
    ],
  • "detection": {
    },
  • "requires_reboot": true,
  • "timeout_seconds": 0,
  • "run_as": "system",
  • "arch": "any",
  • "min_os_build": 0,
  • "used_by": 0,
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a package (409 package_in_use while a deployment that has not finished uses it)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
packageID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Presigned PUT for the package file (draft packages; max 4 GiB)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
packageID
required
string <uuid>
Request Body schema: application/json
required
file_name
required
string [ 1 .. 255 ] characters
size_bytes
required
integer <int64> [ 1 .. 4294967296 ]
content_type
string <= 100 characters

Responses

Request samples

Content type
application/json
{
  • "file_name": "string",
  • "size_bytes": 1,
  • "content_type": "string"
}

Response samples

Content type
application/json
{
  • "url": "string",
  • "headers": {
    },
  • "object_key": "string",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Verify the uploaded file (size, SHA-256; MSI metadata) and mark the package ready

422 hash_mismatch, size_mismatch, upload_missing or object_key_mismatch leave the package draft.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
packageID
required
string <uuid>
Request Body schema: application/json
required
object_key
required
string <= 512 characters
sha256
required
string^[0-9a-fA-F]{64}$

Responses

Request samples

Content type
application/json
{
  • "object_key": "string",
  • "sha256": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "scope": "tenant",
  • "name": "string",
  • "version": "string",
  • "publisher": "string",
  • "description": "string",
  • "kind": "msi",
  • "status": "draft",
  • "file_name": "string",
  • "size_bytes": 0,
  • "sha256": "string",
  • "script_content": "string",
  • "winget_id": "string",
  • "winget_version": "string",
  • "winget_source": "string",
  • "msi_product_code": "string",
  • "install_args": "string",
  • "uninstall_args": "string",
  • "success_exit_codes": [
    ],
  • "detection": {
    },
  • "requires_reboot": true,
  • "timeout_seconds": 0,
  • "run_as": "system",
  • "arch": "any",
  • "min_os_build": 0,
  • "used_by": 0,
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Search the cached winget index (25 results; 503 winget_index_unavailable when never loaded)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
query Parameters
q
string <= 100 characters

2-100 characters (optional in the schema so access checks run first; 422 when missing).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

deployments

Resolve targets without creating anything (count, first 50 hostnames, exclusions)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
target_kind
required
string
Enum: "all" "devices" "filter"
device_ids
Array of strings <uuid> [ 1 .. 20000 ] items [ items <uuid > ]
object (DeploymentTargetFilter)

The device list filters plus software present/absent.

Responses

Request samples

Content type
application/json
{
  • "target_kind": "all",
  • "device_ids": [
    ],
  • "target_filter": {
    }
}

Response samples

Content type
application/json
{
  • "count": 0,
  • "sample": [
    ],
  • "excluded": {
    }
}

Deployments, newest first, with counters

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
query Parameters
page
integer [ 1 .. 100000 ]
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50
q
string <= 200 characters
status
Array of strings (DeploymentStatus) <= 7 items
Items Enum: "draft" "scheduled" "running" "paused" "completed" "cancelled" "failed"
package_id
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "page_size": 0,
  • "total": 0
}

Create a deployment (starts at once for schedule_kind now)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
name
required
string [ 1 .. 200 ] characters
package_id
required
string <uuid>
action
string
Default: "install"
Enum: "install" "uninstall"
target_kind
required
string
Enum: "all" "devices" "filter"
device_ids
Array of strings <uuid> [ 1 .. 20000 ] items [ items <uuid > ]
object (DeploymentTargetFilter)

The device list filters plus software present/absent.

schedule_kind
string
Default: "now"
Enum: "now" "at" "window"
scheduled_at
string <date-time>
window_start
string^([01][0-9]|2[0-3]):[0-5][0-9]$

HH:MM in each device's site timezone.

window_end
string^([01][0-9]|2[0-3]):[0-5][0-9]$
reboot_policy
string
Default: "never"
Enum: "never" "if_required" "always"
max_concurrency
integer [ 1 .. 1000 ]
Default: 50
retry_count
integer [ 0 .. 10 ]
Default: 0
retry_backoff_seconds
integer [ 0 .. 86400 ]
Default: 300
expires_after_hours
integer [ 1 .. 720 ]
Default: 72

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "package_id": "82585450-66a8-4ff2-8a7e-8e7bec960ae1",
  • "action": "install",
  • "target_kind": "all",
  • "device_ids": [
    ],
  • "target_filter": {
    },
  • "schedule_kind": "now",
  • "scheduled_at": "2019-08-24T14:15:22Z",
  • "window_start": "string",
  • "window_end": "string",
  • "reboot_policy": "never",
  • "max_concurrency": 50,
  • "retry_count": 0,
  • "retry_backoff_seconds": 300,
  • "expires_after_hours": 72
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "name": "string",
  • "package_id": "82585450-66a8-4ff2-8a7e-8e7bec960ae1",
  • "package_name": "string",
  • "package_version": "string",
  • "package_kind": "msi",
  • "action": "install",
  • "target_kind": "all",
  • "target_filter": {
    },
  • "schedule_kind": "now",
  • "scheduled_at": "2019-08-24T14:15:22Z",
  • "window_start": "string",
  • "window_end": "string",
  • "reboot_policy": "never",
  • "max_concurrency": 0,
  • "retry_count": 0,
  • "retry_backoff_seconds": 0,
  • "expires_at": "2019-08-24T14:15:22Z",
  • "status": "draft",
  • "excluded_count": 0,
  • "total": 0,
  • "counts": {
    },
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_by_email": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "started_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z"
}

Deploy several packages at once (one deployment per package)

Creates one deployment per package, in the order given, all with the same targets, schedule and options, in one transaction (all or nothing). Each is named " · ". The agent installs the packages of a computer one after another in this order; a restart a reboot policy asks for waits for the last of them.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
name
required
string [ 1 .. 200 ] characters
package_ids
required
Array of strings <uuid> [ 1 .. 20 ] items unique [ items <uuid > ]

The packages, in install order.

action
string
Default: "install"
Enum: "install" "uninstall"
target_kind
required
string
Enum: "all" "devices" "filter"
device_ids
Array of strings <uuid> [ 1 .. 20000 ] items [ items <uuid > ]
object (DeploymentTargetFilter)

The device list filters plus software present/absent.

schedule_kind
string
Default: "now"
Enum: "now" "at" "window"
scheduled_at
string <date-time>
window_start
string^([01][0-9]|2[0-3]):[0-5][0-9]$

HH:MM in each device's site timezone.

window_end
string^([01][0-9]|2[0-3]):[0-5][0-9]$
reboot_policy
string
Default: "never"
Enum: "never" "if_required" "always"
max_concurrency
integer [ 1 .. 1000 ]
Default: 50
retry_count
integer [ 0 .. 10 ]
Default: 0
retry_backoff_seconds
integer [ 0 .. 86400 ]
Default: 300
expires_after_hours
integer [ 1 .. 720 ]
Default: 72

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "package_ids": [
    ],
  • "action": "install",
  • "target_kind": "all",
  • "device_ids": [
    ],
  • "target_filter": {
    },
  • "schedule_kind": "now",
  • "scheduled_at": "2019-08-24T14:15:22Z",
  • "window_start": "string",
  • "window_end": "string",
  • "reboot_policy": "never",
  • "max_concurrency": 50,
  • "retry_count": 0,
  • "retry_backoff_seconds": 300,
  • "expires_after_hours": 72
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Deployment with counters

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
deploymentID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "name": "string",
  • "package_id": "82585450-66a8-4ff2-8a7e-8e7bec960ae1",
  • "package_name": "string",
  • "package_version": "string",
  • "package_kind": "msi",
  • "action": "install",
  • "target_kind": "all",
  • "target_filter": {
    },
  • "schedule_kind": "now",
  • "scheduled_at": "2019-08-24T14:15:22Z",
  • "window_start": "string",
  • "window_end": "string",
  • "reboot_policy": "never",
  • "max_concurrency": 0,
  • "retry_count": 0,
  • "retry_backoff_seconds": 0,
  • "expires_at": "2019-08-24T14:15:22Z",
  • "status": "draft",
  • "excluded_count": 0,
  • "total": 0,
  • "counts": {
    },
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_by_email": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "started_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z"
}

Cancel, pause, resume or add devices that now match

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
deploymentID
required
string <uuid>
Request Body schema: application/json
required
action
required
string
Enum: "cancel" "pause" "resume" "add_new_devices"

Responses

Request samples

Content type
application/json
{
  • "action": "cancel"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "name": "string",
  • "package_id": "82585450-66a8-4ff2-8a7e-8e7bec960ae1",
  • "package_name": "string",
  • "package_version": "string",
  • "package_kind": "msi",
  • "action": "install",
  • "target_kind": "all",
  • "target_filter": {
    },
  • "schedule_kind": "now",
  • "scheduled_at": "2019-08-24T14:15:22Z",
  • "window_start": "string",
  • "window_end": "string",
  • "reboot_policy": "never",
  • "max_concurrency": 0,
  • "retry_count": 0,
  • "retry_backoff_seconds": 0,
  • "expires_at": "2019-08-24T14:15:22Z",
  • "status": "draft",
  • "excluded_count": 0,
  • "total": 0,
  • "counts": {
    },
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_by_email": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "started_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z"
}

Per-device status, attempt, exit code, error and output tail

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
deploymentID
required
string <uuid>
query Parameters
page
integer [ 1 .. 100000 ]
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50
q
string <= 200 characters
status
Array of strings (DeploymentTargetStatus) <= 9 items
Items Enum: "pending" "queued" "downloading" "installing" "success" "failed" "skipped" "cancelled" "timeout"

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "page_size": 0,
  • "total": 0
}

Retry a failed, timed-out or cancelled target (reopens a finished deployment)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
deploymentID
required
string <uuid>
deviceID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "deployment_id": "6ef0ac85-9892-4664-a2a5-58bf2af5a8a6",
  • "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
  • "hostname": "string",
  • "device_status": "string",
  • "status": "pending",
  • "attempt": 0,
  • "next_attempt_at": "2019-08-24T14:15:22Z",
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "exit_code": 0,
  • "error_code": "string",
  • "error": "string",
  • "output_tail": "string",
  • "started_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Deployments that targeted the device (newest first)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
deviceID
required
string <uuid>
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

scripts

Scripts of the tenant and the global library

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
query Parameters
page
integer [ 1 .. 100000 ]
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50
q
string <= 200 characters
language
string (ScriptLanguage)
Enum: "powershell" "pwsh" "cmd"

pwsh runs PowerShell 7 when installed, otherwise Windows PowerShell.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "page_size": 0,
  • "total": 0
}

Add a script (version 1)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
name
required
string [ 1 .. 200 ] characters
description
string <= 2000 characters
language
required
string (ScriptLanguage)
Enum: "powershell" "pwsh" "cmd"

pwsh runs PowerShell 7 when installed, otherwise Windows PowerShell.

content
required
string [ 1 .. 262144 ] characters
object (ScriptParamsSchema)

JSON Schema (draft-07 subset): {"type":"object","properties":{name: spec},"required":[...],"x-order":[...]} where each spec has type string|number|integer|boolean and optional title, description, default, enum (strings and numbers), maxLength (strings), minimum/maximum (numbers). Names are PowerShell identifiers; values reach the script as -Name parameters (PowerShell) and RMM_PARAM_<NAME> variables.

run_as
string
Default: "system"
Enum: "system" "logged_on_user"
timeout_seconds
integer [ 10 .. 86400 ]
Default: 600

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "language": "powershell",
  • "content": "string",
  • "params_schema": { },
  • "run_as": "system",
  • "timeout_seconds": 600
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "scope": "tenant",
  • "name": "string",
  • "description": "string",
  • "language": "powershell",
  • "content": "string",
  • "params_schema": { },
  • "run_as": "system",
  • "timeout_seconds": 0,
  • "current_version": 0,
  • "last_run_at": "2019-08-24T14:15:22Z",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Script detail (tenant or global)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
scriptID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "scope": "tenant",
  • "name": "string",
  • "description": "string",
  • "language": "powershell",
  • "content": "string",
  • "params_schema": { },
  • "run_as": "system",
  • "timeout_seconds": 0,
  • "current_version": 0,
  • "last_run_at": "2019-08-24T14:15:22Z",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Change a tenant script (new content or parameters save a new version)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
scriptID
required
string <uuid>
Request Body schema: application/json
required
name
string [ 1 .. 200 ] characters
description
string <= 2000 characters
language
string (ScriptLanguage)
Enum: "powershell" "pwsh" "cmd"

pwsh runs PowerShell 7 when installed, otherwise Windows PowerShell.

content
string [ 1 .. 262144 ] characters
object (ScriptParamsSchema)

JSON Schema (draft-07 subset): {"type":"object","properties":{name: spec},"required":[...],"x-order":[...]} where each spec has type string|number|integer|boolean and optional title, description, default, enum (strings and numbers), maxLength (strings), minimum/maximum (numbers). Names are PowerShell identifiers; values reach the script as -Name parameters (PowerShell) and RMM_PARAM_<NAME> variables.

run_as
string
Enum: "system" "logged_on_user"
timeout_seconds
integer [ 10 .. 86400 ]

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "language": "powershell",
  • "content": "string",
  • "params_schema": { },
  • "run_as": "system",
  • "timeout_seconds": 10
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "scope": "tenant",
  • "name": "string",
  • "description": "string",
  • "language": "powershell",
  • "content": "string",
  • "params_schema": { },
  • "run_as": "system",
  • "timeout_seconds": 0,
  • "current_version": 0,
  • "last_run_at": "2019-08-24T14:15:22Z",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a tenant script (runs keep their history)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
scriptID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Version history, newest first

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
scriptID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Run the current version on devices (explicit ids, a filter or all devices)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
scriptID
required
string <uuid>
Request Body schema: application/json
required
target_kind
required
string
Enum: "all" "devices" "filter"
device_ids
Array of strings <uuid> [ 1 .. 5000 ] items [ items <uuid > ]
object (DeploymentTargetFilter)

The device list filters plus software present/absent.

object

Parameter values by name (validated against the script's params_schema; 422 with params.<name> fields).

Responses

Request samples

Content type
application/json
{
  • "target_kind": "all",
  • "device_ids": [
    ],
  • "target_filter": {
    },
  • "params": { }
}

Response samples

Content type
application/json
{
  • "runs": [
    ],
  • "excluded": {
    }
}

Script runs, newest first

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
query Parameters
page
integer [ 1 .. 100000 ]
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50
script_id
string <uuid>
device_id
string <uuid>
status
string (ScriptRunStatus)
Enum: "queued" "running" "succeeded" "failed" "timeout" "cancelled"
from
string <date-time>
to
string <date-time>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "page_size": 0,
  • "total": 0
}

Run detail with its output (live output while running)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
runID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "script_id": "74e7d8c3-daa9-40c1-ac0e-b64bfab79c57",
  • "script_version": 0,
  • "script_name": "string",
  • "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
  • "device_hostname": "string",
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "requested_by": "cda0f200-65cd-4343-aedd-9c936b908826",
  • "requested_by_email": "string",
  • "params": { },
  • "run_as": "string",
  • "status": "queued",
  • "exit_code": 0,
  • "output_bytes": 0,
  • "error_code": "string",
  • "error": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "started_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "output": "string",
  • "output_end": 0,
  • "output_truncated": true
}

Cancel a queued or running run (a running script is stopped)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
runID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "script_id": "74e7d8c3-daa9-40c1-ac0e-b64bfab79c57",
  • "script_version": 0,
  • "script_name": "string",
  • "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
  • "device_hostname": "string",
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "requested_by": "cda0f200-65cd-4343-aedd-9c936b908826",
  • "requested_by_email": "string",
  • "params": { },
  • "run_as": "string",
  • "status": "queued",
  • "exit_code": 0,
  • "output_bytes": 0,
  • "error_code": "string",
  • "error": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "started_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z"
}

Global script library

Authorizations:
bearerAuth
query Parameters
page
integer [ 1 .. 100000 ]
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50
q
string <= 200 characters
language
string (ScriptLanguage)
Enum: "powershell" "pwsh" "cmd"

pwsh runs PowerShell 7 when installed, otherwise Windows PowerShell.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "page_size": 0,
  • "total": 0
}

Add a global script (every tenant can run it)

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 200 ] characters
description
string <= 2000 characters
language
required
string (ScriptLanguage)
Enum: "powershell" "pwsh" "cmd"

pwsh runs PowerShell 7 when installed, otherwise Windows PowerShell.

content
required
string [ 1 .. 262144 ] characters
object (ScriptParamsSchema)

JSON Schema (draft-07 subset): {"type":"object","properties":{name: spec},"required":[...],"x-order":[...]} where each spec has type string|number|integer|boolean and optional title, description, default, enum (strings and numbers), maxLength (strings), minimum/maximum (numbers). Names are PowerShell identifiers; values reach the script as -Name parameters (PowerShell) and RMM_PARAM_<NAME> variables.

run_as
string
Default: "system"
Enum: "system" "logged_on_user"
timeout_seconds
integer [ 10 .. 86400 ]
Default: 600

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "language": "powershell",
  • "content": "string",
  • "params_schema": { },
  • "run_as": "system",
  • "timeout_seconds": 600
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "scope": "tenant",
  • "name": "string",
  • "description": "string",
  • "language": "powershell",
  • "content": "string",
  • "params_schema": { },
  • "run_as": "system",
  • "timeout_seconds": 0,
  • "current_version": 0,
  • "last_run_at": "2019-08-24T14:15:22Z",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Global script detail

Authorizations:
bearerAuth
path Parameters
scriptID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "scope": "tenant",
  • "name": "string",
  • "description": "string",
  • "language": "powershell",
  • "content": "string",
  • "params_schema": { },
  • "run_as": "system",
  • "timeout_seconds": 0,
  • "current_version": 0,
  • "last_run_at": "2019-08-24T14:15:22Z",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Change a global script

Authorizations:
bearerAuth
path Parameters
scriptID
required
string <uuid>
Request Body schema: application/json
required
name
string [ 1 .. 200 ] characters
description
string <= 2000 characters
language
string (ScriptLanguage)
Enum: "powershell" "pwsh" "cmd"

pwsh runs PowerShell 7 when installed, otherwise Windows PowerShell.

content
string [ 1 .. 262144 ] characters
object (ScriptParamsSchema)

JSON Schema (draft-07 subset): {"type":"object","properties":{name: spec},"required":[...],"x-order":[...]} where each spec has type string|number|integer|boolean and optional title, description, default, enum (strings and numbers), maxLength (strings), minimum/maximum (numbers). Names are PowerShell identifiers; values reach the script as -Name parameters (PowerShell) and RMM_PARAM_<NAME> variables.

run_as
string
Enum: "system" "logged_on_user"
timeout_seconds
integer [ 10 .. 86400 ]

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "language": "powershell",
  • "content": "string",
  • "params_schema": { },
  • "run_as": "system",
  • "timeout_seconds": 10
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "scope": "tenant",
  • "name": "string",
  • "description": "string",
  • "language": "powershell",
  • "content": "string",
  • "params_schema": { },
  • "run_as": "system",
  • "timeout_seconds": 0,
  • "current_version": 0,
  • "last_run_at": "2019-08-24T14:15:22Z",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a global script

Authorizations:
bearerAuth
path Parameters
scriptID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Version history of a global script

Authorizations:
bearerAuth
path Parameters
scriptID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

alerts

My alert e-mail preferences for this tenant

Defaults for global admins who are not members of the tenant.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "alert_email": "off",
  • "min_severity": "info",
  • "digest_interval": "15m",
  • "digest_hour": 0,
  • "timezone": "string",
  • "offline_batch_minutes": 5,
  • "muted_types": [
    ],
  • "notify_resolved": true,
  • "quiet_hours": {
    }
}

Set my alert e-mail preferences for this tenant (members only; 409 not_a_member)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
alert_email
required
string
Enum: "off" "immediate" "digest"

immediate mails new alerts as they open (a storm becomes one summary); digest collects them and mails them every digest_interval. Offline devices are never mailed one by one (see offline_batch_minutes).

min_severity
required
string (AlertSeverity)
Enum: "info" "warning" "critical"
digest_interval
string
Enum: "15m" "hourly" "daily"

How often digest delivery mails (daily at digest_hour). Default 15m.

digest_hour
integer [ 0 .. 23 ]

Hour of the daily digest, in timezone. Default 8.

timezone
string <= 64 characters

IANA time zone for digest_hour and quiet_hours ("" = the tenant's default time zone).

offline_batch_minutes
integer
Enum: 5 15 30 60

Default 15. Devices going offline are collected for this long and mailed together: one e-mail lists the devices that went offline and every device that is currently offline.

muted_types
Array of strings (AlertRuleType) <= 32 items unique
Items Enum: "device_offline" "disk_free_pct" "agent_outdated" "cpu_pct" "mem_pct" "cpu_temp" "deployment_failed" "adsync_failed" "connector_offline"

Alert types that are never e-mailed. Default none.

notify_resolved
boolean

Also mail when alerts resolve (devices back online are listed in the offline e-mail). Default false.

object (QuietHours)

No e-mail is sent between start and end (in timezone; end before start spans midnight). What would have been sent goes out as one summary when the quiet hours end. Critical alerts are held too unless critical_bypass.

Responses

Request samples

Content type
application/json
{
  • "alert_email": "off",
  • "min_severity": "info",
  • "digest_interval": "15m",
  • "digest_hour": 0,
  • "timezone": "string",
  • "offline_batch_minutes": 5,
  • "muted_types": [
    ],
  • "notify_resolved": true,
  • "quiet_hours": {
    }
}

Response samples

Content type
application/json
{
  • "alert_email": "off",
  • "min_severity": "info",
  • "digest_interval": "15m",
  • "digest_hour": 0,
  • "timezone": "string",
  • "offline_batch_minutes": 5,
  • "muted_types": [
    ],
  • "notify_resolved": true,
  • "quiet_hours": {
    }
}

Alerts, newest first, with counts per status

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
query Parameters
page
integer [ 1 .. 100000 ]
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50
status
string
Enum: "open" "acknowledged" "resolved"
severity
string (AlertSeverity)
Enum: "info" "warning" "critical"
device_id
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 0,
  • "page_size": 0,
  • "counts": {
    }
}

Acknowledge open alerts (they still resolve by themselves)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
ids
required
Array of strings <uuid> [ 1 .. 500 ] items [ items <uuid > ]

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "changed": 0
}

Resolve alerts by hand (a condition that still holds opens a new alert)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
ids
required
Array of strings <uuid> [ 1 .. 500 ] items [ items <uuid > ]

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "changed": 0
}

The tenant's rules and the global ones (with the tenant's on/off state)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create a tenant rule

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
name
required
string [ 1 .. 200 ] characters
type
required
string (AlertRuleType)
Enum: "device_offline" "disk_free_pct" "agent_outdated" "cpu_pct" "mem_pct" "cpu_temp" "deployment_failed" "adsync_failed" "connector_offline"
object (AlertCondition)

Parameters by rule type — device_offline {minutes (default 60)}; disk_free_pct {below, drive?}; agent_outdated {min_version? (default: latest stable agent release)}; cpu_pct / mem_pct {above, minutes (default 15)}; cpu_temp {above_c (default 90), minutes (default 10)}; deployment_failed {threshold_pct (default 20)}; adsync_failed {}; connector_offline {minutes (default 15)}.

severity
string (AlertSeverity)
Enum: "info" "warning" "critical"
enabled
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "type": "device_offline",
  • "condition": {
    },
  • "severity": "info",
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "scope": "tenant",
  • "name": "string",
  • "type": "device_offline",
  • "condition": {
    },
  • "severity": "info",
  • "enabled": true,
  • "enabled_for_tenant": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Edit a tenant rule, or turn a global rule off/on for the tenant (only `enabled`)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
ruleID
required
string <uuid>
Request Body schema: application/json
required
name
string [ 1 .. 200 ] characters
object (AlertCondition)

Parameters by rule type — device_offline {minutes (default 60)}; disk_free_pct {below, drive?}; agent_outdated {min_version? (default: latest stable agent release)}; cpu_pct / mem_pct {above, minutes (default 15)}; cpu_temp {above_c (default 90), minutes (default 10)}; deployment_failed {threshold_pct (default 20)}; adsync_failed {}; connector_offline {minutes (default 15)}.

severity
string (AlertSeverity)
Enum: "info" "warning" "critical"
enabled
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "condition": {
    },
  • "severity": "info",
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "scope": "tenant",
  • "name": "string",
  • "type": "device_offline",
  • "condition": {
    },
  • "severity": "info",
  • "enabled": true,
  • "enabled_for_tenant": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a tenant rule (and its alerts)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
ruleID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Global alert rules (evaluated for every tenant)

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create a global rule

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 200 ] characters
type
required
string (AlertRuleType)
Enum: "device_offline" "disk_free_pct" "agent_outdated" "cpu_pct" "mem_pct" "cpu_temp" "deployment_failed" "adsync_failed" "connector_offline"
object (AlertCondition)

Parameters by rule type — device_offline {minutes (default 60)}; disk_free_pct {below, drive?}; agent_outdated {min_version? (default: latest stable agent release)}; cpu_pct / mem_pct {above, minutes (default 15)}; cpu_temp {above_c (default 90), minutes (default 10)}; deployment_failed {threshold_pct (default 20)}; adsync_failed {}; connector_offline {minutes (default 15)}.

severity
string (AlertSeverity)
Enum: "info" "warning" "critical"
enabled
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "type": "device_offline",
  • "condition": {
    },
  • "severity": "info",
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "scope": "tenant",
  • "name": "string",
  • "type": "device_offline",
  • "condition": {
    },
  • "severity": "info",
  • "enabled": true,
  • "enabled_for_tenant": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Edit a global rule

Authorizations:
bearerAuth
path Parameters
ruleID
required
string <uuid>
Request Body schema: application/json
required
name
string [ 1 .. 200 ] characters
object (AlertCondition)

Parameters by rule type — device_offline {minutes (default 60)}; disk_free_pct {below, drive?}; agent_outdated {min_version? (default: latest stable agent release)}; cpu_pct / mem_pct {above, minutes (default 15)}; cpu_temp {above_c (default 90), minutes (default 10)}; deployment_failed {threshold_pct (default 20)}; adsync_failed {}; connector_offline {minutes (default 15)}.

severity
string (AlertSeverity)
Enum: "info" "warning" "critical"
enabled
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "condition": {
    },
  • "severity": "info",
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "scope": "tenant",
  • "name": "string",
  • "type": "device_offline",
  • "condition": {
    },
  • "severity": "info",
  • "enabled": true,
  • "enabled_for_tenant": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a global rule (and its alerts in every tenant)

Authorizations:
bearerAuth
path Parameters
ruleID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

releases

Agent and connector releases, version adoption and the release public key

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "adoption": [
    ],
  • "public_key": "string"
}

Declare a release and get a presigned upload for its MSI

Global admins, or release automation with Authorization: Bearer <RMM_RELEASE_TOKEN>. PUT the MSI to upload.url with upload.headers, then POST .../publish.

Authorizations:
bearerAuth
Request Body schema: application/json
required
component
required
string
Enum: "agent" "connector"
version
required
string <= 64 characters
channel
string
Enum: "stable" "beta"
notes
string <= 4000 characters
sha256
required
string^[0-9a-fA-F]{64}$
size_bytes
required
integer <int64> [ 1 .. 524288000 ]
rollout_pct
integer [ 0 .. 100 ]

Responses

Request samples

Content type
application/json
{
  • "component": "agent",
  • "version": "string",
  • "channel": "stable",
  • "notes": "string",
  • "sha256": "string",
  • "size_bytes": 1,
  • "rollout_pct": 0
}

Response samples

Content type
application/json
{
  • "release": {
    },
  • "upload": {
    }
}

Change rollout percentage, channel or notes

Authorizations:
bearerAuth
path Parameters
releaseID
required
string <uuid>
Request Body schema: application/json
required
channel
string
Enum: "stable" "beta"
notes
string <= 4000 characters
rollout_pct
integer [ 0 .. 100 ]

Responses

Request samples

Content type
application/json
{
  • "channel": "stable",
  • "notes": "string",
  • "rollout_pct": 0
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "component": "agent",
  • "version": "string",
  • "channel": "stable",
  • "status": "draft",
  • "size_bytes": 0,
  • "sha256": "string",
  • "signature": "string",
  • "notes": "string",
  • "rollout_pct": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "published_at": "2019-08-24T14:15:22Z"
}

Delete a release and its MSI

Authorizations:
bearerAuth
path Parameters
releaseID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Verify the uploaded MSI, sign the manifest and publish

409 codes: upload_missing, upload_mismatch, signing_key_missing, not_draft.

Authorizations:
bearerAuth
path Parameters
releaseID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "component": "agent",
  • "version": "string",
  • "channel": "stable",
  • "status": "draft",
  • "size_bytes": 0,
  • "sha256": "string",
  • "signature": "string",
  • "notes": "string",
  • "rollout_pct": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "published_at": "2019-08-24T14:15:22Z"
}

A one-hour download link for a release MSI

Global admins only (not the release automation token). The link is presigned for one hour and the browser saves the file as file_name (rmm-<component>-<version>.msi). Drafts can be downloaded once their MSI is uploaded. Each link is audited as release.download. 409 codes: upload_missing, storage_unavailable.

Authorizations:
bearerAuth
path Parameters
releaseID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "download_url": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "file_name": "string"
}