API overview

Every deployment serves its own interactive API reference at /api/docs, generated from the code. This page covers the conventions you need before opening it.

Conventions

The API lives under /api/v1/. Responses arrive in a stable envelope:

{
  "status": 200,
  "message": "Success",
  "data": { }
}

Validation problems return the field errors inside errors, and every error carries a human readable detail.

Authentication

POST /api/v1/auth/login/

Returns a short lived access token and a refresh token. Send the access token as Authorization: Bearer <token>. When two factor authentication is enabled for the account, login instead returns two_factor_required and the code goes to POST /api/v1/auth/login/verify/.

Endpoint map

Area	Base path	Notes
Auth	/auth/	Login, refresh, 2FA, password reset, user admin
Profile	/profile/	Photo, address, personal details
Contracts	/contracts/	Employee read, admin manage
Payments	/payments/	Payments, methods, year summary
Invoices	/invoices/	List, detail, download
PTO	/pto/	Balances, requests, admin review
Reimbursements	/reimbursements/	Receipts and review
Meetings	/meetings/	Meetings, slots, slides
Benefits	/benefits/	Plans and enrollments
Support	/support/	Tickets and FAQs
Notifications	/notifications/	List, unread count, mark read
Branding	/branding/	Public white label values
Modules	/modules/	Public module flag state
Logs	/logs/	App logs and the admin audit trail

Live updates

A WebSocket at /ws/notifications/?token=<access> pushes notifications as they happen. The dashboard and the app both keep a connection open and fall back to polling politely when they cannot.

Rate limits

Anonymous callers get sixty requests per minute and authenticated callers two hundred forty. Login and password endpoints carry tighter dedicated limits.