Migration guide from v1

Breaking Changes

🗑️ Organisations Removed

What changed: The Organisations layer has been completely removed from the API.

Why: Organisations served no functional purpose in the new architecture and were originally intended for filtering multiple accounts with multiple groups. Removing this layer simplifies the API structure.

Action required: Update any code that references organisation endpoints or includes organisation IDs in requests.

🔄 Groups System Upgraded

What changed: Groups have been completely redesigned with new functionality and endpoints.

Key changes:

• Every account is now connected to at least one group by default
• New endpoint: GET /api/v2/groups returns all groups connected to your account
• Groups now serve as the top-level container in the new hierarchy

Action required: Update group-related API calls to use the v2 endpoints.

📱 "Things" Renamed to "Sparkies"

What changed: The generic "Things" concept has been replaced with "Sparkies" as a specific device category.

Why: With the introduction of Flint devices, we've separated endpoints by device category to enable category-specific functionality.

Action required: Replace all references to "Things" with "Sparkies" in your code and API calls.

New Features & Architecture

🏠 Groups and Addresses Hierarchy

The API now uses a structured hierarchy for accessing device data:

New workflow:

Groups → Addresses → Devices

Implementation steps:

1. Get all groups: GET /api/v2/groups
2. Get addresses for a group: GET /api/v2/groups/{group_uuid}/addresses
3. Access devices using address_uuid: Use the address information to connect with Sparky or other devices

⚡ Historical Energy Data

New endpoint: /Energy

Access historical energy consumption data through this dedicated endpoint for better performance and organization.

🔌 Category-Specific Device Endpoints

What's new: Each device category now has its own dedicated endpoint structure.

Benefits:

• More targeted functionality per device type
• Better API organization
• Future-proof architecture for new device categories

Migration Checklist

• Remove all Organisation-related code and API calls
• Update group queries to use /api/v2/groups
• Replace "Things" references with "Sparkies"
• Implement the new Groups → Addresses → Devices workflow
• Update energy data calls to use the new /Energy endpoint
• Verify device category endpoints are correctly implemented
• Test all integrations with v2.0 endpoints

Need Help?

If you encounter issues during migration or need clarification on any changes, please refer to the API documentation or contact our support team.