Device REST API documentation.

The esp_iot_framework_device provides a comprehensive REST API and static files for device management and monitoring. All API endpoints are prefixed with /_/ and support JSON format for requests and responses.

Authentication

When Kconfig option CONFIG_EIF_ENABLE_BASIC_AUTH is enabled, all administrative endpoints (all endpoints listed in MAP URIs) require HTTP Basic Authentication.

To authenticate, include the following HTTP header in each of your requests:

Authorization: Basic <base64_encoded_credentials>

Note
Replace the <base64_encoded_credentials> above with your Base64-encoded admin:<your_password>. <your_password> set via web interface or API (default: empty string).

Example of use:

GET /_/wifi/result.json HTTP/1.1
Host: 192.168.4.1
Authorization: Basic YWRtaW46
Content-Length: 20
 
{"profile_index": 1}

Map URIs

/_
- /files - only if the Kconfig option CONFIG_EIF_ENABLE_WEB_ADMIN_GUI is enabled
  - /index.html - Main interface container
  - /network.html - Network management page
  - /system.html - System management page
  - /style.css - Stylesheet
  - /api.js - JavaScript API library
  - /json2.js - JSON utility library
  - /license.txt - License information
- /wifi
  - /list.json - List Wi-Fi profiles
  - /update.do - Update Wi-Fi profile
  - /clear.do - Clear Wi-Fi profile
  - /check.do - Wi-Fi network availability test
  - /result.json - Get the results of the Wi-Fi test
- /tls - only if the Kconfig option CONFIG_EIF_ENABLE_TLS is enabled
  - /recreate.do - Regenerate TLS keys and certificate
- /sys
  - /info.json - Get system information
  - /reboot.do - Reboot system
    - /ota
  - /info.json - Get firmware information
  - /update.do - Upload firmware
  - /confirm.do - Confirm successful update
  - /rollback.do - Rollback firmware
    - /apass - only if the Kconfig option CONFIG_EIF_ENABLE_BASIC_AUTH is enabled
  - /update.do - Update administrator password

HTTP Status Codes

200 OK - Successful GET request
202 Accepted - Action accepted and processing
204 No Content - Successful POST
400 Bad Request - Invalid request parameters
401 Unauthorized - Authentication required/failed
404 Not Found - Resource not found
409 Conflict - Resource conflict (e.g., OTA already in progress)
500 Internal Server Error - Server error

API Endpoints

Wi-Fi Management

List Wi-Fi profiles
GET /_/wifi/list.json

Returns all configured Wi-Fi profiles and current connection status.

Request body: No body

Response body:
{

"current_profile_index": 0,

"rssi_now_profile": -65,

"profiles": [

{

"ssid": "ESP32_SETUP",

"password": "12345678"

},

{

"ssid": "OfficeWiFi"

},

{

"ssid": ""

}

]

}

Fields:
- current_profile_index: Currently active profile (0 - X, is set using eif_set_wifi_profiles_count(), otherwise it is EIF_WIFI_PROFILES_DEFAULT_COUNT)
- rssi_now_profile: RSSI of current connection in dBm
- profiles: Array of Wi-Fi profiles
  - ssid: Network SSID (empty if not configured)
  - password: Password (only for profile 0)

Update Wi-Fi profile
POST /_/wifi/update.do

Update the values of the existing profile

Request body:
{

"profile_index": 1,

"ssid": "MyNetwork",

"password": "MyPassword123"

}

Fields:
- profile_index: Profile number (1 - X, is set using eif_set_wifi_profiles_count(), otherwise it is EIF_WIFI_PROFILES_DEFAULT_COUNT, profile 0 cannot be changed)
- ssid: Network SSID (EIF_WIFI_SSID_MIN_LEN - EIF_WIFI_SSID_MAX_LEN - 1 characters)
- password: Network password (EIF_WIFI_PASS_MIN_LEN - EIF_WIFI_PASS_MAX_LEN - 1 characters)
Response: HTTP 204 No Content

Clear Wi-Fi profile
POST /_/wifi/clear.do

Clear profile fields with empty values

Request Body:
{

"profile_index": 1

}

