API v1 Documentation

Overview

The imbrr API provides access to the latest device reading and flow event data. All endpoints require authentication via PHP session cookies.

Base URL:

https://www.imbrr.com/api/v1/

GET /api/v1/latest_depth/{id}

Description

Returns the latest depth-to-water reading for a specific device.

Parameters

Parameter Type Required Description
id string Yes Device ID (format: AABBCCDDEEFF)

Response Format

Returns JSON with the following structure:

{
  "status": "success",
  "id": "AABBCCDDEEFF",
  "depth_to_water": 577.366,
  "timestamp": "2025-06-27 14:30:25",
  "reading_id": 628381,
  "unique_id": 1751058571,
  "flow_event_status": "completed",
  "accumulated_gallons": 1.57
}

Example Request

GET /api/v1/latest_depth/AABBCCDDEEFF

Example Response

{
  "status": "success",
  "id": "AABBCCDDEEFF",
  "depth_to_water": 45.2,
  "timestamp": "2024-01-15 14:30:25",
  "reading_id": 12345,
  "unique_id": 67890,
  "flow_event_status": "completed",
  "accumulated_gallons": 125.5
}

Flow Event Status Logic

The flow_event_status field indicates whether a flow event is currently in progress or has completed:

  • "in_progress": No flow event record exists for the reading's unique_id
  • "completed": A flow event record exists for the reading's unique_id

Accumulated Gallons Logic

The accumulated_gallons field sums all gallons for the current unique_id:

  • Includes hidden readings in the calculation

Error Responses

401 Unauthorized
{
  "status": "failed",
  "message": "User not authenticated"
}
400 Bad Request
{
  "status": "failed",
  "message": "id parameter is required"
}
404 Not Found
{
  "status": "failed",
  "message": "Device not found"
}
403 Forbidden
{
  "status": "failed",
  "message": "You do not have access to this device"
}
GET /api/v1/latest_flow_event/{id}

Description

Returns the latest flow event data for a specific device in CSV format. Downloads a CSV file with all readings from the most recent flow event.

Parameters

Parameter Type Required Description
id string Yes Device ID (format: AABBCCDDEEFF)

Response Format

Returns CSV data with the following columns:

reading_id,pk_to_pk,psi,gain,flow,gallons,temp,depth_to_water,unique_id,hide_from_graph,atof_ups,atof_dns,dtof,timestamp,created

Example Request

GET /api/v1/latest_flow_event/AABBCCDDEEFF

Error Responses

401 Unauthorized
Error: User not authenticated
400 Bad Request
Error: id parameter is required
404 Not Found
Error: Device not found
403 Forbidden
Error: You do not have access to this device

Authentication

All API endpoints require authentication. Users must be logged in through the login page before accessing the API.

Note:

API access is restricted to authenticated users only. Make sure you have a valid session before making API requests.

Usage Examples

Python Example

import requests
import json
import argparse
import sys

def main():
    # Set up command line argument parsing
    parser = argparse.ArgumentParser(description='imbrr API Client')
    parser.add_argument('--email', required=True, help='Your email address')
    parser.add_argument('--password', required=True, help='Your password')
    parser.add_argument('--id', required=True, help='Device ID (format: AABBCCDDEEFF)')
    parser.add_argument('--base-url', default='https://www.imbrr.com', help='Base URL (default: https://www.imbrr.com)')

    args = parser.parse_args()

    # Configuration
    BASE_URL = args.base_url
    LOGIN_URL = f"{BASE_URL}/login"
    API_BASE = f"{BASE_URL}/api/v1"

    # Create a session to maintain cookies
    session = requests.Session()

    # Login credentials from command line arguments
    login_data = {
        'email': args.email,
        'password': args.password
    }

    # Step 1: Authenticate by logging in
    print("Logging in...")
    login_response = session.post(LOGIN_URL, data=login_data, allow_redirects=True)

    # Check if login was successful (should redirect to dashboard)
    if login_response.status_code == 200 and 'dashboard' in login_response.url:
        print("Login successful! Redirected to dashboard.")

        # Step 2: Get latest depth reading
        device_id = args.id
        depth_url = f"{API_BASE}/latest_depth/{device_id}"

        print(f"Fetching latest depth for device {device_id}...")
        depth_response = session.get(depth_url)

        print(f"Depth response content: {depth_response.text[:500]}...")  # First 500 chars

        if depth_response.status_code == 200:
            try:
                depth_data = depth_response.json()
                print("Latest Depth Reading:")
                print(f"  Depth to water: {depth_data['depth_to_water']}")
                print(f"  Timestamp: {depth_data['timestamp']}")
                print(f"  Flow event status: {depth_data['flow_event_status']}")
                print(f"  Accumulated gallons: {depth_data['accumulated_gallons']}")
            except json.JSONDecodeError as e:
                print(f"Error parsing JSON response: {e}")
                print(f"Raw response: {depth_response.text}")
        else:
            print(f"Error getting depth data: {depth_response.status_code}")
            print(depth_response.text)

        # Step 3: Get latest flow event (CSV download)
        flow_url = f"{API_BASE}/latest_flow_event/{device_id}"

        print(f"Downloading latest flow event for device {device_id}...")
        flow_response = session.get(flow_url)

        print(f"Flow response status: {flow_response.status_code}")

        if flow_response.status_code == 200:
            # Save CSV to file
            filename = f"flow_event_{device_id}.csv"
            with open(filename, 'wb') as f:
                f.write(flow_response.content)
            print(f"Flow event data saved to {filename}")
        else:
            print(f"Error getting flow event data: {flow_response.status_code}")
            print(flow_response.text)

    else:
        print(f"Login failed or unexpected redirect: {login_response.status_code}")
        print(f"Final URL: {login_response.url}")
        print(f"Response content: {login_response.text[:500]}...")
        sys.exit(1)

if __name__ == "__main__":
    main()

Usage:

python3 api_client.py --email your_email@example.com --password your_password --id AABBCCDDEEFF

cURL Example

# Get latest depth reading
curl -X GET "https://www.imbrr.com/api/v1/latest_depth/AABBCCDDEEFF" \
     -H "Cookie: PHPSESSID=your_session_id" \
     -H "Content-Type: application/json"

Notes

  • All timestamps are returned in the device's configured timezone
  • Device IDs should be in the format AABBCCDDEEFF
  • Accumulated gallons include all readings for the current flow event (includes hidden readings)
  • The latest_flow_event endpoint downloads a CSV file with all readings from the most recent flow event