This is a guide for getting started with the Smart Breaker API (formerly known as the Energy Management API, or EM API). Details about all API endpoints can be found in the operations documentation below, or by navigating with the left sidebar.

NOTE: The Smart Breaker Preview API can be found here and contains upcoming additions and changes that are in preview.

Application Credentials and API Key

An Application is the top-level hierarchical node of the Smart Breaker API (see System Hierarchy for more details), and is represented by a set of Application Credentials. Application Credentials consist of a Client ID and two Secrets.

Additionally, all requests in the Smart Breaker API require an API Key to be provided in the request headers (in the em-api-subscription-key header, specifically).

NOTE: Application Secrets have a one-year lifetime and must be rotated, and each Secret must be rotated independently. Application Secret rotation is accomplished via the Smart Breaker Developer Portal.

NOTE: Eaton does not store Application Secrets, so these will have to be securely stored by the Developer. However, Eaton stores Application Client IDs and API Keys, and those can be revisited in the Smart Breaker Developer Portal at any time after Application creation.

Obtain a set of Application Credentials and an API Key by creating an Application via the Smart Breaker Developer Portal.

End User Management

Eaton does not offer end-user management for integrations, with the exception of user account management for Installers and Application Developers. Installers are mentioned in this guide as they are managed programmatically via the APIs (see the Manage Installers section for more information), while Application Developers are managed solely through the Smart Breaker Developer Portal.

It is the Application Developer's responsibility to store and manage users of their system. The intention is that the Application should be responsible for creating middleware functionality that handles users' requests and authorization based on the organization they belong to.

Eaton manages Installer users and the Device Commissioning experience in order to capture information which is necessary for enabling Smart Breaker Applications.

It is safe for a Application Developers to expose the following to its application's end-users:

• Smart Breaker Device IDs and details.
• Smart Breaker Location IDs and details.

Information about the Application, its Organizations, and their respective Service Accounts should not be exposed to the Application's end-users.

The Smart Breaker Developer Portal is available for Developers to use. The Developer Portal is used to create your Developer Account, create and manage Teams of Developers, and create and manage Applications. Once you've created your necessary account, team(s), and application(s), you'll have everything you need to make use of the endpoints documented herein.

It is highly recommended that all developers use the interactive tutorial to understand how to best utilize the Smart Breaker API, so go check it out and come back here to dive in!

For any support needs, please contact our support email address: Smart Breaker API Support.

An Eaton engineer will promptly review your request and reply via email.

Throughout the operation documentation below, you may encounter a tag specifying that the operation is SB Only or EV Only. This API supports interaction with more than one physical device type - specifically, it supports Eaton Smart Breakers and Eaton EV Smart Breaker Chargers.

Most of the Device Command and other device-related operations are supported by both device types, but there are a subset of operations that are only supported by one or the other.

SB Only Operations

Operations with the tag SB Only are only supported by Eaton Smart Breakers. These devices have a corresponding hardwareType of emcb (i.e. from the Get Device operation).

EV Only Operations

Operations with the tag EV Only are only supported by Eaton EV Smart Breaker Chargers. These devices have a corresponding hardwareType of ev-emcb (i.e. from the Get Device operation).

Version	Release Date	Summary
v1.19.0	2023-11-29	Contains additions.
v1.18.0	2023-10-16	Contains improvements, changes, and fixes.
v1.17.0	2023-08-02	Contains removals, improvements, changes, and fixes.
v1.16.0	2023-06-21	Contains additions and changes.
v1.15.0	2023-03-30	Contains additions, and improvements.
v1.14.0	2023-03-06	Contains additions, changes. deprecations, improvements, removals, and documentation updates.
v1.13.0	2022-12-14	Contains additions.
v1.12.0	2022-12-05	Contains additions, changes, bugfixes, and improvements.
v1.11.0	2022-09-28	Contains additions, changes, and improvements.
v1.10.3	2022-08-16	Contains bugfixes and improvements.
v1.10.2	2022-06-24	Contains changes.
v1.10.1	2022-05-25	Contains bugfixes.
v1.10.0	2022-04-22	Contains additions, changes, improvements, and documentation updates.
v1.9.1	2022-02-24	Contains improvements.
v1.9.0	2022-02-11	Contains additions, changes, and documentation updates.
v1.8.0	2022-01-18	Contains additions, improvements, bugfixes, documentation updates, and deprecations.
v1.7.0	2021-11-22	Contains additions.
v1.6.1	2021-11-16	Contains improvements and bugfixes.
v1.6.0	2021-10-19	Contains additions, improvements, bugfixes, and documentation updates.
v1.5.0	2021-08-27	Contains additions, improvements, and documentation updates.
v1.4.1	2021-07-23	Contains bugfixes.
v1.4.0	2021-07-13	Contains additions, documentation updates, and internal improvements.
v1.3.1	2021-04-22	Contains bugfixes.
v1.3.0	2021-04-08	Contains updates and additions, including support for Local Communications.
v1.2.0	2021-02-22	Contains additions, updates, bugfixes and deprecations.
v1.1.1	2021-01-06	Contains bugfixes.
v1.1.0	2020-12-14	Contains additions, updates, and bugfixes.
v1.0.0	2020-09-29	Initial Production Release.

