Device API

HiveControl accepts sensor data over a small HTTP API, the same one the open-source HiveDevice software uses. Any scale, sensor board or gateway that can make an HTTPS POST can send hive readings, weather and air quality to a HiveControl account with it.

• Base URL: https://hivecontrol.org (https://www.hivecontrol.org is served too). Use HTTPS: plain HTTP requests are answered with a 301 redirect.
• Method: every endpoint is POST.
• Auth: a device token from the HiveControl web app (see Authentication).

Quick start

Create a device token first: sign in at hivecontrol.org, open Settings → Device API tokens, and choose Create token. Copy it; it is shown only once. Below it is YOUR_DEVICE_TOKEN.

1. Look up the hive by name.

curl -s -X POST https://hivecontrol.org/api/v1/hive/check \
  -F "api_token=YOUR_DEVICE_TOKEN" \
  -F "hivename=Back Yard 1"

• {"error":"UPDATE_HIVEID","value":"100001"}: the hive exists. Save 100001 as the hive id and skip to step 3.
• {"error":"NOT_REGISTERED"}: no hive has that name yet. Create it (step 2).

2. Create the hive, then repeat step 1 to get its id.

curl -s -X POST https://hivecontrol.org/api/v1/hive/new \
  -F "api_token=YOUR_DEVICE_TOKEN" \
  -F "name=Back Yard 1" \
  -F "hc_version=1.0" \
  -F "timezone=America/New_York" \
  -F "power=solar" \
  -F "internet=wifi" \
  -F "status=active" \
  -F "computer=esp32" \
  -F "start_date=2026-10-28"

Reply: {"result":"SUCCESS"}. This reply has no id; call hive/check again.

3. Send a reading. Form fields and JSON both work; this one is JSON.

curl -s -X POST https://hivecontrol.org/api/v1/hive/data \
  -H "Authorization: Bearer YOUR_DEVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "hive_id": 100001,
    "hivename": "Back Yard 1",
    "hive_observation_time_local": "2026-10-28T12:00:00Z",
    "hive_temp_f": 93.4,
    "hive_humidity": 55.2,
    "hive_weight_lbs": 112.75,
    "hive_battery_voltage": 3.92
  }'

Reply: {"success":"1"}.

4. Send a batch of past readings.

curl -s -w "HTTP %{http_code}\n" -X POST https://hivecontrol.org/api/v1/hive/data/sync \
  -H "Authorization: Bearer YOUR_DEVICE_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary '[
    {"hive_id": 100001, "hive_name": "Back Yard 1", "hive_observation_time_local": "2026-10-28T10:00:00Z", "hive_temp_f": 91.8, "hive_weight_lbs": 112.1},
    {"hive_id": 100001, "hive_name": "Back Yard 1", "hive_observation_time_local": "2026-10-28T10:15:00Z", "hive_temp_f": 92.0, "hive_weight_lbs": 112.2}
  ]'

Reply: an empty body with HTTP 200 when every record was accepted.

5. Send weather from your own station.

curl -s -X POST https://hivecontrol.org/api/v1/wx/data \
  -H "Authorization: Bearer YOUR_DEVICE_TOKEN" \
  -F "wx_station_id=B4:E6:2D:07:87:49" \
  -F "wx_observation_time_rfc822=2026-10-28T12:00:00Z" \
  -F "wx_temp_f=52.3" \
  -F "wx_relative_humidity=71" \
  -F "wx_pressure_mb=1016.2"

Reply: {"success":"1"}.

Authentication

Every request needs a device token. Users create tokens in the web app under Settings → Device API tokens (the add-hive wizard can also create one). A token:

• is 60 letters and digits;
• is shown once, when it's created, and can be revoked at any time from the same page;
• does not expire;
• belongs to the account, not to one hive: it can send data for any hive in the account.

An account can hold up to 50 tokens. Use one per device so a lost device can be revoked alone.

Send the token in one of these places (checked in this order):

Prefer the header or a body field: URLs, query strings included, can end up in proxy and server logs.

A missing, wrong or revoked token, or a token of a disabled account, gets 401 {"error":"Unauthenticated."} from every endpoint.

Request format

Requests may be sent as:

