{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Generic Push Integration","llmstxt":{"title":"Obelisk HEMS API Documentation","description":"Official technical documentation for integrating with the Obelisk Home Energy Management System.","details":{"content":"The HEMS (Home Energy Management System) platform provides a unified interface to connect, monitor, and control residential energy devices, starting with full support for the Shelly ecosystem.\nHEMS allows energy retailers, virtual power plants (VPPs), and smart home providers to integrate distributed energy resources into their applications with minimal effort.\n"},"sections":[{"title":"Introduction & Getting Started","description":"Core concepts, organization registration, and acquiring access tokens.","includeFiles":["pages/index.md","pages/registration.md","pages/authentication.md"],"excludeFiles":[]},{"title":"Vendor Integrations","description":"Guide for fetching supported device manufacturers dynamically from the vendors endpoint.","includeFiles":["pages/vendors-endpoint.md"],"excludeFiles":[]},{"title":"Generic Push Integration","description":"Guide for integrating custom hardware or local automation tools with HEMS.","includeFiles":["pages/generic-push.md"],"excludeFiles":[]},{"title":"API Reference","description":"Complete OpenAPI specification detailing all endpoints, parameters, and schemas.","includeFiles":["apis/openapi.yaml"],"excludeFiles":[]}],"hide":false,"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"generic-push-integration","__idx":0},"children":["Generic Push Integration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Generic Push"]}," integration flow allows you to connect custom hardware, local automation tools (like Node-RED or Home Assistant), or any device capable of making standard HTTP requests to the HEMS platform."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Supported Devices"]},": Currently, the Generic Push integration is designed specifically for ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["electric meters"]},", or any device that publishes active power and energy metrics (such as batteries or inverters)."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-it-works","__idx":1},"children":["How it works"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you link a user using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["generic-push"]}," vendor ID, the API generates a unique ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["PUSH URL"]},". You must configure your device or automation script to periodically send POST requests to this exact URL with the device's telemetry data."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"request-format","__idx":2},"children":["Request Format"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your device or script should send an HTTP ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," request to the generated PUSH URL with a JSON payload."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Headers Required"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Content-Type"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/json"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"payload-schema","__idx":3},"children":["Payload Schema"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The body of the POST request must conform to the following schema:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["device_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A unique identifier for the specific device. (minimum of 1 character)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total_act_power"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The total active power currently consumed/produced, in watts (W)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["device_model"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The model name of the device."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total_act_energy"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The total active energy accumulated, in watt-hours (Wh)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total_act_ret_energy"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The total active returned energy, in watt-hours (Wh)."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-request","__idx":4},"children":["Example Request"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://api-hems.obeliskapp.com/integration/generic-push?id=<generated-id>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"device_id\": \"custom-meter-01\",\n    \"device_model\": \"HomeAssistant-Virtual\",\n    \"total_act_power\": 1450.5,\n    \"total_act_energy\": 50420\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"implementation-tips","__idx":5},"children":["Implementation Tips"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Frequency"]},": We recommend pushing data at a sensible interval, such as every 15 or 20 seconds up to 5 minutes, depending on the capabilities of your device and the precision required."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Unique Device ID"]},": The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["device_id"]}," must be unique per physical device being tracked under the specific user. If you send data from multiple distinct devices to the same URL, differentiate them by their ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["device_id"]},"."]}]}]},"headings":[{"value":"Generic Push Integration","id":"generic-push-integration","depth":1},{"value":"How it works","id":"how-it-works","depth":2},{"value":"Request Format","id":"request-format","depth":2},{"value":"Payload Schema","id":"payload-schema","depth":3},{"value":"Example Request","id":"example-request","depth":3},{"value":"Implementation Tips","id":"implementation-tips","depth":2}],"frontmatter":{"seo":{"title":"Generic Push Integration"}},"lastModified":"2026-06-10T18:47:51.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/pages/generic-push","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}