Enode Developers
Latest version

Enode API 2024-10-01

This reference provides a comprehensive overview of the Enode API endpoints for accessing and controlling its hardware and features. The API follows REST principles, and uses OAuth 2.0.

This page features detailed documentation for each of our endpoints. You can also explore our API through our updated OpenAPI specifications or Postman collection.

The API is versioned, and all documentation on this page, including the links to the OpenAPI specifications and Postman collection is specific to the selected version.

Environments

We provide multiple environments, each with unique data access policies, and live/mocked vendors.

Environments are isolated from each other. Client credentials are tied to a specific environment and cannot be reused across environments.

Copy linkProduction

Features the latest stable software, live vendors, and strict data access controls.

NameURL
APIhttps://enode-api.production.enode.io
OAuth Tokenhttps://oauth.production.enode.io/oauth2/token
Link UIhttps://link.production.enode.io

Copy linkSandbox

Includes the latest stable software and mocked vendors/vehicles/chargers.

NameURL
APIhttps://enode-api.sandbox.enode.io
OAuth Tokenhttps://oauth.sandbox.enode.io/oauth2/token
Link UIhttps://link.sandbox.enode.io

Authentication

The Enode API uses OAuth 2.0 client access tokens for authenticating server requests.

Copy linkAPI credentials

Enode API access begins with a client and its corresponding client ID and client secret. Clients organize data, are separate, and relate to a specific environmentAPI.

API credentials are used to obtain an access tokenAPI for accessing client-wide endpointsAPI and user-specific endpointsAPI.

Key Description
Client IDThe identifier for your client, referred to as the client_id.
Client secretThe secret for your client, referred to as the client_secret.

Copy linkGetting an access token

The access token authorizes client access to all data and functionality. Obtain it via the OAuth 2.0 client credentials grant using the API credentialsAPI and the relevant OAuth URLsAPI for your client's environment.

Token request example

curl https://oauth.{YOUR_CLIENT_ENVIRONMENT}.enode.io/oauth2/token \
-X POST \
-u {YOUR_CLIENT_ID}:{YOUR_CLIENT_SECRET} \
-d "grant_type=client_credentials"

After requesting the token URL, you'll receive an access token in the response. Cache this token on your server until it expires and needs refreshingAPI. Keep the access token secret.

Token response example

{
	"access_token": "{YOUR_ACCESS_TOKEN}",
	"expires_in": 3599,
	"scope": "",
	"token_type": "bearer"
}

Copy linkRefreshing access tokens

Access tokens expire hourly, indicated by the expires_in key in the response. When expired, obtain a new tokenAPI.

Copy linkAccessing the API with the access token

Authenticate all API requests using a bearer authentication header. This header accesses client-wide endpoints (service healthAPI, tariffsAPI, user managementAPI, and webhooksAPI).

Type Value
HeaderAuthorization: Bearer {YOUR_ACCESS_TOKEN}

Client resource request example

curl https://enode-api.{YOUR_CLIENT_ENVIRONMENT}.enode.io/health/ready \
-H "Authorization: Bearer {YOUR_ACCESS_TOKEN}" \
-H "Content-Type: application/json" \

Copy linkAccessing user-specific endpoints

For resources specific to a user, include an additional header with the user ID along with the general authorization header. For versions newer than 2023-08-01, this is no longer required.

Use this additional header for general user endpoints (locationsAPI, usersAPI, schedulesAPI, statisticsAPI) and device-specific endpoints (chargersAPI, HVACsAPI, solar invertersAPI, and vehiclesAPI).

Type Value
HeaderEnode-User-Id: {USER_ID}

User resource request example

curl https://enode-api.{YOUR_CLIENT_ENVIRONMENT}.enode.io/me \
-X GET \
-H "Authorization: Bearer {YOUR_ACCESS_TOKEN}" \
-H "Enode-User-Id: {USER_ID}" \

Response times

Enode resources like Schedules and Locations have response times of <200ms. However, vehicle interactions involve various delays and timing characteristics.

Understanding the range of possible timings without diving into vendor-specific causes, helps you account for these factors in your UX design.

Copy linkAPI GET requests

Copy linkGet Vehicle

Get Vehicles and List Vehicles are fast operations since all data is prefetched by Enode and shared from a cache.

On API versions prior to 2023-08-01 it is possible to request a synchronous update where data is fetched directly from the vendor. Such requests have longer response times, sometimes 30 seconds or more, depending on the characteristics of the underlying vendor APIs. From 2023-08-01 onwards this has been replaced by the refresh hintAPI mechanism.

The Login step usually takes <2 seconds, but can rarely take up to 30 seconds due to background negotiations, retries, and initial vehicle data fetching.

The final Accept step experiences similar delays as List Vehicles.

Copy linkCharging commands

Charging commands show significant timing variability among vendors. Initiating the action is instant, but the updated charging state typically takes 20 seconds to appear. Occasionally the action may take 5 minutes or more to confirm.

Copy linkWebhooks

Webhooks typically involve polling and dynamically adjust the polling rate based on various factors to balance prompt updates with avoiding unnecessary load on the vehicle.

The maximum baseline delay between a real-world change (e.g., a vehicle being plugged in) and the resulting webhook notification is typically 7 minutes. However, actual delays can vary depending on factors such as vehicle activity and network conditions. Below is a general guide for typical webhook delays:

Vehicle contextTypical delay
default~7 minutes
charging~2-5 minutes
smartcharge PLAN:*~2 minutes
sleeping~20 minutes

If you'd like to request a faster refresh, you can call the various /refresh-hint endpoints found on devices to queue an accelerated data refresh.

Scopes

Access to the data and controls of a device are scoped by an inclusive scopes structure. The scopes are requested in the Link user endpoint via the scopes parameter. Scopes are presented to your user in Link UI, and explained through example data and examples of features enabled by each scope. Your user is not able to de-select or configure scopes themselves in Link UI.

  • Data scopes include all data and states we fetch from the device, excluding location data, and is always required (e.g vehicle:read:data)
  • Location scopes include the location coordinates of the device (e.g. vehicle:read:location)
  • Control scopes are always explicit to the type of control that is requested (e.g. vehicle:control:charging)

The applied scopes are surfaced through the scopes object in device responses (see example below).

Copy linkOverview of scopes

Asset type Scope Description
Batterybattery:control:operation_modeControls the operation mode of the battery
battery:read:locationReads the GPS coordinates of the battery
battery:read:dataReads the battery data, such as the charge state, configuration and general information
Chargercharger:control:chargingControls the max current configuration and/or charging of the charger
charger:read:dataReads the charger data, such as the charge state and general information
HVAChvac:control:modeControls the mode (permanent hold or follow schedule) of the HVAC unit
hvac:read:dataReads the HVAC data, such as the information, thermostat state and temperature state
Inverterinverter:read:dataReads the inverter data, such as the production state and general information
inverter:read:locationReads the GPS coordinates of the inverter
Metermeter:read:locationReads the GPS coordinates of the meter
meter:read:dataReads the meter data, such as energy state and general information
Vehiclevehicle:control:chargingControls the charging of the vehicle
vehicle:read:dataReads the vehicle data, such as charge state, odometer and general information
vehicle:read:locationReads the GPS coordinates of the vehicle

Copy linkHandling excluded scopes

Copy linkThe relationship between scopes and capabilities

If a device is missing a scope, e.g. a charger that does not have the charger:control:charging scope set, will always have the charging related capabilities will always be set as isCapable: false with no intervention specified.

Example charger response

{
  "id": "2211e263-0362-4235-83f4-887bdf3ee414",
  "userId": "17d9f847-8a1c-4158-adaa-4911a7acd5f9",
  "vendor": "ZAPTEC",
  "lastSeen": "2023-03-21T21:08:27.596Z",
  "isReachable": true,
  "locationId": "2211e263-d6d4-d6d4-d6d4-dbdd77ec82b6",
  "scopes": ["charger:read:data"], // Scopes applied to the device
  "chargeState": { ... },
  "information": { ... },
  "capabilities": {
    "information": {
      "isCapable": true, // Capable via the charger:read:data scope
      "interventionIds": []
    },
    "chargeState": {
      "isCapable": true, // Capable via the charger:read:data scope
      "interventionIds": []
    },
    "startCharging": {
      "isCapable": false, // Missing charger:control:charging scope
      "interventionIds": []
    },
    "stopCharging": {
      "isCapable": false, // Missing charger:control:charging scope
      "interventionIds": []
    },
    "setMaxCurrent": {
      "isCapable": false, // Missing charger:control:charging scope
      "interventionIds": []
    }
  }
}

Copy linkResponses when the location scope is excluded

Devices with a missing location scopes will respond with longitude: null and latitude: null as part of their location object.

Copy linkResponses when a control scopes is excluded

Devices with missing control scopes will respond with a 403 error, and the action or command will not go through to the device.

Copy linkApplying new scopes to a device

To set new scopes for a device, it needs to be re-linked via the Link userAPI endpoint by setting new scope values in the scopes parameter.

Errors and problems

Copy linkErrors when accessing a User's resources

When using an access_token to access a user's resources, you may encounter the following 4XX range HTTP Status Codes:

HTTP Status CodeExplanation
400 Bad RequestThe request payload failed schema validation or parsing
401 UnauthorizedMissing or invalid authentication details
403 ForbiddenAuthentication succeeded, but the user lacks access to the resource due to a missing control scope.
404 Not FoundRequested resource doesn't exist
405 Method Not AllowedVendor unavailability prevented request completion
408 Request TimeoutVendor timeout prevented request completion
409 ConflictVendor rejection prevented request completion
424 Failed DependencyFailed vendor requests prevented request completion
429 Too Many RequestsVendor rate limiting prevented request completion

In all cases, an RFC7807 Problem Details body is returned to aid in debugging.

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
{
  "type": "https://developers.enode.com/problems/bad-request",
  "title": "Payload validation failed",
  "detail": "\"authorizationRequest.scope\" is required",
}

Copy linkProblems

TitleDescription
Bad request

Some part of the request was malformed. See associated detail message for more information.

Enode Controlled Entity

This entity is currently managed by Smart Charging or Schedules and cannot accept manual commands. Either disable the feature controlling the target, or force charging to start through our External Start APIAPI.

Entity Not Found

The requested entity was not found on the user's account.

Forbidden

The current context is not allowed to access the requested resource.

Not Found

The requested entity was not found on the user's account. If requesting vendor entities, ensure you're using the top level id field and not information.id. information.id is the ID the vendor uses to refer to the entity and changes over time.

Server Error

A critical error has ocurred. An employee has been alerted and will work to remedy the situation

Service Unavailable

The service is currently unavailable. Most likely the service was slow to respond, might be overloaded or down for maintenance. Other endpoints might still be available.

You may want to retry the request using a randomized backoff delay.

Check the Enode Status page if this problem persists.

Timeout

A request timed out. If this problem was returned by a route that tried to communicate with vendor APIs, remove the fields query parameter to fetch the Enode hosted cache. This cache is updated every 10 minutes.

Unauthorized

The request contained an invalid or expired token.

Validation Error

The response we prepared failed to pass outgoing validation. An employee has been alerted and will work to remedy the situation.

Versioning

Enode's REST API is versioned. A dated version is released when breaking changes occur, while new features and bug fixes (additive changes) are available in all supported API versions.

You can view all available versions and updates in the changelog.

API clients are pinned to the latest API version upon creation, affecting all API requests and webhook events. API responses include an Enode-Version header, and webhook events have a version field.

You can override the API version on a specific request by sending an Enode-Version in the request header.

Copy linkBreaking changes

Breaking changes will be released as a new version. When a new version is released, the previous version is supported for six months before deactivation. Enode staff will notify you in advance. Each API version comes with a migration guide explaining changes and upgrade suggestions.

We consider the following breaking changes

  • Changing a request’s authorization or authentication requirements
  • Adding a new required input parameter
  • Changing input validation
  • Removing an HTTP route or method
  • Removing or renaming a response parameter

All other additive changes are considered backwards compatible.

Copy linkVersion Lifecycle

Current

  • This is the latest API version, recommended for all customers.
  • It is the default version for new clients and the default version documented in our API Reference.
  • There is only ever one Current API version.

Deprecated

  • This version has been superseded by a newer version. Multiple Deprecated versions can exist.
  • Customers can still choose this version for new clients or webhook subscriptions at developers.enode.com.
  • Documentation will be marked as Deprecated.
  • New functionality may not be released to Deprecated versions and supported exclusively on the Current API version.
  • We recommend you to upgrade to the Current version as soon as possible.

Legacy

  • This version has been deprecated for 6 months. Multiple Legacy versions can exist.
  • Customers cannot select this version for new clients or webhook subscriptions.
  • Documentation will not be accessible from the API Reference. You can review Legacy documentation by logging in to your organization dashboard and selecting a client with a Legacy version.
  • Functionality may be degraded, and no new features will be added.
  • 4 weeks after entering Legacy status, we will begin preparations for automatically upgrading clients on this version. Enode will conduct API brownouts for clients still using Legacy versions at this time. During these brownouts, we will randomly reject API requests using the Legacy API version.
  • 8 weeks after entering Legacy status, clients using this version will be automatically upgraded to the Current API version.

Copy linkLabels

Some of the products or endpoints we have available are labelled. Here's an explanation of each.

Copy linkBeta

This product or endpoint is now feature complete and the implementation will not change. There may be bugs or stability issues but they are actively being worked on. We are still open to receiving feedback before delivering a stable release.

Copy linkExperimental

This product or endpoint is being released in an early stage to get feedback. There are likely bugs or other issues that may not necessarily be prioritized. The whole implementation may be completely changed or removed.

Copy linkDeprecated

Individual features, endpoints, or fields tagged as Deprecated will be removed in a future version of the API. If you are using deprecated functionality you should update your application to use alternative features or methods we provide.

Pagination

Enode endpoints returning collections of a specific type of resource, such as GET /vehicles, will return a paginated response. Each response will consist of a subset of the resources, called a page. To retrieve the entire collection, subsequent pages need to be fetched.

Each response includes two properties: data and pagination. The data property contains the records of the current page and the pagination property contains cursors that can be used to fetch additional pages. These cursors, before and after, are unique identifiers for specific records in the dataset that help you keep track of your position and navigate through the pages.

Copy linkQuerying a paginated API endpoint

When querying a paginated endpoint, you may provide the following pagination query parameters:

Pagination query parameter example

{
  "pageSize": 50,
  "before": "MjAyMy0wNy0xOFQxMDowODowMi4zNzNa",
  "after": "MjAyMy0wNi0xNlQwOTowMzowMS4yNjJa"
}

All of these pagination query parameters are optional. If pageSize is not provided, the default page size of 50 is used. If neither before nor after are provided, the returned page will contain the first set of resources in the collection.

The before and after parameters are mutually exclusive. If both are supplied, the API will return an error.

Responses from most paginated endpoints are sorted in descending order according to when the resource was created. Hence, for a request like GET /vehicles, the most recently linked vehicles appear on the first page.

Copy linkHow to navigate through paginated API responses

The pagination property in a paginated response typically looks like this:

Pagination property example

"pagination": {
  "before": "MjAyMy0wNy0xOFQxMDowODowMi4zNzNa",
  "after": "MjAyMy0wNi0xNlQwOTowMzowMS4yNjJa"
}

The pagination property provides the cursors required to fetch the next and previous pages of resources:

  • before contains the cursor to be used to fetch the previous page.
  • after contains the cursor to be used to fetch the next page.

One or both cursors may be null instead of a string. This occurs when:

  • You are on the first page. There are no preceding resources, so before will now be null as otherwise it would point to an empty page.
  • You are on the last page. There are no subsequent resources, so after will now be null as otherwise it would point to an empty page.
  • The entire collection fits on the first page. There are no preceding or subsequent resources, so both before and after are null.

Copy linkFull example response

Example paginated response

{
    "data": [
        {
            "id": "0",
            "vendor": "TESLA",
            ...
            "isReachable": true
        },
        ...
        {
            "id": "49",
            "vendor": "TESLA",
            ...
            "isReachable": true
        }
    ],
    "pagination": {
        "before": null,
        "after": "MjAyMy0wNy0xOFQxMDowNDowMi4zNzNa"
    }
}

In this example, the data array includes the resource records for the current page. The pagination object provides the cursors for navigating to adjacent pages.

Batteries

The Battery object represents a residential energy storage unit, like a Tesla Powerwall or Enphase IQ. It offers detailed insights into the battery's operation and allows you to instruct the battery on handling its stored energy.

List batteriesBeta

GET /batteries

Returns a paginated list of all Batteries.

Request

Query parameters
after string Optional
before string Optional
pageSize integer Optional

Default value: 50

Request example

curl --request GET \
  --url 'https://enode-api.production.enode.io/batteries?after=MjAyMy0wNy0xOFQxMDowODowMi4zNzNa&before=MjAyMy0wNy0xOFQxMDowODowMi4zNzNa&pageSize=50' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response 200

Attributes
  • data array of object

    Paginated list of batteries

    Show child attributes
    • data[].id string<uuid>

      Unique identifier for the battery object

    • data[].userId string

      The ID of the user that linked this battery.

    • data[].vendor string

      Machine-friendly name of the vendor. Use this in API requests.

      Possible enum values:

        TESLAENPHASEHUAWEISOLAREDGESMA
    • data[].lastSeen string<date-time>

      The last time Enode successfully communicated with the vendor or when the battery was initially linked.

    • data[].isReachable boolean

      Indicates whether Enode can currently access live data from the battery. If the battery is not reachable, data updates will be delayed.

    • data[].chargeState object

      Latest information about the battery. null values indicate we are unable to determine a value for the field based on the information coming from the vendor.

      Show child attributes
      • data[].chargeState.status string or null

        The power delivery state of the battery.

        Possible enum values:

          CHARGINGDISCHARGINGIDLEFAULTUNKNOWN
      • data[].chargeState.batteryCapacity number or null

        Battery capacity in kWh.

      • data[].chargeState.batteryLevel number or null

        Remaining battery charge level in percent.

      • data[].chargeState.chargeRate number or null

        The current charge rate in kW. A positive value indicates that the battery is charging.

      • data[].chargeState.dischargeLimit number or null

        Minimum charge level for a battery, expressed as a percentage. Batteries will not discharge below this user-set reserve level except in emergency power situations.

      • data[].chargeState.lastUpdated string<date-time> or null

        Time of last received charge state update

    • data[].config object
      Show child attributes
      • data[].config.operationMode string or null

        The current operation mode of the battery.

        • IMPORT_FOCUS: Prioritizes charging the battery. Draws power from the grid and any excess solar energy for charging. Leveraged energy sources depend on the configuration of the battery. Note: Focus modes target a certain battery behavior but are ultimately internal to the battery. Actual behavior might differ from the focus mode.
        • EXPORT_FOCUS: Prioritizes discharging energy stored in the battery back to the household and any excess to the grid. Grid exports often depend on local regulation and might require agreements with grid providers to be supported. Note: Focus modes target a certain battery behavior but are ultimately internal to the battery. Actual behavior might differ from the focus mode.
        • TIME_OF_USE: Maximizes energy cost savings in accordance with a user-defined schedule matching a utility rate plan. Energy may be consumed from solar, battery, or grid sources, depending on the current prices and your user's settings in the OEM app. Energy may be exported to the grid from solar or battery sources, depending on current prices and your user's settings in the OEM app.
        • SELF_RELIANCE: Minimizes household reliance on the grid. Prioritizes using own energy from solar or battery for household consumption before importing from grid. Energy may be exported to the grid from solar, depending on excess solar and your user's settings in the OEM app.

        Possible enum values:

          IMPORT_FOCUSEXPORT_FOCUSTIME_OF_USESELF_RELIANCE
      • data[].config.lastUpdated string<date-time> or null

        Time of last received configuration update

    • data[].information object

      Descriptive information about the battery

      Show child attributes
      • data[].information.id string

        Battery vendor ID

      • data[].information.brand string

        A formatted and properly cased OEM brand name, suitable for reading by humans. May contain special characters.

        Possible enum values:

          TeslaEnphaseHUAWEISolarEdgeSMA
      • data[].information.model string

        Battery model

      • data[].information.siteName string

        Name of the site, as set by the user on the device/vendor. If no user-specified name is available, we construct a fallback name using the vendor/device/model names.

      • data[].information.installationDate string<date-time>

        Battery installation date

    • data[].capabilities object

      A collection of descriptors that describe the capabilities of this specific battery

      Show child attributes
      • data[].capabilities.exportFocus object

        Supports EXPORT_FOCUS operation mode.

        Show child attributes
        • data[].capabilities.exportFocus.isCapable boolean

          The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

        • data[].capabilities.exportFocus.interventionIds array of string

          IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

      • data[].capabilities.importFocus object

        Supports IMPORT_FOCUS operation mode.

        Show child attributes
        • data[].capabilities.importFocus.isCapable boolean

          The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

        • data[].capabilities.importFocus.interventionIds array of string

          IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

      • data[].capabilities.timeOfUse object

        Supports TIME_OF_USE operation mode.

        Show child attributes
        • data[].capabilities.timeOfUse.isCapable boolean

          The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

        • data[].capabilities.timeOfUse.interventionIds array of string

          IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

      • data[].capabilities.selfReliance object

        Supports SELF_RELIANCE operation mode.

        Show child attributes
        • data[].capabilities.selfReliance.isCapable boolean

          The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

        • data[].capabilities.selfReliance.interventionIds array of string

          IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

    • data[].scopes array of string

      Scopes that the user has granted for this battery.

    • data[].location object

      Battery's GPS coordinates

      Show child attributes
      • data[].location.id string<uuid> or null

        ID of the location the battery is currently positioned at (if any).

      • data[].location.longitude number or null

        Longitude in degrees

      • data[].location.latitude number or null

        Latitude in degrees

      • data[].location.lastUpdated string<date-time> or null

        Time of last received location state update

  • pagination object

    Cursors to the pages before and after current page. See the PaginationAPI section for reference.

    Show child attributes
    • pagination.after string or null
    • pagination.before string or null

Response example