v1.19.0 - 2023-11-29

Added

• Local Communication is now supported for EV Chargers

v1.18.0 - 2023-10-16

Changed

• The description for "errorSupplyVoltage" evse error has been updated
• The description for "errorSolenoidPowerFail" evse error has been updated

Improvements

• The POST /sharedDeviceOverrideEvents API now accepts optional description field
• The GET /sharedDeviceOverrideEvents and GET /sharedDeviceOverrideEvents/{id} APIs can now also return a description
• The GET /sharedDeviceOverrideEvents API now also supports filtering by endTime.
  • If no startTime or endTime is provided, the events will be filtered to those that end after the current time instead of those that start after the current time.
  • The results are limited to the first 500 records instead of the first 50.
• The /sharedDeviceOverrideEvents resource endpoints now include the name of the organization that created the override event (createdByOrganizationName).
• eventCreatorOrganizationName is now included in the payload for the device override event webhook.
• /shareDeviceCodes resource endpoints now include the name of the organization that created, claimed, relinquished, or revoked the share code (createdByOrganizationName, claimedByOrganizationName, relinquishedByOrganizationName, revokedByOrganizationName)
• deviceOwnerOrganizationName and claimingOrganizationName are now included in the payload for the share device code webhook.

Fixed

• The GET /deviceData?$filter=deviceId eq '{deviceId}' endpoint now returns the telemetry.settings.alignment and telemetry.settings.dataReportRate data even before those settings have been explicitly configured.

v1.17.0 - 2023-08-02

Removed

• The deprecated endpoints and query parameters for device streams have been removed:
  • The GET /deviceStreamStatus endpoint has been removed. The GET /deviceStreams/{id}/status endpoint should be used to get status information for a device stream by ID instead.
  • The DELETE /deviceStreams endpoint has been removed. The DELETE /deviceStreams/{id} endpoint should be used to delete device streams by ID instead.
  • The deprecated query parameters for GET /deviceStreams are now removed. The $filter query parameter should be used instead of separate deviceId and streamId query params.

Improvements

• The PATCH /devices/{id} endpoint now allows updating load details.
• The GET /devices/{id} and GET /devices endpoints can now also return loadDetails.
• loadDetails are now included in the payload for the device onboarding webhook data if provided during commissioning.
• The GET /shareDeviceCodes/{code}/deviceSummary response body now includes the deviceHardwareType and the shareCodeStatus. And, the organization that claimed the code now also maintains read access to the share code device summary after the code has been revoked or relinquished.
• The POST /shareDeviceCodes/{code} API now sends a 400 response for devices that are configured to use OCPP.
• The POST /ocppChargePoints API will revoke any shared device access that was previously configured.
• The /sharedDeviceOverrideEvents resource endpoints now work for an EV device.

Changed

• The PATCH /devices/{deviceId}/evse/settings/configuration endpoint will respond with 400 BadRequest if the device is actively participating in an Override Event.

Fixed

• Fixed the values for the status of shared device override events in the API documentation.

v1.16.0 - 2023-06-21

Changed

• The GET /deviceBatchCommands/{id}/devices endpoint will now return deviceBatchCommand or deviceSunBatchCommand as a value for scheduleType.
• Breaking Change: The PATCH /devices/{deviceId}/evse/settings/configuration endpoint now expects the maxEnergy restriction to be in watt-hours instead of kilowatt-hours.
• The POST /deviceStreams endpoint now prevents registering the same stream multiple times on one device.
• The POST /devices/{deviceId}/breaker/remoteHandle/remoteHandlePosition endpoint will not accept secondsUntilReset if the device is actively participating in an Override Event.
• Physical Behavior: The LED display on the EV Smart Breaker Charger showing meter current will now be based on the 32 amp limit of the charger instead of the 40 amp limit of the breaker.

Added

