openapi: 3.1.0
info:
  title: Nasak HR API
  version: 1.0.0-alpha.1
  description: Tenant-safe organization, workforce, recruitment, performance and learning APIs.
servers:
  - url: https://api.nasak.ir/v1/hr
paths:
  /live:
    get:
      operationId: getHrLiveness
      summary: Check HR service liveness
      security: []
      responses:
        '200': { $ref: '#/components/responses/Success' }
  /auth/identify:
    post:
      operationId: identifyHrAccount
      summary: Identify an HR account before login or registration
      security: []
      x-idempotency-exempt: true
      requestBody: { $ref: '#/components/requestBodies/Mutation' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
  /auth/login:
    post:
      operationId: loginHrAccount
      summary: Create an independent HR session
      security: []
      x-idempotency-exempt: true
      requestBody: { $ref: '#/components/requestBodies/Mutation' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
  /auth/logout:
    post:
      operationId: logoutHrAccount
      summary: Revoke the current HR session
      security: [{ hrSession: [] }]
      x-idempotency-exempt: true
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /context:
    get:
      operationId: getHrContext
      summary: Get account, tenant, role and navigation context
      security: [{ hrSession: [] }]
      parameters:
        - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /organizations:
    get:
      operationId: listHrOrganizations
      summary: List organizations available to the current account
      security: [{ hrSession: [] }]
      responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
    post:
      operationId: createHrOrganization
      summary: Create an HR organization
      security: [{ hrSession: [] }]
      x-idempotency-exempt: true
      requestBody: { $ref: '#/components/requestBodies/Mutation' }
      responses: { '201': { $ref: '#/components/responses/Success' }, '400': { $ref: '#/components/responses/BadRequest' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
  /sites:
    get:
      operationId: listHrSites
      summary: List tenant sites
      security: [{ hrSession: [] }]
      parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
      responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
    post:
      operationId: createHrSite
      summary: Create a tenant site
      security: [{ hrSession: [] }]
      x-idempotency-exempt: true
      parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
      requestBody: { $ref: '#/components/requestBodies/Mutation' }
      responses: { '201': { $ref: '#/components/responses/Success' }, '400': { $ref: '#/components/responses/BadRequest' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
  /departments:
    get:
      operationId: listHrDepartments
      summary: List tenant departments
      security: [{ hrSession: [] }]
      parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
      responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
    post:
      operationId: createHrDepartment
      summary: Create a tenant department
      security: [{ hrSession: [] }]
      x-idempotency-exempt: true
      parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
      requestBody: { $ref: '#/components/requestBodies/Mutation' }
      responses: { '201': { $ref: '#/components/responses/Success' }, '400': { $ref: '#/components/responses/BadRequest' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
  /jobs:
    get:
      operationId: listHrJobs
      summary: List tenant jobs and job definitions
      security: [{ hrSession: [] }]
      parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
      responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
    post:
      operationId: createHrJob
      summary: Create a tenant job definition
      security: [{ hrSession: [] }]
      x-idempotency-exempt: true
      parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
      requestBody: { $ref: '#/components/requestBodies/Mutation' }
      responses: { '201': { $ref: '#/components/responses/Success' }, '400': { $ref: '#/components/responses/BadRequest' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
  /positions:
    get:
      operationId: listHrPositions
      summary: List organization positions
      security: [{ hrSession: [] }]
      parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
      responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
    post:
      operationId: createHrPosition
      summary: Create an organization position
      security: [{ hrSession: [] }]
      x-idempotency-exempt: true
      parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
      requestBody: { $ref: '#/components/requestBodies/Mutation' }
      responses: { '201': { $ref: '#/components/responses/Success' }, '400': { $ref: '#/components/responses/BadRequest' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
    patch:
      operationId: updateHrPosition
      summary: Update an organization position
      security: [{ hrSession: [] }]
      x-idempotency-exempt: true
      parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
      requestBody: { $ref: '#/components/requestBodies/Mutation' }
      responses: { '200': { $ref: '#/components/responses/Success' }, '400': { $ref: '#/components/responses/BadRequest' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
  /employees:
    get:
      operationId: listHrEmployees
      summary: Search and filter employees
      security: [{ hrSession: [] }]
      parameters:
        - $ref: '#/components/parameters/OrganizationId'
        - { in: query, name: q, schema: { type: string, maxLength: 160 } }
        - { in: query, name: status, schema: { type: string } }
      responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
    post:
      operationId: createHrEmployee
      summary: Create an employee record
      security: [{ hrSession: [] }]
      x-idempotency-exempt: true
      parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
      requestBody: { $ref: '#/components/requestBodies/Mutation' }
      responses: { '201': { $ref: '#/components/responses/Success' }, '400': { $ref: '#/components/responses/BadRequest' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' }, '429': { $ref: '#/components/responses/TooManyRequests' } }
    patch:
      operationId: updateHrEmployee
      summary: Update an employee record
      security: [{ hrSession: [] }]
      x-idempotency-exempt: true
      parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
      requestBody: { $ref: '#/components/requestBodies/Mutation' }
      responses: { '200': { $ref: '#/components/responses/Success' }, '400': { $ref: '#/components/responses/BadRequest' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' }, '429': { $ref: '#/components/responses/TooManyRequests' } }
  /employees/import/template:
    get:
      operationId: downloadHrEmployeeImportTemplate
      summary: Download the employee spreadsheet import template
      security: [{ hrSession: [] }]
      responses: { '200': { $ref: '#/components/responses/Binary' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
  /employees/import:
    post:
      operationId: importHrEmployees
      summary: Validate and import employee spreadsheet rows
      security: [{ hrSession: [] }]
      x-idempotency-exempt: true
      parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file: { type: string, format: binary }
      responses: { '200': { $ref: '#/components/responses/Success' }, '400': { $ref: '#/components/responses/BadRequest' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' }, '413': { $ref: '#/components/responses/PayloadTooLarge' } }
  /workforce-plans:
    get:
      operationId: listHrWorkforcePlans
      summary: List workforce plans, gaps and forecasts
      security: [{ hrSession: [] }]
      parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
      responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
    post:
      operationId: createHrWorkforcePlan
      summary: Create a workforce plan or gap record
      security: [{ hrSession: [] }]
      x-idempotency-exempt: true
      parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
      requestBody: { $ref: '#/components/requestBodies/Mutation' }
      responses: { '201': { $ref: '#/components/responses/Success' }, '400': { $ref: '#/components/responses/BadRequest' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
  /recruitment:
    get:
      operationId: getHrRecruitmentPipeline
      summary: Get recruitment requests, candidates and onboarding tasks
      security: [{ hrSession: [] }]
      parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
      responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
    post:
      operationId: createHrRecruitmentRecord
      summary: Create a recruitment request, candidate or onboarding task
      security: [{ hrSession: [] }]
      x-idempotency-exempt: true
      parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
      requestBody: { $ref: '#/components/requestBodies/Mutation' }
      responses: { '201': { $ref: '#/components/responses/Success' }, '400': { $ref: '#/components/responses/BadRequest' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
    patch:
      operationId: updateHrRecruitmentRecord
      summary: Advance or update a recruitment record
      security: [{ hrSession: [] }]
      x-idempotency-exempt: true
      parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
      requestBody: { $ref: '#/components/requestBodies/Mutation' }
      responses: { '200': { $ref: '#/components/responses/Success' }, '400': { $ref: '#/components/responses/BadRequest' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
  /performance:
    get:
      operationId: getHrPerformanceData
      summary: Get performance cycles, goals, KPI and OKR records
      security: [{ hrSession: [] }]
      parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
      responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
    post:
      operationId: createHrPerformanceRecord
      summary: Create a performance cycle, goal, KPI or OKR record
      security: [{ hrSession: [] }]
      x-idempotency-exempt: true
      parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
      requestBody: { $ref: '#/components/requestBodies/Mutation' }
      responses: { '201': { $ref: '#/components/responses/Success' }, '400': { $ref: '#/components/responses/BadRequest' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
  /learning:
    get:
      operationId: getHrLearningData
      summary: Get courses, enrollments and learning status
      security: [{ hrSession: [] }]
      parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
      responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
    post:
      operationId: createHrLearningRecord
      summary: Create a course or employee enrollment
      security: [{ hrSession: [] }]
      x-idempotency-exempt: true
      parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
      requestBody: { $ref: '#/components/requestBodies/Mutation' }
      responses: { '201': { $ref: '#/components/responses/Success' }, '400': { $ref: '#/components/responses/BadRequest' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
  /feedback:
    get:
      operationId: listHrFeedback
      summary: List feedback submitted by the current HR user
      security: [{ hrSession: [] }]
      responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
    post:
      operationId: createHrFeedback
      summary: Submit feedback to the central Nasak administration
      security: [{ hrSession: [] }]
      x-idempotency-exempt: true
      requestBody: { $ref: '#/components/requestBodies/Mutation' }
      responses: { '201': { $ref: '#/components/responses/Success' }, '400': { $ref: '#/components/responses/BadRequest' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
  /feedback/{feedbackId}/comments:
    post:
      deprecated: true
      operationId: createLegacyHrFeedbackComment
      summary: Legacy feedback comment route retained during central feedback migration
      security: [{ hrSession: [] }]
      x-idempotency-exempt: true
      parameters:
        - in: path
          name: feedbackId
          required: true
          schema: { type: string, format: uuid }
      responses: { '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' }, '410': { $ref: '#/components/responses/Gone' } }
components:
  securitySchemes:
    hrSession:
      type: apiKey
      in: cookie
      name: nasak_hr_session
  parameters:
    OrganizationId:
      in: query
      name: organizationId
      required: false
      schema: { type: string, format: uuid }
  requestBodies:
    Mutation:
      required: true
      content:
        application/json:
          schema: { type: object, additionalProperties: true }
  responses:
    Success:
      description: Request completed successfully.
      content:
        application/json:
          schema: { type: object, additionalProperties: true }
    Binary:
      description: Binary file response.
      content:
        application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
          schema: { type: string, format: binary }
    BadRequest:
      description: Input validation failed.
    Unauthorized:
      description: Authentication is required.
    Forbidden:
      description: The account cannot access the organization or operation.
    TooManyRequests:
      description: Request rate limit exceeded.
    PayloadTooLarge:
      description: Uploaded file exceeds the configured limit.
    Gone:
      description: The legacy operation has moved to the central feedback service.