{
  "openapi": "3.0.3",
  "info": {
    "title": "HR4B Workforce API",
    "description": "REST API for employee records, organization structure, vacancies, leave requests, payroll summaries, and operational status.",
    "version": "1.8.2",
    "contact": {"name": "HR4B Platform Support", "email": "platform-support@hr4b.tech"}
  },
  "servers": [{"url": "https://my.hr4b.tech", "description": "Production"}],
  "tags": [
    {"name": "System", "description": "Health and component status"},
    {"name": "Authentication", "description": "Session and token checks"},
    {"name": "Employees", "description": "Employee directory and profile data"},
    {"name": "Organization", "description": "Departments and reporting structure"},
    {"name": "Recruiting", "description": "Vacancies and hiring workflow"},
    {"name": "Time Off", "description": "Leave requests and approvals"},
    {"name": "Payroll", "description": "Payroll summaries"},
    {"name": "Reports", "description": "Aggregated workforce reports"}
  ],
  "paths": {
    "/api/v1/health": {"get": {"tags": ["System"], "summary": "Health probe", "responses": {"200": {"description": "Gateway is healthy", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Health"}}}}}}},
    "/api/v1/status": {"get": {"tags": ["System"], "summary": "Component status", "responses": {"200": {"description": "Component status", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Status"}}}}}}},
    "/api/v1/auth/session": {"get": {"tags": ["Authentication"], "summary": "Validate current bearer token", "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Session is valid"}, "401": {"description": "Bearer token is missing or invalid", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}},
    "/api/v1/employees": {"get": {"tags": ["Employees"], "summary": "List employees", "parameters": [{"name": "page", "in": "query", "schema": {"type": "integer", "minimum": 1, "default": 1}}, {"name": "per_page", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 25}}, {"name": "status", "in": "query", "schema": {"type": "string", "enum": ["active", "on_leave", "terminated"]}}, {"name": "department_id", "in": "query", "schema": {"type": "string"}}], "responses": {"200": {"description": "Employee list", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/EmployeeList"}}}}}}},
    "/api/v1/employees/{employee_id}": {"get": {"tags": ["Employees"], "summary": "Get employee profile", "parameters": [{"name": "employee_id", "in": "path", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"description": "Employee profile", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Employee"}}}}, "404": {"description": "Employee not found"}}}},
    "/api/v1/departments": {"get": {"tags": ["Organization"], "summary": "List departments", "responses": {"200": {"description": "Department list", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DepartmentList"}}}}}}},
    "/api/v1/vacancies": {"get": {"tags": ["Recruiting"], "summary": "List vacancies", "parameters": [{"name": "status", "in": "query", "schema": {"type": "string", "enum": ["draft", "published", "internal_review", "closed"]}}], "responses": {"200": {"description": "Vacancy list", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/VacancyList"}}}}}}},
    "/api/v1/time-off/requests": {"get": {"tags": ["Time Off"], "summary": "List time-off requests", "parameters": [{"name": "employee_id", "in": "query", "schema": {"type": "string"}}, {"name": "status", "in": "query", "schema": {"type": "string", "enum": ["pending", "approved", "rejected"]}}], "responses": {"200": {"description": "Leave request list", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TimeOffList"}}}}}}},
    "/api/v1/payroll/summary": {"get": {"tags": ["Payroll"], "summary": "Payroll summary by period", "parameters": [{"name": "period", "in": "query", "schema": {"type": "string", "example": "2026-05"}}], "responses": {"200": {"description": "Payroll summary", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PayrollSummary"}}}}}}},
    "/api/v1/reports/headcount": {"get": {"tags": ["Reports"], "summary": "Headcount report", "parameters": [{"name": "period", "in": "query", "schema": {"type": "string", "example": "2026-06"}}], "responses": {"200": {"description": "Headcount report", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/HeadcountReport"}}}}}}}
  },
  "components": {
    "securitySchemes": {"bearerAuth": {"type": "http", "scheme": "bearer", "bearerFormat": "JWT"}},
    "schemas": {
      "Health": {"type": "object", "properties": {"status": {"type": "string"}, "service": {"type": "string"}, "version": {"type": "string"}, "build": {"type": "string"}, "timestamp": {"type": "string", "format": "date-time"}}},
      "Status": {"type": "object", "properties": {"status": {"type": "string"}, "region": {"type": "string"}, "environment": {"type": "string"}, "components": {"type": "object"}}},
      "Employee": {"type": "object", "properties": {"id": {"type": "string"}, "employee_number": {"type": "string"}, "status": {"type": "string"}, "first_name": {"type": "string"}, "last_name": {"type": "string"}, "email": {"type": "string", "format": "email"}, "department": {"type": "object"}, "position": {"type": "string"}, "location": {"type": "string"}}},
      "EmployeeList": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Employee"}}, "pagination": {"$ref": "#/components/schemas/Pagination"}, "links": {"type": "object"}}},
      "DepartmentList": {"type": "object", "properties": {"data": {"type": "array", "items": {"type": "object"}}, "total": {"type": "integer"}}},
      "VacancyList": {"type": "object", "properties": {"data": {"type": "array", "items": {"type": "object"}}, "pagination": {"$ref": "#/components/schemas/Pagination"}}},
      "TimeOffList": {"type": "object", "properties": {"data": {"type": "array", "items": {"type": "object"}}, "summary": {"type": "object"}}},
      "PayrollSummary": {"type": "object", "properties": {"period": {"type": "string"}, "currency": {"type": "string"}, "employees_count": {"type": "integer"}, "gross_total": {"type": "string"}, "net_total": {"type": "string"}, "status": {"type": "string"}}},
      "HeadcountReport": {"type": "object", "properties": {"period": {"type": "string"}, "total_headcount": {"type": "integer"}, "active": {"type": "integer"}, "on_leave": {"type": "integer"}, "by_department": {"type": "array", "items": {"type": "object"}}}},
      "Pagination": {"type": "object", "properties": {"page": {"type": "integer"}, "per_page": {"type": "integer"}, "total": {"type": "integer"}, "total_pages": {"type": "integer"}}},
      "Error": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string"}, "message": {"type": "string"}, "documentation_url": {"type": "string"}}}, "request_id": {"type": "string"}}}
    }
  }
}