{
  "data": [
    {
      "id": "54d827e1-8355-4fed-97b5-55940d1d09ba",
      "userId": "4f6fecd0-bdae-49be-b6e8-ee442e1e3da9",
      "vendor": "TESLA",
      "lastSeen": "2020-04-07T17:04:26Z",
      "isReachable": true,
      "chargeState": {
        "status": "CHARGING",
        "batteryCapacity": 13.5,
        "batteryLevel": 80,
        "chargeRate": 4.6,
        "dischargeLimit": 20,
        "lastUpdated": "2020-04-07T17:04:26Z"
      },
      "config": {
        "operationMode": "IMPORT_FOCUS",
        "lastUpdated": "2020-04-07T17:04:26Z"
      },
      "information": {
        "id": "7deb27f8-794f-467b-855e-5c61dd9f2cb3",
        "brand": "Tesla",
        "model": "Powerwall",
        "siteName": "Powerwall Home",
        "installationDate": "2020-04-07T17:04:26Z"
      },
      "capabilities": {
        "exportFocus": {
          "isCapable": false,
          "interventionIds": [
            "4eaeb363-296d-4ccc-a973-7805e6f400bd"
          ]
        },
        "importFocus": {
          "isCapable": false,
          "interventionIds": [
            "4eaeb363-296d-4ccc-a973-7805e6f400bd"
          ]
        },
        "timeOfUse": {
          "isCapable": false,
          "interventionIds": [
            "4eaeb363-296d-4ccc-a973-7805e6f400bd"
          ]
        },
        "selfReliance": {
          "isCapable": false,
          "interventionIds": [
            "4eaeb363-296d-4ccc-a973-7805e6f400bd"
          ]
        }
      },
      "scopes": [
        "string"
      ],
      "location": {
        "id": "8d90101b-3f2f-462a-bbb4-1ed320d33bbe",
        "longitude": 10.7197486,
        "latitude": 59.9173985,
        "lastUpdated": "2020-04-07T17:04:26Z"
      }
    }
  ],
  "pagination": {
    "after": "MjAyMy0wNy0xOFQxMDowODowMi4zNzNa",
    "before": "MjAyMy0wNi0xNlQwOTowMzowMS4yNjJa"
  }
}
Was this section helpful?

List user batteriesBeta

GET /users/{userId}/batteries

Returns a paginated list of batteries for the given userId.

Request

Path parameters
userId string Required

ID of the User.

Query parameters
after string Optional
before string Optional
pageSize integer Optional

Default value: 50

Request example

curl --request GET \
  --url 'https://enode-api.production.enode.io/users/%7BuserId%7D/batteries?after=MjAyMy0wNy0xOFQxMDowODowMi4zNzNa&before=MjAyMy0wNy0xOFQxMDowODowMi4zNzNa&pageSize=50' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response 200

Attributes
  • data array of object

    Paginated list of batteries

    Show child attributes
    • data[].id string<uuid>

      Unique identifier for the battery object

    • data[].userId string

      The ID of the user that linked this battery.

    • data[].vendor string

      Machine-friendly name of the vendor. Use this in API requests.

      Possible enum values:

        TESLAENPHASEHUAWEISOLAREDGESMA
    • data[].lastSeen string<date-time>

      The last time Enode successfully communicated with the vendor or when the battery was initially linked.

    • data[].isReachable boolean

      Indicates whether Enode can currently access live data from the battery. If the battery is not reachable, data updates will be delayed.

    • data[].chargeState object

      Latest information about the battery. null values indicate we are unable to determine a value for the field based on the information coming from the vendor.

      Show child attributes
      • data[].chargeState.status string or null

        The power delivery state of the battery.

        Possible enum values:

          CHARGINGDISCHARGINGIDLEFAULTUNKNOWN
      • data[].chargeState.batteryCapacity number or null

        Battery capacity in kWh.

      • data[].chargeState.batteryLevel number or null

        Remaining battery charge level in percent.

      • data[].chargeState.chargeRate number or null

        The current charge rate in kW. A positive value indicates that the battery is charging.

      • data[].chargeState.dischargeLimit number or null

        Minimum charge level for a battery, expressed as a percentage. Batteries will not discharge below this user-set reserve level except in emergency power situations.

      • data[].chargeState.lastUpdated string<date-time> or null

        Time of last received charge state update

    • data[].config object
      Show child attributes
      • data[].config.operationMode string or null

        The current operation mode of the battery.

        • IMPORT_FOCUS: Prioritizes charging the battery. Draws power from the grid and any excess solar energy for charging. Leveraged energy sources depend on the configuration of the battery. Note: Focus modes target a certain battery behavior but are ultimately internal to the battery. Actual behavior might differ from the focus mode.
        • EXPORT_FOCUS: Prioritizes discharging energy stored in the battery back to the household and any excess to the grid. Grid exports often depend on local regulation and might require agreements with grid providers to be supported. Note: Focus modes target a certain battery behavior but are ultimately internal to the battery. Actual behavior might differ from the focus mode.
        • TIME_OF_USE: Maximizes energy cost savings in accordance with a user-defined schedule matching a utility rate plan. Energy may be consumed from solar, battery, or grid sources, depending on the current prices and your user's settings in the OEM app. Energy may be exported to the grid from solar or battery sources, depending on current prices and your user's settings in the OEM app.
        • SELF_RELIANCE: Minimizes household reliance on the grid. Prioritizes using own energy from solar or battery for household consumption before importing from grid. Energy may be exported to the grid from solar, depending on excess solar and your user's settings in the OEM app.

        Possible enum values:

          IMPORT_FOCUSEXPORT_FOCUSTIME_OF_USESELF_RELIANCE
      • data[].config.lastUpdated string<date-time> or null

        Time of last received configuration update

    • data[].information object

      Descriptive information about the battery

      Show child attributes
      • data[].information.id string

        Battery vendor ID

      • data[].information.brand string

        A formatted and properly cased OEM brand name, suitable for reading by humans. May contain special characters.

        Possible enum values:

          TeslaEnphaseHUAWEISolarEdgeSMA
      • data[].information.model string

        Battery model

      • data[].information.siteName string

        Name of the site, as set by the user on the device/vendor. If no user-specified name is available, we construct a fallback name using the vendor/device/model names.

      • data[].information.installationDate string<date-time>

        Battery installation date

    • data[].capabilities object

      A collection of descriptors that describe the capabilities of this specific battery

      Show child attributes
      • data[].capabilities.exportFocus object

        Supports EXPORT_FOCUS operation mode.

        Show child attributes
        • data[].capabilities.exportFocus.isCapable boolean

          The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

        • data[].capabilities.exportFocus.interventionIds array of string

          IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

      • data[].capabilities.importFocus object

        Supports IMPORT_FOCUS operation mode.

        Show child attributes
        • data[].capabilities.importFocus.isCapable boolean

          The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

        • data[].capabilities.importFocus.interventionIds array of string

          IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

      • data[].capabilities.timeOfUse object

        Supports TIME_OF_USE operation mode.

        Show child attributes
        • data[].capabilities.timeOfUse.isCapable boolean

          The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

        • data[].capabilities.timeOfUse.interventionIds array of string

          IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

      • data[].capabilities.selfReliance object

        Supports SELF_RELIANCE operation mode.

        Show child attributes
        • data[].capabilities.selfReliance.isCapable boolean

          The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

        • data[].capabilities.selfReliance.interventionIds array of string

          IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

    • data[].scopes array of string

      Scopes that the user has granted for this battery.

    • data[].location object

      Battery's GPS coordinates

      Show child attributes
      • data[].location.id string<uuid> or null

        ID of the location the battery is currently positioned at (if any).

      • data[].location.longitude number or null

        Longitude in degrees

      • data[].location.latitude number or null

        Latitude in degrees

      • data[].location.lastUpdated string<date-time> or null

        Time of last received location state update

  • pagination object

    Cursors to the pages before and after current page. See the PaginationAPI section for reference.

    Show child attributes
    • pagination.after string or null
    • pagination.before string or null

Response example

{
  "data": [
    {
      "id": "54d827e1-8355-4fed-97b5-55940d1d09ba",
      "userId": "4f6fecd0-bdae-49be-b6e8-ee442e1e3da9",
      "vendor": "TESLA",
      "lastSeen": "2020-04-07T17:04:26Z",
      "isReachable": true,
      "chargeState": {
        "status": "CHARGING",
        "batteryCapacity": 13.5,
        "batteryLevel": 80,
        "chargeRate": 4.6,
        "dischargeLimit": 20,
        "lastUpdated": "2020-04-07T17:04:26Z"
      },
      "config": {
        "operationMode": "IMPORT_FOCUS",
        "lastUpdated": "2020-04-07T17:04:26Z"
      },
      "information": {
        "id": "7deb27f8-794f-467b-855e-5c61dd9f2cb3",
        "brand": "Tesla",
        "model": "Powerwall",
        "siteName": "Powerwall Home",
        "installationDate": "2020-04-07T17:04:26Z"
      },
      "capabilities": {
        "exportFocus": {
          "isCapable": false,
          "interventionIds": [
            "4eaeb363-296d-4ccc-a973-7805e6f400bd"
          ]
        },
        "importFocus": {
          "isCapable": false,
          "interventionIds": [
            "4eaeb363-296d-4ccc-a973-7805e6f400bd"
          ]
        },
        "timeOfUse": {
          "isCapable": false,
          "interventionIds": [
            "4eaeb363-296d-4ccc-a973-7805e6f400bd"
          ]
        },
        "selfReliance": {
          "isCapable": false,
          "interventionIds": [
            "4eaeb363-296d-4ccc-a973-7805e6f400bd"
          ]
        }
      },
      "scopes": [
        "string"
      ],
      "location": {
        "id": "8d90101b-3f2f-462a-bbb4-1ed320d33bbe",
        "longitude": 10.7197486,
        "latitude": 59.9173985,
        "lastUpdated": "2020-04-07T17:04:26Z"
      }
    }
  ],
  "pagination": {
    "after": "MjAyMy0wNy0xOFQxMDowODowMi4zNzNa",
    "before": "MjAyMy0wNi0xNlQwOTowMzowMS4yNjJa"
  }
}
Was this section helpful?

Get batteryBeta

GET /batteries/{batteryId}

Request

Path parameters
batteryId string<uuid> Required

The ID of the battery to look up.

Request example

curl --request GET \
  --url https://enode-api.production.enode.io/batteries/54d827e1-8355-4fed-97b5-55940d1d09ba

Response 200

Attributes
  • id string<uuid>

    Unique identifier for the battery object

  • userId string

    The ID of the user that linked this battery.

  • vendor string

    Machine-friendly name of the vendor. Use this in API requests.

    Possible enum values:

      TESLAENPHASEHUAWEISOLAREDGESMA
  • lastSeen string<date-time>

    The last time Enode successfully communicated with the vendor or when the battery was initially linked.

  • isReachable boolean

    Indicates whether Enode can currently access live data from the battery. If the battery is not reachable, data updates will be delayed.

  • chargeState object

    Latest information about the battery. null values indicate we are unable to determine a value for the field based on the information coming from the vendor.

    Show child attributes
    • chargeState.status string or null

      The power delivery state of the battery.

      Possible enum values:

        CHARGINGDISCHARGINGIDLEFAULTUNKNOWN
    • chargeState.batteryCapacity number or null

      Battery capacity in kWh.

    • chargeState.batteryLevel number or null

      Remaining battery charge level in percent.

    • chargeState.chargeRate number or null

      The current charge rate in kW. A positive value indicates that the battery is charging.

    • chargeState.dischargeLimit number or null

      Minimum charge level for a battery, expressed as a percentage. Batteries will not discharge below this user-set reserve level except in emergency power situations.

    • chargeState.lastUpdated string<date-time> or null

      Time of last received charge state update

  • config object
    Show child attributes
    • config.operationMode string or null

      The current operation mode of the battery.

      • IMPORT_FOCUS: Prioritizes charging the battery. Draws power from the grid and any excess solar energy for charging. Leveraged energy sources depend on the configuration of the battery. Note: Focus modes target a certain battery behavior but are ultimately internal to the battery. Actual behavior might differ from the focus mode.
      • EXPORT_FOCUS: Prioritizes discharging energy stored in the battery back to the household and any excess to the grid. Grid exports often depend on local regulation and might require agreements with grid providers to be supported. Note: Focus modes target a certain battery behavior but are ultimately internal to the battery. Actual behavior might differ from the focus mode.
      • TIME_OF_USE: Maximizes energy cost savings in accordance with a user-defined schedule matching a utility rate plan. Energy may be consumed from solar, battery, or grid sources, depending on the current prices and your user's settings in the OEM app. Energy may be exported to the grid from solar or battery sources, depending on current prices and your user's settings in the OEM app.
      • SELF_RELIANCE: Minimizes household reliance on the grid. Prioritizes using own energy from solar or battery for household consumption before importing from grid. Energy may be exported to the grid from solar, depending on excess solar and your user's settings in the OEM app.

      Possible enum values:

        IMPORT_FOCUSEXPORT_FOCUSTIME_OF_USESELF_RELIANCE
    • config.lastUpdated string<date-time> or null

      Time of last received configuration update

  • information object

    Descriptive information about the battery

    Show child attributes
    • information.id string

      Battery vendor ID

    • information.brand string

      A formatted and properly cased OEM brand name, suitable for reading by humans. May contain special characters.

      Possible enum values:

        TeslaEnphaseHUAWEISolarEdgeSMA
    • information.model string

      Battery model

    • information.siteName string

      Name of the site, as set by the user on the device/vendor. If no user-specified name is available, we construct a fallback name using the vendor/device/model names.

    • information.installationDate string<date-time>

      Battery installation date

  • capabilities object

    A collection of descriptors that describe the capabilities of this specific battery

    Show child attributes
    • capabilities.exportFocus object

      Supports EXPORT_FOCUS operation mode.

      Show child attributes
      • capabilities.exportFocus.isCapable boolean

        The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

      • capabilities.exportFocus.interventionIds array of string

        IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

    • capabilities.importFocus object

      Supports IMPORT_FOCUS operation mode.

      Show child attributes
      • capabilities.importFocus.isCapable boolean

        The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

      • capabilities.importFocus.interventionIds array of string

        IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

    • capabilities.timeOfUse object

      Supports TIME_OF_USE operation mode.

      Show child attributes
      • capabilities.timeOfUse.isCapable boolean

        The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

      • capabilities.timeOfUse.interventionIds array of string

        IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

    • capabilities.selfReliance object

      Supports SELF_RELIANCE operation mode.

      Show child attributes
      • capabilities.selfReliance.isCapable boolean

        The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

      • capabilities.selfReliance.interventionIds array of string

        IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

  • scopes array of string

    Scopes that the user has granted for this battery.

  • location object

    Battery's GPS coordinates

    Show child attributes
    • location.id string<uuid> or null

      ID of the location the battery is currently positioned at (if any).

    • location.longitude number or null

      Longitude in degrees

    • location.latitude number or null

      Latitude in degrees

    • location.lastUpdated string<date-time> or null

      Time of last received location state update

Response example

{
  "id": "54d827e1-8355-4fed-97b5-55940d1d09ba",
  "userId": "4f6fecd0-bdae-49be-b6e8-ee442e1e3da9",
  "vendor": "TESLA",
  "lastSeen": "2020-04-07T17:04:26Z",
  "isReachable": true,
  "chargeState": {
    "status": "CHARGING",
    "batteryCapacity": 13.5,
    "batteryLevel": 80,
    "chargeRate": 4.6,
    "dischargeLimit": 20,
    "lastUpdated": "2020-04-07T17:04:26Z"
  },
  "config": {
    "operationMode": "IMPORT_FOCUS",
    "lastUpdated": "2020-04-07T17:04:26Z"
  },
  "information": {
    "id": "7deb27f8-794f-467b-855e-5c61dd9f2cb3",
    "brand": "Tesla",
    "model": "Powerwall",
    "siteName": "Powerwall Home",
    "installationDate": "2020-04-07T17:04:26Z"
  },
  "capabilities": {
    "exportFocus": {
      "isCapable": false,
      "interventionIds": [
        "4eaeb363-296d-4ccc-a973-7805e6f400bd"
      ]
    },
    "importFocus": {
      "isCapable": false,
      "interventionIds": [
        "4eaeb363-296d-4ccc-a973-7805e6f400bd"
      ]
    },
    "timeOfUse": {
      "isCapable": false,
      "interventionIds": [
        "4eaeb363-296d-4ccc-a973-7805e6f400bd"
      ]
    },
    "selfReliance": {
      "isCapable": false,
      "interventionIds": [
        "4eaeb363-296d-4ccc-a973-7805e6f400bd"
      ]
    }
  },
  "scopes": [
    "string"
  ],
  "location": {
    "id": "8d90101b-3f2f-462a-bbb4-1ed320d33bbe",
    "longitude": 10.7197486,
    "latitude": 59.9173985,
    "lastUpdated": "2020-04-07T17:04:26Z"
  }
}
Was this section helpful?

Set operation mode for batteryBeta

POST /batteries/{batteryId}/operation-mode

Request an operationMode change for a battery. This request creates an Action that will retry until the battery's operationMode matches the expected value. The Action must complete before any further commands can be sent to the battery. Only one Action can be active for a specific battery at a time. If a new Action is created, the previous Action will be automatically cancelled and transitioned to the CANCELLED state. Regardless of operation mode, the battery's charge limit will not fall below dischargeLimit except in emergency power situations. Transitions can be tracked via the user:vendor-action:updated webhook event or Get Operation Mode ActionAPI.

Request

Path parameters
batteryId string<uuid> Required

The ID of the battery being targeted.

Attributes
  • operationMode string Required

    Desired operation mode of the battery.

    • IMPORT_FOCUS: Prioritizes charging the battery. Draws power from the grid and any excess solar energy for charging. Leveraged energy sources depend on the configuration of the battery. Note: Focus modes target a certain battery behavior but are ultimately internal to the battery. Actual behavior might differ from the focus mode.
    • EXPORT_FOCUS: Prioritizes discharging energy stored in the battery back to the household and any excess to the grid. Grid exports often depend on local regulation and might require agreements with grid providers to be supported. Note: Focus modes target a certain battery behavior but are ultimately internal to the battery. Actual behavior might differ from the focus mode.
    • TIME_OF_USE: Maximizes energy cost savings in accordance with a user-defined schedule matching a utility rate plan. Energy may be consumed from solar, battery, or grid sources, depending on the current prices and your user's settings in the OEM app. Energy may be exported to the grid from solar or battery sources, depending on current prices and your user's settings in the OEM app.
    • SELF_RELIANCE: Minimizes household reliance on the grid. Prioritizes using own energy from solar or battery for household consumption before importing from grid. Energy may be exported to the grid from solar, depending on excess solar and your user's settings in the OEM app.

    Possible enum values:

      IMPORT_FOCUSEXPORT_FOCUSTIME_OF_USESELF_RELIANCE

Request example

curl --request POST \
  --url https://enode-api.production.enode.io/batteries/54d827e1-8355-4fed-97b5-55940d1d09ba/operation-mode \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"operationMode":"IMPORT_FOCUS"}'

Response 200

Attributes
  • id string<uuid>

    The ID of the action.

  • userId string

    The ID of the user that owns the target of this action.

  • createdAt string<date-time>

    Time when this action was created

  • updatedAt string<date-time>

    Time when this action was last updated

  • completedAt string<date-time> or null

    Time when the action transitioned to a non-pending state.

  • state string

    The real-time status of an action executed on a target.

    • PENDING: The initial state. Enode is actively sending commands and monitoring the target for changes.
    • CONFIRMED: Successful transition of the target to the desired state.
    • FAILED: The target did not respond to the action before timing out. Enode has ceased sending additional commands.
    • CANCELLED: A required precondition was not met during the action's timeout window or another action has been sent to the target, overriding this one.

    Possible enum values:

      PENDINGCONFIRMEDFAILEDCANCELLED
  • targetId string

    ID of the battery which this action is controlling.

  • targetType string

    Possible enum values:

      battery
  • targetState object

    Target battery operation mode

    Show child attributes
    • targetState.operationMode string

      Desired operation mode of the battery.

      • IMPORT_FOCUS: Prioritizes charging the battery. Draws power from the grid and any excess solar energy for charging. Leveraged energy sources depend on the configuration of the battery. Note: Focus modes target a certain battery behavior but are ultimately internal to the battery. Actual behavior might differ from the focus mode.
      • EXPORT_FOCUS: Prioritizes discharging energy stored in the battery back to the household and any excess to the grid. Grid exports often depend on local regulation and might require agreements with grid providers to be supported. Note: Focus modes target a certain battery behavior but are ultimately internal to the battery. Actual behavior might differ from the focus mode.
      • TIME_OF_USE: Maximizes energy cost savings in accordance with a user-defined schedule matching a utility rate plan. Energy may be consumed from solar, battery, or grid sources, depending on the current prices and your user's settings in the OEM app. Energy may be exported to the grid from solar or battery sources, depending on current prices and your user's settings in the OEM app.
      • SELF_RELIANCE: Minimizes household reliance on the grid. Prioritizes using own energy from solar or battery for household consumption before importing from grid. Energy may be exported to the grid from solar, depending on excess solar and your user's settings in the OEM app.

      Possible enum values:

        IMPORT_FOCUSEXPORT_FOCUSTIME_OF_USESELF_RELIANCE

Response example

{
  "id": "4eaeb363-296d-4ccc-a973-7805e6f400bd",
  "userId": "d5bd4771-864e-4ae5-b913-dfb5cdcd5772",
  "createdAt": "2020-04-07T17:04:26Z",
  "updatedAt": "2020-04-07T17:04:26Z",
  "completedAt": "2020-04-07T17:04:26Z",
  "state": "PENDING",
  "targetId": "ac03a513-5494-4e1c-9dd7-2a29dc024312",
  "targetType": "battery",
  "targetState": {
    "operationMode": "IMPORT_FOCUS"
  }
}

Response 400

A precondition check failed that is unlikely to change within the action's timeout window. This occurs if the battery cannot perform the action.

Attributes
  • type string

    A URI reference that identifies the problem type.

  • title string

    A short, human-readable summary of the problem type.

  • detail string

    A human-readable explanation specific to this occurrence of the problem.

Response example

{
  "type": "https://developers.enode.com/api/problems/not-found",
  "title": "Not Found",
  "detail": "The requested asset wasn't found."
}
Was this section helpful?

Get operation mode actionBeta

GET /batteries/actions/{actionId}

Returns the current state of the requested Action.

Request

Path parameters
actionId string<uuid> Required

ID of the Action.

Request example

curl --request GET \
  --url https://enode-api.production.enode.io/batteries/actions/4eaeb363-296d-4ccc-a973-7805e6f400bd \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response 200

