API Reference

Open the interactive OpenAPI reference:

Download OpenAPI spec (YAML)

Download Swagger OpenAPI spec (YAML)

Open ReDoc reference (new tab)

GET /device_classes

List device classes

Lists the device classes, ordered by id.

Unlike the other listing endpoints of this service, filters are optional: with no filter[...] parameter, every device class is listed. When filters are provided and match no device class, the response is 404. limit and offset page through the device classes, ordered by id; a page past the last match is an empty list, not a 404.

Requires the DEV_CLASS_VIEW access hook.

Query Parameters:

  • pretty (boolean) – When true, enums are returned as strings (e.g., COMPONENT). When false, enums are returned as integers.

  • fields (string) –

    Optional response field allowlist (Pydantic-style include behavior).

    When provided, only the specified comma-separated fields are included in the response (e.g., id,guid,class_name,description). validation_errors is always included when present.

    If both fields and exclude are provided, fields is applied first, then exclude.

  • exclude (string) –

    Optional response field blocklist (Pydantic-style exclude behavior).

    When provided, all response fields are returned except the specified comma-separated fields (e.g., id,class_type,last_edited).

    If both fields and exclude are provided, fields is applied first, then exclude.

  • limit (integer) – The maximum number of device classes to return, ordered by id. Defaults to all of them. Must be a non-negative integer (400 otherwise).

  • offset (integer) – The number of matching device classes to skip. Must be a non-negative integer (400 otherwise). A page past the last match is an empty list, even with filters.

  • require_all_filters (boolean) –

    Controls how multiple filter conditions are combined.

    • true: all filters must match (AND)

    • false: any filter may match (OR)

  • filter[<field>][<operator>] (string) –

    Filter expression in the forms:

    • filter[<field>][<operator>]=<value>

    • filter[<field>][not][<operator>]=<value>

    Optional. Multiple filters may be provided. Supported operators:

    • is

    • contains

    • gt (single value only)

    • lt (single value only)

    • search (single value only, not negatable)

    Values may be comma-separated to express multi-value matching. For is, the special value null (case-insensitive) is treated as a SQL NULL check on the fields that accept null, such as pp_guid.

    Every stored field can be filtered on: id, guid, class_name, description, category (by id), device_type, is_snmp, class_identifier_1, class_identifier_2, discovery_qualifier, agent_identifier_1, agent_identifier_2, root_device, weight, tier_id, image, pp_guid, class_type and last_edited. category_name cannot be filtered on.

    Examples:

    • filter[device_type][is]=COMPONENT

    • filter[class_name][contains]=Microsoft,Cisco

    • filter[pp_guid][is]=null

Status Codes:

  • 200 OK – The device classes that match, ordered by id.

  • 400 Bad Request – A malformed filter, a filter on an unknown field or with an unsupported operator, or a limit or offset that is not a non-negative integer.

  • 401 Unauthorized – Unauthenticated

  • 403 Forbidden – Forbidden (insufficient access hooks)

  • 404 Not Found – Filters were provided and no device class matches them, with an offset of 0. A page past the last match, with a non-zero offset, is an empty list instead.

  • 422 Unprocessable Entity – A stored device class could not be processed.

  • 500 Internal Server Error – The device classes could not be listed (Could not get Device Classes).

