Alerts, Audit Logs, Daily Duties & EOD Reports REST API

The governance API provides the oversight and operational infrastructure of the Workforce Intelligence OS. Alerts deliver system signals to individual users; the audit log captures every sensitive state change as an immutable record visible only to administrators; the ops endpoints manage personal duties (daily task notes) and end-of-day reports with a structured review workflow. All paths are prefixed with /api/v1 and require a valid JWT.

The audit log is Admin-only and immutable. Records can never be deleted or modified through the API. Attempts by non-admin callers return 403 PERMISSION_ERROR.

Alerts

Alerts are system-generated notifications attached to a specific recipient user. Each alert has a status (OPEN, RESOLVED) and is ordered by creation time with a maximum of 100 returned per request.

`GET /api/v1/alerts`

Returns up to 100 alerts addressed to the currently authenticated user, ordered newest-first. Auth: Any authenticated user (get_current_user).

[]

array

Array of AlertRead objects.

Show AlertRead fields

string

UUID of the alert.

recipient_user_id

string

UUID of the user this alert belongs to.

status

string

Alert lifecycle status: OPEN or RESOLVED.

message

string

Human-readable alert message.

created_at

string

ISO-8601 UTC creation timestamp.

resolved_at

string | null

ISO-8601 UTC timestamp when the alert was resolved, or null if still open.

Example Response

[
  {
    "id": "a1b2c3d4-e5f6-...",
    "recipient_user_id": "u9v8w7x6-...",
    "status": "OPEN",
    "message": "Attendance session not closed — auto check-out applied.",
    "created_at": "2025-01-20T18:05:00Z",
    "resolved_at": null
  }
]

`PATCH /api/v1/alerts/{alert_id}/resolve`

Marks a specific alert as resolved. Only the alert’s intended recipient may resolve it. Auth: Any authenticated user. Must own the alert.

alert_id

string

required

UUID of the alert to resolve.

string

status

string

Will be RESOLVED after a successful call.

resolved_at

string

UTC timestamp set at resolution time.

Attempting to resolve an alert owned by a different user returns 403 PERMISSION_ERROR. A missing alert returns 404 NOT_FOUND.

Example Response

{
  "id": "a1b2c3d4-e5f6-...",
  "recipient_user_id": "u9v8w7x6-...",
  "status": "RESOLVED",
  "message": "Attendance session not closed — auto check-out applied.",
  "created_at": "2025-01-20T18:05:00Z",
  "resolved_at": "2025-01-20T18:12:34Z"
}

Audit Logs

The audit log is the tamper-evident record of sensitive operations performed in the system. Every destructive or privileged action — user role changes, permission overrides, data exports — is written here automatically by the application.

`GET /api/v1/audit-logs`

Returns up to 200 audit log entries ordered by creation time (newest-first). Auth: ADMIN role required. All other roles receive 403 PERMISSION_ERROR.

[]

array

Array of AuditLogRead objects.

Show AuditLogRead fields

string

UUID of the log entry.

actor_id

string

UUID of the user who performed the action.

action

string

Action identifier string, e.g. "user.role_changed" or "permission.override_set".

entity_type

string | null

The type of resource affected, e.g. "user", "department".

entity_id

string | null

UUID of the affected resource.

metadata

object | null

JSON object containing before/after state or additional context.

ip_address

string | null

IP address of the request origin.

created_at

string

ISO-8601 UTC timestamp of the action.

Audit log entries are written by the server and cannot be created, edited, or deleted via the API. The 200-record cap applies per request.

Example Request

GET /api/v1/audit-logs
Authorization: Bearer <admin_token>

Example Response

[
  {
    "id": "log-1234-...",
    "actor_id": "admin-uuid-...",
    "action": "user.role_changed",
    "entity_type": "user",
    "entity_id": "emp-uuid-...",
    "metadata": {
      "previous_role": "employee",
      "new_role": "team_lead"
    },
    "ip_address": "192.168.1.10",
    "created_at": "2025-01-19T14:22:05Z"
  }
]