Attributes
  • id string<uuid>

    The ID of the action.

  • userId string

    The ID of the user that owns the target of this action.

  • createdAt string<date-time>

    Time when this action was created

  • updatedAt string<date-time>

    Time when this action was last updated

  • completedAt string<date-time> or null

    Time when the action transitioned to a non-pending state.

  • state string

    The real-time status of an action executed on a target.

    • PENDING: The initial state. Enode is actively sending commands and monitoring the target for changes.
    • CONFIRMED: Successful transition of the target to the desired state.
    • FAILED: The target did not respond to the action before timing out. Enode has ceased sending additional commands.
    • CANCELLED: A required precondition was not met during the action's timeout window or another action has been sent to the target, overriding this one.

    Possible enum values:

      PENDINGCONFIRMEDFAILEDCANCELLED
  • targetId string

    ID of the battery which this action is controlling.

  • targetType string

    Possible enum values:

      battery
  • targetState object

    Target battery operation mode

    Show child attributes
    • targetState.operationMode string

      Desired operation mode of the battery.

      • IMPORT_FOCUS: Prioritizes charging the battery. Draws power from the grid and any excess solar energy for charging. Leveraged energy sources depend on the configuration of the battery. Note: Focus modes target a certain battery behavior but are ultimately internal to the battery. Actual behavior might differ from the focus mode.
      • EXPORT_FOCUS: Prioritizes discharging energy stored in the battery back to the household and any excess to the grid. Grid exports often depend on local regulation and might require agreements with grid providers to be supported. Note: Focus modes target a certain battery behavior but are ultimately internal to the battery. Actual behavior might differ from the focus mode.
      • TIME_OF_USE: Maximizes energy cost savings in accordance with a user-defined schedule matching a utility rate plan. Energy may be consumed from solar, battery, or grid sources, depending on the current prices and your user's settings in the OEM app. Energy may be exported to the grid from solar or battery sources, depending on current prices and your user's settings in the OEM app.
      • SELF_RELIANCE: Minimizes household reliance on the grid. Prioritizes using own energy from solar or battery for household consumption before importing from grid. Energy may be exported to the grid from solar, depending on excess solar and your user's settings in the OEM app.

      Possible enum values:

        IMPORT_FOCUSEXPORT_FOCUSTIME_OF_USESELF_RELIANCE

Response example

{
  "id": "4eaeb363-296d-4ccc-a973-7805e6f400bd",
  "userId": "d5bd4771-864e-4ae5-b913-dfb5cdcd5772",
  "createdAt": "2020-04-07T17:04:26Z",
  "updatedAt": "2020-04-07T17:04:26Z",
  "completedAt": "2020-04-07T17:04:26Z",
  "state": "PENDING",
  "targetId": "ac03a513-5494-4e1c-9dd7-2a29dc024312",
  "targetType": "battery",
  "targetState": {
    "operationMode": "IMPORT_FOCUS"
  }
}

Response 404

Action not found.

Was this section helpful?

Cancel battery actionBeta

POST /batteries/actions/{actionId}/cancel

Cancels a pending battery Action, halting any further attempts by Enode to execute it.

Note: This only updates the Action's status to CANCELLED within Enode and does not reflect a change in the vendor's cloud. Thus any pending Action in the vendor's cloud might still be executed.

Request

Path parameters
actionId string<uuid> Required

ID of the Action.

Request example

curl --request POST \
  --url https://enode-api.production.enode.io/batteries/actions/4eaeb363-296d-4ccc-a973-7805e6f400bd/cancel \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response 200

Attributes
  • id string<uuid>

    The ID of the action.

  • userId string

    The ID of the user that owns the target of this action.

  • createdAt string<date-time>

    Time when this action was created

  • updatedAt string<date-time>

    Time when this action was last updated

  • completedAt string<date-time> or null

    Time when the action transitioned to a non-pending state.

  • state string

    The real-time status of an action executed on a target.

    • PENDING: The initial state. Enode is actively sending commands and monitoring the target for changes.
    • CONFIRMED: Successful transition of the target to the desired state.
    • FAILED: The target did not respond to the action before timing out. Enode has ceased sending additional commands.
    • CANCELLED: A required precondition was not met during the action's timeout window or another action has been sent to the target, overriding this one.

    Possible enum values:

      PENDINGCONFIRMEDFAILEDCANCELLED
  • targetId string

    ID of the battery which this action is controlling.

  • targetType string

    Possible enum values:

      battery
  • targetState object

    Target battery operation mode

    Show child attributes
    • targetState.operationMode string

      Desired operation mode of the battery.

      • IMPORT_FOCUS: Prioritizes charging the battery. Draws power from the grid and any excess solar energy for charging. Leveraged energy sources depend on the configuration of the battery. Note: Focus modes target a certain battery behavior but are ultimately internal to the battery. Actual behavior might differ from the focus mode.
      • EXPORT_FOCUS: Prioritizes discharging energy stored in the battery back to the household and any excess to the grid. Grid exports often depend on local regulation and might require agreements with grid providers to be supported. Note: Focus modes target a certain battery behavior but are ultimately internal to the battery. Actual behavior might differ from the focus mode.
      • TIME_OF_USE: Maximizes energy cost savings in accordance with a user-defined schedule matching a utility rate plan. Energy may be consumed from solar, battery, or grid sources, depending on the current prices and your user's settings in the OEM app. Energy may be exported to the grid from solar or battery sources, depending on current prices and your user's settings in the OEM app.
      • SELF_RELIANCE: Minimizes household reliance on the grid. Prioritizes using own energy from solar or battery for household consumption before importing from grid. Energy may be exported to the grid from solar, depending on excess solar and your user's settings in the OEM app.

      Possible enum values:

        IMPORT_FOCUSEXPORT_FOCUSTIME_OF_USESELF_RELIANCE

Response example

{
  "id": "4eaeb363-296d-4ccc-a973-7805e6f400bd",
  "userId": "d5bd4771-864e-4ae5-b913-dfb5cdcd5772",
  "createdAt": "2020-04-07T17:04:26Z",
  "updatedAt": "2020-04-07T17:04:26Z",
  "completedAt": "2020-04-07T17:04:26Z",
  "state": "PENDING",
  "targetId": "ac03a513-5494-4e1c-9dd7-2a29dc024312",
  "targetType": "battery",
  "targetState": {
    "operationMode": "IMPORT_FOCUS"
  }
}

Response 404

Action not found.

Response 409

Action already in a resolved state and can therefore not be cancelled.

Attributes
  • id string<uuid>

    The ID of the action.

  • userId string

    The ID of the user that owns the target of this action.

  • createdAt string<date-time>

    Time when this action was created

  • updatedAt string<date-time>

    Time when this action was last updated

  • completedAt string<date-time> or null

    Time when the action transitioned to a non-pending state.

  • targetId string

    ID of the battery which this action is controlling.

  • targetType string

    Possible enum values:

      battery
  • targetState object

    Target battery operation mode

    Show child attributes
    • targetState.operationMode string

      Desired operation mode of the battery.

      • IMPORT_FOCUS: Prioritizes charging the battery. Draws power from the grid and any excess solar energy for charging. Leveraged energy sources depend on the configuration of the battery. Note: Focus modes target a certain battery behavior but are ultimately internal to the battery. Actual behavior might differ from the focus mode.
      • EXPORT_FOCUS: Prioritizes discharging energy stored in the battery back to the household and any excess to the grid. Grid exports often depend on local regulation and might require agreements with grid providers to be supported. Note: Focus modes target a certain battery behavior but are ultimately internal to the battery. Actual behavior might differ from the focus mode.
      • TIME_OF_USE: Maximizes energy cost savings in accordance with a user-defined schedule matching a utility rate plan. Energy may be consumed from solar, battery, or grid sources, depending on the current prices and your user's settings in the OEM app. Energy may be exported to the grid from solar or battery sources, depending on current prices and your user's settings in the OEM app.
      • SELF_RELIANCE: Minimizes household reliance on the grid. Prioritizes using own energy from solar or battery for household consumption before importing from grid. Energy may be exported to the grid from solar, depending on excess solar and your user's settings in the OEM app.

      Possible enum values:

        IMPORT_FOCUSEXPORT_FOCUSTIME_OF_USESELF_RELIANCE
  • state string

    The real-time status of an action executed on a target.

    • CONFIRMED: Successful transition of the target to the desired state.
    • FAILED: The target did not respond to the action before timing out. Enode has ceased sending additional commands.
    • CANCELLED: A required precondition was not met during the action's timeout window or another action has been sent to the target, overriding this one.

    Possible enum values:

      CONFIRMEDFAILEDCANCELLED

Response example

{
  "id": "4eaeb363-296d-4ccc-a973-7805e6f400bd",
  "userId": "d5bd4771-864e-4ae5-b913-dfb5cdcd5772",
  "createdAt": "2020-04-07T17:04:26Z",
  "updatedAt": "2020-04-07T17:04:26Z",
  "completedAt": "2020-04-07T17:04:26Z",
  "targetId": "ac03a513-5494-4e1c-9dd7-2a29dc024312",
  "targetType": "battery",
  "targetState": {
    "operationMode": "IMPORT_FOCUS"
  },
  "state": "CONFIRMED"
}
Was this section helpful?

Refresh battery dataBeta

POST /batteries/{batteryId}/refresh-hint

Use this endpoint to initiate an expedited data refresh for the specified battery.

Note: The Enode platform keeps data automatically up-to-date and detects changes in the OEM APIs within seconds to a few minutes. We change the refresh interval dynamically based on a number of heuristics. This ensures we find the best trade-off between the stability of the connection to the OEM and freshness of the data.
This method overrides most of our heuristics and should therefore be used with caution. You may use it when you have a strong reason to believe the data might be stale.

Request

Path parameters
batteryId string<uuid> Required

The ID of the battery being targeted.

Request example

curl --request POST \
  --url https://enode-api.production.enode.io/batteries/54d827e1-8355-4fed-97b5-55940d1d09ba/refresh-hint \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response 204

Refresh hint registered successfully.

Response 404

The specified battery was not found.

Was this section helpful?

Chargers

EV Chargers provide charging data and can be controlled via Control ChargingAPI and Schedules

List chargers

GET /chargers

Returns a paginated list of all Chargers.

Request

Query parameters
after string Optional
before string Optional
pageSize integer Optional

Default value: 50

Request example

curl --request GET \
  --url 'https://enode-api.production.enode.io/chargers?after=MjAyMy0wNy0xOFQxMDowODowMi4zNzNa&before=MjAyMy0wNy0xOFQxMDowODowMi4zNzNa&pageSize=50' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response 200

Attributes
  • data array of object

    Paginated list of chargers

    Show child attributes
    • data[].id string

      Charger ID

    • data[].userId string

      The ID of the user that linked this charger.

    • data[].vendor string

      Machine-friendly name of the vendor. Use this in API requests.

      Possible enum values:

        ZAPTECEASEEWALLBOXEOCHARGEAMPSEVBOXGOEFRONIUSCHARGEPOINTENELXTESLAOHMEGAROSCHNEIDERPODPOINT
    • data[].lastSeen string<date-time>

      The last time Enode communicated with the charger.

    • data[].isReachable boolean

      Indicates whether Enode can currently access live data from the charger. If the charger is not reachable, data updates will be delayed.

    • data[].chargeState object

      Latest information about the charger. null values indicate we are unable to determine a value for the field based on the information coming from the vendor.

      Show child attributes
      • data[].chargeState.isPluggedIn boolean or null

        Indicates whether the charger has a vehicle plugged into it (regardless of whether that vehicle is actually charging)

      • data[].chargeState.isCharging boolean or null

        Indicates whether the charger is currently delivering power to the vehicle and actively charging its battery.

      • data[].chargeState.chargeRate number or null

        The current charge rate in kW.

        This property is only available when the charger is actively charging a vehicle, and is null any other time.

      • data[].chargeState.lastUpdated string<date-time> or null

        Time of latest charge state update

      • data[].chargeState.maxCurrent number or null

        Desired max current in amperes, if set

      • data[].chargeState.powerDeliveryState string

        The current state of power delivery between the vehicle and charger.

        • UNKNOWN: The state of power delivery is currently unknown.
        • UNPLUGGED: The vehicle is not connected to the charger.
        • PLUGGED_IN:INITIALIZING: The charging station is preparing to deliver power to the vehicle. It is expected for this state to shortly transition into PLUGGED_IN:CHARGING.
        • PLUGGED_IN:CHARGING: The charger is actively delivering power to the vehicle, causing the battery level to increase.
        • PLUGGED_IN:STOPPED: The vehicle is plugged in, but the charger has been stopped. It is possible to transition into a charging state by sending a start command.
        • PLUGGED_IN:NO_POWER: The charger attempted to initialize charging, however no external power was accepted by the vehicle. It is not possible to transition into a charging state with a remote command until there is some user intervention to resolve the issue.
        • PLUGGED_IN:FAULT: A malfunction in the charging process is preventing power from being delivered. Possible causes include a charging cable not being properly locked, extreme temperatures, or malfunctions in either the charging station or the vehicle's internal system. It is not possible to transition into a charging state with a remote command until there is some user intervention to resolve the issue.
        • PLUGGED_IN:DISCHARGING: The charger is actively discharging by giving power to the home/grid, causing the battery level to decrease.

        Possible enum values:

          UNKNOWNUNPLUGGEDPLUGGED_IN:INITIALIZINGPLUGGED_IN:CHARGINGPLUGGED_IN:STOPPEDPLUGGED_IN:NO_POWERPLUGGED_IN:FAULT
    • data[].capabilities object

      A collection of descriptors that describe the capabilities of this specific charger

      Show child attributes
      • data[].capabilities.information object

        Full availability of information data.

        Show child attributes
        • data[].capabilities.information.isCapable boolean

          The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

        • data[].capabilities.information.interventionIds array of string

          IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

      • data[].capabilities.chargeState object

        Full availability of chargeState data.

        Show child attributes
        • data[].capabilities.chargeState.isCapable boolean

          The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

        • data[].capabilities.chargeState.interventionIds array of string

          IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

      • data[].capabilities.startCharging object

        Supports START charging command.

        Show child attributes
        • data[].capabilities.startCharging.isCapable boolean

          The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

        • data[].capabilities.startCharging.interventionIds array of string

          IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

      • data[].capabilities.stopCharging object

        Supports STOP charging command.

        Show child attributes
        • data[].capabilities.stopCharging.isCapable boolean

          The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

        • data[].capabilities.stopCharging.interventionIds array of string

          IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

      • data[].capabilities.setMaxCurrent object

        Ability to set the max charge rate.

        Show child attributes
        • data[].capabilities.setMaxCurrent.isCapable boolean

          The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

        • data[].capabilities.setMaxCurrent.interventionIds array of string

          IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

    • data[].scopes array of string

      Scopes that the user has granted for this charger.

    • data[].information object

      Descriptive information about the Charger

      Show child attributes
      • data[].information.brand string

        Charger brand

        Possible enum values:

          ZaptecEaseeWallboxEOEVBoxCharge Ampsgo-eFroniusChargePointEnel XTeslaOhmeGaroSchneider ElectricPod Point
      • data[].information.model string

        Charger model

      • data[].information.year number or null

        Charger production year

    • data[].location object
      Show child attributes
      • data[].location.id string<uuid> or null

        ID of the location the charger is currently positioned at (if any).

      • data[].location.lastUpdated string<date-time> or null

        Time of last received location state update

  • pagination object

    Cursors to the pages before and after current page. See the PaginationAPI section for reference.

    Show child attributes
    • pagination.after string or null
    • pagination.before string or null

Response example

{
  "data": [
    {
      "information": {
        "brand": "Zaptec",
        "model": "ZAPTEC PRO",
        "year": null
      },
      "location": {
        "id": "2211e263-d6d4-d6d4-d6d4-dbdd77ec82b6",
        "lastUpdated": "2023-03-21T16:39:20.000Z"
      },
      "id": "2211e263-0362-4235-83f4-887bdf3ee414",
      "userId": "d381faac-5283-44a1-9eb1-36cab2ace670",
      "vendor": "ZAPTEC",
      "lastSeen": "2023-03-21T21:08:27.596Z",
      "isReachable": true,
      "chargeState": {
        "isPluggedIn": true,
        "isCharging": true,
        "chargeRate": 6.939,
        "lastUpdated": "2023-03-21T16:39:20.000Z",
        "maxCurrent": 16,
        "powerDeliveryState": "PLUGGED_IN:CHARGING"
      },
      "capabilities": {
        "information": {
          "isCapable": true,
          "interventionIds": []
        },
        "chargeState": {
          "isCapable": true,
          "interventionIds": []
        },
        "startCharging": {
          "isCapable": true,
          "interventionIds": []
        },
        "stopCharging": {
          "isCapable": true,
          "interventionIds": []
        },
        "setMaxCurrent": {
          "isCapable": false,
          "interventionIds": [
            "dbdd77ec82b6-d6d4-d6d4-d6d4-dbdd77ec82b6"
          ]
        }
      },
      "scopes": [
        "charger:control:charging",
        "charger:read:data"
      ]
    }
  ],
  "pagination": {
    "after": "MjAyMy0wNy0xOFQxMDowODowMi4zNzNa",
    "before": "MjAyMy0wNi0xNlQwOTowMzowMS4yNjJa"
  }
}
Was this section helpful?

List user chargers

GET /users/{userId}/chargers

Returns a paginated list of chargers for the given userId.

Request

Path parameters
userId string Required

ID of the User.

Query parameters
after string Optional
before string Optional
pageSize integer Optional

Default value: 50

Request example

curl --request GET \
  --url 'https://enode-api.production.enode.io/users/%7BuserId%7D/chargers?after=MjAyMy0wNy0xOFQxMDowODowMi4zNzNa&before=MjAyMy0wNy0xOFQxMDowODowMi4zNzNa&pageSize=50' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response 200

Attributes
  • data array of object

    Paginated list of chargers

    Show child attributes
    • data[].id string

      Charger ID

    • data[].userId string

      The ID of the user that linked this charger.

    • data[].vendor string

      Machine-friendly name of the vendor. Use this in API requests.

      Possible enum values:

        ZAPTECEASEEWALLBOXEOCHARGEAMPSEVBOXGOEFRONIUSCHARGEPOINTENELXTESLAOHMEGAROSCHNEIDERPODPOINT
    • data[].lastSeen string<date-time>

      The last time Enode communicated with the charger.

    • data[].isReachable boolean

      Indicates whether Enode can currently access live data from the charger. If the charger is not reachable, data updates will be delayed.

    • data[].chargeState object

      Latest information about the charger. null values indicate we are unable to determine a value for the field based on the information coming from the vendor.

      Show child attributes
      • data[].chargeState.isPluggedIn boolean or null

        Indicates whether the charger has a vehicle plugged into it (regardless of whether that vehicle is actually charging)

      • data[].chargeState.isCharging boolean or null

        Indicates whether the charger is currently delivering power to the vehicle and actively charging its battery.

      • data[].chargeState.chargeRate number or null

        The current charge rate in kW.

        This property is only available when the charger is actively charging a vehicle, and is null any other time.

      • data[].chargeState.lastUpdated string<date-time> or null

        Time of latest charge state update

      • data[].chargeState.maxCurrent number or null

        Desired max current in amperes, if set

      • data[].chargeState.powerDeliveryState string

        The current state of power delivery between the vehicle and charger.

        • UNKNOWN: The state of power delivery is currently unknown.
        • UNPLUGGED: The vehicle is not connected to the charger.
        • PLUGGED_IN:INITIALIZING: The charging station is preparing to deliver power to the vehicle. It is expected for this state to shortly transition into PLUGGED_IN:CHARGING.
        • PLUGGED_IN:CHARGING: The charger is actively delivering power to the vehicle, causing the battery level to increase.
        • PLUGGED_IN:STOPPED: The vehicle is plugged in, but the charger has been stopped. It is possible to transition into a charging state by sending a start command.
        • PLUGGED_IN:NO_POWER: The charger attempted to initialize charging, however no external power was accepted by the vehicle. It is not possible to transition into a charging state with a remote command until there is some user intervention to resolve the issue.
        • PLUGGED_IN:FAULT: A malfunction in the charging process is preventing power from being delivered. Possible causes include a charging cable not being properly locked, extreme temperatures, or malfunctions in either the charging station or the vehicle's internal system. It is not possible to transition into a charging state with a remote command until there is some user intervention to resolve the issue.
        • PLUGGED_IN:DISCHARGING: The charger is actively discharging by giving power to the home/grid, causing the battery level to decrease.

        Possible enum values:

          UNKNOWNUNPLUGGEDPLUGGED_IN:INITIALIZINGPLUGGED_IN:CHARGINGPLUGGED_IN:STOPPEDPLUGGED_IN:NO_POWERPLUGGED_IN:FAULT
    • data[].capabilities object

      A collection of descriptors that describe the capabilities of this specific charger

      Show child attributes
      • data[].capabilities.information object

        Full availability of information data.

        Show child attributes
        • data[].capabilities.information.isCapable boolean

          The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

        • data[].capabilities.information.interventionIds array of string

          IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

      • data[].capabilities.chargeState object

        Full availability of chargeState data.

        Show child attributes
        • data[].capabilities.chargeState.isCapable boolean

          The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

        • data[].capabilities.chargeState.interventionIds array of string

          IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

      • data[].capabilities.startCharging object

        Supports START charging command.

        Show child attributes
        • data[].capabilities.startCharging.isCapable boolean

          The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

        • data[].capabilities.startCharging.interventionIds array of string

          IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

      • data[].capabilities.stopCharging object

        Supports STOP charging command.

        Show child attributes
        • data[].capabilities.stopCharging.isCapable boolean

          The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

        • data[].capabilities.stopCharging.interventionIds array of string

          IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

      • data[].capabilities.setMaxCurrent object

        Ability to set the max charge rate.

        Show child attributes
        • data[].capabilities.setMaxCurrent.isCapable boolean

          The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

        • data[].capabilities.setMaxCurrent.interventionIds array of string

          IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

    • data[].scopes array of string

      Scopes that the user has granted for this charger.

    • data[].information object

      Descriptive information about the Charger

      Show child attributes
      • data[].information.brand string

        Charger brand

        Possible enum values:

          ZaptecEaseeWallboxEOEVBoxCharge Ampsgo-eFroniusChargePointEnel XTeslaOhmeGaroSchneider ElectricPod Point
      • data[].information.model string

        Charger model

      • data[].information.year number or null

        Charger production year

    • data[].location object
      Show child attributes
      • data[].location.id string<uuid> or null

        ID of the location the charger is currently positioned at (if any).

      • data[].location.lastUpdated string<date-time> or null

        Time of last received location state update

  • pagination object

    Cursors to the pages before and after current page. See the PaginationAPI section for reference.

    Show child attributes
    • pagination.after string or null
    • pagination.before string or null

Response example

{
  "data": [
    {
      "information": {
        "brand": "Zaptec",
        "model": "ZAPTEC PRO",
        "year": null
      },
      "location": {
        "id": "2211e263-d6d4-d6d4-d6d4-dbdd77ec82b6",
        "lastUpdated": "2023-03-21T16:39:20.000Z"
      },
      "id": "2211e263-0362-4235-83f4-887bdf3ee414",
      "userId": "d381faac-5283-44a1-9eb1-36cab2ace670",
      "vendor": "ZAPTEC",
      "lastSeen": "2023-03-21T21:08:27.596Z",
      "isReachable": true,
      "chargeState": {
        "isPluggedIn": true,
        "isCharging": true,
        "chargeRate": 6.939,
        "lastUpdated": "2023-03-21T16:39:20.000Z",
        "maxCurrent": 16,
        "powerDeliveryState": "PLUGGED_IN:CHARGING"
      },
      "capabilities": {
        "information": {
          "isCapable": true,
          "interventionIds": []
        },
        "chargeState": {
          "isCapable": true,
          "interventionIds": []
        },
        "startCharging": {
          "isCapable": true,
          "interventionIds": []
        },
        "stopCharging": {
          "isCapable": true,
          "interventionIds": []
        },
        "setMaxCurrent": {
          "isCapable": false,
          "interventionIds": [
            "dbdd77ec82b6-d6d4-d6d4-d6d4-dbdd77ec82b6"
          ]
        }
      },
      "scopes": [
        "charger:control:charging",
        "charger:read:data"
      ]
    }
  ],
  "pagination": {
    "after": "MjAyMy0wNy0xOFQxMDowODowMi4zNzNa",
    "before": "MjAyMy0wNi0xNlQwOTowMzowMS4yNjJa"
  }
}
Was this section helpful?

