openapi: 3.0.3
info:
  title: Acadia - Platform Employees API
  description: Acadia is a Connected Worker Platform providing digital work instructions, skills matrices, quizzing, evaluations, knowledge management, and team communications for frontline workforce development. This API specification documents the programmatic interface for integrating with Acadia's platform features.
  version: 1.0.0
  contact:
    url: https://www.acadia-software.com/
  x-generated-from: documentation
servers:
- url: https://api.acadia-software.com/v1
  description: Acadia Platform API v1
security:
- bearerAuth: []
tags:
- name: Employees
  description: Manage employee profiles and training records
paths:
  /employees:
    get:
      operationId: listEmployees
      summary: Acadia List Employees
      description: List all employees in the organization with their training status.
      tags:
      - Employees
      parameters:
      - name: role_id
        in: query
        required: false
        description: Filter employees by role identifier.
        schema:
          type: string
        example: role-ops-001
      - name: department
        in: query
        required: false
        description: Filter employees by department name.
        schema:
          type: string
        example: Production
      - name: page
        in: query
        required: false
        description: Page number for pagination.
        schema:
          type: integer
          default: 1
        example: 1
      - name: limit
        in: query
        required: false
        description: Number of results per page.
        schema:
          type: integer
          default: 25
        example: 25
      responses:
        '200':
          description: List of employees
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeList'
              examples:
                listEmployees200Example:
                  summary: Default listEmployees 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - id: emp-ghi789
                      name: Jane Smith
                      email: jsmith@example.com
                      department: Production
                      role: Machine Operator
                      trainingCompletion: 87
                    total: 1
                    page: 1
                    limit: 25
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Employee:
      type: object
      description: An employee in the organization
      properties:
        id:
          type: string
          description: Unique employee identifier
          example: emp-ghi789
        name:
          type: string
          description: Employee full name
          example: Jane Smith
        email:
          type: string
          format: email
          description: Employee email address
          example: jsmith@example.com
        department:
          type: string
          description: Department name
          example: Production
        role:
          type: string
          description: Job role name
          example: Machine Operator
        trainingCompletion:
          type: integer
          description: Overall training completion percentage
          example: 87
    ErrorResponse:
      type: object
      description: Error response
      properties:
        message:
          type: string
          description: Human-readable error message
          example: Unauthorized - invalid or expired token
        error:
          type: string
          description: Error code
          example: unauthorized
    EmployeeList:
      type: object
      description: Paginated list of employees
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Employee'
        total:
          type: integer
          example: 150
        page:
          type: integer
          example: 1
        limit:
          type: integer
          example: 25
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT Bearer token for API authentication