Frontend API reference

This reference describes request paths and the response fields the frontend service code expects. It is not a server-side API specification. Where backend behavior is not established by frontend source code, it is identified as unavailable and requires backend/API contract verification.

Base URL and request headers

• VITE_API_BASE_URL, fallback http://localhost:3000/api (front/src/config/environment.ts).
• Axios timeout: VITE_API_TIMEOUT, fallback 10000 ms.
• The shared client sets Content-Type: application/json.
• The request interceptor adds Authorization: Bearer <stored access token> when a token exists.
• Blob export methods use Axios responseType: 'blob'; they still use the configured Axios instance.
• Exact API host and server prefix must be configured for each environment; no live URL is documented here.

Response types

The common frontend types are in front/src/types/common.ts:

interface ApiResponse<T = any> {
  success: boolean;
  data?: T;
  error?: string;
  message?: string;
}

interface PaginatedResponse<T = any> {
  success: boolean;
  data: T[];
  pagination: {
    page: number;
    limit: number;
    total: number;
    totalPages: number;
    hasNext: boolean;
    hasPrev: boolean;
  };
  message?: string;
}

These are frontend expectations, not confirmation every backend endpoint returns these exact shapes. Some services cast responses or map fields; inspect each endpoint page for specifics.

Authentication notes

Frontend service calls use the shared client unless explicitly noted. Token presence causes the client to add a bearer token; the frontend does not establish server-side authorization requirements for each route. On HTTP 401, the client attempts a token refresh, retries the original request once on refresh success, or clears local auth data and redirects to /login on failure. Other status codes are not centrally normalized by this interceptor.

Reading endpoint entries

Each endpoint section gives its implemented method/path, known caller and trigger, request parameters/body, and the frontend's consumed or declared response fields. If no body or parameter is listed, the service does not supply one. All endpoints using the shared client inherit the JSON content-type default and conditional bearer header above; the server's requirement for that header cannot be determined from frontend source. The only HTTP status explicitly handled centrally by the current apiClient is 401. A complete backend error response schema is unavailable unless stated otherwise. Request examples are illustrative path/parameter representations, not verified server contract samples.

Endpoint index

• Authentication and password reset
• Leases
• Reports
• Analytics
• Users
• Settings
• Entities and departments
• Audit

The service modules expose 62 unique request paths when duplicate calls to the same path are counted once (including the /health helper). Some methods are not called by the mounted pages; each reference page identifies these where known.

Legacy API service

front/src/services/api.ts also exports an older static ApiService using API_ENDPOINTS from front/src/constants/index.ts. Its constants include /api/auth/profile, /api/reports/generate, /api/reports/download/:id, and older user/lease paths; the service also implements login/logout, lease, and user methods. No active page call site was found for this class in the reviewed source, and it is not counted as part of the current feature service inventory. Its base URL fallback (http://localhost:3001) and path prefix differ from the current apiClient. Verify call sites before using or extending this legacy service.

All endpoint paths below are relative to {VITE_API_BASE_URL}. Request examples use placeholders and are not backend contract examples. Where an exact request or response cannot be determined, this is stated explicitly.

GET /health (service utility)

front/src/services/api/api.ts exposes apiHealth.check() and apiHealth.getStatus(), both of which call GET {VITE_API_BASE_URL}/health. The health utility is exported from this API module; no mounted page call site was found during the source search. check() returns the response's success value and returns false after logging an exception. getStatus() is typed as an ApiResponse with status, timestamp, environment, and version fields. The actual server response and route availability require backend verification.