• The following operations have been added to the /devices resource.
  • The GET /devices/{deviceId}/data/telemetry/meter/reading endpoint can be used to get the current breaker meter reading.
• The /shareDeviceCodes resource has been added:
  • The POST /shareDeviceCodes endpoint can be used to create a share device code that other organizations can use to gain limited access to a device.
  • The POST /shareDeviceCodes/{code}/claim endpoint can be used to claim a share device code.
  • The POST /shareDeviceCodes/{code}/revocation endpoint can be used to revoke a share device code.
  • The POST /shareDeviceCodes/{code}/relinquishment endpoint can be used to relinquish a share device code.
  • The GET /shareDeviceCodes/{code} endpoint can be used to get the details of a share device code by the organization who created it or an organization who claimed it.
  • The GET /shareDeviceCodes endpoint can be used to get a list of share device codes, with support for filtering by 'status', 'action', and 'deviceId'.
  • The GET /shareDeviceCodes/{code}/deviceSummary endpoint can be used to get a preview of the device associated with a share code before claiming it.
• The /shareDeviceCodeWebhooks resource has been added:
  • The POST /shareDeviceCodeWebhooks endpoint can be used to register a webhook that will be called when share device codes are claimed, relinquished, or revoked.
  • The GET /shareDeviceCodeWebhooks/{id} endpoint can be used to retrieve an individual share device code webhook.
  • The GET /shareDeviceCodeWebhooks endpoint can be used to get a list of registered share device code webhooks.
  • The DELETE /shareDeviceCodeWebhooks/{id} endpoint can be used to delete an individual share device code webhook.
• The sharedDevices resource has been added:
  • The GET /sharedDevices endpoint can be used to the details for all shared devices claimed by an Organization.
  • The GET /sharedDevices/{id} endpoint can be used to get the details of a shared device by the Organization that claimed it.
• The /sharedDeviceStreams resource has been added:
  • The POST /sharedDeviceStreams endpoint can be used to add a device shared with an application to a stream that application owns.
  • The GET /sharedDeviceStreams/{id}/status endpoint can be used to check the status of a shared device stream.
  • The GET /sharedDeviceStreams/{id} endpont can be used to get details for an individual shared device stream association.
  • The GET /sharedDeviceStreams endpoint can be used to get a list of shared device streams.
  • The DELETE /sharedDeviceStreams/{id} endpoint can be used to remove a stream association for a device shared with an application
• The /sharedDeviceOverrideEvents resource has been added:
  • The POST /sharedDeviceOverrideEvents endpoint can be used to create an override event that shared devices can then be assigned to.
  • The GET /sharedDeviceOverrideEvents/{eventId} endpoint can be used to retrieve an individual shared device override event.
  • The GET /sharedDeviceOverrideEvents endpoint can be used to get a list of shared device override events that were created by the current user's organization or affect one or more of the user's devices.
  • The POST /sharedDeviceOverrideEvents/{eventId}/sharedDeviceParticipations endpoint can be used to assign shared devices to an override event.
  • The POST /sharedDeviceOverrideEvents/{eventId}/sharedDeviceRemovals endpoint can be used to remove devices from participating in an override event. This is only accessible to users who belong to the organization that created the override event.
  • The POST /sharedDeviceOverrideEvents/{eventId}/sharedDeviceOptouts endpoint can be used to opt devices out from participating in an override event. This is only accessible to the device owner.
  • The GET /sharedDeviceOverrideEvents/{eventId}/sharedDeviceParticipations endpoint can be used to get a list of participations assigned to the override event.
  • The POST /sharedDeviceOverrideEvents/{eventId}/cancellation endpoint can be used to cancel an override event if all device participations are opted out or removed. This is only accessible to users who belong to the organization that created the override event.
• The /deviceOverrideEventWebhooks resource has been added:
  • The POST /deviceOverrideEventWebhooks endpoint can be used to register a webhook that will be called when devices are added to, removed from, or opted out of a shared device override event.
  • The GET /deviceOverrideEventWebhooks/{id} endpoint can be used to retrieve an individual device override event webhook.
  • The GET /deviceOverrideEventWebhooks endpoint can be used to get a list of registered device override event webhooks.
  • The DELETE /deviceOverrideEventWebhooks/{id} endpoint can be used to delete an individual device override event webhook.

v1.15.0 - 2023-03-30

Improvements

• The POST /deviceBatchCommands endpoint now accepts timeZone as an optional parameter which can be used to make cron execution of batch command as per the timezone. It will also return timeZone as a response if it is provided.
• The GET /deviceBatchCommands/{id} and GET /deviceBatchCommands endpoints can now also return timeZone in clockSchedule.

