No report email? One request reports the run.
When a backup sends no email, or a script does the backing up, the last step of the job can tell BackupSentinel how it went. The result is handled exactly like a report email.
POST /api/v1/jobs/{jobId}/report Authorization: Bearer bsk_live_… Content-Type: application/json Idempotency-Key: nightly-2026-10-06 { "status": "ok", "size_bytes": 48318382080, "duration_seconds": 2710, "timestamp": "2026-10-06T01:45:00Z" }
When to use it instead of email.
Most backup software sends a report email, and the client address is the easier route. The API is for the rest: a product that sends nothing, a database dump or sync run by your own script, or a scheduled task you want watched like a backup.
Create the backup job in BackupSentinel first, then copy its Job ID from the job page. The page also shows an example request with the ID filled in.
The same as a report email
- Status
- ok, warn and failed set Healthy, Warning and Failed, and reset the clock for the next report.
- Alerts
- A warning or failure opens the job’s alert, sends it to your channels and escalates it like any other.
- Recovery
- An ok report resolves the open alert and sends the recovery notice.
- Paused
- For a paused client the report is stored and no alert opens.
- History
- The run shows in the job’s history with the source
api:and the key’s prefix.
What the request carries.
One POST to /api/v1/jobs/:jobId/report with a JSON body. Only the status is required.
| Field | Value | Notes |
|---|---|---|
status | "ok", "warn" or "failed" | Required |
size_bytes | number, 0 or more | Size of the run; 0 is not recorded |
duration_seconds | number, 0 to 604800 | How long the run took, up to 7 days |
timestamp | ISO 8601 date and time | When the run happened |
idempotency_key | string | Used when there is no Idempotency-Key header |
A timestamp more than 5 minutes in the future or more than 30 days old is ignored, and the time the request arrived is used instead.
The answer
{
"ok": true,
"status": "ok",
"alert_id": null,
"duplicate": false,
"superseded": false
}alert_id is the alert the report opened or updated. superseded is true when the job already has a newer report: this one is stored, and the status stays as it is.
Keys are shown once, and retries cannot count twice.
Keys
Owners and admins create keys under Settings → API keys. A key starts with bsk_live_ and is shown once, when it is created; BackupSentinel keeps only a hash of it. The list shows each key’s prefix, when it was created and when it was last used. Revoking a key stops every integration that uses it at once.
A key can report to any job in its workspace. Each key may send 60 requests a minute.
Idempotency
- Send an Idempotency-Key header that names the run, such as the job and the date. The idempotency_key field in the body is the fallback.
- A repeat of the same key on the same job is answered with
duplicate: true. Nothing changes and no second alert opens. - If the first request is still being processed, the repeat gets a 503 with Retry-After: 30.
- A request that never finished is processed again when it is retried after 60 seconds.
What an error tells you.
Every error comes back as JSON with an error message in plain words.
- 400
- The body is not JSON, status is missing or not one of ok, warn, failed, or a number is out of range. The message names the field.
- 401
- The Authorization header is missing or malformed, or the key is not valid.
- 403
- Workspace suspended: a suspended or cancelled workspace is not monitored, so the report is refused.
- 404
- Job not found: the ID is wrong, or the job belongs to another workspace.
- 429
- More than 60 requests a minute on one key, or more than 100 reports for one job in the last 24 hours.
- 503
- A request with the same Idempotency-Key is still being processed. Retry-After says 30 seconds.
- 500
- The report could not be stored. Retry with the same Idempotency-Key.
What it does not do.
- It only takes reports in. There are no endpoints to read jobs, statuses or alerts.
- It cannot create jobs or clients: create the job in the app first and use its Job ID.
- Keys have no scopes. Every key can report to every job in its workspace.
Watch the backups that send no email.
Create the job, create a key, and add one request to the end of the script.