# Johnson Controls Activities API
**Canonical:** https://apis.io/apis/johnson-controls/johnson-controls-activities-api/
**Provider:** Johnson Controls — https://apis.io/providers/johnson-controls/
**Base URL:** https://{hostname}/api/v6
**Documentation:** https://jci-metasys.github.io/api-landing/
Johnson Controls Activities API is one of 11 APIs that [Johnson Controls](https://apis.io/providers/johnson-controls/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification. This API exposes 6 JSON Schema definitions. Tagged areas include Activities. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, a getting-started guide, a changelog, and 6 JSON Schemas.
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. Obtain a stream ID using the workflow outlined in the [Streaming](#section/Streaming) section. 2. Use [Get Activities](#operation/getActivities) 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](#operation/deleteActivitiesSubscription) request to `METASYS-SUBSCRIPTION-LOCATION`. **See also:** - [Get a stream](#operation/getStream) - [Streaming](#tag/streaming) #### 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 120 seconds. Heartbeat Payload Example
```json { "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
```json { "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://metasys-server.example.com/api/v6/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f" } ], "equipment": [ { "id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f", "itemReference": "{hostname}:{deviceHostname}/equipment.Engine1", "equipmentName": "Engine1", "shortName": null, "equipmentUrl": "https://metasys-server.example.com/api/v6/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f" } ], "objectUrl": "https://metasys-server.example.com/api/v6/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://metasys-server.example.com/api/v6/objects/bfcc3fce-a182-53c0-a529-268f8184496b" } }, "isAckRequired": true, "acknowledgedTime": "2021-02-16T20:31:02Z", "type": "alarmValueEnumSet.avHiAlarm", "priority": 70, "category": "objectCategoryEnumSet.generalCategory", "annotationsUrl": "https://metasys-server.example.com/api/v6/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations", "self": "https://metasys-server.example.com/api/v6/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
```json { "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://metasys-server.example.com/api/v6/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f" } ], "equipment": [ { "id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f", "itemReference": "{hostname}:{deviceHostname}/equipment.Engine1", "equipmentName": "Engine1", "shortName": null, "equipmentUrl": "https://metasys-server.example.com/api/v6/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f" } ], "objectUrl": "https://metasys-server.example.com/api/v6/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://metasys-server.example.com/api/v6/objects/bfcc3fce-a182-53c0-a529-268f8184496b" } }, "isAckRequired": true, "acknowledgedTime": "2021-02-16T20:31:02Z", "type": "alarmValueEnumSet.avHiAlarm", "priority": 70, "category": "objectCategoryEnumSet.generalCategory", "annotationsUrl": "https://metasys-server.example.com/api/v6/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations", "self": "https://metasys-server.example.com/api/v6/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
```json { "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://metasys-server.example.com/api/v6/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f" } ], "equipment": [ { "id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f", "itemReference": "{hostname}:{deviceHostname}/equipment.Engine1", "equipmentName": "Engine1", "shortName": null, "equipmentUrl": "https://metasys-server.example.com/api/v6/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f" } ], "objectUrl": "https://metasys-server.example.com/api/v6/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://metasys-server.example.com/api/v6/objects/bfcc3fce-a182-53c0-a529-268f8184496b" } }, "isAckRequired": true, "acknowledgedTime": "2021-02-16T20:31:02Z", "type": "alarmValueEnumSet.avHiAlarm", "priority": 70, "category": "objectCategoryEnumSet.generalCategory", "annotationsUrl": "https://metasys-server.example.com/api/v6/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations", "self": "https://metasys-server.example.com/api/v6/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
```json { "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://metasys-server.example.com/api/v6/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f" } ], "equipment": [ { "id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f", "itemReference": "{hostname}:{deviceHostname}/equipment.Engine1", "equipmentName": "IDU1", "shortName": null, "equipmentUrl": "https://metasys-server.example.com/api/v6/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f" } ], "objectUrl": "https://metasys-server.example.com/api/v6/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://metasys-server.example.com/api/v6/objects/bfcc3fce-a182-53c0-a529-268f8184496b" } }, "isAckRequired": true, "type": "alarmValueEnumSet.avHiAlarm", "priority": 70, "category": "objectCategoryEnumSet.generalCategory", "annotationsUrl": "https://metasys-server.example.com/api/v6/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations", "self": "https://metasys-server.example.com/api/v6/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
```json { "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://metasys-server.example.com/api/v6/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://metasys-server.example.com/api/v6/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
```json { "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://metasys-server.example.com/api/v6/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://metasys-server.example.com/api/v6/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations", "self": "https://metasys-server.example.com/api/v6/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
```json { "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://metasys-server.example.com/api/v6/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://metasys-server.example.com/api/v6/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations", "self": "https://metasys-server.example.com/api/v6/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.
## Operations (3)
| Method | Path | Summary |
|---|---|---|
| GET | `/activities` | List activities |
| POST | `/activities/batch` | Batch operations |
| DELETE | `/activities/streams/{streamId}/subscriptions/{subscriptionId}` | Delete activities subscription |
## Machine-readable artifacts (11)
- **OpenAPI** — https://raw.githubusercontent.com/api-evangelist/johnson-controls/refs/heads/main/openapi/johnson-controls-activities-api-openapi.yml
- **Documentation** — https://jci-metasys.github.io/api-landing/
- **GettingStarted** — https://jci-metasys.github.io/api-landing/guides/quickstart
- **ChangeLog** — https://jci-metasys.github.io/api-landing/guides/api-changelog
- **JSONSchema** — https://raw.githubusercontent.com/api-evangelist/johnson-controls/refs/heads/main/json-schema/johnson-controls-activities-schema.json
- **JSONSchema** — https://raw.githubusercontent.com/api-evangelist/johnson-controls/refs/heads/main/json-schema/johnson-controls-alarm-schema.json
- **JSONSchema** — https://raw.githubusercontent.com/api-evangelist/johnson-controls/refs/heads/main/json-schema/johnson-controls-network-device-schema.json
- **JSONSchema** — https://raw.githubusercontent.com/api-evangelist/johnson-controls/refs/heads/main/json-schema/johnson-controls-audit-schema.json
- **JSONSchema** — https://raw.githubusercontent.com/api-evangelist/johnson-controls/refs/heads/main/json-schema/johnson-controls-equipment-item-schema.json
- **JSONSchema** — https://raw.githubusercontent.com/api-evangelist/johnson-controls/refs/heads/main/json-schema/johnson-controls-equipment-points-schema.json
- **APIsJSON** — https://raw.githubusercontent.com/api-evangelist/johnson-controls/refs/heads/main/apis.yml
## Other Johnson Controls APIs (10)
- [Johnson Controls Alarms API](https://apis.io/apis/johnson-controls/johnson-controls-alarms-api/)
- [Johnson Controls Audits API](https://apis.io/apis/johnson-controls/johnson-controls-audits-api/)
- [Johnson Controls Authentication API](https://apis.io/apis/johnson-controls/johnson-controls-authentication-api/)
- [Johnson Controls Equipment API](https://apis.io/apis/johnson-controls/johnson-controls-equipment-api/)
- [Johnson Controls network devices API](https://apis.io/apis/johnson-controls/johnson-controls-network-devices-api/)
- [Johnson Controls Objects API](https://apis.io/apis/johnson-controls/johnson-controls-objects-api/)
- [Johnson Controls Schemas API](https://apis.io/apis/johnson-controls/johnson-controls-schemas-api/)
- [Johnson Controls Spaces API](https://apis.io/apis/johnson-controls/johnson-controls-spaces-api/)
- [Johnson Controls Streaming API](https://apis.io/apis/johnson-controls/johnson-controls-streaming-api/)
- [Johnson Controls time series API](https://apis.io/apis/johnson-controls/johnson-controls-time-series-api/)
## Tags
Activities
---
Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/johnson-controls/johnson-controls-activities-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/johnson-controls/.