openapi: 3.2.0
info:
  title: VKS Work Orders API
  description: The VKS (Visual Knowledge Share) JSON REST API provides programmatic access to pull guidebook and production information out of VKS and manage Work Orders and operations. It supports bi-directional integration with ERP, MES, QMS, and LMS systems for manufacturing environments. Supports up to 50 requests per minute for SaaS deployments.
  version: 1.23.0
  contact:
    name: VKS Support
    url: https://help.vksapp.com/
  license:
    name: Proprietary
    url: https://vksapp.com/
servers:
- url: https://api.vksapp.com
  description: VKS SaaS API
- url: https://{your-vks-instance}
  description: VKS On-Premises API
  variables:
    your-vks-instance:
      default: vks.example.com
      description: Your VKS on-premises hostname
tags:
- name: Work Orders
  description: Create, retrieve, and manage work orders on the manufacturing floor
paths:
  /api/workorders:
    get:
      operationId: listWorkOrders
      summary: List Work Orders
      description: Retrieve a list of work orders in VKS. Supports filtering by status, date range, and assignment. Returns planned, in-progress, and completed work orders.
      tags:
      - Work Orders
      security:
      - ApiKeyAuth: []
      parameters:
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - planned
          - in_progress
          - completed
          - on_hold
        description: Filter by work order status
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
          default: 20
          maximum: 100
      - name: from_date
        in: query
        required: false
        schema:
          type: string
          format: date
        description: Filter work orders created on or after this date (ISO 8601)
      - name: to_date
        in: query
        required: false
        schema:
          type: string
          format: date
        description: Filter work orders created on or before this date (ISO 8601)
      responses:
        '200':
          description: List of work orders
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WorkOrder'
                  total:
                    type: integer
                  page:
                    type: integer
                  per_page:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createWorkOrder
      summary: Create Work Order
      description: Create a new work order in VKS. Typically called by an ERP or MES system to push manufacturing orders into VKS for floor execution. The work order references a guidebook and may include bill of materials, part numbers, and expected quantities.
      tags:
      - Work Orders
      security:
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkOrderRequest'
      responses:
        '201':
          description: Work order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkOrder'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/workorders/{work_order_id}:
    get:
      operationId: getWorkOrder
      summary: Get Work Order
      description: Retrieve full details for a specific work order including status, operations, and production data.
      tags:
      - Work Orders
      security:
      - ApiKeyAuth: []
      parameters:
      - name: work_order_id
        in: path
        required: true
        schema:
          type: string
        description: Unique work order identifier
      responses:
        '200':
          description: Work order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkOrder'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateWorkOrder
      summary: Update Work Order
      description: Update a work order's status, assignment, or metadata.
      tags:
      - Work Orders
      security:
      - ApiKeyAuth: []
      parameters:
      - name: work_order_id
        in: path
        required: true
        schema:
          type: string
        description: Unique work order identifier
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWorkOrderRequest'
      responses:
        '200':
          description: Work order updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkOrder'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    BadRequest:
      description: Bad request — invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized — invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    CreateWorkOrderRequest:
      type: object
      required:
      - work_order_number
      - guidebook_id
      description: Request body to create a new work order.
      properties:
        work_order_number:
          type: string
          description: External work order number from ERP or MES.
        guidebook_id:
          type: string
          description: VKS guidebook ID containing the work instructions.
        part_number:
          type: string
          description: Part number to be manufactured.
        expected_quantity:
          type: integer
          description: Expected production quantity.
        assigned_worker:
          type: string
          description: Worker assignment.
        metadata:
          type: object
          description: Additional ERP/MES metadata fields.
          additionalProperties: true
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
    WorkOrder:
      type: object
      description: A VKS work order representing a manufacturing task assigned to a guidebook.
      properties:
        id:
          type: string
          description: Unique work order identifier.
        work_order_number:
          type: string
          description: Human-readable work order number (e.g. from ERP).
          example: WO-2026-001234
        guidebook_id:
          type: string
          description: ID of the associated VKS guidebook (work instructions).
        guidebook_name:
          type: string
          description: Name of the associated guidebook.
        status:
          type: string
          enum:
          - planned
          - in_progress
          - completed
          - on_hold
          description: Current work order status.
        part_number:
          type: string
          description: Part number being manufactured.
          example: PN-12345
        expected_quantity:
          type: integer
          description: Expected number of units to produce.
        actual_quantity:
          type: integer
          description: Actual units produced.
        assigned_worker:
          type: string
          description: Worker ID or name assigned to the work order.
        started_at:
          type: string
          format: date-time
          description: When work on the order began.
        completed_at:
          type: string
          format: date-time
          description: When the work order was completed.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    UpdateWorkOrderRequest:
      type: object
      description: Request body to update a work order.
      properties:
        status:
          type: string
          enum:
          - planned
          - in_progress
          - completed
          - on_hold
        assigned_worker:
          type: string
        expected_quantity:
          type: integer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'VKS API key. Include as ''Authorization: Bearer {api_key}'' or as configured in your VKS instance.'
externalDocs:
  description: VKS API Documentation
  url: https://help.vksapp.com/Content/VKS_Features/API/APIInfo.htm