Added

• The following operations have been added to the /devices resource.
  • The POST /devices/{deviceId}/restart endpoint can be used to perform a soft reboot of the device, including applying any pending firmware updates.

v1.14.0 - 2023-03-06

Added

• The deviceSunBatchCommands resource has been added:
  • The POST /deviceSunBatchCommands endpoint can be used create a batchCommand that respects sunrise or sunset.

Changed

• The GET /deviceStreams endpoint now accepts using the $filter query parameter instead of separate deviceId and streamId query params.
  • The query parameters will still function but are now considered deprecated.
  • The $filter param cannot be used at the same time as the deviceId/streamId params.
  • It will now return 200 OK with an empty list instead of a 403 Forbidden if the caller is not authorized to view the requested resources.
• The GET /deviceStreamStatus endpoint (and its replacement, GET /deviceStreams/{id}/status) now returns a 404 response instead of a 400 response when a device ID or stream ID is provided instead of a deviceStream ID.

Deprecated

• The GET /deviceStreamStatus endpoint has been deprecated. The GET /deviceStreams/{id}/status endpoint should be used to get status information for a device stream by ID instead.
• The DELETE /deviceStreams endpoint has been deprecated. The DELETE /deviceStreams/{id} endpoint should be used to delete device streams by ID instead.

Improvements

• The POST /locations endpoint now accepts coordinates as an optional parameter in type address which can be used to store latitude and longitude of the location. It will also return coordinates as a response if it is provided
• The GET /locations and GET /locations/{locationId} endpoints now also returns the stored coordinates value for locations
• The PATCH /locations/{locationId} endpoint can now also be used to update coordinates's latitude and longitude
• The GET /deviceBatchCommands/{id} endpoint now also returns sunSchedule information for sun batch command.
• The GET /deviceBatchCommands endpoint now also returns sunSchedule information for sun batch command.
• The GET /deviceBatchCommands endpoint now also supports filtering on type.
• The POST /ocppChargePoints , GET /ocppChargePoints and GET /ocppChargePoints/{ocppChargePointId} endpoints now returns ocppCentralSystemUrl in the response
• chargerStationId is now included in the payload for the device onboarding webhook data for EV devices.
• chargerStationId is now included in the device details info for EV devices.

Removed

• The deprecated /users/roles endpoints have been removed:
  • The GET /users/roles endpoint has been removed. The GET /roles endpoint should be used to retrieve assignable roles instead.
  • The POST /users/roles endpoint has been removed. The POST /userRoles endpoint should be used to assign a role to a user instead.
  • The DELETE /users/roles endpoint has been removed. The DELETE /userRoles endpoint should be used to remove a user role assignment.
• The deprecated endpoints for legacy partner user management have been removed from the partner and preview APIs. The EM Developer Portal should be used to manage developer accounts and application service accounts instead.
  • The POST /users/my/password and POST /users/passwordResets endpoints have been removed.
  • The POST /partners and PATCH /partners/{id} endpoints have been removed.
  • The POST /tokens, POST /tokens/my, and DELETE /tokens/my endpoints have been removed.

Documentation

• Add 429 Too Many Requests to the list of responses for POST /devices/{deviceId}/breaker/remoteHandle/remoteHandlePosition endpoint.

v1.13.0 - 2022-12-14

Added

• The following operations have been added to the /devices resource.
  • The GET /devices/{deviceId}/evse/metadata/state endpoint can be used to get EVSE state information for an individual device. Will return the latest current error that the EVSE micro has recorded.
  • The GET /devices/{deviceId}/evse/metadata/controlConfiguration endpoint can be used to get EVSE control configuation for an individual device.
  • The PATCH /devices/{deviceId}/evse/settings/configuration endpoint can be used to set/update the EVSE configuration settings individual device.
  • The GET /devices/{deviceId}/evse/settings/configuration endpoint can be used to get the EVSE configuration settings for an individual device
• The /ocppCentralSystems resource has been added:
  • The POST /ocppCentralSystems operation can be used to create a new OCPP Central System.
  • The GET /ocppCentralSystems operation can be used to get all OCPP Central Systems a partner has created.
  • The GET /ocppCentralSystems/{ocppCentralSystemId} operation can be used to get a single OCPP Central System by Id.
  • The DELETE /ocppCentralSystems/{ocppCentralSystemId} operation can be used to delete a Central System.
