Common Headers

Authorization: Bearer <jwt_access_token>
X-Tenant-ID: <society_id>
X-Society-ID: <society_id>          // alias for X-Tenant-ID
X-Societee-Persona-ID: <persona_id>  // optional persona switch
Content-Type: application/json

Rate Limiting Tiers

Tier	Limit	Applied To
AUTH	10 req/min per IP	Login, register, MFA, password reset
READ	120 req/min per user	GET endpoints, list operations
WRITE	30 req/min per user	POST/PUT/DELETE mutations
EXPORT	5 req/min per user	CSV/PDF generation, report exports
AI_QUERY	10 req/min per user	AI copilot, RAG queries

1. Authentication — auth.ts 23 endpoints

Public

Method	Path	Description
POST	/auth/register	Register new society + admin user
POST	/auth/login	Email/password login
POST	/auth/refresh	Refresh JWT pair (valid refresh token)
POST	/auth/forgot-password	Send password-reset email
POST	/auth/reset-password	Set new password via token

Authenticated

Method	Path	Description
POST	/auth/logout	Invalidate session
POST	/auth/change-password	Change password (old + new)
POST	/auth/mfa/setup	Generate TOTP secret + QR data URL
POST	/auth/mfa/verify	Verify TOTP code during setup
POST	/auth/mfa/login	MFA step in login flow (tempToken + code)
POST	/auth/mfa/disable	Disable MFA (requires password recheck)
GET	/auth/mfa/status	Check MFA enrollment
GET	/auth/me	Current user profile + permissions + roles
PATCH	/auth/profile	Update profile (name, phone, avatar)
POST	/auth/switch-persona	Switch active persona/role context
POST	/auth/dpdp/consent	Record DPDP data-usage consent
GET	/auth/dpdp/consent	Fetch DPDP consent record
GET	/auth/sessions	List active sessions
DELETE	/auth/sessions/:sessionId	Revoke specific session
POST	/auth/sessions/revoke-all	Revoke all other sessions

RBAC Management

Method	Path	Description
GET	/auth/rbac/roles	List system roles
POST	/auth/rbac/roles	Create custom role
PUT	/auth/rbac/roles/:roleId	Update role permissions
DELETE	/auth/rbac/roles/:roleId	Delete custom role
POST	/auth/rbac/assign	Assign role to user
POST	/auth/rbac/revoke	Revoke role from user
GET	/auth/rbac/permissions	List all permission strings

2. Society Admin — admin.ts 11 endpoints

Method	Path	Description
GET	/admin/profile	Get society profile
PUT	/admin/profile	Update society profile (name, address, logo)
POST	/admin/ai/tasks	Create AI task
GET	/admin/ai/tasks	List AI tasks (filter by status)
PUT	/admin/ai/tasks/:taskId	Update AI task
DELETE	/admin/ai/tasks/:taskId	Delete AI task
GET	/admin/notices	List notices
POST	/admin/notices	Create notice
PUT	/admin/notices/:noticeId	Update notice
DELETE	/admin/notices/:noticeId	Delete notice
GET	/admin/notices/:noticeId	Get single notice

3. Accounting & GST — accounting.ts 16 endpoints

Method	Path	Description
GET	/accounting/chart-of-accounts	List chart of accounts
POST	/accounting/chart-of-accounts	Create account (code, name, type)
POST	/accounting/journal-entries	Create double-entry journal
GET	/accounting/journal-entries	List journal entries (date range)
POST	/accounting/bank-reconciliation	Reconcile bank statement (fuzzy match)
GET	/accounting/gst-summary	GST liability summary (CGST/SGST/IGST)
POST	/accounting/gst-returns	File/prepare GST return
GET	/accounting/tds-summary	TDS deduction summary
POST	/accounting/credit-notes	Create credit note
POST	/accounting/debit-notes	Create debit note
GET	/accounting/trial-balance	Trial balance report
GET	/accounting/profit-and-loss	P&L statement
GET	/accounting/balance-sheet	Balance sheet
GET	/accounting/cash-flow	Cash flow statement
GET	/accounting/party-ledger	Party ledger (vendor/flat)
POST	/accounting/tally/export	Export for Tally (XML/CSV)

4. Payments — payments.ts 7 endpoints

Method	Path	Description
POST	/payments/record	Record a payment
POST	/payments/upi/qr	Generate UPI QR code
GET	/payments/bank-accounts	List bank accounts
POST	/payments/bank-accounts	Add bank account
POST	/payments/verify	Verify/confirm payment
POST	/payments/refund	Initiate refund
GET	/payments/stats	Payment statistics

5. Complaints — complaints.ts 6 endpoints

