Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Paramount-Intelligence/HR_Monitoring_System/llms.txt

Use this file to discover all available pages before exploring further.

The Workforce Intelligence & Execution OS exposes a versioned REST API built with FastAPI. Every route is mounted under the /api/v1 prefix, responses are JSON, and errors always follow a consistent envelope so client code can handle failures uniformly across every endpoint.

​
Base URL

All API requests must target the /api/v1 prefix: 
https://<your-domain>/api/v1
Interactive API docs (/docs) and the OpenAPI schema (/api/v1/openapi.json) are only served in development. Both endpoints are disabled when APP_ENV is set to any value other than development.

​
Health Check

A public health endpoint lives outside the /api/v1 prefix and requires no authentication: 
GET /health
Response 
{ "status": "ok" }
Use this endpoint for load-balancer probes and uptime monitors.

​
Authentication

Protected endpoints require a valid JWT access token passed as a Bearer credential in the Authorization header: 
Authorization: Bearer <access_token>
Access tokens are short-lived (15 minutes by default). When a token expires, use POST /api/v1/auth/refresh with a valid refresh token to obtain a new pair. See the Auth Endpoints page for the full login, refresh, and logout flow.

​
Standard Error Response

Every error returned by the API — whether a validation failure, a missing resource, or an unhandled exception — follows the same envelope: 
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Start date must be before end date",
    "details": []
  }
}
FieldTypeDescription
codestringMachine-readable error code (see table below)
messagestringHuman-readable summary of the problem
detailsarrayOptional list of field-level validation details

​
Error Codes

CodeHTTP StatusMeaning
AUTH_ERROR401Missing, expired, or invalid access token
PERMISSION_ERROR403Authenticated but insufficient role or permission
NOT_FOUND404Requested resource does not exist
CONFLICT409State conflict — e.g., duplicate record
VALIDATION_ERROR422Request body or query parameter failed validation
RATE_LIMIT_ERROR429Too many requests within the rate-limit window
INTERNAL_ERROR500Unhandled server-side exception
API_ERROR4xxGeneric HTTP error not covered by a specific code above

​
Rate Limiting

Sensitive auth endpoints are rate-limited per IP to protect against brute-force attacks. Exceeding a limit returns a 429 RATE_LIMIT_ERROR.
EndpointMax AttemptsWindow
POST /auth/login515 minutes
POST /auth/forgot-password315 minutes
POST /auth/reset-password515 minutes
Limits apply per IP address. After exhausting attempts the client must wait for the full window to expire before retrying. Configure AUTH_LOGIN_MAX_ATTEMPTS, AUTH_FORGOT_PASSWORD_MAX_ATTEMPTS, and AUTH_RESET_PASSWORD_MAX_ATTEMPTS environment variables to adjust thresholds.

​
CORS Configuration

The API configures CORS via CORSMiddleware. Allowed origins are derived from the FRONTEND_BASE_URL and CORS_ORIGINS environment variables. In development, localhost ports 3000–3002 are also allowed automatically. Allowed methods: GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD Allowed request headers: Authorization, Content-Type, Accept, Origin, Range, X-Requested-With Exposed response headers: Content-Disposition, Content-Length, Content-Range, Accept-Ranges
In production, CORS_ORIGINS must be set explicitly and must include FRONTEND_BASE_URL. The API will refuse to start if these constraints are not met. A wildcard (*) is not accepted in production.

​
API Endpoint Groups

Authentication

Login, token refresh, logout, password reset, and account activation.

Users

Create, retrieve, and update user profiles. Scoped by role.

Attendance

Check-in, check-out, breaks, and attendance correction requests.

Leaves & WFH

Submit and resolve leave requests including sick, casual, WFH, and half-day.

Projects & Tasks

Project lifecycle management and task tracking with complexity scoring.

Time Logs

Start/stop timers against tasks and submit manual time entries.

Analytics & Reports

Employee, manager, and admin dashboards plus exportable attendance reports.

Organization

Departments, shifts, holidays, and announcements.

Governance

System alerts, immutable audit logs, and permission definitions.

Realtime

WebSocket connections and presence tracking via WS tickets.

Build docs developers (and LLMs) love

Get started for freeTalk to us