Get charger

GET /chargers/{chargerId}

Request

Path parameters
chargerId string Required

ID of the Charger.

Request example

curl --request GET \
  --url https://enode-api.production.enode.io/chargers/ad84e742-0f46-4cf4-b0db-7d890f8f23f5 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response 200

Attributes
  • id string

    Charger ID

  • userId string

    The ID of the user that linked this charger.

  • vendor string

    Machine-friendly name of the vendor. Use this in API requests.

    Possible enum values:

      ZAPTECEASEEWALLBOXEOCHARGEAMPSEVBOXGOEFRONIUSCHARGEPOINTENELXTESLAOHMEGAROSCHNEIDERPODPOINT
  • lastSeen string<date-time>

    The last time Enode communicated with the charger.

  • isReachable boolean

    Indicates whether Enode can currently access live data from the charger. If the charger is not reachable, data updates will be delayed.

  • chargeState object

    Latest information about the charger. null values indicate we are unable to determine a value for the field based on the information coming from the vendor.

    Show child attributes
    • chargeState.isPluggedIn boolean or null

      Indicates whether the charger has a vehicle plugged into it (regardless of whether that vehicle is actually charging)

    • chargeState.isCharging boolean or null

      Indicates whether the charger is currently delivering power to the vehicle and actively charging its battery.

    • chargeState.chargeRate number or null

      The current charge rate in kW.

      This property is only available when the charger is actively charging a vehicle, and is null any other time.

    • chargeState.lastUpdated string<date-time> or null

      Time of latest charge state update

    • chargeState.maxCurrent number or null

      Desired max current in amperes, if set

    • chargeState.powerDeliveryState string

      The current state of power delivery between the vehicle and charger.

      • UNKNOWN: The state of power delivery is currently unknown.
      • UNPLUGGED: The vehicle is not connected to the charger.
      • PLUGGED_IN:INITIALIZING: The charging station is preparing to deliver power to the vehicle. It is expected for this state to shortly transition into PLUGGED_IN:CHARGING.
      • PLUGGED_IN:CHARGING: The charger is actively delivering power to the vehicle, causing the battery level to increase.
      • PLUGGED_IN:STOPPED: The vehicle is plugged in, but the charger has been stopped. It is possible to transition into a charging state by sending a start command.
      • PLUGGED_IN:NO_POWER: The charger attempted to initialize charging, however no external power was accepted by the vehicle. It is not possible to transition into a charging state with a remote command until there is some user intervention to resolve the issue.
      • PLUGGED_IN:FAULT: A malfunction in the charging process is preventing power from being delivered. Possible causes include a charging cable not being properly locked, extreme temperatures, or malfunctions in either the charging station or the vehicle's internal system. It is not possible to transition into a charging state with a remote command until there is some user intervention to resolve the issue.
      • PLUGGED_IN:DISCHARGING: The charger is actively discharging by giving power to the home/grid, causing the battery level to decrease.

      Possible enum values:

        UNKNOWNUNPLUGGEDPLUGGED_IN:INITIALIZINGPLUGGED_IN:CHARGINGPLUGGED_IN:STOPPEDPLUGGED_IN:NO_POWERPLUGGED_IN:FAULT
  • capabilities object

    A collection of descriptors that describe the capabilities of this specific charger

    Show child attributes
    • capabilities.information object

      Full availability of information data.

      Show child attributes
      • capabilities.information.isCapable boolean

        The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

      • capabilities.information.interventionIds array of string

        IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

    • capabilities.chargeState object

      Full availability of chargeState data.

      Show child attributes
      • capabilities.chargeState.isCapable boolean

        The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

      • capabilities.chargeState.interventionIds array of string

        IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

    • capabilities.startCharging object

      Supports START charging command.

      Show child attributes
      • capabilities.startCharging.isCapable boolean

        The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

      • capabilities.startCharging.interventionIds array of string

        IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

    • capabilities.stopCharging object

      Supports STOP charging command.

      Show child attributes
      • capabilities.stopCharging.isCapable boolean

        The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

      • capabilities.stopCharging.interventionIds array of string

        IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

    • capabilities.setMaxCurrent object

      Ability to set the max charge rate.

      Show child attributes
      • capabilities.setMaxCurrent.isCapable boolean

        The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

      • capabilities.setMaxCurrent.interventionIds array of string

        IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

  • scopes array of string

    Scopes that the user has granted for this charger.

  • information object

    Descriptive information about the Charger

    Show child attributes
    • information.brand string

      Charger brand

      Possible enum values:

        ZaptecEaseeWallboxEOEVBoxCharge Ampsgo-eFroniusChargePointEnel XTeslaOhmeGaroSchneider ElectricPod Point
    • information.model string

      Charger model

    • information.year number or null

      Charger production year

  • location object
    Show child attributes
    • location.id string<uuid> or null

      ID of the location the charger is currently positioned at (if any).

    • location.lastUpdated string<date-time> or null

      Time of last received location state update

Response example

{
  "information": {
    "brand": "Zaptec",
    "model": "ZAPTEC PRO",
    "year": null
  },
  "location": {
    "id": "2211e263-d6d4-d6d4-d6d4-dbdd77ec82b6",
    "lastUpdated": "2023-03-21T16:39:20.000Z"
  },
  "id": "2211e263-0362-4235-83f4-887bdf3ee414",
  "userId": "d381faac-5283-44a1-9eb1-36cab2ace670",
  "vendor": "ZAPTEC",
  "lastSeen": "2023-03-21T21:08:27.596Z",
  "isReachable": true,
  "chargeState": {
    "isPluggedIn": true,
    "isCharging": true,
    "chargeRate": 6.939,
    "lastUpdated": "2023-03-21T16:39:20.000Z",
    "maxCurrent": 16,
    "powerDeliveryState": "PLUGGED_IN:CHARGING"
  },
  "capabilities": {
    "information": {
      "isCapable": true,
      "interventionIds": []
    },
    "chargeState": {
      "isCapable": true,
      "interventionIds": []
    },
    "startCharging": {
      "isCapable": true,
      "interventionIds": []
    },
    "stopCharging": {
      "isCapable": true,
      "interventionIds": []
    },
    "setMaxCurrent": {
      "isCapable": false,
      "interventionIds": [
        "dbdd77ec82b6-d6d4-d6d4-d6d4-dbdd77ec82b6"
      ]
    }
  },
  "scopes": [
    "charger:control:charging",
    "charger:read:data"
  ]
}
Was this section helpful?

Update chargerBeta

PUT /chargers/{chargerId}

Update the locationId field on a Charger.

Request

Path parameters
chargerId string Required

ID of the Charger.

Attributes
  • locationId string<uuid> or null Required

Request example

curl --request PUT \
  --url https://enode-api.production.enode.io/chargers/ad84e742-0f46-4cf4-b0db-7d890f8f23f5 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"locationId":"4eaeb363-296d-4ccc-a973-7805e6f400bd"}'

Response 200

Attributes
  • id string

    Charger ID

  • userId string

    The ID of the user that linked this charger.

  • vendor string

    Machine-friendly name of the vendor. Use this in API requests.

    Possible enum values:

      ZAPTECEASEEWALLBOXEOCHARGEAMPSEVBOXGOEFRONIUSCHARGEPOINTENELXTESLAOHMEGAROSCHNEIDERPODPOINT
  • lastSeen string<date-time>

    The last time Enode communicated with the charger.

  • isReachable boolean

    Indicates whether Enode can currently access live data from the charger. If the charger is not reachable, data updates will be delayed.

  • chargeState object

    Latest information about the charger. null values indicate we are unable to determine a value for the field based on the information coming from the vendor.

    Show child attributes
    • chargeState.isPluggedIn boolean or null

      Indicates whether the charger has a vehicle plugged into it (regardless of whether that vehicle is actually charging)

    • chargeState.isCharging boolean or null

      Indicates whether the charger is currently delivering power to the vehicle and actively charging its battery.

    • chargeState.chargeRate number or null

      The current charge rate in kW.

      This property is only available when the charger is actively charging a vehicle, and is null any other time.

    • chargeState.lastUpdated string<date-time> or null

      Time of latest charge state update

    • chargeState.maxCurrent number or null

      Desired max current in amperes, if set

    • chargeState.powerDeliveryState string

      The current state of power delivery between the vehicle and charger.

      • UNKNOWN: The state of power delivery is currently unknown.
      • UNPLUGGED: The vehicle is not connected to the charger.
      • PLUGGED_IN:INITIALIZING: The charging station is preparing to deliver power to the vehicle. It is expected for this state to shortly transition into PLUGGED_IN:CHARGING.
      • PLUGGED_IN:CHARGING: The charger is actively delivering power to the vehicle, causing the battery level to increase.
      • PLUGGED_IN:STOPPED: The vehicle is plugged in, but the charger has been stopped. It is possible to transition into a charging state by sending a start command.
      • PLUGGED_IN:NO_POWER: The charger attempted to initialize charging, however no external power was accepted by the vehicle. It is not possible to transition into a charging state with a remote command until there is some user intervention to resolve the issue.
      • PLUGGED_IN:FAULT: A malfunction in the charging process is preventing power from being delivered. Possible causes include a charging cable not being properly locked, extreme temperatures, or malfunctions in either the charging station or the vehicle's internal system. It is not possible to transition into a charging state with a remote command until there is some user intervention to resolve the issue.
      • PLUGGED_IN:DISCHARGING: The charger is actively discharging by giving power to the home/grid, causing the battery level to decrease.

      Possible enum values:

        UNKNOWNUNPLUGGEDPLUGGED_IN:INITIALIZINGPLUGGED_IN:CHARGINGPLUGGED_IN:STOPPEDPLUGGED_IN:NO_POWERPLUGGED_IN:FAULT
  • capabilities object

    A collection of descriptors that describe the capabilities of this specific charger

    Show child attributes
    • capabilities.information object

      Full availability of information data.

      Show child attributes
      • capabilities.information.isCapable boolean

        The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

      • capabilities.information.interventionIds array of string

        IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

    • capabilities.chargeState object

      Full availability of chargeState data.

      Show child attributes
      • capabilities.chargeState.isCapable boolean

        The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

      • capabilities.chargeState.interventionIds array of string

        IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

    • capabilities.startCharging object

      Supports START charging command.

      Show child attributes
      • capabilities.startCharging.isCapable boolean

        The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

      • capabilities.startCharging.interventionIds array of string

        IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

    • capabilities.stopCharging object

      Supports STOP charging command.

      Show child attributes
      • capabilities.stopCharging.isCapable boolean

        The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

      • capabilities.stopCharging.interventionIds array of string

        IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

    • capabilities.setMaxCurrent object

      Ability to set the max charge rate.

      Show child attributes
      • capabilities.setMaxCurrent.isCapable boolean

        The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

      • capabilities.setMaxCurrent.interventionIds array of string

        IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

  • scopes array of string

    Scopes that the user has granted for this charger.

  • information object

    Descriptive information about the Charger

    Show child attributes
    • information.brand string

      Charger brand

      Possible enum values:

        ZaptecEaseeWallboxEOEVBoxCharge Ampsgo-eFroniusChargePointEnel XTeslaOhmeGaroSchneider ElectricPod Point
    • information.model string

      Charger model

    • information.year number or null

      Charger production year

  • location object
    Show child attributes
    • location.id string<uuid> or null

      ID of the location the charger is currently positioned at (if any).

    • location.lastUpdated string<date-time> or null

      Time of last received location state update

Response example

{
  "information": {
    "brand": "Zaptec",
    "model": "ZAPTEC PRO",
    "year": null
  },
  "location": {
    "id": "2211e263-d6d4-d6d4-d6d4-dbdd77ec82b6",
    "lastUpdated": "2023-03-21T16:39:20.000Z"
  },
  "id": "2211e263-0362-4235-83f4-887bdf3ee414",
  "userId": "d381faac-5283-44a1-9eb1-36cab2ace670",
  "vendor": "ZAPTEC",
  "lastSeen": "2023-03-21T21:08:27.596Z",
  "isReachable": true,
  "chargeState": {
    "isPluggedIn": true,
    "isCharging": true,
    "chargeRate": 6.939,
    "lastUpdated": "2023-03-21T16:39:20.000Z",
    "maxCurrent": 16,
    "powerDeliveryState": "PLUGGED_IN:CHARGING"
  },
  "capabilities": {
    "information": {
      "isCapable": true,
      "interventionIds": []
    },
    "chargeState": {
      "isCapable": true,
      "interventionIds": []
    },
    "startCharging": {
      "isCapable": true,
      "interventionIds": []
    },
    "stopCharging": {
      "isCapable": true,
      "interventionIds": []
    },
    "setMaxCurrent": {
      "isCapable": false,
      "interventionIds": [
        "dbdd77ec82b6-d6d4-d6d4-d6d4-dbdd77ec82b6"
      ]
    }
  },
  "scopes": [
    "charger:control:charging",
    "charger:read:data"
  ]
}
Was this section helpful?

Control charging

POST /chargers/{chargerId}/charging

Request for a charger to start or stop charging. This request creates an Action that will retry until the charger's powerDeliveryState matches the expected value. The Action must complete before any further commands are sent to the charger. Only one Action can be active for a specific charger at a time. If a new Action is created, the previous Action will be automatically cancelled and transitioned to the CANCELLED state. Transitions can be tracked via the user:vendor-action:updated webhook event or Get Charger ActionAPI.

This endpoint returns an error with status code 422 if the charger is controlled by a schedule. To restore user control, either disable the schedule or use Create Smart OverrideAPI to temporarily enable charging.

Request

Path parameters
chargerId string Required

ID of the Charger.

Attributes
  • action string Required

    Charging action to perform

    Possible enum values:

      STARTSTOP

Request example

curl --request POST \
  --url https://enode-api.production.enode.io/chargers/ad84e742-0f46-4cf4-b0db-7d890f8f23f5/charging \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"action":"START"}'

Response 200

Resulting charge action

Attributes
  • id string<uuid>

    The ID of the action.

  • userId string

    The ID of the user that owns the target of this action.

  • createdAt string<date-time>

    Time when this action was created

  • updatedAt string<date-time>

    Time when this action was last updated

  • completedAt string<date-time> or null

    Time when the action transitioned to a non-pending state.

  • state string

    The real-time status of an action executed on a target.

    • PENDING: The initial state. Enode is actively sending commands and monitoring the target for changes.
    • CONFIRMED: Successful transition of the target to the desired state.
    • FAILED: The target did not respond to the action before timing out. Enode has ceased sending additional commands.
    • CANCELLED: A required precondition was not met during the action's timeout window or another action has been sent to the target, overriding this one.

    Possible enum values:

      PENDINGCONFIRMEDFAILEDCANCELLED
  • targetId string

    ID of the target which this action is controlling.

  • targetType string

    Possible enum values:

      vehiclecharger
  • kind string

    The charging action to perform

    Possible enum values:

      STARTSTOP
  • failureReason object or null

    Information about why was this action not executed successfully.

    Show child attributes
    • failureReason.type string

      A machine-readable high level error category.

      • NO_RESPONSE: The chargeable device did not react to our charge commands within the action's timeout window.
      • FAILED_PRECONDITION: The chargeable device did not meet all required preconditions for this action to be executed during the action's timeout window.
      • UNNECESSARY: The action was not carried out given that the device was already in the desired state.
      • CONFLICT: A newer action for this chargeable has been created. This action is now abandoned.
      • REQUESTED_CANCELLATION: This action was cancelled by request of the controlling owner. The controlling owner may refer to another Enode entity which initiated the command, such as a schedule or smart override.
      • NOT_FOUND: The chargeable was deleted while the action was PENDING.

      Possible enum values:

        NO_RESPONSEFAILED_PRECONDITIONCONFLICTNOT_FOUNDUNNECESSARYREQUESTED_CANCELLATION
    • failureReason.detail string

      A human-readable explanation of why the charging action was unsuccessful.

Response example

{
  "id": "4eaeb363-296d-4ccc-a973-7805e6f400bd",
  "userId": "d5bd4771-864e-4ae5-b913-dfb5cdcd5772",
  "createdAt": "2020-04-07T17:04:26Z",
  "updatedAt": "2020-04-07T17:04:26Z",
  "completedAt": "2020-04-07T17:04:26Z",
  "state": "PENDING",
  "targetId": "bfbccded-8a1c-45a8-bbda-dcaeef29977a",
  "targetType": "vehicle",
  "kind": "START",
  "failureReason": {
    "type": "NO_RESPONSE",
    "detail": "The chargeable device remained unreachable."
  }
}

Response 400

A precondition check failed that is unlikely to change within the action's timeout window. This occurs if the charger cannot perform the action, is fully charged, or is already in the desired state.

Attributes
  • type string

    A URI reference that identifies the problem type.

  • title string

    A short, human-readable summary of the problem type.

  • detail string

    A human-readable explanation specific to this occurrence of the problem.

Response example

{
  "type": "https://developers.enode.com/api/problems/not-found",
  "title": "Not Found",
  "detail": "The requested asset wasn't found."
}

Response 422

Charger controlled by a Schedule

Attributes
  • type string

    A URI reference that identifies the problem type.

  • title string

    A short, human-readable summary of the problem type.

  • detail string

    A human-readable explanation specific to this occurrence of the problem.

Response example

{
  "type": "https://developers.enode.com/api/problems/not-found",
  "title": "Not Found",
  "detail": "The requested asset wasn't found."
}
Was this section helpful?

Set max current

POST /chargers/{chargerId}/max-current

Register for a change of the maxCurrent field on a charger. This request creates an Action that will retry until the charger's maxCurrent matches the expected value. The Action must complete before any further commands are sent to the charger. Only one Action can be active for a specific charger at a time. If a new Action is created, the previous Action will be automatically cancelled and transitioned to the CANCELLED state. Transitions can be tracked via the user:vendor-action:updated webhook event or Get Charger ActionAPI.

Request

Path parameters
chargerId string Required

ID of the Charger.

Attributes
  • maxCurrent number Required

    Desired max current in ampere

Request example

curl --request POST \
  --url https://enode-api.production.enode.io/chargers/ad84e742-0f46-4cf4-b0db-7d890f8f23f5/max-current \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"maxCurrent":10}'

Response 200

Attributes
  • id string<uuid>

    The ID of the action.

  • userId string

    The ID of the user that owns the target of this action.

  • createdAt string<date-time>

    Time when this action was created

  • updatedAt string<date-time>

    Time when this action was last updated

  • completedAt string<date-time> or null

    Time when the action transitioned to a non-pending state.

  • state string

    The real-time status of an action executed on a target.

    • PENDING: The initial state. Enode is actively sending commands and monitoring the target for changes.
    • CONFIRMED: Successful transition of the target to the desired state.
    • FAILED: The target did not respond to the action before timing out. Enode has ceased sending additional commands.
    • CANCELLED: A required precondition was not met during the action's timeout window or another action has been sent to the target, overriding this one.

    Possible enum values:

      PENDINGCONFIRMEDFAILEDCANCELLED
  • targetId string

    ID of the entity which this action is controlling.

  • targetType string

    Possible enum values:

      vehiclecharger
  • targetState object

    Target maximum current for entity

    Show child attributes
    • targetState.maxCurrent number

      Desired max current in ampere

  • failureReason object or null

    Information about why was this action not executed successfully.

    Show child attributes
    • failureReason.type string

      A machine-readable high level error category.

      • NO_RESPONSE: The chargeable device did not react to our charge commands within the action's timeout window.
      • FAILED_PRECONDITION: The chargeable device did not meet all required preconditions for this action to be executed during the action's timeout window.
      • UNNECESSARY: The action was not carried out given that the device was already in the desired state.
      • CONFLICT: A newer action for this chargeable has been created. This action is now abandoned.
      • REQUESTED_CANCELLATION: This action was cancelled by request of the controlling owner. The controlling owner may refer to another Enode entity which initiated the command, such as a schedule or smart override.
      • NOT_FOUND: The chargeable was deleted while the action was PENDING.

      Possible enum values:

        NO_RESPONSEFAILED_PRECONDITIONCONFLICTNOT_FOUNDUNNECESSARYREQUESTED_CANCELLATION
    • failureReason.detail string

      A human-readable explanation of why the charging action was unsuccessful.

Response example

{
  "id": "4eaeb363-296d-4ccc-a973-7805e6f400bd",
  "userId": "d5bd4771-864e-4ae5-b913-dfb5cdcd5772",
  "createdAt": "2020-04-07T17:04:26Z",
  "updatedAt": "2020-04-07T17:04:26Z",
  "completedAt": "2020-04-07T17:04:26Z",
  "state": "PENDING",
  "targetId": "string",
  "targetType": "vehicle",
  "targetState": {
    "maxCurrent": 10
  },
  "failureReason": {
    "type": "NO_RESPONSE",
    "detail": "The chargeable device remained unreachable."
  }
}

Response 400

A precondition check failed that is unlikely to change within the action's timeout window. This occurs if the charger cannot perform the action.

Attributes
  • type string

    A URI reference that identifies the problem type.

  • title string

    A short, human-readable summary of the problem type.

  • detail string

    A human-readable explanation specific to this occurrence of the problem.

Response example

{
  "type": "https://developers.enode.com/api/problems/not-found",
  "title": "Not Found",
  "detail": "The requested asset wasn't found."
}
Was this section helpful?

Get charger action

GET /chargers/actions/{actionId}

Returns the current state of the requested Action.

Request

Path parameters
actionId string<uuid> Required

ID of the Action.

Request example

curl --request GET \
  --url https://enode-api.production.enode.io/chargers/actions/4eaeb363-296d-4ccc-a973-7805e6f400bd \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response 200

