openapi: 3.0.3
info:
title: Eaton Smart Breaker API
description: |
REST API (formerly the Energy Management / EM API) for Eaton AbleEdge Smart Breakers and Eaton Green Motion EV Smart Breaker Chargers. Lets developers commission, monitor, and control devices, model panels and locations, run batch commands, and pull real-time and historical energy telemetry. Devices are typed via `hardwareType` — `emcb` for standard smart breakers, `ev-emcb` for EV chargers.
Authentication: every request must include `Em-Api-Subscription-Key: {SMART_BREAKER_API_KEY}` and `Authorization: Bearer {AUTH_TOKEN}`. Tokens are obtained from the OAuth2 token endpoint via Client ID + secret (Base64-encoded Basic auth) and are valid for 1 hour.
This OpenAPI spec is reconstructed from the public Eaton developer-portal documentation (https://api.em.eaton.com/docs and https://api.em.eaton.com/preview/docs) and the AbleEdge Smart Breaker developer portal (https://portal.em.eaton.com/). It is intended for cataloging and capability mapping in API Evangelist tooling, not as a substitute for the authoritative provider spec.
version: '1.0.0'
contact:
name: Eaton AbleEdge Developer Portal
url: https://portal.em.eaton.com/
license:
name: Eaton Brightlayer Experience Hub Terms
url: https://www.eaton.com/us/en-us/company/policies-and-statements/brightlayer-experience-hub-terms-and-conditions.html
x-source: https://api.em.eaton.com/docs
x-spec-status: reconstructed-from-public-docs
servers:
- url: https://api.em.eaton.com
description: Production
- url: https://api.em.eaton.com/preview
description: Preview (forward-looking, opt-in)
tags:
- name: Authorization
description: OAuth2 token issuance and user/service-account authentication.
- name: Organizations
description: Tenant organizations that own devices and users.
- name: Locations
description: Sites, buildings, and panels grouping devices.
- name: Devices
description: Smart breakers and EV chargers (emcb, ev-emcb).
- name: Device Commands
description: Per-device and batch device-control commands.
- name: Energy Data
description: Real-time and historical energy telemetry.
- name: Events
description: Device events, alarms, and notifications.
- name: EV Only
description: Operations supported only by Eaton EV Smart Breaker Chargers.
paths:
/oauth2/token:
post:
tags: [Authorization]
summary: Issue OAuth2 Bearer Token
description: Exchange Client ID + secret (Base64-encoded as Basic auth) for a Bearer access token valid for 1 hour.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required: [grant_type]
properties:
grant_type:
type: string
enum: [client_credentials]
responses:
'200':
description: Token issued
content:
application/json:
schema:
$ref: '#/components/schemas/AccessToken'
'401':
$ref: '#/components/responses/Unauthorized'
/api/v1/organizations:
get:
tags: [Organizations]
summary: List Organizations
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items: { $ref: '#/components/schemas/Organization' }
/api/v1/organizations/{organizationId}:
parameters:
- $ref: '#/components/parameters/OrganizationId'
get:
tags: [Organizations]
summary: Get Organization
responses:
'200':
description: OK
content:
application/json:
schema: { $ref: '#/components/schemas/Organization' }
/api/v1/locations:
get:
tags: [Locations]
summary: List Locations
parameters:
- in: query
name: organizationId
schema: { type: string, format: uuid }
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items: { $ref: '#/components/schemas/Location' }
/api/v1/locations/{locationId}:
parameters:
- $ref: '#/components/parameters/LocationId'
get:
tags: [Locations]
summary: Get Location
responses:
'200':
description: OK
content:
application/json:
schema: { $ref: '#/components/schemas/Location' }
/api/v1/devices:
get:
tags: [Devices]
summary: List Devices
description: List devices, optionally filtered by location.
parameters:
- in: query
name: locationId
schema: { type: string, format: uuid }
- in: query
name: hardwareType
schema:
type: string
enum: [emcb, ev-emcb]
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items: { $ref: '#/components/schemas/Device' }
/api/v1/devices/{deviceId}:
parameters:
- $ref: '#/components/parameters/DeviceId'
get:
tags: [Devices]
summary: Get Device
responses:
'200':
description: OK
content:
application/json:
schema: { $ref: '#/components/schemas/Device' }
delete:
tags: [Devices]
summary: Decommission Device
responses:
'204': { description: Device decommissioned }
/api/v1/devices/{deviceId}/state:
parameters:
- $ref: '#/components/parameters/DeviceId'
get:
tags: [Devices]
summary: Get Device State
responses:
'200':
description: OK
content:
application/json:
schema: { $ref: '#/components/schemas/DeviceState' }
/api/v1/devices/{deviceId}/commands:
parameters:
- $ref: '#/components/parameters/DeviceId'
post:
tags: [Device Commands]
summary: Send Device Command
description: Send an on/off/cycle command to a single device.
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/DeviceCommand' }
responses:
'202':
description: Command accepted
content:
application/json:
schema: { $ref: '#/components/schemas/CommandReceipt' }
/api/v1/deviceBatchCommands:
post:
tags: [Device Commands]
summary: Send Batch Device Commands
description: Send a single command to many devices in one request.
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/BatchDeviceCommand' }
responses:
'202':
description: Batch accepted
content:
application/json:
schema: { $ref: '#/components/schemas/BatchCommandReceipt' }
/api/v1/devices/{deviceId}/energy:
parameters:
- $ref: '#/components/parameters/DeviceId'
get:
tags: [Energy Data]
summary: Get Device Energy Telemetry
parameters:
- in: query
name: start
schema: { type: string, format: date-time }
- in: query
name: end
schema: { type: string, format: date-time }
- in: query
name: interval
schema: { type: string, enum: [1m, 5m, 15m, 1h, 1d] }
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items: { $ref: '#/components/schemas/EnergyReading' }
/api/v1/devices/{deviceId}/events:
parameters:
- $ref: '#/components/parameters/DeviceId'
get:
tags: [Events]
summary: List Device Events
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items: { $ref: '#/components/schemas/DeviceEvent' }
/api/v1/ev/{deviceId}/sessions:
parameters:
- $ref: '#/components/parameters/DeviceId'
get:
tags: [EV Only]
summary: List EV Charging Sessions
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items: { $ref: '#/components/schemas/ChargingSession' }
/api/v1/ev/{deviceId}/sessions/{sessionId}:
parameters:
- $ref: '#/components/parameters/DeviceId'
- in: path
name: sessionId
required: true
schema: { type: string, format: uuid }
get:
tags: [EV Only]
summary: Get EV Charging Session
responses:
'200':
description: OK
content:
application/json:
schema: { $ref: '#/components/schemas/ChargingSession' }
components:
securitySchemes:
OAuth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://api.em.eaton.com/oauth2/token
scopes: {}
SubscriptionKey:
type: apiKey
in: header
name: Em-Api-Subscription-Key
parameters:
OrganizationId:
in: path
name: organizationId
required: true
schema: { type: string, format: uuid }
LocationId:
in: path
name: locationId
required: true
schema: { type: string, format: uuid }
DeviceId:
in: path
name: deviceId
required: true
schema: { type: string, format: uuid }
responses:
Unauthorized:
description: Missing or invalid credentials
content:
application/json:
schema: { $ref: '#/components/schemas/Error' }
schemas:
AccessToken:
type: object
required: [access_token, token_type, expires_in]
properties:
access_token: { type: string }
token_type: { type: string, enum: [Bearer] }
expires_in: { type: integer, description: Token lifetime in seconds (typically 3600) }
Organization:
type: object
properties:
id: { type: string, format: uuid }
name: { type: string }
Location:
type: object
properties:
id: { type: string, format: uuid }
organizationId: { type: string, format: uuid }
name: { type: string }
address:
type: object
properties:
street: { type: string }
city: { type: string }
region: { type: string }
postalCode: { type: string }
country: { type: string }
timezone: { type: string }
Device:
type: object
required: [id, locationId, hardwareType]
properties:
id: { type: string, format: uuid }
locationId: { type: string, format: uuid }
hardwareType:
type: string
enum: [emcb, ev-emcb]
sku: { type: string }
serialNumber: { type: string }
chargerStationId: { type: string, nullable: true }
name: { type: string }
firmwareVersion: { type: string }
DeviceState:
type: object
properties:
deviceId: { type: string, format: uuid }
position: { type: string, enum: [open, closed, tripped] }
connectivity: { type: string, enum: [online, offline] }
lastReportedAt: { type: string, format: date-time }
DeviceCommand:
type: object
required: [command]
properties:
command:
type: string
enum: [open, close, cycle]
reason: { type: string }
BatchDeviceCommand:
type: object
required: [deviceIds, command]
properties:
deviceIds:
type: array
items: { type: string, format: uuid }
command: { $ref: '#/components/schemas/DeviceCommand' }
CommandReceipt:
type: object
properties:
commandId: { type: string, format: uuid }
status: { type: string, enum: [accepted, queued, executing, completed, failed] }
createdAt: { type: string, format: date-time }
BatchCommandReceipt:
type: object
properties:
batchId: { type: string, format: uuid }
receipts:
type: array
items: { $ref: '#/components/schemas/CommandReceipt' }
EnergyReading:
type: object
properties:
timestamp: { type: string, format: date-time }
current: { type: number, description: Amps }
voltage: { type: number, description: Volts }
frequency: { type: number, description: Hertz }
activePower: { type: number, description: Watts }
energy: { type: number, description: Watt-hours consumed in the interval }
DeviceEvent:
type: object
properties:
id: { type: string, format: uuid }
deviceId: { type: string, format: uuid }
type: { type: string, enum: [trip, overcurrent, undervoltage, overvoltage, offline, online, commandFailed, custom] }
severity: { type: string, enum: [info, warning, error, critical] }
timestamp: { type: string, format: date-time }
message: { type: string }
ChargingSession:
type: object
properties:
id: { type: string, format: uuid }
deviceId: { type: string, format: uuid }
startedAt: { type: string, format: date-time }
endedAt: { type: string, format: date-time, nullable: true }
energyDelivered: { type: number, description: Watt-hours }
peakPower: { type: number, description: Watts }
status: { type: string, enum: [active, completed, faulted, cancelled] }
Error:
type: object
properties:
code: { type: string }
message: { type: string }
details: { type: object, additionalProperties: true }
security:
- OAuth2: []
SubscriptionKey: []