• The /ocppChargePoints resource has been added:
  • The POST /ocppChargePoints operation can be used to register a new OCPP Charge Point to a device.
  • The GET /ocppChargePoints operation can be used to get all OCPP Charge Points a partner has created. Filtering on central system ID, device ID or both is supported.
  • The GET /ocppChargePoints/{ocppChargePointId} operation can be used to get a single OCPP Charge Point by Id.
  • The DELETE /ocppChargePoints/{ocppChargePointId} operation can be used to unregister an OCPP Charge Point from a device.
• The /plugSessions resource has been added
  • The GET /plugSessions?$filter=deviceId eq '{deviceId}' operation can be used to get plug sessions for a device. Filtering on a device ID (required) and status. Added filters (gt, ge, lt, le) on startedAt and stoppedAt for valid UTC dates. Can order by startedAt or stoppedAt. Request is paginated with query parameters for limit and offset.
  • The GET /plugSessions/{plugSessionId}/meterTelemetryData operation can be used to get the telemetry data collected during a specific plug session. Request is paginated with query parameters for limit and offset.

v1.12.0 - 2022-12-05

Added

• The following operations have been added to the /inviteCodes resource.
  • The POST /inviteCodes/{code}/deactivation endpoint can be used to deactivate an invite code. Existing user acceptances will remain unaffected.
• The /userPermissionWebhooks resource has been added:
  • The POST /userPermissionWebhooks endpoint can be used to register a webhook that will be called when user permissions within an application hierarchy are changed.
  • The GET /userPermissionsWebhooks endpoint can be used to get a list of registered user permission webhooks.
  • The GET /userPermissionsWebhooks/{webhookId} endpoint can be used to retrieve an individual user permission webhook.
  • The DELETE /userPermissionsWebhooks/{webhookId} endpoint can be used to delete an individual user permission webhook.
• The following operations have been added to the /deviceBatchCommands resource.
  • The GET /deviceBatchCommands endpoint can be used to get the list of batch command details.
  • The GET /deviceBatchCommands/{id} endpoint can be used to get details of a batch command.

Changed

• The PATCH /devices/{deviceId}/evse/settings/configuration endpoint now forces the time and day properties on windows to match the formats specified in the docs. Window days must be lowercase and equal to sunday, monday, tuesday, wednesday, thursday, friday or saturday. Window times must be a 4 digit 24-hour time. Ex: 1300, 0900, 2345.
• The POST /inviteCodes endpoint no longer has a default or maximum value of 100 for the user limit restriction.

Improvements

• The POST /deviceBatchCommands endpoint now returns a complete object which includes locationId, organizationId, type, deviceIds, clockSchedule, createdAt, path and body

Fixed

• An issue that was preventing BatchCommands from executing after one hour of scheduling.

v1.11.0 - 2022-09-28

Added

• The /inviteCodes resource has been added:
  • The POST /inviteCodes endpoint can be used to create an invite code that users can claim to gain access to a given location/organization.
  • The GET /inviteCodes/{code} endpoint can be used to get a created invite code, including details about invite code usage restrictions and a list of user acceptances for the code.
  • The GET /inviteCodes endpoint can be used to get a list of invite codes, with support for filtering by scope, locationId, or isActive status.

Changed

• The POST /userRoles and GET /userRoles response bodies now contain an inviteType field that describes how the user role was assigned.
• The DELETE /locations endpoint will now cleanup user invites that exclusively target the deleted location.
• Physical Behavior: The physical behavior of the standard Smart Breaker (aka EMCB) Display button has been updated as follows:
  • Press (regardless of hold):
    • Enable blinkup (commissioning) for 5 minutes
  • Press and hold:
    • Display WiFi Signal Strength

Improvements

• The POST /deviceBatchCommands endpoint now accepts endTime as an optional input parameter for cron schedules.
• The GET /deviceBatchCommands/{id}/devices endpoint now also returns the endTime for cron schedules.
• Emails sent from the API will now come from: "blsupport@eaton.com".

v1.10.3 - 2022-08-16

Improvements

• serialNumber is now included in the payload for the device onboarding webhook data.
• DELETE /devices/{deviceId} endpoint now returns 503 Device Unavailable when the device is offline.

Fixed

• An issue that would cause GET /devices/{deviceId}/breaker/remoteHandle/secondsUntilReset to respond with an empty object when there was no active timer. Now, the response returns 0 for the value of the timer if no timer is active.

v1.10.2 - 2022-06-24

Changed

• Physical Behavior: The physical behavior of the standard Smart Breaker (aka EMCB) Display button has been updated as follows:
  • Press (no hold):
    • Enable blinkup (commissioning) for 5 minutes (previously, this was 1 minute)
  • Press and hold:
    • Display WiFi Signal Strength

