logo
API docs by Redocly

Metasys REST API (4.494)

Download OpenAPI specification:Download

Introduction

The Metasys REST API is the exposed interface for accessing data from a Johnson Controls® Metasys system. This spec documents v4 of the API first released as part of Metasys 12.0. This documentation was last updated on November 16, 2023 at 5:23 PM (UTC).

Note
The Metasys REST API is only supported on the following Metasys products: ADS, ADX, and OAS. The REST API is not supported on Metasys for Validated Environments (MVE) sites. Do not attempt to use the REST API on an MVE site.

Metasys is a network-based building automation system (BAS) that operates the mechanical and electrical equipment in your building. For an introduction to Metasys, refer to Metasys System in Metasys System Configuration Guide. For a glossary of Metasys terms, refer to Metasys System Glossary. For additional information on Metasys, search the Johnson Controls documentation site Knowledge Exchange.

This specification defines the operations you can use to retrieve data through the API. For further information on the Metasys API, including tutorials, see the Metasys API home page.

© 2022 Johnson Controls Tyco IP Holdings LLP.

Base URL

This documentation is for Metasys 12.0 which ships with version 4 of the Metasys Server.

The base path for the API is https://{hostname}/api/v4 where {hostname} is the host name of your Metasys server.

API Version Notes

Multiple versions of this API may be supported on one release of Metasys. At Metasys 12.0, the supported versions are v2, v3, and v4.

Note: v1 is not supported by Metasys 12.0.