Request JSON Object:

  • device_classes[].agent_identifier_1 (string) – The first identifier agent discovery matches devices against.

  • device_classes[].agent_identifier_2 (string) – The second identifier agent discovery matches devices against.

  • device_classes[].category (integer) – The id of the device category the device class belongs to (column family). A payload may also provide the GUID or the exact name of the category.

  • device_classes[].category_name (string) – The name of the device category the device class belongs to. (read only)

  • device_classes[].class_identifier_1 (string) – The first identifier discovery matches devices against (column identifyer_1): the sysObjectID of an SNMP device class, which must then be a numeric OID for a PHYSICAL device class unless agent_identifier_1 is set, or the first class identifier of a component device class. Must be empty for a device class that is neither SNMP nor a component.

  • device_classes[].class_identifier_2 (string) – The second identifier discovery matches devices against (column identifyer_3): the second class identifier of a component device class, or the value the discovery_qualifier OID must have for an SNMP device class.

  • device_classes[].class_name (string) – The class of the device class, typically the vendor or platform (column class).

  • device_classes[].class_type (integer) – The number Dynamic Applications are aligned with, and devices record as their device class. Allocated when the device class is created, as the next number after the highest in use, and never changed. Not portable between systems. (read only)

  • device_classes[].description (string) – The description of the device class, typically the model or type (column descript). Several device classes can share a class and description.

  • device_classes[].device_type (string) – The kind of device a device class describes, stored in the virtual column. Serialized by name with pretty=true and by value with pretty=false; a payload accepts either. - PHYSICAL (0): a physical device - VIRTUAL (1): a virtual device - COMPONENT (2): a component device

  • device_classes[].discovery_qualifier (string) – The OID whose value must equal class_identifier_2 for an SNMP device to match the device class (column identifyer_2). Must be a numeric OID on a PHYSICAL SNMP device class when it or class_identifier_2 is set.

  • device_classes[].guid (any) – The identity of the device class (column devtype_guid), in either case. It is kept across systems, and cannot change once the device class exists.

  • device_classes[].id (integer) – The numeric id of the device class on this system. Not portable between systems. (read only)

  • device_classes[].image (string) – The legacy PNG image file of the device class. Its icon is not this field: icons are set with the GraphQL setDeviceClassIcon mutation.

  • device_classes[].is_snmp (boolean) – Whether devices of the device class are discovered over SNMP. A COMPONENT device class cannot be an SNMP device class.

  • device_classes[].last_edited (string) – When the device class was last edited, as an ISO 8601 timestamp (column date_edit). Null when it has never been edited. (read only)

  • device_classes[].pp_guid (any) – The GUID of the PowerPack the device class belongs to (column ppguid), in either case. It must be the GUID of a PowerPack installed on the system.

  • device_classes[].root_device (boolean) – Whether devices of the device class are the root of a component tree.

  • device_classes[].tier_id (integer) – The device class tier the device class belongs to: the id of a row of master.definitions_dev_class_tiers, or 0 for “No Tier”.

  • device_classes[].validation_errors[].field (string) – The field with the invalid stored value. (required)

  • device_classes[].validation_errors[].message (string) – Why the stored value is invalid. (required)

  • device_classes[].weight (integer) – The precedence of the device class when several device classes match a device.

POST /device_classes

Create or update device classes

Creates or updates one or more device classes, keyed by GUID. GUIDs are 32 hexadecimal characters in either case, and are matched without regard to case:

  • a guid of an existing device class updates it, keeping its stored GUID. Only the provided fields are applied, and only the fields whose value changes are written. Any id is ignored.

  • a guid that does not exist creates a device class with that GUID. Any id is ignored.

  • no guid creates a device class with a generated GUID.

  • an id without a guid is rejected with 400.

The GUID is the key of a device class and its id is local to a system, so a provided id never selects or changes anything.

The read-only fields category_name, class_type, last_edited and validation_errors are discarded, so a retrieved device class is a valid payload, and posting it back unchanged writes nothing.

Every device class is validated against the complete result (the stored values updated with the payload) before any is written, so a stored device class that breaks a rule is rejected on every update until the payload fixes it:

  • its identifiers must be consistent with its kind: a COMPONENT device class cannot have is_snmp true; a PHYSICAL device class with is_snmp true needs a numeric OID as class_identifier_1 unless agent_identifier_1 is set, and a numeric OID as discovery_qualifier when discovery_qualifier or class_identifier_2 is set; a device class that is neither SNMP nor a component must have an empty class_identifier_1

  • its category must exist and not be ambiguous

  • its tier_id must be 0 (no tier) or an existing device class tier

  • its pp_guid must be an installed PowerPack

  • its text must be encodable as latin1

Device classes may share a class and description. The whole payload is handled in a single transaction.

