Reports¶
Reports are PDF summaries of a device's history over a period. A report is generated in the background and emailed when ready; it can then be viewed, shared with a public link or deleted.
Supported device types: sensor, batmon, met, ws (or workstation), gps.
Retention: reports are kept for 35 days after creation. Expired reports are still listed (with expired: true) until a scheduled cleanup job removes the record and the PDF; they can no longer be viewed or shared.
Quota: the number of reports a user may hold at the same time (non-expired reports) depends on the account type:
| Account type | Max reports |
|---|---|
| 0 | 5 |
| 1 (Basic) | 10 |
| 2 (Start-up) | 15 |
| 3 (Growth) | 25 |
| 4 (Premium) | 50 |
| any other value | 10 |
Unlike most endpoints, errors from /reports/generate, /reports/view, /reports/share and /reports/delete are returned as {"failed": "..."} with HTTP status 200. An invalid api_key returns HTTP 401 with {"failed": "[Auth]: Failed to validate the api_key. Try to login again."}.
List reports¶
/reports/listReturns the user's reports, newest first, with the quota information
Request¶
Auth: api_key (query param or cookie)
Request body:
None
Request example:
https://spoilerinterface.com/interface/reports/list?api_key=8f14e45fceea167a5a36dedd4bea2543
Response¶
{
"success": [
{
"id": 42,
"report_name": "sensor_report_3f2b8c1e-5d4a-4e7b-9c0d-1a2b3c4d5e6f.pdf",
"report_link": "https://spoilerinterface.com/interface/reports/shared/eyJhbGciOiJIUzI1NiJ9.eyJyZXBvcnRfbmFtZSI6Ii4uLiJ9.c2lnbmF0dXJl",
"start_time_epoch": 1715948672,
"end_time_epoch": 1716553472,
"created_at_epoch": 1716553480,
"expired": false,
"expires_at_epoch": 1719577480,
"type": "report"
}
],
"limit": 10,
"active": 1
}
Field description¶
| Field name | Description | Type |
|---|---|---|
| id | Report ID, used by the view / share / delete endpoints | int |
| report_name | PDF file name | str |
| report_link | Public share link created when the report was generated | str |
| start_time_epoch / end_time_epoch | Reported period (epoch seconds) | int |
| created_at_epoch | Creation time (epoch seconds) | int |
| expired | true when the report is older than 35 days |
bool |
| expires_at_epoch | Expiry time (epoch seconds) | int |
| limit | Maximum number of reports for the account (top level) | int |
| active | Number of non-expired reports (top level) | int |
Generate report¶
/reports/generateStarts generating a PDF report for a device; the report is emailed when ready
Request¶
Auth: api_key (query param or cookie) · Content-type: application/x-www-form-urlencoded
Request body:
The request body should be sent as form data:
| Field name | Description | Type |
|---|---|---|
| device_type | sensor, batmon, met, ws / workstation or gps |
str |
| device_id | ID of the device | int |
| period | [Optional] weekly (last 7 days, default), monthly (last 30 days) or custom |
str |
| start_epoch | [Optional] Start of the period in epoch seconds. Required when period=custom |
int |
| end_epoch | [Optional] End of the period in epoch seconds. Required when period=custom; must be after start_epoch |
int |
| [Optional] Address to send the report to. Defaults to the account email | str |
Request example:
device_type=sensor&device_id=301659085216623&period=custom&start_epoch=1715948672&end_epoch=1716553472&email=user@example.com
Response¶
{
"success": "Report is being generated. An email will be sent to the specified address shortly.",
"limit": 10,
"active": 1
}
Failures: Unsupported device_type '...', device_id required, Invalid custom period, Invalid custom date range, You have reached the maximum of <limit> reports. Please delete an existing report first., No data found for the device.
Note: active is counted when the request returns, before the new report is stored.
View report¶
/reports/view/{report_id}Downloads the PDF of one of the user's reports
Request¶
Auth: api_key (query param or cookie)
Request body:
None. {report_id} is the id from List reports.
Request example:
https://spoilerinterface.com/interface/reports/view/42?api_key=8f14e45fceea167a5a36dedd4bea2543
Response¶
The PDF file (Content-Type: application/pdf).
Failures (JSON): Report not found, Report has expired (older than 35 days)., Report file not found.
Share report¶
/reports/share/{report_id}Returns a public link to a report that can be opened without logging in
Request¶
Auth: api_key (query param or cookie)
Request body:
None
Request example:
https://spoilerinterface.com/interface/reports/share/42?api_key=8f14e45fceea167a5a36dedd4bea2543
Response¶
{
"success": "https://spoilerinterface.com/interface/reports/shared/eyJhbGciOiJIUzI1NiJ9.eyJyZXBvcnRfbmFtZSI6Ii4uLiJ9.c2lnbmF0dXJl"
}
The link stays valid for as long as the report exists (until its 35-day retention ends or it is deleted).
Delete report¶
/reports/deleteDeletes one of the user's reports and its PDF
Request¶
Auth: api_key (query param or cookie) · Content-type: application/x-www-form-urlencoded
Request body:
The request body should be sent as form data:
| Field name | Description | Type |
|---|---|---|
| report_id | ID of the report | int |
Request example:
report_id=42
Response¶
Shared report (public)¶
/reports/shared/{token}Opens a shared report from its public link
Request¶
Auth: None (the token identifies the report)
Request body:
None. {token} is the token from the share link. The same handler is also mounted at /boardboard/reports/shared/{token}.
Request example:
https://spoilerinterface.com/interface/reports/shared/eyJhbGciOiJIUzI1NiJ9.eyJyZXBvcnRfbmFtZSI6Ii4uLiJ9.c2lnbmF0dXJl
Response¶
The PDF file (Content-Type: application/pdf). Errors are returned as short HTML pages:
| Status | Meaning |
|---|---|
| 400 | Invalid report link (token cannot be decoded) |
| 404 | Report or report file not found |
| 410 | Report has expired (older than 35 days) |
| 500 | Unexpected error |
Legacy endpoints¶
The following older endpoints are still available. New integrations should use the endpoints above.
Generate report (legacy)¶
/reportAuth: api_key (query param or cookie)
Fields can be sent as query parameters or a JSON body (Content-type: application/json). No report quota is applied.
| Field name | Description | Type |
|---|---|---|
| device_type | sensor, batmon, met, ws or gps (also Sensor, Met, WS, GPS) |
str |
| device_id | ID of the device | int |
| start_time_epoch | Start of the period (epoch seconds) | int |
| end_time_epoch | End of the period (epoch seconds) | int |
| [Optional] Address to send the report to | str |
{
"device_type": "sensor",
"device_id": 301659085216623,
"start_time_epoch": 1715948672,
"end_time_epoch": 1716553472,
"email": "user@example.com"
}
Response:
{
"success": "Report is being generated. An email will be sent to the specified address shortly. "
}
List reports (legacy)¶
/reports/Auth: api_key (query param or cookie)
Response:
{
"success": [
{
"report_name": "sensor_report_3f2b8c1e-5d4a-4e7b-9c0d-1a2b3c4d5e6f.pdf",
"start_time_epoch": 1715948672,
"end_time_epoch": 1716553472,
"created_at_epoch": 1716553480,
"report_link": "https://spoilerinterface.com/interface/reports/shared/eyJhbGciOiJIUzI1NiJ9.eyJyZXBvcnRfbmFtZSI6Ii4uLiJ9.c2lnbmF0dXJl"
}
]
}