User API Routes

This document describes api for MyBroodMinder users - currently in beta.

Send request for use to support@broodminder.com

Authentication

All endpoints require a rate-limited API key in the request header.

Header:

X-Api-Key: <your-api-key>

The key is associated to a single user account, only requests to that account's data are authorized.

Common query parameters

Endpoints

GET /user/metadata/apiaries

Returns the list of apiaries for the authenticated user.

• Query parameters: none

Success response

• 200 OK
• Body: array of apiary objects

[
  {
    "apiaryId": "apiary-123",
    "name": "Main Apiary",
    "color": "blue",
    "hives": [
      {
        "hiveId": "hive-456",
        "name": "Hive A",
        "description": "North field hive",
        "color": "yellow"
      }
    ],
    "location": {
      "latitude": 44.123456,
      "longitude": -93.123456
    }
  }
]

Notes

• Apiaries marked inactive are excluded from the response.

GET /user/hive/{id}/readings

Returns sensor readings grouped by position for a hive owned by the authenticated user. Limited to 6 months of data per request.

• Path parameter:
  • id — hive ID
• Query parameters:
  • start — epoch seconds
  • end — epoch seconds

Success response

• 200 OK
• Body: array of hive position reading objects

[
  {
    "positionID": "position-1",
    "positionName": "Front",
    "readings": [
      {
        "deviceId": "device-123",
        "timestamp": 1684128000,
        "batteryLevel": 93,
        "chargeRemaining": 110,
        "readings": {
          "temperature": 34.8,
          "humidity": 60.2
        }
      }
    ]
  }
]

Notes

• If the hive is not found, returns 400 Bad Request.
• If the hive does not belong to the user, returns 403 Forbidden.

GET /user/hive/{id}/notes

Returns notes attached to a hive for the authenticated user. Limited to 6 months of data per request.

• Path parameter:
  • id — hive ID
• Query parameters:
  • start — epoch seconds
  • end — epoch seconds

Success response

• 200 OK
• Body: object containing notes array

{
  "notes": [
    {
      "id": "note-123",
      "hiveId": "hive-456",
      "description": "Checked hive entrance.",
      "tags": [
        { "id": "tag-1", "name": "inspection" }
      ],
      "timestamp": 1684128000,
      "created": 1684128000,
      "modified": 1684129000
    }
  ]
}

Notes

• If the hive is not found, returns 400 Bad Request.
• If the hive does not belong to the user, returns 403 Forbidden.

GET /user/device/{id}/readings

Returns sensor readings for a single device belonging to the authenticated user. Limited to 6 months of data per request.

• Path parameter:
  • id — device ID
• Query parameters:
  • start — epoch seconds
  • end — epoch seconds

Success response

• 200 OK
• Body: array of sensor reading objects

[
  {
    "deviceId": "device-123",
    "timestamp": 1684128000,
    "batteryLevel": 95,
    "chargeRemaining": 120,
    "readings": {
      "temperature": 35.2,
      "humidity": 61.4,
      "weight": 25.76,
      "radar": 0,
      "audio": 0,
      "swarmState": 0
    }
  }
]

Notes

• If the device is not found, returns 400 Bad Request.
• If the device does not belong to the user, returns 403 Forbidden.

Common error responses

• 400 Bad Request — missing or invalid start / end, or resource not found
• 401 Unauthorized — missing or invalid API key or user context not available
• 403 Forbidden — resource does not belong to authenticated user
• 429 Too Many Requests — rate-limited API key usage limit exceeded
• 500 Internal Server Error — unexpected server or datastore failure

Example request

GET /user/device/abc123/readings?start=1684128000&end=1684214400 HTTP/1.1
Host: external-api.mybroodminder.com
X-Api-Key: YOUR_API_KEY

Recommended Usage Strategy

• Query apiary metada for your account
• Use metadata results to get hiveIDs
• Use hiveIDs to query hive sensor readings / notes
• Have a fun time