A new device class is allocated the next class_type after the highest in use, which is what Dynamic Applications are aligned with. Each change is recorded in the audit log, and the revision of each installed PowerPack whose device classes change is incremented. PowerPacks that are no longer installed are skipped.

Requires the DEV_CLASS_VIEW and SYS_CUSTOM_DEV_CLASS_PAGE access hooks.

Query Parameters:

  • pretty (boolean) – Controls enum serialization format in responses. When true, enums are returned as strings; when false, as integers.

  • commit (boolean) –

    Controls whether the device classes are upserted. Useful for validating the changes that would occur (with retrieve=true) or for testing frameworks that should not have to clean up after themselves.

    When true, the device classes are upserted on the system. When false, the request is processed exactly as it would be otherwise, then rolled back, so nothing is changed.

  • retrieve (boolean) – When true, the response includes an entities list with each device class as stored after the request, in payload order. When false, only results is returned.

  • fields (string) –

    Optional entities field allowlist (Pydantic-style include behavior). Only used when retrieve=true.

    If both fields and exclude are provided, fields is applied first, then exclude.

  • exclude (string) –

    Optional entities field blocklist (Pydantic-style exclude behavior). Only used when retrieve=true.

    If both fields and exclude are provided, fields is applied first, then exclude.

Response JSON Object:

  • device_classes[].agent_identifier_1 (string)

  • device_classes[].agent_identifier_2 (string)

  • device_classes[].category (any) – Required on create. The id, the GUID or the exact name of the device category.

  • device_classes[].class_identifier_1 (string)

  • device_classes[].class_identifier_2 (string)

  • device_classes[].class_name (string) – Required on create.

  • device_classes[].description (string) – Required on create.

  • device_classes[].device_type (any) – The name of a device type, or its value (0, 1 or 2).

  • device_classes[].discovery_qualifier (string)

  • device_classes[].guid (any) – The GUID that keys the upsert, in either case: an existing GUID updates that device class (its stored GUID is kept), a new GUID creates a device class with it as provided, and no GUID creates one with a generated GUID.

  • device_classes[].id (integer) – Optional and always ignored, as the guid is the key and an id is local to a system. An id without a guid is rejected with 400.

  • device_classes[].image (string)

  • device_classes[].is_snmp (boolean)

  • device_classes[].pp_guid (any) – Must be the GUID of a PowerPack installed on the system.

  • device_classes[].root_device (boolean)

  • device_classes[].tier_id (integer) – 0 (no tier) or the id of an existing device class tier.

  • device_classes[].weight (integer)

Status Codes:

  • 200 OK – The id, guid, name and new flag of each device class, in payload order.

  • 400 Bad Request – Invalid JSON (Invalid JSON payload provided), an empty body (No JSON payload provided), or an invalid payload (Invalid Device Class Request): not one of the accepted forms, no device classes, the same guid twice, or an id without a guid.

  • 401 Unauthorized – Unauthenticated

  • 403 Forbidden – Forbidden (insufficient access hooks)

  • 415 Unsupported Media Type – Unsupported Media Type. The request body was not sent as JSON with a Content-Type of application/json.

  • 422 Unprocessable Entity – A device class failed validation (Device Class(es) Failed Validation); nothing is written. For example a missing required field, an unknown field, identifiers that are inconsistent with the kind of device class, a category that does not resolve, a tier_id that does not exist, a pp_guid that is not an installed PowerPack, text that cannot be stored as latin1, or a stored value that fails validation and is not corrected in the payload.

  • 500 Internal Server Error – The device classes could not be updated (Could not update Device Class(es)). Nothing is written.

