openapi: 3.0.3
info:
  title: Acadia - Platform Employees Skills 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: Skills
  description: Manage employee skills and skills matrices
paths:
  /employees/{id}/skills:
    get:
      operationId: getEmployeeSkills
      summary: Acadia Get Employee Skills
      description: Get the skills matrix for a specific employee, showing all required and completed skills.
      tags:
      - Skills
      parameters:
      - name: id
        in: path
        required: true
        description: Employee identifier.
        schema:
          type: string
        example: emp-ghi789
      responses:
        '200':
          description: Employee skills matrix
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeSkillsMatrix'
              examples:
                getEmployeeSkills200Example:
                  summary: Default getEmployeeSkills 200 response
                  x-microcks-default: true
                  value:
                    employeeId: emp-ghi789
                    employeeName: Jane Smith
                    role: Machine Operator
                    skills:
                    - skillId: skill-001
                      name: Machine Startup
                      required: true
                      completed: true
                      completedAt: '2026-02-10T08:00:00Z'
                      score: 95
                    - skillId: skill-002
                      name: Emergency Shutdown
                      required: true
                      completed: false
                      completedAt: null
                      score: null
                    overallCompletion: 50
        '404':
          description: Employee not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    EmployeeSkillsMatrix:
      type: object
      description: Complete skills matrix for an employee
      properties:
        employeeId:
          type: string
          description: Employee identifier
          example: emp-ghi789
        employeeName:
          type: string
          description: Employee name
          example: Jane Smith
        role:
          type: string
          description: Current job role
          example: Machine Operator
        skills:
          type: array
          items:
            $ref: '#/components/schemas/SkillRecord'
        overallCompletion:
          type: integer
          description: Overall skill completion percentage
          example: 87
    SkillRecord:
      type: object
      description: A skill record in the employee skills matrix
      properties:
        skillId:
          type: string
          description: Unique skill identifier
          example: skill-001
        name:
          type: string
          description: Skill name
          example: Machine Startup
        required:
          type: boolean
          description: Whether this skill is required for the role
          example: true
        completed:
          type: boolean
          description: Whether the employee has completed this skill
          example: true
        completedAt:
          type: string
          format: date-time
          description: When the skill was completed
          example: '2026-02-10T08:00:00Z'
        score:
          type: integer
          description: Score achieved (0-100)
          example: 95
    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