openapi: 3.1.0
info:
  title: Nasak HSE API
  version: 1.0.0-alpha.1
  description: Tenant-safe safety, health, environment, compliance, reporting, AI, BI, equipment and integration APIs.
servers:
  - url: https://api.nasak.ir/v1/hse
paths:
  /live:
    get: { operationId: getHseLiveness, summary: Check HSE service liveness, security: [], responses: { '200': { $ref: '#/components/responses/Success' } } }
  /auth/identify:
    post:
      operationId: identifyHseAccount
      summary: Identify an HSE account before login
      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: loginHseAccount
      summary: Create an independent HSE 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: logoutHseAccount
      summary: Revoke the current HSE session
      security: [{ hseSession: [] }]
      x-idempotency-exempt: true
      responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
  /context:
    get:
      operationId: getHseContext
      summary: Get account, organization, site, module and permission context
      security: [{ hseSession: [] }]
      responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
  /{resource}:
    parameters:
      - name: resource
        in: path
        required: true
        schema:
          type: string
          enum: [incidents, risks, permits, inspections, actions, training, health, environment, documents, audits, legal, organizations, sites, departments, equipment]
    get:
      operationId: listHseResource
      summary: List tenant-scoped records for an enabled HSE module
      security: [{ hseSession: [] }]
      parameters: [{ name: organizationId, in: query, schema: { type: string, format: uuid } }]
      responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
    post:
      operationId: createHseResource
      summary: Create an audited tenant-scoped HSE record
      security: [{ hseSession: [] }]
      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' }, '429': { $ref: '#/components/responses/TooManyRequests' } }
    patch:
      operationId: updateHseResource
      summary: Update status, workflow, evidence or module-specific HSE fields
      security: [{ hseSession: [] }]
      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' }, '404': { $ref: '#/components/responses/NotFound' } }
  /{resource}/{id}/attachments:
    post:
      operationId: attachFileToHseResource
      summary: Upload a private validated attachment to an authorized HSE record
      security: [{ hseSession: [] }]
      parameters: [{ $ref: '#/components/parameters/Resource' }, { $ref: '#/components/parameters/Id' }]
      x-idempotency-exempt: true
      responses: { '201': { $ref: '#/components/responses/Success' }, '400': { $ref: '#/components/responses/BadRequest' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' }, '413': { $ref: '#/components/responses/BadRequest' } }
  /attachments/{id}:
    get:
      operationId: downloadHseAttachment
      summary: Download a private HSE attachment after tenant and health-scope checks
      security: [{ hseSession: [] }]
      parameters: [{ $ref: '#/components/parameters/Id' }]
      responses: { '200': { description: Authorized file stream. }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' }, '404': { $ref: '#/components/responses/NotFound' } }
  /settings:
    get:
      operationId: getHseSettings
      summary: Get organization HSE modules, risk matrix and policy settings
      security: [{ hseSession: [] }]
      responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
    patch:
      operationId: updateHseSettings
      summary: Update organization HSE configuration
      security: [{ hseSession: [] }]
      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' } }
  /profile:
    get: { operationId: getHseProfile, summary: Get the independent HSE profile, security: [{ hseSession: [] }], responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } } }
    patch:
      operationId: updateHseProfile
      summary: Update the independent HSE profile
      security: [{ hseSession: [] }]
      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' } }
  /profile/password:
    patch:
      operationId: changeHsePassword
      summary: Change the HSE account password
      security: [{ hseSession: [] }]
      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' } }
  /feedback:
    get: { operationId: listOwnHseFeedback, summary: List feedback submitted from HSE, security: [{ hseSession: [] }], responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } } }
    post:
      operationId: createHseFeedback
      summary: Submit feedback to central Nasak administration
      security: [{ hseSession: [] }]
      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/{id}/comments:
    post:
      operationId: commentOnHseFeedback
      summary: Continue an HSE feedback conversation
      security: [{ hseSession: [] }]
      parameters: [{ $ref: '#/components/parameters/Id' }]
      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' } }
  /ai/chat:
    post:
      operationId: chatWithHseAssistant
      summary: Ask the guarded HSE assistant for advisory guidance
      security: [{ hseSession: [] }]
      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' } }
  /ai/incidents/{id}/analyze:
    post: { operationId: analyzeHseIncident, summary: Generate a reviewable AI incident analysis, security: [{ hseSession: [] }], parameters: [{ $ref: '#/components/parameters/Id' }], x-idempotency-exempt: true, responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' }, '404': { $ref: '#/components/responses/NotFound' } } }
  /ai/incidents/{id}/capa:
    post: { operationId: suggestHseIncidentCapa, summary: Generate reviewable corrective-action suggestions, security: [{ hseSession: [] }], parameters: [{ $ref: '#/components/parameters/Id' }], x-idempotency-exempt: true, responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' }, '404': { $ref: '#/components/responses/NotFound' } } }
  /bi/summary:
    get: { operationId: getHseBiSummary, summary: Get management KPIs and risk trends, security: [{ hseSession: [] }], responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } } }
  /bi/dataset:
    get: { operationId: getHseBiDataset, summary: Get a permission-scoped BI dataset, security: [{ hseSession: [] }], responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } } }
  /bi/export:
    get: { operationId: exportHseReport, summary: Export an authorized HSE report, security: [{ hseSession: [] }], responses: { '200': { description: Report stream. }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } } }
  /integrations/status:
    get: { operationId: getHseIntegrationStatus, summary: Get configured ERP, SAP, IoT, GIS and BI integration health without secrets, security: [{ hseSession: [] }], responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } } }
  /iot/sensors:
    get: { operationId: listHseIotSensors, summary: List tenant IoT sensors and latest state, security: [{ hseSession: [] }], responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } } }
  /iot/ingest:
    post:
      operationId: ingestHseIotReading
      summary: Ingest an authenticated IoT reading with replay protection
      security: [{ serviceToken: [] }]
      x-idempotency-exempt: true
      requestBody: { $ref: '#/components/requestBodies/Mutation' }
      responses: { '202': { $ref: '#/components/responses/Success' }, '400': { $ref: '#/components/responses/BadRequest' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' }, '429': { $ref: '#/components/responses/TooManyRequests' } }
  /equipment/{id}:
    get: { operationId: getHseEquipment, summary: Get an authorized equipment record, security: [{ hseSession: [] }], parameters: [{ $ref: '#/components/parameters/Id' }], responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' }, '404': { $ref: '#/components/responses/NotFound' } } }
  /equipment/{id}/qr:
    get: { operationId: getHseEquipmentQr, summary: Get a signed equipment QR payload, security: [{ hseSession: [] }], parameters: [{ $ref: '#/components/parameters/Id' }], responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' }, '404': { $ref: '#/components/responses/NotFound' } } }
  /admin:
    get: { operationId: getHseAdminDashboard, summary: Get system and organization administration state, security: [{ hseSession: [] }], responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } } }
    patch: { operationId: updateHseAdministration, summary: Update roles, membership or organization configuration, security: [{ hseSession: [] }], 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' } } }
    post: { operationId: createHseOrganizationOrMembership, summary: Create an audited HSE administration record, security: [{ hseSession: [] }], 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' } } }
components:
  securitySchemes:
    hseSession: { type: apiKey, in: cookie, name: nasak_hse_session }
    serviceToken: { type: http, scheme: bearer, bearerFormat: JWT }
  parameters:
    Id: { name: id, in: path, required: true, schema: { type: string, format: uuid } }
    Resource: { name: resource, in: path, required: true, schema: { type: string } }
  requestBodies:
    Mutation:
      required: true
      content: { application/json: { schema: { type: object, additionalProperties: true } } }
  responses:
    Success: { description: Operation completed., content: { application/json: { schema: { type: object, additionalProperties: true } } } }
    BadRequest: { description: Invalid request. }
    Unauthorized: { description: Authentication required. }
    Forbidden: { description: Tenant, module or permission access denied. }
    NotFound: { description: Resource not found in the authorized tenant. }
    TooManyRequests: { description: Rate limit exceeded. }