☀️ REST API: Morning Checks

The complete usage guide for the Morning Checks module of the REST API — the daily operational checklist. Mirrors the interactive documentation at System → API → Documentation (with its live "Try it" tester).

[!NOTE] New to the API? The basics table on REST API: Tickets covers base URL, authentication, the response envelope, error codes, rate limits and PATCH semantics — identical across all modules.

What's distinctive about Morning Checks:

📅 One result per check per day	Recording is an upsert — POST /morning-checks/results for a check + date that already has a result overwrites it (200) rather than creating a second (a first record is a 201). That's the dashboard's exact behaviour, and it's backed by a database unique key.
🤖 Built for automated checking	The whole point of exposing this module: a script that probes your backups/mail-flow/VPN each morning can record Green/Amber/Red itself, and the team dashboard fills in before anyone sits down. Results recorded via the API stamp created_by with the key's acting analyst.
🗓️ Plain dates, not timestamps	A check happens on a day — date values are bare YYYY-MM-DD (defaulting to today, server-local, like the dashboard). created_at/modified_at are normal UTC ISO timestamps.
📝 Notes rules enforced	Statuses flagged requires notes in Settings (Red by default) reject an empty notes field with a 422 — same rule as the dashboard's notes modal.
👻 Orphans surfaced	If an admin deletes a status option, historical results saved against it keep a label snapshot. Those rows come back with is_orphan: true + orphan_label, and ?orphans=true lists them — the dashboard's warning-banner set.

---

🚀 Quick start — an automated morning check

B="https://your-server/api/v1"; K="Authorization: Bearer fitsm_…"

# What's on the board and what's already been done today?
curl -s "$B/morning-checks/board" -H "$K"

# Probe passed → record Green for check 3
curl -s -X POST "$B/morning-checks/results" -H "$K" -H "Content-Type: application/json" \
  -d '{"check_id": 3, "status": "Green"}'

# Probe failed → Red requires notes
curl -s -X POST "$B/morning-checks/results" -H "$K" -H "Content-Type: application/json" \
  -d '{"check_id": 3, "status": "Red", "notes": "Overnight Veeam job failed on VM-SQL01."}'

# Ran it again an hour later and things recovered → same call simply overwrites today's result
curl -s -X POST "$B/morning-checks/results" -H "$K" -H "Content-Type: application/json" \
  -d '{"check_id": 3, "status": "Green", "notes": "Job re-ran clean."}'

---

📋 The day board

🟢 GET /morning-checks/board   🔑 morning_check_results.read

Every active check with its result for one date (?date=YYYY-MM-DD, default today) — the dashboard's exact view. result is null for checks not yet done:

{ "data": { "date": "2026-07-03", "checks": [
    { "id": 3, "name": "Backup Status", "description": "Check overnight backup jobs completed", "sort_order": 2,
      "result": { "id": 731, "status": { "id": 1, "label": "Green", "colour": "#28a745" },
                  "is_orphan": false, "orphan_label": null, "notes": "" } },
    { "id": 4, "name": "VPN Gateway", "description": null, "sort_order": 3, "result": null } ] } }

---

✅ Results

🔵 POST /morning-checks/results   🔑 morning_check_results.record

Record (or overwrite) a result — the integration verb.

Field	Notes
check_id	Required. Unknown ids are a 422 (the UI would 500 on the foreign key).
status or status_id	Required. Label (e.g. "Green") or id; must exist and be active.
notes	Required when the status is flagged requires notes, optional otherwise.
date	YYYY-MM-DD, default today. Malformed dates are a 422 — the internal endpoint silently substitutes today, which is exactly wrong for a machine backfilling yesterday.

201 on the first record for that check + date, 200 when overwriting an existing one (same row, status/notes replaced — one result per check per day).

🟢 GET /morning-checks/results   🔑 morning_check_results.read

Result history, newest date first, paginated. Filters: check_id, status_id, date (exact), from / to (inclusive bounds), and orphans=true for only the rows whose status has since been deleted.

🟢 GET /morning-checks/results/{id}   🔑 morning_check_results.read

One result:

{ "data": { "id": 731, "check": { "id": 3, "name": "Backup Status" }, "date": "2026-07-03",
    "status": { "id": 2, "label": "Amber", "colour": "#ffc107" },
    "is_orphan": false, "orphan_label": null, "notes": "Minor delays on one job.",
    "created_by": "Administrator", "created_at": "2026-07-03T07:02:11Z", "modified_at": "2026-07-03T08:15:40Z" } }

There is deliberately no DELETE for results — the module has no such operation (correcting a mistake is just re-POSTing the right status for that date).

---

🧾 Checks (the definitions)

🟢 GET /morning-checks/checks   🔑 morning_checks.read

All check definitions (active and inactive) in board order. is_active=true|false filters; q searches names.

🔵 POST /morning-checks/checks   🔑 morning_checks.create

Only name is required; description, sort_order, is_active optional.

🟢 GET · 🟠 PATCH /morning-checks/checks/{id}   🔑 morning_checks.read/update

PATCH sends only what changes. Deactivating (is_active: false) removes a check from the board but keeps its history — usually what you want.

🔴 DELETE /morning-checks/checks/{id}   🔑 morning_checks.delete

Removes the check and all its historical results, transactionally. Prefer deactivating.

---

📚 Reference lookup

🟢 GET /morning-check-statuses   🔑 reference.read

The configurable status options (Green / Amber / Red by default) with colour, requires_notes and is_active — inactive ones included so historical results always resolve:

{ "data": [ { "id": 1, "label": "Green", "colour": "#28a745", "requires_notes": false, "sort_order": 10, "is_active": true } ] }

---

🔐 Permissions

Group	Actions
Morning checks (morning_checks)	read · create · update · delete — the check definitions
Morning check results (morning_check_results)	read (board + history) · record (the daily upsert)

A typical monitoring key needs only morning_check_results.record (plus read if it wants to see what's outstanding first).

Morning Checks is install-wide — no company scoping (matches the UI) — and the module has no audit trail.