Method	Path	Description
GET	/complaints	List complaints (filter: status, category, priority)
GET	/complaints/my	List current user's complaints
POST	/complaints	Create complaint
GET	/complaints/:complaintId	Get complaint details
PUT	/complaints/:complaintId	Update complaint
DELETE	/complaints/:complaintId	Delete complaint

6. Community — community.ts 15 endpoints

Method	Path	Description
GET	/community/polls	List polls
POST	/community/polls	Create poll
POST	/community/polls/:pollId/vote	Cast vote
GET	/community/polls/:pollId/results	Poll results
GET	/community/forum	List forum threads
POST	/community/forum	Create thread
GET	/community/forum/:threadId	Get thread + replies
POST	/community/forum/:threadId/reply	Reply to thread
GET	/community/events	List events
POST	/community/events	Create event
POST	/community/events/:eventId/rsvp	RSVP (GOING/MAYBE/NOT_GOING)
GET	/community/blood-donors	List blood donors
POST	/community/blood-donors	Register as blood donor
GET	/community/safety-alerts	List safety alerts
POST	/community/safety-alerts	Create safety alert

7. Visitors — visitors.ts 8 endpoints

Method	Path	Description
GET	/visitors	List visitor logs
POST	/visitors	Create visitor entry (check-in)
GET	/visitors/active	List currently-in-premises visitors
GET	/visitors/stats	Visitor statistics
GET	/visitors/:visitorId	Get visitor details
POST	/visitors/:visitorId/check-out	Check out visitor
POST	/visitors/:visitorId/approve	Approve pre-approved visitor
POST	/visitors/:visitorId/reject	Reject visitor

8. Letters & NOC — letters.ts 9 endpoints

Method	Path	Description
GET	/letters/templates	List letter templates
POST	/letters/templates	Create letter template
PUT	/letters/templates/:templateId	Update template
DELETE	/letters/templates/:templateId	Delete template
POST	/letters/request	Submit letter request
GET	/letters/requests	List letter requests
POST	/letters/requests/:requestId/approve	Approve letter request
POST	/letters/requests/:requestId/reject	Reject letter request
GET	/letters/requests/:requestId/generate	Generate letter PDF

9. Guard Operations — guard.ts 10 endpoints

Method	Path	Description
POST	/guard/login	Guard badge-based login
POST	/guard/shift/start	Start shift
POST	/guard/shift/end	End shift
GET	/guard/shift/current	Get current active shift
POST	/guard/gate/entry	Log vehicle/person entry
POST	/guard/gate/exit	Log vehicle/person exit
POST	/guard/passcode/approve	Approve visitor passcode
POST	/guard/patrol/scan	Record patrol checkpoint scan
POST	/guard/sos	Trigger SOS alert
GET	/guard/shift/event-log	Get shift event log

10. AI Guard Agents — guardAgents.ts 6 endpoints

Method	Path	Description
POST	/guard-agents/anpr/webhook	ANPR camera plate detection (service-to-service)
POST	/guard-agents/face/webhook	Face detection webhook (service-to-service)
POST	/guard-agents/auto-checkout	Auto-checkout visitors >4hrs (cron)
POST	/guard-agents/boom/barrier	Open/close boom barrier
GET	/guard-agents/dashboard	Guard AI dashboard (alerts, stats)
POST	/guard-agents/sos/broadcast	Broadcast SOS to all guards

11. Documents & Vault — documents.ts 14 endpoints

Method	Path	Description
GET	/documents	List documents (vault)
POST	/documents	Upload document (multipart)
GET	/documents/:documentId	Get document + download URL
DELETE	/documents/:documentId	Delete document
GET	/documents/registers/members	Members register
GET	/documents/registers/minutes	Minutes register
GET	/documents/registers/resolutions	Resolutions register
GET	/documents/registers/meetings	Meetings register
GET	/documents/registers/vehicles	Vehicles register
GET	/documents/letter-templates	List letter templates
POST	/documents/letter-templates	Create letter template
POST	/documents/letter-requests	Submit letter request
GET	/documents/letter-requests	List letter requests
POST	/documents/letter-requests/:requestId/approve	Approve letter request

12. Vendor Management — vendors.ts 11 endpoints

Method	Path	Description
GET	/vendors	List vendors
POST	/vendors	Create vendor
PUT	/vendors/:vendorId	Update vendor
DELETE	/vendors/:vendorId	Delete vendor
POST	/vendors/:vendorId/rate	Rate vendor (1-5 stars)
GET	/vendors/directory	Public vendor directory
GET	/vendors/:vendorId/bills	List vendor bills
POST	/vendors/:vendorId/bills	Create vendor bill
PUT	/vendors/bills/:billId	Update bill
POST	/vendors/bills/:billId/approve	Approve bill
POST	/vendors/bills/:billId/pay	Mark bill as paid