You must specify which version you intend to use in the URL, using the format v[#].

For example, https://localhost/api/v4/spaces for version 4 of spaces.

Documentation for v3 and earlier can be found here.

Version Response Behavior

The Content-Type header of the response will always contain (in part) the version of the API that was used to serve the request. This allows you to identify which version of the API was utilized.

For example, Content-Type: application/vnd.metasysapi.v4+json for version 4.

Licensed Operations

You must obtain an additional license to access some operations. For more information, refer to the Licensing information and Software information sections in Metasys System Software Purchase Options Product Bulletin (LIT-12011703).

Monitoring and Commanding API license

The Monitoring and Commanding API enables reading, writing, and commanding one or more Metasys objects/properties, including Present Value. This API succeeds the Metasys System Secure Data Access dynamic link library (MSSDA DLL).

The following operations require the Monitoring and Commanding API license:

Case Sensitivity Rules

In general, you should assume that all URLs, parameter names, parameter values, payload property names and payload property values are case sensitive. For example:

  • All attributes of objects are case sensitive. For example, many objects have an attribute named presentValue. It is case sensitive and must always be spelled presentValue.
  • Enumeration set names and set members are case sensitive (for example, reliabilityEnumSet.reliable, displayPrecisionEnumSet.displayPrecision1, and writePriorityEnumSet.priorityDefault).

Pagination

For operations where page and pageSize is allowed, the default page number will be 1 and is 1-based for all paths while the default pageSize will vary between paths. The page parameter indicates the page number of items to return from the path. The pageSize parameter indicates the maximum number of items in the response from the path.

Payloads returned by pagination-enabled paths have a similar structure. A total property indicates the total number of items included in all pages. A next and previous property supplies a link to the next and previous page of data, respectively. These properties can be empty if irrelevant (for example, if it is the first/last page, or there is only one page of data). The items property contains the data included in the page.

Sorting Rules

For operations where a sort query parameter is allowed, the supplied value should be in the format of a single attribute name, optionally prefixed with - to indicate descending sort order (ascending order is used if no prefix is supplied).

DateTimes

All date-times in the alarms, audits, activities, and samples operations are ISO-8601 encoded strings in UTC. Other operations, such as objects, use a proprietary structure further described in supporting documentation.

Validation and Common Error Codes

There are some general rules that apply across all operations. If certain provided inputs are invalid or preconditions are not met, the API will respond with an appropriate error to indicate what went wrong.

Condition Error Details
Invalid request body 400 (Bad Request) A body is provided which does not adhere to the expected format and/or schema
Missing required parameter 400 (Bad Request) A parameter marked required in this document is not included in the request
Parameter incorrect type 400 (Bad Request) A parameter is included with a value of the wrong type (for example, number is expected and string is provided)
Parameter out of range 400 (Bad Request) A numeric parameter is included but the value is outside the allowed range
Parameter not in set 400 (Bad Request) A string parameter has a set of predefined valid values, and the value provided is not included in that set
Parameter not in correct format 400 (Bad Request) A string parameter with expected format is provided in the wrong format
Unsupported Content-Type 400 (Bad Request) An unsupported Content-Type header is provided
User not authenticated 401 (Unauthorized) The auth token supplied with the request is missing, invalid, or expired
Record not authorized 403 (Forbidden) The user is not authorized to view data matching the provided identifier or too many requests
Invalid user type 403 (Forbidden) Not an "API user"; not all user accounts have API access
Identifier not found 404 (Not Found) An identifier is provided that does not match any known data
The resource already exists 409 (Conflict) The resource already exists
Internal Server Error 500 (Internal Server Error) An unexpected error occurred
The device is not supported 501 (Not Implemented) The server does not support the functionality required to fulfill the request
A service is unavailable 503 (Service Unavailable) A service is currently unavailable to service the request.
The device is offline 504 (Bad Gateway) An attempt was made to talk to another device that is currently offline.

Schemas in Response Payloads

The response payload of some operations in this document have a section of information labeled schema. This section of information includes important pieces of metadata about the item or items attributes that gives better context to the meaning of attribute values. This section follows JSON Schema specification with added custom annotation keywords.

Security

Bearer-Authentication

Most of the calls in the API use bearer token authentication. What this means is that these requests require an Authorization header to be set to a value with the following format: Bearer: {accessToken}. Use the /login operation to request an accessToken. An example of the full header would look like the following: Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1....

Note: This example access token is truncated.

The expiration time of the access token is based on the user's Metasys profile.

Note: If the expiration time of the access token is greater than 60 minutes from issue, disregard and refresh before 60 minutes to prevent session expiration. The next version of the API will provide the correct expiration time.

Security Scheme Type: HTTP
HTTP Authorization Scheme: bearer
Bearer format: JWT

API-Key-Authentication

The Streaming operation is the only operation to use API key authentication, because web browsers do not allow setting custom headers when initiating Server Sent Event connections.

Security Scheme Type: API Key
Query parameter name: access_token

activities

This section describes the operations you can perform on activities. Activities are a superset of all alarms and audits in a Metasys system. Use activities operations to view audits and alarms. Apply filters to further refine the results.

Activities Event Subscriptions

Subscribe for activity-related events to receive updates when activities are created, discarded, acknowledged, or annotated.

Subscribing

To subscribe for activity-related events, complete the following steps:

  1. Open a stream with the Get a stream operation. Take note of the stream ID.
  2. Use Get Activities and include a METASYS-SUBSCRIBE header with the stream ID.

Note: Any filters added to the original GET operation also apply the event subscription.

Unsubscribing

To unsubscribe from an activities event subscription, complete the following steps:

  1. Get the METASYS-SUBSCRIPTION-LOCATION from the subscribe operation response.
  2. Issue a Delete activities subscription request to METASYS-SUBSCRIPTION-LOCATION.

See also:

Events

There are five event types sent by the activities subscription: acknowledged, annotate, discard, new, and heartbeat.

  • activity.heartbeat - A heartbeat event is sent to show that the subscription is still alive. A heartbeat is a JSON string with the current UTC date time in ISO 8601 format and is sent every 30 seconds.

    Heartbeat Payload Example 
    {
  "currentTime": "2021-02-16T16:21:10.23Z",
  "subscriptionIds": ["c569a157-7315-4f32-bc8f-11607f075660"]
}

  • activity.alarm.ack - An alarm acknowledge event is sent to indicate that the management status has changed to acknowledged.

    Acknowledged Alarm Payload Example 
    {
  "subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
  "activity": {
    "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
    "itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
    "objectName": "OA_T",
    "activityManagementStatus": "acknowledged",
    "creationTime": "2021-02-16T20:30:00Z",
    "spaces": [
      {
        "id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
        "itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
        "name": "Floor 1",
        "spaceUrl": "https://{hostname}/api/v4/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
      }
    ],
    "equipment": [
      {
        "id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
        "itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
        "equipmentName": "Engine1",
        "shortName": null,
        "equipmentUrl": "https://{hostname}/api/v4/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
      }
    ],
    "objectUrl": "https://{hostname}/api/v4/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
    "objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
    "alarm": {
      "message": "",
      "alarmGeneratorObject": {
        "objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
        "referencedObject": {
          "objectUrl": "https://{hostname}/api/v4/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
        }
      },
      "isAckRequired": true,
      "acknowledgedTime": "2021-02-16T20:31:02Z",
      "type": "alarmValueEnumSet.avHiAlarm",
      "priority": 70,
      "category": "objectCategoryEnumSet.generalCategory",
      "annotationsUrl": "https://{hostname}/api/v4/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
      "self": "https://{hostname}/api/v4/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
      "triggerValue": {
        "item": "2.0",
        "schema": {
          "type": "string",
          "metasysType": "string",
          "units": {
            "id": "unitEnumSet.degF",
            "title": "deg F"
          }
        }
      },
      "description": ""
    }
  },
  "effectivePermission": {
    "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
    "canAcknowledge": true,
    "canDiscard": true,
    "canAnnotate": true
  }
}

  • activity.alarm.annotate - An alarm annotate event is sent when an annotation is added to an alarm activity, providing the information for the annotated alarm.

    Annotate Alarm Payload Example 
    {
  "subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
  "activity": {
    "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
    "itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
    "objectName": "OA_T",
    "activityManagementStatus": "pending",
    "creationTime": "2021-02-16T20:30:00Z",
    "spaces": [
      {
        "id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
        "itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
        "name": "Floor 1",
        "spaceUrl": "https://{hostname}/api/v4/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
      }
    ],
    "equipment": [
      {
        "id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
        "itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
        "equipmentName": "Engine1",
        "shortName": null,
        "equipmentUrl": "https://{hostname}/api/v4/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
      }
    ],
    "objectUrl": "https://{hostname}/api/v4/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
    "objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
    "alarm": {
      "message": "",
      "alarmGeneratorObject": {
        "objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
        "referencedObject": {
          "objectUrl": "https://{hostname}/api/v4/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
        }
      },
      "isAckRequired": true,
      "acknowledgedTime": "2021-02-16T20:31:02Z",
      "type": "alarmValueEnumSet.avHiAlarm",
      "priority": 70,
      "category": "objectCategoryEnumSet.generalCategory",
      "annotationsUrl": "https://{hostname}/api/v4/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
      "self": "https://{hostname}/api/v4/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
      "triggerValue": {
        "item": "2.0",
        "schema": {
          "type": "string",
          "metasysType": "string",
          "units": {
            "id": "unitEnumSet.degF",
            "title": "deg F"
          }
        }
      },
      "description": ""
    }
  },
  "effectivePermission": {
    "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
    "canAcknowledge": true,
    "canDiscard": true,
    "canAnnotate": true
  }
}

  • activity.alarm.discard - An alarm discard event is sent when the management status of an alarm activity changes to discarded.

    Discard Alarm Payload Example 
    {
  "subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
  "activity": {
    "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
    "itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
    "objectName": "OA_T",
    "activityManagementStatus": "discarded",
    "creationTime": "2021-02-16T20:30:00Z",
    "spaces": [
      {
        "id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
        "itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
        "name": "Floor 1",
        "spaceUrl": "https://{hostname}/api/v4/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
      }
    ],
    "equipment": [
      {
        "id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
        "itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
        "equipmentName": "Engine1",
        "shortName": null,
        "equipmentUrl": "https://{hostname}/api/v4/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
      }
    ],
    "objectUrl": "https://{hostname}/api/v4/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
    "objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
    "alarm": {
      "message": "",
      "alarmGeneratorObject": {
        "objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
        "referencedObject": {
          "objectUrl": "https://{hostname}/api/v4/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
        }
      },
      "isAckRequired": true,
      "acknowledgedTime": "2021-02-16T20:31:02Z",
      "type": "alarmValueEnumSet.avHiAlarm",
      "priority": 70,
      "category": "objectCategoryEnumSet.generalCategory",
      "annotationsUrl": "https://{hostname}/api/v4/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
      "self": "https://{hostname}/api/v4/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
      "triggerValue": {
        "item": "2.0",
        "schema": {
          "type": "string",
          "metasysType": "string",
          "units": {
            "id": "unitEnumSet.degF",
            "title": "deg F"
          }
        }
      },
      "description": ""
    }
  },
  "effectivePermission": {
    "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
    "canAcknowledge": true,
    "canDiscard": true,
    "canAnnotate": true
  }
}

  • activity.alarm.new - A new alarm event is sent when an alarm activity is created.

    New Alarm Payload Example 
    {
  "subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
  "activity": {
    "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
    "itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
    "objectName": "OA_T",
    "activityManagementStatus": "pending",
    "creationTime": "2021-02-16T20:30:00Z",
    "spaces": [
      {
        "id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
        "itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
        "name": "Floor 1",
        "spaceUrl": "https://{hostname}/api/v4/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
      }
    ],
    "equipment": [
      {
        "id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
        "itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
        "equipmentName": "IDU1",
        "shortName": null,
        "equipmentUrl": "https://{hostname}/api/v4/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
      }
    ],
    "objectUrl": "https://{hostname}/api/v4/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
    "objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
    "alarm": {
      "message": "",
      "alarmGeneratorObject": {
        "objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
        "referencedObject": {
          "objectUrl": "https://{hostname}/api/v4/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
        }
      },
      "isAckRequired": true,
      "type": "alarmValueEnumSet.avHiAlarm",
      "priority": 70,
      "category": "objectCategoryEnumSet.generalCategory",
      "annotationsUrl": "https://{hostname}/api/v4/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
      "self": "https://{hostname}/api/v4/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
      "triggerValue": {
        "item": "2.0",
        "schema": {
          "type": "string",
          "metasysType": "string",
          "units": {
            "id": "unitEnumSet.degF",
            "title": "deg F"
          }
        }
      },
      "description": ""
    }
  },
  "effectivePermission": {
    "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
    "canAcknowledge": true,
    "canDiscard": true,
    "canAnnotate": true
  }
}

  • activity.audit.new - A new audit event is sent when an audit activity is created.

    New Audit Payload Example 
    {
  "subscriptionIds": ["7373cc85-37a5-4ad5-b703-6bc61968aa9a"],
  "activity": {
    "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
    "itemReference": "{hostname}:{deviceHostname}",
    "objectName": "MS-NAE5510-3",
    "activityManagementStatus": "pending",
    "creationTime": "2021-02-16T16:21:10.23Z",
    "objectUrl": "https://{hostname}/api/v4/objects/CDAC85B9-726F-5677-9CBC-ADC77A14E79B",
    "objectId": "cdac85b9-726f-5677-9cbc-adc77a14e79b",
    "audit": {
      "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
      "status": null,
      "preData": null,
      "postData": {
        "item": "10.10.198.131",
        "schema": {
          "type": "string",
          "metasysType": "string"
        }
      },
      "parameters": [],
      "errorString": null,
      "user": "MetasysSysAgent",
      "signature": null,
      "classLevel": "auditClassesEnumSet.userActionAuditClass",
      "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
      "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful",
      "annotationsUrl": null,
      "self": "https://{hostname}/api/v4/audits/128d7db4-8ab6-4232-afe1-026fe06d267f"
    }
  },
  "effectivePermission": {
    "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
    "canDiscard": true
  }
}

  • activity.audit.annotate - An annotate audit event is sent when an annotation is added to an audit activity, providing the information for the annotated audit.

    Annotate Audit Payload Example 
    {
  "subscriptionIds": ["7373cc85-37a5-4ad5-b703-6bc61968aa9a"],
  "activity": {
    "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
    "itemReference": "{hostname}:{deviceHostname}",
    "objectName": "MS-NAE5510-3",
    "activityManagementStatus": "pending",
    "creationTime": "2021-02-16T16:21:10.23Z",
    "objectUrl": "https://{hostname}/api/v4/objects/CDAC85B9-726F-5677-9CBC-ADC77A14E79B",
    "objectId": "cdac85b9-726f-5677-9cbc-adc77a14e79b",
    "audit": {
      "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
      "status": null,
      "preData": null,
      "postData": {
        "item": "10.10.198.131",
        "schema": {
          "type": "string",
          "metasysType": "string"
        }
      },
      "parameters": [],
      "errorString": null,
      "user": "MetasysSysAgent",
      "signature": null,
      "classLevel": "auditClassesEnumSet.userActionAuditClass",
      "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
      "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful",
      "annotationsUrl": "https://{hostname}/api/v4/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
      "self": "https://{hostname}/api/v4/audits/128d7db4-8ab6-4232-afe1-026fe06d267f"
    }
  },
  "effectivePermission": {
    "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
    "canDiscard": true
  }
}

  • activity.audit.discard - An audit discard event is sent when the management status of an audit activity changes to discarded.

    Discard Audit Payload Example 
    {
  "subscriptionIds": ["7373cc85-37a5-4ad5-b703-6bc61968aa9a"],
  "activity": {
    "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
    "itemReference": "{hostname}:{deviceHostname}",
    "objectName": "MS-NAE5510-3",
    "activityManagementStatus": "discarded",
    "creationTime": "2021-02-16T16:21:10.23Z",
    "objectUrl": "https://{hostname}/api/v4/objects/CDAC85B9-726F-5677-9CBC-ADC77A14E79B",
    "objectId": "cdac85b9-726f-5677-9cbc-adc77a14e79b",
    "audit": {
      "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
      "status": null,
      "preData": null,
      "postData": {
        "item": "10.10.198.131",
        "schema": {
          "type": "string",
          "metasysType": "string"
        }
      },
      "parameters": [],
      "errorString": null,
      "user": "MetasysSysAgent",
      "signature": null,
      "classLevel": "auditClassesEnumSet.userActionAuditClass",
      "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
      "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful",
      "annotationsUrl": "https://{hostname}/api/v4/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
      "self": "https://{hostname}/api/v4/audits/128d7db4-8ab6-4232-afe1-026fe06d267f"
    }
  },
  "effectivePermission": {
    "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
    "canDiscard": true
  }
}

Filter Behavior

Filters supplied to an activities request limit the results to activities for which the filters apply. When subscribing to an activities request that uses filters, the events received are also limited to the same filter criteria. Exceptions to this behavior occur when filtering on activity management status, such as for acknowledged or discarded activities. You receive an update whenever an activity management change occurs, regardless of filters, because the change can impact the original set of activities you subscribed to. For example, consider the following scenario:

  • You subscribe to acknowledged activities and receive all acknowledged activities, receiving updates for any acknowledged thereafter across the stream.
  • In this state, one of the activities in your original list is discarded by another user.

When this occurs, you receive an activity.alarm.discard message for the discarded activity even though your filters exclude activities that are discarded. This is necessary so that you can properly maintain the state of activities already received in your application.

List activities

Retrieves a collection of activities.

Authorizations:
Bearer-Authentication
query Parameters
activityType
Array of strings[ items <= 2 items ]
Items Enum: "alarm" "audit"
Example: activityType=alarm

Limit the activities returned to a specific type

includeDiscarded
boolean

Determines whether discarded activities will be included in the results or be the only type of activity in the results. Discarded activities are those for which the activityManagementStatus is discarded.

This parameter can produce 3 different types of results.

  • true - Return only discarded activities in the response.
  • false - Do not include any discarded activities in the response.
  • missing - (default) Discarded status is ignored; both discarded and non-discarded activities are returned.
continuationToken
string
Example: continuationToken=eyJhdWRpdCI6eyJpZCI6IjgOTQ2NjUzLTlmM...

Provide a token from a previous request to fetch the next set of results. Ignored for streaming subscriptions.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime" "priority" "-priority"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

equipment
Array of strings <= 100 items
Example: equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398

Filter by list of equipment identifiers.

object
Array of strings <= 100 items
Example: object=06d77c63-6357-467a-a306-5e1ab3eb3aa7

Filter by list of object identifiers.

space
Array of strings <= 100 items
Example: space=214f52d1-0c56-4a29-a690-abe5656d1647

Filter by list of space identifiers.

priorityRange
string^\d+,\d+$
Example: priorityRange=0,255

Includes only results within the specified alarm priority range, from 0 to 255 inclusive.

type
Array of strings[ items <= 100 items ]
Example: type=alarmValueEnumSet.avHighLimit
metasysEnum: alarmValueEnumSet

Limits the alarms returned to specified types.

The acceptable values for the elements of this parameter come from the alarmValueEnumSet enumeration. Only the long name of the alarm value (for example, alarmValueEnumSet.avHighLimit instead of avHighLimit) is accepted. Find the definition of alarmValueEnumSet at the relative URL of /schemas/enums/alarmValueEnumSet.

See also:

includeAcknowledged
boolean

Determines whether acknowledged alarms will be included in the results or be the only type of alarm in the results. Acknowledged alarms are those which have an acknowledgedTime value set.

This parameter can produce 3 different types of results.

  • true - Return only acknowledged alarms in the response.
  • false - Do not include any acknowledged alarms in the response.
  • missing - (default) Acknowledged status is ignored; both acknowledged and non-acknowledged alarms are returned.
includeAcknowledgementRequired
boolean
Default: true
Example: includeAcknowledgementRequired=true

Determines whether activities which can be acknowledged are included in the results. When the value is true, activities which can be acknowledged will be included in the results. When false, activities which can be acknowledged will not be included in the results.

The use of this parameter implies a filter of activityType=alarm and the results will not include any audits.

includeAcknowledgementNotRequired
boolean
Default: true
Example: includeAcknowledgementNotRequired=true

Determines whether activities which can not be acknowledged are included in the results. When the value is true then the results will include activities which cannot be acknowledged. When the value is false then the results will not include activities which cannot be acknowledged.

The use of this parameter implies a filter of activityType=alarm and the results will not include any audits.

category
Array of strings
Example: category=objectCategoryEnumSet.hvacCategory
metasysEnum: objectCategoryEnumSet

The authorization category of the requested activities.

The acceptable values for the elements of this parameter come from the objectCategoryEnumSet enumeration. Only the long name of the object category (for example, objectCategoryEnumSet.hvacCategory instead of hvacCategory) is accepted. Find the definition of objectCategoryEnumSet at the relative URL of /schemas/enums/objectCategoryEnumSet.

See also:

originApplication
Array of strings
Example: originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp
metasysEnum: auditOriginAppEnumSet

Filter by list of origin applications. The origin application property indicates which application in Metasys generated the audit message.

The acceptable values for the elements of this parameter come from the auditOriginAppEnumSet enumeration. Only the long name of the origin application (for example, auditOriginAppEnumSet.deviceManagerAuditOriginApp instead of deviceManagerAuditOriginApp) is accepted. Find the definition of auditOriginAppEnumSet at the relative URL of /schemas/enums/auditOriginAppEnumSet.

See also:

classLevel
Array of strings
Example: classLevel=auditClassesEnumSet.userActionAuditClass
metasysEnum: auditClassesEnumSet

Filter by list of class levels. The class level of an audit indicates the class or family the audit belongs to. Typically, each level of audit provides additional detail about the system, with Diagnostic audits being the most verbose.

The Enabled Audit Level attribute (attributeEnumSet.auditEnabledClasLev) determines which audit levels the system generates. Therefore, be aware that there will be no audits to return if the Enabled Audit Level attribute is set too low to generate audits at the desired class level in this filter. This attribute is set per device (for audits generated on that device).

The acceptable values for the elements of this parameter come from the auditClassesEnumSet enumeration. Only the long name of the class level (for example, auditClassesEnumSet.userActionAuditClass instead of userActionAuditClass) is accepted. Find the definition of auditClassesEnumSet at the relative URL of /schemas/enums/auditClassesEnumSet.

See also:

actionType
Array of strings
Example: actionType=auditActionTypeEnumSet.writeAuditActionType
metasysEnum: auditActionTypeEnumSet

Filter by list of action types. The action type property indicates the user or system action performed.

The acceptable values for the elements of this parameter come from the auditActionTypeEnumSet enumeration. Only the long name of the action type (for example, auditActionTypeEnumSet.writeAuditActionType instead of writeAuditActionType) is accepted. Find the definition of auditActionTypeEnumSet at the relative URL of /schemas/enums/auditActionTypeEnumSet.

See also:

user
Array of strings <= 100 items
Example: user=metasysuser

Filter by list of users. The user property indicates which user initiated the action being audited.

header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/activities?activityType=alarm&includeDiscarded=false&continuationToken=eyJhdWRpdCI6eyJpZCI6IjgOTQ2NjUzLTlmM...&sort=creationTime&startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398&object=06d77c63-6357-467a-a306-5e1ab3eb3aa7&space=214f52d1-0c56-4a29-a690-abe5656d1647&priorityRange=0%2C255&type=alarmValueEnumSet.avHighLimit&includeAcknowledged=false&includeAcknowledgementRequired=true&includeAcknowledgementNotRequired=true&category=objectCategoryEnumSet.hvacCategory&originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp&classLevel=auditClassesEnumSet.userActionAuditClass&actionType=auditActionTypeEnumSet.writeAuditActionType&user=metasysuser' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'

Response samples

Content type
application/vnd.metasysapi.v4+json

The first 10 activities.

{}

Batch operations

Used to invoke multiple activity operations in a single HTTP request. In this version of the API, the only activity-related operations that can be used in a batch are listed below.

See also

Authorizations:
Bearer-Authentication
Request Body schema: application/json
method
required
string
Enum: "PATCH" "POST"

The HTTP method to use for each request.

required
Array of objects

A collection of entries that represent the operations to invoke.

Responses

Request samples

Content type
application/json
Example

A request to discard multiple activities (2 audits and 2 alarms). One audit request and one alarm request include annotation text and the other requests do not.

{}

Response samples

Content type
application/vnd.metasysapi.v4+json

This is an example response to a batch request. Two of the operations succeeded and two of them failed.

{
  • "responses": [
    ]
}

Delete activities subscription

Deletes a subscription to the activities resource.

Authorizations:
Bearer-Authentication
path Parameters
streamId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The stream identifier that contains the subscription. This is the unique identifier for the client's stream obtained via GET /stream.

subscriptionId
required
string
Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5

The identifier of the subscription to act upon. This is the unique identifier to the subscription for a specific resource or type of event. This value is found as the last parameter of a METASYS-SUBSCRIPTION-LOCATION header returned for the original subscription request.

Responses

Request samples 

curl --request DELETE \
  --url https:///%7Bhostname%7D/api/v4/activities/streams/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/subscriptions/626e5ac3-506d-4017-bb8f-973f1c54ddb5 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

alarms

Alarms alert users to potential problems identified by a Metasys system, for example high zone temperatures. Use alarms operations to get object alarms, network device alarms, single alarms, alarm collections, and alarm annotations. Acknowledge or discard alarms with the edit patch operation. Filter the results with the query parameters time, priority, type, category, acknowledgement, and page. Sort the results by creation time and priority.

Get alarms for an object

Retrieves a collection of alarms for the specified object.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

priorityRange
string^\d+,\d+$
Example: priorityRange=0,255

Includes only results within the specified alarm priority range, from 0 to 255 inclusive.

type
Array of strings[ items <= 100 items ]
Example: type=alarmValueEnumSet.avHighLimit
metasysEnum: alarmValueEnumSet

Limits the alarms returned to specified types.

The acceptable values for the elements of this parameter come from the alarmValueEnumSet enumeration. Only the long name of the alarm value (for example, alarmValueEnumSet.avHighLimit instead of avHighLimit) is accepted. Find the definition of alarmValueEnumSet at the relative URL of /schemas/enums/alarmValueEnumSet.

See also:

includeAcknowledged
boolean

Determines whether acknowledged alarms will be included in the results or be the only type of alarm in the results. Acknowledged alarms are those which have an acknowledgedTime value set.

This parameter can produce 3 different types of results.

  • true - Return only acknowledged alarms in the response.
  • false - Do not include any acknowledged alarms in the response.
  • missing - (default) Acknowledged status is ignored; both acknowledged and non-acknowledged alarms are returned.
includeDiscarded
boolean

Determines whether discarded alarms will be included in the results or be the only type of alarm in the results. Discarded alarms are those for which the activityManagementStatus is discarded. This parameter can produce 3 different types of results.

  • true - Return only discarded alarms in the response.
  • false - Do not include any discarded alarms in the response.
  • missing - (default) Discarded status is ignored; both discarded and non-discarded alarms are returned.
includeAcknowledgementRequired
boolean
Default: true
Example: includeAcknowledgementRequired=true

Determines whether alarms which can be acknowledged are included in the results. When the value is true, alarms which can be acknowledged will be included in the results. When false, alarms which can be acknowledged will not be included in the results.

includeAcknowledgementNotRequired
boolean
Default: true
Example: includeAcknowledgementNotRequired=true

Determines whether alarms which can not be acknowledged are included in the results. When the value is true then the results will include alarms which cannot be acknowledged. When the value is false then the results will not include alarms which cannot be acknowledged.

category
Array of strings
Example: category=objectCategoryEnumSet.hvacCategory
metasysEnum: objectCategoryEnumSet

The authorization category of the requested activities.

The acceptable values for the elements of this parameter come from the objectCategoryEnumSet enumeration. Only the long name of the object category (for example, objectCategoryEnumSet.hvacCategory instead of hvacCategory) is accepted. Find the definition of objectCategoryEnumSet at the relative URL of /schemas/enums/objectCategoryEnumSet.

See also:

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime" "priority" "-priority"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/alarms?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&priorityRange=0%2C255&type=alarmValueEnumSet.avHighLimit&includeAcknowledged=false&includeDiscarded=false&includeAcknowledgementRequired=true&includeAcknowledgementNotRequired=true&category=objectCategoryEnumSet.hvacCategory&page=1&pageSize=100&sort=creationTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

The first 10 alarms.

{}

Get alarms for a network device

Retrieves a collection of alarms for the specified network device.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

priorityRange
string^\d+,\d+$
Example: priorityRange=0,255

Includes only results within the specified alarm priority range, from 0 to 255 inclusive.

type
Array of strings[ items <= 100 items ]
Example: type=alarmValueEnumSet.avHighLimit
metasysEnum: alarmValueEnumSet

Limits the alarms returned to specified types.

The acceptable values for the elements of this parameter come from the alarmValueEnumSet enumeration. Only the long name of the alarm value (for example, alarmValueEnumSet.avHighLimit instead of avHighLimit) is accepted. Find the definition of alarmValueEnumSet at the relative URL of /schemas/enums/alarmValueEnumSet.

See also:

includeAcknowledged
boolean

Determines whether acknowledged alarms will be included in the results or be the only type of alarm in the results. Acknowledged alarms are those which have an acknowledgedTime value set.

This parameter can produce 3 different types of results.

  • true - Return only acknowledged alarms in the response.
  • false - Do not include any acknowledged alarms in the response.
  • missing - (default) Acknowledged status is ignored; both acknowledged and non-acknowledged alarms are returned.
includeDiscarded
boolean

Determines whether discarded alarms will be included in the results or be the only type of alarm in the results. Discarded alarms are those for which the activityManagementStatus is discarded. This parameter can produce 3 different types of results.

  • true - Return only discarded alarms in the response.
  • false - Do not include any discarded alarms in the response.
  • missing - (default) Discarded status is ignored; both discarded and non-discarded alarms are returned.
includeAcknowledgementRequired
boolean
Default: true
Example: includeAcknowledgementRequired=true

Determines whether alarms which can be acknowledged are included in the results. When the value is true, alarms which can be acknowledged will be included in the results. When false, alarms which can be acknowledged will not be included in the results.

includeAcknowledgementNotRequired
boolean
Default: true
Example: includeAcknowledgementNotRequired=true

Determines whether alarms which can not be acknowledged are included in the results. When the value is true then the results will include alarms which cannot be acknowledged. When the value is false then the results will not include alarms which cannot be acknowledged.

equipment
Array of strings <= 100 items
Example: equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398

Filter by list of equipment identifiers.

object
Array of strings <= 100 items
Example: object=06d77c63-6357-467a-a306-5e1ab3eb3aa7

Filter by list of object identifiers.

space
Array of strings <= 100 items
Example: space=214f52d1-0c56-4a29-a690-abe5656d1647

Filter by list of space identifiers.

category
Array of strings
Example: category=objectCategoryEnumSet.hvacCategory
metasysEnum: objectCategoryEnumSet

The authorization category of the requested activities.

The acceptable values for the elements of this parameter come from the objectCategoryEnumSet enumeration. Only the long name of the object category (for example, objectCategoryEnumSet.hvacCategory instead of hvacCategory) is accepted. Find the definition of objectCategoryEnumSet at the relative URL of /schemas/enums/objectCategoryEnumSet.

See also:

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime" "priority" "-priority"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/alarms?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&priorityRange=0%2C255&type=alarmValueEnumSet.avHighLimit&includeAcknowledged=false&includeDiscarded=false&includeAcknowledgementRequired=true&includeAcknowledgementNotRequired=true&equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398&object=06d77c63-6357-467a-a306-5e1ab3eb3aa7&space=214f52d1-0c56-4a29-a690-abe5656d1647&category=objectCategoryEnumSet.hvacCategory&page=1&pageSize=100&sort=creationTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

The first 10 alarms.

{}

Get alarms Deprecated

Retrieves a collection of alarms.

Note: This operation is deprecated and may be removed in a future release. To retrieve alarms, consider using GET /activities?activityType=alarm instead. See List activities

Authorizations:
Bearer-Authentication
query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

priorityRange
string^\d+,\d+$
Example: priorityRange=0,255

Includes only results within the specified alarm priority range, from 0 to 255 inclusive.

type
Array of strings[ items <= 100 items ]
Example: type=alarmValueEnumSet.avHighLimit
metasysEnum: alarmValueEnumSet

Limits the alarms returned to specified types.

The acceptable values for the elements of this parameter come from the alarmValueEnumSet enumeration. Only the long name of the alarm value (for example, alarmValueEnumSet.avHighLimit instead of avHighLimit) is accepted. Find the definition of alarmValueEnumSet at the relative URL of /schemas/enums/alarmValueEnumSet.

See also:

includeAcknowledged
boolean

Determines whether acknowledged alarms will be included in the results or be the only type of alarm in the results. Acknowledged alarms are those which have an acknowledgedTime value set.

This parameter can produce 3 different types of results.

  • true - Return only acknowledged alarms in the response.
  • false - Do not include any acknowledged alarms in the response.
  • missing - (default) Acknowledged status is ignored; both acknowledged and non-acknowledged alarms are returned.
includeDiscarded
boolean

Determines whether discarded alarms will be included in the results or be the only type of alarm in the results. Discarded alarms are those for which the activityManagementStatus is discarded. This parameter can produce 3 different types of results.

  • true - Return only discarded alarms in the response.
  • false - Do not include any discarded alarms in the response.
  • missing - (default) Discarded status is ignored; both discarded and non-discarded alarms are returned.
includeAcknowledgementRequired
boolean
Default: true
Example: includeAcknowledgementRequired=true

Determines whether alarms which can be acknowledged are included in the results. When the value is true, alarms which can be acknowledged will be included in the results. When false, alarms which can be acknowledged will not be included in the results.

includeAcknowledgementNotRequired
boolean
Default: true
Example: includeAcknowledgementNotRequired=true

Determines whether alarms which can not be acknowledged are included in the results. When the value is true then the results will include alarms which cannot be acknowledged. When the value is false then the results will not include alarms which cannot be acknowledged.

equipment
Array of strings <= 100 items
Example: equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398

Filter by list of equipment identifiers.

object
Array of strings <= 100 items
Example: object=06d77c63-6357-467a-a306-5e1ab3eb3aa7

Filter by list of object identifiers.

space
Array of strings <= 100 items
Example: space=214f52d1-0c56-4a29-a690-abe5656d1647

Filter by list of space identifiers.

category
Array of strings
Example: category=objectCategoryEnumSet.hvacCategory
metasysEnum: objectCategoryEnumSet

The authorization category of the requested activities.

The acceptable values for the elements of this parameter come from the objectCategoryEnumSet enumeration. Only the long name of the object category (for example, objectCategoryEnumSet.hvacCategory instead of hvacCategory) is accepted. Find the definition of objectCategoryEnumSet at the relative URL of /schemas/enums/objectCategoryEnumSet.

See also:

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime" "priority" "-priority"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/alarms?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&priorityRange=0%2C255&type=alarmValueEnumSet.avHighLimit&includeAcknowledged=false&includeDiscarded=false&includeAcknowledgementRequired=true&includeAcknowledgementNotRequired=true&equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398&object=06d77c63-6357-467a-a306-5e1ab3eb3aa7&space=214f52d1-0c56-4a29-a690-abe5656d1647&category=objectCategoryEnumSet.hvacCategory&page=1&pageSize=100&sort=creationTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

The first 10 alarms.

{}

Get an alarm

Retrieves the specified alarm.

Authorizations:
Bearer-Authentication
path Parameters
alarmId
required
string
Example: 4d0598d4-2836-4efd-84b8-6f39754b1fc5

The identifier of the alarm.

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/alarms/4d0598d4-2836-4efd-84b8-6f39754b1fc5 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

An alarm for an analog value object.

{}

Edit an alarm

Allows for acknowledging or discarding an alarm.

Authorizations:
Bearer-Authentication
path Parameters
alarmId
required
string
Example: 4d0598d4-2836-4efd-84b8-6f39754b1fc5

The identifier of the alarm.

Request Body schema: application/json
activityManagementStatus
required
string
Enum: "acknowledged" "discarded"

The new activity management status of the alarm.

The values of this property are described as follows:

  • acknowledged - The alarm has been recognized and viewed by a user. An alarm may only be acknowledged if activityManagementStatus is currently pending and isAckRequired is true.
  • discarded - The alarm has been acted upon and addressed by a user. Once an alarm is discarded, it cannot be changed to any other state.
annotationText
string or null

The annotation associated with the change of alarm state.

Responses

Request samples

Content type
application/json
Example
{
  • "activityManagementStatus": "acknowledged"
}

Get alarm annotations

Retrieves the collection of annotations available for the specified alarm.

Authorizations:
Bearer-Authentication
path Parameters
alarmId
required
string
Example: 4d0598d4-2836-4efd-84b8-6f39754b1fc5

The identifier of the alarm.

query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime" "user" "-user"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/alarms/4d0598d4-2836-4efd-84b8-6f39754b1fc5/annotations?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&page=1&pageSize=100&sort=creationTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
{}

audits

How to retrieve, discard, and annotate audits.

Relationships

Audits have relationships to other resources in the system. Find information about the most important below.

  • objects

When users or the system affect objects in the Metasys system, such as analog inputs, multistate objects, or binary outputs, audits are generated. Those "acted upon" objects then relate to those audits. That relationship is returned as part of any audit response.

  • equipment instances

Equipment instance associations to audits build off of the objects association explanation. Each equipment instance can contain many points, such as Outdoor Air Temperature, Damper Position, or Zone Setpoint. Those points map to actual objects in Metasys, as noted above. When users or the system affect those objects, audits are generated. If an equipment instance's point is mapped to one of those affected objects the instance is then associated with that audit.

In short, an equipment instance contains points which map to Metasys objects which are affected by an audited action.

  • spaces

Space associations to audits build off of the equipment instance association explanation. Equipment instances can serve spaces, such as an Air Handler Unit (AHU) serving the floor of a building. Therefore, audits associated with a particular equipment instance are associated to the spaces they serve.

Get audits for an object

Retrieves a collection of audits for the specified object.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

originApplication
Array of strings
Example: originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp
metasysEnum: auditOriginAppEnumSet

Filter by list of origin applications. The origin application property indicates which application in Metasys generated the audit message.

The acceptable values for the elements of this parameter come from the auditOriginAppEnumSet enumeration. Only the long name of the origin application (for example, auditOriginAppEnumSet.deviceManagerAuditOriginApp instead of deviceManagerAuditOriginApp) is accepted. Find the definition of auditOriginAppEnumSet at the relative URL of /schemas/enums/auditOriginAppEnumSet.

See also:

classLevel
Array of strings
Example: classLevel=auditClassesEnumSet.userActionAuditClass
metasysEnum: auditClassesEnumSet

Filter by list of class levels. The class level of an audit indicates the class or family the audit belongs to. Typically, each level of audit provides additional detail about the system, with Diagnostic audits being the most verbose.

The Enabled Audit Level attribute (attributeEnumSet.auditEnabledClasLev) determines which audit levels the system generates. Therefore, be aware that there will be no audits to return if the Enabled Audit Level attribute is set too low to generate audits at the desired class level in this filter. This attribute is set per device (for audits generated on that device).

The acceptable values for the elements of this parameter come from the auditClassesEnumSet enumeration. Only the long name of the class level (for example, auditClassesEnumSet.userActionAuditClass instead of userActionAuditClass) is accepted. Find the definition of auditClassesEnumSet at the relative URL of /schemas/enums/auditClassesEnumSet.

See also:

actionType
Array of strings
Example: actionType=auditActionTypeEnumSet.writeAuditActionType
metasysEnum: auditActionTypeEnumSet

Filter by list of action types. The action type property indicates the user or system action performed.

The acceptable values for the elements of this parameter come from the auditActionTypeEnumSet enumeration. Only the long name of the action type (for example, auditActionTypeEnumSet.writeAuditActionType instead of writeAuditActionType) is accepted. Find the definition of auditActionTypeEnumSet at the relative URL of /schemas/enums/auditActionTypeEnumSet.

See also:

user
Array of strings <= 100 items
Example: user=metasysuser

Filter by list of users. The user property indicates which user initiated the action being audited.

includeDiscarded
boolean

Determines whether discarded audits will be included in the results.

  • true - Return only discarded audits in the response.
  • false - Do not include any discarded audits in the response.
  • missing - Discarded status is ignored; both discarded and non-discarded audits are returned.
equipment
Array of strings <= 100 items
Example: equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398

Filter by list of equipment identifiers.

space
Array of strings <= 100 items
Example: space=214f52d1-0c56-4a29-a690-abe5656d1647

Filter by list of space identifiers.

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/audits?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp&classLevel=auditClassesEnumSet.userActionAuditClass&actionType=auditActionTypeEnumSet.writeAuditActionType&user=metasysuser&includeDiscarded=false&equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398&space=214f52d1-0c56-4a29-a690-abe5656d1647&page=1&pageSize=100&sort=creationTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

Gets the first 10 audits.

{
  • "total": 400,
  • "next": "https://{hostname}/api/v4/objects/a68f10e5-da10-5b87-a96b-42a36e9919ae/audits?page=2&pageSize=10&sort=-creationtime",
  • "previous": null,
  • "items": [
    ],
  • "effectivePermissions": [
    ],
  • "self": "https://{hostname}/api/v4/audits?page=1&pageSize=10&sort=-creationtime"
}

Get audits Deprecated

Retrieves a collection of audits.

Note: This operation is deprecated and may be removed in a future release. To retrieve audits, consider using GET /activities?activityType=audit instead. See List activities

Authorizations:
Bearer-Authentication
query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

originApplication
Array of strings
Example: originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp
metasysEnum: auditOriginAppEnumSet

Filter by list of origin applications. The origin application property indicates which application in Metasys generated the audit message.

The acceptable values for the elements of this parameter come from the auditOriginAppEnumSet enumeration. Only the long name of the origin application (for example, auditOriginAppEnumSet.deviceManagerAuditOriginApp instead of deviceManagerAuditOriginApp) is accepted. Find the definition of auditOriginAppEnumSet at the relative URL of /schemas/enums/auditOriginAppEnumSet.

See also:

classLevel
Array of strings
Example: classLevel=auditClassesEnumSet.userActionAuditClass
metasysEnum: auditClassesEnumSet

Filter by list of class levels. The class level of an audit indicates the class or family the audit belongs to. Typically, each level of audit provides additional detail about the system, with Diagnostic audits being the most verbose.

The Enabled Audit Level attribute (attributeEnumSet.auditEnabledClasLev) determines which audit levels the system generates. Therefore, be aware that there will be no audits to return if the Enabled Audit Level attribute is set too low to generate audits at the desired class level in this filter. This attribute is set per device (for audits generated on that device).

The acceptable values for the elements of this parameter come from the auditClassesEnumSet enumeration. Only the long name of the class level (for example, auditClassesEnumSet.userActionAuditClass instead of userActionAuditClass) is accepted. Find the definition of auditClassesEnumSet at the relative URL of /schemas/enums/auditClassesEnumSet.

See also:

actionType
Array of strings
Example: actionType=auditActionTypeEnumSet.writeAuditActionType
metasysEnum: auditActionTypeEnumSet

Filter by list of action types. The action type property indicates the user or system action performed.

The acceptable values for the elements of this parameter come from the auditActionTypeEnumSet enumeration. Only the long name of the action type (for example, auditActionTypeEnumSet.writeAuditActionType instead of writeAuditActionType) is accepted. Find the definition of auditActionTypeEnumSet at the relative URL of /schemas/enums/auditActionTypeEnumSet.

See also:

user
Array of strings <= 100 items
Example: user=metasysuser

Filter by list of users. The user property indicates which user initiated the action being audited.

includeDiscarded
boolean

Determines whether discarded audits will be included in the results.

  • true - Return only discarded audits in the response.
  • false - Do not include any discarded audits in the response.
  • missing - Discarded status is ignored; both discarded and non-discarded audits are returned.
equipment
Array of strings <= 100 items
Example: equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398

Filter by list of equipment identifiers.

object
Array of strings <= 100 items
Example: object=06d77c63-6357-467a-a306-5e1ab3eb3aa7

Filter by list of object identifiers.

space
Array of strings <= 100 items
Example: space=214f52d1-0c56-4a29-a690-abe5656d1647

Filter by list of space identifiers.

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/audits?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp&classLevel=auditClassesEnumSet.userActionAuditClass&actionType=auditActionTypeEnumSet.writeAuditActionType&user=metasysuser&includeDiscarded=false&equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398&object=06d77c63-6357-467a-a306-5e1ab3eb3aa7&space=214f52d1-0c56-4a29-a690-abe5656d1647&page=1&pageSize=100&sort=creationTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

Gets the first 10 audits.

{
  • "total": 400,
  • "next": "https://{hostname}/api/v4/audits?page=2&pageSize=10&sort=-creationtime",
  • "previous": null,
  • "items": [
    ],
  • "effectivePermissions": [
    ],
  • "self": "https://{hostname}/api/v4/audits?page=1&pageSize=10&sort=-creationtime"
}

Get an audit

Retrieves the specific audit.

Authorizations:
Bearer-Authentication
path Parameters
auditId
required
string
Example: 4990ee27-7a0a-4b2b-9b27-279e3f1a060c

The identifier of the audit.

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/audits/4990ee27-7a0a-4b2b-9b27-279e3f1a060c \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

An audit for an analog value object.

{
  • "id": "6c6ae3dd-c514-423d-bd22-0b48678c5384",
  • "creationTime": "2021-12-10T21:05:53Z",
  • "actionType": "auditActionTypeEnumSet.commandAuditActionType",
  • "activityManagementStatus": "pending",
  • "status": "statusEnumSet.ok",
  • "spaces": [ ],
  • "equipment": [ ],
  • "preData": {
    },
  • "postData": null,
  • "parameters": [
    ],
  • "errorString": null,
  • "user": null,
  • "signature": null,
  • "objectUrl": "https://{hostname}/api/v4/objects/283fd3ad-ab1c-5849-8bdb-d635c5c274d9",
  • "self": "https://{hostname}/api/v4/audits/6c6ae3dd-c514-423d-bd22-0b48678c5384",
  • "itemReference": "{hostname}:{deviceHostname}/AV1",
  • "objectName": "Interlock1/AV1",
  • "classLevel": "auditClassesEnumSet.applicationAuditClass",
  • "originApplication": "auditOriginAppEnumSet.interlockAuditOriginApp",
  • "description": "commandIdEnumSet.adjustCommand"
}

Edit an audit

Allows for discarding an audit.

Authorizations:
Bearer-Authentication
path Parameters
auditId
required
string
Example: 4990ee27-7a0a-4b2b-9b27-279e3f1a060c

The identifier of the audit.

Request Body schema: application/json
activityManagementStatus
required
string
Value: "discarded"

The new activity management status of the audit.

The only accepted value of this property is discarded because it is the only valid activity management state transition for an audit. Once an audit is discarded, it cannot be changed to any other state.

annotationText
string or null

The annotation to associate with the change of audit state.

Responses

Request samples

Content type
application/json
{
  • "activityManagementStatus": "discarded"
}

Get audit annotations

Retrieves the collection of annotations available for the specified audit.

Authorizations:
Bearer-Authentication
path Parameters
auditId
required
string
Example: 4990ee27-7a0a-4b2b-9b27-279e3f1a060c

The identifier of the audit.

query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/audits/4990ee27-7a0a-4b2b-9b27-279e3f1a060c/annotations?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&page=1&pageSize=100&sort=creationTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
{}

Add audit annotation

Adds an annotation to an audit.

Authorizations:
Bearer-Authentication
path Parameters
auditId
required
string
Example: 4990ee27-7a0a-4b2b-9b27-279e3f1a060c

The identifier of the audit.

Request Body schema: application/json
text
required
string [ 1 .. 255 ] characters \S

The text of the annotation to create. This must not be null, empty, nor only whitespace. Additionally, any surrounding whitespace will be trimmed.

Responses

Request samples

Content type
application/json
{
  • "text": "Looks okay."
}

List audit users

Retrieves a list of unique usernames from all users present in a currently stored audit. The provided usernames may or may not reflect known users of the current system, but were known when the system recorded an audit for them.

Authorizations:
Bearer-Authentication

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/audits/users \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
{}

authentication

Operations to get and refresh an access token.

Request access token

Use this to request an access token that can be used for authentication on other API calls.

Request Body schema: application/json

Used to supply credentials for login.

username
string

The user name of an account. This can either be a local Metasys account, or an Active Directory account that has been granted access to Metasys. When using an Active Directory account, the value should be in the format {name}@{domain} (for example, jane-doe@mycorp.com).

Note: Only accounts with an Access Type of API can be used to request a token from the REST API.

password
string

The corresponding password of a Metasys account.

Responses

Request samples

Content type
application/json
Example
{
  • "username": "jane-doe",
  • "password": "strongPassword"
}

Response samples

Content type
application/vnd.metasysapi.v4+json

The result includes the access token needed to make requests. (The token in this example has been truncated.)

{
  • "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1...",
  • "expires": "2021-04-22T00:12:18Z"
}

Refresh a token

Use this operation to request a new token before the previous one expires. Note: If the expiration time of the access token is greater than 60 minutes from issue, disregard and refresh before 60 minutes to prevent session expiration. The next version of the API will provide the correct expiration time.

Authorizations:
Bearer-Authentication

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/refreshToken \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

The result includes the access token needed to make requests. (The token in this example has been truncated.)

{
  • "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1...",
  • "expires": "2021-04-22T00:12:18Z"
}

equipment

This section describes the operations you can perform on equipment. Equipment is a broad term for anything that makes a building run, including boilers, chillers, air handling units, lights, meters, and security systems. Use equipment operations to get equipment instances and to list equipment points. Apply filters, sorting, and paging to further refine the results.

Get equipment hosted by a network device

Retrieves the collection of equipment instances hosted by the specified network device or its children. A network device is considered to host an equipment if the equipment defines points that map to an attribute of any object contained on the network device.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "type" "-type"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/equipment?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A page of equipment instances.

{}

Get equipment instances

Retrieves a collection of equipment instances.

Authorizations:
Bearer-Authentication
query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "type" "-type"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/equipment?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A page of equipment instances.

{}

Get a single equipment instance

Retrieves the specified equipment instance.

Authorizations:
Bearer-Authentication
path Parameters
equipmentId
required
string
Example: b78fa672-3ec9-4794-bd00-7aeafeb9cde0

The identifier of the equipment instance.

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A single equipment instance.

{}

Get equipment served by an equipment instance

Retrieves the equipment served by the specified equipment instance.

Authorizations:
Bearer-Authentication
path Parameters
equipmentId
required
string
Example: b78fa672-3ec9-4794-bd00-7aeafeb9cde0

The identifier of the equipment instance.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "type" "-type"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/equipment?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A page of equipment instances.

{}

Get equipment that serve an equipment instance

Retrieves the collection of equipment that serve the specified equipment instance.

Authorizations:
Bearer-Authentication
path Parameters
equipmentId
required
string
Example: 04d68394-3415-4813-b5ec-43d840deee38

The identifier of the equipment instance.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "type" "-type"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/equipment/04d68394-3415-4813-b5ec-43d840deee38/upstreamEquipment?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A page of equipment instances.

{}

List equipment points

Retrieves the collection of points that are defined by the specified equipment instance. Each point contains a mapping to an attribute on an object.

Authorizations:
Bearer-Authentication
path Parameters
equipmentId
required
string
Example: b78fa672-3ec9-4794-bd00-7aeafeb9cde0

The identifier of the equipment instance.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "shortName"
Enum: "category" "-category" "equipmentName" "-equipmentName" "isDisplayData" "-isDisplayData" "shortName" "-shortName"
Example: sort=shortName

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/points?page=1&pageSize=100&sort=shortName' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A page of equipment points

{}

Get equipment serving a space

Retrieves the collection of equipment that serve the specified space.

Authorizations:
Bearer-Authentication
path Parameters
spaceId
required
string
Example: bf254f63-2cbb-4195-8c53-a1d6fcbe54f6

The identifier of a space.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "type" "-type"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6/equipment?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A page of equipment instances.

{}

network-devices

This section describes the operations you can perform on network devices. Network devices are physical devices such as coordinators and routers that are required for communication between hardware on a computer network. Use network device operations to get, list, and delete network devices. Apply filters, sorting, and paging to further refine the results.

List network devices

Retrieves a collection of network devices.

Authorizations:
Bearer-Authentication
query Parameters
objectType
string
Example: objectType=bacnetIntegrationClass
metasysType: enum
metasysEnum: objectTypeEnumSet

The type of network device to return.

The objectType query parameter cannot be used in conjunction with the classification query parameter.

The acceptable values for this parameter come from the objectTypeEnumSet enumeration. Only the long name of the object type (for example, objectTypeEnumSet.bacnetIntegrationClass instead of bacnetIntegrationClass) is accepted. Find the definition of objectTypeEnumSet at the relative URL of /schemas/enums/objectTypeEnumSet.

See also:

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "categoryId" "-categoryId" "firmwareVersion" "-firmwareVersion" "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

classification
Array of strings
Items Enum: "device" "integration" "server" "controller"
Examples:
  • classification=device&classification=server&classification=controller - Only devices (excludes integrations)
  • classification=device - Only supervisory engines
  • classification=server&classification=device - Servers and supervisory engines

The classification to filter devices on. One or more values are supported.

The classification query parameter cannot be used in conjunction with the objectType query parameter.

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/networkDevices?objectType=bacnetIntegrationClass&page=1&pageSize=100&sort=name&classification=device&classification=server&classification=controller' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A page of network devices.

{}

Get a single network device

Retrieves the specified network device.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A single network device.

{}

Deletes a network device

Deletes an engine or a server which is a child device of the site director. Cannot be used to delete controllers, integrations, or the site director.

Note: The device must be offline for the operation to succeed.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

Responses

Request samples 

curl --request DELETE \
  --url https:///%7Bhostname%7D/api/v4/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

List network device children

Retrieves the collection of network devices that are children of the specified network device.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "categoryId" "-categoryId" "firmwareVersion" "-firmwareVersion" "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/networkDevices?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A page of network devices.

{}

List network devices hosting an equipment instance

Retrieves the collection of network devices that host the specified equipment instance, along with the parents of those network devices. A network device hosts an equipment when the equipment defines points that map to an attribute of any object contained on the network device.

Authorizations:
Bearer-Authentication
path Parameters
equipmentId
required
string
Example: b78fa672-3ec9-4794-bd00-7aeafeb9cde0

The identifier of the equipment instance.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "categoryId" "-categoryId" "firmwareVersion" "-firmwareVersion" "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/networkDevices?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A page of network devices.

{}

List network devices serving a space

Retrieves the collection of network devices that serve the specified space. A space serves a network device when any equipment instance serving the space defines points that map to an attribute of any object contained on the network device.

Authorizations:
Bearer-Authentication
path Parameters
spaceId
required
string
Example: bf254f63-2cbb-4195-8c53-a1d6fcbe54f6

The identifier of a space.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "categoryId" "-categoryId" "firmwareVersion" "-firmwareVersion" "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6/networkDevices?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A page of network devices.

{}

objects

This section describes the operations you can perform on objects. Objects are self-contained functional items in the Metasys system, for a full definition refer to the Metasys System Glossary. Use objects operations to list, create, edit, and delete objects. Apply filters, sorting, and paging to further refine the results. Some operations accept subscriptions, see Change of Value Subscriptions.

Change of Value Subscriptions

Subscribe for change of value (COV) events to receive updates when attribute values change. Currently, subscriptions are available for Get attribute value operations (individual and batch).

Subscribing

To subscribe for COV events, complete the following steps:

  1. Open a stream with the Get a stream operation. Take note of the stream ID.
  2. Use one of the following operations and include a METASYS-SUBSCRIBE header with the stream ID:

Note: Any filters added to the original GET operation also apply to the event subscription.

Unsubscribing

To unsubscribe from a COV event, complete the following steps:

  1. Get the METASYS-SUBSCRIPTION-LOCATION from the subscribe operation response.
  2. Issue a Delete objects subscription request to METASYS-SUBSCRIPTION-LOCATION.

See also:

Events

There are three event types sent by the COV subscription: heartbeat, update, and notification.

  • object.values.heartbeat - A heartbeat event is sent to show that the subscription is still alive. A heartbeat is a JSON string with the current UTC date time in ISO 8601 format and is sent every 30 seconds.

    Heartbeat Payload Example 
    "2021-09-16T19:58:28.5902588Z"

  • object.values.update - An update event is sent when an attribute value changes and the value is included in the event. Here is an example data payload for this type of event. This payload is the same as the payload returned by Get attribute value, except for the inclusion of id and itemReference in the item object. The overall schema for this payload is identical to the Get an object schema (except this payload has no schema or effectivePermissions properties).

    Update Payload Example 
    {
  "item": {
    "presentValue": 76.5,
    "id": "960534d2-7df5-5ed8-884c-164e7a2f280a",
    "itemReference": "{hostname}:{deviceHostname}/AV1"
  },
  "condition": {
    "presentValue": {
      "reliability": "reliabilityEnumSet.reliable",
      "priority": "writePriorityEnumSet.priorityDefault"
    }
  }
}

  • object.values.notification - A notification event is sent when a value has changed but the value is not included in the payload. This happens for some values that are not simple scalar values. You can use this event as a trigger to reread the attribute.

    In the following example, even though the payload does not include the current value, you know which object this is for (based on id and itemReference), and you know it is the overrideExpirationTime attribute based on the attribute property.

    Notification Payload Example 
    {
  "item": {
    "id": "960534d2-7df5-5ed8-884c-164e7a2f280a",
    "itemReference": "{hostname}:{deviceHostname}/AV1"
  },
  "condition": {
    "overrideExpirationTime": {
      "reliability": "reliabilityEnumSet.reliable",
      "priority": "writePriorityEnumSet.priorityNone"
    }
  },
  "attribute": "attributeEnumSet.overrideExpirationTime"
}

List objects

Returns the root object of the tree and, optionally, its children. The root object is the site object. The default response is a tree representation. Set flatten=true to flatten the tree into a list representation. The number of levels returned depends on the value of the depth parameter. To get just the root of the tree use a depth of 0. Values of depth greater than 1 are not allowed on this endpoint.

Authorizations:
Bearer-Authentication
query Parameters
depth
integer [ 0 .. 1 ]
Default: 1
Example: depth=1

The depth of the tree to return. The provided value is ignored if pathTo, objectType, or classification are specified.

flatten
boolean
Default: false

A value of true indicates the response payload should be a flat list. A value of false (the default) indicates the response payload should be a tree with child objects nested under their parent object. While this parameter influences the shape of the response, it does not affect the content. The same set of objects is returned no matter the value of this parameter.

includeExtensions
boolean
Default: false

A value of true indicates that extension objects should be included in the result. A value of false (the default) indicates that they should not be included.

This parameter is ignored if pathTo is specified.

pathTo
string
Example: pathTo=a5885077-9dba-5923-a6d8-ae4aabdc6f0a

This parameter causes the response to contain the object specified by this parameter, the root object, and the objects in between.

If this parameter is specified, then depth and includeExtensions are ignored.

includeEffectivePermissions
boolean
Default: false
Example: includeEffectivePermissions=true

Include the effectivePermissions property in the response payload. This property describes which objects in the response the current user can view, modify or delete.

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/objects?depth=1&flatten=false&includeExtensions=false&pathTo=a5885077-9dba-5923-a6d8-ae4aabdc6f0a&includeEffectivePermissions=true' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example

The objects are returned in a tree structure. Child objects are nested under their parents.

{}

Create object

Creates a new object. Several things are needed to successfully create an object. You must know

  • the type of object you want to create
  • if that object type is supported in the location you want to create it
  • what properties can be set on that type of object when creating it
  • what properties are required to be set.

Find the complete list of object types with the operation GET /schemas/enums/objectTypeEnumSet. To determine the specific set of objects that can be created in a location use List supported child types (GET /objects/{objectId}/supportedChildTypes). To discover what object properties can be set and which are required when creating an object use Get a schema for an object type (GET /schemas/objectTypes/{objectType})

See also:

Authorizations:
Bearer-Authentication
Request Body schema: application/json
parentId
required
string

The ID of the parent object. The new object will be created under this object.

localUniqueIdentifier
required
string <= 32 characters ^[^\x00-\x1F\x7F\x22#'*,.\/:<>?@\[\\\]|]+$

A string that is locally unique within the context of the parent object for identifying the new object. This string will be the last component of the itemReference of the newly created object. For example, assume you have a folder with an itemReference of adx:oas/Programming. Then you create an AV with a local unique identifier of ZN-3-T within that folder. The newly created object will have an itemReference of adx:oas/Programming.ZN-3-T.

The value must not contain any control characters or any of the following characters: " # ' * , . / : < > ? @ [ \ ] |

objectType
required
string
metasysType: enum
metasysEnum: objectTypeEnumSet

The type of object to create.

The values for this property come from the objectTypeEnumSet enumeration. Find the definition of objectTypeEnumSet at the relative URL of /schemas/enums/objectTypeEnumSet.

See also:

item
object

The item object is where you set the properties of the newly created object. Which properties can be set and their data types can be discovered by using the Get schema for object type operation.

This property may or may not be required depending on the object you are creating. Some objects have defaults for all properties and require nothing to be set when creating them. Others have required properties that must be set at creation time.

Responses

Request samples

Content type
application/json
Example

This request body creates a new object of type objectTypeEnumSet.avClass under a folder with an identifier of 82b6f2d5-6fed-5074-b611-94dd40028312 with a locally unique identifier of ZN-3-SETPT. The properties on the new object are name, description, objectCategory, minPresValue and maxPresValue.

{
  • "parentId": "82b6f2d5-6fed-5074-b611-94dd40028312",
  • "localUniqueIdentifier": "ZN-3-SETPT",
  • "objectType": "objectTypeEnumSet.avClass",
  • "item": {
    }
}

List child objects

Returns the specified object and optionally one or more levels of the tree under the object. The default response is a tree representation. Set flatten=true to flatten the tree into a list representation.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 767d8af0-163f-552c-ba37-a884466075f9

Specifies the root of the subtree to return for this request. The objectId is the identifier of the object to retrieve (optionally along with 1 or more levels of descendants).

query Parameters
depth
integer >= -1
Default: 1
Example: depth=1

The depth of the tree to return. For typical usage, a value or 1 or 2 is recommended. Use -1 for maximum depth.

The provided value is ignored if pathTo, objectType, or classification are specified.

flatten
boolean
Default: false

A value of true indicates the response payload should be a flat list. A value of false (the default) indicates the response payload should be a tree with child objects nested under their parent object. While this parameter influences the shape of the response, it does not affect the content. The same set of objects is returned no matter the value of this parameter.

includeExtensions
boolean
Default: false

A value of true indicates that extension objects should be included in the result. A value of false (the default) indicates that they should not be included.

This parameter is ignored if pathTo is specified.

pathTo
string
Example: pathTo=a5885077-9dba-5923-a6d8-ae4aabdc6f0a

This parameter filters the response down to just containing the object specified by this parameter, the object specified by objectId in the path, and the objects in between.

If this parameter is specified, then depth, includeExtensions, objectType and classification are ignored.

objectType
string
Examples:
  • objectType=objectTypeEnumSet.avClass - Analog Value Object Type
  • objectType=objectTypeEnumSet.bvClass - Binary Value Object Type
  • objectType=objectTypeEnumSet.mvClass - Multiple Value Object Type
metasysType: enum
metasysEnum: objectTypeEnumSet

Type of objects to include in the response. This parameter may be repeated. To search for all AV and AI objects one would specify /objects?type=objectTypeEnumSet.avClass&type=objectTypeEnumSet.aiClass.

The use of this parameter overrides depth to -1 and includeExtensions to true.

It is an error to specify this parameter if classification is specified.

The response will include the specified object, the objects that match the objectType for the given depth and any objects in between (like folders and devices).

The acceptable values for this parameter come from the objectTypeEnumSet enumeration. It is acceptable to use the short name of the object type (for example, avClass instead of objectTypeEnumSet.avClass) because the enumeration set is known from context. Find the definition of objectTypeEnumSet at the relative URL of /schemas/enums/objectTypeEnumSet.

See also:

classification
string
Enum: "object" "device" "integration" "controller" "point" "site" "navList" "extension" "folder" "reference" "server" "archive"
Examples:
  • classification=object - Any object not classified by one of the other classification values
  • classification=device - An object that represents a supervisory controller
  • classification=controller - An object that represents a field controller

Filter objects to those with the specific classification. The use of this parameter overrides depth to -1 and includeExtensions to true. It is an error to specify this parameter if objectType is specified.

includeEffectivePermissions
boolean
Default: false
Example: includeEffectivePermissions=true

Include the effectivePermissions property in the response payload. This property describes which objects in the response the current user can view, modify or delete.

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/objects/767d8af0-163f-552c-ba37-a884466075f9/objects?depth=1&flatten=false&includeExtensions=false&pathTo=a5885077-9dba-5923-a6d8-ae4aabdc6f0a&objectType=objectTypeEnumSet.avClass&classification=object&includeEffectivePermissions=true' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example

The objects are returned in a tree structure. Child objects are nested under their parents.

{}

Get object id

Finds the object identifier (the id property of an object) for the object with the specified fully qualified reference (fqr).

Authorizations:
Bearer-Authentication
query Parameters
fqr
required
string
Examples:
  • fqr=adx:adx - An example of a site director fqr
  • fqr=adx:nae23/Programming.AV1 - An example an analog value object fqr
format: fully-qualified-reference

The fully qualified reference of an object.

Fully qualified references use characters that must be escaped when used as query parameters. Most HTTP libraries do this for you automatically. However, if you are using curl or PowerShell where you specify the full URL yourself you may need to be aware. For example, here is the URL to use with curl for a reference of oas:oas/Programming.AV3: https://{hostname}/api/v4/objectIdentifiers?fqr=oas%3Aoas%2FProgramming.AV3

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/objectIdentifiers?fqr=adx%3Aadx' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
"32cfddc0-411f-5b9e-9a6d-442cb62fecbb"

Get an object

Objects support one or more views. By default, this operation gets the default view of an object. For many objects this is the Focus View (identifier viewNameEnumSet.focusView). To see the list of views an object supports see List Views (/objects/{objectId}/views). To get a different view of an object specify a value for the viewId parameter.

Licensing Restrictions

Requires Monitoring and Commanding API license.

See also:

  • List Views for information on retrieving the view collection of an object.
Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

query Parameters
viewId
string
Examples:
  • viewId=viewNameEnumSet.focusView - Focus View
  • viewId=viewNameEnumSet.diagnosticView - Diagnostic View
metasysEnum: viewNameEnumSet

The view to retrieve.

This parameter is optional and if it is not specified the default view for the object will be returned. For many objects this is the Focus view (focusView).

The acceptable values for this parameter come from the viewNameEnumSet enumeration. It is acceptable to use the short name of the view (for example, focusView instead of viewNameEnumSet.focusView) because the enumeration set is known from context. Find the definition of viewNameEnumSet at the relative URL of /schemas/enums/viewNameEnumSet.

See also:

includeSchema
boolean

Every object can have a unique schema. Set this parameter to true to include the schema for this object in the response payload.

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb?viewId=viewNameEnumSet.focusView&includeSchema=false' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example

This is an example of an AV object without a schema. Notice that the presentValue is 105 but the maxPresValue is set to 100. This results in the presentValue attribute going unreliable. This can be seen in the condition object where presentValue has a reliability value of reliabilityEnumSet.unreliableHigh. We can also see that the current priority for presentValue is set to writePriorityEnumSet.priorityCriticalEquipment.

{}

Edit an object

This operation modifies one or more attributes of an object. Note: attributes must be updated in whole. For example, if you wish to modify an attribute of metasysType struct which is modelled as a JSON object you must include all elements of the struct. It is undefined what might happen if you do not. The write could fail, the non-mentioned members may get their default value or something else. This applies to any attribute that has a JSON type of array or object. The entire attribute value must be written even if you only wish to change one part of the value.

The request body contains an item property which contains one or more properties and their new values.

The attributes of an object (and their schemas) can be discovered by looking at the different views of an object or by requesting all of the attributes.

Licensing Restrictions

Requires Monitoring and Commanding API license.

See also:

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

Request Body schema: application/json
item
object

The attributes to update.

Responses

Request samples

Content type
application/json
Example
{
  • "item": {
    }
}

Delete an object

Deletes the specified object.

Not all objects can be deleted (not even by an administrator). Examine the effectivePermissions of an object to determine if it can be deleted by the current user.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

Responses

Request samples 

curl --request DELETE \
  --url https:///%7Bhostname%7D/api/v4/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

List the views of an object

Objects support one or more views. Each view of an object contains a logical grouping of the object's attributes. This operation lists the collection of views that an object has.

Each entry in the response contains the id of a view, and also the absolute URL used to request that view. Use Get an object (/objects/{objectId}) to request a specific view by specifying the desired id for the viewId query parameter.

See also:

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

query Parameters
includeSchema
boolean

Set this parameter to true to include a schema in the response.

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/views?includeSchema=false' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example

List attributes of an object

Returns an object payload with a JSON schema that contains all of the properties of the object. Each property entry contains only a partial schema for that property. (To discover the full schema of an attribute use /objects/{objectId}?includeSchema=true or /objects/{objectId}/attributes/{attrId}?includeSchema=true

The item section of the payload will contain at most one attribute, the defaultAttribute. The item section will be completely missing if the object does not have a default attribute.

There will be no views or condition sections like a typical object payload.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/attributes \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example
{
  • "item": {
    },
  • "schema": {
    }
}

Get attribute value

Returns an object payload containing the specified attribute. Invoke this operation with a valid METASYS-SUBSCRIBE header to create a subscription for changes to that attribute, rather than returning a value. The current value and any updates to the attribute are instead sent over the specified stream.

Licensing Restrictions

Requires Monitoring and Commanding API license.

See also:

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

attributeId
required
string
Examples:
  • presentValue - The Present Value
  • itemReference - The Fully Qualified reference
metasysEnum: attributeEnumSet

The attribute to read.

The acceptable values for this parameter come from the attributeEnumSet enumeration. Only the short name of the attribute (for example, presentValue instead of attributeEnumSet.presentValue) is accepted. Find the definition of attributeEnumSet at the relative URL of /schemas/enums/attributeEnumSet.

See also:

query Parameters
includeSchema
boolean

Set this parameter to true to include a schema in the response.

header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/attributes/presentValue?includeSchema=false' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example
{
  • "item": {
    },
  • "condition": {
    },
  • "schema": {
    }
}

List commands

Returns a payload that lists all of the commands that an object supports. Each command entry has an invokeUrl property, which is the URL needed to invoke the command. In addition, each command entry has a commandBodySchema property, which is a JSON schema that describes the acceptable payload for the command. Commands are invoked using the HTTP method PUT along with the invokeUrl and acceptable body.

Note: Some objects, such as multi-state values (MV) and binary values (BV), may list a command that has a commandSet property and a property named aggregateCommand with a value of true instead of invokeUrl. This commandSet lists one or more commands. This entry is not a true command but rather provides a hint to graphical user interfaces on how they may want to group the commands of the commandSet under one command name. For example, an MV object lists a command with the identifier commandIdEnumSet.adjustCommand. This is not an actual command on an MV. Instead the actual commands that could be used to present this command in a UI are listed in the commandSet and they have identifiers like commandIdEnumSet.multistate0Command. The Metasys User Interface displays all of these commands as a single adjust command with the titles of the individual commands as the parameter to send.

Licensing Restrictions

Requires Monitoring and Commanding API license.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/commands \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example
{
  • "self": "https://{hostname}/api/v4/objects/960534d2-7df5-5ed8-884c-164e7a2f280a/commands",
  • "items": [
    ],
  • "effectivePermissions": {
    }
}

Send command

Used to send a command to an object. The payloads of commands differ, but they share some similarities. To learn the specifics of the commands of an object use List commands.

Licensing Restrictions

Requires Monitoring and Commanding API license.

See also:

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

commandId
required
string
Example: adjustCommand
metasysEnum: commandIdEnumSet

The identifier of the command to send.

The acceptable values for this parameter come from the commandIdEnumSet enumeration. It is acceptable to use the short name of the command identifier (for example, adjustCommand instead of commandIdEnumSet.adjustCommand) because the enumeration set is known from context. Find the definition of commandIdEnumSet at the relative URL of /schemas/enums/commandIdEnumSet.

See also:

Request Body schema: application/json

The body of a command is defined by the commandBodySchema. The commandBodySchema is a property of every command returned by the List commands operation.

priority
string (write-priority-enum-set)
Enum: "writePriorityEnumSet.priorityNone" "writePriorityEnumSet.priorityManualEmergency" "writePriorityEnumSet.priorityFireApplications" "writePriorityEnumSet.priority3" "writePriorityEnumSet.priority4" "writePriorityEnumSet.priorityCriticalEquipment" "writePriorityEnumSet.priorityMinimumOnOff" "writePriorityEnumSet.priorityHeavyEquipDelay" "writePriorityEnumSet.priorityOperatorOverride" "writePriorityEnumSet.priority9" "writePriorityEnumSet.priority10" "writePriorityEnumSet.priorityDemandLimiting" "writePriorityEnumSet.priority12" "writePriorityEnumSet.priorityLoadRolling" "writePriorityEnumSet.priority14" "writePriorityEnumSet.prioritySchedulingOst" "writePriorityEnumSet.priorityDefault"
metasysType: enum
metasysEnum: writePriorityEnumSet
parameters
Array of any >= 0 items
annotation
string

Responses

Request samples

Content type
application/json
Example

This body is used with the adjust command of an Analog Value (AV). It sends the value 72.5 along with an annotation about why the command was invoked. The URL for this command is /objects/{objectId}/commands/adjustCommand

{
  • "parameters": [
    ],
  • "annotation": "Increase the set point to make it warmer."
}

Response samples

Content type
application/vnd.metasysapi.v4+json
"Success"

List supported child types

Many objects support nested objects. The obvious examples of this are folder objects and device objects. Less obvious examples include objects like analog value and multi-state value objects (which can have child objects like integrations). This operation lists the types of objects that can be created under an object.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/supportedChildTypes \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example

The supported child types of a folder.

[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

List object equipment points

Retrieves all equipment points mapped to attributes of this object.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "shortName"
Enum: "category" "-category" "equipmentName" "-equipmentName" "isDisplayData" "-isDisplayData" "shortName" "-shortName"
Example: sort=shortName

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/points?page=1&pageSize=100&sort=shortName' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
{}

Batch operations

This operation is used to invoke multiple operations in a single HTTP request. Often a batch request is more efficient than sending each individual operation in its own HTTP request.

In this version of the API, the only objects related operation that can be used in a batch is Get attribute value.

If this operation is invoked with a valid METASYS-SUBSCRIBE header it will cause a subscription to be created for the attributes in the request and rather than returning any values, the current values and any updates to the attributes will be sent over the specified stream.

Licensing Restrictions

Requires Monitoring and Commanding API license.

See also:

Authorizations:
Bearer-Authentication
header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

Request Body schema: application/json
method
required
string
Value: "GET"

The HTTP method to use for each request. This property is restricted to GET for this version of the API since Get attribute value is the only operation supported in a batch.

required
Array of objects non-empty

A collection of entries that represent the operations to invoke.

Responses

Request samples

Content type
application/json

This example shows a request body that will read the presentValue and status from 3 different objects using sequential numbers as request identifiers.

This example shows the use of sequential numeric values used as request identifiers but any unique strings can be used.

{
  • "method": "GET",
  • "requests": [
    ]
}

Response samples

Content type
application/vnd.metasysapi.v4+json
Example

This example shows the response to a read multiple attributes request. Each operation response is uniquely identified by the corresponding identifier (id) from the request.

{
  • "responses": [
    ]
}

Delete object subscription

Delete a subscription to a resource in the objects domain.

Authorizations:
Bearer-Authentication
path Parameters
streamId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The stream identifier that contains the subscription. This is the unique identifier for the client's stream obtained via GET /stream.

subscriptionId
required
string
Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5

The identifier of the subscription to act upon. This is the unique identifier to the subscription for a specific resource or type of event. This value is found as the last parameter of a METASYS-SUBSCRIPTION-LOCATION header returned for the original subscription request.

Responses

Request samples 

curl --request DELETE \
  --url https:///%7Bhostname%7D/api/v4/objects/streams/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/subscriptions/626e5ac3-506d-4017-bb8f-973f1c54ddb5 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

schemas

A collection of JSON schemas for describing enumerations and object types.

Get enumeration

This operation retrieves the specified enumeration as a JSON schema. The path of this operation appears in several schemas of object payloads.

To get a list of all enumerations fetch the enumerationSetNamesEnumSet:

GET /schemas/enums/enumerationSetNamesEnumSet

See also:

Authorizations:
Bearer-Authentication
path Parameters
enumId
required
string
Examples:
  • writePriorityEnumSet - The write priority enumeration
  • displayPrecisionEnumSet - The display precision enumeration
  • enumerationSetNamesEnumSet - The set of all sets
metasysType: enum

The enumeration to retrieve.

The acceptable values for this parameter come from the enumerationSetNamesEnumSet enumeration. It is acceptable to use the short name of the value (for example, writePriorityEnumSet instead of enumerationSetNamesEnumSet.writePriorityEnumSet) because the enumeration set is known from context. Find the definition of enumerationSetNamesEnumSet at the relative URL of /schemas/enums/enumerationSetNamesEnumSet.

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/schemas/enums/writePriorityEnumSet \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example
{
  • "$schema": "http://json-schema.org/draft-07/schema#",
  • "title": "Write Priority",
  • "$id": "https://{hostname}/api/v4/schemas/enums/writePriorityEnumSet",
  • "setId": 1,
  • "oneOf": [
    ]
}

Get object type schema

This endpoint retrieves a schema for a specific objectType. The schema describes the properties that can be set when creating an object of the specific type.

Authorizations:
Bearer-Authentication
path Parameters
objectType
required
string
Examples:
  • objectTypeEnumSet.avClass - AV
  • objectTypeEnumSet.bvClass - BV
  • objectTypeEnumSet.mvClass - MV
metasysEnum: objectTypeEnumSet

The type of object

The acceptable values for this parameter come from the objectTypeEnumSet enumeration. It is acceptable to use the short name of the object type (for example, avClass instead of objectTypeEnumSet.avClass) because the enumeration set is known from context. Find the definition of objectTypeEnumSet at the relative URL of /schemas/enums/objectTypeEnumSet.

See also:

query Parameters
parentId
required
string
Example: parentId=2993aed9-5765-5641-889c-40ec968c8a82

The object under which this new object will be created.

extendedProperty
string
Examples:
  • extendedProperty=attributeEnumSet.presentValue - Present Value
  • extendedProperty=attributeEnumSet.reliability - Reliability
metasysEnum: attributeEnumSet

The attribute to extend.

Indicates which attribute of the parent object the extension should be linked to. Used only for extension objects (like alarm extensions).

The acceptable values for this parameter come from the attributeEnumSet enumeration. It is acceptable to use the short name of the attribute (for example, presentValue instead of attributeEnumSet.presentValue) because the enumeration set is known from context. Find the definition of attributeEnumSet at the relative URL of /schemas/enums/attributeEnumSet.

See also:

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/schemas/objectTypes/objectTypeEnumSet.avClass?parentId=2993aed9-5765-5641-889c-40ec968c8a82&extendedProperty=attributeEnumSet.presentValue' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example

This schema describes the properties that can be configured when creating an object of the type avClass.

{
  • "schema": {
    },
  • "views": [
    ]
}

spaces

Operations on space-related resources.

Get spaces served by a network device

Retrieves the collection of spaces served by the specified network device. A space is served by a network device when any equipment instance serving the space defines points that map to an attribute of any object contained on the network device.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/spaces?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A page of spaces.

{}

Get spaces served by an equipment instance

Retrieves the collection of spaces served by the specified equipment instance.

Authorizations:
Bearer-Authentication
path Parameters
equipmentId
required
string
Example: b78fa672-3ec9-4794-bd00-7aeafeb9cde0

The identifier of the equipment instance.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/spaces?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A page of spaces.

{}

Get spaces

Retrieves a collection of spaces.

Authorizations:
Bearer-Authentication
query Parameters
type
string
Example: type=spaceTypesEnumSet.building
metasysType: enum
metasysEnum: spaceTypesEnumSet

Type of space to return.

The acceptable values for this parameter come from the spaceTypesEnumSet enumeration. Only the long name of the space type (for example, spaceTypesEnumSet.building instead of building) is accepted. Find the definition of spaceTypesEnumSet at the relative URL of /schemas/enums/spaceTypesEnumSet.

See also:

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/spaces?type=spaceTypesEnumSet.building&page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A page of spaces.

{}

Get a single space

Retrieves the specified space.

Authorizations:
Bearer-Authentication
path Parameters
spaceId
required
string
Example: bf254f63-2cbb-4195-8c53-a1d6fcbe54f6

The identifier of a space.

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A page of spaces.

{}

Get space children

Retrieves the collection of spaces that are located within the specified space.

Authorizations:
Bearer-Authentication
path Parameters
spaceId
required
string
Example: bf254f63-2cbb-4195-8c53-a1d6fcbe54f6

The identifier of a space.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6/spaces?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A page of spaces.

{}

streaming

Your Metasys system works continuously: sensors report current conditions, algorithms make adjustments, and alarms alert operators to potential issues. Streaming is how the Metasys API provides access to these events using the HTML standard server-sent events (SSE). For further information, refer to Mozilla developer guide. In this document, Streaming typically refers to the Metasys feature and stream refers to the concept of the HTTP connection and the flow of data.

Per the standard, a server-sent event usually contains three components, separated by newline, with the last component having a second newline to mark the end of the event.

id: <event id>\n
event: <event type>\n
data: <event data>\n\n
Line Prefix Explanation
id ordering id to enable the "pick up where you left off" reconnection
event message type
data message payload as a JSON string

Example:

id: b6d184ee-e137-44aa-b9b1-14bc704cd25d:1\n
event: hello\n
data: b6d184ee-e137-44aa-b9b1-14bc704cd25d\n\n

Getting Started

To get started, you first need a client. There are SSE clients available in many languages.

Begin by getting a stream. Only one stream is needed regardless of the number of subscriptions you later create. As explained in the documentation for getting a stream, the first event, hello, is a special event because the data field contains your stream ID.

Some operations support the METASYS-SUBSCRIBE header which transforms them from being a single request/response operations into a streaming subscription. The value of the header is the stream ID from the data field of the hello event described above. As an example, refer to the Get Activities operation for more details about this technique. This technique does not apply to every operation. See each operation's description to understand its Streaming capability.

Not all event data is currently exposed by Streaming. Future versions of the API will add further Streaming capabilities.

Streaming Connection Maintenance

There are a few behaviors to be aware of if you want your stream to work beyond the lifetime of the access token used to get your stream.

Keep Events Flowing After Initial Access Token Expiration

Recall that your access token has an expiration time. To keep the stream longer than the lifetime of that access token, be sure to refresh your token just as you would when using non-Streaming portions of the API. Not only will you get a fresh token to use, but internally, your stream expirations are updated to match the expiration time of the new token.

Reconnect and Using the Current Access Token in Reconnect Requests

The server-sent events standard has a provision for reconnecting a lost connection. Call the same get a stream operation but also add the Last-Event-Id header with the id of the last event received. Most clients handle this for you. Metasys continues to buffer events for at least thirty seconds after the connection failure is detected, so you can resume streams that experienced brief outages. If Metasys has cleaned up your buffer or cannot find that id in the recently sent buffer, you will get a 204 response per the SSE specification. Because your existing stream is not resumable, your Last-Event-Id is no longer valid. The recovery path is to start anew by calling get a stream without the Last-Event-Id and subscribe again to data of interest.

One critical aspect of reconnect is ensuring that the reconnect request is done with the current access token. As covered by get a stream, Streaming lets you specify the token in either the Authorization header or query string. This flexibility accommodates a variety of clients. For example, the web browser client, EventSource, does not provide access to request headers, so you have to use the query string.

For EventSource, this however poses an issue because the reconnect attempt will be done against the original URL which has a potentially outdated access token embedded in the query string. For that reason, if you want to use a JavaScript client, consider using the open source EventSource component. The Metasys User Interface (MUI) employs this library to workaround the limitation of the browser's EventSource . When using it, use the Authorization header instead. Keep the options object passed to the constructor so you can update the Authorization property when you refresh your access token.

Assuming:

  1. Your access token is in variable accessToken
  2. Variable streamingUrl is the URL for get a stream
const eventSourceOptions = {
  headers: {
    Authorization = `Bearer ${accessToken}`
  }
};

const eventSource = new $window.EventSourcePolyfill(streamingUrl, eventSourceOptions);

Before token expiration:

  1. Get a refreshed token. Behind the scenes this also refreshes you stream expirations.
  2. Modify eventSourceOptions with new token like example below
eventSourceOptions.headers.Authorization = `Bearer ${newToken}`;

Tips For Other Client Libraries

SSE clients exist in many languages. Inclusion in this section is not an endorsement; however, if you chose one of these clients, these tips may prove useful for ensuring the current token is used for reconnect.

C# - 3ventic EventSource

When using the 3ventic EventSource for C# you will need to use Reflection to update Uri which is a private field within the EventSource that contains the location to get a stream with the access token embedded in the query string.

public static void SetField(Object obj, String fieldName, object value)
{
    Type type = obj.GetType();
    FieldInfo field = type.GetField(
        fieldName,
        BindingFlags.NonPublic | BindingFlags.Instance
    );
    field.SetValue(obj, value);
}

// example usage
Reflector.SetField(eventSource, "Uri", uriWithCurrentToken);

C# - LaunchDarkly EventSource

When using the LaunchDarkly EventSource for C# you will not call the Reset method to attempt a reconnect. Instead, dispose of the EventSource and then create a new instance, passing the the LastEventId from the last message and the URL to get a stream with a current access token embedded as a query string parameter.

Streaming Events

The following are types of events sent by Streaming along with example data payloads for each:

  • hello - Indicates Streaming connection was successful.

    Example Data Payload 
    "b6d184ee-e137-44aa-b9b1-14bc704cd25d"

  • heartbeat - Indicates Streaming connection is alive.

    Example Data Payload 
    "2021-02-16T16:21:10.23Z"

Get a stream

Opens or reconnects a Server Sent Event stream which is a prerequisite for subscribing to any dynamic updates

Authorizations:
Bearer-AuthenticationAPI-Key-Authentication
header Parameters
Last-Event-Id
string
Example: b6d184ee-e137-44aa-b9b1-14bc704cd25d:5

Providing the ID of the last event received enables a briefly broken stream to be resumed

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/stream \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Last-Event-Id: b6d184ee-e137-44aa-b9b1-14bc704cd25d:5'

time series

Operations to retrieve time series data.

Time series data is located in two places: in buffers on devices and in an historical data repository (if your site has a repository).

The buffers typically have relatively recent samples while the repository may have samples as old as your site. Over time the samples in buffers are moved to the repository (if configured to do so).

The samples in buffers are associated with Metasys objects that currently exist on your site. The samples that reside within the repository are also usually associated with objects that exist on your site, but it maintains samples even if the associated objects are deleted. Therefore there may be samples in the repository that are no longer associated with any object on your site.

The time series operations that have paths that begin with /objects only work with objects that exist on the site. When you fetch samples with these operations they will read data from both device buffers and the repository as needed.

The time series operations that have paths that begin with /timeSeries retrieve any historical data that is in the repository regardless of whether the associated object still exists or not. They never retrieve any samples from device buffers.

Get object attributes with samples

Retrieves a collection of attributes under the specified object for which samples are available.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/trendedAttributes \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Get samples for an object attribute

Retrieves a collection of samples for the specified object attribute during a particular date and time range.

Note: The parent endpoint /objects/{objectId}/trendedAttributes/{attributeId} is not currently supported.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

attributeId
required
string
Example: presentValue
metasysType: enum
metasysEnum: attributeEnumSet

The identifier of the attribute.

The acceptable values for this parameter come from the attributeEnumSet enumeration. It is acceptable to use the short name of the attribute (for example, presentValue instead of attributeEnumSet.presentValue) because the enumeration set is known from context. Find the definition of attributeEnumSet at the relative URL of /schemas/enums/attributeEnumSet.

See also:

query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 1000
Example: pageSize=1000

The maximum number of items to return in the response.

sort
string
Default: "timestamp"
Enum: "timestamp" "-timestamp"
Example: sort=timestamp

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/trendedAttributes/presentValue/samples?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&page=1&pageSize=1000&sort=timestamp' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example

Single page get samples response containing only analog values.

{}

Get network device attributes with samples

Retrieves a collection of attributes under the specified network device for which samples are available.

Authorizations:
Bearer-Authentication
path Parameters
id
required
string
Example: 6b092d2e-c795-4e90-95e8-5acafc74f19d

The identifier of the network device.

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/networkDevices/6b092d2e-c795-4e90-95e8-5acafc74f19d/trendedAttributes \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Get samples for a network device attribute

Retrieves a collection of samples for the specified network device attribute during a particular date and time range.

Note: The parent endpoint /networkDevices/{id}/trendedAttributes/{attributeId} is not currently supported.

Authorizations:
Bearer-Authentication
path Parameters
id
required
string
Example: c550095d-ee4c-4314-b415-b0577e383ee9

The identifier of the network device.

attributeId
required
string
Example: presentValue
metasysType: enum
metasysEnum: attributeEnumSet

The identifier of the attribute.

The acceptable values for this parameter come from the attributeEnumSet enumeration. It is acceptable to use the short name of the attribute (for example, presentValue instead of attributeEnumSet.presentValue) because the enumeration set is known from context. Find the definition of attributeEnumSet at the relative URL of /schemas/enums/attributeEnumSet.

See also:

query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 1000
Example: pageSize=1000

The maximum number of items to return in the response.

sort
string
Default: "timestamp"
Enum: "timestamp" "-timestamp"
Example: sort=timestamp

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/networkDevices/c550095d-ee4c-4314-b415-b0577e383ee9/trendedAttributes/presentValue/samples?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&page=1&pageSize=1000&sort=timestamp' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example

Single page get samples response containing only analog values.

{}