Fields:
- profile_index: Profile number (Profile number (1 - X, is set using eif_set_wifi_profiles_count(), otherwise it is EIF_WIFI_PROFILES_DEFAULT_COUNT), profile #0 cannot be changed)
Response: HTTP 204 No Content

Wi-Fi network availability test
POST /_/wifi/check.do

Checking the availability of a Wi-Fi network using profile

Request Body:
{

"profile_index": 1

}

Fields:
- profile_index: Profile number (0 - X, is set using eif_set_wifi_profiles_count(), otherwise it is EIF_WIFI_PROFILES_DEFAULT_COUNT)
Response: HTTP 202 Accepted

Warning
This operation can take quite a long time (tens of seconds). During the test, the ESP also disconnects from the actual Wi-Fi network and attempts to connect to the network being tested. This is done due to the physical limitations of the ESP.

Get the results of the Wi-Fi test
POST /_/wifi/result.json

Note
The use of POST is due to the fact that Internet Explorer 8 does not support sending a GET request with a body.
Get the results of the Wi-Fi network availability test

Request Body:
{

"profile_index": 1

}

Fields:
- profile_index: Profile number (0 - X, is set using eif_set_wifi_profiles_count(), otherwise it is EIF_WIFI_PROFILES_DEFAULT_COUNT)
Response body:
{

"result": true,

"rssi": -72

}

Fields:
- result: true if a connection was established and an IP address was obtained, false otherwise
- rssi: Signal strength in dBm
Warning
Due to the change of Wi-Fi networks for the test, this request may be sent too early and the server may not even see it. To get the result, use a loop of requests after some time has passed since the test started (about 8 seconds)

TLS Management

Note
Only available if the Kconfig option CONFIG_EIF_ENABLE_TLS is enabled.

Regenerate TLS keys and certificate
POST /_/tls/recreate.do

Generates a new self-signed TLS certificate and keys

Request Body: No body

Response: HTTP 202 Accepted

Warning
After regenerating TLS keys and certificate, the device will automatically restart to apply the new configuration. The entire process usually takes less than 5 seconds.

System Management

Get system information
GET /_/sys/info.json

Returns detailed system information.

Request body: No body

Response body:
{

"features": {

"has_wifi": true,

"has_bluetooth": true,

"has_ble": true

},

"heap_free": 123456,

"heap_min": 120000,

"largest_block": 80000,

"uptime": 3600,

"cores": 2,

"chip_rev": 3,

"flash_size": 4,

"cpu_freq": 240,

"chip_model": "ESP32",

"reset_reason": 1,

"features": "WBL",

"mac": "AA:BB:CC:DD:EE:FF"

}

Fields:
- features: Object containing supported hardware features
  - has_wifi: true if Wi-Fi (802.11 b/g/n) is supported
  - has_bluetooth: true if Bluetooth Classic is supported
  - has_ble: true if Bluetooth Low Energy (BLE) is supported
- heap_free: Current free heap in bytes
- heap_min: Minimum free heap since boot
- largest_block: Largest contiguous free memory block in heap
- uptime: System uptime in seconds
- cores: Number of CPU cores
- chip_rev: Chip revision
- flash_size: Flash size in MB
- cpu_freq: CPU frequency in MHz
- chip_model: ESP chip model
- reset_reason: Last reset reason code
- mac: Device MAC address

Reboot System
POST /_/sys/reboot.do

Gracefully reboot the device.

Request body: No body

Response: HTTP 202 Accepted

Warning
The device will reboot immediately after this request. All active connections will be closed.

OTA Updates

Get firmware information

GET /_/ota/info.json

Returns current firmware information.

Request body: No body

Response body:

{
  "project": "my_iot_project",
  "version": "1.0.0",
  "build_id": "a1b2c3d4e5f6...",
  "build_date": "Jan 1 2026",
  "build_time": "12:00:00",
  "idf_version": "v4.4.6",
  "compiler": "gcc 8.4.0",
  "target": "esp32",
  "partition": "factory",
  "ota_status": "valid"
}

Fields:

project: Project name
version: Firmware version
build_id: SHA256 of ELF file
build_date: Build date
build_time: Build time
idf_version: ESP-IDF version
compiler: Compiler version
target: Target chip
partition: Current running partition

ota_status: OTA status. Possible values:

Status	Description
`new`	Firmware uploaded, not booted yet.
`pending_verify`	First boot. Waiting for confirm.do.
`valid`	Firmware confirmed and stable.
`invalid`	Firmware failed checks.
`aborted`	Update interrupted.
`factory`	Running factory partition.

Upload firmware
POST /_/ota/update.do

Uploads a new firmware binary to the device. Once the upload is complete and verified, the device will automatically reboot to apply the update.

Request:
- Header Content-Type: application/octet-stream
- Body: Raw firmware binary (.bin file)
Response: HTTP 202 Accepted

Warning
The device will automatically restart after a successful upload. This process usually takes less than 5 seconds.

Confirm successful update
POST /_/ota/confirm.do

Marks the current firmware as valid to prevent automatic rollback on the next boot.

Request body: No body

Response: HTTP 202 Accepted

Rollback firmware
POST /_/ota/rollback.do

Rolls back to the previous firmware version. The device will automatically reboot.

Request body: No body

Response: HTTP 202 Accepted

Warning
The device will automatically restart immediately after the rollback is initiated. This process usually takes less than 5 seconds.

Authentication Management

Note
Only available if the Kconfig option CONFIG_EIF_ENABLE_BASIC_AUTH is enabled.

Update administrator password
POST /_/apass/update.do

Changes the administrator password used for Basic Authentication.

Request body:
{

"password": "NewSecurePassword123"

}

Fields:
- password: New password (EIF_BASIC_AUTH_PASS_MIN_LEN - EIF_BASIC_AUTH_PASS_MAX_LEN - 1 characters)
Response: HTTP 204 No Content