Skip to main content

API v1.5 Documentation

This documentation set describes the different REST API resources of the Energyworx SaaS and the different JSON structures to be used with the individual requests.

Overview​

The platform already provides a vast amount of available endpoints that are ready to use. Simply go to [API Documentation] in the console and start exploring the options. The available endpoints are continuously updated, meaning that the possibilities provided here expand over time. They are categorised per resource, making it easier to find what you need.

Refer to the Open API spec file for complete overview​

For a more complete overview refer to the OpenAPI spec that can be downloaded from the API for the most up to date version with your platform. The file can be found here:

https://ah.{your_project}.ewxapis.com/json/ewxv1openapi.json

API Design Patterns​

Append-Only Architecture​

The Energyworx platform follows an append-only design pattern for auditing and compliance purposes. This architectural principle has important implications for how the API works:

Versioned Resources: Resources with built-in versioning (datasources, tags, and datapoints) use a create-or-update pattern:

  • Create endpoints handle both creating new resources and updating existing ones
  • Calling a create endpoint with an existing resource ID will update that resource's properties
  • No separate update endpoints exist for these versioned resources
  • This is an intentional design choice to maintain audit trails and support re-ingestion workflows

No Deletion Support: Datasources and timeseries data cannot be deleted through the API. This ensures:

  • Complete audit trails are maintained
  • Data lineage is preserved
  • Regulatory compliance requirements are met

Idempotent Operations: Many create operations are idempotent, meaning you can safely call them multiple times with the same data. The platform will handle this gracefully by updating properties rather than returning errors.

Best Practices​

When working with API v1.5:

  • Understand that "create" endpoints for versioned resources may also update existing resources
  • Implement client-side logic if you need to distinguish between create and update operations
  • Use GET endpoints to check for resource existence before attempting creation if needed
  • Design your integrations to handle the idempotent behavior of create endpoints
  • For re-ingestion workflows, leverage the create-or-update pattern to refresh datasource properties