openapi: 3.0.3
info:
  title: Acadia - Platform Employees Roles 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: Roles
  description: Manage job roles and training requirements
paths:
  /roles:
    get:
      operationId: listRoles
      summary: Acadia List Roles
      description: List all defined job roles with their training requirements.
      tags:
      - Roles
      responses:
        '200':
          description: List of roles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleList'
              examples:
                listRoles200Example:
                  summary: Default listRoles 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - id: role-ops-001
                      name: Machine Operator
                      department: Production
                      requiredTrainings: 12
                      completionRate: 78
                    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:
    RoleList:
      type: object
      description: Paginated list of roles
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Role'
        total:
          type: integer
          example: 8
        page:
          type: integer
          example: 1
        limit:
          type: integer
          example: 25
    Role:
      type: object
      description: A job role with training requirements
      properties:
        id:
          type: string
          description: Role identifier
          example: role-ops-001
        name:
          type: string
          description: Role name
          example: Machine Operator
        department:
          type: string
          description: Department the role belongs to
          example: Production
        requiredTrainings:
          type: integer
          description: Number of required training completions for the role
          example: 12
        completionRate:
          type: integer
          description: Average completion rate across employees in this role
          example: 78
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT Bearer token for API authentication