Request JSON Object:

  • entities[].agent_identifier_1 (string) – The first identifier agent discovery matches devices against.

  • entities[].agent_identifier_2 (string) – The second identifier agent discovery matches devices against.

  • entities[].category (integer) – The id of the device category the device class belongs to (column family). A payload may also provide the GUID or the exact name of the category.

  • entities[].category_name (string) – The name of the device category the device class belongs to. (read only)

  • entities[].class_identifier_1 (string) – The first identifier discovery matches devices against (column identifyer_1): the sysObjectID of an SNMP device class, which must then be a numeric OID for a PHYSICAL device class unless agent_identifier_1 is set, or the first class identifier of a component device class. Must be empty for a device class that is neither SNMP nor a component.

  • entities[].class_identifier_2 (string) – The second identifier discovery matches devices against (column identifyer_3): the second class identifier of a component device class, or the value the discovery_qualifier OID must have for an SNMP device class.

  • entities[].class_name (string) – The class of the device class, typically the vendor or platform (column class).

  • entities[].class_type (integer) – The number Dynamic Applications are aligned with, and devices record as their device class. Allocated when the device class is created, as the next number after the highest in use, and never changed. Not portable between systems. (read only)

  • entities[].description (string) – The description of the device class, typically the model or type (column descript). Several device classes can share a class and description.

  • entities[].device_type (string) – The kind of device a device class describes, stored in the virtual column. Serialized by name with pretty=true and by value with pretty=false; a payload accepts either. - PHYSICAL (0): a physical device - VIRTUAL (1): a virtual device - COMPONENT (2): a component device

  • entities[].discovery_qualifier (string) – The OID whose value must equal class_identifier_2 for an SNMP device to match the device class (column identifyer_2). Must be a numeric OID on a PHYSICAL SNMP device class when it or class_identifier_2 is set.

  • entities[].guid (any) – The identity of the device class (column devtype_guid), in either case. It is kept across systems, and cannot change once the device class exists.

  • entities[].id (integer) – The numeric id of the device class on this system. Not portable between systems. (read only)

  • entities[].image (string) – The legacy PNG image file of the device class. Its icon is not this field: icons are set with the GraphQL setDeviceClassIcon mutation.

  • entities[].is_snmp (boolean) – Whether devices of the device class are discovered over SNMP. A COMPONENT device class cannot be an SNMP device class.

  • entities[].last_edited (string) – When the device class was last edited, as an ISO 8601 timestamp (column date_edit). Null when it has never been edited. (read only)

  • entities[].pp_guid (any) – The GUID of the PowerPack the device class belongs to (column ppguid), in either case. It must be the GUID of a PowerPack installed on the system.

  • entities[].root_device (boolean) – Whether devices of the device class are the root of a component tree.

  • entities[].tier_id (integer) – The device class tier the device class belongs to: the id of a row of master.definitions_dev_class_tiers, or 0 for “No Tier”.

  • entities[].validation_errors[].field (string) – The field with the invalid stored value. (required)

  • entities[].validation_errors[].message (string) – Why the stored value is invalid. (required)

  • entities[].weight (integer) – The precedence of the device class when several device classes match a device.

  • results[].guid (string) – The GUID of a device class, or of its PowerPack: 32 hexadecimal characters in either case, as many device classes shipped with the platform have lowercase GUIDs. The value is kept as provided, and compared without regard to case.

  • results[].id (integer) – The numeric id of the device class.

  • results[].name (string) – The class and description of the device class, joined by " | ".

  • results[].new (boolean) – Whether the device class was created. False for an update, including one that changed nothing.

  • success (boolean) – Whether the update call succeeded overall.

GET /device_classes/{device_class_identifier}

Retrieve a device class

Retrieves one device class by id, GUID or name.

A stored device class with values that fail validation is returned as stored, with a validation_errors list describing each problem.

Requires the DEV_CLASS_VIEW access hook.

Parameters:

  • device_class_identifier (string) – The numeric id, the GUID (in either case), or the name of the device class. A numeric value is treated as an id, unless it is a 32-digit GUID. The name is the class and description joined by " | ", such as Microsoft | Windows Server 2019, used as-is and URL-encoded as usual; it may contain a /, but a name ending in /icon must be addressed by id or GUID. It is looked up by exact match first, then, for a name of at most 64 characters, by fuzzy match. Names are not unique: when several device classes have the name, the response is 404 with their GUIDs in matches.

