REST API

With the HTTP API you read the devices of your account from your own program. The API sees the same devices and has the same permissions as your account in the app.

Basics

Item	Value
Base URL	https://api.hamsystems.eu
Request format	POST with application/x-www-form-urlencoded, unless the section says something different
Response format	JSON
Serial number	<family>:<number>, for example e11:123. The first part is the device family.

Most responses have a messages field. It is a list of objects {"text": "...", "type": "error"}. The type is error, success or info.

Authentication

There are two methods:

Method	How you get it	Lifetime
API key (api_key)	From the Account page of the app	It does not expire. One key per account.
Access token (access_token)	From login.php or login_api.php	60 days

Send the API key in one of these ways:

• Parameter api_key in the POST body or in the query string.
• Header Authorization: Bearer-API YOUR_API_KEY.

Send the access token in one of these ways:

• Parameter access_token in the POST body or in the query string.
• Header Authorization: Bearer YOUR_ACCESS_TOKEN.

If you send both, the server uses the API key.

Caution

The API key gives full access to your account. Do not put it in code that runs in a browser or in a public repository.

Create an API key

1. Open the Menu and tap Account.
2. In the API Key section, tap Generate API key.
3. Confirm the message. A new key cancels the old key.
4. Tap the key to copy it. The app shows Copied.

Computer

Phone

To cancel a key, create a new key. The old key stops working immediately.

Endpoints

Check a key: check_api_key.php

Checks an API key.

curl -X POST https://api.hamsystems.eu/check_api_key.php \
  -d api_key=YOUR_API_KEY

Response: user, messages. If the key is not correct, messages has the error Api key not found.

Access token from a key: login_api.php

Gives an access token for the API key. Use it when a tool accepts only an access token.

Parameter	Value
key	The API key

curl -X POST https://api.hamsystems.eu/login_api.php \
  -d key=YOUR_API_KEY

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "user": { "id": 1234 },
  "messages": []
}

This endpoint has an attempt limit. After many failures it replies Too many attempts, try again later.

Sign in with email: login.php

Parameter	Value
email	The account email
password	The password
timezone	Optional. The time zone, for example Europe/Athens.

Response: access_token, user, messages. If must_recaptcha is true, the server asks for a reCAPTCHA check. Then use an API key.

Device list: get_user_devices.php

Returns the devices, groups, floor plans and scenes of the account.

curl -X POST "https://api.hamsystems.eu/get_user_devices.php?v=2" \
  -H "Authorization: Bearer-API YOUR_API_KEY"

Response fields: devices, groups, floorplans, scenes, messages. With ?v=2&definitions=1 the response also has a definitions field for the families of your devices.

Each device has these fields:

Field	Content
serialno	The serial number, for example e11:123
name, icon	The name and the icon from the app
mac	The MAC address
device_server	The device server of the device. You need it for history and for the WebSocket.
latitude, longitude	The location, if it is set
firmware_version	The firmware version
settings	The device settings
groups, floorplans	The groups and floor plans of the device
permissions	Your permission on the device (see below)

Values of permissions:

Value	Permission
1	Read
2	Write (control outputs)
3	Admin
4	Owner

One device: get_device_info.php

Parameter	Value
serialno	The serial number

curl -X POST "https://api.hamsystems.eu/get_device_info.php?v=2" \
  -H "Authorization: Bearer-API YOUR_API_KEY" \
  -d serialno=e11:123

Response: device (the same fields as in the list), messages. It also accepts &definitions=1. Without serialno it replies with HTTP 400. Without access to the device it replies with HTTP 403.

Current state: get_device_state.php

Returns the current readings of one or more devices. The body is JSON.

curl -X POST https://api.hamsystems.eu/get_device_state.php \
  -H "Authorization: Bearer-API YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"serialno": "e11:123"}'

{
  "serialno": "e11:123",
  "name": "Fridge 1",
  "state": {
    "connected": true,
    "timestamp": 1791936198,
    "readings": { "T": 2082, "GI": 1, "GIC": 0, "GI2": 1, "GI2C": 0 },
    "rssi": -55,
    "device_name": "Fridge 1"
  }
}

For more devices, send a list: {"serialno": ["e11:123", "e9:456"]}. The response is {"devices": [...], "count": 2}. If the state is not available, state is {"connected": false, "message": "Device state not available"}. Without authentication the response is HTTP 401 with {"error": "Authentication required"}.

Note

The values in readings are raw. In the example, T: 2082 means 20.82 °C. The family definition tells you how to convert each value. See the family definitions below.

Family definitions

The definitions tell you which readings, outputs and settings each family has. They do not need authentication.

curl "https://api.hamsystems.eu/get_device_definitions.php?family_id=e11"

The response has families and readings. With &include_readings=false the response does not have the readings dictionary. Without family_id the response has all families.

Each family has:

Field	Content
readings	The reading codes in their order, for example ["T", "GI", "GIC", "GI2", "GI2C"]
output_names	The outputs in their order
settings	The settings of the family
ping_period	The keep-alive interval in seconds

The readings dictionary gives the label, the unit and the conversion for each reading code. For example, reading T has the unit °C and the conversion divide_by_100. You can also see the list of readings on the Readings page.

The value 2147483648 means that the reading is missing.

Timeout

Set a timeout of about 30 seconds on your requests.

See also

• Download historical data
• Live data (WebSocket)
• MCP for AI assistants
• Virtual devices