With form and JSON-object requests, a field missing from the body is also looked up in the query string.

Values. Leading and trailing spaces and double quotes are trimmed from every value. An empty value, or the text null in any letter case, means "not sent". Numbers are plain decimals (93.4, -2, 1e3). Field names are case-sensitive, except configuration and equipment keys (noted where they apply). Fields the API doesn't know are ignored.

Size. Request bodies are limited to 1 MiB (1,048,576 bytes); a 500-record sync batch is about 350 KB.

Times

Timestamps are accepted in these forms:

A date starting 0000-00-00 counts as missing. Other formats, including RFC 822 dates, are not accepted.

Wall-clock times are read in the hive's time zone: the zone given at registration or by a later configuration update, or the hive's location zone if the hive has none, or UTC if neither is a valid IANA zone name. Fields whose name ends in _utc are read as UTC. A time that occurs twice when daylight saving time ends is taken as the first occurrence.

Allowed range. A reading's time must be after 1 January 2010 and no more than 24 hours ahead of the server's clock, or the reading is rejected (INVALID_DATA; in a sync, the record is skipped). Weather and air times must be after 1 January 2010 and no more than 1 hour ahead, or those values are dropped and the hive values kept.

Recommendation: send RFC 3339 with Z or an offset. It's unambiguous and doesn't depend on any time-zone setting.

Units

There are no unit fields. Every field has a fixed unit, given in its name and in the tables below: temperatures in °F (some fields have a _c alternative in °C), weight in pounds, wind in mph, pressure in millibars (or inches of mercury in wx_pressure_in), rain in inches. There is no kilogram weight field: convert before sending (1 kg = 2.20462 lb).

Hive names and hive ids

A device identifies its hive by name (hivename) and a numeric hive id (hive_id) that HiveControl assigns. Every endpoint except hive/new and hive/log checks the pair:

1. If hive_id is a hive in the token's account and that hive's name matches hivename: the request goes ahead.
2. Otherwise, if a hive in the account has the name hivename: the API answers with that hive's id (UPDATE_HIVEID) and stores nothing. Save the id and resend.
3. Otherwise: NOT_REGISTERED. Create the hive with hive/new.

Name matching ignores letter case and leading/trailing spaces: "back yard 1 " matches Back Yard 1. Everything else (inner spaces, punctuation) must match exactly. Only hives in the token's own account are ever matched.

What this means for a device:

• A new name is NOT_REGISTERED until you call hive/new.
• A name that matches an existing hive, including a hive the user created in the web app, is found by hive/check, which returns its id. Don't call hive/new for it: that returns DUPLICATE. The add-hive wizard tells the user to give the device the hive's name exactly, for this reason.
• If the user renames the hive in HiveControl, the device's old name no longer matches and the API answers NOT_REGISTERED. Update the device's name; don't register a new hive.
• If several hives in one account share a name, the one with the lowest hive id is used.

Weight: net of equipment

Send hive_weight_lbs as the net weight: what the scale reads minus the weight of the hive's equipment (bottom board, boxes, covers, feeder, and anything else on the scale, such as the electronics or a brick). That leaves bees, brood, comb and honey. This is what HiveDevice sends, and HiveControl shows and alerts on the value as sent.

HiveControl does not subtract anything from the uploaded weight. If your scale has no equipment settings, either subtract your own tare before sending, or use the hive's equipment from HiveControl:

• Once the user has saved the hive's equipment in the web app, hive/config returns its box counts (NUM_HIVE_*) and the weight of each kind of part (HIVE_*_WEIGHT, lbs). The tare is the sum of each count times the matching weight (NUM_HIVE_FEEDER × HIVE_FEEDER_WEIGHT, and so on), plus HIVE_TOP_WEIGHT, HIVE_COMPUTER_WEIGHT and HIVE_MISC_WEIGHT. Until then the weight keys are null.
• When the user changes the equipment, the hive's config version goes up, so poll it and reload the tare when it changes.

If you send gross weight instead, the charts still work but show the equipment as part of the hive.

Plausibility: a weight of exactly 0, below −10 lbs or above 500 lbs is treated as a sensor fault and dropped from the reading (see Validation). Small negative values are kept: they're expected calibration drift.

