API Reference

API Reference

DOCSight exposes a REST-style API for the web UI, external clients, and automation.

Most endpoints live under /api/* and return JSON. A few endpoints return binary data such as PNG images, PDF reports, or backup archives.

Authentication

When an admin password is set, almost all API endpoints require authentication.

Two auth modes are supported:

• Session auth via /login for browser clients
• Bearer token auth via Authorization: Bearer dsk_... for programmatic access

Token management endpoints are session-only and cannot be called with a bearer token:

• POST /api/tokens
• DELETE /api/tokens/<id>

Exceptions

• GET /health does not require auth
• /api/restore/validate and /api/restore can be used without auth during initial setup before the instance is configured

Timestamps

• Timestamp fields use UTC ISO format with Z suffix, for example 2026-03-10T14:30:00Z
• Date-only fields use YYYY-MM-DD
• Some endpoints localize timestamps for browser consumption, so clients should not assume every response is raw UTC storage output

Response Format

There is no single universal envelope for all endpoints.

Current patterns include:

• raw objects, for example /api/device
• raw arrays, for example /api/trends
• success/error JSON objects, for example /api/config
• binary responses, for example /api/report, /api/bqm/image/<date>, /api/backup

Always inspect the endpoint-specific response shape below.

Health and Status

Method	Path	Auth	Description
GET	/health	No	Basic health check with app status, DOCSIS health, and version
GET	/metrics	No	Prometheus metrics
GET	/api/device	Yes	Detected modem/router information
GET	/api/connection	Yes	ISP name, connection type, and detected provisioned speeds
GET	/api/collectors/status	Yes	Collector health, failure counts, and next poll timing

Configuration and Admin

Method	Path	Auth	Description
POST	/api/config	Yes	Save configuration values
POST	/api/test-modem	Yes	Test modem connection with submitted credentials
POST	/api/test-fritz	Yes	Deprecated alias for /api/test-modem
POST	/api/test-mqtt	Yes	Test MQTT broker connection
POST	/api/notifications/test	Yes	Send a test notification to configured channels
POST	/api/demo/migrate	Yes	Convert a demo instance to live mode while keeping user data

Core Data and Analysis

Method	Path	Auth	Description
POST	/api/poll	Yes	Trigger an immediate modem poll
GET	/api/snapshots	Yes	List available snapshot timestamps
GET	/api/snapshots/<timestamp>	Yes	Full stored snapshot payload
GET	/api/trends?range=day|week|month&date=YYYY-MM-DD	Yes	Trend data for rolling or anchored day/week/month views
GET	/api/channels	Yes	Current downstream/upstream channels plus aggregated summary
GET	/api/thresholds	Yes	Active threshold profile used for analysis
GET	/api/gaming-score	Yes	Gaming Quality Index score, grade, components, and genre suitability
GET	/api/channel-history?channel_id=<id>&direction=ds|us&days=7	Yes	Time series for a single channel
GET	/api/channel-compare?channels=1,2,3&direction=ds|us&days=7	Yes	Overlay history for up to 6 channels
GET	/api/correlation?hours=24&sources=modem,speedtest,events,bnetz	Yes	Unified cross-source correlation timeline
GET	/api/export?mode=full|update	Yes	LLM-oriented markdown export of current state and context

Before/After Comparison

Method	Path	Auth	Description
GET	/api/comparison?from_a=...&to_a=...&from_b=...&to_b=...	Yes	Compare two explicit time windows with period summaries, deltas, health distribution, and time series

Comparison Response

Returns an object with:

• period_a
• period_b
• delta

Each period includes:

• from
• to
• snapshots
• avg
• total
• health_distribution
• timeseries

Modulation Performance

Method	Path	Auth	Description
GET	/api/modulation/distribution?direction=us|ds&days=7	Yes	Distribution and health trend by modulation/protocol group
GET	/api/modulation/intraday?direction=us|ds&date=YYYY-MM-DD	Yes	Intraday per-channel modulation timeline
GET	/api/modulation/trend?direction=us|ds&days=7	Yes	Legacy modulation trend endpoint

Events

Method	Path	Auth	Description
GET	/api/events?page=1&per_page=50	Yes	Paginated event list
GET	/api/events/count	Yes	Count of unacknowledged events
POST	/api/events/<id>/acknowledge	Yes	Acknowledge a single event
POST	/api/events/acknowledge-all	Yes	Acknowledge all events

Speedtest

Method	Path	Auth	Description
GET	/api/speedtest	Yes	List speedtest results with quality classification
GET	/api/speedtest/<id>	Yes	Detail view for one result
GET	/api/speedtest/<id>/signal	Yes	Closest modem snapshot for a result

Journal and Incidents

Journal Entries

Method	Path	Auth	Description
GET	/api/journal?limit=1000&search=...&incident_id=N	Yes	List journal entries
POST	/api/journal	Yes	Create a journal entry
GET	/api/journal/<id>	Yes	Get a single entry with attachments
PUT	/api/journal/<id>	Yes	Update an entry
DELETE	/api/journal/<id>	Yes	Delete an entry
POST	/api/journal/<id>/attachments	Yes	Upload an attachment
GET	/api/attachments/<id>	Yes	Download an attachment
DELETE	/api/attachments/<id>	Yes	Delete an attachment
GET	/api/journal/export?format=csv|json|markdown	Yes	Export journal entries

Journal Import and Bulk Actions

Method	Path	Auth	Description
POST	/api/journal/import/preview	Yes	Upload Excel/CSV and preview parsed rows
POST	/api/journal/import/confirm	Yes	Confirm import of selected rows
DELETE	/api/journal/batch	Yes	Batch delete journal entries
POST	/api/journal/unassign	Yes	Remove incident assignments from entries

Incident Containers

Method	Path	Auth	Description
GET	/api/incidents?status=open	Yes	List incidents
POST	/api/incidents	Yes	Create an incident
GET	/api/incidents/<id>	Yes	Get a single incident
PUT	/api/incidents/<id>	Yes	Update an incident
DELETE	/api/incidents/<id>	Yes	Delete an incident
POST	/api/incidents/<id>/assign	Yes	Assign journal entries to an incident
GET	/api/incidents/<id>/timeline	Yes	Combined incident timeline including journal, correlation, and BNetzA data
GET	/api/incidents/<id>/report	Yes	Generate an incident-specific PDF report

Reports and Complaint Generation

Method	Path	Auth	Description
GET	/api/report?days=7	Yes	Generate a PDF report for the selected rolling period
GET	/api/complaint?days=7	Yes	Generate ISP complaint letter text

Comparison-Aware Report Parameters

Both /api/report and /api/complaint can include active before/after comparison data with:

• comparison_from_a
• comparison_to_a
• comparison_from_b
• comparison_to_b

Complaint Parameters

Parameter	Type	Description
days	int	Report period, clamped to 1-90
lang	string	Language code
name	string	Customer name
number	string	Customer or contract number
address	string	Customer address
include_bnetz	boolean	Include the most relevant BNetzA campaign from the period
bnetz_id	int	Force a specific BNetzA campaign

/api/complaint returns JSON with at least:

• text
• lang

BNetzA Measurements

Method	Path	Auth	Description
POST	/api/bnetz/upload	Yes	Upload a BNetzA PDF
GET	/api/bnetz/measurements	Yes	List uploaded campaigns and parsed results
GET	/api/bnetz/pdf/<id>	Yes	Download the original uploaded PDF
DELETE	/api/bnetz/<id>	Yes	Delete a measurement campaign

BQM Integration

Method	Path	Auth	Description
GET	/api/bqm/dates	Yes	List dates with archived BQM graphs
GET	/api/bqm/image/<date>	Yes	Return archived BQM image as PNG
GET	/api/bqm/live	Yes	Return live or cached BQM PNG with source headers
POST	/api/bqm/import	Yes	Bulk-import BQM images
DELETE	/api/bqm/images	Yes	Delete one, many, or all BQM images

BQM Delete Modes

DELETE /api/bqm/images accepts one of:

• {"date": "YYYY-MM-DD"}
• {"start": "YYYY-MM-DD", "end": "YYYY-MM-DD"}
• {"all": true, "confirm": "DELETE_ALL"}

Smokeping

Method	Path	Auth	Description
GET	/api/smokeping/targets	Yes	List configured Smokeping targets
GET	/api/smokeping/graph/<target>/<timespan>	Yes	Proxy Smokeping graph as PNG

Weather

Method	Path	Auth	Description
GET	/api/weather?count=2000	Yes	Weather history, newest first
GET	/api/weather/current	Yes	Latest weather reading
GET	/api/weather/range?start=...&end=...	Yes	Weather data for a time range

FRITZ!Box Segment Utilization

Method	Path	Auth	Description
GET	/api/fritzbox/segment-utilization?range=24h|7d|30d|all	Yes	Stored FRITZ!Box cable segment utilization samples, latest value, and stats
GET	/api/fritzbox/segment-utilization/range?start=...&end=...	Yes	Segment utilization data for a custom time window

These endpoints are only meaningful for FRITZ!Box cable devices.

Modules and Themes

Method	Path	Auth	Description
GET	/api/modules	Yes	List discovered modules and status
POST	/api/modules/<module_id>/enable	Yes	Enable a module, restart required
POST	/api/modules/<module_id>/disable	Yes	Disable a module, restart required
GET	/api/themes	Yes	List installed theme modules including theme data
GET	/api/themes/registry	Yes	List available remote themes not yet installed
POST	/api/themes/install	Yes	Install a theme from the registry

Backup and Restore

Method	Path	Auth	Description
POST	/api/backup	Yes	Create and download a .tar.gz backup
POST	/api/backup/scheduled	Yes	Create a backup in the configured backup directory
GET	/api/backup/list	Yes	List stored backups
DELETE	/api/backup/<filename>	Yes	Delete a backup file
POST	/api/restore/validate	Setup exception	Validate a backup archive before restore
POST	/api/restore	Setup exception	Restore a backup archive
GET	/api/browse?path=/backup	Yes	Browse server-side directories for backup path selection

Connection Monitor

Method	Path	Auth	Description
GET	/api/connection-monitor/targets	Yes	List all configured targets
POST	/api/connection-monitor/targets	Yes	Create a target (label required, host optional)
PUT	/api/connection-monitor/targets/<id>	Yes	Update target fields (auto-enables when host is set)
DELETE	/api/connection-monitor/targets/<id>	Yes	Delete a target and its samples
GET	/api/connection-monitor/samples/<id>	Yes	Get samples with envelope format (start, end, limit, resolution params)
GET	/api/connection-monitor/stats	Yes	Per-target range statistics (start, end params) with avg/min/max/P95 latency, packet loss, and sample count
GET	/api/connection-monitor/summary	Yes	Summary stats (avg latency, packet loss) for all targets
GET	/api/connection-monitor/outages/<id>	Yes	Derived outages from consecutive timeouts (start, end, threshold params)
GET	/api/connection-monitor/export/<id>	Yes	CSV export (start, end, resolution params)
GET	/api/connection-monitor/capability	Yes	Current probe method (icmp or tcp) and reason
GET	/api/connection-monitor/pinned-days	Yes	List all pinned days with UTC epoch ranges
POST	/api/connection-monitor/pinned-days	Yes	Pin a day (date or timestamp, optional label)
DELETE	/api/connection-monitor/pinned-days/<date>	Yes	Unpin a day by date

Samples Response

GET /api/connection-monitor/samples/<id> returns an envelope:

{
  "meta": {
    "resolution": "raw",
    "bucket_seconds": null,
    "blended": false
  },
  "samples": [...]
}

The resolution parameter accepts auto (default), raw, 1min, 5min, or 1hr. With auto, the backend selects the best resolution for the requested time range. When limit=0, all matching samples are returned.

Raw samples include latency_ms, timeout, and probe_method. Aggregated samples include avg_latency_ms, min_latency_ms, max_latency_ms, p95_latency_ms, packet_loss_pct, and sample_count.

Export Columns

CSV columns depend on the resolution:

Resolution	Columns
raw	datetime, latency_ms, timeout, probe_method
1min, 5min, 1hr	datetime, avg_latency_ms, min_latency_ms, max_latency_ms, p95_latency_ms, packet_loss_pct, sample_count

Smart Capture

Method	Path	Auth	Description
GET	/api/smart-capture/executions?limit=50	Yes	List recent execution records, newest first

Execution Record

Each record includes:

Field	Type	Description
id	int	Execution record ID
trigger_type	string	Event type that triggered (e.g. modulation_change, snr_change)
action_type	string	Action adapter (e.g. capture)
status	string	One of pending, fired, completed, suppressed, expired
fired_at	string	ISO-8601 UTC timestamp when action was dispatched
completed_at	string	ISO-8601 UTC timestamp when result was linked
suppression_reason	string	Why execution was blocked (only for suppressed status)
linked_result_id	int	Speedtest result ID (only for completed status)
last_error	string	Error message (only for expired status)
details	string	JSON-serialized event details from the triggering event
created_at	string	ISO-8601 UTC timestamp when the record was created

API Tokens

Method	Path	Auth	Description
GET	/api/tokens	Yes	List API tokens
POST	/api/tokens	Session only	Create a new token
DELETE	/api/tokens/<id>	Session only	Revoke a token

Notes for Client Authors

• Some endpoints return localized timestamps for UI convenience
• Some endpoints return empty arrays instead of errors when a module is disabled or has no data yet
• Binary endpoints should be handled by Content-Type, not by assuming JSON
• Feature modules may add more /api/* endpoints over time, so clients should tolerate additive changes