Skip to content

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

GET/reports/list

Returns 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

POST/reports/generate

Starts 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
email [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

GET/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

GET/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

POST/reports/delete

Deletes 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

{
    "success": "Report deleted"
}

Shared report (public)

GET/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)

POST/report

Auth: 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
email [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)

GET/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"
        }
    ]
}