Attributes
  • id string<uuid>

    The ID of the action.

  • userId string

    The ID of the user that owns the target of this action.

  • createdAt string<date-time>

    Time when this action was created

  • updatedAt string<date-time>

    Time when this action was last updated

  • completedAt string<date-time> or null

    Time when the action transitioned to a non-pending state.

  • state string

    The real-time status of an action executed on a target.

    • PENDING: The initial state. Enode is actively sending commands and monitoring the target for changes.
    • CONFIRMED: Successful transition of the target to the desired state.
    • FAILED: The target did not respond to the action before timing out. Enode has ceased sending additional commands.
    • CANCELLED: A required precondition was not met during the action's timeout window or another action has been sent to the target, overriding this one.

    Possible enum values:

      PENDINGCONFIRMEDFAILEDCANCELLED
  • targetId string

    ID of the target which this action is controlling.

  • targetType string

    Possible enum values:

      vehiclecharger
  • kind string

    The charging action to perform

    Possible enum values:

      STARTSTOP
  • failureReason object or null

    Information about why was this action not executed successfully.

    Show child attributes
    • failureReason.type string

      A machine-readable high level error category.

      • NO_RESPONSE: The chargeable device did not react to our charge commands within the action's timeout window.
      • FAILED_PRECONDITION: The chargeable device did not meet all required preconditions for this action to be executed during the action's timeout window.
      • UNNECESSARY: The action was not carried out given that the device was already in the desired state.
      • CONFLICT: A newer action for this chargeable has been created. This action is now abandoned.
      • REQUESTED_CANCELLATION: This action was cancelled by request of the controlling owner. The controlling owner may refer to another Enode entity which initiated the command, such as a schedule or smart override.
      • NOT_FOUND: The chargeable was deleted while the action was PENDING.

      Possible enum values:

        NO_RESPONSEFAILED_PRECONDITIONCONFLICTNOT_FOUNDUNNECESSARYREQUESTED_CANCELLATION
    • failureReason.detail string

      A human-readable explanation of why the charging action was unsuccessful.

Response example

{
  "id": "4eaeb363-296d-4ccc-a973-7805e6f400bd",
  "userId": "d5bd4771-864e-4ae5-b913-dfb5cdcd5772",
  "createdAt": "2020-04-07T17:04:26Z",
  "updatedAt": "2020-04-07T17:04:26Z",
  "completedAt": "2020-04-07T17:04:26Z",
  "state": "PENDING",
  "targetId": "bfbccded-8a1c-45a8-bbda-dcaeef29977a",
  "targetType": "vehicle",
  "kind": "START",
  "failureReason": {
    "type": "NO_RESPONSE",
    "detail": "The chargeable device remained unreachable."
  }
}

Response 404

Action not found.

Was this section helpful?

Cancel charger action

POST /chargers/actions/{actionId}/cancel

Cancels a pending Action, halting any further attempts by Enode to execute it.

Note: This only updates the Action's status to CANCELLED within Enode and does not reflect a change in the vendor's cloud. Thus any pending Action in the vendor's cloud might still be executed.

Request

Path parameters
actionId string<uuid> Required

ID of the Action.

Request example

curl --request POST \
  --url https://enode-api.production.enode.io/chargers/actions/4eaeb363-296d-4ccc-a973-7805e6f400bd/cancel \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response 200

Attributes
  • id string<uuid>

    The ID of the action.

  • userId string

    The ID of the user that owns the target of this action.

  • createdAt string<date-time>

    Time when this action was created

  • updatedAt string<date-time>

    Time when this action was last updated

  • completedAt string<date-time> or null

    Time when the action transitioned to a non-pending state.

  • state string

    The real-time status of an action executed on a target.

    • PENDING: The initial state. Enode is actively sending commands and monitoring the target for changes.
    • CONFIRMED: Successful transition of the target to the desired state.
    • FAILED: The target did not respond to the action before timing out. Enode has ceased sending additional commands.
    • CANCELLED: A required precondition was not met during the action's timeout window or another action has been sent to the target, overriding this one.

    Possible enum values:

      PENDINGCONFIRMEDFAILEDCANCELLED
  • targetId string

    ID of the target which this action is controlling.

  • targetType string

    Possible enum values:

      vehiclecharger
  • kind string

    The charging action to perform

    Possible enum values:

      STARTSTOP
  • failureReason object or null

    Information about why was this action not executed successfully.

    Show child attributes
    • failureReason.type string

      A machine-readable high level error category.

      • NO_RESPONSE: The chargeable device did not react to our charge commands within the action's timeout window.
      • FAILED_PRECONDITION: The chargeable device did not meet all required preconditions for this action to be executed during the action's timeout window.
      • UNNECESSARY: The action was not carried out given that the device was already in the desired state.
      • CONFLICT: A newer action for this chargeable has been created. This action is now abandoned.
      • REQUESTED_CANCELLATION: This action was cancelled by request of the controlling owner. The controlling owner may refer to another Enode entity which initiated the command, such as a schedule or smart override.
      • NOT_FOUND: The chargeable was deleted while the action was PENDING.

      Possible enum values:

        NO_RESPONSEFAILED_PRECONDITIONCONFLICTNOT_FOUNDUNNECESSARYREQUESTED_CANCELLATION
    • failureReason.detail string

      A human-readable explanation of why the charging action was unsuccessful.

Response example

{
  "id": "4eaeb363-296d-4ccc-a973-7805e6f400bd",
  "userId": "d5bd4771-864e-4ae5-b913-dfb5cdcd5772",
  "createdAt": "2020-04-07T17:04:26Z",
  "updatedAt": "2020-04-07T17:04:26Z",
  "completedAt": "2020-04-07T17:04:26Z",
  "state": "PENDING",
  "targetId": "bfbccded-8a1c-45a8-bbda-dcaeef29977a",
  "targetType": "vehicle",
  "kind": "START",
  "failureReason": {
    "type": "NO_RESPONSE",
    "detail": "The chargeable device remained unreachable."
  }
}

Response 404

Action not found.

Response 409

Action already in a resolved state.

Attributes
  • id string<uuid>

    The ID of the action.

  • userId string

    The ID of the user that owns the target of this action.

  • createdAt string<date-time>

    Time when this action was created

  • updatedAt string<date-time>

    Time when this action was last updated

  • completedAt string<date-time> or null

    Time when the action transitioned to a non-pending state.

  • state string

    The real-time status of an action executed on a target.

    • PENDING: The initial state. Enode is actively sending commands and monitoring the target for changes.
    • CONFIRMED: Successful transition of the target to the desired state.
    • FAILED: The target did not respond to the action before timing out. Enode has ceased sending additional commands.
    • CANCELLED: A required precondition was not met during the action's timeout window or another action has been sent to the target, overriding this one.

    Possible enum values:

      PENDINGCONFIRMEDFAILEDCANCELLED
  • targetId string

    ID of the target which this action is controlling.

  • targetType string

    Possible enum values:

      vehiclecharger
  • kind string

    The charging action to perform

    Possible enum values:

      STARTSTOP
  • failureReason object or null

    Information about why was this action not executed successfully.

    Show child attributes
    • failureReason.type string

      A machine-readable high level error category.

      • NO_RESPONSE: The chargeable device did not react to our charge commands within the action's timeout window.
      • FAILED_PRECONDITION: The chargeable device did not meet all required preconditions for this action to be executed during the action's timeout window.
      • UNNECESSARY: The action was not carried out given that the device was already in the desired state.
      • CONFLICT: A newer action for this chargeable has been created. This action is now abandoned.
      • REQUESTED_CANCELLATION: This action was cancelled by request of the controlling owner. The controlling owner may refer to another Enode entity which initiated the command, such as a schedule or smart override.
      • NOT_FOUND: The chargeable was deleted while the action was PENDING.

      Possible enum values:

        NO_RESPONSEFAILED_PRECONDITIONCONFLICTNOT_FOUNDUNNECESSARYREQUESTED_CANCELLATION
    • failureReason.detail string

      A human-readable explanation of why the charging action was unsuccessful.

Response example

{
  "id": "4eaeb363-296d-4ccc-a973-7805e6f400bd",
  "userId": "d5bd4771-864e-4ae5-b913-dfb5cdcd5772",
  "createdAt": "2020-04-07T17:04:26Z",
  "updatedAt": "2020-04-07T17:04:26Z",
  "completedAt": "2020-04-07T17:04:26Z",
  "state": "PENDING",
  "targetId": "bfbccded-8a1c-45a8-bbda-dcaeef29977a",
  "targetType": "vehicle",
  "kind": "START",
  "failureReason": {
    "type": "NO_RESPONSE",
    "detail": "The chargeable device remained unreachable."
  }
}
Was this section helpful?

Refresh charger data

POST /chargers/{chargerId}/refresh-hint

Use this endpoint to initiate an expedited data refresh for the specified charger.

Note: The Enode platform keeps data automatically up-to-date and detects changes in the OEM APIs within seconds to a few minutes. We change the refresh interval dynamically based on a number of heuristics. This ensures we find the best trade-off between the stability of the connection to the OEM and freshness of the data.
This method overrides most of our heuristics and should therefore be used with caution. You may use it when you have a strong reason to believe the data might be stale.

Request

Path parameters
chargerId string Required

ID of the Charger.

Request example

curl --request POST \
  --url https://enode-api.production.enode.io/chargers/ad84e742-0f46-4cf4-b0db-7d890f8f23f5/refresh-hint \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response 204

Refresh hint registered successfully.

Response 404

The specified charger was not found.

Was this section helpful?

HVAC

HVAC units (heaters, heat pumps, air conditioning, thermostats, etc.) are controlled by altering the mode & target setpoints. This can be done directly using the Set Permanent HoldAPI endpoint, Return to ScheduleAPI, or via Schedules.

List HVAC units

GET /hvacs

Paginated list of HVAC units

Request

Query parameters
after string Optional
before string Optional
pageSize integer Optional

Default value: 50

Request example

curl --request GET \
  --url 'https://enode-api.production.enode.io/hvacs?after=MjAyMy0wNy0xOFQxMDowODowMi4zNzNa&before=MjAyMy0wNy0xOFQxMDowODowMi4zNzNa&pageSize=50' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response 200

Attributes
  • data array of object

    List of paginated HVAC units

    Show child attributes
    • data[].id string

      HVAC unit ID

    • data[].userId string

      The ID of the user that linked this hvac.

    • data[].vendor string

      Machine-friendly name of the vendor. Use this in API requests.

      Possible enum values:

        TADOMILLADAXECOBEESENSIBOHONEYWELLRESIDEOMITSUBISHIMICROMATICNIBEPANASONICTOSHIBADAIKINNESTFUJITSUBOSCHNETATMO
    • data[].lastSeen string<date-time>

      The last time Enode successfully communicated with the vendor or when the HVAC unit was initially linked.

    • data[].isReachable boolean

      Indicates whether Enode can currently access live data from the HVAC. If the HVAC is not reachable, data updates will be delayed.

    • data[].consumptionRate number or null

      The current rate of energy consumption in kW. An inactive HVAC will have a consumption rate of 0. HVACs not supporting consumption rate will report null. This value is currently only supported by a small number of devices.

    • data[].information object

      Descriptive information about the HVAC unit

      Show child attributes
      • data[].information.brand string

        Display name of OEM/vendor

        Possible enum values:

          TadoMillADAXEcobeeSensiboHoneywell TCCResideoMitsubishiMicro MaticNIBEPanasonicToshibaDAIKINNestFujitsuBoschNetatmo
      • data[].information.model string or null

        Device model name

      • data[].information.displayName string

        Name of the device, as set by the user on the device/vendor. If no user-specified name is available, we construct a fallback name using the vendor/device/model names.

      • data[].information.groupName string or null

        Name of the group the device belongs to, as set by the user on the device/vendor. Groups are typically presented as "rooms" or "zones".

      • data[].information.category string

        Classification of the connected HVAC device.

        • HEATING: A direct heating device, such as an electric panel heater

        • COOLING: A direct cooling device, such as an air conditioner

        • HEAT_PUMP: An air-to-air heat pump capable of both heating and cooling

        • AGGREGATOR: A device that is capable of controlling various HVAC systems behind it, such as a smart thermostat

        Possible enum values:

          HEATINGCOOLINGHEAT_PUMPAGGREGATOR
    • data[].temperatureState object

      Latest information about temperature. null values indicate we are unable to determine a value for the field based on the information coming from the vendor.

      Show child attributes
      • data[].temperatureState.currentTemperature number or null

        Current air temperature reported by device in degrees Celsius.

      • data[].temperatureState.isActive boolean

        Whether the HVAC unit is actively heating or cooling.

      • data[].temperatureState.lastUpdated string<date-time> or null

        Time of last temperature state update. Reflects when the OEM reported a change or Enode recorded a change in any field, whichever is newer

    • data[].thermostatState object

      Latest information about the thermostat state. null values indicate we are unable to determine a value for the field based on the information coming from the vendor.

      Show child attributes
      • data[].thermostatState.mode string

        The current state of the HVAC unit.

        • UNKNOWN: The mode of the HVAC unit is currently not available from the vendor or not supported by enode.
        • OFF: The HVAC unit is turned off.
        • AUTO: The HVAC unit will try to maintain the given setpoint by alternating between cooling and heating based on the ambient temperature
        • COOL: The HVAC unit will only cool to the given setpoint.
        • HEAT: The HVAC unit will only heat to the given setpoint

        Possible enum values:

          UNKNOWNOFFAUTOCOOLHEAT
      • data[].thermostatState.heatSetpoint number or null

        If mode allows, heat when currentTemperature falls below this point.

      • data[].thermostatState.coolSetpoint number or null

        If mode allows, cool when currentTemperature rises above this point.

      • data[].thermostatState.holdType string or null

        The duration the setpoints and mode are expected to be held. If SCHEDULED, the device is being controlled by an OEM schedule configured on the device.

        Possible enum values:

          PERMANENTSCHEDULED
      • data[].thermostatState.lastUpdated string<date-time> or null

        Time of last thermostat state update. Reflects when the OEM reported a change or Enode recorded a change in any field, whichever is newer.

    • data[].scopes array of string

      Scopes that the user has granted for this HVAC unit.

    • data[].capabilities object

      An object describing valid states for this HVAC unit.

      Show child attributes
      • data[].capabilities.capableModes array of string or null

        A list of valid modes for this HVAC unit.

      • data[].capabilities.coolSetpointRange object or null

        The range of allowable values for coolSetpoint.

        Show child attributes
        • data[].capabilities.coolSetpointRange.min number or null

          The minimum allowable temperature, inclusive.

        • data[].capabilities.coolSetpointRange.max number or null

          The maximum allowable temperature, inclusive.

      • data[].capabilities.heatSetpointRange object or null

        The range of allowable values for heatSetpoint.

        Show child attributes
        • data[].capabilities.heatSetpointRange.min number or null

          The minimum allowable temperature, inclusive.

        • data[].capabilities.heatSetpointRange.max number or null

          The maximum allowable temperature, inclusive.

      • data[].capabilities.setpointDifferenceRange object or null

        A constraint specifying the minimum and maximum allowable difference between heatSetpoint and coolSetpoint. Only applicable in AUTO mode.

        Show child attributes
        • data[].capabilities.setpointDifferenceRange.min number or null

          The minimum allowable difference, inclusive.

        • data[].capabilities.setpointDifferenceRange.max number or null

          The maximum allowable difference, inclusive.

      • data[].capabilities.setFollowSchedule object

        Supports following a schedule set on the device.

        Show child attributes
        • data[].capabilities.setFollowSchedule.isCapable boolean

          The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

        • data[].capabilities.setFollowSchedule.interventionIds array of string

          IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

      • data[].capabilities.setPermanentHold object

        Supports setting a permanent hold.

        Show child attributes
        • data[].capabilities.setPermanentHold.isCapable boolean

          The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

        • data[].capabilities.setPermanentHold.interventionIds array of string

          IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

    • data[].location object
      Show child attributes
      • data[].location.id string<uuid> or null

        ID of the charging location the HVAC unit is housed at (if any)

  • pagination object

    Cursors to the pages before and after current page. See the PaginationAPI section for reference.

    Show child attributes
    • pagination.after string or null
    • pagination.before string or null

Response example

{
  "data": [
    {
      "id": "8f39fa8d-8f10-4984-a319-741dc23848c0",
      "userId": "17d9f847-8a1c-4158-adaa-4911a7acd5f9",
      "vendor": "ADAX",
      "lastSeen": "2020-04-07T17:04:26.000Z",
      "isReachable": true,
      "consumptionRate": 1.8,
      "information": {
        "brand": "ADAX",
        "model": "Neo Wi-Fi Skirting",
        "displayName": "Bedroom Panel Heater",
        "groupName": "Bedroom",
        "category": "HEATING"
      },
      "capabilities": {
        "capableModes": [
          "HEAT",
          "COOL",
          "OFF"
        ],
        "capableHoldTypes": [
          "PERMANENT"
        ],
        "coolSetpointRange": {
          "min": 15,
          "max": 25
        },
        "heatSetpointRange": {
          "min": 15,
          "max": 25
        },
        "setpointDifferenceRange": {
          "min": 15,
          "max": 25
        },
        "setFollowSchedule": {
          "isCapable": true,
          "interventionIds": []
        },
        "setPermanentHold": {
          "isCapable": true,
          "interventionIds": []
        }
      },
      "thermostatState": {
        "mode": "HEAT",
        "heatSetpoint": 22,
        "coolSetpoint": 24,
        "holdType": "PERMANENT",
        "lastUpdated": "2020-04-07T17:04:26.000Z"
      },
      "temperatureState": {
        "currentTemperature": 20.8,
        "isActive": true,
        "lastUpdated": "2020-04-07T17:03:26.000Z"
      },
      "scopes": [
        "hvac:control:mode",
        "hvac:read:data"
      ],
      "location": {
        "id": "8d90101b-3f2f-462a-bbb4-1ed320d33bbe"
      }
    }
  ],
  "pagination": {
    "after": "MjAyMy0wNy0xOFQxMDowODowMi4zNzNa",
    "before": "MjAyMy0wNi0xNlQwOTowMzowMS4yNjJa"
  }
}
Was this section helpful?

List user HVAC units

GET /users/{userId}/hvacs

Paginated list of HVAC units for the given User

Request

Path parameters
userId string Required

ID of the User.

Query parameters
after string Optional
before string Optional
pageSize integer Optional

Default value: 50

Request example

curl --request GET \
  --url 'https://enode-api.production.enode.io/users/%7BuserId%7D/hvacs?after=MjAyMy0wNy0xOFQxMDowODowMi4zNzNa&before=MjAyMy0wNy0xOFQxMDowODowMi4zNzNa&pageSize=50' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response 200

Attributes
  • data array of object

    List of paginated HVAC units

    Show child attributes
    • data[].id string

      HVAC unit ID

    • data[].userId string

      The ID of the user that linked this hvac.

    • data[].vendor string

      Machine-friendly name of the vendor. Use this in API requests.

      Possible enum values:

        TADOMILLADAXECOBEESENSIBOHONEYWELLRESIDEOMITSUBISHIMICROMATICNIBEPANASONICTOSHIBADAIKINNESTFUJITSUBOSCHNETATMO
    • data[].lastSeen string<date-time>

      The last time Enode successfully communicated with the vendor or when the HVAC unit was initially linked.

    • data[].isReachable boolean

      Indicates whether Enode can currently access live data from the HVAC. If the HVAC is not reachable, data updates will be delayed.

    • data[].consumptionRate number or null

      The current rate of energy consumption in kW. An inactive HVAC will have a consumption rate of 0. HVACs not supporting consumption rate will report null. This value is currently only supported by a small number of devices.

    • data[].information object

      Descriptive information about the HVAC unit

      Show child attributes
      • data[].information.brand string

        Display name of OEM/vendor

        Possible enum values:

          TadoMillADAXEcobeeSensiboHoneywell TCCResideoMitsubishiMicro MaticNIBEPanasonicToshibaDAIKINNestFujitsuBoschNetatmo
      • data[].information.model string or null

        Device model name

      • data[].information.displayName string

        Name of the device, as set by the user on the device/vendor. If no user-specified name is available, we construct a fallback name using the vendor/device/model names.

      • data[].information.groupName string or null

        Name of the group the device belongs to, as set by the user on the device/vendor. Groups are typically presented as "rooms" or "zones".

      • data[].information.category string

        Classification of the connected HVAC device.

        • HEATING: A direct heating device, such as an electric panel heater

        • COOLING: A direct cooling device, such as an air conditioner

        • HEAT_PUMP: An air-to-air heat pump capable of both heating and cooling

        • AGGREGATOR: A device that is capable of controlling various HVAC systems behind it, such as a smart thermostat

        Possible enum values:

          HEATINGCOOLINGHEAT_PUMPAGGREGATOR
    • data[].temperatureState object

      Latest information about temperature. null values indicate we are unable to determine a value for the field based on the information coming from the vendor.

      Show child attributes
      • data[].temperatureState.currentTemperature number or null

        Current air temperature reported by device in degrees Celsius.

      • data[].temperatureState.isActive boolean

        Whether the HVAC unit is actively heating or cooling.

      • data[].temperatureState.lastUpdated string<date-time> or null

        Time of last temperature state update. Reflects when the OEM reported a change or Enode recorded a change in any field, whichever is newer

    • data[].thermostatState object

      Latest information about the thermostat state. null values indicate we are unable to determine a value for the field based on the information coming from the vendor.

      Show child attributes
      • data[].thermostatState.mode string

        The current state of the HVAC unit.

        • UNKNOWN: The mode of the HVAC unit is currently not available from the vendor or not supported by enode.
        • OFF: The HVAC unit is turned off.
        • AUTO: The HVAC unit will try to maintain the given setpoint by alternating between cooling and heating based on the ambient temperature
        • COOL: The HVAC unit will only cool to the given setpoint.
        • HEAT: The HVAC unit will only heat to the given setpoint

        Possible enum values:

          UNKNOWNOFFAUTOCOOLHEAT
      • data[].thermostatState.heatSetpoint number or null

        If mode allows, heat when currentTemperature falls below this point.

      • data[].thermostatState.coolSetpoint number or null

        If mode allows, cool when currentTemperature rises above this point.

      • data[].thermostatState.holdType string or null

        The duration the setpoints and mode are expected to be held. If SCHEDULED, the device is being controlled by an OEM schedule configured on the device.

        Possible enum values:

          PERMANENTSCHEDULED
      • data[].thermostatState.lastUpdated string<date-time> or null

        Time of last thermostat state update. Reflects when the OEM reported a change or Enode recorded a change in any field, whichever is newer.

    • data[].scopes array of string

      Scopes that the user has granted for this HVAC unit.

    • data[].capabilities object

      An object describing valid states for this HVAC unit.

      Show child attributes
      • data[].capabilities.capableModes array of string or null

        A list of valid modes for this HVAC unit.

      • data[].capabilities.coolSetpointRange object or null

        The range of allowable values for coolSetpoint.

        Show child attributes
        • data[].capabilities.coolSetpointRange.min number or null

          The minimum allowable temperature, inclusive.

        • data[].capabilities.coolSetpointRange.max number or null

          The maximum allowable temperature, inclusive.

      • data[].capabilities.heatSetpointRange object or null

        The range of allowable values for heatSetpoint.

        Show child attributes
        • data[].capabilities.heatSetpointRange.min number or null

          The minimum allowable temperature, inclusive.

        • data[].capabilities.heatSetpointRange.max number or null

          The maximum allowable temperature, inclusive.

      • data[].capabilities.setpointDifferenceRange object or null

        A constraint specifying the minimum and maximum allowable difference between heatSetpoint and coolSetpoint. Only applicable in AUTO mode.

        Show child attributes
        • data[].capabilities.setpointDifferenceRange.min number or null

          The minimum allowable difference, inclusive.

        • data[].capabilities.setpointDifferenceRange.max number or null

          The maximum allowable difference, inclusive.

      • data[].capabilities.setFollowSchedule object

        Supports following a schedule set on the device.

        Show child attributes
        • data[].capabilities.setFollowSchedule.isCapable boolean

          The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

        • data[].capabilities.setFollowSchedule.interventionIds array of string

          IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

      • data[].capabilities.setPermanentHold object

        Supports setting a permanent hold.

        Show child attributes
        • data[].capabilities.setPermanentHold.isCapable boolean

          The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

        • data[].capabilities.setPermanentHold.interventionIds array of string

          IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

    • data[].location object
      Show child attributes
      • data[].location.id string<uuid> or null

        ID of the charging location the HVAC unit is housed at (if any)

  • pagination object

    Cursors to the pages before and after current page. See the PaginationAPI section for reference.

    Show child attributes
    • pagination.after string or null
    • pagination.before string or null

Response example

{
  "data": [
    {
      "id": "8f39fa8d-8f10-4984-a319-741dc23848c0",
      "userId": "17d9f847-8a1c-4158-adaa-4911a7acd5f9",
      "vendor": "ADAX",
      "lastSeen": "2020-04-07T17:04:26.000Z",
      "isReachable": true,
      "consumptionRate": 1.8,
      "information": {
        "brand": "ADAX",
        "model": "Neo Wi-Fi Skirting",
        "displayName": "Bedroom Panel Heater",
        "groupName": "Bedroom",
        "category": "HEATING"
      },
      "capabilities": {
        "capableModes": [
          "HEAT",
          "COOL",
          "OFF"
        ],
        "capableHoldTypes": [
          "PERMANENT"
        ],
        "coolSetpointRange": {
          "min": 15,
          "max": 25
        },
        "heatSetpointRange": {
          "min": 15,
          "max": 25
        },
        "setpointDifferenceRange": {
          "min": 15,
          "max": 25
        },
        "setFollowSchedule": {
          "isCapable": true,
          "interventionIds": []
        },
        "setPermanentHold": {
          "isCapable": true,
          "interventionIds": []
        }
      },
      "thermostatState": {
        "mode": "HEAT",
        "heatSetpoint": 22,
        "coolSetpoint": 24,
        "holdType": "PERMANENT",
        "lastUpdated": "2020-04-07T17:04:26.000Z"
      },
      "temperatureState": {
        "currentTemperature": 20.8,
        "isActive": true,
        "lastUpdated": "2020-04-07T17:03:26.000Z"
      },
      "scopes": [
        "hvac:control:mode",
        "hvac:read:data"
      ],
      "location": {
        "id": "8d90101b-3f2f-462a-bbb4-1ed320d33bbe"
      }
    }
  ],
  "pagination": {
    "after": "MjAyMy0wNy0xOFQxMDowODowMi4zNzNa",
    "before": "MjAyMy0wNi0xNlQwOTowMzowMS4yNjJa"
  }
}
Was this section helpful?

Set location for an HVAC unit

PUT /hvacs/{hvacId}

Update the locationId field on an HVAC unit.

Request

Path parameters
hvacId string Required

ID of the HVAC unit.

Attributes
  • locationId string<uuid> or null Required

Request example

curl --request PUT \
  --url https://enode-api.production.enode.io/hvacs/8f39fa8d-8f10-4984-a319-741dc23848c0 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"locationId":"4eaeb363-296d-4ccc-a973-7805e6f400bd"}'

Response 200

Successfully updated HVAC unit

Attributes
  • id string

    HVAC unit ID

  • userId string

    The ID of the user that linked this hvac.

  • vendor string

    Machine-friendly name of the vendor. Use this in API requests.

    Possible enum values:

      TADOMILLADAXECOBEESENSIBOHONEYWELLRESIDEOMITSUBISHIMICROMATICNIBEPANASONICTOSHIBADAIKINNESTFUJITSUBOSCHNETATMO
  • lastSeen string<date-time>

    The last time Enode successfully communicated with the vendor or when the HVAC unit was initially linked.

  • isReachable boolean

    Indicates whether Enode can currently access live data from the HVAC. If the HVAC is not reachable, data updates will be delayed.

  • consumptionRate number or null

    The current rate of energy consumption in kW. An inactive HVAC will have a consumption rate of 0. HVACs not supporting consumption rate will report null. This value is currently only supported by a small number of devices.

  • information object

    Descriptive information about the HVAC unit

    Show child attributes
    • information.brand string

      Display name of OEM/vendor

      Possible enum values:

        TadoMillADAXEcobeeSensiboHoneywell TCCResideoMitsubishiMicro MaticNIBEPanasonicToshibaDAIKINNestFujitsuBoschNetatmo
    • information.model string or null

      Device model name

    • information.displayName string

      Name of the device, as set by the user on the device/vendor. If no user-specified name is available, we construct a fallback name using the vendor/device/model names.

    • information.groupName string or null

      Name of the group the device belongs to, as set by the user on the device/vendor. Groups are typically presented as "rooms" or "zones".

    • information.category string

      Classification of the connected HVAC device.

      • HEATING: A direct heating device, such as an electric panel heater

      • COOLING: A direct cooling device, such as an air conditioner

      • HEAT_PUMP: An air-to-air heat pump capable of both heating and cooling

      • AGGREGATOR: A device that is capable of controlling various HVAC systems behind it, such as a smart thermostat

      Possible enum values:

        HEATINGCOOLINGHEAT_PUMPAGGREGATOR
  • temperatureState object

    Latest information about temperature. null values indicate we are unable to determine a value for the field based on the information coming from the vendor.

    Show child attributes
    • temperatureState.currentTemperature number or null

      Current air temperature reported by device in degrees Celsius.

    • temperatureState.isActive boolean

      Whether the HVAC unit is actively heating or cooling.

    • temperatureState.lastUpdated string<date-time> or null

      Time of last temperature state update. Reflects when the OEM reported a change or Enode recorded a change in any field, whichever is newer

  • thermostatState object

    Latest information about the thermostat state. null values indicate we are unable to determine a value for the field based on the information coming from the vendor.

    Show child attributes
    • thermostatState.mode string

      The current state of the HVAC unit.

      • UNKNOWN: The mode of the HVAC unit is currently not available from the vendor or not supported by enode.
      • OFF: The HVAC unit is turned off.
      • AUTO: The HVAC unit will try to maintain the given setpoint by alternating between cooling and heating based on the ambient temperature
      • COOL: The HVAC unit will only cool to the given setpoint.
      • HEAT: The HVAC unit will only heat to the given setpoint

      Possible enum values:

        UNKNOWNOFFAUTOCOOLHEAT
    • thermostatState.heatSetpoint number or null

      If mode allows, heat when currentTemperature falls below this point.

    • thermostatState.coolSetpoint number or null

      If mode allows, cool when currentTemperature rises above this point.

    • thermostatState.holdType string or null

      The duration the setpoints and mode are expected to be held. If SCHEDULED, the device is being controlled by an OEM schedule configured on the device.

      Possible enum values:

        PERMANENTSCHEDULED
    • thermostatState.lastUpdated string<date-time> or null

      Time of last thermostat state update. Reflects when the OEM reported a change or Enode recorded a change in any field, whichever is newer.

  • scopes array of string

    Scopes that the user has granted for this HVAC unit.

  • capabilities object

    An object describing valid states for this HVAC unit.

    Show child attributes
    • capabilities.capableModes array of string or null

      A list of valid modes for this HVAC unit.

    • capabilities.coolSetpointRange object or null

      The range of allowable values for coolSetpoint.

      Show child attributes
      • capabilities.coolSetpointRange.min number or null

        The minimum allowable temperature, inclusive.

      • capabilities.coolSetpointRange.max number or null

        The maximum allowable temperature, inclusive.

    • capabilities.heatSetpointRange object or null

      The range of allowable values for heatSetpoint.

      Show child attributes
      • capabilities.heatSetpointRange.min number or null

        The minimum allowable temperature, inclusive.

      • capabilities.heatSetpointRange.max number or null

        The maximum allowable temperature, inclusive.

    • capabilities.setpointDifferenceRange object or null

      A constraint specifying the minimum and maximum allowable difference between heatSetpoint and coolSetpoint. Only applicable in AUTO mode.

      Show child attributes
      • capabilities.setpointDifferenceRange.min number or null

        The minimum allowable difference, inclusive.

      • capabilities.setpointDifferenceRange.max number or null

        The maximum allowable difference, inclusive.

    • capabilities.setFollowSchedule object

      Supports following a schedule set on the device.

      Show child attributes
      • capabilities.setFollowSchedule.isCapable boolean

        The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

      • capabilities.setFollowSchedule.interventionIds array of string

        IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

    • capabilities.setPermanentHold object

      Supports setting a permanent hold.

      Show child attributes
      • capabilities.setPermanentHold.isCapable boolean

        The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

      • capabilities.setPermanentHold.interventionIds array of string

        IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

  • location object
    Show child attributes
    • location.id string<uuid> or null

      ID of the charging location the HVAC unit is housed at (if any)

Response example

{
  "id": "8f39fa8d-8f10-4984-a319-741dc23848c0",
  "userId": "17d9f847-8a1c-4158-adaa-4911a7acd5f9",
  "vendor": "ADAX",
  "lastSeen": "2020-04-07T17:04:26.000Z",
  "isReachable": true,
  "consumptionRate": 1.8,
  "information": {
    "brand": "ADAX",
    "model": "Neo Wi-Fi Skirting",
    "displayName": "Bedroom Panel Heater",
    "groupName": "Bedroom",
    "category": "HEATING"
  },
  "capabilities": {
    "capableModes": [
      "HEAT",
      "COOL",
      "OFF"
    ],
    "capableHoldTypes": [
      "PERMANENT"
    ],
    "coolSetpointRange": {
      "min": 15,
      "max": 25
    },
    "heatSetpointRange": {
      "min": 15,
      "max": 25
    },
    "setpointDifferenceRange": {
      "min": 15,
      "max": 25
    },
    "setFollowSchedule": {
      "isCapable": true,
      "interventionIds": []
    },
    "setPermanentHold": {
      "isCapable": true,
      "interventionIds": []
    }
  },
  "thermostatState": {
    "mode": "HEAT",
    "heatSetpoint": 22,
    "coolSetpoint": 24,
    "holdType": "PERMANENT",
    "lastUpdated": "2020-04-07T17:04:26.000Z"
  },
  "temperatureState": {
    "currentTemperature": 20.8,
    "isActive": true,
    "lastUpdated": "2020-04-07T17:03:26.000Z"
  },
  "scopes": [
    "hvac:control:mode",
    "hvac:read:data"
  ],
  "location": {
    "id": "8d90101b-3f2f-462a-bbb4-1ed320d33bbe"
  }
}
Was this section helpful?

Get HVAC unit

GET /hvacs/{hvacId}

Request

Path parameters
hvacId string Required

ID of the HVAC unit.

Request example

curl --request GET \
  --url https://enode-api.production.enode.io/hvacs/8f39fa8d-8f10-4984-a319-741dc23848c0 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response 200

Attributes
  • id string

    HVAC unit ID

  • userId string

    The ID of the user that linked this hvac.

  • vendor string

    Machine-friendly name of the vendor. Use this in API requests.

    Possible enum values:

      TADOMILLADAXECOBEESENSIBOHONEYWELLRESIDEOMITSUBISHIMICROMATICNIBEPANASONICTOSHIBADAIKINNESTFUJITSUBOSCHNETATMO
  • lastSeen string<date-time>

    The last time Enode successfully communicated with the vendor or when the HVAC unit was initially linked.

  • isReachable boolean

    Indicates whether Enode can currently access live data from the HVAC. If the HVAC is not reachable, data updates will be delayed.

  • consumptionRate number or null

    The current rate of energy consumption in kW. An inactive HVAC will have a consumption rate of 0. HVACs not supporting consumption rate will report null. This value is currently only supported by a small number of devices.

  • information object

    Descriptive information about the HVAC unit

    Show child attributes
    • information.brand string

      Display name of OEM/vendor

      Possible enum values:

        TadoMillADAXEcobeeSensiboHoneywell TCCResideoMitsubishiMicro MaticNIBEPanasonicToshibaDAIKINNestFujitsuBoschNetatmo
    • information.model string or null

      Device model name

    • information.displayName string

      Name of the device, as set by the user on the device/vendor. If no user-specified name is available, we construct a fallback name using the vendor/device/model names.

    • information.groupName string or null

      Name of the group the device belongs to, as set by the user on the device/vendor. Groups are typically presented as "rooms" or "zones".

    • information.category string

      Classification of the connected HVAC device.

      • HEATING: A direct heating device, such as an electric panel heater

      • COOLING: A direct cooling device, such as an air conditioner

      • HEAT_PUMP: An air-to-air heat pump capable of both heating and cooling

      • AGGREGATOR: A device that is capable of controlling various HVAC systems behind it, such as a smart thermostat

      Possible enum values:

        HEATINGCOOLINGHEAT_PUMPAGGREGATOR
  • temperatureState object

    Latest information about temperature. null values indicate we are unable to determine a value for the field based on the information coming from the vendor.

    Show child attributes
    • temperatureState.currentTemperature number or null

      Current air temperature reported by device in degrees Celsius.

    • temperatureState.isActive boolean

      Whether the HVAC unit is actively heating or cooling.

    • temperatureState.lastUpdated string<date-time> or null

      Time of last temperature state update. Reflects when the OEM reported a change or Enode recorded a change in any field, whichever is newer

  • thermostatState object

    Latest information about the thermostat state. null values indicate we are unable to determine a value for the field based on the information coming from the vendor.

    Show child attributes
    • thermostatState.mode string

      The current state of the HVAC unit.

      • UNKNOWN: The mode of the HVAC unit is currently not available from the vendor or not supported by enode.
      • OFF: The HVAC unit is turned off.
      • AUTO: The HVAC unit will try to maintain the given setpoint by alternating between cooling and heating based on the ambient temperature
      • COOL: The HVAC unit will only cool to the given setpoint.
      • HEAT: The HVAC unit will only heat to the given setpoint

      Possible enum values:

        UNKNOWNOFFAUTOCOOLHEAT
    • thermostatState.heatSetpoint number or null

      If mode allows, heat when currentTemperature falls below this point.

    • thermostatState.coolSetpoint number or null

      If mode allows, cool when currentTemperature rises above this point.

    • thermostatState.holdType string or null

      The duration the setpoints and mode are expected to be held. If SCHEDULED, the device is being controlled by an OEM schedule configured on the device.

      Possible enum values:

        PERMANENTSCHEDULED
    • thermostatState.lastUpdated string<date-time> or null

      Time of last thermostat state update. Reflects when the OEM reported a change or Enode recorded a change in any field, whichever is newer.

  • scopes array of string

    Scopes that the user has granted for this HVAC unit.

  • capabilities object

    An object describing valid states for this HVAC unit.

    Show child attributes
    • capabilities.capableModes array of string or null

      A list of valid modes for this HVAC unit.

    • capabilities.coolSetpointRange object or null

      The range of allowable values for coolSetpoint.

      Show child attributes
      • capabilities.coolSetpointRange.min number or null

        The minimum allowable temperature, inclusive.

      • capabilities.coolSetpointRange.max number or null

        The maximum allowable temperature, inclusive.

    • capabilities.heatSetpointRange object or null

      The range of allowable values for heatSetpoint.

      Show child attributes
      • capabilities.heatSetpointRange.min number or null

        The minimum allowable temperature, inclusive.

      • capabilities.heatSetpointRange.max number or null

        The maximum allowable temperature, inclusive.

    • capabilities.setpointDifferenceRange object or null

      A constraint specifying the minimum and maximum allowable difference between heatSetpoint and coolSetpoint. Only applicable in AUTO mode.

      Show child attributes
      • capabilities.setpointDifferenceRange.min number or null

        The minimum allowable difference, inclusive.

      • capabilities.setpointDifferenceRange.max number or null

        The maximum allowable difference, inclusive.

    • capabilities.setFollowSchedule object

      Supports following a schedule set on the device.

      Show child attributes
      • capabilities.setFollowSchedule.isCapable boolean

        The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

      • capabilities.setFollowSchedule.interventionIds array of string

        IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

    • capabilities.setPermanentHold object

      Supports setting a permanent hold.

      Show child attributes
      • capabilities.setPermanentHold.isCapable boolean

        The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

      • capabilities.setPermanentHold.interventionIds array of string

        IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

  • location object
    Show child attributes
    • location.id string<uuid> or null

      ID of the charging location the HVAC unit is housed at (if any)

Response example

{
  "id": "8f39fa8d-8f10-4984-a319-741dc23848c0",
  "userId": "17d9f847-8a1c-4158-adaa-4911a7acd5f9",
  "vendor": "ADAX",
  "lastSeen": "2020-04-07T17:04:26.000Z",
  "isReachable": true,
  "consumptionRate": 1.8,
  "information": {
    "brand": "ADAX",
    "model": "Neo Wi-Fi Skirting",
    "displayName": "Bedroom Panel Heater",
    "groupName": "Bedroom",
    "category": "HEATING"
  },
  "capabilities": {
    "capableModes": [
      "HEAT",
      "COOL",
      "OFF"
    ],
    "capableHoldTypes": [
      "PERMANENT"
    ],
    "coolSetpointRange": {
      "min": 15,
      "max": 25
    },
    "heatSetpointRange": {
      "min": 15,
      "max": 25
    },
    "setpointDifferenceRange": {
      "min": 15,
      "max": 25
    },
    "setFollowSchedule": {
      "isCapable": true,
      "interventionIds": []
    },
    "setPermanentHold": {
      "isCapable": true,
      "interventionIds": []
    }
  },
  "thermostatState": {
    "mode": "HEAT",
    "heatSetpoint": 22,
    "coolSetpoint": 24,
    "holdType": "PERMANENT",
    "lastUpdated": "2020-04-07T17:04:26.000Z"
  },
  "temperatureState": {
    "currentTemperature": 20.8,
    "isActive": true,
    "lastUpdated": "2020-04-07T17:03:26.000Z"
  },
  "scopes": [
    "hvac:control:mode",
    "hvac:read:data"
  ],
  "location": {
    "id": "8d90101b-3f2f-462a-bbb4-1ed320d33bbe"
  }
}
Was this section helpful?

Get action

GET /hvacs/actions/{actionId}

Returns the current state of the requested action.

Request

Path parameters
actionId string<uuid> Required

ID of the Action.

Request example

curl --request GET \
  --url https://enode-api.production.enode.io/hvacs/actions/4eaeb363-296d-4ccc-a973-7805e6f400bd \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response 200

Attributes
  • id string<uuid>

    The ID of the action.

  • userId string

    The ID of the user that owns the target of this action.

  • createdAt string<date-time>

    Time when this action was created

  • updatedAt string<date-time>

    Time when this action was last updated

  • completedAt string<date-time> or null

    Time when the action transitioned to a non-pending state.

  • state string

    The real-time status of an action executed on a target.

    • PENDING: The initial state. Enode is actively sending commands and monitoring the target for changes.
    • CONFIRMED: Successful transition of the target to the desired state.
    • FAILED: The target did not respond to the action before timing out. Enode has ceased sending additional commands.
    • CANCELLED: A required precondition was not met during the action's timeout window or another action has been sent to the target, overriding this one.

    Possible enum values:

      PENDINGCONFIRMEDFAILEDCANCELLED
  • targetId string

    ID of the entity asset (HVAC) which this action is controlling.

  • targetType string

    Possible enum values:

      hvac
  • target

Response example

{
  "id": "4eaeb363-296d-4ccc-a973-7805e6f400bd",
  "userId": "d5bd4771-864e-4ae5-b913-dfb5cdcd5772",
  "createdAt": "2020-04-07T17:04:26Z",
  "updatedAt": "2020-04-07T17:04:26Z",
  "completedAt": "2020-04-07T17:04:26Z",
  "state": "PENDING",
  "targetId": "string",
  "targetType": "hvac",
  "target": {
    "coolSetpoint": 0,
    "mode": "COOL",
    "holdType": "PERMANENT"
  }
}

Response 404

Action not found.

Was this section helpful?

Cancel HVAC action

POST /hvacs/actions/{actionId}/cancel

Cancels a pending HVAC action, halting any further attempts by Enode to execute it.

Note: This only updates the action's status to CANCELLED within Enode and does not reflect a change in the vendor's cloud. Thus any pending action in the vendor's cloud might still be executed.

Request

Path parameters
actionId string<uuid> Required

ID of the Action.

Request example

curl --request POST \
  --url https://enode-api.production.enode.io/hvacs/actions/4eaeb363-296d-4ccc-a973-7805e6f400bd/cancel \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response 200

Attributes
  • id string<uuid>

    The ID of the action.

  • userId string

    The ID of the user that owns the target of this action.

  • createdAt string<date-time>

    Time when this action was created

  • updatedAt string<date-time>

    Time when this action was last updated

  • completedAt string<date-time> or null

    Time when the action transitioned to a non-pending state.

  • state string

    The real-time status of an action executed on a target.

    • PENDING: The initial state. Enode is actively sending commands and monitoring the target for changes.
    • CONFIRMED: Successful transition of the target to the desired state.
    • FAILED: The target did not respond to the action before timing out. Enode has ceased sending additional commands.
    • CANCELLED: A required precondition was not met during the action's timeout window or another action has been sent to the target, overriding this one.

    Possible enum values:

      PENDINGCONFIRMEDFAILEDCANCELLED
  • targetId string

    ID of the entity asset (HVAC) which this action is controlling.

  • targetType string

    Possible enum values:

      hvac
  • target

Response example

{
  "id": "4eaeb363-296d-4ccc-a973-7805e6f400bd",
  "userId": "d5bd4771-864e-4ae5-b913-dfb5cdcd5772",
  "createdAt": "2020-04-07T17:04:26Z",
  "updatedAt": "2020-04-07T17:04:26Z",
  "completedAt": "2020-04-07T17:04:26Z",
  "state": "PENDING",
  "targetId": "string",
  "targetType": "hvac",
  "target": {
    "coolSetpoint": 0,
    "mode": "COOL",
    "holdType": "PERMANENT"
  }
}

Response 404

Action not found.

Response 409

Action already in a resolved state.

