Backup Registry API

Three methods are supported (checked in order):

• Bearer token — Authorization: Bearer <token> (API token or JWT)
• X-API-Key header — X-API-Key: <token>
• Basic auth — Authorization: Basic <base64(user:pass)>

Set API_TOKENS (comma-separated) as a Cloudflare Secret for agent authentication.
Set AUTH_USER / AUTH_PASS for UI/admin access.

npx wrangler secret put API_TOKENS
npx wrangler secret put AUTH_USER
npx wrangler secret put AUTH_PASS

Authentication is bypassed for localhost requests (development/testing).

POST/v1/backup-runs

Submit a backup run report. The server adds received_at. Submitting an existing run_id overwrites it (idempotent).

Request body

{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",  // required — unique run identifier
  "job_name": "postgres-daily",                        // required
  "agent_id": "agent-prod-db-01",                      // required
  "start_time": "2026-05-12T02:00:00Z",               // required — ISO8601
  "end_time": "2026-05-12T02:04:33Z",                 // required — ISO8601
  "status": "success",                                  // required — success|failure|partial
  "bytes_backed_up": 1073741824,                        // optional
  "encrypted": true,                                    // optional
  "encryption_status": "encrypted",                     // optional — encrypted|unencrypted|partial|failed
  "error": null,                                        // optional — string or null
  "metadata": { "compression": "zstd" }                // optional — arbitrary object
}

Example

curl -s -X POST https://backup-registry.golder.tech/v1/backup-runs \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"run_id":"...","job_name":"postgres-daily","agent_id":"db-01","start_time":"2026-05-12T02:00:00Z","end_time":"2026-05-12T02:04:33Z","status":"success"}'

Returns 201 Created with the stored run object on success, or 400 Bad Request with {"error":"..."} on validation failure.

GET/v1/backup-runs

Returns a JSON array of runs, sorted by received_at descending.

Query parameters

• agent_id — filter by exact agent ID
• job_name — filter by exact job name
• status — filter by status: success, failure, partial
• since — only include runs with received_at ≥ since (ISO8601)
• limit — max results, default 100, max 1000

Example

curl -s "https://backup-registry.golder.tech/v1/backup-runs?status=failure&limit=20" \
  -H "Authorization: Bearer <token>"

GET/v1/backup-runs/{run_id}

Returns the full run object, or 404 if not found.

curl -s "https://backup-registry.golder.tech/v1/backup-runs/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer <token>"

DELETE/v1/backup-runs/{run_id}

Removes the run record. Returns 204 No Content.

curl -s -X DELETE "https://backup-registry.golder.tech/v1/backup-runs/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer <token>"