Query Parameters:

  • pretty (boolean) – When true, enums are returned as strings (e.g., COMPONENT). When false, enums are returned as integers.

  • fields (string) –

    Optional response field allowlist (Pydantic-style include behavior).

    If both fields and exclude are provided, fields is applied first, then exclude.

  • exclude (string) –

    Optional response field blocklist (Pydantic-style exclude behavior).

    If both fields and exclude are provided, fields is applied first, then exclude.

Status Codes:

  • 200 OK – The device class.

  • 400 Bad Request – The identifier is not a usable name.

  • 401 Unauthorized – Unauthenticated

  • 403 Forbidden – Forbidden (insufficient access hooks)

  • 404 Not Found – No device class matches the identifier, or several device classes share the name given, in which case their GUIDs are in matches. A fuzzy name lookup that is not confident lists the closest names in matches.

  • 422 Unprocessable Entity – The stored device class could not be processed.

  • 500 Internal Server Error – The device class could not be retrieved (Could not get Device Class).

Request JSON Object:

  • agent_identifier_1 (string) – The first identifier agent discovery matches devices against.

  • agent_identifier_2 (string) – The second identifier agent discovery matches devices against.

  • category (integer) – The id of the device category the device class belongs to (column family). A payload may also provide the GUID or the exact name of the category.

  • category_name (string) – The name of the device category the device class belongs to. (read only)

  • class_identifier_1 (string) – The first identifier discovery matches devices against (column identifyer_1): the sysObjectID of an SNMP device class, which must then be a numeric OID for a PHYSICAL device class unless agent_identifier_1 is set, or the first class identifier of a component device class. Must be empty for a device class that is neither SNMP nor a component.

  • class_identifier_2 (string) – The second identifier discovery matches devices against (column identifyer_3): the second class identifier of a component device class, or the value the discovery_qualifier OID must have for an SNMP device class.

  • class_name (string) – The class of the device class, typically the vendor or platform (column class).

  • class_type (integer) – The number Dynamic Applications are aligned with, and devices record as their device class. Allocated when the device class is created, as the next number after the highest in use, and never changed. Not portable between systems. (read only)

  • description (string) – The description of the device class, typically the model or type (column descript). Several device classes can share a class and description.

  • device_type (string) – The kind of device a device class describes, stored in the virtual column. Serialized by name with pretty=true and by value with pretty=false; a payload accepts either. - PHYSICAL (0): a physical device - VIRTUAL (1): a virtual device - COMPONENT (2): a component device

  • discovery_qualifier (string) – The OID whose value must equal class_identifier_2 for an SNMP device to match the device class (column identifyer_2). Must be a numeric OID on a PHYSICAL SNMP device class when it or class_identifier_2 is set.

  • guid (any) – The identity of the device class (column devtype_guid), in either case. It is kept across systems, and cannot change once the device class exists.

  • id (integer) – The numeric id of the device class on this system. Not portable between systems. (read only)

  • image (string) – The legacy PNG image file of the device class. Its icon is not this field: icons are set with the GraphQL setDeviceClassIcon mutation.

  • is_snmp (boolean) – Whether devices of the device class are discovered over SNMP. A COMPONENT device class cannot be an SNMP device class.

  • last_edited (string) – When the device class was last edited, as an ISO 8601 timestamp (column date_edit). Null when it has never been edited. (read only)

  • pp_guid (any) – The GUID of the PowerPack the device class belongs to (column ppguid), in either case. It must be the GUID of a PowerPack installed on the system.

  • root_device (boolean) – Whether devices of the device class are the root of a component tree.

  • tier_id (integer) – The device class tier the device class belongs to: the id of a row of master.definitions_dev_class_tiers, or 0 for “No Tier”.

  • validation_errors[].field (string) – The field with the invalid stored value. (required)

  • validation_errors[].message (string) – Why the stored value is invalid. (required)

  • weight (integer) – The precedence of the device class when several device classes match a device.

DELETE /device_classes/{device_class_identifier}

Delete a device class

Deletes a device class that no device or Dynamic Application references.

