{"openapi":"3.1.0","info":{"title":"ETK Pulse API","version":"1.0.0","description":"REST API for ETK Pulse - multi-tenant HR, payroll, attendance & double-entry finance. All tenant data is isolated by Postgres Row-Level Security; authentication is a NextAuth session cookie set by signing in. Money is always `Decimal` (string) - never float."},"servers":[{"url":"/","description":"This deployment"}],"tags":[{"name":"Auth","description":"Sign-in and password management."},{"name":"Attendance","description":"Employee clock in/out, breaks, and self-service edits."},{"name":"Admin · Attendance","description":"Workspace-admin attendance management, import & export."},{"name":"Admin · People","description":"Employees, teams, and positions."},{"name":"Admin · Shifts","description":"Shift definitions and per-employee assignments."},{"name":"Admin · Time Off","description":"Leave types and request approvals."},{"name":"Admin · Settings","description":"Workspace policy and finance settings."},{"name":"Me","description":"Employee self-service (profile, time off, payslips)."},{"name":"Payroll","description":"Payroll runs, line items, and posting to the ledger."},{"name":"Payslips","description":"Payslip records and PDF export."},{"name":"Finance","description":"Double-entry ledger: accounts, journals, periods, expenses, recurring items, banking."},{"name":"Contracts","description":"Contract templates, generation, and e-signature."},{"name":"Notifications","description":"In-app notification inbox."},{"name":"Status","description":"User presence (online/offline)."},{"name":"Billing","description":"Stripe-ready billing (dark until keys exist)."},{"name":"Integrations","description":"Third-party connectors and inbound webhooks."},{"name":"Super Admin","description":"Platform operations: workspaces, users, audit."},{"name":"Support","description":"Support tickets."},{"name":"Help","description":"Public knowledge-base search."}],"components":{"securitySchemes":{"cookieAuth":{"type":"apiKey","in":"cookie","name":"next-auth.session-token","description":"NextAuth session cookie, set after signing in via /login."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","example":"forbidden"}},"required":["error"]}}},"security":[{"cookieAuth":[]}],"paths":{"/api/auth/{nextauth}":{"get":{"tags":["Auth"],"summary":"NextAuth handler","description":"Catch-all NextAuth route: session, CSRF, callbacks, sign-out.","x-role":"PUBLIC","security":[],"responses":{"200":{"description":"OK"}}},"post":{"tags":["Auth"],"summary":"NextAuth handler (credentials sign-in, sign-out)","x-role":"PUBLIC","security":[],"responses":{"200":{"description":"OK"}}}},"/api/auth/change-password":{"post":{"tags":["Auth"],"summary":"Change your password","x-role":"SESSION","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["currentPassword","newPassword"],"properties":{"currentPassword":{"type":"string"},"newPassword":{"type":"string","minLength":8}}},"example":{"currentPassword":"oldpass123","newPassword":"n3w-strong-pass"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"ok":true}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/attendance/clock-in":{"post":{"tags":["Attendance"],"summary":"Clock in","description":"Starts a work session. Idempotent via `clientEventId` (offline replay-safe). Location captured only if the workspace enables it.","x-role":"SESSION","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lat":{"type":"number"},"lng":{"type":"number"},"clientEventId":{"type":"string","minLength":8},"clientTime":{"type":"string","format":"date-time"}}},"example":{"clientEventId":"evt_3f9ab1c2d4","clientTime":"2026-06-09T08:30:00.000Z"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"session":{"id":"ckxyz","clockInAt":"2026-06-09T08:30:00.000Z","clockOutAt":null}}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/attendance/clock-out":{"post":{"tags":["Attendance"],"summary":"Clock out","x-role":"SESSION","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lat":{"type":"number"},"lng":{"type":"number"},"clientEventId":{"type":"string","minLength":8},"clientTime":{"type":"string","format":"date-time"}}},"example":{"clientEventId":"evt_9c1b7a","clientTime":"2026-06-09T17:00:00.000Z"}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/attendance/start-break":{"post":{"tags":["Attendance"],"summary":"Start a break","x-role":"SESSION","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"clientEventId":{"type":"string","minLength":8},"clientTime":{"type":"string","format":"date-time"}}}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/attendance/end-break":{"post":{"tags":["Attendance"],"summary":"End a break","x-role":"SESSION","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["breakId"],"properties":{"breakId":{"type":"string"},"clientEventId":{"type":"string","minLength":8},"clientTime":{"type":"string","format":"date-time"}}},"example":{"breakId":"brk_123"}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/attendance/sessions/{sessionId}":{"patch":{"tags":["Attendance"],"summary":"Edit your own attendance session","description":"Self-edit of clock in/out + note. Allowed **only** when the workspace has enabled “Allow manual time edits”; otherwise returns 403. Worked/overtime are recomputed server-side.","x-role":"SESSION","security":[{"cookieAuth":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"clockInAt":{"type":"string","format":"date-time"},"clockOutAt":{"type":["string","null"],"format":"date-time"},"note":{"type":["string","null"]}}},"example":{"clockInAt":"2026-06-09T08:45:00.000Z","note":"Adjusted - badge reader was down"}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/attendance/export":{"get":{"tags":["Attendance"],"summary":"Export your attendance (CSV)","x-role":"SESSION","security":[{"cookieAuth":[]}],"parameters":[{"name":"start","in":"query","required":false,"description":"YYYY-MM-DD","schema":{"type":"string"}},{"name":"end","in":"query","required":false,"description":"YYYY-MM-DD","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"text/csv":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/admin/attendance/sessions":{"post":{"tags":["Admin · Attendance"],"summary":"Create an attendance session","x-role":"ADMIN","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["employeeId","clockInAt"],"properties":{"orgId":{"type":"string","description":"Super-admin only: act within this workspace."},"employeeId":{"type":"string"},"clockInAt":{"type":"string","format":"date-time"},"clockOutAt":{"type":["string","null"],"format":"date-time"},"timezone":{"type":"string"},"note":{"type":["string","null"]}}},"example":{"employeeId":"emp_123","clockInAt":"2026-06-09T08:30:00.000Z","clockOutAt":"2026-06-09T17:00:00.000Z"}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/admin/attendance/sessions/{sessionId}":{"patch":{"tags":["Admin · Attendance"],"summary":"Update an attendance session","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgId":{"type":"string","description":"Super-admin only: act within this workspace."},"clockInAt":{"type":"string","format":"date-time"},"clockOutAt":{"type":["string","null"],"format":"date-time"},"timezone":{"type":"string"},"note":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Admin · Attendance"],"summary":"Delete an attendance session","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"orgId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/admin/attendance/import":{"post":{"tags":["Admin · Attendance"],"summary":"Bulk-import attendance rows","x-role":"ADMIN","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rows"],"properties":{"orgId":{"type":"string","description":"Super-admin only: act within this workspace."},"rows":{"type":"array","minItems":1,"maxItems":2000,"items":{"type":"object","required":["employeeEmail","clockInAt"],"properties":{"employeeEmail":{"type":"string"},"clockInAt":{"type":"string","format":"date-time"},"clockOutAt":{"type":["string","null"]},"timezone":{"type":["string","null"]},"note":{"type":["string","null"]},"breaks":{"type":"array","items":{"type":"object","properties":{"breakStartAt":{"type":"string"},"breakEndAt":{"type":["string","null"]}}}}}}}}},"example":{"rows":[{"employeeEmail":"jane@acme.com","clockInAt":"2026-06-09T08:30:00Z","clockOutAt":"2026-06-09T17:00:00Z"}]}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/admin/attendance/export":{"get":{"tags":["Admin · Attendance"],"summary":"Export company attendance (CSV)","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"orgId","in":"query","required":false,"schema":{"type":"string"}},{"name":"teamId","in":"query","required":false,"schema":{"type":"string"}},{"name":"employeeId","in":"query","required":false,"schema":{"type":"string"}},{"name":"start","in":"query","required":false,"description":"YYYY-MM-DD","schema":{"type":"string"}},{"name":"end","in":"query","required":false,"description":"YYYY-MM-DD","schema":{"type":"string"}},{"name":"exceptions","in":"query","required":false,"description":"1 = only exceptions","schema":{"type":"string"}},{"name":"includeBreaks","in":"query","required":false,"description":"0 to exclude","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"text/csv":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/admin/employees":{"get":{"tags":["Admin · People"],"summary":"List employees","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"orgId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"employees":[{"id":"emp_123","fullName":"Jane Doe","teamId":"team_1"}]}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/admin/employees/{employeeId}":{"patch":{"tags":["Admin · People"],"summary":"Update an employee","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"employeeId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgId":{"type":"string","description":"Super-admin only: act within this workspace."},"fullName":{"type":"string","minLength":1},"email":{"type":"string","format":"email"},"teamId":{"type":["string","null"]},"positionId":{"type":["string","null"]},"baseSalaryCurrency":{"type":"string","enum":["USD","EGP"]},"baseSalaryAmount":{"type":"number","minimum":0},"overtimeRateUsdPerHour":{"type":"number","minimum":0},"expectedHoursPerDay":{"type":"number","exclusiveMinimum":0},"expectedDaysPerWeek":{"type":"integer","minimum":1,"maximum":7},"timezone":{"type":"string"},"isActive":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/admin/teams":{"get":{"tags":["Admin · People"],"summary":"List teams","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"orgId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Admin · People"],"summary":"Create a team","x-role":"ADMIN","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"orgId":{"type":"string","description":"Super-admin only: act within this workspace."},"name":{"type":"string","minLength":1}}},"example":{"name":"Engineering"}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/admin/teams/{teamId}":{"patch":{"tags":["Admin · People"],"summary":"Rename a team","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"teamId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgId":{"type":"string","description":"Super-admin only: act within this workspace."},"name":{"type":"string","minLength":1}}}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Admin · People"],"summary":"Delete a team","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"teamId","in":"path","required":true,"schema":{"type":"string"}},{"name":"orgId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/admin/positions":{"get":{"tags":["Admin · People"],"summary":"List positions","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"orgId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Admin · People"],"summary":"Create a position","x-role":"ADMIN","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"orgId":{"type":"string","description":"Super-admin only: act within this workspace."},"title":{"type":"string","minLength":1},"defaultOvertimeRateUsd":{"type":"number","minimum":0}}},"example":{"title":"Senior Engineer","defaultOvertimeRateUsd":25}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/admin/positions/{positionId}":{"patch":{"tags":["Admin · People"],"summary":"Update a position","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"positionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgId":{"type":"string","description":"Super-admin only: act within this workspace."},"title":{"type":"string","minLength":1},"defaultOvertimeRateUsd":{"type":["number","null"],"minimum":0}}}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Admin · People"],"summary":"Delete a position","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"positionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"orgId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/admin/shifts":{"get":{"tags":["Admin · Shifts"],"summary":"List shifts (with teams)","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"orgId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Admin · Shifts"],"summary":"Create a shift","x-role":"ADMIN","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"orgId":{"type":"string","description":"Super-admin only: act within this workspace."},"title":{"type":"string","minLength":1},"teamId":{"type":["string","null"]},"type":{"type":"string","enum":["FIXED","FLEXIBLE","ON_CALL"]},"visibility":{"type":"string","enum":["ALL","TEAM","PRIVATE"]},"daysOfWeek":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6},"description":"0=Sun … 6=Sat. Empty = every day."},"startTimeLocal":{"type":["string","null"],"example":"09:00"},"endTimeLocal":{"type":["string","null"],"example":"17:00"}}},"example":{"title":"Morning Shift","visibility":"TEAM","daysOfWeek":[1,2,3,4,5],"startTimeLocal":"09:00","endTimeLocal":"17:00"}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/admin/shifts/{shiftId}":{"patch":{"tags":["Admin · Shifts"],"summary":"Update a shift","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"shiftId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgId":{"type":"string","description":"Super-admin only: act within this workspace."},"title":{"type":"string","minLength":1},"teamId":{"type":["string","null"]},"type":{"type":"string","enum":["FIXED","FLEXIBLE","ON_CALL"]},"visibility":{"type":"string","enum":["ALL","TEAM","PRIVATE"]},"daysOfWeek":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6}},"startTimeLocal":{"type":["string","null"]},"endTimeLocal":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Admin · Shifts"],"summary":"Delete a shift","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"shiftId","in":"path","required":true,"schema":{"type":"string"}},{"name":"orgId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/admin/shifts/{shiftId}/assignments":{"get":{"tags":["Admin · Shifts"],"summary":"List assigned employees","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"shiftId","in":"path","required":true,"schema":{"type":"string"}},{"name":"orgId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"employeeIds":["emp_123","emp_456"]}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Admin · Shifts"],"summary":"Assign an employee to a shift","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"shiftId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["employeeId"],"properties":{"orgId":{"type":"string","description":"Super-admin only: act within this workspace."},"employeeId":{"type":"string"}}},"example":{"employeeId":"emp_123"}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Admin · Shifts"],"summary":"Unassign an employee","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"shiftId","in":"path","required":true,"schema":{"type":"string"}},{"name":"employeeId","in":"query","required":true,"description":"Employee to unassign","schema":{"type":"string"}},{"name":"orgId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/admin/timeoff/requests":{"get":{"tags":["Admin · Time Off"],"summary":"List time-off requests","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"description":"PENDING | APPROVED | DENIED | …","schema":{"type":"string"}},{"name":"orgId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Admin · Time Off"],"summary":"Approve / deny / postpone a request","x-role":"ADMIN","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["requestId","action"],"properties":{"orgId":{"type":"string","description":"Super-admin only: act within this workspace."},"requestId":{"type":"string"},"action":{"type":"string","enum":["APPROVE","DENY","POSTPONE"]},"adminNote":{"type":"string"},"postponedUntil":{"type":"string","format":"date"}}},"example":{"requestId":"to_1","action":"APPROVE"}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/admin/timeoff/types":{"get":{"tags":["Admin · Time Off"],"summary":"List leave types","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"orgId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Admin · Time Off"],"summary":"Create a leave type","x-role":"ADMIN","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1},"isPaid":{"type":"boolean"},"requiresApproval":{"type":"boolean"},"maxPerYearDays":{"type":"number","exclusiveMinimum":0}}},"example":{"name":"Vacation","isPaid":true,"requiresApproval":true}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Admin · Time Off"],"summary":"Update a leave type","x-role":"ADMIN","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"name":{"type":"string","minLength":1},"isPaid":{"type":"boolean"},"requiresApproval":{"type":"boolean"},"maxPerYearDays":{"type":"number","exclusiveMinimum":0}}}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Admin · Time Off"],"summary":"Delete a leave type","x-role":"ADMIN","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id"],"properties":{"id":{"type":"string"}}}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/admin/settings":{"get":{"tags":["Admin · Settings"],"summary":"Get workspace settings","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"orgId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Admin · Settings"],"summary":"Update workspace settings","x-role":"ADMIN","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgId":{"type":"string","description":"Super-admin only: act within this workspace."},"firstDayOfWeek":{"type":"string","enum":["MONDAY","SUNDAY"]},"defaultTimezone":{"type":"string"},"allowedCurrencies":{"type":"array","items":{"type":"string","enum":["USD","EGP"]}},"allowPickOpenShifts":{"type":"boolean"},"allowDropShifts":{"type":"boolean"},"recordClockLocation":{"type":"boolean"},"allowManualTimeEdits":{"type":"boolean"},"enableFinance":{"type":"boolean"},"defaultExpectedHoursPerDay":{"type":"number","exclusiveMinimum":0,"maximum":24},"overtimeGraceMinutes":{"type":"integer","minimum":0,"maximum":240},"overtimeMultiplier":{"type":"number","minimum":0.25,"maximum":5},"payrollRounding":{"type":"string","enum":["NONE","NEAREST_1","NEAREST_5","NEAREST_10"]}}},"example":{"recordClockLocation":true,"allowManualTimeEdits":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/admin/settings/finance":{"get":{"tags":["Admin · Settings"],"summary":"Get finance settings","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"orgId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Admin · Settings"],"summary":"Update finance settings","x-role":"ADMIN","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgId":{"type":"string","description":"Super-admin only: act within this workspace."},"baseCurrency":{"type":"string","enum":["USD","EGP"]},"fiscalYearStartMonth":{"type":"integer","minimum":1,"maximum":12}}}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/me/profile":{"patch":{"tags":["Me"],"summary":"Update your profile","x-role":"SESSION","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"timezone":{"type":"string"}}},"example":{"timezone":"Africa/Cairo"}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/me/timeoff/requests":{"get":{"tags":["Me"],"summary":"List your time-off requests","x-role":"SESSION","security":[{"cookieAuth":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Me"],"summary":"Request time off","x-role":"SESSION","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["typeId","startDate","endDate"],"properties":{"typeId":{"type":"string"},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"durationHours":{"type":"number","exclusiveMinimum":0},"reason":{"type":"string","maxLength":500}}},"example":{"typeId":"tot_1","startDate":"2026-07-01","endDate":"2026-07-05","reason":"Family trip"}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/me/timeoff/requests/{requestId}":{"delete":{"tags":["Me"],"summary":"Cancel a pending request","x-role":"SESSION","security":[{"cookieAuth":[]}],"parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/me/timeoff/types":{"get":{"tags":["Me"],"summary":"List leave types available to you","x-role":"SESSION","security":[{"cookieAuth":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/me/payslips/{payslipId}/export":{"get":{"tags":["Me"],"summary":"Download your payslip (PDF)","x-role":"SESSION","security":[{"cookieAuth":[]}],"parameters":[{"name":"payslipId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/payroll/runs":{"get":{"tags":["Payroll"],"summary":"List payroll runs","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"orgId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Payroll"],"summary":"Create a payroll run","x-role":"ADMIN","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["periodStart","periodEnd","defaultUsdToEgpRate"],"properties":{"periodStart":{"type":"string","format":"date"},"periodEnd":{"type":"string","format":"date"},"defaultUsdToEgpRate":{"type":"number","exclusiveMinimum":0}}},"example":{"periodStart":"2026-06-01","periodEnd":"2026-06-30","defaultUsdToEgpRate":48.5}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/payroll/runs/{runId}":{"get":{"tags":["Payroll"],"summary":"Get a payroll run","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"}},{"name":"orgId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Payroll"],"summary":"Recalculate a payroll run","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/payroll/runs/{runId}/line-items":{"put":{"tags":["Payroll"],"summary":"Override a run line item","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["employeeId"],"properties":{"employeeId":{"type":"string"},"usdToEgpRateUsed":{"type":"number","exclusiveMinimum":0},"overtimeRateUsdPerHour":{"type":"number","minimum":0},"baseSalaryAmount":{"type":"number","minimum":0}}}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/payroll/runs/{runId}/post-to-ledger":{"post":{"tags":["Payroll"],"summary":"Post a payroll run to the ledger","description":"Emits balanced double-entry journal entries tagged with the payroll source.","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/payslips/{payslipId}":{"get":{"tags":["Payslips"],"summary":"Get a payslip","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"payslipId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/payslips/{payslipId}/export":{"get":{"tags":["Payslips"],"summary":"Download a payslip (PDF)","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"payslipId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/finance/accounts":{"get":{"tags":["Finance"],"summary":"List chart of accounts","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"orgId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Finance"],"summary":"Create an account","x-role":"ADMIN","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code","name","type"],"properties":{"orgId":{"type":"string","description":"Super-admin only: act within this workspace."},"code":{"type":"string","minLength":1,"maxLength":32},"name":{"type":"string","minLength":1,"maxLength":200},"type":{"type":"string","enum":["ASSET","LIABILITY","EQUITY","INCOME","EXPENSE"]},"parentAccountId":{"type":"string"}}},"example":{"code":"6000","name":"Office Supplies","type":"EXPENSE"}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/finance/journals":{"get":{"tags":["Finance"],"summary":"List journal entries","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"orgId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Finance"],"summary":"Create a journal entry (draft)","description":"Lines must balance (Σ debit = Σ credit). At least two lines.","x-role":"ADMIN","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["entryDate","lines"],"properties":{"orgId":{"type":"string","description":"Super-admin only: act within this workspace."},"entryDate":{"type":"string","format":"date"},"memo":{"type":"string","maxLength":2000},"lines":{"type":"array","minItems":2,"maxItems":200,"items":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string"},"debit":{"type":"number","minimum":0},"credit":{"type":"number","minimum":0},"description":{"type":"string","maxLength":2000}}}}}},"example":{"entryDate":"2026-06-09","memo":"Office supplies","lines":[{"accountId":"acc_exp","debit":100},{"accountId":"acc_cash","credit":100}]}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/finance/journals/{journalEntryId}/post":{"post":{"tags":["Finance"],"summary":"Post a draft journal entry","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"journalEntryId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/finance/journals/{journalEntryId}/reverse":{"post":{"tags":["Finance"],"summary":"Reverse a posted journal entry","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"journalEntryId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/finance/periods":{"get":{"tags":["Finance"],"summary":"List finance periods","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"orgId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Finance"],"summary":"Open a finance period","x-role":"ADMIN","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["year","month"],"properties":{"year":{"type":"integer","minimum":2000,"maximum":2100},"month":{"type":"integer","minimum":1,"maximum":12}}},"example":{"year":2026,"month":6}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Finance"],"summary":"Close / delete a period","x-role":"ADMIN","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["year","month"],"properties":{"year":{"type":"integer"},"month":{"type":"integer"}}}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/finance/expense":{"post":{"tags":["Finance"],"summary":"Record an expense","description":"Convenience endpoint that books a balanced expense entry.","x-role":"ADMIN","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["entryDate","amount","expenseAccountId","paymentAccountId"],"properties":{"entryDate":{"type":"string","format":"date"},"amount":{"type":"number","exclusiveMinimum":0},"expenseAccountId":{"type":"string"},"paymentAccountId":{"type":"string"},"memo":{"type":"string","maxLength":2000}}},"example":{"entryDate":"2026-06-09","amount":250,"expenseAccountId":"acc_exp","paymentAccountId":"acc_bank"}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/finance/recurring":{"get":{"tags":["Finance"],"summary":"List recurring items","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"orgId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Finance"],"summary":"Create a recurring item","x-role":"ADMIN","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","kind","amount","cadence","accountId","counterAccountId","nextRunOn"],"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"kind":{"type":"string","enum":["INCOME","EXPENSE"]},"amount":{"type":"number","exclusiveMinimum":0},"cadence":{"type":"string","enum":["MONTHLY","YEARLY"]},"accountId":{"type":"string"},"counterAccountId":{"type":"string"},"nextRunOn":{"type":"string","format":"date"}}},"example":{"name":"Office rent","kind":"EXPENSE","amount":1200,"cadence":"MONTHLY","accountId":"acc_rent","counterAccountId":"acc_bank","nextRunOn":"2026-07-01"}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/finance/recurring/{itemId}":{"patch":{"tags":["Finance"],"summary":"Update a recurring item","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Finance"],"summary":"Delete a recurring item","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/finance/recurring/{itemId}/book":{"post":{"tags":["Finance"],"summary":"Book a recurring item now","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/finance/bank-accounts":{"get":{"tags":["Finance"],"summary":"List bank accounts","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"orgId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Finance"],"summary":"Create a bank account","x-role":"ADMIN","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"institution":{"type":"string","maxLength":120},"currency":{"type":"string","enum":["USD","EGP"]}}},"example":{"name":"Operating - CIB","currency":"EGP"}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/finance/bank-accounts/{bankAccountId}/import":{"post":{"tags":["Finance"],"summary":"Import bank transactions","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"bankAccountId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rows"],"properties":{"source":{"type":"string","maxLength":120},"rows":{"type":"array","minItems":1,"maxItems":2000,"items":{"type":"object","required":["postedAt","amount","description"],"properties":{"postedAt":{"type":"string","format":"date"},"amount":{"type":"number"},"description":{"type":"string","maxLength":500},"reference":{"type":"string","maxLength":120}}}}}}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/finance/bank-transactions/{transactionId}":{"patch":{"tags":["Finance"],"summary":"Match / unmatch / ignore a transaction","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"transactionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["MATCH","UNMATCH","IGNORE"]},"journalEntryId":{"type":"string"}}},"example":{"action":"MATCH","journalEntryId":"je_1"}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/finance/reports/export":{"get":{"tags":["Finance"],"summary":"Export a finance report (CSV)","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"orgId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"text/csv":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/finance/seed":{"post":{"tags":["Finance"],"summary":"Seed a default chart of accounts","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"orgId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/contracts/templates":{"get":{"tags":["Contracts"],"summary":"List contract templates","x-role":"ADMIN","security":[{"cookieAuth":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Contracts"],"summary":"Create a template","x-role":"ADMIN","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","contentHtml"],"properties":{"title":{"type":"string","minLength":1},"language":{"type":"string","enum":["EN","AR","BOTH"]},"direction":{"type":"string","enum":["LTR","RTL"]},"contentHtml":{"type":"string","minLength":1},"fieldsSchema":{"type":"object"}}}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/contracts/templates/{templateId}":{"get":{"tags":["Contracts"],"summary":"Get a template","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"templateId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Contracts"],"summary":"Update a template","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"templateId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"language":{"type":"string","enum":["EN","AR","BOTH"]},"direction":{"type":"string","enum":["LTR","RTL"]},"contentHtml":{"type":"string"},"fieldsSchema":{"type":"object"},"overlaySchema":{"type":"object"}}}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Contracts"],"summary":"Delete a template","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"templateId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/contracts/templates/{templateId}/upload":{"post":{"tags":["Contracts"],"summary":"Upload a DOCX template","description":"multipart/form-data DOCX, converted to HTML via mammoth.","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"templateId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/contracts/create":{"post":{"tags":["Contracts"],"summary":"Generate a contract from a template","x-role":"ADMIN","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["templateId","employeeId"],"properties":{"templateId":{"type":"string"},"employeeId":{"type":"string"},"allowEmployeeEdits":{"type":"boolean"}}},"example":{"templateId":"tpl_1","employeeId":"emp_123"}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/contracts/{contractId}":{"get":{"tags":["Contracts"],"summary":"Get a contract","x-role":"SESSION","security":[{"cookieAuth":[]}],"parameters":[{"name":"contractId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Contracts"],"summary":"Update field values","x-role":"SESSION","security":[{"cookieAuth":[]}],"parameters":[{"name":"contractId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fieldValues"],"properties":{"fieldValues":{"type":"object","additionalProperties":true}}}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Contracts"],"summary":"Change contract status","x-role":"SESSION","security":[{"cookieAuth":[]}],"parameters":[{"name":"contractId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["SENT","VOID"]}}},"example":{"status":"SENT"}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/contracts/{contractId}/sign":{"post":{"tags":["Contracts"],"summary":"Sign a contract","x-role":"SESSION","security":[{"cookieAuth":[]}],"parameters":[{"name":"contractId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["signatureType"],"properties":{"signatureType":{"type":"string","enum":["DRAWN","TYPED","UPLOADED"]},"typedName":{"type":"string"},"signatureImageDataUrl":{"type":"string"},"consent":{"type":"boolean"}}},"example":{"signatureType":"TYPED","typedName":"Jane Doe","consent":true}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/contracts/{contractId}/export":{"get":{"tags":["Contracts"],"summary":"Download a contract (PDF)","x-role":"SESSION","security":[{"cookieAuth":[]}],"parameters":[{"name":"contractId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/notifications":{"get":{"tags":["Notifications"],"summary":"List your notifications","x-role":"SESSION","security":[{"cookieAuth":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Notifications"],"summary":"Mark read / archive / delete","x-role":"SESSION","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["MARK_ALL_READ","MARK_READ","ARCHIVE","DELETE"]},"ids":{"type":"array","items":{"type":"string"}}}},"example":{"action":"MARK_READ","ids":["ntf_1"]}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/status":{"get":{"tags":["Status"],"summary":"Get your presence","x-role":"SESSION","security":[{"cookieAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"status":"ONLINE"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Status"],"summary":"Set your presence","x-role":"SESSION","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["ONLINE","OFFLINE"]}}},"example":{"status":"ONLINE"}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/billing/checkout":{"post":{"tags":["Billing"],"summary":"Start a checkout session","description":"Stripe-ready; returns a checkout URL once billing is enabled (otherwise dark).","x-role":"ADMIN","security":[{"cookieAuth":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/billing/webhook":{"post":{"tags":["Billing"],"summary":"Stripe webhook","description":"Verified by Stripe signature header (no session).","x-role":"PUBLIC","security":[],"responses":{"200":{"description":"OK"}}}},"/api/integrations/providers":{"get":{"tags":["Integrations"],"summary":"List integration providers","x-role":"SUPER_ADMIN","security":[{"cookieAuth":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Integrations"],"summary":"Register a provider","x-role":"SUPER_ADMIN","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["key","name"],"properties":{"key":{"type":"string","minLength":2,"maxLength":64},"name":{"type":"string","minLength":2,"maxLength":200},"category":{"type":"string","maxLength":64},"capabilities":{}}},"example":{"key":"slack","name":"Slack"}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/integrations/webhook-endpoints":{"get":{"tags":["Integrations"],"summary":"List webhook endpoints","x-role":"ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"orgId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Integrations"],"summary":"Create a webhook endpoint","x-role":"ADMIN","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["providerKey","signingSecret"],"properties":{"orgId":{"type":"string","description":"Super-admin only: act within this workspace."},"providerKey":{"type":"string","minLength":2,"maxLength":64},"signingSecret":{"type":"string","minLength":8,"maxLength":500}}}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/integrations/webhooks/{providerKey}":{"post":{"tags":["Integrations"],"summary":"Inbound provider webhook","description":"Verified by the provider's signing secret (no session).","x-role":"PUBLIC","security":[],"parameters":[{"name":"providerKey","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/super/orgs":{"get":{"tags":["Super Admin"],"summary":"List workspaces","x-role":"SUPER_ADMIN","security":[{"cookieAuth":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Super Admin"],"summary":"Create a workspace","x-role":"SUPER_ADMIN","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1}}},"example":{"name":"Acme Inc."}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Super Admin"],"summary":"Update a workspace","x-role":"SUPER_ADMIN","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Super Admin"],"summary":"Delete a workspace","x-role":"SUPER_ADMIN","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id"],"properties":{"id":{"type":"string"}}}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/super/users":{"get":{"tags":["Super Admin"],"summary":"List users across workspaces","x-role":"SUPER_ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"orgId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Super Admin"],"summary":"Create a user","x-role":"SUPER_ADMIN","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","role","organizationId","tempPassword"],"properties":{"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string","enum":["SUPER_ADMIN","ADMIN","EMPLOYEE"]},"organizationId":{"type":"string"},"tempPassword":{"type":"string","minLength":8}}},"example":{"email":"new@acme.com","role":"ADMIN","organizationId":"org_1","tempPassword":"temp-pass-123"}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Super Admin"],"summary":"Update a user","x-role":"SUPER_ADMIN","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["userId"],"properties":{"userId":{"type":"string"},"role":{"type":"string","enum":["SUPER_ADMIN","ADMIN","EMPLOYEE"]},"organizationId":{"type":"string"},"name":{"type":"string"},"tempPassword":{"type":"string","minLength":8},"attendance":{"type":"boolean"},"payroll":{"type":"boolean"},"contracts":{"type":"boolean"},"notifications":{"type":"boolean"},"timeOff":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/super/audit":{"get":{"tags":["Super Admin"],"summary":"Query the audit log","x-role":"SUPER_ADMIN","security":[{"cookieAuth":[]}],"parameters":[{"name":"actorEmail","in":"query","required":false,"schema":{"type":"string"}},{"name":"targetEmail","in":"query","required":false,"schema":{"type":"string"}},{"name":"action","in":"query","required":false,"schema":{"type":"string"}},{"name":"take","in":"query","required":false,"description":"Max rows","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/support/tickets":{"post":{"tags":["Support"],"summary":"Submit a support ticket","x-role":"PUBLIC","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subject","bodyMarkdown"],"properties":{"subject":{"type":"string","minLength":4,"maxLength":200},"bodyMarkdown":{"type":"string","minLength":10,"maxLength":10000},"category":{"type":"string","maxLength":64},"priority":{"type":"string","maxLength":16}}},"example":{"subject":"Cannot clock in","bodyMarkdown":"The clock-in button is greyed out on iOS."}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/help/quick":{"get":{"tags":["Help"],"summary":"Quick help suggestions","x-role":"PUBLIC","security":[],"parameters":[{"name":"q","in":"query","required":false,"description":"Search query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/api/help/search":{"get":{"tags":["Help"],"summary":"Search the knowledge base","x-role":"PUBLIC","security":[],"parameters":[{"name":"q","in":"query","required":true,"description":"Search query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}}}}