Validation

Each numeric field has an upper limit. A value that is not a number or is over the limit rejects the whole reading (INVALID_DATA, nothing stored). There are no lower limits unless stated.

Some hive values are dropped instead: the rest of the reading is stored and the reply is still a success. Old devices send 0 when a sensor is missing, and a disconnected load cell reads a fixed, impossible weight.

Weather and air values with a time more than 1 hour in the future (server clock) are dropped; the hive values of the same reading are still stored.

Duplicates

Sending a reading again is safe. HiveControl keeps one reading per hive per timestamp, one weather observation per station per minute, and one air reading per location per timestamp. The first one stored wins; later duplicates are ignored, and the reply is still a success.

Responses and errors

Most outcomes, including errors, are answered with HTTP 200 and a short JSON body. Always check the body, not just the status. Bodies are compact JSON with no spaces, as shown.

These can come from any endpoint:

The hive identity replies (from every endpoint that takes hive_id and hivename):

hive/check reports a stale id in its own format: {"error":"UPDATE_HIVEID","value":"100001"}.

Rate limit

Requests to all device endpoints together are limited per client IP address: a burst of up to 60 requests, refilled at 1 request per second. Over the limit, requests get 429. Devices behind one public IP (one home network, for example) share the budget. For history, use hive/data/sync with up to a few hundred readings per request rather than many hive/data calls, and pause about a second between batches.

Endpoints

POST /api/v1/hive/check

Looks up a hive by name and reports its id. Call it on first start, after the user changes the device's hive name, and when another endpoint answers NOT_REGISTERED. If a hive with this name was created in the web app, this is the call that connects the device to it.

POST /api/v1/hive/new

Creates a hive in the account. Call it only after hive/check answered NOT_REGISTERED. The hive is added to the user's first apiary; if the user has none, a location named "Home" and an apiary named "Home Apiary" are created. The reply does not include the new hive's id: call hive/check next to get it.

All fields are required, non-empty, and at most 255 bytes.

POST /api/v1/hive/data

Stores one reading: hive sensors, plus optional weather and air quality from the same moment. Call it each time the device takes a reading.

Fields: the identity fields, the reading fields, and optionally the weather and air fields. Only hive_id, hivename and hive_observation_time_local are required; send whichever sensor values you have.

POST /api/v1/hive/data/sync

Stores many readings in one request: for uploading history, or catching up after the device was offline. Send Content-Type: application/json with a JSON array of records, oldest first. Put the token in the Authorization header or the api_token query parameter (there is no body field for it).

Each record is an object with the same fields as hive/data, except that the hive name may be sent as hive_name (preferred) or hivename. Records may be for different hives in the account. Send at most 1,000 records per request (and within the 1 MiB body limit); HiveDevice sends 500 at a time. A few syncs are processed at once; others wait their turn.

Records are processed in order:

• a record that fails validation, or has no hive name, is skipped and counted;
• a record whose hive_id/name pair doesn't match stops the batch: records before it are stored, it and everything after it are not, and the reply is the identity error. Fix the id and resend from the start: readings already stored are ignored as duplicates.

POST /api/v1/wx/data

Stores a weather observation that isn't attached to a hive reading: for a stand-alone weather station. (To send weather with a hive reading, add the weather fields to hive/data instead.)

POST /api/v1/hive/log

Stores one line of the device's log. The user sees recent lines in the web app (they're kept for 30 days), and the add-hive wizard takes the first one as a sign the device has connected. Only the id is checked, not the name.

POST /api/v1/hive/config/version

Returns the version number of the hive's device configuration. The number goes up when the user changes settings or equipment in the web app. Poll it and download hive/config when it's higher than the version you have.

Fields: the identity fields.

POST /api/v1/hive/config

Returns the hive's device configuration: the HiveDevice settings the user can edit in the web app (sensors, calibration, weather source, equipment counts and weights, and so on). A third-party device can ignore the settings it has no use for; the equipment keys are useful for weight.

Fields: the identity fields.

Reply 200: one JSON object. Every configuration key is present, as a string or null when unset, plus:

