Explore FritzBox /api/v0/ REST API for richer data access

[itsDNNS]

Context

DOCSight currently uses the data.lua endpoint for all FritzBox communication (DOCSIS channels, device info, connection info). While functional, this approach has limitations:

• data.lua responses mix HTML and JSON depending on firmware version and page
• Some data (e.g. segment utilization) is only available via the newer /api/v0/ REST API
• The REST API likely exposes additional data that data.lua does not

Discovery

While investigating cable segment utilization (#182), we found the FritzBox serves a proper REST API:

Endpoint	Purpose
/api/v0/generic/box	Box info
/api/v0/generic/connections	Connection details
/api/v0/generic/time	Time reference
/api/v0/monitor/segment/subsets	Segment utilization datasets
/api/v0/monitor/segment/{0-4}	Individual segment series (DS/US total + own share)

The cable utilization page (#/cable/utilization) uses this API to display network-wide segment load as 0-100% over configurable timeranges (1h to 1y).

Problem

The /api/v0/ endpoints return permission denied (code 3001) when called with the standard SID authentication used by data.lua. The FritzBox SPA successfully loads these endpoints during page navigation, so there is a working auth mechanism - it just needs to be identified.

Goals

1. Reverse-engineer /api/v0/ authentication by analyzing the FritzBox frontend JS (specifically /js3/views/internet/wan/utilization.html and related modules)
2. Document all available /api/v0/ endpoints - map out what data is accessible
3. Evaluate migration path - identify which current data.lua calls could be replaced with cleaner REST API equivalents
4. Enable segment utilization feature - this is the immediate use case, tracked separately

Why This Matters

• Cleaner, more reliable data access (structured JSON vs HTML/JSON mix)
• Access to data not available through data.lua (segment utilization, spectrum, etc.)
• Better foundation for future FritzBox features
• Reduces workarounds for firmware-specific data.lua quirks (see fix: add TR-064 fallback for FritzBox device info #181, fix: prefer stable FritzBox device info pages #183)

Research notes

See docs/plans/2026-03-09-segment-utilization-research.md for detailed findings.

[itsDNNS]

Research findings

I did a deeper pass over the public FRITZ!Box REST API surface and related firmware metadata. This comment focuses only on repo-safe findings and implementation-relevant conclusions.

1. Authentication: most likely root cause of 3001 permission denied

The strongest current hypothesis is that /api/v0/* does not use a different login handshake than data.lua, but it does expect the session to be presented differently.

Public AVM REST API material shows a pattern where the FRITZ!Box Session-ID is sent via the HTTP header:

Authorization: AVM-SID <SID>

instead of as a classic sid query/form parameter.

That means the likely call pattern for /api/v0/* is:

GET /api/v0/generic/box HTTP/1.1
Accept: application/json
Authorization: AVM-SID <SID>

This fits the observed symptom very well:

• login_sid.lua succeeds
• data.lua works with classic sid
• /api/v0/* returns 3001 permission denied

So the current best assumption is:

• keep using the normal login_sid.lua challenge-response flow to obtain a valid SID
• call /api/v0/* with Authorization: AVM-SID <SID>

A second factor is likely user rights. Public AVM and BoxMatrix material both indicate that REST endpoints are rights-gated, so a valid SID may still fail if the account lacks the required permissions.

2. /api/v0/ is a broader internal FRITZ!OS REST layer

Public BoxMatrix material describes /api/v0/ as an internal FRITZ!OS REST API backed by /usr/rest_api, including:

• a generic layer (api_generic.lua)
• endpoint security/rights mapping (security.lua)
• plugin-style endpoint groups such as monitor-related routes

That is important because it suggests the segment endpoints are not a one-off hidden interface, but part of a broader API surface used by the FRITZ!Box UI itself.

3. Endpoint mapping

The currently known endpoints fit that structure well:

• /api/v0/generic/box
• /api/v0/generic/connections
• /api/v0/generic/time
• /api/v0/monitor/segment/subsets
• /api/v0/monitor/segment/{0-4}

generic/*

Public examples and BoxMatrix documentation indicate that the generic API exposes structured device/UI data via stable JSON endpoints.

This makes these mappings very plausible:

• generic/box -> box/device metadata
• generic/connections -> active internet connection metadata
• generic/time -> system/reference time data

monitor/*

Public documentation for monitor-related REST handlers shows that /api/v0/monitor/* already exists as a family of time-series and monitoring endpoints.

That makes the discovered segment routes highly plausible as part of the same monitoring subsystem.

4. Segment utilization appears to be cable-specific capability

Public firmware metadata strongly suggests that segment utilization is backed by a dedicated cable statistics subsystem.

Notable published artifacts include references such as:

• cable_segment_stats
• cable_segment_stats.service
• libavm_cable_seg_stats_api.so

Inference:

• segment utilization should be treated as capability-gated
• availability is likely limited to specific cable models and FRITZ!OS versions
• this should not be assumed to exist on DSL/fiber boxes or even all cable firmware revisions

5. Migration assessment

Based on the public endpoint naming and available documentation, these look like the best migration candidates from legacy data.lua access to /api/v0/:

1. Device info
   Likely replacement: /api/v0/generic/box

2. Connection info
   Likely replacement: /api/v0/generic/connections

3. Time/reference metadata
   Likely addition: /api/v0/generic/time

4. Segment utilization
   Target endpoints:

   • /api/v0/monitor/segment/subsets
   • /api/v0/monitor/segment/{0-4}

One thing that is still not proven from public sources is a REST replacement for the current DOCSIS channel table data obtained via legacy endpoints. So a full migration away from data.lua should probably stay incremental.

6. Recommended next step

The cleanest next experiment is:

1. authenticate normally via login_sid.lua
2. call /api/v0/generic/box with Authorization: AVM-SID <SID>
3. if that works, test /api/v0/generic/connections
4. then test /api/v0/monitor/segment/subsets
5. treat 404 / 3001 as capability or rights failures and keep legacy fallback where appropriate

7. Working conclusion

Current conclusion from public research:

• there is no strong evidence yet for a separate hidden auth handshake for /api/v0/*
• there is strong evidence that the existing FRITZ!Box SID likely needs to be sent as Authorization: AVM-SID <SID>
• endpoint rights and model/firmware capability likely determine the remaining access behavior
• /api/v0/monitor/segment/* looks like the right path for implementing segment utilization support

Public sources

• AVM REST API spec: https://fritz.support/resources/SmarthomeRestApiFRITZOS82.yaml
• BoxMatrix REST API overview: https://boxmatrix.info/wiki/RESTAPI-Scripts
• BoxMatrix generic REST layer: https://boxmatrix.info/wiki/api_generic.lua
• BoxMatrix REST security mapping: https://boxmatrix.info/wiki/Property%3Asecurity.lua_%28restapi%29
• BoxMatrix monitor handler: https://boxmatrix.info/wiki/monitor.lua
• BoxMatrix cable segment stats daemon: https://boxmatrix.info/wiki/cable_segment_stats
• BoxMatrix cable segment stats library: https://boxmatrix.info/wiki/libavm_cable_seg_stats_api.so

[neofabrics]

Hi @itsDNNS, not going to open a new issue but it looks like the GET /api/v0/* endpoints are not available on my (Vodafone branded) FRITZ!Box 6591 (with FRITZ!OS: 8.03).

DOCSight log:

docsight  | 2026-03-10 16:15:29,405 [DEBUG] urllib3.connectionpool: Starting new HTTP connection (1): 192.168.178.1:80
docsight  | 2026-03-10 16:15:29,433 [DEBUG] urllib3.connectionpool: http://192.168.178.1:80 "GET /api/v0/monitor/segment/0 HTTP/1.1" 400 None
docsight  | 2026-03-10 16:15:29,434 [WARNING] docsis.collector: segment_utilization: Failure #2 recorded, next attempt in 360s (effective interval: 60s)
docsight  | 2026-03-10 16:15:29,435 [WARNING] docsis.main: segment_utilization: API request failed: 400 Client Error: Bad Request for url: http://192.168.178.1/api/v0/monitor/segment/0

Manual cURL commands confirm that the API Endpoint does not exist on this model/firmware version:

curl -v -H "Authorization: AVM-SID [redacted]" http://192.168.178.1/api/v0/monitor/segment/0
*   Trying 192.168.178.1:80...
* Connected to 192.168.178.1 (192.168.178.1) port 80
> GET /api/v0/monitor/segment/0 HTTP/1.1
> Host: 192.168.178.1
> User-Agent: curl/8.7.1
> Accept: */*
> Authorization: AVM-SID [redacted]
>
* Request completely sent off
< HTTP/1.1 400 Bad Request
[snip]
<
* Closing connection
{"errors":[{"message":"bad path: \/segment\/0.","code":3002}]}

curl -H "Authorization: AVM-SID [redacted]" http://192.168.178.1/api/v0/generic/connections
{"errors":[{"message":"bad path","code":3002}]}

curl -H "Authorization: AVM-SID [redacted]" http://192.168.178.1/api/v0/monitor/segment/subnets
{"errors":[{"message":"bad path: \/segment\/subnets.","code":3002}]}

Is there anything that needs to be enabled in FRITZ!OS? Or maybe the OS is too old?

[itsDNNS]

Based on the official AVM release notes, this looks much more like a firmware capability gap than a setting that can be enabled manually.

What I could confirm:

• On FRITZ!Box 6591 Cable, the online monitor feature "Display of the utilization of the network segment where own subscriber connection is located" first appears in the FRITZ!OS 8.20 release notes.
• In the FRITZ!OS 8.03 section for the 6591, there is nothing about segment utilization or the newer online monitor.
• On FRITZ!Box 6690 Cable, the same segment utilization feature is listed in the FRITZ!OS 8.21 release notes.
• AVM also explicitly notes in the 6591 release notes that for cable-provider devices, updates are installed by the cable provider.

So for a Vodafone-branded 6591 on FRITZ!OS 8.03, your 3002 bad path result is consistent with the endpoint simply not being present yet.

On the Vodafone side, I also found recent community evidence that the rollout is still uneven:

• In a Vodafone Community thread from December 3, 2025, a user with a Vodafone 6591 was still on 8.03.
• In the same discussion, a Vodafone moderator wrote on February 7, 2026 that the rollout to 8.21 was still ongoing and that not all devices are updated at the same time.

So I do not think there is anything you can enable locally on 8.03. The more realistic conclusion is:

• FRITZ!OS 8.03 is too old for this feature on the 6591
• provider-managed firmware rollout is the gating factor for Vodafone rental devices
• DOCSight should treat segment utilization as capability-gated and stop polling once the box returns a clear "bad path" response

Sources:

• AVM 6591 release notes: https://download.avm.de/fritzbox/fritzbox-6591-cable/other/fritz.os/info_de.txt
• AVM 6690 release notes: https://download.avm.de/fritzbox/fritzbox-6690-cable/other/fritz.os/info_de.txt
• Vodafone Community thread: https://forum.vodafone.de/t5/Ger%C3%A4te/FRITZ-OS-Update-6591-Cable/td-p/3305881
• Vodafone Community thread: https://forum.vodafone.de/t5/Ger%C3%A4te/FRITZ-OS-Update-Ihrer-FRITZ-Box-6591-Cable-Vodafone-nicht/td-p/3303937

[itsDNNS]

One practical workaround is available in the latest main build now:

DOCSight has a real Segment Utilization toggle under Settings -> Modem.

So if your FRITZ!Box firmware does not support the segment API yet, you can simply disable it there for now. That stops the collector and removes the Segment Utilization entry from the UI until your provider rolls out a newer FRITZ!OS version.

[neofabrics]

Thank you. Disabled the collector for now and going to wait for Vodafone to fully release the new FRITZ!OS version 👍

Thanks for the screenshot too, gives me an idea already on how to implement it in DOCSIOS 😁