13. Reports & Analytics — reports.ts 11 endpoints

Method	Path	Description
GET	/reports/financial/summary	Financial summary (income, expenses, balance)
GET	/reports/financial/aging	Accounts receivable aging (0-30-60-90+)
GET	/reports/financial/trends	Financial trends (monthly/quarterly)
GET	/reports/financial/defaulters	Payment defaulters list
GET	/reports/operational/complaints	Complaint report by category
GET	/reports/operational/visitors	Visitor report by purpose
GET	/reports/operational/staff	Staff attendance report
GET	/reports/compliance/gst	GST compliance report
GET	/reports/compliance/tds	TDS compliance report
GET	/reports/overview/dashboard	Overview dashboard (all modules)
GET	/reports/export/csv	Export any report as CSV

14. AGM & Governance — agm.ts 13 endpoints

Method	Path	Description
GET	/agm/meetings	List meetings
POST	/agm/meetings	Create AGM/EGM meeting
PUT	/agm/meetings/:meetingId	Update meeting
DELETE	/agm/meetings/:meetingId	Cancel meeting
GET	/agm/meetings/:meetingId/agendas	List agendas
POST	/agm/meetings/:meetingId/agendas	Add agenda item
GET	/agm/meetings/:meetingId/resolutions	List resolutions
POST	/agm/meetings/:meetingId/resolutions	Create resolution
POST	/agm/resolutions/:resolutionId/vote	Cast anonymous vote (Pedersen commitment)
GET	/agm/meetings/:meetingId/minutes	Get minutes
POST	/agm/meetings/:meetingId/minutes	Submit minutes
GET	/agm/meetings/:meetingId/quorum	Calculate quorum
GET	/agm/overview	Governance overview

15. Resident Self-Service — resident.ts 12 endpoints

Method	Path	Description
GET	/resident/dashboard	Resident dashboard (invoices, notices, complaints)
GET	/resident/flats	List flats for current user
GET	/resident/invoices	List user's invoices
GET	/resident/invoices/:invoiceId	Get invoice detail + payments
POST	/resident/payments	Record a payment
GET	/resident/payments	List payment history
GET	/resident/receipts/:paymentId	Get payment receipt
POST	/resident/pay/upi	Pay via UPI (QR code + deep link)
POST	/resident/pay/advance	Pay advance deposit
GET	/resident/ledger	Ledger statement
GET	/resident/vehicles	List user's vehicles
POST	/resident/vehicles	Register vehicle

16. Facilities — facilities.ts 7 endpoints

Method	Path	Description
GET	/facilities	List available facilities
GET	/facilities/:facilityId/slots	Check availability (date filter)
POST	/facilities/bookings	Create booking
GET	/facilities/bookings	List my bookings
POST	/facilities/bookings/:bookingId/cancel	Cancel booking
POST	/facilities/escrow/hold	Hold security deposit
POST	/facilities/escrow/release	Release escrow

17. Finance & Billing — finance.ts 10 endpoints

Method	Path	Description
GET	/finance/invoices	List invoices (filter by status, flat)
POST	/finance/invoices	Create single invoice
POST	/finance/invoices/generate	Billing run (batch generate)
POST	/finance/invoices/generate-run	Automated billing run
POST	/finance/interest/accrue	Accrue late-payment interest
GET	/finance/receipts	List receipts
POST	/finance/receipts	Create receipt
GET	/finance/payments/stats	Payment statistics
GET	/finance/ledger	Society-wide ledger
POST	/finance/accounting/journal-entries	Create journal entry

18. Governance & Elections — governance.ts 14 endpoints

Method	Path	Description
GET	/governance/elections	List elections
POST	/governance/elections	Create election
PUT	/governance/elections/:electionId	Update election
POST	/governance/elections/:electionId/vote	Cast vote (anonymous)
GET	/governance/elections/:electionId/results	Election results
GET	/governance/meetings	List governance meetings
POST	/governance/meetings	Create meeting
GET	/governance/meetings/:meetingId/minutes	Get minutes
POST	/governance/meetings/:meetingId/minutes/ai	AI-generated MoM from transcript
POST	/governance/meetings/:meetingId/minutes/transcribe	Transcribe audio → minutes
GET	/governance/noc	List NOC requests
POST	/governance/noc	Create NOC request
POST	/governance/noc/:nocId/sign	Sign NOC via Aadhaar eSign
GET	/governance/audit-logs	View audit logs