{"id":100001,"name":"Back Yard 1","version":23,"timezone":"America/New_York",
 "NUM_HIVE_BODY_DEEP_FOUNDATION":"2","HIVE_BODY_DEEP_FOUNDATION_WEIGHT":"10.5",
 "gdd_base_temp":"50","enable_lux":null, "...": "..."}

Errors: {"error":"INVALID_DATA"} (identity fields missing or malformed) and the identity replies, all with status 200.

The configuration includes third-party weather API keys the user entered for the device (key_*, hive_air_api). Treat the reply as a secret.

POST /api/v1/hive/config/update

Uploads configuration values the device changed locally. Only the keys you send change.

How values are applied:

• An empty value or null clears that key. Keys you don't send are left alone.
• Unknown keys, and values over 1,000 bytes, are ignored.
• timezone must be a valid IANA zone name, or it's ignored. It also becomes the hive's time zone for reading wall-clock times.
• Once the user manages the hive's equipment in the web app, uploaded box counts and part weights (NUM_HIVE_*, HIVE_*_WEIGHT) are ignored: the web app's values win.
• If the user set the hive up in the web app before the device connected, the device's first upload doesn't overwrite the settings made there. The version is then set above the one you sent, so your next config/version check tells you to download the merged configuration.

POST /api/v1/hive/equipment

Uploads what the hive is built from, so HiveControl can manage it. Accepted once per hive: when the hive has no equipment saved yet. After that, equipment is edited in the web app and read back from hive/config. Field names may be in any letter case; values over 255 bytes are ignored.

The stack must have at least one part (from HIVE_STACK_ORDER or the counts). When the upload is stored, the configuration version goes up if the hive's counts or weights changed.

Field reference

Identity

Sent with hive/data, hive/data/sync records, and all hive/config* and hive/equipment requests.

Reading fields

Bee counts must be whole numbers (120 or 120.0).

Weather fields

Optional, with hive/data and sync records; at least one is required with wx/data. A weather observation is stored only if at least one of the measured values below is sent.

Air fields

Optional, with hive/data and sync records. Air readings belong to the hive's location: all hives at one location share them.

HiveDevice also sends these, which are accepted and ignored: record_id, wx_wind_dir, wx_precip_1hr_metric, wx_precip_today_in, wx_precip_today_metric, air_pm10_aqi, air_pm1_raw, air_pm2_5_raw, air_pm10_raw, air_pressure, air_source.

Weather stations

Weather is stored per station, chosen by wx_station_id. IDs of public weather networks are shared by every HiveControl user; anything else is private to your account.

Shared station IDs are upper-cased; private text IDs match without regard to case.

If you built the weather sensor, send its MAC address or a name, not a public station ID. Readings for a public station ID are shared with everyone who uses that station, and only the first observation for each minute is kept.

Configuration keys

Returned by hive/config and accepted by hive/config/update (any letter case). Most are HiveDevice settings.

hc_version timezone power internet status computer start_date run homedir public_html_dir
check_for_upgrades bee_race bee_source hive_type hive_status queen_start queen_color
enable_hive_temp_chk temptype hive_temp_gpio hive_temp_measure hivedevice hive_temp_slope
hive_temp_intercept hive_humidity_slope hive_humidity_intercept enable_hive_weight_chk
scaletype hive_weight_gpio hive_weight_slope hive_weight_intercept enable_lux lux_source
hive_lux_gpio hive_lux_slope hive_lux_intercept enable_hive_camera enable_beecounter
cameratype cameramode countertype gdd_base_temp gdd_start_date latitude longitude
local_wx_type local_wx_url weather_detail weather_level wx_humidity_intercept
wx_humidity_slope wx_temp_gpio wx_temp_intercept wx_temp_slope wx_temper_device wx_station
wx_temp_type enable_hive_air_chk hive_air_type hive_air_id hive_air_api weather_fallback
weather_fallback_2 wx_max_stale_minutes key_openweathermap key_weatherapi key_visualcrossing
key_pirateweather key_tomorrow key_ambee key_airnow enable_airnow airnow_distance

Equipment: box counts and the weight (lbs) of one part of each kind.

Once the web app manages the hive's equipment, the _LESS (foundationless) counts are 0 and those boxes are counted with their size.