A device class that devices belong to, or that Dynamic Applications are aligned with (both through its class_type), is refused with 409 and a references object listing them. Deleting a device class also deletes its icon assignment (its row in master_ap2.dev_class_icon) and its legacy fallback icon mapping (its row in definitions_dev_class_svg_icons), invalidates the platform’s device class cache (the ent_device_class entry of master.cache_data), records the deletion in the audit log and increments the revision of its PowerPack, unless that PowerPack is no longer installed.

This is stricter than the platform’s device class editor, which refuses a deletion only for devices and silently unaligns the Dynamic Applications. This API also refuses while Dynamic Applications are aligned, so an alignment is never removed as a side effect.

Requires the DEV_CLASS_VIEW and SYS_CUSTOM_DEV_CLASS_PAGE access hooks.

Parameters:

  • device_class_identifier (string) – The numeric id, the GUID (in either case), or the exact name of the device class. A numeric value is treated as an id, unless it is a 32-digit GUID. The name is the class and description joined by " | ", used as-is and URL-encoded as usual; it may contain a /, but a name ending in /icon must be addressed by id or GUID. Requests that change a device class never fuzzy match a name, so a typo cannot select another device class: a name without an exact match returns 404.

Query Parameters:

  • commit (boolean) – When false, the deletion is validated and rolled back: the response is the one a committed deletion would return, including a 409, and nothing is deleted.

Status Codes:

  • 200 OK – The id, guid and name of the deleted device class.

  • 400 Bad Request – The identifier is not a usable name.

  • 401 Unauthorized – Unauthenticated

  • 403 Forbidden – Forbidden (insufficient access hooks)

  • 404 Not Found – No device class has the id or GUID, or exactly the name, given (No device class found named exactly: <name>; names are not fuzzy matched here), or several device classes share the name (their GUIDs are in matches).

  • 409 Conflict – The device class is in use (Device Class In Use): devices belong to it or Dynamic Applications are aligned with it. Nothing is deleted.

  • 500 Internal Server Error – The device class could not be deleted (Could not delete Device Class). Nothing is deleted.

Request JSON Object:

  • result.guid (string) – The GUID of a device class, or of its PowerPack: 32 hexadecimal characters in either case, as many device classes shipped with the platform have lowercase GUIDs. The value is kept as provided, and compared without regard to case.

  • result.id (integer) – The numeric id of the device class.

  • result.name (string) – The class and description of the device class, joined by " | ".

  • success (boolean) – Whether the deletion succeeded.

GET /icons

List icons

Lists the icons that can be assigned to device classes (master_ap2.icons), ordered by name.

Creating icons is not part of this API: upload them with the GraphQL createIcon mutation, which validates and compresses the SVG.

Requires the DEV_CLASS_VIEW access hook.

Query Parameters:

  • search (string) – Keep only the icons whose name contains this text, ignoring case. The text is matched literally: % and _ are not wildcards. Surrounding whitespace is ignored, so a blank search lists every icon.

Status Codes:
Request JSON Object:

  • icons[].id (string) – The id of the icon.

  • icons[].name (string) – The name of the icon. Several icons can share a name.

  • icons[].size (integer) – The size of the icon, in bytes.

GET /device_classes/{device_class_identifier}/icon

Retrieve the icon of a device class

Returns the icon assigned to a device class (master_ap2.dev_class_icon), and its legacy fallback icon, which the platform shows when no icon is assigned.

Requires the DEV_CLASS_VIEW access hook.

Parameters:

  • device_class_identifier (string) – The numeric id, the GUID (in either case), or the name of the device class. A numeric value is treated as an id, unless it is a 32-digit GUID. The name is the class and description joined by " | ", used as-is and URL-encoded as usual; it may contain a /, but a name ending in /icon must be addressed by id or GUID. It is fuzzy matched when it has no exact match.