19. Security & Gate — security.ts 8 endpoints

Method	Path	Description
POST	/security/pre-approve	Pre-approve visitor (TOTP-based)
POST	/security/delivery/webhook	Delivery partner webhook
POST	/security/check-in	Check in visitor (guard)
POST	/security/check-out	Check out visitor (guard)
GET	/security/blacklist	List blacklisted persons
POST	/security/blacklist	Add to blacklist
DELETE	/security/blacklist/:entryId	Remove from blacklist
POST	/security/gate/sync	Sync gate status

20. ERP & Property Tree — erp.ts 12 endpoints

Method	Path	Description
GET	/erp/buildings	List buildings
POST	/erp/buildings	Create building
GET	/erp/buildings/:buildingId/wings	List wings
POST	/erp/buildings/:buildingId/wings	Create wing
GET	/erp/wings/:wingId/flats	List flats
POST	/erp/wings/:wingId/flats	Create flat
PUT	/erp/flats/:flatId	Update flat
POST	/erp/residents/onboard	Onboard resident to flat
POST	/erp/residents/offboard	Offboard resident from flat
GET	/erp/noc	List NOC requests
POST	/erp/noc	Create NOC request
POST	/erp/noc/:nocId/approve	Approve NOC

21. Parking & EV — parking.ts 10 endpoints

Method	Path	Description
GET	/parking/vehicles	List registered vehicles
POST	/parking/vehicles	Register vehicle
PUT	/parking/vehicles/:vehicleId	Update vehicle
DELETE	/parking/vehicles/:vehicleId	Remove vehicle
POST	/parking/anpr/webhook	ANPR camera detection webhook
POST	/parking/rfid/webhook	RFID tag read webhook
GET	/parking/visitors	List visitor parking
POST	/parking/ev/sessions	Start EV charging session
POST	/parking/ev/sessions/:sessionId/stop	Stop EV charging session
GET	/parking/slots/availability	Check slot availability

22. Hyperlocal Marketplace — hyperlocal.ts 8 endpoints

Method	Path	Description
POST	/hyperlocal/merchants	Register as merchant
GET	/hyperlocal/merchants	List merchants
GET	/hyperlocal/marketplace	Browse marketplace listings
POST	/hyperlocal/marketplace	Create listing
POST	/hyperlocal/services/book	Book home service
GET	/hyperlocal/services/bookings	List service bookings
POST	/hyperlocal/deals	Create merchant deal
GET	/hyperlocal/deals	List active deals

23. Workforce — workforce.ts 6 endpoints

Method	Path	Description
GET	/workforce/employees	List employees
POST	/workforce/check-in	Geo-fenced check-in
POST	/workforce/check-out	Check out
GET	/workforce/attendance	Attendance records
POST	/workforce/checklist	Submit daily checklist
GET	/workforce/checklist	List checklists

24. Civic Escalation — civic.ts 5 endpoints

Method	Path	Description
POST	/civic/complaints/escalate	Escalate to municipal authority
GET	/civic/complaints	List civic complaints
POST	/civic/corporator/feedback	Submit ward feedback
GET	/civic/corporator/feedback	List feedback
POST	/civic/cron/sla-monitor	SLA monitoring cron trigger

25. AI Copilot & RAG — ai.ts 4 endpoints

Method	Path	Description
POST	/ai/copilot/swarm	Dispatch query to AI agent swarm
POST	/ai/rag/query	Query RAG pipeline (Vectorize)
POST	/ai/queue/event	Ingress event to AI processing queue
GET	/ai/copilot/history	Recent copilot query history

Endpoint Summary

Module	Route File	Endpoints
Authentication & RBAC	auth.ts	23
Society Admin	admin.ts	11
Accounting & GST	accounting.ts	16
Payments	payments.ts	7
Complaints	complaints.ts	6
Community	community.ts	15
Visitors	visitors.ts	8
Letters & NOC	letters.ts	9
Guard Operations	guard.ts	10
AI Guard Agents	guardAgents.ts	6
Documents & Vault	documents.ts	14
Vendor Management	vendors.ts	11
Reports & Analytics	reports.ts	11
AGM & Governance	agm.ts	13
Resident Self-Service	resident.ts	12
Facilities	facilities.ts	7
Finance & Billing	finance.ts	10
Governance & Elections	governance.ts	14
Security & Gate	security.ts	8
ERP & Property Tree	erp.ts	12
Parking & EV	parking.ts	10
Hyperlocal Marketplace	hyperlocal.ts	8
Workforce	workforce.ts	6
Civic Escalation	civic.ts	5
AI Copilot & RAG	ai.ts	4
TOTAL	25 files	~265