Attributes
  • id string<uuid>

    The ID of the action.

  • userId string

    The ID of the user that owns the target of this action.

  • createdAt string<date-time>

    Time when this action was created

  • updatedAt string<date-time>

    Time when this action was last updated

  • completedAt string<date-time> or null

    Time when the action transitioned to a non-pending state.

  • state string

    The real-time status of an action executed on a target.

    • PENDING: The initial state. Enode is actively sending commands and monitoring the target for changes.
    • CONFIRMED: Successful transition of the target to the desired state.
    • FAILED: The target did not respond to the action before timing out. Enode has ceased sending additional commands.
    • CANCELLED: A required precondition was not met during the action's timeout window or another action has been sent to the target, overriding this one.

    Possible enum values:

      PENDINGCONFIRMEDFAILEDCANCELLED
  • targetId string

    ID of the entity asset (HVAC) which this action is controlling.

  • targetType string

    Possible enum values:

      hvac
  • target

Response example

{
  "id": "4eaeb363-296d-4ccc-a973-7805e6f400bd",
  "userId": "d5bd4771-864e-4ae5-b913-dfb5cdcd5772",
  "createdAt": "2020-04-07T17:04:26Z",
  "updatedAt": "2020-04-07T17:04:26Z",
  "completedAt": "2020-04-07T17:04:26Z",
  "state": "PENDING",
  "targetId": "string",
  "targetType": "hvac",
  "target": {
    "coolSetpoint": 0,
    "mode": "COOL",
    "holdType": "PERMANENT"
  }
}
Was this section helpful?

Set HVAC unit to follow device schedule

POST /hvacs/{hvacId}/follow-schedule

Tell an HVAC unit to follow the schedule set on the device. Only available if the target's capabilities.setFollowSchedule.isCapable is set to true. This endpoint can be used to cancel permanent holds. We retry sending the command until the HVAC unit's fields transition to the expected values. Note that this request will complete before any commands are sent to the HVAC unit. You may react to transitions by listening for the user:vendor-action:updated webhook event or polling the HVAC action endpointAPI.

Request

Path parameters
hvacId string Required

ID of the HVAC unit.

Request example

curl --request POST \
  --url https://enode-api.production.enode.io/hvacs/8f39fa8d-8f10-4984-a319-741dc23848c0/follow-schedule \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response 200

Resulting HVAC action

Attributes
  • id string<uuid>

    The ID of the action.

  • userId string

    The ID of the user that owns the target of this action.

  • createdAt string<date-time>

    Time when this action was created

  • updatedAt string<date-time>

    Time when this action was last updated

  • completedAt string<date-time> or null

    Time when the action transitioned to a non-pending state.

  • state string

    The real-time status of an action executed on a target.

    • PENDING: The initial state. Enode is actively sending commands and monitoring the target for changes.
    • CONFIRMED: Successful transition of the target to the desired state.
    • FAILED: The target did not respond to the action before timing out. Enode has ceased sending additional commands.
    • CANCELLED: A required precondition was not met during the action's timeout window or another action has been sent to the target, overriding this one.

    Possible enum values:

      PENDINGCONFIRMEDFAILEDCANCELLED
  • targetId string

    ID of the entity asset (HVAC) which this action is controlling.

  • targetType string

    Possible enum values:

      hvac
  • target object
    Show child attributes
    • target.holdType string

      Possible enum values:

        SCHEDULED

Response example

{
  "id": "4eaeb363-296d-4ccc-a973-7805e6f400bd",
  "userId": "d5bd4771-864e-4ae5-b913-dfb5cdcd5772",
  "createdAt": "2020-04-07T17:04:26Z",
  "updatedAt": "2020-04-07T17:04:26Z",
  "completedAt": "2020-04-07T17:04:26Z",
  "state": "PENDING",
  "targetId": "string",
  "targetType": "hvac",
  "target": {
    "holdType": "SCHEDULED"
  }
}

Response 400

A precondition check failed that is unlikely to change within the action's timeout window. This occurs if the HVAC unit cannot perform the action.

Attributes
  • type string

    A URI reference that identifies the problem type.

  • title string

    A short, human-readable summary of the problem type.

  • detail string

    A human-readable explanation specific to this occurrence of the problem.

Response example

{
  "type": "https://developers.enode.com/api/problems/not-found",
  "title": "Not Found",
  "detail": "The requested asset wasn't found."
}

Response 422

HVAC unit controlled by an Enode Schedule

Attributes
  • type string

    A URI reference that identifies the problem type.

  • title string

    A short, human-readable summary of the problem type.

  • detail string

    A human-readable explanation specific to this occurrence of the problem.

Response example

{
  "type": "https://developers.enode.com/api/problems/not-found",
  "title": "Not Found",
  "detail": "The requested asset wasn't found."
}
Was this section helpful?

Refresh HVAC unit data

POST /hvacs/{hvacId}/refresh-hint

Use this endpoint to initiate an expedited data refresh for the specified HVAC unit.

Note: The Enode platform keeps data automatically up-to-date and detects changes in the OEM APIs within seconds to a few minutes. We change the refresh interval dynamically based on a number of heuristics. This ensures we find the best trade-off between the stability of the connection to the OEM and freshness of the data.
This method overrides most of our heuristics and should therefore be used with caution. You may use it when you have a strong reason to believe the data might be stale.

Request

Path parameters
hvacId string Required

ID of the HVAC unit.

Request example

curl --request POST \
  --url https://enode-api.production.enode.io/hvacs/8f39fa8d-8f10-4984-a319-741dc23848c0/refresh-hint \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response 204

Refresh hint registered successfully.

Response 404

The specified hvac was not found.

Was this section helpful?

Set HVAC unit mode as permanent hold

POST /hvacs/{hvacId}/permanent-hold

Tell an HVAC unit to enter a permanent hold. Only available if the target's capabilities.setPermanentHold.isCapable is set to true. We retry sending the command until the HVAC unit's target field transition to the expected value. Note that this request will complete before any commands are sent to the HVAC unit. You may react to transitions by listening for the user:vendor-action:updated webhook event or polling the HVAC action endpointAPI.

Request

Path parameters
hvacId string Required

ID of the HVAC unit.

Attributes
  • coolSetpoint number Required
  • mode string Required

    Possible enum values:

      COOL

Request example

curl --request POST \
  --url https://enode-api.production.enode.io/hvacs/8f39fa8d-8f10-4984-a319-741dc23848c0/permanent-hold \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"coolSetpoint":0,"mode":"COOL"}'

Response 200

Resulting action

Attributes
  • id string<uuid>

    The ID of the action.

  • userId string

    The ID of the user that owns the target of this action.

  • createdAt string<date-time>

    Time when this action was created

  • updatedAt string<date-time>

    Time when this action was last updated

  • completedAt string<date-time> or null

    Time when the action transitioned to a non-pending state.

  • state string

    The real-time status of an action executed on a target.

    • PENDING: The initial state. Enode is actively sending commands and monitoring the target for changes.
    • CONFIRMED: Successful transition of the target to the desired state.
    • FAILED: The target did not respond to the action before timing out. Enode has ceased sending additional commands.
    • CANCELLED: A required precondition was not met during the action's timeout window or another action has been sent to the target, overriding this one.

    Possible enum values:

      PENDINGCONFIRMEDFAILEDCANCELLED
  • targetId string

    ID of the entity asset (HVAC) which this action is controlling.

  • targetType string

    Possible enum values:

      hvac
  • target

Response example

{
  "id": "4eaeb363-296d-4ccc-a973-7805e6f400bd",
  "userId": "d5bd4771-864e-4ae5-b913-dfb5cdcd5772",
  "createdAt": "2020-04-07T17:04:26Z",
  "updatedAt": "2020-04-07T17:04:26Z",
  "completedAt": "2020-04-07T17:04:26Z",
  "state": "PENDING",
  "targetId": "string",
  "targetType": "hvac",
  "target": {
    "coolSetpoint": 0,
    "mode": "COOL",
    "holdType": "PERMANENT"
  }
}

Response 400

A precondition check failed that is unlikely to change within the action's timeout window. This occurs if the HVAC unit cannot perform the action or the setpoints are invalid.

Attributes
  • type string

    A URI reference that identifies the problem type.

  • title string

    A short, human-readable summary of the problem type.

  • detail string

    A human-readable explanation specific to this occurrence of the problem.

Response example

{
  "type": "https://developers.enode.com/api/problems/not-found",
  "title": "Not Found",
  "detail": "The requested asset wasn't found."
}

Response 422

HVAC unit controlled by an Enode Schedule

Attributes
  • type string

    A URI reference that identifies the problem type.

  • title string

    A short, human-readable summary of the problem type.

  • detail string

    A human-readable explanation specific to this occurrence of the problem.

Response example

{
  "type": "https://developers.enode.com/api/problems/not-found",
  "title": "Not Found",
  "detail": "The requested asset wasn't found."
}
Was this section helpful?

Interventions

Endpoints that return information about interventions. More information and examples are available in the Interventions guide.

List interventions

GET /interventions

Returns a list of all supported interventions.

The language parameter can be used to specify the language of the resolution title and description.

Request

Query parameters
language string Optional

Preferred BCP47 language code - Request translation for the specified language. Falls back to en-US if not provided or provided language code is unsupported.

Possible enum values:

    en-USen-GBde-DEfr-FRes-ESpt-PTnl-NLnl-BEnb-NOsv-SEda-DKfi-FIro-RO
vendorType string Optional

Only return interventions for the specified vendor type.

Possible enum values:

    vehiclechargerhvacinverterbatterymeter
vendor string Optional

Only return interventions for the specified vendor.

Possible enum values:

    APSYSTEMSCSISolarDeyeENPHASEFOXESSFRONIUSGOODWEGROWATTHoymilesHUAWEIINVTSMASOFARSOLAREDGESOLARKSOLAXSOLISSOLPLANETSUNGROWSUNSYNKTESLATSUNAUDIBMWHONDAHYUNDAIJAGUARLANDROVERKIAMERCEDESMININISSANPEUGEOTPORSCHERENAULTSEATSKODAVOLKSWAGENVOLVOFORDOPELDSTOYOTALEXUSCITROENCUPRAVAUXHALLFIATRIVIANNIOCHEVROLETGMCCADILLACXPENGSUBARUTADOMILLADAXECOBEESENSIBOHONEYWELLRESIDEOMITSUBISHIMICROMATICNIBEPANASONICTOSHIBADAIKINNESTFUJITSUBOSCHNETATMOZAPTECEASEEWALLBOXEOCHARGEAMPSEVBOXGOECHARGEPOINTENELXOHMEGAROSCHNEIDERPODPOINT

Request example

curl --request GET \
  --url 'https://enode-api.production.enode.io/interventions?language=SOME_STRING_VALUE&vendorType=SOME_undefined_VALUE&vendor=TESLA' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response 200

