# Gridshare API Documentation > Gridshare API documentation by Lunar Energy ## API Reference - [Fleet Management](https://developers.gridshare.com/reference/fleet-management.md): Bring your fleet of 3rd party Distributed Energy Resources (<>) into a single place, enabling apps, fleet management, and simplified workflows. - [Home Energy Management System](https://developers.gridshare.com/reference/energy-management.md): Connect to and optimizes Distributed Energy Resources (<>), enabling you to deliver energy propositions that save cost and carbon for you and your customers. - [Virtual Power Plants](https://developers.gridshare.com/reference/vpp.md): Gridshare's industry leading Virtual Power Plant (<>) engine lets you maximize revenue for your customers and yourself while decarbonizing the grid. - [Topology](https://developers.gridshare.com/reference/topology-key-concepts.md) - [Telemetry](https://developers.gridshare.com/reference/telemetry-key-concepts.md) - [Remote MCP](https://developers.gridshare.com/reference/customer-remote-mcp.md) - [Authentication](https://developers.gridshare.com/reference/authentication-customer.md) - [Devices](https://developers.gridshare.com/reference/devices-customer.md) - [Savings](https://developers.gridshare.com/reference/savings-customer.md) - [List Devices](https://developers.gridshare.com/reference/get_api-v2-devices.md): List all devices. - [Get](https://developers.gridshare.com/reference/get_api-v2-devices-synthid.md): Get a device by ID, along with its static properties. - [Partial Update](https://developers.gridshare.com/reference/patch_api-v2-devices-synthid.md): Update a device - [Get Operation Mode](https://developers.gridshare.com/reference/get_api-v2-devices-synthid-operationmode.md): Get the current Gridshare operation mode of a device. Valid operation modes are: - Simple: Follows the simplest plan possible for the device kind - Schedule: Follows the periodical plan defined for the device - Smart: The AI optimized smart plan for the device - Unknown: The operation mode can not be determined - [Change Operation Mode](https://developers.gridshare.com/reference/put_api-v2-devices-synthid-operationmode.md): Set the Gridshare operation mode. - [Get Telemetry](https://developers.gridshare.com/reference/get_api-v2-devices-synthid-telemetry.md): Get time-bucketed telemetry for a single device sensor stream. `synthId` must be a **sensor ID** from the [Site Topology](https://developers.gridshare.com/reference/topology-key-concepts) endpoint — any node with `"kind": "sensor"`. On most installations the telemetry streams are keyed by derived sensor IDs (e.g. `__GRID_METER_DERIVED`, `__bb_agg`, `__PV_DERIVED`). Querying the bare device ID returns an empty `entries` array for those installations. ## Energy fields `energy_Wh_increment` and `energy_Wh_decrement` are only populated when `include=energy` (or `include=default,energy`) is requested: - `energy_Wh_increment` — total energy flowing **into** the device (positive, lifetime cumulative). - `energy_Wh_decrement` — total energy flowing **out of** the device (negative, lifetime cumulative). - [List Sites](https://developers.gridshare.com/reference/get_api-v2-sites.md): List the siteIds the authenticated customer has access to. v2 is the lightweight external endpoint — pair it with `GET /api/v2/sites/{siteId}/topology` and `GET /api/v2/devices` to drill into a specific site's structure or devices when needed. - [Get Topology](https://developers.gridshare.com/reference/get_api-v2-sites-siteid-topology.md): Returns the electrical topology of a site the authenticated customer has access to. The topology is a tree rooted at the site. Nodes with `"kind": "sensor"` expose an `id` that can be passed directly to `GET /api/v2/devices/{synthId}/telemetry` and a `channels` array listing the data channels available for that stream. See the [Topology key concept](https://developers.gridshare.com/reference/topology-key-concepts) page for a full explanation and worked examples. - [Get Savings](https://developers.gridshare.com/reference/get_api-v2-sites-siteid-savings.md): Returns cost savings for a site broken down by time bucket over the requested interval. - [Get Overlay Plan](https://developers.gridshare.com/reference/get_api-v2-devices-synthid-plans-overlay.md): Get the current overlay plan for the device. - [Set Overlay Plan](https://developers.gridshare.com/reference/put_api-v2-devices-synthid-plans-overlay.md): Set an overlay plan for the device. To delete an overlay plan, send an empty `commands` array in the request body. - [Authentication](https://developers.gridshare.com/reference/authentication.md) - [WebSocket Connections](https://developers.gridshare.com/reference/websocket-connection.md) - [List](https://developers.gridshare.com/reference/get_api-v1-sites-1.md): List all sites. - [Create](https://developers.gridshare.com/reference/post_api-v1-sites-1.md): Create a Site. - [Get](https://developers.gridshare.com/reference/get_api-v1-sites-siteid-1.md): Get a site by ID. - [Replace](https://developers.gridshare.com/reference/put_api-v1-sites-siteid-1.md): Overrides a site with new attributes. - [Get Topology](https://developers.gridshare.com/reference/get_api-v1-sites-siteid-topology.md): Get the [Topology](https://developers.gridshare.com/reference/topology) of a site - [Get Alerts](https://developers.gridshare.com/reference/get_api-v1-sites-siteid-alerts.md): Get the Alerts of a site - [Get Device Statuses](https://developers.gridshare.com/reference/get_api-v1-sites-siteid-statuses.md): Get the Statuses of a site - [List Devices](https://developers.gridshare.com/reference/get_api-v1-devices-1.md): List all devices. - [Create](https://developers.gridshare.com/reference/post_api-v1-devices-1.md): Create a new device - [Get](https://developers.gridshare.com/reference/get_api-v1-devices-synthid-1.md): Get a device by ID, along with its static properties. - [Replace or Create](https://developers.gridshare.com/reference/put_api-v1-devices-synthid-1.md): Overrides an existing device with new properties or creates a device if it does not yet exist. - [Telemetry](https://developers.gridshare.com/reference/get_api-v1-devices-synthid-telemetry-1.md): Get device telemetry. In Gridshare every kind of device has a corresponding telemetry schema. Currently Gridshare supports the following device kinds: - Inverter ( `interver` ) - Battery Pack ( `battery_pack` ) - PV array (`PV`) - Electric Vehicle (`EV`) - Meter (`meter`) - Load Control Relay (`load_control_relay`) Note the "Device kind" is a simpler and broader definition of type, compared to "Device type" used in other endpoints. `synthId` can be either: - A Device ID (from the `/sites` and `/devices` endpoints) - An ID from the [Topology](https://developers.gridshare.com/reference/get_api-v1-sites-siteid-topology) endpoint (any node with `"kind": "sensor"`). ## Energy The fields `energy_Wh_increment` and `energy_Wh_decrement` are only populated if you include `energy` in the `include` query parameter (e.g. `include=default,energy`). - `energy_Wh_increment` is a positive value representing total energy inflow to the device. - `energy_Wh_decrement` is a negative value representing total energy outflow from the device. These are intended to be lifetime cumulative values. In exceptional circumstances, these values might get reset. Energy flow is subjective to the device. For example, if a system was charging from solar the PV would have `energy_Wh_decrement` value reduced (i.e. more negative) the battery would have the `energy_Wh_increment` value increased and (if there was left over energy exported to grid) the inverter would have the `energy_Wh_decrement` value reduced (i.e. more negative). - [Get Operation Mode](https://developers.gridshare.com/reference/get_api-v1-devices-synthid-operationmode-1.md): Get the current Gridshare operation mode of a device. Valid operation modes are: - Simple: Follows the simplest plan possible for the device kind - Schedule: Follows the periodical plan defined for the device - Smart: The AI optimized smart plan for the device - Unknown: The operation mode can not be determined - [Change Operation Mode](https://developers.gridshare.com/reference/put_api-v1-devices-synthid-operationmode-1.md): Set the Gridshare operation mode. - [Counterfactuals](https://developers.gridshare.com/reference/get_api-v1-counterfactuals-counterfactualname-devices-deviceid-telemetry.md): Counterfactual telemetry if the device had not been smartly controlled. Talk to your Gridshare representative about what counterfactuals may be available to you. - [List](https://developers.gridshare.com/reference/get_api-v1-periodicaltariffs-1.md): List all periodical tariffs. - [Create](https://developers.gridshare.com/reference/post_api-v1-periodicaltariffs-1.md): Create a tariff. - [Get](https://developers.gridshare.com/reference/get_api-v1-periodicaltariffs-tariffid-1.md): Get a periodical tariff by ID. - [Update](https://developers.gridshare.com/reference/patch_api-v1-periodicaltariffs-tariffid-1.md): Updates the properties of an existing tariff. The body of the request requires the tariff "name" and "companyName". These must match the corresponding parts of the tariff identifier in the URL. Note that if you create a tariff with mixed case in these two properties, it will be converted to lower-case and both the identifier in the path and these two properties must be in lower case in this PATCH request. If these do not match you will receive a 422 response. You can PATCH a tariff in order to update the list of "exceptions" for an existing "pricingPeriod". You can PATCH a tariff to alter the prices for an existing "pricingPeriod". You can PATCH a tariff to extend the "end" date of the latest "pricingPeriod". The latest "pricingPeriod" in a tariff can be opened-ended; i.e. you can omit the "end" property. An open-ended "pricingPeriod" extends indefinitely into the future. If you later PATCH the tariff again with a new "pricingPeriod" with a "start" that is after the "start" of the open-ended "pricingPeriod", that previously open-ended "pricingPeriod" will be automatically modified to have an "end" property that matches the "start" property of the new "pricingPeriod"; i.e. it will become closed at the point when the new "pricingPeriod" starts. If you PATCH a tariff with a "pricingPeriod" that has a "start" date that's before the "end" date of the latest "pricingPeriod", we will modify that latest "pricingPeriod" to end before the new "pricingPeriod" and add a new "pricingPeriod" with the given "start" and "end" dates. E.g. if the lastest "pricingPeriod" had "start:2024-01-01; end:2024-01-31" and you PATCH the tariff with a new "pricingPeriod" with "start:2024-01-20; end:2024-02-29", you will end up with a tariff that contains a "pricingPeriod" from "start:2024-01-01; end:2024-01-19" and a new "pricingPeriod" from "start:2024-01-20; end:2024-02-29". If you PATCH a tariff with a new "pricingPeriod" whose "start" date is not contiguous with the current latest "pricingPeriod" you will receive a 422 response because we will refuse to allow a gap in the tariff. E.g. if the current latest "pricingPeriod" has "end:2024-02-01" and you PATCH the tariff with a new "pricingPeriod" with "start:2024-02-02" (or later) you will receive a 422 error. The new "pricingPeriod" must have a start of "2024-02-01" (or earlier) in order to avoid leaving a gap. You can PATCH a tariff with multiple new "pricingPeriods" at once. If you do this, you must make sure that there are no gaps between the "pricingPeriods" (as detailed above). If there are any gaps you will receive a 422 response. - [Create](https://developers.gridshare.com/reference/post_api-v1-dynamictariffs-1.md): Create a dynamic tariff. The `values` field is included as a convenience to add some initial timeseries values. You'll typically add more values later using the Update (PATCH) endpoint. - [Update](https://developers.gridshare.com/reference/patch_api-v1-dynamictariffs-tariffid-1.md): Appends or overrides periods of a dynamic tariff. An override happens if the new values overlap in time with existing values. Existing values are not deleted by this endpoint (this is not a "replace" operation). - [List](https://developers.gridshare.com/reference/get_api-v1-dynamictariffs.md): List all dynamic tariffs associated with the calling partner account. - [Get](https://developers.gridshare.com/reference/get_api-v1-dynamictariffs-tariffid.md): Returns the metadata for a dynamic tariff together with a single page of timeseries values. The page covers a 7 day window. If `interval` is provided, the response starts from the latest 7 days inside that interval and `nextToken` paginates backwards 7 days at a time until `interval.start` is reached. If `interval` is omitted the page covers the previous 7 days and `nextToken` paginates backwards through the available history. - [List](https://developers.gridshare.com/reference/get_api-v1-flexgroups-1.md): List all flex groups. - [Create](https://developers.gridshare.com/reference/post_api-v1-flexgroups-1.md): Create a flex group. - [Get](https://developers.gridshare.com/reference/get_api-v1-flexgroups-flexgroupid-1.md): Get a flex group by ID. - [List Participants](https://developers.gridshare.com/reference/get_api-v1-flexgroups-flexgroupid-participants-1.md): List all flex participants in a specified group. - [Create Bulk Action](https://developers.gridshare.com/reference/post_api-v1-flexgroups-flexgroupid-participants-bulk-1.md): Overwrites the list of participants in a specified flex group by sending a new list of participants to make up the flex group. Ensure the provided list is correct as this action is irreversible. - [Get Bulk Action](https://developers.gridshare.com/reference/get_api-v1-flexgroups-flexgroupid-participants-bulk-bulkid-1.md): Retrieve the current status of a bulk operation on the participants of a flex group. This endpoint provides insights into whether the bulk update is still in progress, scheduled, or has been completed. - [Add Participant](https://developers.gridshare.com/reference/post_api-v1-flexgroups-flexgroupid-participants.md): Add a participant to a specified flex group. - [Get Participant](https://developers.gridshare.com/reference/get_api-v1-flexgroups-flexgroupid-participants-participantid.md): Get a participant. - [Delete Participant](https://developers.gridshare.com/reference/delete_api-v1-flexgroups-flexgroupid-participants-participantid.md): Delete a participant from a specified flex group. - [List Prognoses](https://developers.gridshare.com/reference/get_api-v1-flexgroups-flexgroupid-prognoses-1.md): List prognoses for a specific flex group. New prognoses are generated when there are changes in the group forecast for a period, either as a result of changes in predictions or because of an explicit change of the power profile for a group due to flex events. - [Get Prognosis](https://developers.gridshare.com/reference/get_api-v1-flexgroups-flexgroupid-prognoses-prognosisid-1.md): Get prognosis using the prognosis ID. This endpoint provides insight into the forecasted power profile of the group, aggregated from the forecasted power profile of each participant at their settlement point. - [Get Diff Request](https://developers.gridshare.com/reference/get_api-v1-prognosisdiffrequests-prognosisdiffrequestid-1.md): Check the status and potential offer of a prognosis diff request. Once the request has been processed, an offer, which indicates the feasible amount of power that can be provided, will be included in the response. - [Create Diff Request](https://developers.gridshare.com/reference/post_api-v1-prognoses-prognosisid-prognosisdiffrequests-1.md): Create a request to modify a specific prognosis profile. This endpoint allows users to perform flex actions, such as charging or discharging to the network in a coordinated manner, by submitting a differential (diff) profile over the original prognosis. This operation is asynchronous. Once the diff request is submitted, you should periodically poll the "Poll Flex Prognosis Diff Request Status" endpoint to check the status and outcome of your request. - [Get Diff Order](https://developers.gridshare.com/reference/get_api-v1-prognosisdifforders-prognosisdifforderid-1.md): Get the details of an accepted prognosis diff offer, now referred to as an order. This endpoint provides information about the committed flex offer, including its associated power profiles and prices. - [Create Diff Order](https://developers.gridshare.com/reference/post_api-v1-prognosisdiffrequests-prognosisdiffrequestid-prognosisdifforders-1.md): Confirm and commit to the offer associated with a prognosis diff request. Upon accepting the offer, commands will be dispatched to the corresponding devices. - [List](https://developers.gridshare.com/reference/get_api-v1-flexevent-1.md): List all flex events within a specified time range, optionally filtered by group. - [Create](https://developers.gridshare.com/reference/post_api-v1-flexevent-1.md): Create a flex event for a defined flex group. This endpoint supports the creation of flat dispatch events, events that achieve a flat power profile within a specified time frame. - [Update](https://developers.gridshare.com/reference/patch_api-v1-flexevents-flexeventid-1.md): Update an existing flex event by modifying it's properties or cancel the event. - [Opt Out](https://developers.gridshare.com/reference/post_api-v1-flexdispatches-flexdispatchid-optout.md): Opt a participant out of a flex dispatch. The participant can be identified by either site ID or participant ID. If the participant has already been opted out of this dispatch, the original opt-out details are returned. - [Get Overlay Plan](https://developers.gridshare.com/reference/get_api-v1-devices-synthid-plans-overlay.md): Get the current overlay plan for the device. - [Set Overlay Plan](https://developers.gridshare.com/reference/put_api-v1-devices-synthid-plans-overlay.md): Set an overlay plan for the device. To delete an overlay plan, send an empty `commands` array in the request body. - [List](https://developers.gridshare.com/reference/get_api-v1-visits.md): List all visits. - [Create](https://developers.gridshare.com/reference/post_api-v1-visits.md): Create a visit. - [Get](https://developers.gridshare.com/reference/get_api-v1-visits-visitid.md): Get a visit by ID.