Reports
Create immutable English-language restore reports and download them as PDF or HTML.
Loading documentation…
Powered by heyo
Reports capture a point-in-time result set. Their contents are immutable after creation; PDF generation updates their status and download metadata in the background.
Provide a title, ISO 8601 time_range.from and time_range.to (each with an explicit offset or Z; to is exclusive), and one scope:
{"type":"all_checks"} for all project checks in the time range{"type":"check_ids","check_ids":[...]} for up to 500 selected project checks{"type":"schedule","schedule_id":"..."} for checks from one project scheduleReports are generated in English. A client-supplied locale does not change the output language.
All scopes are limited to 500 checks. The time range is inclusive at from and exclusive at to; selection uses finished_at, then started_at, then created_at when the preceding timestamp is absent. Explicit check_ids must also belong to the project and fall within this range, otherwise creation returns 400.
Creation returns 201 with data.id. The new report has status: "pending": its snapshot and HTML are already stored, and the PDF is rendered once in the background. Poll Get report details with bounded backoff until the status is ready or failed. Do not create a new report on every poll.
A ready report exposes pdf_size_bytes, pdf_sha256, and pdf_rendered_at. A failed report can include pdf_error. The renderer retries failed attempts automatically before marking the report failed; downloading it does not trigger another attempt.
Call the download action with {"format":"pdf"} or {"format":"html"}. PDF is the default. The response is a file attachment with Cache-Control: no-store, not a JSON envelope.
PDF requests can return 409 with one of these codes:
| Code | Meaning | Client action |
|---|---|---|
report_pdf_pending | The PDF is still being generated | Wait, poll the report, and retry the download when ready |
report_pdf_failed | PDF generation exhausted its retries | Inspect detail.pdf_error when present; use the stored HTML or investigate before creating a replacement |
report_pdf_unavailable | No stored PDF is available | Use HTML or create a new report; older reports are not automatically backfilled |
HTML is available immediately after successful creation, including while the PDF is pending or failed. A legacy report can be ready without a stored PDF, so clients must still handle report_pdf_unavailable.
List filters support title, scope_type, status, schedule_id, created_from, and created_to. The two timestamp filters take ISO 8601 values with an explicit offset or Z.
Required scopes are v1.reports:read, v1.reports:write, and v1.reports:delete.