> For the complete documentation index, see [llms.txt](https://docs.efento.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.efento.io/nb-iot-loggers/integrations/efento-coap-loader/api-reference/measurements.md).

# Measurements

Endpoint for receiving periodic measurement data from sensors

## Receive measurements from sensors

> \## Overview\
> \
> This endpoint is used by the CoAP Loader to forward periodic measurement data from Efento NB-IoT sensors to your platform.\
> \
> \*\*Important:\*\* The endpoint paths shown in this documentation (\`/measurements\`, \`/configuration\`, \`/device-info\`) are \*\*examples only\*\*.\
> \
> The actual endpoint URLs are fully configurable in the CoAP Loader's \`application.yml\` file\
> \
> \*\*When is it called?\*\*\
> \- At regular intervals configured on the sensor (e.g., every 15 minutes)\
> \- When a rule/alarm is triggered on the sensor\
> \- When the sensor's buffer is full\
> \
> \*\*What data do you receive?\*\*\
> \- Sensor readings: temperature, humidity, pressure, alarms, water/electricity meters, air quality, etc.\
> \- Metadata: battery status, signal strength, measurement timestamps\
> \- Multiple sensors can send data in a single request\
> \
> \## Request Structure\
> \
> \*\*Method:\*\* \`POST\`\
> \
> \*\*Endpoint:\*\* Configurable in \`application.yml\` under the \`endpoint\` key. The path \`/measurements\` shown here is just an example.\
> \
> \*\*Headers:\*\*\
> \- \`Content-Type: application/json\`\
> \- \`charset: UTF-8\`\
> \- \`X-Api-Token: "optional api token"\` (if configured on sensor via CLOUD\_TOKEN parameter)\
> \
> \*\*Body:\*\* JSON array containing measurement objects. Each measurement object includes:\
> \- \`serial\` - Unique sensor identifier\
> \- \`battery\` - Battery status: "ok" or "low"\
> \- \`signal\` - Signal quality (0-63, based on RSSI)\
> \- \`measured\_at\` - UTC timestamp of measurement\
> \- \`measurement\_interval\` - Interval between measurements in seconds\
> \- \`next\_measurement\_at\` - Scheduled UTC time for next connection\
> \- \`params\` - Array of measured parameters (channels 1-6)\
> \
> \## Data Filtering - Empty Measurements\
> \
> The CoAP Loader automatically filters out channels with type "NO\_SENSOR" (unconfigured/disabled sensor channels). This may result in:\
> \- \*\*Empty measurements array\*\*: If all sensor channels are of type NO\_SENSOR, the measurements array will be empty and \*\*no data will be forwarded\*\* to your REST API\
> \- \*\*Partial data\*\*: Only channels with actual sensors connected will be included in the request\
> \
> This is normal behavior - sensors can have 1-6 channels, and not all channels need to be physically connected.\
> \
> \## Response Options\
> \
> Your platform must respond with HTTP status code \*\*2xx\*\* (e.g., 200, 201, or 204) to confirm receipt.\
> \
> \### Option 1: Empty Response\
> Simply confirms receipt of data:\
> \`\`\`json\
> {}\
> \`\`\`\
> \
> \### Option 2: Configuration Update\
> You can include a JSON object in the response body to remotely change the sensor's settings:\
> \`\`\`json\
> {\
> &#x20; "parameters": \[\
> &#x20;   {\
> &#x20;     "type": "MEASUREMENT\_PERIOD",\
> &#x20;     "settings": {\
> &#x20;       "period": "600"\
> &#x20;     }\
> &#x20;   }\
> &#x20; ]\
> }\
> \`\`\`\
> \
> For a full list of available configuration parameter types and their validation rules, see the \*\*ConfigurationParametersReference\*\* in the Models section.\
> \
> \## Response: Configuration Parameter Validation\
> \
> When you return configuration parameters in the response:\
> \- \*\*Duplicate parameter types\*\*: If you send multiple parameters with the same \`type\`, the CoAP Loader will keep only the \*\*last occurrence\*\* and log a warning\
> \- \*\*Invalid parameters\*\*: Parameters that fail validation (wrong value ranges, missing required fields, etc.) are \*\*automatically removed\*\* and logged as errors - the remaining valid parameters are still applied to the sensor\
> \- \*\*Partial success\*\*: Even if some parameters fail validation, the valid ones will be sent to the sensor\
> \
> \## Important - Software Version Compatibility\
> \
> Configuration updates are only supported on sensors with modern firmware. The CoAP Loader determines this by checking the sensor's \`hash\` value:\
> \- \*\*hash = "0"\*\*: Deprecated software version - configuration changes are NOT sent to the sensor (the CoAP Loader will log a warning and skip configuration)\
> \- \*\*hash > "0"\*\*: Modern software version - configuration changes can be applied normally\
> \
> If you send configuration parameters in the response for a sensor with hash="0", they will be ignored by the CoAP Loader.<br>

````json
{"openapi":"3.0.3","info":{"title":"CoAP Loader API Documentation","version":"3.0.0"},"tags":[{"name":"Measurements","description":"Endpoint for receiving periodic measurement data from sensors"}],"paths":{"/measurements":{"post":{"tags":["Measurements"],"summary":"Receive measurements from sensors","description":"## Overview\n\nThis endpoint is used by the CoAP Loader to forward periodic measurement data from Efento NB-IoT sensors to your platform.\n\n**Important:** The endpoint paths shown in this documentation (`/measurements`, `/configuration`, `/device-info`) are **examples only**.\n\nThe actual endpoint URLs are fully configurable in the CoAP Loader's `application.yml` file\n\n**When is it called?**\n- At regular intervals configured on the sensor (e.g., every 15 minutes)\n- When a rule/alarm is triggered on the sensor\n- When the sensor's buffer is full\n\n**What data do you receive?**\n- Sensor readings: temperature, humidity, pressure, alarms, water/electricity meters, air quality, etc.\n- Metadata: battery status, signal strength, measurement timestamps\n- Multiple sensors can send data in a single request\n\n## Request Structure\n\n**Method:** `POST`\n\n**Endpoint:** Configurable in `application.yml` under the `endpoint` key. The path `/measurements` shown here is just an example.\n\n**Headers:**\n- `Content-Type: application/json`\n- `charset: UTF-8`\n- `X-Api-Token: \"optional api token\"` (if configured on sensor via CLOUD_TOKEN parameter)\n\n**Body:** JSON array containing measurement objects. Each measurement object includes:\n- `serial` - Unique sensor identifier\n- `battery` - Battery status: \"ok\" or \"low\"\n- `signal` - Signal quality (0-63, based on RSSI)\n- `measured_at` - UTC timestamp of measurement\n- `measurement_interval` - Interval between measurements in seconds\n- `next_measurement_at` - Scheduled UTC time for next connection\n- `params` - Array of measured parameters (channels 1-6)\n\n## Data Filtering - Empty Measurements\n\nThe CoAP Loader automatically filters out channels with type \"NO_SENSOR\" (unconfigured/disabled sensor channels). This may result in:\n- **Empty measurements array**: If all sensor channels are of type NO_SENSOR, the measurements array will be empty and **no data will be forwarded** to your REST API\n- **Partial data**: Only channels with actual sensors connected will be included in the request\n\nThis is normal behavior - sensors can have 1-6 channels, and not all channels need to be physically connected.\n\n## Response Options\n\nYour platform must respond with HTTP status code **2xx** (e.g., 200, 201, or 204) to confirm receipt.\n\n### Option 1: Empty Response\nSimply confirms receipt of data:\n```json\n{}\n```\n\n### Option 2: Configuration Update\nYou can include a JSON object in the response body to remotely change the sensor's settings:\n```json\n{\n  \"parameters\": [\n    {\n      \"type\": \"MEASUREMENT_PERIOD\",\n      \"settings\": {\n        \"period\": \"600\"\n      }\n    }\n  ]\n}\n```\n\nFor a full list of available configuration parameter types and their validation rules, see the **ConfigurationParametersReference** in the Models section.\n\n## Response: Configuration Parameter Validation\n\nWhen you return configuration parameters in the response:\n- **Duplicate parameter types**: If you send multiple parameters with the same `type`, the CoAP Loader will keep only the **last occurrence** and log a warning\n- **Invalid parameters**: Parameters that fail validation (wrong value ranges, missing required fields, etc.) are **automatically removed** and logged as errors - the remaining valid parameters are still applied to the sensor\n- **Partial success**: Even if some parameters fail validation, the valid ones will be sent to the sensor\n\n## Important - Software Version Compatibility\n\nConfiguration updates are only supported on sensors with modern firmware. The CoAP Loader determines this by checking the sensor's `hash` value:\n- **hash = \"0\"**: Deprecated software version - configuration changes are NOT sent to the sensor (the CoAP Loader will log a warning and skip configuration)\n- **hash > \"0\"**: Modern software version - configuration changes can be applied normally\n\nIf you send configuration parameters in the response for a sensor with hash=\"0\", they will be ignored by the CoAP Loader.\n","operationId":"receiveMeasurements","parameters":[{"name":"X-Api-Token","in":"header","description":"Optional API token for authentication (if configured)","required":false,"schema":{"type":"string"}},{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string","default":"application/json"}},{"name":"charset","in":"header","required":true,"schema":{"type":"string","default":"UTF-8"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["measurements"],"properties":{"measurements":{"type":"array","description":"Array of measurement objects from sensors","items":{"$ref":"#/components/schemas/Measurement"}}}}}}},"responses":{"401":{"description":"Unauthorized.\n\n**HTTP to CoAP mapping:** HTTP 401 or 403 will be converted to CoAP 4.01 UNAUTHORIZED.\n\n**Sensor behavior:** The sensor does NOT receive any configuration updates. The sensor will retry according to its retry policy.\n"},"403":{"description":"Forbidden.\n\n**HTTP to CoAP mapping:** HTTP 401 or 403 will be converted to CoAP 4.01 UNAUTHORIZED.\n\n**Sensor behavior:** The sensor does NOT receive any configuration updates. The sensor will retry according to its retry policy.\n"},"2XX":{"description":"Success - Data received successfully.\n\nYou can return an empty response or include configuration parameters to update the sensor.\nSee endpoint description above for details on parameter validation and error handling.\n\n**HTTP to CoAP mapping:** Any 2xx HTTP status code (200, 201, 204, etc.) will be converted to CoAP 2.01 CREATED.\n\n**Sensor behavior:** The sensor receives the response and applies any configuration parameters included in the response body.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigurationResponse"}}}},"3XX":{"description":"Redirection.\n\n**HTTP to CoAP mapping:** Any 3xx HTTP status code (301, 302, 304, etc.) will be converted to CoAP 5.00 INTERNAL SERVER ERROR.\n\n**Sensor behavior:** The sensor does NOT receive any configuration updates. The sensor will retry according to its retry policy.\n"},"4XX":{"description":"Client Error.\n\n**HTTP to CoAP mapping:** Any 4xx HTTP status code (except 401/403) will be converted to CoAP 4.00 BAD REQUEST.\n\n**Sensor behavior:** The sensor does NOT receive any configuration updates. The sensor will retry according to its retry policy.\n"},"5XX":{"description":"Server Error.\n\n**HTTP to CoAP mapping:** Any 5xx HTTP status code (500, 502, 503, etc.) will be converted to CoAP 5.00 INTERNAL SERVER ERROR.\n\n**Sensor behavior:** The sensor does NOT receive any configuration updates. The sensor will retry according to its retry policy.\n"}}}}},"components":{"schemas":{"Measurement":{"type":"object","required":["serial","battery","signal","measured_at","measurement_interval","next_measurement_at","params"],"properties":{"serial":{"type":"string","description":"Unique serial number of the sensor"},"battery":{"type":"string","description":"Battery level status","enum":["ok","low"]},"signal":{"type":"integer","description":"Signal quality indicator based on RSSI (0-63)","minimum":0,"maximum":63},"measured_at":{"type":"string","description":"UTC date and time of the measurement"},"measurement_interval":{"type":"integer","description":"The interval between measurements in seconds"},"next_measurement_at":{"type":"string","description":"The scheduled UTC time for the next connection"},"params":{"type":"array","description":"A list of measured physical parameters.\n\n**Note:** This array may be empty if all sensor channels are of type NO_SENSOR (unconfigured/disabled channels).\nThe CoAP Loader automatically filters out NO_SENSOR channels before forwarding data to your API.\n","items":{"$ref":"#/components/schemas/MeasurementParam"}}}},"MeasurementParam":{"type":"object","required":["channel","type","value","status"],"properties":{"channel":{"type":"integer","description":"The sensor channel number","minimum":1,"maximum":6},"type":{"type":"string","description":"The Measurement Type","enum":["temperature","humidity","pressure","pressure_diff","open-close","iaq","flooding","pulse_counter","electricity_usage","water_usage","soil_moisture","co_gas","no2_gas","h2s_gas","ambient_light","pm_1_0","pm_2_5","pm_10_0","noise_level","nh3_gas","ch4_gas","high_pressure","distance_mm","water_meter_acc","co2_gas","humidity_accurate","static_iaq","co2_equivalent","breath_voc","percentage","voltage","current","electricity_meter_acc","output_control","shared_modem"]},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"The actual value recorded for this measurement"},"status":{"type":"string","description":"Indicates reading health","enum":["ok","error"]}}},"ConfigurationResponse":{"type":"object","description":"Response body to remotely change the sensor's settings","properties":{"parameters":{"type":"array","description":"List of parameters to update on the sensor","items":{"$ref":"#/components/schemas/SensorParameter"}}}},"SensorParameter":{"type":"object","required":["type","settings"],"properties":{"type":{"type":"string","description":"The unique name of the parameter. Available types include:\nACK_INTERVAL, APN, BANDS, BLE_TURNOFF_TIME, BLE_TX_POWER_LEVEL,\nCELLULAR_CONFIG, CLOUD_TOKEN, CLOUD_TOKEN_COAP_OPTION,\nCONFIGURATION_ENDPOINT, DATA_ENDPOINT, DEVICE_INFO_ENDPOINT,\nDNS_SERVER, DNS_TTL_CONFIG, ENCRYPTION_KEY, LED_CONFIG,\nMEASUREMENT_PERIOD, NETWORK_TROUBLESHOOTING,\nPAYLOAD_SIGNATURE_COAP_OPTION, PLMN, REQUEST_DISABLE_MODEM,\nSERVER_DATA, SERVER_UPDATE, SUPERVISION_PERIOD, TIME_ENDPOINT,\nTRANSMISSION_INTERVAL, TRANSFER_LIMIT, TRANSFER_LIMIT_TIMER,\nCALIBRATION, RULE_1 through RULE_12, RULE_CALENDAR_1 through RULE_CALENDAR_6\n\nFor detailed specification of each parameter type, including required fields and validation rules, see **ConfigurationParametersReference** in the Models section.\n"},"settings":{"type":"object","description":"A nested object containing specific key-value pairs for that parameter","additionalProperties":true}}}}}}
````


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.efento.io/nb-iot-loggers/integrations/efento-coap-loader/api-reference/measurements.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.