Status Codes:
Request JSON Object:

  • device_class.guid (string) – The GUID of a device class, or of its PowerPack: 32 hexadecimal characters in either case, as many device classes shipped with the platform have lowercase GUIDs. The value is kept as provided, and compared without regard to case.

  • device_class.id (integer) – The numeric id of the device class.

  • device_class.name (string) – The class and description of the device class, joined by " | ".

  • fallback_icon (any) – The legacy icon of the device class (master.definitions_dev_class_svg_icons joined to master.definitions_default_svg_icons), which the platform shows when no icon is assigned, or null. Its id is the svg_icon_guid of the legacy icon. This API never changes it, except that deleting the device class removes it.

  • icon (any) – The icon assigned to the device class (master_ap2.dev_class_icon), or null when none is assigned.

PUT /device_classes/{device_class_identifier}/icon

Assign or unassign the icon of a device class

Assigns an icon to a device class, by the icon’s id or exact name, or unassigns its icon with {"icon": null}.

This does exactly what the GraphQL setDeviceClassIcon mutation does: the device class’s row in master_ap2.dev_class_icon is replaced and the change is recorded in the audit log. The revision of the device class’s PowerPack is not incremented, and the legacy fallback icon is left as is.

Unlike the mutation, which always rewrites the assignment, assigning the icon the device class already has, or unassigning when none is assigned, changes nothing and writes no audit entry.

Requires the DEV_CLASS_VIEW and DEV_CLASS_EDIT access hooks. DEV_CLASS_EDIT is the hook setDeviceClassIcon checks; it is not the SYS_CUSTOM_DEV_CLASS_PAGE hook the other device class changes require.

Parameters:

  • device_class_identifier (string) – The numeric id, the GUID (in either case), or the exact name of the device class. A numeric value is treated as an id, unless it is a 32-digit GUID. The name is the class and description joined by " | ", used as-is and URL-encoded as usual; it may contain a /, but a name ending in /icon must be addressed by id or GUID. Requests that change a device class never fuzzy match a name, so a typo cannot select another device class: a name without an exact match returns 404.

Query Parameters:

  • commit (boolean) – When false, the change is validated and rolled back: the response is the one a committed change would return, and nothing is changed.

Response JSON Object:

  • icon (string) – The id of the icon, or its exact name, or null to unassign the icon. The id is looked up first. A name shared by several icons is rejected with 422. (required)

Status Codes:

  • 200 OK – The icons of the device class after the change.

  • 400 Bad Request – The body is malformed JSON (Invalid JSON payload provided), or is not an object with an icon that is a non-empty string or null (Invalid Icon Request).

  • 401 Unauthorized – Unauthenticated

  • 403 Forbidden – Forbidden (insufficient access hooks)

  • 404 Not Found – No device class has the id or GUID, or exactly the name, given (No device class found named exactly: <name>; names are not fuzzy matched here), or several device classes share the name (their GUIDs are in matches).

  • 415 Unsupported Media Type – Unsupported Media Type. The request body was not sent as JSON with a Content-Type of application/json.

  • 422 Unprocessable Entity – Invalid Icon: no icon has the id or name given, or several icons share the name (the message lists their ids; pass the id instead). Device Class(es) Failed Validation: the device class has no valid GUID. Nothing is changed.

  • 500 Internal Server Error – The icon could not be set (Could not set the Icon of a Device Class). Nothing is changed.

Request JSON Object:

  • result.device_class.guid (string) – The GUID of a device class, or of its PowerPack: 32 hexadecimal characters in either case, as many device classes shipped with the platform have lowercase GUIDs. The value is kept as provided, and compared without regard to case.

  • result.device_class.id (integer) – The numeric id of the device class.

  • result.device_class.name (string) – The class and description of the device class, joined by " | ".

  • result.fallback_icon (any) – The legacy icon of the device class (master.definitions_dev_class_svg_icons joined to master.definitions_default_svg_icons), which the platform shows when no icon is assigned, or null. Its id is the svg_icon_guid of the legacy icon. This API never changes it, except that deleting the device class removes it.

  • result.icon (any) – The icon assigned to the device class (master_ap2.dev_class_icon), or null when none is assigned.

  • success (boolean) – Whether the change succeeded.