Device event API

Submit readings from a device over HTTP. For the workflow around this endpoint, see Send data over HTTP.

Endpoint


POST /api/v1/deviceapi/event
Content-Type: application/json
Authorization: Bearer YOUR_DEVICE_TOKEN

Use the Copy API URL action on the device overview to get the base URL for your environment. The path is versioned under /api/v1.

Request body

Field	Type	Required	Description
`serial`	string	yes	The device serial number. Identifies which device is reporting.
`data`	object	yes	Readings, keyed by device input name.
`accessToken`	string	no	Device token, as an alternative to the `Authorization` header.

request


{
  "serial": "YOUR_DEVICE_SERIAL",
  "data": {
    "temperature": 23.4,
    "humidity": 58
  }
}

The device token may be supplied either as a Bearer token in the Authorization header or as accessToken in the body. Prefer the header: a token in the body travels alongside telemetry and is more likely to end up in logs or stored payloads.

Only devices whose connection type is API accept this endpoint. A device configured for MQTT will be rejected as having an invalid access token even if the token itself is correct.

Response

Every response is a JSON object with this shape:


{
  success: boolean
  message: string
  error?: string
}

Read success, not the HTTP status. The endpoint reports rejected readings in the response body, so a request can complete normally and still have stored nothing.

Success


{
  "success": true,
  "message": "Message processed and data stored successfully"
}

Rejections

`message`	`error`	What to fix
`Invalid message format`	`Message must be a valid JSON object`	Send a JSON object as the body.
`Missing serial number`	`Device serial number is required`	Include `serial`.
`Missing access token`	`Device access token is required (either in data or as Bearer token)`	Send the `Authorization` header or `accessToken`.
`Invalid data format`	`Message data must be a valid object`	`data` must be an object, not a string or array.
`Device not found`	`Device with serial <serial> not found`	Check the serial against the device record.
`Invalid access token`	`Invalid access token for device with serial <serial>`	Check the token, and that the device’s connection type is API.
`No connections configured`	`No connections found for this device`	Map the payload keys to entity inputs. See entities and mappings.
`Message processed but failed to store data`	storage error	Reading was accepted but not persisted; retry and report if it continues.
`Failed to process message`	underlying error	Unexpected failure; safe to retry.

Handling `No connections configured`

This is the response that most often surprises integrators. It means the request was authenticated and well-formed, but none of the keys in data matched a device input that is connected to an entity.

The reading is not stored. Nothing is wrong with your request — the mapping is missing in the workspace. See payloads and input matching.

Client guidance

Treat any success: false as a failure, regardless of HTTP status.
Log message and error together; the pair identifies the cause exactly.
Retry on Failed to process message and storage failures. Do not retry configuration rejections — they will fail identically until the workspace is changed.
Set a request timeout and do not block the device’s sampling loop on the response.

Verifying end to end

An accepted request confirms ingestion only. To confirm the full path:

Check the device’s Messages tab for the raw message.
Check the mapped entity input for the new value.
Check the dashboard widget and its time range.

Each stage can fail independently — see troubleshooting.