v1.10.1 - 2022-05-25

Fixed

• Fixed an issue that could cause local communication to fail after momentary network connection loss.

v1.10.0 - 2022-04-22

Added

• The following operations have been added to the /eventHistory resource.
  • The GET /eventHistory/breakerMainHandlePosition?$filter=deviceId eq '{deviceId}' operation can be used to get remote main handle position historical data. Filtering on a device ID (required).

Changes

• Limit the number of device streams of type webhook to 3 for a device.

Improvements

• The POST /locations endpoint now supports creating an address and equipment locations in one call.

Documentation

• The Commands for Specific Device Types section has been added to the API Overview.
• Update published API documentation to include previously-released endpoints:
  • GET /eventHistory/breakerRemoteHandlePosition?$filter=deviceId eq '{deviceId}'
  • GET /devices/{deviceId}/bargraph/settings/mode
  • GET /devices/{deviceId}/bargraph/settings/colors
  • GET /devices/{deviceId}/meter/settings/waveformConfiguration

v1.9.1 - 2022-02-24

Improvements

• The GET /deviceData?$filter=deviceId eq '{deviceId}' endpoint now also returns the meter.settings.loadPresentThreshold, telemetry, and bargraph data.

v1.9.0 - 2022-02-11

Added

• The following operations have been added to the /devices resource.
  • The PUT /devices/{deviceId}/telemetry/settings/alignment operation can be used to set the alignment setting for the device.

Changed

• Added an optional skipNotificationEmail parameter to the POST /userRoles endpoint query params. This field will determine if the user will be emailed when their role is changed. Defaults to false which sends an email.
• The POST /deviceBatchCommands operation now supports the /telemetry/settings/alignment path.

Documentation

• Understanding Streams portion of the EM API Partner Guide documentation has been moved to the Advanced Topics: Understanding Streams area of the Smart Breaker Portal.
• Understanding Local Communications portion of the EM API Partner Guide documentation has been moved to the Advanced Topics: Understanding Local Communications area of the Smart Breaker Portal.
• Control Devices portion of the EM API Partner Guide documentation has been moved to the Advanced Topics: Control Devices area of the Smart Breaker Portal.
• System Hierarchy portion of the EM API Partner Guide documentation has been moved to the Advanced Topics: System Hierarchy area of the Smart Breaker Portal.
• Create an Application portion of the EM API Partner Guide documentation has been moved to the Advanced Topics: System Hierarchy area of the Smart Breaker Portal.
• Create an Organization portion of the EM API Partner Guide documentation has been moved to the Advanced Topics: System Hierarchy area of the Smart Breaker Portal.
• Create Locations portion of the EM API Partner Guide documentation has been moved to the Advanced Topics: System Hierarchy area of the Smart Breaker Portal.
• Manage Installers portion of the EM API Partner Guide documentation has been moved to the Advanced Topics: System Hierarchy area of the Smart Breaker Portal.
• Manage Devices portion of the EM API Partner Guide documentation has been moved to the Advanced Topics: System Hierarchy area of the Smart Breaker Portal.
• Permissions portion of the EM API Partner Guide documentation has been moved to the Advanced Topics: Permissions area of the Smart Breaker Portal.

v1.8.0 - 2022-01-18

Added

• The /eventHistory resource has been added
  • The GET /eventHistory/breakerRemoteHandlePosition?$filter=deviceId eq '{deviceId}' operation can be used to get remote meter handle position historical data. Filtering on a device ID (required).

Improvements

• Improve main handle position detection to better suit a wider variety of deployments
• Email sent from the API will now come from: "smartbreaker@eaton.com"

Fixed

• Fixed an issue that could cause streams to fail to initialize for some devices at restart

Documentation

• Following the release of the Smart Breaker Developer Portal:
  • The "Energy Management" naming has updated to "Smart Breaker" throughout the documentation. All request URIs have been maintained and there are no functional differences with the naming update.
  • References to Partners have been replaced with Applications in most cases

Deprecated

• The following operations have been deprecated following the release of the Smart Breaker Developer Portal
  • POST /users/my/password (Change Password)
  • POST /users/passwordResets (Reset Password)
  • POST /partners (Activate Partner Account)
  • PATCH /partners/{partnerId} (Update Partner Account)
  • POST /tokens (Obtain User Authorization Token)
  • POST /tokens/my (Refresh User Authorization Token)
  • DELETE /tokens/my (Invalidate User Authorization Token)

v1.7.0 - 2021-11-22

