chore: Update Public API schema (#3951)

Co-authored-by: tomi <10324676+tomi@users.noreply.github.com>
Co-authored-by: Kartik Balasubramanian <22399046+HumanistSerif@users.noreply.github.com>

docs/api/v1/openapi.yml

@@ -594,7 +594,7 @@ paths:
       tags:
         - Workflow
       summary: Update a workflow
-      description: Update a workflow.
+      description: Update a workflow. If the workflow is active, the updated version will be automatically reactivated.
       parameters:
         - $ref: '#/components/parameters/workflowId'
       requestBody:
@@ -617,6 +617,34 @@ paths:
           $ref: '#/components/responses/unauthorized'
         '404':
           $ref: '#/components/responses/notFound'
+  /workflows/{id}/{versionId}:
+    get:
+      x-eov-operation-id: getWorkflowVersion
+      x-eov-operation-handler: v1/handlers/workflows/workflows.handler
+      tags:
+        - Workflow
+      summary: Retrieves a specific version of a workflow
+      description: Retrieves a specific version of a workflow from workflow history.
+      parameters:
+        - $ref: '#/components/parameters/workflowId'
+        - name: versionId
+          in: path
+          required: true
+          description: The version ID to retrieve
+          schema:
+            type: string
+          example: abc123-def456-ghi789
+      responses:
+        '200':
+          description: Operation successful.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/workflowVersion'
+        '401':
+          $ref: '#/components/responses/unauthorized'
+        '404':
+          $ref: '#/components/responses/notFound'
   /workflows/{id}/activate:
     post:
       x-eov-operation-id: activateWorkflow
@@ -627,6 +655,23 @@ paths:
       description: Active a workflow.
       parameters:
         - $ref: '#/components/parameters/workflowId'
+      requestBody:
+        description: Optional parameters for workflow activation.
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                versionId:
+                  type: string
+                  description: The specific version ID to activate. If not provided, activates the latest version.
+                name:
+                  type: string
+                  description: Optional name for the workflow version during activation.
+                description:
+                  type: string
+                  description: Optional description for the workflow version during activation.
+        required: false
       responses:
         '200':
           description: Workflow object
@@ -634,6 +679,8 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/workflow'
+        '400':
+          $ref: '#/components/responses/badRequest'
         '401':
           $ref: '#/components/responses/unauthorized'
         '404':
@@ -1774,6 +1821,66 @@ components:
           description: Paginate through workflows by setting the cursor parameter to a nextCursor attribute returned by a previous request. Default value fetches the first "page" of the collection.
           nullable: true
           example: MTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDA
+    workflowVersion:
+      type: object
+      additionalProperties: false
+      required:
+        - versionId
+        - workflowId
+        - nodes
+        - connections
+        - authors
+      properties:
+        versionId:
+          type: string
+          readOnly: true
+          description: The version ID of this workflow snapshot
+          example: abc123-def456
+        workflowId:
+          type: string
+          readOnly: true
+          description: The workflow ID this version belongs to
+          example: 2tUt1wbLX592XDdX
+        nodes:
+          type: array
+          items:
+            $ref: '#/components/schemas/node'
+          description: Nodes as they were in this version
+          readOnly: true
+        connections:
+          type: object
+          example:
+            Jira:
+              main:
+                - - node: Jira
+                    type: main
+                    index: 0
+          description: Connections as they were in this version
+          readOnly: true
+        authors:
+          type: string
+          readOnly: true
+          description: Authors who created this version
+          example: John Doe
+        name:
+          type: string
+          nullable: true
+          description: Workflow name at this version
+          example: Workflow 1
+        description:
+          type: string
+          nullable: true
+          description: Workflow description at this version
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: When this version was created
+        updatedAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: When this version was last updated
     workflowTags:
       type: array
       items: