Last updated: August 15, 2026
Firmware upload, device flashing, flash history, and firmware management via REST API.
New to flashing? See the getting started guide first — it covers your first flash with the CLI. This page covers the details and the REST API.
For the first flash, manually enter BOOTSEL mode. BOOTSEL is a button on the board (e.g. Raspberry Pi Pico) that puts it into a USB mass-storage mode so you can copy firmware to it.
cd ~/ferqon/pico_tools
python3 flash_pico.py
# Output will guide you:
# 1. Hold BOOTSEL button
# 2. Press and release RESET while holding BOOTSEL
# 3. Script detects USB mount (RPI-RP2)
# 4. UF2 firmware copied
# 5. Device rebootsUF2is a firmware file format designed for flashing microcontrollers over USB — you just drag-and-drop it onto the board’s USB drive.
After the binary protocol firmware is loaded once, automatic BOOTSEL works — no button press needed:
cd ~/ferqon/pico_tools
python3 flash_pico.py
# Device automatically enters BOOTSEL mode
# No manual button press needed!| Endpoint | Method | Auth | Description |
|---|---|---|---|
| /api/flash | POST | Yes | Start flash job |
| /api/flash/jobs | GET | Yes | List flash jobs |
| /api/flash/jobs/{job_id} | GET | Yes | Get flash job status |
| /api/flash/jobs/{job_id}/cancel | POST | Yes | Cancel flash job |
| /api/flash/jobs/{job_id}/logs | GET | Yes | Get flash job logs |
| /api/flash/history | GET | Yes | Get flash history |
| /api/flash/upload | POST | Yes | Upload firmware |
| /api/flash/uploads | GET | Yes | List firmware uploads |
| /api/flash/boards | GET | Yes | List supported boards |
{
"device_id": "esp32_001",
"firmware_id": "firmware_001",
"firmware_version": "1.0.0",
"artifact_url": "https://example.com/firmware.bin",
"checksum": "sha256:abc123...",
"force": false
}{
"ok": true,
"job_id": "flash-001",
"status": "queued",
"device_id": "esp32_001",
"firmware_version": "1.0.0"
}curl -X POST https://auth.ferqon.dev/api/flash \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"device_id": "esp32_001",
"firmware_id": "firmware_001",
"firmware_version": "1.0.0"
}'limit — Maximum jobs (default: 50)device_id — Filter by device (optional){
"jobs": [
{
"job_id": "flash-001",
"device_id": "esp32_001",
"firmware_version": "1.0.0",
"status": "completed",
"created_at": "2026-04-15T12:00:00Z",
"completed_at": "2026-04-15T12:01:00Z",
"duration_seconds": 60
}
]
}{
"job_id": "flash-001",
"device_id": "esp32_001",
"firmware_version": "1.0.0",
"status": "flashing",
"progress_pct": 45,
"message": "Writing flash...",
"created_at": "2026-04-15T12:00:00Z",
"started_at": "2026-04-15T12:00:05Z"
}| Code | Description |
|---|---|
| Ferqon.E0010 | Firmware flashing failed |
| Ferqon.E0011 | Flash cooldown active |
| Ferqon.E0012 | Firmware unchanged — flash skipped |
| Ferqon.E0013 | Device is locked by another operation |
| Ferqon.E0041 | Device not found |
| Ferqon.E0042 | Device does not support this capability |