Added

• The **/deviceData resource has been added
  • The GET /deviceData?$filter=deviceId eq '{deviceId}' operation can be used to get latest data for a device. Filtering on a device ID (required).

v1.6.1 - 2021-11-16

Changed

• Some improvements and bug fixes.

v1.6.0 - 2021-10-19

Added

• The /resourceQuotas resource has been added:
  • The GET /resourceQuotas endpoint can be used to get the current resource usage and limit details.

Fixed

• Fixed issue with GET /devices endpoint where a partner can get duplicate entries if the partner is also added as an installer.
• Fixed issue with POST /locations endpoint where empty optional fields are returning BadRequest.
• Fixed issue with POST /udpKeys endpoint where expired keys are counted against the key limit.
• Fixed issue with GET /deviceStreamsStatus where it was returning a 200 response code when the uuid provided was not a device stream.

Improvements

• The POST /deviceBatchCommands endpoint now supports Unix cron schedules.
• The POST /deviceBatchCommands endpoint now also supports sending commands to a specific set of devices.
• The GET /deviceBatchCommands/{id}/devices endpoint now also returns the startTime, scheduleType, and cronSchedule.
• The GET /devices endpoint now also supports filtering on serial number.

Documentation

• Update Webhook Stream details for correctness (rename numSamples to hwSamples for telemetry data to match implementation)

v1.5.0 - 2021-08-27

Added

• The following operations have been added to the /devices resource.
  • The GET /devices/{deviceId} endpoint can be used to get a single device.

Improvements

• Reliability improvements for device commands
• Reliability improvements for waveform captures across multiple devices at the same time
• Reliability improvements for IoTHub Device Stream connectivity

Documentation

• Update Webhook Stream details for correctness and include an SDK recommendation
• Update code samples to use axios instead of $.ajax
• Add breaker.metadata.mainHandlePositon to Stream Publish Payload

v1.4.1 - 2021-07-23

This release contains bugfixes.

Fixed

• Fix issue with verification link in user registration email

v1.4.0 - 2021-07-13

This release contains additions, documentation updates, and internal improvements.

Added

• The following operations have been added to the /streams resource.

  • The DELETE /streams/{streamId} endpoint can be used to remove a stream.

• The following operations have been added to the /devices resource.

  • The POST /devices/{deviceId}/waveforms endpoint can be used to record an immediate waveform.

Documentation

• Added Release Notes section (this section!) to API Documentation
• Added Webhooks collection of API calls to API Documentation

v1.3.1 - 2021-04-22

This release contains bugfixes.

Fixed

• Fixed issue with POST /userRoles and DELETE /userRoles operations.

v1.3.0 - 2021-04-08

This release contains updates and additions, including support for Local Communications.

Added

• The /udpKeys resource has been added:
  • The POST /udpKeys operation can be used to generate a new keys for local communications.
  • The GET /udpKeys operation can be used to retrieve multiple UDP keys.
  • The GET /udpKeys/{keyId} operation can be used to get an individual UDP key.
  • The DELETE /udpKeys/{keyId} operation can be used to delete a UDP key.
• The following operations have been added to the /devices resource.
  • The GET /devices/{deviceId}/meter/settings/waveformConfiguration operation can be used to get waveform configuration settings for an individual device.
  • The POST /devices/{deviceId}/udpKeys operation can be used to assign a UDP key to a device.

Updates

• Documentation updates:
  • The Understanding Local Communications section has been added to the API Overview
  • The Energy Management Local Communications Protocol (SBLCP) documentation is now available
    • An open-source Node.JS SDK for the Smart Breaker Coordinator is also available on Github
  • Left-hand content menu and operation groupings have been improved for ease of navigating documentation.

v1.2.0 - 2021-02-22

This release contains additions, updates, bugfixes and deprecations.

Added

• The /userRoles resource has been added:
  • The POST /userRoles operation can be used to invite and assign permissions to new and existing users.
  • The GET /userRoles operation can be used to view all assigned permissions to users in an org, along with their status ("pending" or "active").
  • The DELETE /userRoles operation can be used to delete a user’s role (regardless of permission grant status).
• The /roles resource has been added:
  • The GET /roles endpoint can be used to retrieve a list of assignable roles.
• Additions to the Streams payload
  • The property mainHandlePosition has been added to the breaker metadata section of the stream payload (breaker.metadata.mainHandlePosition)
  • The property loadState has been added to the meter metadata section of the stream payload (meter.metadata.loadState)

Fixed