System Health

`GET /health`

A lightweight liveness probe that confirms the API process is running. This endpoint is mounted at the application root — not under the /api/v1 prefix — so it is always reachable even if the versioned router is misconfigured. Auth: None required. Suitable for load-balancer health checks.

status

string

Always "ok" when the process is running.

Example Request

GET /health

Example Response

{ "status": "ok" }

Use this endpoint in Kubernetes livenessProbe and readinessProbe configurations. Permission seeding and admin bootstrapping run automatically at application startup — they do not require manual API calls.

Daily Duties

Personal duties are lightweight daily task notes backed by PersonalNote records. They carry a title, optional description, and a pending / completed status. All duty endpoints operate on the currently authenticated user — there is no cross-user access.

`GET /api/v1/duties`

Returns all duties logged by the authenticated user for today (Asia/Karachi date). Auth: Any authenticated user.

[]

array

Array of DutyRead objects.

Show DutyRead fields

string

UUID of the duty (maps to the underlying PersonalNote ID).

user_id

string

UUID of the owning user.

title

string

Duty title extracted from the note content.

description

string | null

Optional additional detail.

status

string

pending or completed.

created_at

string

ISO-8601 UTC creation timestamp.

updated_at

string

ISO-8601 UTC last-updated timestamp.

Example Response

[
  {
    "id": "d1e2f3a4-...",
    "user_id": "u1a2b3c4-...",
    "title": "Review PR #142",
    "description": "Check the authentication middleware changes",
    "status": "pending",
    "created_at": "2025-01-20T08:30:00Z",
    "updated_at": "2025-01-20T08:30:00Z"
  }
]

`POST /api/v1/duties`

Creates a new duty for today. Auth: Any authenticated user.

title

string

required

Duty title.

description

string

Optional additional detail.

string

UUID of the created duty.

status

string

Always "pending" on creation.

Example Request Body

{
  "title": "Write unit tests for attendance service",
  "description": "Cover check-in, check-out, and auto-checkout edge cases"
}

`PATCH /api/v1/duties/{duty_id}`

Update a duty’s title, description, or completion status. Auth: Any authenticated user. Must own the duty.

duty_id

string

required

UUID of the duty to update.

title

string

Updated title.

description

string

Updated description.

status

string

Set to "completed" to mark done, "pending" to reopen.

`DELETE /api/v1/duties/{duty_id}`

Permanently deletes a duty. Auth: Any authenticated user. Must own the duty.

duty_id

string

required

UUID of the duty to delete.

success

boolean

Always true on success.

End-of-Day Reports

EOD reports are structured daily summaries submitted by employees and reviewed by their direct manager. The workflow progresses through states: Generated → Pending Approval → Approved / Rejected / Needs Revision.

`GET /api/v1/eod/me`

Returns the authenticated user’s EOD report for a specific date, or null if none exists. Auth: Any authenticated user.

date

string

Report date in ISO format YYYY-MM-DD. Defaults to today (Asia/Karachi timezone).

string | null

UUID of the EOD report, or response is null.

`GET /api/v1/eod/me/today`

Convenience alias for GET /eod/me with today’s date. Returns the current user’s EOD for today or null. Auth: Any authenticated user.

`POST /api/v1/eod/me/generate`

Generates (or refreshes) the authenticated user’s EOD report for today by pulling attendance, time logs, and task activity. If a report already exists it is refreshed in place. Auth: Any authenticated user.

string

UUID of the generated EOD report.

status

string

Report status after generation, e.g. "Generated".

`POST /api/v1/eod/me/submit`

Submits the authenticated user’s EOD report for manager review. Auth: Any authenticated user.

report_date

string

required

Date of the report being submitted. ISO format YYYY-MM-DD.

work_summary

string

Free-text summary of work completed today.

blockers

string

Any blockers encountered.

next_day_plan

string

Plan for the following day.

status

string

Will be "Pending Approval" after successful submission.