Attributes (list of undefined)

    Response example

    [
      {
        "id": "9d90a9ad-9b24-4ce0-94e9-e888b1b877f4",
        "vendor": "AUDI",
        "vendorType": "string",
        "brand": "Audi",
        "introducedAt": "2023-03-16T00:00:00",
        "domain": "Account",
        "resolution": {
          "title": "Accept the Audi terms and conditions",
          "description": "To gain access to your vehicle's telemetry data, it's necessary to accept Audi's terms and conditions. Follow these steps to proceed:<br><br>1. Open the **myAudi app** on your phone<br>2. Follow the prompts to accept Audi's terms and conditions",
          "access": "Remote",
          "agent": "User"
        }
      }
    ]
    Was this section helpful?

    Get intervention

    GET /interventions/{interventionId}

    Returns a single intervention.

    The language parameter can be used to specify the language of the resolution title and description.

    Request

    Path parameters
    interventionId string<uuid> Required

    ID of the intervention.

    Query parameters
    language string Optional

    Preferred BCP47 language code - Request translation for the specified language. Falls back to en-US if not provided or provided language code is unsupported.

    Possible enum values:

      en-USen-GBde-DEfr-FRes-ESpt-PTnl-NLnl-BEnb-NOsv-SEda-DKfi-FIro-RO
    vendorType string Optional

    Only return interventions for the specified vendor type.

    Possible enum values:

      vehiclechargerhvacinverterbatterymeter
    vendor string Optional

    Only return interventions for the specified vendor.

    Possible enum values:

      APSYSTEMSCSISolarDeyeENPHASEFOXESSFRONIUSGOODWEGROWATTHoymilesHUAWEIINVTSMASOFARSOLAREDGESOLARKSOLAXSOLISSOLPLANETSUNGROWSUNSYNKTESLATSUNAUDIBMWHONDAHYUNDAIJAGUARLANDROVERKIAMERCEDESMININISSANPEUGEOTPORSCHERENAULTSEATSKODAVOLKSWAGENVOLVOFORDOPELDSTOYOTALEXUSCITROENCUPRAVAUXHALLFIATRIVIANNIOCHEVROLETGMCCADILLACXPENGSUBARUTADOMILLADAXECOBEESENSIBOHONEYWELLRESIDEOMITSUBISHIMICROMATICNIBEPANASONICTOSHIBADAIKINNESTFUJITSUBOSCHNETATMOZAPTECEASEEWALLBOXEOCHARGEAMPSEVBOXGOECHARGEPOINTENELXOHMEGAROSCHNEIDERPODPOINT

    Request example

    curl --request GET \
      --url 'https://enode-api.production.enode.io/interventions/ad84e742-0f46-4cf4-b0db-7d890f8f23f5?language=SOME_STRING_VALUE&vendorType=SOME_undefined_VALUE&vendor=TESLA' \
      --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

    Response 200

    Attributes
    • id string<uuid>
    • vendor string

      Machine-friendly representation of the OEM's name.

      Possible enum values:

        APSYSTEMSCSISolarDeyeENPHASEFOXESSFRONIUSGOODWEGROWATTHoymilesHUAWEIINVTSMASOFARSOLAREDGESOLARKSOLAXSOLISSOLPLANETSUNGROWSUNSYNKTESLATSUNAUDIBMWHONDAHYUNDAIJAGUARLANDROVERKIAMERCEDESMININISSANPEUGEOTPORSCHERENAULTSEATSKODAVOLKSWAGENVOLVOFORDOPELDSTOYOTALEXUSCITROENCUPRAVAUXHALLFIATRIVIANNIOCHEVROLETGMCCADILLACXPENGSUBARUTADOMILLADAXECOBEESENSIBOHONEYWELLRESIDEOMITSUBISHIMICROMATICNIBEPANASONICTOSHIBADAIKINNESTFUJITSUBOSCHNETATMOZAPTECEASEEWALLBOXEOCHARGEAMPSEVBOXGOECHARGEPOINTENELXOHMEGAROSCHNEIDERPODPOINT
    • vendorType string

      Type of device this intervention relates to.

      Possible enum values:

        vehiclechargerhvacinverterbatterymeter
    • brand string

      A formatted and properly cased OEM brand name, suitable for reading by humans. May contain special characters.

      Possible enum values:

        APsystemsCSISolarDeyeEnphaseFOXESSFroniusGoodWeGrowattHoymilesHuaweiINVTSMASofarSolarEdgeSolArkSolaxSolisSolplanetSungrowSUNSYNKTeslaTSUNAudiBMWHondaHyundaiJaguarLand RoverKiaMercedesMININissanPeugeotPorscheRenaultSEATŠKODAVolkswagenVolvoFordOpelDSToyotaLexusCitroënCupraVauxhallFiatRivianNioChevroletGMCCadillacXPENGSubaruTadoMillADAXEcobeeSensiboHoneywell TCCResideoMitsubishiMicro MaticNIBEPanasonicToshibaDAIKINNestFujitsuBoschNetatmoZaptecEaseeWallboxEOEVBoxCharge Ampsgo-eChargePointEnel XOhmeGaroSchneider ElectricPod PointHUAWEI
    • introducedAt string<date-time>

      ISO 8601 timestamp of when the intervention was introduced.

    • domain string

      The domain the intervention is related to. i.e. Is the intervention related to the vendor service account or a setting on the device.

      Possible enum values:

        AccountDevice
    • resolution object
      Show child attributes
      • resolution.title string

        A localized title for the intervention.

      • resolution.description string

        A localized description of how to resolve the intervention. Formatted as Markdown.

      • resolution.access string

        Where the intervention needs to be resolved. i.e. remotely using the vendor's app or directly on the device.

        Possible enum values:

          RemotePhysical
      • resolution.agent string

        Who can resolve the intervention. i.e. a user can resolve the intervention themselves, or a licensed service retailer is needed.

        Possible enum values:

          UserThirdParty

    Response example

    {
      "id": "9d90a9ad-9b24-4ce0-94e9-e888b1b877f4",
      "vendor": "AUDI",
      "vendorType": "string",
      "brand": "Audi",
      "introducedAt": "2023-03-16T00:00:00",
      "domain": "Account",
      "resolution": {
        "title": "Accept the Audi terms and conditions",
        "description": "To gain access to your vehicle's telemetry data, it's necessary to accept Audi's terms and conditions. Follow these steps to proceed:<br><br>1. Open the **myAudi app** on your phone<br>2. Follow the prompts to accept Audi's terms and conditions",
        "access": "Remote",
        "agent": "User"
      }
    }

    Response 404

    Intervention not found.

    Was this section helpful?

    Locations

    Locations are used to assign devices to a geographical group. This is useful when running schedules, smart charging, or smart heating, as target behavior usually depends on a common locality of demand (charging, heating, cooling, etc.) and supply (tariff, battery, inverter, etc.) of energy.

    List locations

    GET /locations

    Returns a paginated list of all Locations.

    Request

    Query parameters
    after string Optional
    before string Optional
    pageSize integer Optional

    Default value: 50

    Request example

    curl --request GET \
      --url 'https://enode-api.production.enode.io/locations?after=MjAyMy0wNy0xOFQxMDowODowMi4zNzNa&before=MjAyMy0wNy0xOFQxMDowODowMi4zNzNa&pageSize=50' \
      --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

    Response 200

    Attributes
    • data array of object

      Paginated list of locations

      Show child attributes
      • data[].id string<uuid>

        The ID of the Location.

      • data[].userId string

        User ID the location belongs to

      • data[].name string

        User-supplied name for the Location

      • data[].latitude number

        Latitude in degrees

      • data[].longitude number

        Longitude in degrees

      • data[].timezoneName string

        An IANA TZ database timezone name. This value will be used to convert rules and deadlines for tariffs, smart charging, and schedules into local time. Defaults to UTC.

        Default value: UTC

    • pagination object

      Cursors to the pages before and after current page. See the PaginationAPI section for reference.

      Show child attributes
      • pagination.after string or null
      • pagination.before string or null

    Response example

    {
      "data": [
        {
          "id": "4eaeb363-296d-4ccc-a973-7805e6f400bd",
          "userId": "0fc4b1e7-9bdf-4958-b343-86eff3d9f92f",
          "name": "Enode",
          "latitude": 59.9165915,
          "longitude": 10.7582268,
          "timezoneName": "Europe/Oslo"
        }
      ],
      "pagination": {
        "after": "MjAyMy0wNy0xOFQxMDowODowMi4zNzNa",
        "before": "MjAyMy0wNi0xNlQwOTowMzowMS4yNjJa"
      }
    }
    Was this section helpful?

    List user locations

    GET /users/{userId}/locations

    Returns a paginated list of Locations for the given user.

    Request

    Path parameters
    userId string Required

    ID of the User.

    Query parameters
    after string Optional
    before string Optional
    pageSize integer Optional

    Default value: 50

    Request example

    curl --request GET \
      --url 'https://enode-api.production.enode.io/users/%7BuserId%7D/locations?after=MjAyMy0wNy0xOFQxMDowODowMi4zNzNa&before=MjAyMy0wNy0xOFQxMDowODowMi4zNzNa&pageSize=50' \
      --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

    Response 200

    Attributes
    • data array of object

      Paginated list of locations

      Show child attributes
      • data[].id string<uuid>

        The ID of the Location.

      • data[].userId string

        User ID the location belongs to

      • data[].name string

        User-supplied name for the Location

      • data[].latitude number

        Latitude in degrees

      • data[].longitude number

        Longitude in degrees

      • data[].timezoneName string

        An IANA TZ database timezone name. This value will be used to convert rules and deadlines for tariffs, smart charging, and schedules into local time. Defaults to UTC.

        Default value: UTC

    • pagination object

      Cursors to the pages before and after current page. See the PaginationAPI section for reference.

      Show child attributes
      • pagination.after string or null
      • pagination.before string or null

    Response example

    {
      "data": [
        {
          "id": "4eaeb363-296d-4ccc-a973-7805e6f400bd",
          "userId": "0fc4b1e7-9bdf-4958-b343-86eff3d9f92f",
          "name": "Enode",
          "latitude": 59.9165915,
          "longitude": 10.7582268,
          "timezoneName": "Europe/Oslo"
        }
      ],
      "pagination": {
        "after": "MjAyMy0wNy0xOFQxMDowODowMi4zNzNa",
        "before": "MjAyMy0wNi0xNlQwOTowMzowMS4yNjJa"
      }
    }
    Was this section helpful?

    Create location

    POST /users/{userId}/locations

    Create a Location for a User.

    Request

    Path parameters
    userId string Required

    ID of the User.

    Attributes
    • name string Required

      User-supplied name for the Location

    • latitude number Required

      Latitude in degrees

    • longitude number Required

      Longitude in degrees

    • timezoneName string Required

      An IANA TZ database timezone name. This value will be used to convert rules and deadlines for tariffs, smart charging, and schedules into local time. Defaults to UTC.

      Default value: UTC

    Request example

    curl --request POST \
      --url https://enode-api.production.enode.io/users/%7BuserId%7D/locations \
      --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
      --header 'content-type: application/json' \
      --data '{"name":"Enode","latitude":59.9165915,"longitude":10.7582268,"timezoneName":"Europe/Oslo"}'

    Response 200

    Created

    Attributes
    • id string<uuid>

      The ID of the Location.

    • userId string

      User ID the location belongs to

    • name string

      User-supplied name for the Location

    • latitude number

      Latitude in degrees

    • longitude number

      Longitude in degrees

    • timezoneName string

      An IANA TZ database timezone name. This value will be used to convert rules and deadlines for tariffs, smart charging, and schedules into local time. Defaults to UTC.

      Default value: UTC

    Response example

    {
      "id": "4eaeb363-296d-4ccc-a973-7805e6f400bd",
      "userId": "0fc4b1e7-9bdf-4958-b343-86eff3d9f92f",
      "name": "Enode",
      "latitude": 59.9165915,
      "longitude": 10.7582268,
      "timezoneName": "Europe/Oslo"
    }
    Was this section helpful?

    Get location

    GET /locations/{locationId}

    Fetch a Location.

    Request

    Path parameters
    locationId string<uuid> Required

    ID of the Location.

    Request example

    curl --request GET \
      --url https://enode-api.production.enode.io/locations/4eaeb363-296d-4ccc-a973-7805e6f400bd \
      --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

    Response 200

    Attributes
    • id string<uuid>

      The ID of the Location.

    • userId string

      User ID the location belongs to

    • name string

      User-supplied name for the Location

    • latitude number

      Latitude in degrees

    • longitude number

      Longitude in degrees

    • timezoneName string

      An IANA TZ database timezone name. This value will be used to convert rules and deadlines for tariffs, smart charging, and schedules into local time. Defaults to UTC.

      Default value: UTC

    Response example

    {
      "id": "4eaeb363-296d-4ccc-a973-7805e6f400bd",
      "userId": "0fc4b1e7-9bdf-4958-b343-86eff3d9f92f",
      "name": "Enode",
      "latitude": 59.9165915,
      "longitude": 10.7582268,
      "timezoneName": "Europe/Oslo"
    }
    Was this section helpful?

    Delete location

    DELETE /locations/{locationId}

    Delete a Location.

    Request

    Path parameters
    locationId string<uuid> Required

    ID of the Location.

    Request example

    curl --request DELETE \
      --url https://enode-api.production.enode.io/locations/4eaeb363-296d-4ccc-a973-7805e6f400bd \
      --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

    Response 200

    Attributes
    • id string<uuid>

      The ID of the Location.

    • userId string

      User ID the location belongs to

    • name string

      User-supplied name for the Location

    • latitude number

      Latitude in degrees

    • longitude number

      Longitude in degrees

    • timezoneName string

      An IANA TZ database timezone name. This value will be used to convert rules and deadlines for tariffs, smart charging, and schedules into local time. Defaults to UTC.

      Default value: UTC

    Response example

    {
      "id": "4eaeb363-296d-4ccc-a973-7805e6f400bd",
      "userId": "0fc4b1e7-9bdf-4958-b343-86eff3d9f92f",
      "name": "Enode",
      "latitude": 59.9165915,
      "longitude": 10.7582268,
      "timezoneName": "Europe/Oslo"
    }
    Was this section helpful?

    Update location

    PUT /locations/{locationId}

    Updates a location.

    Request

    Path parameters
    locationId string<uuid> Required

    ID of the Location.

    Attributes
    • name string Required

      User-supplied name for the Location

    • latitude number Required

      Latitude in degrees

    • longitude number Required

      Longitude in degrees

    • timezoneName string Required

      An IANA TZ database timezone name. This value will be used to convert rules and deadlines for tariffs, smart charging, and schedules into local time. Defaults to UTC.

      Default value: UTC

    Request example

    curl --request PUT \
      --url https://enode-api.production.enode.io/locations/4eaeb363-296d-4ccc-a973-7805e6f400bd \
      --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
      --header 'content-type: application/json' \
      --data '{"name":"Enode","latitude":59.9165915,"longitude":10.7582268,"timezoneName":"Europe/Oslo"}'

    Response 200

    Attributes
    • id string<uuid>

      The ID of the Location.

    • userId string

      User ID the location belongs to

    • name string

      User-supplied name for the Location

    • latitude number

      Latitude in degrees

    • longitude number

      Longitude in degrees

    • timezoneName string

      An IANA TZ database timezone name. This value will be used to convert rules and deadlines for tariffs, smart charging, and schedules into local time. Defaults to UTC.

      Default value: UTC

    Response example

    {
      "id": "4eaeb363-296d-4ccc-a973-7805e6f400bd",
      "userId": "0fc4b1e7-9bdf-4958-b343-86eff3d9f92f",
      "name": "Enode",
      "latitude": 59.9165915,
      "longitude": 10.7582268,
      "timezoneName": "Europe/Oslo"
    }
    Was this section helpful?

    Meters

    The Meter object represents a unit responsible for measuring energy usage. It provides detailed information about the meter itself and the energy consumption data it records.

    Get meterBeta

    GET /meters/{meterId}

    Request

    Path parameters
    meterId string<uuid> Required

    The ID of the meter you are looking up

    Request example

    curl --request GET \
      --url https://enode-api.production.enode.io/meters/54d827e1-8355-4fed-97b5-55940d1d09ba

    Response 200

    Attributes
    • id string<uuid>

      Unique identifier for the meter object

    • userId string

      The ID of the user that linked this meter.

    • vendor string

      Machine-friendly name of the vendor. Use this in API requests.

      Possible enum values:

        ENPHASEHUAWEITESLASMASOLAREDGE
    • lastSeen string<date-time>

      The last time Enode successfully communicated with the vendor or when the meter was initially linked.

    • isReachable boolean

      Indicates whether Enode can currently access live data from the meter. If the meter is not reachable, data updates will be delayed.

    • information object

      Descriptive information about the meter

      Show child attributes
      • information.brand string

        A formatted and properly cased OEM brand name, suitable for reading by humans. May contain special characters.

        Possible enum values:

          EnphaseHuaweiTeslaSMASolarEdge
      • information.model string

        Meter model

      • information.siteName string

        Name of the site, as set by the user on the device/vendor. If no user-specified name is available, we construct a fallback name using the vendor/device/model names.

      • information.installationDate string<date-time>

        Meter installation date

    • energyState object

      Latest information about meter load. null values indicate we are unable to determine a value for the field based on the information coming from the vendor.

      Show child attributes
      • energyState.power number or null

        Indicates the current load on the meter.

        • Positive value: Power is imported from the grid to the site, indicating consumption.
        • Negative value: Power is exported back to the grid, typically when the site generates excess electricity (e.g. from solar panels, or battery discharge).
      • energyState.lastUpdated string<date-time> or null

        Time of last received energy state update.

    • location object

      Meter's GPS coordinates

      Show child attributes
      • location.id string<uuid> or null

        ID of the location the solar battery is currently positioned at (if any).

      • location.longitude number or null

        Longitude in degrees

      • location.latitude number or null

        Latitude in degrees

      • location.lastUpdated string<date-time> or null

        Time of last received location state update

    • capabilities object

      The specific meter's capabilities for recording energy consumption and production data.

      Show child attributes
      • capabilities.measuresConsumption object

        Indicates if the meter can measure consumed energy.

        Show child attributes
        • capabilities.measuresConsumption.isCapable boolean

          The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

        • capabilities.measuresConsumption.interventionIds array of string

          IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

      • capabilities.measuresProduction object

        Indicates if the meter can measure energy produced or generated.

        Show child attributes
        • capabilities.measuresProduction.isCapable boolean

          The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

        • capabilities.measuresProduction.interventionIds array of string

          IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

    • scopes array of string

      Scopes that the user has granted for this meter.

    Response example

    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "userId": "string",
      "vendor": "TESLA",
      "lastSeen": "2020-04-07T17:04:26Z",
      "isReachable": true,
      "information": {
        "brand": "Tesla",
        "model": "Tesla Powerwall built-in meter",
        "siteName": "Powerwall Home",
        "installationDate": "2020-04-07T17:04:26Z"
      },
      "energyState": {
        "power": 2.2,
        "lastUpdated": "2022-03-01T12:34:56Z"
      },
      "location": {
        "id": "8d90101b-3f2f-462a-bbb4-1ed320d33bbe",
        "longitude": 10.7197486,
        "latitude": 59.9173985,
        "lastUpdated": "2024-01-07T17:04:26.000Z"
      },
      "capabilities": {
        "measuresConsumption": {
          "isCapable": false,
          "interventionIds": [
            "4eaeb363-296d-4ccc-a973-7805e6f400bd"
          ]
        },
        "measuresProduction": {
          "isCapable": false,
          "interventionIds": [
            "4eaeb363-296d-4ccc-a973-7805e6f400bd"
          ]
        }
      },
      "scopes": [
        "meter:read:data",
        "meter:read:location"
      ]
    }
    Was this section helpful?

    Refresh meter dataBeta

    POST /meters/{meterId}/refresh-hint

    Use this endpoint to initiate an expedited data refresh for the specified meter.

    Note: The Enode platform keeps data automatically up-to-date and detects changes in the OEM APIs within seconds to a few minutes. We change the refresh interval dynamically based on a number of heuristics. This ensures we find the best trade-off between the stability of the connection to the OEM and freshness of the data.
    This method overrides most of our heuristics and should therefore be used with caution. You may use it when you have a strong reason to believe the data might be stale.

    Request

    Path parameters
    meterId string<uuid> Required

    The ID of the meter you are looking up

    Request example

    curl --request POST \
      --url https://enode-api.production.enode.io/meters/54d827e1-8355-4fed-97b5-55940d1d09ba/refresh-hint \
      --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

    Response 204

    Refresh hint registered successfully.

    Response 404

    The specified meter was not found.

    Was this section helpful?

    List user metersBeta

    GET /users/{userId}/meters

    Returns a paginated list of meters for the given userId.

    Request

    Path parameters
    userId string Required

    ID of the User.

    Query parameters
    after string Optional
    before string Optional
    pageSize integer Optional

    Default value: 50

    Request example

    curl --request GET \
      --url 'https://enode-api.production.enode.io/users/%7BuserId%7D/meters?after=MjAyMy0wNy0xOFQxMDowODowMi4zNzNa&before=MjAyMy0wNy0xOFQxMDowODowMi4zNzNa&pageSize=50' \
      --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

    Response 200

    Attributes
    • data array of object

      Paginated list of meters

      Show child attributes
      • data[].id string<uuid>

        Unique identifier for the meter object

      • data[].userId string

        The ID of the user that linked this meter.

      • data[].vendor string

        Machine-friendly name of the vendor. Use this in API requests.

        Possible enum values:

          ENPHASEHUAWEITESLASMASOLAREDGE
      • data[].lastSeen string<date-time>

        The last time Enode successfully communicated with the vendor or when the meter was initially linked.

      • data[].isReachable boolean

        Indicates whether Enode can currently access live data from the meter. If the meter is not reachable, data updates will be delayed.

      • data[].information object

        Descriptive information about the meter

        Show child attributes
        • data[].information.brand string

          A formatted and properly cased OEM brand name, suitable for reading by humans. May contain special characters.

          Possible enum values:

            EnphaseHuaweiTeslaSMASolarEdge
        • data[].information.model string

          Meter model

        • data[].information.siteName string

          Name of the site, as set by the user on the device/vendor. If no user-specified name is available, we construct a fallback name using the vendor/device/model names.

        • data[].information.installationDate string<date-time>

          Meter installation date

      • data[].energyState object

        Latest information about meter load. null values indicate we are unable to determine a value for the field based on the information coming from the vendor.

        Show child attributes
        • data[].energyState.power number or null

          Indicates the current load on the meter.

          • Positive value: Power is imported from the grid to the site, indicating consumption.
          • Negative value: Power is exported back to the grid, typically when the site generates excess electricity (e.g. from solar panels, or battery discharge).
        • data[].energyState.lastUpdated string<date-time> or null

          Time of last received energy state update.

      • data[].location object

        Meter's GPS coordinates

        Show child attributes
        • data[].location.id string<uuid> or null

          ID of the location the solar battery is currently positioned at (if any).

        • data[].location.longitude number or null

          Longitude in degrees

        • data[].location.latitude number or null

          Latitude in degrees

        • data[].location.lastUpdated string<date-time> or null

          Time of last received location state update

      • data[].capabilities object

        The specific meter's capabilities for recording energy consumption and production data.

        Show child attributes
        • data[].capabilities.measuresConsumption object

          Indicates if the meter can measure consumed energy.

          Show child attributes
          • data[].capabilities.measuresConsumption.isCapable boolean

            The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

          • data[].capabilities.measuresConsumption.interventionIds array of string

            IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

        • data[].capabilities.measuresProduction object

          Indicates if the meter can measure energy produced or generated.

          Show child attributes
          • data[].capabilities.measuresProduction.isCapable boolean

            The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

          • data[].capabilities.measuresProduction.interventionIds array of string

            IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

      • data[].scopes array of string

        Scopes that the user has granted for this meter.

    • pagination object

      Cursors to the pages before and after current page. See the PaginationAPI section for reference.

      Show child attributes
      • pagination.after string or null
      • pagination.before string or null

    Response example

    {
      "data": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "userId": "string",
          "vendor": "TESLA",
          "lastSeen": "2020-04-07T17:04:26Z",
          "isReachable": true,
          "information": {
            "brand": "Tesla",
            "model": "Tesla Powerwall built-in meter",
            "siteName": "Powerwall Home",
            "installationDate": "2020-04-07T17:04:26Z"
          },
          "energyState": {
            "power": 2.2,
            "lastUpdated": "2022-03-01T12:34:56Z"
          },
          "location": {
            "id": "8d90101b-3f2f-462a-bbb4-1ed320d33bbe",
            "longitude": 10.7197486,
            "latitude": 59.9173985,
            "lastUpdated": "2024-01-07T17:04:26.000Z"
          },
          "capabilities": {
            "measuresConsumption": {
              "isCapable": false,
              "interventionIds": [
                "4eaeb363-296d-4ccc-a973-7805e6f400bd"
              ]
            },
            "measuresProduction": {
              "isCapable": false,
              "interventionIds": [
                "4eaeb363-296d-4ccc-a973-7805e6f400bd"
              ]
            }
          },
          "scopes": [
            "meter:read:data",
            "meter:read:location"
          ]
        }
      ],
      "pagination": {
        "after": "MjAyMy0wNy0xOFQxMDowODowMi4zNzNa",
        "before": "MjAyMy0wNi0xNlQwOTowMzowMS4yNjJa"
      }
    }
    Was this section helpful?

    List metersBeta

    GET /meters

    Returns a paginated list of all Meters.

    Request

    Query parameters
    after string Optional
    before string Optional
    pageSize integer Optional

    Default value: 50

    Request example

    curl --request GET \
      --url 'https://enode-api.production.enode.io/meters?after=MjAyMy0wNy0xOFQxMDowODowMi4zNzNa&before=MjAyMy0wNy0xOFQxMDowODowMi4zNzNa&pageSize=50' \
      --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

    Response 200

    Attributes
    • data array of object

      Paginated list of meters

      Show child attributes
      • data[].id string<uuid>

        Unique identifier for the meter object

      • data[].userId string

        The ID of the user that linked this meter.

      • data[].vendor string

        Machine-friendly name of the vendor. Use this in API requests.

        Possible enum values:

          ENPHASEHUAWEITESLASMASOLAREDGE
      • data[].lastSeen string<date-time>

        The last time Enode successfully communicated with the vendor or when the meter was initially linked.

      • data[].isReachable boolean

        Indicates whether Enode can currently access live data from the meter. If the meter is not reachable, data updates will be delayed.

      • data[].information object

        Descriptive information about the meter

        Show child attributes
        • data[].information.brand string

          A formatted and properly cased OEM brand name, suitable for reading by humans. May contain special characters.

          Possible enum values:

            EnphaseHuaweiTeslaSMASolarEdge
        • data[].information.model string

          Meter model

        • data[].information.siteName string

          Name of the site, as set by the user on the device/vendor. If no user-specified name is available, we construct a fallback name using the vendor/device/model names.

        • data[].information.installationDate string<date-time>

          Meter installation date

      • data[].energyState object

        Latest information about meter load. null values indicate we are unable to determine a value for the field based on the information coming from the vendor.

        Show child attributes
        • data[].energyState.power number or null

          Indicates the current load on the meter.

          • Positive value: Power is imported from the grid to the site, indicating consumption.
          • Negative value: Power is exported back to the grid, typically when the site generates excess electricity (e.g. from solar panels, or battery discharge).
        • data[].energyState.lastUpdated string<date-time> or null

          Time of last received energy state update.

      • data[].location object

        Meter's GPS coordinates

        Show child attributes
        • data[].location.id string<uuid> or null

          ID of the location the solar battery is currently positioned at (if any).

        • data[].location.longitude number or null

          Longitude in degrees

        • data[].location.latitude number or null

          Latitude in degrees

        • data[].location.lastUpdated string<date-time> or null

          Time of last received location state update

      • data[].capabilities object

        The specific meter's capabilities for recording energy consumption and production data.

        Show child attributes
        • data[].capabilities.measuresConsumption object

          Indicates if the meter can measure consumed energy.

          Show child attributes
          • data[].capabilities.measuresConsumption.isCapable boolean

            The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

          • data[].capabilities.measuresConsumption.interventionIds array of string

            IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

        • data[].capabilities.measuresProduction object

          Indicates if the meter can measure energy produced or generated.

          Show child attributes
          • data[].capabilities.measuresProduction.isCapable boolean

            The entity is fully capable of providing this data or functionality. If false, support is partial or missing.

          • data[].capabilities.measuresProduction.interventionIds array of string

            IDs of interventions the user can make to alter the availability of this capability. Please refer to the interventions guide for more information.

      • data[].scopes array of string

        Scopes that the user has granted for this meter.

    • pagination object

      Cursors to the pages before and after current page. See the PaginationAPI section for reference.

      Show child attributes
      • pagination.after string or null
      • pagination.before string or null

    Response example

    {
      "data": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "userId": "string",
          "vendor": "TESLA",
          "lastSeen": "2020-04-07T17:04:26Z",
          "isReachable": true,
          "information": {
            "brand": "Tesla",
            "model": "Tesla Powerwall built-in meter",
            "siteName": "Powerwall Home",
            "installationDate": "2020-04-07T17:04:26Z"
          },
          "energyState": {
            "power": 2.2,
            "lastUpdated": "2022-03-01T12:34:56Z"
          },
          "location": {
            "id": "8d90101b-3f2f-462a-bbb4-1ed320d33bbe",
            "longitude": 10.7197486,
            "latitude": 59.9173985,
            "lastUpdated": "2024-01-07T17:04:26.000Z"
          },
          "capabilities": {
            "measuresConsumption": {
              "isCapable": false,
              "interventionIds": [
                "4eaeb363-296d-4ccc-a973-7805e6f400bd"
              ]
            },
            "measuresProduction": {
              "isCapable": false,
              "interventionIds": [
                "4eaeb363-296d-4ccc-a973-7805e6f400bd"
              ]
            }
          },
          "scopes": [
            "meter:read:data",
            "meter:read:location"
          ]
        }
      ],
      "pagination": {
        "after": "MjAyMy0wNy0xOFQxMDowODowMi4zNzNa",
        "before": "MjAyMy0wNi0xNlQwOTowMzowMS4yNjJa"
      }
    }
    Was this section helpful?

    Schedules

    Endpoints to manage schedules for Vehicles, Chargers and HVACs.

    More information and examples are available in the Scheduling guide.

    List schedules

    GET /users/{userId}/schedules

    Returns a list of Schedules registered to the User.

    Request

    Path parameters
    userId string Required

    ID of the User.

    Query parameters
    after string Optional
    before string Optional
    pageSize integer Optional

    Default value: 50

    Request example

    curl --request GET \
      --url 'https://enode-api.production.enode.io/users/%7BuserId%7D/schedules?after=MjAyMy0wNy0xOFQxMDowODowMi4zNzNa&before=MjAyMy0wNy0xOFQxMDowODowMi4zNzNa&pageSize=50' \
      --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

    Response 200

    Attributes
    • data array

      Paginated list of schedules

    • pagination object

      Cursors to the pages before and after current page. See the PaginationAPI section for reference.

      Show child attributes
      • pagination.after string or null
      • pagination.before string or null

    Response example

    {
      "data": [
        {
          "isEnabled": true,
          "defaultShouldCharge": true,
          "rules": [
            {
              "hourMinute": {
                "from": "08:00",
                "to": "09:00"
              },
              "fromTimestamp": "2020-04-07T17:04:26Z",
              "toTimestamp": "2020-04-07T17:04:26Z",
              "weekdays": [
                0,
                1,
                2,
                3,
                4,
                5
              ],
              "shouldCharge": true
            }
          ],
          "targetId": "string",
          "targetType": "vehicle",
          "locationId": "4eaeb363-296d-4ccc-a973-7805e6f400bd",
          "id": "string"
        }
      ],
      "pagination": {
        "after": "MjAyMy0wNy0xOFQxMDowODowMi4zNzNa",
        "before": "MjAyMy0wNi0xNlQwOTowMzowMS4yNjJa"
      }
    }
    Was this section helpful?

    Create schedule

    POST /users/{userId}/schedules

    Request

    Path parameters
    userId string Required

    ID of the User.

    Attributes
    • isEnabled boolean Required

      Whether this Schedule should be attempting to control the target's charge state.

      Default value: true

    • defaultShouldCharge boolean Required

      When no rule is active, the default charge state for the target.

    • rules array of object Required

      Each rule sets a value for shouldCharge, either true or false. All other properties of the rule are optional filters that limit the times to which this rule applies.

      Show child attributes
      • rules[].hourMinute object Optional

        An interval composed of two clock times during which this rule applies each day. to always resolves to a timestamp after from, and thus may span across midnight and fall on the next day.

        Show child attributes
        • rules[].hourMinute.from string Required

          Clock time from which this rule should apply each day.

        • rules[].hourMinute.to string Required

          Clock time until which this rule should apply each day.

      • rules[].fromTimestamp string<date-time> Optional

        UTC timestamp from which this rule should apply.

      • rules[].toTimestamp string<date-time> Optional

        UTC timestamp until which this rule should apply.

      • rules[].weekdays array of integer Optional

        An array of weekdays to which this rule should apply. A weekday starts with 0 for Monday and ends with 6 for Sunday.

      • rules[].shouldCharge boolean Required

        Whether a chargeable asset should want to charge while this rule is active.

    • targetId string Required

      ID of the asset (Vehicle/Charger) to which this schedule applies

    • targetType string Required

      Possible enum values:

        vehiclecharger
    • locationId string<uuid> or null Required

      ID of the Location to which this schedule applies. The behavior of a null value differs based on the targetType. For chargers, a null value is essentially ignored and the schedule is applied even if the charger isn't at a location. This is designed to prevent schedules from controlling vehicles at public chargers where the user doesn't pay for electricity.

    Request example

    curl --request POST \
      --url https://enode-api.production.enode.io/users/%7BuserId%7D/schedules \
      --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
      --header 'content-type: application/json' \
      --data '{"isEnabled":true,"defaultShouldCharge":true,"rules":[{"hourMinute":{"from":"08:00","to":"09:00"},"fromTimestamp":"2020-04-07T17:04:26Z","toTimestamp":"2020-04-07T17:04:26Z","weekdays":[0,1,2,3,4,5],"shouldCharge":true}],"targetId":"string","targetType":"vehicle","locationId":"4eaeb363-296d-4ccc-a973-7805e6f400bd"}'

    Response 200

    Attributes
    • isEnabled boolean

      Whether this Schedule should be attempting to control the target's charge state.

      Default value: true

    • defaultShouldCharge boolean

      When no rule is active, the default charge state for the target.

    • rules array of object

      Each rule sets a value for shouldCharge, either true or false. All other properties of the rule are optional filters that limit the times to which this rule applies.

      Show c