reports
7 endpoints.
/api/reports Bearer tokenList automated reports
Every automated report, by name, for a superuser; for anyone else, the reports they are a recipient of. Each names the roles it covers, who it goes to, when it is next sent and how its latest run went. A report's figures are on its page, `/reports/{report_id}`.
Responses
| Status | Description | Body |
|---|---|---|
| 200 | The reports open to the caller. | ReportList |
| 401 | The access token is missing or invalid. | ErrorResponse |
| 500 | The reports could not be read. | ErrorResponse |
/api/reports Bearer tokenCreate an automated report
Schedules a report on the people currently holding the given roles — the trainer dashboard's team progress and the sign-in statistics over them — for the given recipients, every day, one weekday or the first of each month, at an hour of the deployment's clock. The first run is the next occurrence: creating a report sends nothing at once (send it by hand with `POST /api/reports/{report_id}/send`). Recipients must be people's accounts, and may open the report's page whether or not they manage its roles. `exclusions` leaves accounts out by email domain or address — the deployment's own staff and test accounts holding the roles, say; omitted, the report starts from the trainer dashboard's default exclusions (`GET /api/trainer-dashboard/default-exclusions`). `contents` chooses what it shows — the per-role pie charts and a line per trainee among them, the sign-in statistics left out — over the default of everything but those two. Superusers only.
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | yes | What the report is called, in its emails and on its page. 1–120 characters |
| enabled | boolean | no | Defaults to true. |
| cadence | string | yes | `daily`: every day at `hour`. `weekly`: on `weekday` at `hour`. `monthly`: on the first of each month at `hour`. Hours are on the deployment's clock (`time_zone`). one of "daily" | "weekly" | "monthly" |
| weekday | integer | no | Defaults to 1 (Monday). minimum 0 · maximum 6 |
| hour | integer | no | Defaults to 7. minimum 0 · maximum 23 |
| role_ids | array of string (uuid) | yes | The department roles the report covers: its people are everyone currently holding one of them. 1–100 items |
| recipient_ids | array of string (uuid) | yes | The accounts the report goes to. Each may also open the report's page, whether or not they manage the roles it covers. at most 50 items |
| exclusions | array of string | no | Defaults to the trainer dashboard's default exclusions, as they stand when the report is created; `[]` leaves nobody out. at most 20 items |
| contents | ReportContentsChanges | no | — |
Responses
| Status | Description | Body |
|---|---|---|
| 201 | The report, as created. | Report |
| 400 | The request body failed validation, or names an unknown role or account, or an exclusion that is neither a domain nor an address, or switches off all its contents. | ErrorResponse |
| 401 | The access token is missing or invalid. | ErrorResponse |
| 403 | The caller is not a superuser. | ErrorResponse |
| 500 | The report could not be saved. | ErrorResponse |
/api/reports/{report_id} Bearer tokenRead an automated report
A report's configuration — its roles, recipients and schedule, and to a superuser the accounts it leaves out — with its next occurrence and latest run. Open to superusers and to the report's recipients; anyone else is answered 404, as if there were no such report.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| report_id | path | string (uuid) | yes | e.g. 3b0f6c1e-2d5a-4f0e-9a51-6d2b8c4e7a10 |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | The report. | Report |
| 401 | The access token is missing or invalid. | ErrorResponse |
| 404 | No such report, or not one the caller receives. | ErrorResponse |
| 500 | The report could not be read. | ErrorResponse |
/api/reports/{report_id} Bearer tokenChange an automated report
Sets any of its name, whether it is sent on schedule, its cadence, weekday and hour, and — replacing them whole — its roles, its recipients and the accounts it leaves out, and any of the switches of what it shows (`contents`). An omitted field is left as it is. Switching a report on or re-timing it does not send retroactively: the next run is the next occurrence of the new schedule. Superusers only.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| report_id | path | string (uuid) | yes | e.g. 3b0f6c1e-2d5a-4f0e-9a51-6d2b8c4e7a10 |
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | no | What the report is called, in its emails and on its page. 1–120 characters |
| enabled | boolean | no | — |
| cadence | string | no | `daily`: every day at `hour`. `weekly`: on `weekday` at `hour`. `monthly`: on the first of each month at `hour`. Hours are on the deployment's clock (`time_zone`). one of "daily" | "weekly" | "monthly" |
| weekday | integer | no | Day of the week, 0 = Sunday … 6 = Saturday; read only when weekly. minimum 0 · maximum 6 |
| hour | integer | no | Hour of the day, 0–23, on the deployment's clock. minimum 0 · maximum 23 |
| role_ids | array of string (uuid) | no | Replaces the roles. 1–100 items |
| recipient_ids | array of string (uuid) | no | Replaces the recipients. at most 50 items |
| exclusions | array of string | no | Replaces the exclusions; `[]` leaves nobody out. at most 20 items |
| contents | any | no | — |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | The report, as changed. | Report |
| 400 | The request body failed validation, or names an unknown role or account, or an exclusion that is neither a domain nor an address, or switches off all its contents. | ErrorResponse |
| 401 | The access token is missing or invalid. | ErrorResponse |
| 403 | The caller is not a superuser. | ErrorResponse |
| 404 | No such report. | ErrorResponse |
| 500 | The report could not be saved. | ErrorResponse |
/api/reports/{report_id} Bearer tokenDelete an automated report
Deletes the report with its record of runs; nothing more is sent. The notifications its runs left in recipients' inboxes stay, leading to a page that is gone. Superusers only.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| report_id | path | string (uuid) | yes | e.g. 3b0f6c1e-2d5a-4f0e-9a51-6d2b8c4e7a10 |
Responses
| Status | Description | Body |
|---|---|---|
| 204 | The report is gone. | — |
| 401 | The access token is missing or invalid. | ErrorResponse |
| 403 | The caller is not a superuser. | ErrorResponse |
| 404 | No such report. | ErrorResponse |
| 500 | The report could not be deleted. | ErrorResponse |
/api/reports/tick Bearer tokenTick the report schedules (cron)
Called hourly by the deployment's cron (`vercel.json`). Sends every enabled report whose latest occurrence at or before now has not been claimed yet — each to its recipients' inboxes and email — one after another within one invocation's time budget; a report not reached is left unclaimed for the next tick. First marks failed any run whose invocation died before settling it. Authenticated by the deployment's `CRON_SECRET` as a bearer token, not by an OIDC access token; a deployment without the variable answers 401 to everyone.
Responses
| Status | Description | Body |
|---|---|---|
| 200 | What the tick sent. | ReportTickResult |
| 401 | The cron secret is missing or wrong. | ErrorResponse |
| 500 | The tick failed part-way; reports not yet claimed go out on the next one. | ErrorResponse |
/api/reports/{report_id}/send Bearer tokenSend an automated report now
Sends the report outside its schedule — whether or not it is enabled — to every recipient's inbox and email, covering the days since the occurrence before today's (the day before for a daily report, the seven days before for a weekly one, the month so far for a monthly one). The schedule is left as it is. Answers the run, with how every recipient fared; a report that could not be built answers its run `failed`, with why. Superusers only.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| report_id | path | string (uuid) | yes | e.g. 3b0f6c1e-2d5a-4f0e-9a51-6d2b8c4e7a10 |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | The run, settled. | ReportRun |
| 401 | The access token is missing or invalid. | ErrorResponse |
| 403 | The caller is not a superuser. | ErrorResponse |
| 404 | No such report. | ErrorResponse |
| 500 | The run could not be recorded. | ErrorResponse |