openapi: 3.1.0
info:
  title: Workflow Management API
  description: |
    API for managing workflows.

    The API described in the [workflows.yaml](https://developers.hivelight.com/schemas/workflows.yaml) file is designed to read Workflows (Roadmaps and Task Lists) available to use.

  version: 1.1.0

servers:
  - url: https://api.hivelight.com
    description: Global endpoint
  - url: https://au.api.hivelight.com
    description: Australian endpoint

paths:
  /workflows:
    get:
      summary: Get workflows
      description: Fetch a list of workflows for the given workspace and organization.
      operationId: getWorkflows
      parameters:
        - name: from
          in: query
          description: The starting point for pagination (offset).
          required: false
          schema:
            type: integer
        - name: size
          in: query
          description: The number of workflows to return per request.
          required: false
          schema:
            type: integer
        - name: type
          in: query
          description: Filter workflows by type, ROADMAP (default) or TASK_LIST
          required: false
          schema:
            type: string
      responses:
        "200":
          description: A list of workflows
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Workflow"
                  meta:
                    type: object
                    properties:
                      total:
                        description: Total number of workflows
                        type: integer
                        example: 100
                      showing:
                        description: Total number of workflows returned
                        type: integer
                        example: 10
                      from:
                        description: Current starting index for pagination
                        type: integer
                        example: 0
        "500":
          $ref: "#/components/responses/InternalServerError"

  /workflows/{workflowId}:
    get:
      summary: Get workflow
      description: Fetch details of a specific workflow by ID, including its milestones.
      operationId: getWorkflow
      parameters:
        - $ref: "#/components/parameters/workflowId"
      responses:
        "200":
          description: A single workflow with milestones
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/Workflow"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /workflows/{workflowId}/milestone/{milestoneId}:
    get:
      summary: Get workflow milestone
      description: Fetch a specific milestone within a workflow, including all of its template tasks.
      operationId: getWorkflowMilestone
      parameters:
        - $ref: "#/components/parameters/workflowId"
        - name: milestoneId
          in: path
          required: true
          description: The ID of the milestone to retrieve.
          schema:
            type: string
      responses:
        "200":
          description: A workflow milestone with its tasks
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowMilestone"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

components:
  parameters:
    workflowId:
      name: workflowId
      in: path
      required: true
      description: The ID of the workflow.
      schema:
        type: string

  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: "Resource not found"
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: "Forbidden"
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: "Internal Server Error"

  schemas:
    Workflow:
      type: object
      properties:
        type:
          type: string
          example: workflow
        id:
          type: string
          example: UsFdl1Ykuz7NxBy0U5Q3q
        attributes:
          $ref: "#/components/schemas/WorkflowAttributes"

    WorkflowAttributes:
      type: object
      properties:
        name:
          type: string
          description: Name of the workflow
          example: POST NOCD WORKFLOW
        description:
          type: string
          description: HTML description of the workflow
          example: "<p>The Workplace Injury Roadmap is used to assist clients in the Common Law phase.</p>"
        type:
          type: string
          description: Workflow type
          enum: [ROADMAP, TASK_LIST]
          example: ROADMAP
        types:
          type: array
          description: A list of matter type identifiers this workflow applies to
          items:
            type: string
        jurisdictions:
          type: array
          description: A list of jurisdictions this workflow is associated with
          items:
            type: string
          example: ["AU", "AU-QLD"]
        audience:
          type: string
          description: Visibility scope of the workflow
          enum: [PUBLIC, ORGANIZATION, WORKSPACE]
          example: WORKSPACE
        duration:
          type: integer
          description: Total duration of the workflow in milliseconds
          example: 28512000000
        createdDate:
          type: integer
          description: Unix timestamp (ms) when the workflow was created
          example: 1772415092623
        milestones:
          type: array
          description: Milestones defined in this workflow
          items:
            $ref: "#/components/schemas/WorkflowMilestoneSummary"

    WorkflowMilestoneSummary:
      type: object
      description: A summary of a workflow milestone as embedded in a workflow response
      properties:
        milestoneId:
          type: string
          example: Af3-y814AI
        name:
          type: string
          example: NOCD
        description:
          type: string
          description: HTML description of the milestone
          example: "<p>How we progress our client's claim</p>"
        taskCount:
          type: integer
          description: Number of tasks in this milestone
          example: 8
        dueDate:
          $ref: "#/components/schemas/RelativeDate"
        targetDate:
          $ref: "#/components/schemas/RelativeDate"
        workspaceId:
          type: string
          example: Cs8dD1-8CubzojjqvauZH
        lastModifiedBy:
          type: string
          example: Co0J-Nn3JpjjdD79Dvz-X
        lastModifiedDate:
          type: integer
          description: Unix timestamp (ms) of last modification
          example: 1772417202723
        lastModifiedFrom:
          type: string
          example: "20.5.11.95, 130.176.212.77"

    WorkflowMilestone:
      type: object
      description: A workflow milestone with all its template tasks
      properties:
        milestoneId:
          type: string
          example: Af3-y814AI
        name:
          type: string
          example: NOCD
        description:
          type: string
          description: HTML description of the milestone
          example: "<p>How we progress our client's claim</p>"
        taskCount:
          type: integer
          description: Number of tasks in this milestone
          example: 8
        dueDate:
          $ref: "#/components/schemas/RelativeDate"
        targetDate:
          $ref: "#/components/schemas/RelativeDate"
        workspaceId:
          type: string
          example: Cs8dD1-8CubzojjqvauZH
        lastModifiedBy:
          type: string
          example: Co0J-Nn3JpjjdD79Dvz-X
        lastModifiedDate:
          type: integer
          description: Unix timestamp (ms) of last modification
          example: 1772417202723
        tasks:
          type: array
          description: Template tasks within this milestone, sorted by rank
          items:
            $ref: "#/components/schemas/WorkflowTask"

    WorkflowTask:
      type: object
      description: A template task within a workflow milestone
      properties:
        taskId:
          type: string
          example: x9fSVyPKCoOsYll0rp5PJ
        name:
          type: string
          example: Send letter of engagement
        description:
          type: string
          description: HTML description of the task
          example: "<p>Send the standard letter of engagement to the client.</p>"
        dueDate:
          $ref: "#/components/schemas/RelativeDate"
        rank:
          type: string
          description: Lexicographic rank used to order tasks within a milestone
          example: dsuiz
        assigneeRole:
          type: string
          description: Default role to assign this task to
          enum: [OWNER, LEAD, VIEWER]
          example: OWNER
        reviewerRole:
          type: string
          description: Default role to assign as reviewer
          enum: [OWNER, LEAD, VIEWER]
          example: LEAD
        relationships:
          type: array
          description: Dependencies between tasks
          items:
            $ref: "#/components/schemas/TaskRelationship"

    TaskRelationship:
      type: object
      properties:
        id:
          type: string
          description: Unique ID of the relationship
          example: L9WltkrXts96aQA7sHw5W
        type:
          type: string
          description: The relationship type
          enum: [REQUIRES, REQUIRED_BY]
          example: REQUIRES
        taskId:
          type: string
          description: The related task ID
          example: 8EV6ZdyB3M3Rlm4R3a_cL

    RelativeDate:
      type: object
      description: A date expressed relative to a known anchor point
      properties:
        plus:
          type: integer
          description: Days to add to the anchor date (used when expressing due dates)
          example: 300
        minus:
          type: integer
          description: Days to subtract from the anchor date (used when expressing target dates)
          example: 0
        relativeTo:
          type: string
          description: The anchor point this date is relative to
          enum:
            - ROADMAP_START_DATE
            - MILESTONE_DUE_DATE
            - MILESTONE_TARGET_DATE
          example: ROADMAP_START_DATE