An EOD report must exist (via generate) before it can be submitted. Attempting to submit a non-existent report returns 422.

`GET /api/v1/eod/team`

Returns EOD reports for the manager’s direct reports that have been submitted for review. Supports filtering by status, date, and employee search. Auth: MANAGER or ADMIN role required.

string

Filter by employee name, email, role, department, or designation.

status

string

Filter by EOD status: Pending Approval, Approved, Rejected, or Needs Revision.

report_date

string

Filter to a specific date ISO YYYY-MM-DD.

[]

array

Array of EODReportRead objects for the manager’s direct reports, ordered by date descending.

`POST /api/v1/eod/{report_id}/review`

Reviews a submitted EOD report by approving, rejecting, or requesting revision. Auth: MANAGER or ADMIN role required. The reviewer must be the submitter’s direct manager.

report_id

string

required

UUID of the EOD report to review.

action

string

required

Review decision. One of: Approved, Rejected, Needs Revision.

comments

string

Optional reviewer feedback attached to the report.

string

UUID of the reviewed report.

status

string

Updated status reflecting the review decision.

manager_comments

string | null

Comments stored on the report.

A manager cannot review their own EOD report. Attempting to do so returns 403. HR Operations users are not authorised to review EODs — only the direct manager or an Admin may review.

Example Request Body

{
  "action": "Approved",
  "comments": "Great work today — well-structured summary."
}

Error Reference

HTTP Status	Error Code	Reason
`401`	`AUTH_ERROR`	Missing or invalid JWT
`403`	`PERMISSION_ERROR`	Caller is not authorised (wrong role or not the owner)
`404`	`NOT_FOUND`	Alert, duty, or EOD report not found
`422`	`VALIDATION_ERROR`	Invalid review action or missing required fields
`500`	`INTERNAL_ERROR`	Unhandled server error

Overview

Endpoints

Alerts

`GET /api/v1/alerts`

`PATCH /api/v1/alerts/{alert_id}/resolve`

Audit Logs

`GET /api/v1/audit-logs`

System Health

`GET /health`

Daily Duties

`GET /api/v1/duties`

`POST /api/v1/duties`

`PATCH /api/v1/duties/{duty_id}`

`DELETE /api/v1/duties/{duty_id}`

End-of-Day Reports

`GET /api/v1/eod/me`

`GET /api/v1/eod/me/today`

`POST /api/v1/eod/me/generate`

`POST /api/v1/eod/me/submit`

`GET /api/v1/eod/team`

`POST /api/v1/eod/{report_id}/review`

Error Reference

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Alerts

​GET /api/v1/alerts

​PATCH /api/v1/alerts/{alert_id}/resolve

​Audit Logs

​GET /api/v1/audit-logs

​System Health

​GET /health

​Daily Duties

​GET /api/v1/duties

​POST /api/v1/duties

​PATCH /api/v1/duties/{duty_id}

​DELETE /api/v1/duties/{duty_id}

​End-of-Day Reports

​GET /api/v1/eod/me

​GET /api/v1/eod/me/today

​POST /api/v1/eod/me/generate

​POST /api/v1/eod/me/submit

​GET /api/v1/eod/team

​POST /api/v1/eod/{report_id}/review

​Error Reference

Build docs developers (and LLMs) love

Alerts

`GET /api/v1/alerts`

`PATCH /api/v1/alerts/{alert_id}/resolve`

Audit Logs

`GET /api/v1/audit-logs`

System Health

`GET /health`

Daily Duties

`GET /api/v1/duties`

`POST /api/v1/duties`

`PATCH /api/v1/duties/{duty_id}`

`DELETE /api/v1/duties/{duty_id}`

End-of-Day Reports

`GET /api/v1/eod/me`

`GET /api/v1/eod/me/today`

`POST /api/v1/eod/me/generate`

`POST /api/v1/eod/me/submit`

`GET /api/v1/eod/team`

`POST /api/v1/eod/{report_id}/review`

Error Reference