> For the complete documentation index, see [llms.txt](https://renewables.docs.helinplatform.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://renewables.docs.helinplatform.com/api-reference/sites.md). # Sites ## Sites > List all sites.\ > \ > Args:\ > \- delivery\_status: Site delivery status filter. \`-1\` will list all.\ > \ > Returns:\ > List of sites matching delivery status. ```json {"openapi":"3.0.3","info":{"title":"POLARIS Curtailment API","version":"0.1"},"security":[{"Auth0HTTPBearer":[]}],"components":{"securitySchemes":{"Auth0HTTPBearer":{"scheme":"bearer","type":"http"}},"schemas":{"NullableDeliveryStatus":{"enum":["1","2","3","4","6","7","8","9","0","-1"],"title":"NullableDeliveryStatus","type":"string"},"SiteResponse":{"properties":{"created_at":{"format":"date-time","title":"Created At","type":"string"},"curtailment_time_limit":{"exclusiveMinimum":true,"minimum":0,"nullable":true,"title":"Curtailment Time Limit","type":"integer"},"cyclic_write_timeout":{"minimum":0,"nullable":true,"title":"Cyclic Write Timeout","type":"integer"},"id":{"format":"uuid","title":"Id","type":"string"},"meta_data":{"additionalProperties":true,"default":{},"nullable":true,"title":"Meta Data","type":"object"},"name":{"title":"Name","type":"string"},"site_tag":{"title":"Site Tag","type":"string"}},"required":["id","created_at","site_tag","name"],"title":"SiteResponse","type":"object"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/sites":{"get":{"description":"List all sites.\n\nArgs:\n - delivery_status: Site delivery status filter. `-1` will list all.\n\nReturns:\n List of sites matching delivery status.","operationId":"Sites_api_sites_get","parameters":[{"in":"query","name":"delivery_status","required":false,"schema":{"$ref":"#/components/schemas/NullableDeliveryStatus"}},{"in":"header","name":"X-Management-Token","required":false,"schema":{"nullable":true,"title":"X-Management-Token","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/SiteResponse"},"title":"Response Sites Api Sites Get","type":"array"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Sites","tags":["sites"]}}}} ``` ## Site Metrics > Show metrics for all sites.\ > \ > Args:\ > \- delivery\_status: Site delivery status filter. \`-1\` will list all.\ > \ > Returns:\ > List of metrics for all sites matching delivery status. ```json {"openapi":"3.0.3","info":{"title":"POLARIS Curtailment API","version":"0.1"},"security":[{"Auth0HTTPBearer":[]}],"components":{"securitySchemes":{"Auth0HTTPBearer":{"scheme":"bearer","type":"http"}},"schemas":{"NullableDeliveryStatus":{"enum":["1","2","3","4","6","7","8","9","0","-1"],"title":"NullableDeliveryStatus","type":"string"},"SiteMetric":{"properties":{"key":{"title":"Key","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"value":{"title":"Value"}},"required":["key","value","timestamp"],"title":"SiteMetric","type":"object"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/sites/metrics":{"get":{"description":"Show metrics for all sites.\n\nArgs:\n - delivery_status: Site delivery status filter. `-1` will list all.\n\nReturns:\n List of metrics for all sites matching delivery status.","operationId":"Site_metrics_api_sites_metrics_get","parameters":[{"in":"query","name":"delivery_status","required":false,"schema":{"$ref":"#/components/schemas/NullableDeliveryStatus"}},{"in":"header","name":"X-Management-Token","required":false,"schema":{"nullable":true,"title":"X-Management-Token","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/SiteMetric"},"title":"Response Site Metrics Api Sites Metrics Get","type":"array"}}},"description":"Successful Response"},"404":{"content":{"application/json":{"schema":{"properties":{"detail":{"items":{"type":"string"},"title":"Detail","type":"array"}},"title":"Object not found","type":"object"}}},"description":"Object not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"},"424":{"content":{"application/json":{"schema":{"properties":{"detail":{"title":"Detail","type":"string"}},"title":"Dependency Failed","type":"object"}}},"description":"Dependency Failed"}},"summary":"Site Metrics","tags":["sites"]}}}} ``` ## Site Details > Get site by id.\ > \ > Returns:\ > Site details.\ > HTTP 404 if Site not found. ```json {"openapi":"3.0.3","info":{"title":"POLARIS Curtailment API","version":"0.1"},"security":[{"Auth0HTTPBearer":[]}],"components":{"securitySchemes":{"Auth0HTTPBearer":{"scheme":"bearer","type":"http"}},"schemas":{"SiteDetailsResponse":{"properties":{"created_at":{"format":"date-time","title":"Created At","type":"string"},"curtailment_time_limit":{"exclusiveMinimum":true,"minimum":0,"nullable":true,"title":"Curtailment Time Limit","type":"integer"},"cyclic_write_timeout":{"minimum":0,"nullable":true,"title":"Cyclic Write Timeout","type":"integer"},"id":{"format":"uuid","title":"Id","type":"string"},"meta_data":{"additionalProperties":true,"default":{},"nullable":true,"title":"Meta Data","type":"object"},"metrics":{"items":{"anyOf":[{"$ref":"#/components/schemas/SiteMetric"},{"$ref":"#/components/schemas/SiteDeviceMetric"}]},"title":"Metrics","type":"array"},"metrics_v2":{"items":{"anyOf":[{"$ref":"#/components/schemas/SiteMetric"},{"$ref":"#/components/schemas/SiteDeviceMetric"}]},"nullable":true,"title":"Metrics V2","type":"array"},"name":{"title":"Name","type":"string"},"site_tag":{"title":"Site Tag","type":"string"}},"required":["id","created_at","site_tag","name","metrics"],"title":"SiteDetailsResponse","type":"object"},"SiteMetric":{"properties":{"key":{"title":"Key","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"value":{"title":"Value"}},"required":["key","value","timestamp"],"title":"SiteMetric","type":"object"},"SiteDeviceMetric":{"properties":{"device":{"title":"Device","type":"string"},"key":{"title":"Key","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"value":{"title":"Value"}},"required":["key","value","timestamp","device"],"title":"SiteDeviceMetric","type":"object"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/sites/{site_id}":{"get":{"description":"Get site by id.\n\nReturns:\n Site details.\n HTTP 404 if Site not found.","operationId":"Site_details_api_sites__site_id__get","parameters":[{"in":"path","name":"site_id","required":true,"schema":{"format":"uuid","nullable":true,"title":"Site Id","type":"string"}},{"in":"header","name":"X-Management-Token","required":false,"schema":{"nullable":true,"title":"X-Management-Token","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteDetailsResponse"}}},"description":"Site Object Details"},"404":{"content":{"application/json":{"schema":{"properties":{"detail":{"items":{"type":"string"},"title":"Detail","type":"array"}},"title":"Object not found","type":"object"}}},"description":"Object not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Site Details","tags":["sites"]}}}} ``` ## Site Update > Update Site details.\ > \ > Returns:\ > Updated site details.\ > HTTP 404 if Site not found. ```json {"openapi":"3.0.3","info":{"title":"POLARIS Curtailment API","version":"0.1"},"security":[{"Auth0HTTPBearer":[]}],"components":{"securitySchemes":{"Auth0HTTPBearer":{"scheme":"bearer","type":"http"}},"schemas":{"SiteUpdate":{"properties":{"curtailment_time_limit":{"exclusiveMinimum":true,"minimum":0,"nullable":true,"title":"Curtailment Time Limit","type":"integer"},"cyclic_write_timeout":{"exclusiveMinimum":true,"minimum":0,"nullable":true,"title":"Cyclic Write Timeout","type":"integer"},"meta_data":{"additionalProperties":true,"nullable":true,"title":"Meta Data","type":"object"},"name":{"nullable":true,"title":"Name","type":"string"},"site_tag":{"nullable":true,"title":"Site Tag","type":"string"}},"title":"SiteUpdate","type":"object"},"SiteResponse":{"properties":{"created_at":{"format":"date-time","title":"Created At","type":"string"},"curtailment_time_limit":{"exclusiveMinimum":true,"minimum":0,"nullable":true,"title":"Curtailment Time Limit","type":"integer"},"cyclic_write_timeout":{"minimum":0,"nullable":true,"title":"Cyclic Write Timeout","type":"integer"},"id":{"format":"uuid","title":"Id","type":"string"},"meta_data":{"additionalProperties":true,"default":{},"nullable":true,"title":"Meta Data","type":"object"},"name":{"title":"Name","type":"string"},"site_tag":{"title":"Site Tag","type":"string"}},"required":["id","created_at","site_tag","name"],"title":"SiteResponse","type":"object"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/sites/{site_id}":{"put":{"description":"Update Site details.\n\nReturns:\n Updated site details.\n HTTP 404 if Site not found.","operationId":"Site_update_api_sites__site_id__put","parameters":[{"in":"path","name":"site_id","required":true,"schema":{"format":"uuid","title":"Site Id","type":"string"}},{"in":"header","name":"X-Management-Token","required":false,"schema":{"nullable":true,"title":"X-Management-Token","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteUpdate"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteResponse"}}},"description":"Successful Response"},"404":{"content":{"application/json":{"schema":{"properties":{"detail":{"items":{"type":"string"},"title":"Detail","type":"array"}},"title":"Object not found","type":"object"}}},"description":"Object not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Site Update","tags":["sites"]}}}} ``` ## Control Devices Per Category On A Site > Control devices per category for a given site.\ > \ > Response contains mappings of updated and not updated devices.\ > \ > Not updated devices mappings contains device id and error details.\ > After encountering device error for the first time,\ > erronious device will be placed into "backoff list",\ > meaning that command won't be sent to device next time.\ > \ > After re-trying once and encountering errors again,\ > device will skip 2 commands before next command is sent,\ > backing off up to 16 times. ```json {"openapi":"3.0.3","info":{"title":"POLARIS Curtailment API","version":"0.1"},"security":[{"Auth0HTTPBearer":[]}],"components":{"securitySchemes":{"Auth0HTTPBearer":{"scheme":"bearer","type":"http"}},"schemas":{"CurtailCategoryRequest":{"properties":{"category":{"title":"Category","type":"string"},"device_tags":{"items":{"type":"string"},"nullable":true,"title":"Device Tags","type":"array"},"value":{"title":"Value","type":"integer"}},"required":["value","category"],"title":"CurtailCategoryRequest","type":"object"},"CurtailmentServiceResponse":{"properties":{"not_updated_devices":{"additionalProperties":{"$ref":"#/components/schemas/NotUpdatedDeviceCurtailmentResponse"},"title":"Not Updated Devices","type":"object"},"updated_devices":{"additionalProperties":{"$ref":"#/components/schemas/UpdatedDeviceCurtailmentResponse"},"title":"Updated Devices","type":"object"}},"required":["updated_devices","not_updated_devices"],"title":"CurtailmentServiceResponse","type":"object"},"NotUpdatedDeviceCurtailmentResponse":{"properties":{"detail":{"title":"Detail","type":"string"},"reason":{"title":"Reason","type":"string"}},"required":["reason","detail"],"title":"NotUpdatedDeviceCurtailmentResponse","type":"object"},"UpdatedDeviceCurtailmentResponse":{"properties":{"value":{"anyOf":[{"type":"integer"},{"type":"string"}],"title":"Value"}},"required":["value"],"title":"UpdatedDeviceCurtailmentResponse","type":"object"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/sites/{site_id}/curtail-category":{"put":{"description":"Control devices per category for a given site.\n\nResponse contains mappings of updated and not updated devices.\n\nNot updated devices mappings contains device id and error details.\nAfter encountering device error for the first time,\nerronious device will be placed into \"backoff list\",\nmeaning that command won't be sent to device next time.\n\nAfter re-trying once and encountering errors again,\ndevice will skip 2 commands before next command is sent,\nbacking off up to 16 times.","operationId":"Control_devices_per_category_on_a_site_api_sites__site_id__curtail_category_put","parameters":[{"in":"path","name":"site_id","required":true,"schema":{"format":"uuid","nullable":true,"title":"Site Id","type":"string"}},{"in":"header","name":"X-Management-Token","required":false,"schema":{"nullable":true,"title":"X-Management-Token","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurtailCategoryRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurtailmentServiceResponse"}}},"description":"Successfully updated all devices"},"201":{"content":{"application/json":{"schema":{"properties":{"not_updated_devices":{"additionalProperties":{"properties":{"detail":{"type":"string"},"reason":{"type":"string"}},"title":"Mapping of device to error message","type":"object"},"title":"List of not updated devices","type":"object"},"updated_devices":{"additionalProperties":{"properties":{"value":{"type":"string"}},"title":"Mapping of device to updated value","type":"object"},"title":"List of updated devices","type":"object"}},"title":"Partially Updated devices","type":"object"}}},"description":"Partially Updated devices"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"},"404":{"content":{"application/json":{"schema":{"properties":{"detail":{"items":{"type":"string"},"title":"Detail","type":"array"}},"title":"Object not found","type":"object"}}},"description":"Object not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"},"424":{"content":{"application/json":{"schema":{"properties":{"detail":{"title":"Detail","type":"string"}},"title":"Dependency Failed","type":"object"}}},"description":"Dependency Failed"},"429":{"content":{"application/json":{"schema":{"properties":{"detail":{"title":"Detail","type":"string"}},"title":"Rate limit is exceeded","type":"object"}}},"description":"Rate limit is exceeded"}},"summary":"Control Devices Per Category On A Site","tags":["sites"]}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://renewables.docs.helinplatform.com/api-reference/sites.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.