Hydros Connect + Official API

[johnacharles93]

Hello! I'm building the Home Assistant integration for HYDROS and planning to migrate to the official API. I've got some specific questions about how this affects Home Assistant users and what we need to plan for.

QUESTIONS ABOUT LIMITATIONS

RATE LIMITS FOR HOME ASSISTANT USE

The 10 state updates/min per key...that's tight for a multi-device setup. Home Assistant users often run:

• Sensor polling every 30-60 seconds
• Multiple automations that read/write state simultaneously
• Cross-tank automations that chain requests

With 3 tanks on 60-second polling, I'm at 3 updates/min just for reads. Add automations and I'm approaching the limit.

Questions:

• Can users request higher rate limit tiers?
• Is there a way to batch operations or will each update count separately?
• What happens at rate limit? (Error message? Backoff needed? Dropped request?)

POLLING VS. PUSH MODEL

The docs mention "polling sessions" (5/hour limit) For Home Assistant:

• Is WebSocket or Server-Sent Events on the roadmap?
• When would polling sessions launch? (Need to plan timeline)
• Will push notifications be included in the free tier or premium only?

If we're stuck with polling, I need to plan for higher latency and trade-offs between freshness and rate limits.

ERROR HANDLING & RESILIENCY

What are the edge cases?

• If a key gets invalidated or revoked mid-automation, what does HA get back? Specific error code?
• Are there transient errors vs. permanent auth failures? (Need to retry vs. immediate fail)
• If the API is down, do failed requests queue or just error immediately?
• Any circuit breaker patterns recommended for integration reliability?

Feature Requests:

Not blockers, but would make integration better:

1. Batch operations: Get/set multiple device states in one call instead of N calls
2. Query filtering: "Give me all devices in feed mode" instead of polling all devices
3. Webhook support: HA could expose a webhook to receive state change notifications
4. Scope granularity: "Read-only on tank 1, read-write on tank 2" from one key (instead of separate keys)

@hydros team:

• What's the recommended polling interval for a single device? (30s? 60s? longer?)
• When should I tell users to expect the migration from account auth to API keys?

Appreciate the clarity on these. Building a great integration requires understanding the real constraints and roadmap. I know this was a little chaotic and skattered, but I needed to get my thoughts out.

Thanks!

 

[Carlos]

RATE LIMITS FOR HOME ASSISTANT USE

The 10 state updates/min per key...that's tight for a multi-device setup. Home Assistant users often run:

• Sensor polling every 30-60 seconds
• Multiple automations that read/write state simultaneously
• Cross-tank automations that chain requests

With 3 tanks on 60-second polling, I'm at 3 updates/min just for reads. Add automations and I'm approaching the limit.

The limit here is PER DEVICE, not account-wide. Each key corresponds to one device, not the provider. Current rate limits should be fine for 30-second polling.

Questions:

• Can users request higher rate limit tiers?
• Is there a way to batch operations or will each update count separately?
• What happens at rate limit? (Error message? Backoff needed? Dropped request?)

• If the rate limits, as currently designed, are too strict, we will adjust. If you need substantially higher rate limits, we can talk.
• No batching yet, but with per-device keys driving the rate limit, it shouldn't be a big problem
• HTTP 429, JSON {"error":"Rate limit exceeded: ..."}, request dropped, retry after backoff. Not queued.

POLLING VS. PUSH MODEL

The docs mention "polling sessions" (5/hour limit) For Home Assistant:

• Is WebSocket or Server-Sent Events on the roadmap?
• When would polling sessions launch? (Need to plan timeline)
• Will push notifications be included in the free tier or premium only?

If we're stuck with polling, I need to plan for higher latency and trade-offs between freshness and rate limits.

• Something to consider for future enhancement.
• After the next firmware update, polling sessions will be live. Starting a session "wakes up" a device, and the device starts updating state every 30s (faster immediately after an override operation).
• The HYDROS app already offers push notifications.

ERROR HANDLING & RESILIENCY

What are the edge cases?

• If a key gets invalidated or revoked mid-automation, what does HA get back? Specific error code?
• Are there transient errors vs. permanent auth failures? (Need to retry vs. immediate fail)
• If the API is down, do failed requests queue or just error immediately?
• Any circuit breaker patterns recommended for integration reliability?

• 401/403 treat as permanent, 429 / 500 treat as transient
• Not currently. Key works or does not work.
• If the API is down, requests do not queue.

Feature Requests:

Not blockers, but would make integration better:

1. Batch operations: Get/set multiple device states in one call instead of N calls
2. Query filtering: "Give me all devices in feed mode" instead of polling all devices
3. Webhook support: HA could expose a webhook to receive state change notifications
4. Scope granularity: "Read-only on tank 1, read-write on tank 2" from one key (instead of separate keys)

1. Good idea! I will bring that up in the next developer meeting.
2. This would be a more fundamental change to the device/collective-scoped keys. The integration will need to track separate keys for each device/collective being controlled. To ensure we are on the same page, a collective (regardless of how many devices it has) uses only one device key.
3. This is also something to consider.
4. Not on the current roadmap.

@hydros team:

• What's the recommended polling interval for a single device? (30s? 60s? longer?)
• When should I tell users to expect the migration from account auth to API keys?