• Fixed an issue that would cause the bargraph display to show current usage relative to 30A (instead of the breaker’s handle rating) when in track-meter-data mode.

Updates

• Updates to Streams payloads:
  • The root-level property schemaVersion has been updated to 4.2.0.beta (to reflect the inclusion of mainHandlePosition and loadState).
• Documentation updates:
  • The Manage Installers section of the API Overview includes:
    • An overview of how to use the new /roles and /userRoles resources
    • Links to the EM Install application on both platforms (iOS and Android)
  • The Understanding Streams section has been added to the API Overview
    • Much of the documentation was moved from the POST /streams operation description
    • Added documentation to better describe the Webhook Stream

Deprecated

• The /users/roles and contained operations have been deprecated.
  • The POST /userRoles operation should be used to assign a role to a user (previously performed by the POST /users/roles operation)
  • The DELETE /userRoles operation should be used to remove a role from a user (previously performed by the DELETE /users/roles operation)
  • The GET /roles operation should be used to retrieve a list of assignable user roles (previously performed by the GET /users/roles operation)

v1.1.1 - 2021-01-06

This release contains bugfixes.

Fixed

• Addressed a bug that prevented a successful re-commissioning of a device that has been decommissioned.

v1.1.0 - 2020-12-14

This release contains additions, updates, and bugfixes.

Added

• The following operations have been added to the /devices resource.
  • The PATCH /devices/{deviceId} operation can be used to re-parent a device to a new location within the same organization.
  • The PUT /devices/{deviceId}/bargraph/settings/mode operation can be used to set the device's bargraph mode.
  • The GET /devices/{deviceId}/bargraph/settings/mode operation can be used to get the device's bargraph mode.
  • The PUT /devices/{deviceId}/bargraph/settings/colors operation can be used to set the device's bargraph colors.
  • The GET /devices/{deviceId}/bargraph/settings/colors operation can be used to get the device's bargraph colors.
  • The GET /devices/{deviceId}/breaker/remoteHandle/secondsUntilReset operation can be used to get the number of seconds until the breaker's remote handle will reset
  • The GET /devices/{deviceId}/device/metadata/isConnected operation can be used to get the device's connection state
  • The PUT /devices/{deviceId}/meter/settings/loadPresentThreshold operation can be used to set the load present threshold for a device.
  • The GET /devices/{deviceId}/meter/settings/loadPresentThreshold operation can be used to get the load present threshold for a device.
  • The GET /devices/{deviceId}/waveforms operation can be used to get summaries of waveforms for a device.
  • The GET /devices/{deviceId}/waveforms/{waveformId} operation can be used to get details of a waveform for a device.
• The following operations have been added to the /deviceBatchCommands resource
  • The DELETE /deviceBatchCommands/{id} operation can be used to cancel a device batch command scheduled for a future start time.

Fixed

• Addressed a bug that sometimes caused device commands to fail with a 503.
• Addressed a bug that would cause some meter-related commands to timeout.
• Addressed a bug that would cause the initial data payload that is pushed to a new stream when it is set up to be encapsulated in an unexpected "data" property.

Updates

• The POST /devices/{deviceId}/breaker/remoteHandle/position operation has been updated to support the following optional features:
  • secondsUntilReset was added as an optional parameter to re-close the breaker (after an open operation) after secondsUntilReset seconds
• The POST /deviceBatchCommands operation has been updated to support the following new commands:
  • /bargraph/settings/mode
  • /bargraph/settings/colors
  • /meter/settings/loadPresentThreshold
• Updates to Streams payloads:
  • serialNumber has been added to the root of all device stream payloads and maps to the Legacy Smart Breaker Platform idDevice key
  • The schemaVersion in device stream payloads has been updated to v4.1.0.beta (reflecting the update to include serialNumber in the payload)
• Documentation updates:
  • The Streams documentation has been updated to include previously-missing and new payload information

v1.0.0 - 2020-09-29

Initial Production Release.

Added

• The following operations have been added to the /deviceBatchCommands resource:
  • The GET /deviceBatchCommands/{id}/devices operation can be used to get status of device batch command.

Fixed

• Update Device Streams to make the following changes to the root of the streams push payload:
  • idAgent updated to deviceId
  • idTransaction updated to transactionId
  • ts is added for all stream push payloads
• Ignore waveform if triggered immediately on bootup

Updates

• Partner accounts can no longer be used to perform a number of operations, including: managing locations, managing installer users, or controlling devices. An organization service account token must be used instead.

Attribution

App Store is a registered trademark of Apple Inc.

Google Play and the Google Play logo are trademarks of Google LLC