Reference Websocket Api

Websocket API

The integration registers these Home Assistant websocket commands. They are what the card and the editor use, and you can use them from scripts or from the developer tools of your browser. Commands marked admin are refused for non-admin users.

Every command follows the usual websocket convention: send {"id": <n>, "type": "...", ...}, receive {"id": <n>, "type": "result", "success": true, "result": ...} or "success": false with an error object.

plan/get

Returns the stored plan; {} before the first save. Not restricted to admins.

{"id": 1, "type": "fns_floorplan/plan/get"}

{"id": 1, "type": "result", "success": true, "result": {"rev": 7, "rooms": [], "levels": []}}

plan/subscribe

Sends the plan immediately and again after every save. This is how open cards redraw by themselves.

{"id": 2, "type": "fns_floorplan/plan/subscribe"}

{"id": 2, "type": "result", "success": true, "result": null}
{"id": 2, "type": "event", "event": {"rev": 7, "rooms": []}}

plan/save

Admin. Replaces the whole plan. Always read the current plan first and send it back with your changes.

{"id": 3, "type": "fns_floorplan/plan/save", "plan": {"rooms": [], "levels": []}, "rev": 7}

{"id": 3, "type": "result", "success": true, "result": {"ok": true, "rev": 8}}

Revisions and conflicts

Every save stores the plan with rev increased by one. When the request contains rev, the save only succeeds if it equals the stored revision. Otherwise you get an error and nothing is written:

{"id": 3, "type": "result", "success": false,
 "error": {"code": "conflict", "message": "The plan changed meanwhile (revision 8)"}}

Without rev the save always overwrites (useful for imports). The previous plan is pushed to the history first, when it contained rooms. If the integration is not set up, the error code is not_loaded.

history/list

Admin. Lists the last 20 saved revisions, newest first.

{"id": 4, "type": "fns_floorplan/history/list"}

{"id": 4, "type": "result", "success": true, "result": [
  {"rev": 7, "saved_at": "2026-10-04T12:00:00+00:00", "rooms": 3, "items": 12}
]}

items counts furniture, devices, sensors and texts.

history/get

Admin. Returns one stored plan by its revision, or the error not_found.

{"id": 5, "type": "fns_floorplan/history/get", "rev": 7}

yaml/parse

Admin. Parses YAML text with Home Assistant's own loader. An error has the code invalid_yaml.

{"id": 6, "type": "fns_floorplan/yaml/parse", "text": "- if:\n    - entity: light.x\n      state: 'on'\n  color: red"}

{"id": 6, "type": "result", "success": true, "result": {"data": [{"if": [{"entity": "light.x", "state": "on"}], "color": "red"}]}}

yaml/dump

Admin. The opposite: data (a list or an object) to YAML text.

{"id": 7, "type": "fns_floorplan/yaml/dump", "data": [{"color": "red"}]}

{"id": 7, "type": "result", "success": true, "result": {"text": "- color: red\n"}}

Tracing images (HTTP)

Floor tracing images are not uploaded over the websocket but through an HTTP endpoint of the integration. It needs an admin user's access token.

Method	URL	Body	Result
POST	/api/fns_floorplan/background	multipart form: level (floor id), file (png, jpg, jpeg, webp or svg, at most 15 MB)	{"url": "/local/fns_floorplan/bg_<level>.<ext>?v=<timestamp>"}
DELETE	/api/fns_floorplan/background?level=<id>	none	{"ok": true}

The file is stored in www/fns_floorplan/bg_<level>.<ext> (a new upload replaces the old one of that floor). Errors: 403 for non-admins, 400 for an unsupported type, 413 for a file that is too large. The returned url goes into backgrounds[level].url of the plan, which is then saved with plan/save.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -F level=0 -F file=@floor.png \
  http://homeassistant.local:8123/api/fns_floorplan/background

See also the Plan format.