• 30 seconds. That's how fast the device sends updates after a session has started. It will keep sending 30-second updates for 6 hours. You can reset the 6-hour time up to 5 times per hour and get a new polling token.
  
  Immediately after sending an override, the device accelerates updates to once every 5 seconds. You can poll faster after the override is received to verify that the override change had the intended effect. The rate limit should allow occasional bursts of state polling. We will tune rate limits if needed
  
  
• The existing password flow will stop working sometime after 4 weeks from now. Using the API will be required after.
  

 

[Jorgex3]

Hi Carlos,

I wanted to follow up regarding my request for API access, as I have not yet received a response.

Over the past several months, I have been developing a web-based platform designed to help maintenance teams manage multiple aquariums across a single location through a centralized interface. Beyond operational management, the platform includes comprehensive water quality monitoring and record keeping capabilities, enabling users to track, analyze, and maintain historical data on key parameters.

More recently, we have begun integrating AI-driven capabilities to help identify trends, diagnose potential issues, and provide actionable recommendations for maintaining healthy reef ecosystems. Our objective is to leverage data-driven insights to assist users in making more informed decisions regarding dosing, supplementation, maintenance schedules, and overall tank health.

In parallel, I currently provide support to new HYDROS users throughout Mexico, helping them design, configure, and deploy their systems so they can become operational more quickly and confidently. As part of that effort, I have also translated multiple HYDROS-related documents and guides into Spanish to better support Spanish-speaking hobbyists who require technical guidance and educational resources. My goal has always been to help expand adoption while improving the overall customer experience for users in the region.

Access to the HYDROS API would significantly enhance the value of this platform. By integrating controller data directly into our analytics engine, we can correlate critical parameters such as temperature, pH, salinity, ORP, nutrient levels, and consumption patterns with long-term system performance. This creates a much richer dataset that enables AI models to generate more accurate recommendations and predictive insights for end users.

Additionally, API integration would allow centralized visibility and management of multiple HYDROS-controlled systems from a single interface. Users would benefit from a unified platform for monitoring, analysis, record keeping, and controller management across multiple installations, whether they are maintaining a single reef aquarium or an entire facility.

I believe this project represents a meaningful opportunity to extend the value of the HYDROS ecosystem while delivering a more intelligent, data-driven solution for our shared customer base. The combination of controller data, historical water quality records, and AI-assisted recommendations has the potential to significantly simplify reef keeping while helping users achieve better long-term outcomes.

I would appreciate any update you can provide regarding API access and would welcome the opportunity to discuss the project in greater detail.

Best regards,

Jorge Plascencia Correa

 

[Carlos]

Hi Carlos,

I wanted to follow up regarding my request for API access, as I have not yet received a response.

Over the past several months, I have been developing a web-based platform designed to help maintenance teams manage multiple aquariums across a single location through a centralized interface. Beyond operational management, the platform includes comprehensive water quality monitoring and record keeping capabilities, enabling users to track, analyze, and maintain historical data on key parameters.

More recently, we have begun integrating AI-driven capabilities to help identify trends, diagnose potential issues, and provide actionable recommendations for maintaining healthy reef ecosystems. Our objective is to leverage data-driven insights to assist users in making more informed decisions regarding dosing, supplementation, maintenance schedules, and overall tank health.

In parallel, I currently provide support to new HYDROS users throughout Mexico, helping them design, configure, and deploy their systems so they can become operational more quickly and confidently. As part of that effort, I have also translated multiple HYDROS-related documents and guides into Spanish to better support Spanish-speaking hobbyists who require technical guidance and educational resources. My goal has always been to help expand adoption while improving the overall customer experience for users in the region.

Access to the HYDROS API would significantly enhance the value of this platform. By integrating controller data directly into our analytics engine, we can correlate critical parameters such as temperature, pH, salinity, ORP, nutrient levels, and consumption patterns with long-term system performance. This creates a much richer dataset that enables AI models to generate more accurate recommendations and predictive insights for end users.

Additionally, API integration would allow centralized visibility and management of multiple HYDROS-controlled systems from a single interface. Users would benefit from a unified platform for monitoring, analysis, record keeping, and controller management across multiple installations, whether they are maintaining a single reef aquarium or an entire facility.

I believe this project represents a meaningful opportunity to extend the value of the HYDROS ecosystem while delivering a more intelligent, data-driven solution for our shared customer base. The combination of controller data, historical water quality records, and AI-assisted recommendations has the potential to significantly simplify reef keeping while helping users achieve better long-term outcomes.

I would appreciate any update you can provide regarding API access and would welcome the opportunity to discuss the project in greater detail.

Best regards,

Jorge Plascencia Correa

It sounds like a great project. Please submit your request for the API key. We will send the terms of the agreement contract within the next day or so to get the ball rolling and get developers working directly with the API and their local HYDROS devices.

 

[Jorgex3]

It sounds like a great project. Please submit your request for the API key. We will send the terms of the agreement contract within the next day or so to get the ball rolling and get developers working directly with the API and their local HYDROS devices.

Request has been submitted for a cuple of days now.

 

[Carlos]

Check your emails.