RaftCoreAPI

Built-in REST Endpoints — Raft Core

This page lists the REST API endpoints exposed by the core Raft framework (SysManager, NetworkManager, DeviceManager, etc.). For the endpoints exposed by the standard SysMods see SysMod REST Endpoints. The full alphabetical list is at Raft Full API List.

To register your own endpoints from a SysMod, see Adding REST API Endpoints.

URL	Verb	Description	e.g. req	e.g. resp
blerestart	GET	Restart BLE sub-system. This will take a few seconds to restart.	blerestart	{"req":"blerestart","rslt":"ok"}
bledisconnect	GET	Disconnect every connected BLE central, about 200 ms after replying (so the reply is sent first). A BLE client should send this when it finishes, as some hosts (e.g. Windows) keep the link up after the client has gone - see BLEManager. Can be sent over any channel, e.g. the serial console, to release a link held by another host.	bledisconnect	{"req":"bledisconnect","rslt":"ok"}
caps	GET	List device capabilities — the names of every registered REST API endpoint — so clients can feature-detect firmware support instead of probing endpoints (which wastes time and can spam retries/timeouts on firmware that lacks a command). The default form returns the full endpoint name list plus a capsVersion. The extended form caps/<name> returns the HTTP method and description (the same help text the serial console prints) for a single endpoint; an unknown feature returns rslt:fail with error:unknownFeature. Firmware that predates this endpoint returns failUnknownAPI, which clients treat as "capabilities unknown" and fall back to their own detection.	caps or caps/datetime	{"req":"caps","rslt":"ok","capsVersion":1,"caps":["reset","v","caps","sysmodinfo","datetime","devman","subscription","pubtopics", ...]} or {"req":"caps/datetime","rslt":"ok","capsVersion":1,"name":"datetime","method":"GET","desc":"Get or set the system UTC time..."}
clearsettings	GET	Clear nv (non-volatile) settings, see getsettings for more information.	clearsettings
datetime	GET	Get or set the system UTC time. Useful when NTP is unavailable (e.g. BLE-only connection). Time can be set using ISO 8601 format or Unix epoch seconds. The RaftJS library sends this automatically on connect.	datetime or datetime?UTC=2026-04-04T15:30:12Z or datetime?epoch=1775404212	{"req":"datetime","rslt":"ok","UTC":"2026-04-04T15:30:12Z","epoch":1775404212}
devman/busname	GET	Get the bus name from a bus number. Bus numbers start from 1 and match the numbering used in device data JSON/binary messages. Only buses with valid device interfaces are numbered.	devman/busname?busnum=1	{"req":"devman/busname?busnum=1","rslt":"ok","busName":"I2CA"} Errors: failInvalidBusNum, failBusNotFound
devman/cmdjson	GET	Send a JSON command to a device. The body parameter contains URL-encoded JSON and must include a device field. Used for devices that accept JSON commands like MotorControl. See MotorControl Commands for details.	devman/cmdjson?body={"device":"MotorControl","cmd":"motion","mode":"abs","pos":[100,50,25],"speed":75}	{"req":"devman/cmdjson?body={...}","rslt":"ok"} Returns: RAFT_OK, RAFT_BUSY, RAFT_INVALID_DATA, RAFT_INVALID_OPERATION, RAFT_CANNOT_START
devman/cmdraw	GET	Send a raw command to a device on a specific bus. The hexWr parameter contains hex-encoded bytes to write. The numToRd parameter specifies how many bytes to read back. Device can be identified by deviceid=<busNum>_<hexAddr> or by separate bus (can be name or number) and addr (plain hex, no 0x prefix) parameters.	devman/cmdraw?deviceid=1_6a&hexWr=0F&numToRd=1 or devman/cmdraw?bus=I2CA&addr=6a&hexWr=0F&numToRd=1	{"req":"devman/cmdraw?bus=I2CA&addr=6a&hexWr=0F&numToRd=1","rslt":"ok"}
devman/demo	GET	Start a demo device for testing. deviceTypeKey (or type) specifies the device type (default: "ACCDEMO"). Optional parameters include rate (sample rate in ms, default: 100), duration (duration in ms, default: 0 = infinite), offlineIntvS (interval between offline periods in seconds, default: 0 = no offline), and offlineDurS (duration of offline period in seconds, default: 10). Note: This endpoint is only available if DEVICE_MANAGER_ENABLE_DEMO_DEVICE is defined.	devman/demo?deviceTypeKey=ACCDEMO&rate=100&duration=60000&offlineIntvS=30&offlineDurS=5	{"req":"devman/demo?deviceTypeKey=ACCDEMO&rate=100&duration=60000&offlineIntvS=30&offlineDurS=5","rslt":"ok","demoStarted":true,"type":"ACCDEMO","rate":100,"duration":60000,"offlineIntvS":30,"offlineDurS":5} Errors: failDemoDeviceExists
devman/devconfig	GET	Configure polling parameters for a device. intervalUs (optional) sets the polling interval in microseconds. numSamples (optional) sets the number of buffered poll samples (changing this clears buffered data). busHz (optional) sets the I2C bus speed in Hz for this device's polls (0 = revert to default bus speed). busHzSlots (optional) comma-separated list of slot numbers to which busHz applies (omit to keep current mask; empty or 0 = all slots). save=1 keeps the device's settings over a restart (saved device settings). Returns the current pollIntervalUs, numSamples, busHz, and busHzSlots. Device can be identified by deviceid=<busNum>_<hexAddr> or by separate bus (can be name or number) and addr (plain hex, no 0x prefix) parameters.	devman/devconfig?deviceid=1_25&intervalUs=50000 or devman/devconfig?bus=I2CA&addr=25&intervalUs=50000&numSamples=5 or devman/devconfig?deviceid=1_6a&busHz=400000&busHzSlots=4,5,6	{"req":"devman/devconfig?bus=I2CA&addr=25&intervalUs=50000","rslt":"ok","deviceID":"1_25","pollIntervalUs":50000,"numSamples":5,"busHz":400000,"busHzSlots":[4,5,6]} Errors: failAddrMissing, failBusMissing, failBusNotFound, failInvalidDeviceID, failInvalidInterval, failInvalidNumSamples, failUnsupportedBus
devman/devdata	GET	Get status/data from a device. The name parameter specifies the device name. Returns device-specific data in JSON format.	devman/devdata?name=MotorControl	{"req":"devman/devdata?name=MotorControl","rslt":"ok","pos":[100.0,50.0,25.0],"steps":[10000,5000,2500],"busy":false,"paused":false}
devman/listdevs	GET	Enumerate currently-instantiated static devices and bus-detected devices. Optional role parameter filters by role (e.g. system, normal). Each entry includes the canonical deviceid, its displayName (the device name, or the type display name and device ID), optional name/role (when set / non-default), and dtIdx (device type index) when known. Undetected bus addresses are not reported.	devman/listdevs or devman/listdevs?role=system	{"req":"devman/listdevs","rslt":"ok","devices":[{"deviceid":"0_0","name":"MotorControl","displayName":"MotorControl","dtIdx":12},{"deviceid":"1_36","displayName":"Fuel Gauge 1_36","role":"system","dtIdx":7}]}
devman/typefile	GET	Device type file status: path, state, counts (added, replaced, disabled, rejected), first error, CRC16 (as filehash) and capacity. devman/typefile/check?file=<path> checks a file without changing anything; devman/typefile/apply?file=<path> checks it, installs it as the type file if nothing is rejected, and restarts; devman/typefile/apply restarts the device to apply a changed file. A check is done in the background with a deferred reply (a few seconds) - see Device Manager REST API. devlib returns the same status with the device library endpoint's fields	devman/typefile or devman/typefile/apply	{"req":"devman/typefile","file":"/local/devlib.json","state":"applied","present":true,"applied":true,"crc":"2c68","added":1,"replaced":1,...,"rslt":"ok"}
devman/reident	GET	Identify devices again - one (deviceid), a type (deviceTypeKey, deviceTypeIndex or type), all=1 or unidentified=1. An identified device keeps its type until a different one is found	devman/reident?deviceTypeKey=MPU6050	{"req":"devman/reident?deviceTypeKey=MPU6050","buses":2,"rslt":"ok"}
devman/typepolicy	GET	Set a device type's policy (enabled, disabled, disabledClaim) at runtime and identify the devices it affects again. save=1 also sets it in the device type file (applied by the next restart; restartRequired is reported)	devman/typepolicy?deviceTypeKey=APDS9960&policy=disabled	{"req":"devman/typepolicy?deviceTypeKey=APDS9960&policy=disabled","deviceTypeKey":"APDS9960","policy":"disabled","rslt":"ok"}
devman/types	GET	The device type table, a page at a time (offset, count default 50): index, key, source (base, override, extended) and policy, with total and generation	devman/types?offset=0&count=2	{"req":"devman/types?offset=0&count=2","total":53,"generation":1,"types":[{"dtIdx":0,"key":"RoboticalLightSensor","src":"base","policy":"enabled"},...],"rslt":"ok"}
devman/identinfo	GET	Identification state of a bus device (deviceid or bus+addr): state, attempts, time to the next attempt, type, whether it is polled, and the candidate types in the order they are tried	devman/identinfo?deviceid=1_68	{"req":"devman/identinfo?deviceid=1_68","deviceID":"1_68","ident":{"online":"online","state":"identified","attempts":0,"nextInMs":0,"dtIdx":52,"polled":true,"reverify":false,"reident":false,"candidates":[{"dtIdx":52,"key":"MPU6050"}],"hook":false},"rslt":"ok"}
devman/reinit	GET	Run a device's initialisation again without identifying it again; its devconfig settings are then applied again. The response is deferred until it is done where the connection supports it, otherwise queued	devman/reinit?deviceid=1_68	{"req":"devman/reinit?deviceid=1_68","rslt":"ok"} Errors: failDeviceNotOnline, failInit, failTimeout
devman/devenable	GET	Stop (poll=0) or resume (poll=1) polling a device, which stays identified; omit poll to query. Kept while the device is offline; save=1 keeps it over a restart	devman/devenable?deviceid=1_68&poll=0	{"req":"devman/devenable?deviceid=1_68&poll=0","deviceID":"1_68","poll":false,"online":true,"rslt":"ok"}
devman/reserved	GET	Addresses device type records identify devices at (re-addressable devices keep off them)	devman/reserved	{"req":"devman/reserved","addrs":["0x10","0x11","0x68"],"rslt":"ok"}
devman/busstatus	GET	Per-bus diagnostics: poll integrity, poll load, bus task activity, poll timing per device, identification timing and scan statistics. busnum for one bus, reset=1 to restart the poll timing statistics	devman/busstatus?busnum=1	{"req":"devman/busstatus","buses":{"I2CA":{"pollIntegrity":{...},"pollLoadPct":7,"activity":{...},"pollTiming":{...},"identTiming":[...],"scan":{...}}},"rslt":"ok"}
devman/setname	GET	Assign a friendly name to a device. The device is identified by canonical deviceid=<busNum>_<hexAddr> (use 0_<hexAddr> for statically-instantiated devices). name is required and must be non-empty. save=1 keeps it over a restart. Works for both static and bus-detected devices.	devman/setname?deviceid=1_6a&name=IMU1&save=1	{"req":"devman/setname?deviceid=1_6a&name=IMU1&save=1","rslt":"ok"} Errors: failDeviceIdMissing, failNameMissing, failInvalidDeviceId, failSave
devman/setrole	GET	Assign a role string to a device. The default role is normal; set role=system to tag devices (such as a fuel gauge) that should be treated as system devices rather than published measurement devices. Pass an empty role or normal to clear. save=1 keeps it over a restart.	devman/setrole?deviceid=1_36&role=system	{"req":"devman/setrole?deviceid=1_36&role=system","rslt":"ok"} Errors: failDeviceIdMissing, failInvalidDeviceId, failSave
devman/slot	GET	Set or query the operating mode of multiplexer/expander slots on a bus. bus is the bus name or number. To set a mode, supply slot (must be >0) and mode (e.g. i2c, serial-full, serial-half). To query all slots' modes on the bus, omit mode.	devman/slot?bus=I2CA&slot=4&mode=serial-half or devman/slot?bus=I2CA (query)	{"req":"devman/slot?bus=I2CA&slot=4&mode=serial-half","rslt":"ok","bus":"I2CA","slot":4,"mode":"serial-half"} Errors: failBusMissing, failBusNotFound, failSlotMissing, failInvalidSlot, failBusNoSlotControl, failSetMode
devman/typeinfo	GET	Two modes: (a) Type lookup — supply deviceTypeKey or deviceTypeIndex (or the older type, key or index) to get the device type record. (b) Per-device lookup — supply deviceid=<busNum>_<hexAddr> or bus+addr to get the type record for the device actually installed/detected at that address plus displayName and any sidecar fields (name, role) that have been assigned to it. The name field is omitted when no friendly name is set, and role is omitted when the role is normal. Both modes return deviceTypeKey, src and policy; full=1 adds the whole record in the device type file format as record.	devman/typeinfo?deviceTypeKey=LSM6DS3 or devman/typeinfo?deviceTypeIndex=5 or devman/typeinfo?deviceid=1_6a	{"req":"devman/typeinfo?deviceid=1_6a","rslt":"ok","devinfo":{"name":"LSM6DS3", ... },"dtIdx":5,"deviceTypeKey":"LSM6DS3","name":"IMU1","role":"system","displayName":"IMU1"}
espFwUpdate	POST	Start a firmware update of the main system firmware. Since this is a POSt command it operates normally over WiFi but must be used via RICREST for other comms channels.	espFwUpdate
filedelete/<fs>/<filename>	GET	Delete a file on a file system	filedelete/<fs>/<filename>	{"req":"filedelete/local/test.txt","rslt":"ok"}
filelist/<fs>	GET	Get a list of files on the file system. Two file systems are supported: local (stored in flash on the ESP32) and SD (if an external SD card is present). The first part of the path can specify a file system followed by ~. If no file system is specified the default one is used which is generally local.	filelist or filelist/local or filelist/sd	{"req":"filelist","rslt":"ok","fsName":"local","fsBase":"/local","diskSize":892556.00,"diskUsed":111946.00,"folder":"/local/","files":[{"name":"test.txt","size":317}, ... ]}
fileread/<fs>/<filename>	GET	Read the content of a text file and return as a string	fileread/local/<fileName> or fileread/sd/test.txt	… the text content of the file …
fileupload	POST	Upload a file to the file system using HTTP POST. This is only directly usable from a WiFi/Ethernet connection, other communication channels are supported using the RICREST protocol (ufStart etc. - see RICREST file transfers). The file is written on the file system worker and the reply is sent once it is written (FileWriteFailed if writing failed).	fileupload
friendlyname	GET	Get or set the friendly name. Set a blank name to clear. The name and friendlyNameIsSet are strored in non-volatile storage	friendlyname or friendlyname/My Device or friendlyname/	{"req":"friendlyname","friendlyName":"My Device","friendlyNameIsSet":1,"rslt":"ok"} or {"req":"friendlyname/My Device","friendlyName":"My Device","friendlyNameIsSet":1,"rslt":"ok"} or {"req":"friendlyname/","friendlyName":"SystemName","friendlyNameIsSet":0,"rslt":"ok"}
getsettings/<filter>	GET	Get SysType settings. These are the overall JSON configuration for the active SysType. There are two sections to the SysType settings, base settings are those defined in the SysType defined when the firmware was built and are immutable, nv settings are overrides to the base settings which are stored in non-volatile storage and are user-modifiable (see postsettings below). The option allows section of base, nv or all settings	getsettings or getsettings/nv	{"req":"getsettings","sysType":"MySysType","nv":{},"base":{"SysType":"MySysType","CmdsAtStart":"","WebUI":"","SysManager":{"monitorPeriodMs":10000,"reportList":["NetMan","BLEMan","SysMan"],...
hwrevno	GET	Get hardware revision and SysTypeVersion The hardware revision may be any string. Once set the hardware revision is stored in non-volatile storage The SysTypeVers is a string which is used to determine which version of a SysType is used (this is applicable to versioned SysTypes only)	hwrevno	{"req":"hwrevno","SysTypeVers":"","HwRev":"","rslt":"ok"}
led/<elem>/<cmd>/<data>?<args>	GET	Control LED pixels via LEDPixelsDevice. <elem> is segment name or index (e.g. ring, 0). Commands include setall, setled, setleds, off, pattern, listpatterns.	led/ring/setall/FF0000 or led/ring/pattern/RainbowSnake?speed=1000&brightness=50	{"req":"led/ring/setall/FF0000","rslt":"ok"}
postsettings	POST	Set SysType nv (non-volatile) settings, see getsettings for explanation of SysType settings. This POST operation will only work natively over HTTP - see RICREST for use over other comms channels.	postsettings	The JSON object has the same format as the SysType settings returned by the getsettings/base command. Override occurs JSON tag by JSON tag, so if an array is specified at exactly the same point in the nv section then it will override an array of the same name and position in the base settings.
reformatfs	GET	Re-format the file system (either local or sd). This can be forced (even if the fs is not corrupt) using the reformatfs/force option. Note that the system will restart if a re-format is successful.	reformatfs/local	{"req":"reformatfs/local","rslt":"ok"}
reset	GET	Schedule a reset in around 1 second.	reset	{"req":"reset","rslt":"ok"}
serialno	GET	Set / get system serial number. Serial number is a 16 byte value (sent/received hex formatted).	serialno or serialno/01234567890ABCDEF0123456789ABCDEF	{"req":"serialno","SerialNo":"0123456789abcdef0123456789abcdef","rslt":"ok"} or {"req":"serialno/0123456789ABCDEF0123456789ABCDEF","SerialNo":"01234567890abcdef0123456789abcde","rslt":"ok"}
subscription	GET	Setup subscriptions to published information. Single topic format: topic (or name) is the topic name, rateHz specifies publish rate in Hz (0 to disable), minMs sets minimum interval between messages in milliseconds (default: varies), and trigger sets the trigger type (change, time, timeorchange - default: timeorchange). Multiple topics format: Use pubRecs array with objects containing name (or topic), rateHz, minMs, and trigger fields. Note that subscriptions are specific to a communication channel and all interfaces now require explicit subscription (including BLE and serial interfaces).	Single topic: subscription?action=update&topic=MyPublishedData&rateHz=10.0&trigger=timeorchange&minMs=100 Multiple topics (JSON format): {"cmdName":"subscription","action":"update","pubRecs":[{"name":"Topic1","rateHz":10.0,"trigger":"timeorchange"},{"name":"Topic2","rateHz":0}]}	{'req': 'subscription', 'rslt': 'ok'}
sysmoddebug/<SysMod>	GET	Get debug information from a SysMod. sysmoddebug/SysMan gives the main loop timing stats plus slow: slow SysMod loops since startup (n, longest maxMs and the SysMod maxMod) and slow file system writes (fsSlowWrites, total fsSlowWriteMs) - see SysManager. sysmoddebug/RestAPI gives the deferred response counters.	sysmoddebug/NetMan or sysmoddebug/RestAPI	{"req":"sysmoddebug/RobotCtrl","debugStr":"... debug info ..."}
sysmodinfo/<SysMod>	GET	Get information on a SysMod (system module). SysMod names are case-sensitive. Examples of SysMod names are NetMan, BLEMan, SysMan.	sysmodinfo/NetMan	{“rslt”:”ok”,"isConn":1,"connState":"WiFiAndIP","SSID":"myssid","IP":"192.168.1.12","Hostname":""}
v	GET	Get the system name and version of RIC	v	{"req":"v","rslt":"ok","SystemName":"Cog","SystemVersion":"1.3.0","Friendly":"","SerialNo":"","MAC":"b0818422894a","SysTypeVers":"","HwRev":""}
w/<ssid>/<password>	GET	Specify WiFi Station (client) credentials. WiFi SSID is limited to 31 (not 32) chars. Password is limited to 63 (not 64) chars. Valid SSID chars include: ~!@#$^*()-={}[:;<>?,.Aa1 %&_/<br> And valid Password chars include:~!@#$^*()-={}[:;<>?,.A1 %&_]+"\/ HTTP encoded chars are valid - e.g. backslash %2F forward-slash %5C.	w/myssid/mypassword	{"req":"w/myssid/mypassword","rslt":"ok"}
wap/<ssid>/<password>	GET	Specify WiFi Access Point credentials. WiFi SSID is limited to 31 (not 32) chars. Password is limited to 63 (not 64) chars. Valid SSID chars include: ~!@#$^*()-={}[:;<>?,.Aa1 %&_/<br> And valid Password chars include:~!@#$^*()-={}[:;<>?,.A1 %&_]+"\/ HTTP encoded chars are valid - e.g. backslash %2F forward-slash %5C.	wap/myssid/mypassword	{"req":"wap/myssid/mypassword","rslt":"ok"}
wc/<norestart>	GET	Clear WiFi credentials and disconnect WiFi. norestart option suppresses restart	wc or wc/norestart	{"req":"wc","rslt":"ok"} or {"req":"wc/norestart","rslt":"ok"}
wifipause/<op>	GET	Pause/resume WiFi operation	wifipause/pause or wifipause/resume	{"req":"wifipause/pause","rslt":"ok"} or {"req":"wifipause/resume","rslt":"ok"}
wifiscan/<op>	GET	Scan for WiFi Access Points. Two operations are supported: start starts a new scan and results returns the scan status along with the cached results of the last completed scan. After starting a scan, poll results until scan.state is done (or failed). While a scan is running results returns "rslt":"ok" with scan.state of scanning (and the results of the previous scan, if any) - it does not fail. start only fails if the scan could not be started (the reason is in scan.err); a start while a scan is already running (or within 1 second of a scan completing) is not an error and does not start a new scan. Older firmware (RaftCore 1.54.1 and earlier) has no scan object: results returns "rslt":"fail" while the scan is in progress and the results can only be read once per scan. See NetworkManager wifiscan for full details of the response fields and client polling guidance.	wifiscan/start or wifiscan/results	{"req":"wifiscan/start","scan":{"state":"scanning","id":1,"elapsedMs":0},"rslt":"ok"} or (scan in progress) {"req":"wifiscan/results","scan":{"state":"scanning","id":1,"elapsedMs":850},"wifi":[],"rslt":"ok"} or (scan complete) {"req":"wifiscan/results","scan":{"state":"done","id":1,"durMs":2410,"ageMs":120,"count":1,"found":1,"new":0,"lost":0},"wifi":[{"ssid":"rd01","rssi":-66,"ch1":6,"ch2":0,"auth":"WPA2_PSK","bssid":"aa:aa:9a:17:89:bb","pair":"CCMP","group":"CCMP","new":0},...],"rslt":"ok"}
wifidiag	GET	WiFi link diagnostics (signal, access point, power save, TX power, connection counts, gateway ping, recovery and heap). Parameters set link options first: ps, txPwr, proto, bw, pingMs, pingRecover, logS, bssid (lock to one access point, or any) and reconnect. (RaftCore versions after 1.58.1) See NetworkManager wifidiag for the options, response fields and link recovery.	wifidiag or wifidiag?txPwr=15	{"req":"/wifidiag","diag":{"link":1,"rssi":-77,"ch":11,"bssid":"fc:ec:da:11:eb:3b",...,"ping":{...},"recov":{...},"heap":{...}},"rslt":"ok"}