Windmill flow API

openapi: 3.0.3
info:
  version: 1.694.0
  title: Windmill admin flow API
  contact:
    name: Windmill Team
    email: contact@windmill.dev
    url: https://windmill.dev
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  x-logo:
    url: https://windmill.dev/img/windmill.svg
servers:
- url: /api
security:
- bearerAuth: []
- cookieAuth: []
tags:
- name: flow
paths:
  /flows/hub/list:
    get:
      summary: List All Hub Flows
      operationId: listHubFlows
      tags:
      - flow
      responses:
        '200':
          description: hub flows list
          content:
            application/json:
              schema:
                type: object
                properties:
                  flows:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: number
                        flow_id:
                          type: number
                        summary:
                          type: string
                        apps:
                          type: array
                          items:
                            type: string
                        approved:
                          type: boolean
                        votes:
                          type: number
                      required:
                      - id
                      - flow_id
                      - summary
                      - apps
                      - approved
                      - votes
  /flows/hub/get/{id}:
    get:
      summary: Get Hub Flow by Id
      operationId: getHubFlowById
      tags:
      - flow
      parameters:
      - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: flow
          content:
            application/json:
              schema:
                type: object
                properties:
                  flow:
                    $ref: ../../openflow.openapi.yaml#/components/schemas/OpenFlow
  /w/{workspace}/flows/list_paths:
    get:
      summary: List All Flow Paths
      operationId: listFlowPaths
      tags:
      - flow
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      responses:
        '200':
          description: list of flow paths
          content:
            text/plain:
              schema:
                type: array
                items:
                  type: string
  /w/{workspace}/flows/list_search:
    get:
      summary: List Flows for Search
      operationId: listSearchFlow
      tags:
      - flow
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      responses:
        '200':
          description: flow list
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    path:
                      type: string
                    value: {}
                  required:
                  - path
                  - value
  /w/{workspace}/flows/list:
    get:
      summary: List All Flows
      operationId: listFlows
      x-mcp-tool: true
      tags:
      - flow
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      - $ref: '#/components/parameters/OrderDesc'
      - $ref: '#/components/parameters/CreatedBy'
      - name: path_start
        description: mask to filter matching starting path
        in: query
        schema:
          type: string
      - name: path_exact
        description: mask to filter exact matching path
        in: query
        schema:
          type: string
      - name: show_archived
        description: '(default false)

          show only the archived files.

          when multiple archived hash share the same path, only the ones with the latest create_at

          are displayed.

          '
        in: query
        schema:
          type: boolean
      - name: starred_only
        description: '(default false)

          show only the starred items

          '
        in: query
        schema:
          type: boolean
      - name: include_draft_only
        description: '(default false)

          include items that have no deployed version

          '
        in: query
        schema:
          type: boolean
      - name: with_deployment_msg
        description: '(default false)

          include deployment message

          '
        in: query
        schema:
          type: boolean
      - name: without_description
        in: query
        description: '(default false)

          If true, the description field will be omitted from the response.

          '
        schema:
          type: boolean
      - name: dedicated_worker
        in: query
        description: '(default regardless)

          If true, show only flows with dedicated_worker enabled.

          If false, show only flows with dedicated_worker disabled.

          '
        schema:
          type: boolean
      - name: label
        in: query
        required: false
        schema:
          type: string
        description: Filter by label
      responses:
        '200':
          description: All flow
          content:
            application/json:
              schema:
                type: array
                items:
                  allOf:
                  - $ref: '#/components/schemas/Flow'
                  - type: object
                    properties:
                      has_draft:
                        type: boolean
                      draft_only:
                        type: boolean
  /w/{workspace}/flows/history/p/{path}:
    get:
      summary: Get Flow History by Path
      operationId: getFlowHistory
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/ScriptPath'
      tags:
      - flow
      responses:
        '200':
          description: Flow history
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FlowVersion'
  /w/{workspace}/flows/get_latest_version/{path}:
    get:
      summary: Get Flow's Latest Version
      operationId: getFlowLatestVersion
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/ScriptPath'
      tags:
      - flow
      responses:
        '200':
          description: Flow version
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowVersion'
  /w/{workspace}/flows/list_paths_from_workspace_runnable/{runnable_kind}/{path}:
    get:
      summary: List Flow Paths from Workspace Runnable
      operationId: listFlowPathsFromWorkspaceRunnable
      tags:
      - flow
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/RunnableKind'
      - $ref: '#/components/parameters/ScriptPath'
      - name: match_path_start
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: list of flow paths
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  /w/{workspace}/flows/get/v/{version}:
    get:
      summary: Get Flow Version
      operationId: getFlowVersion
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - name: version
        in: path
        required: true
        schema:
          type: number
      tags:
      - flow
      responses:
        '200':
          description: flow details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Flow'
  /w/{workspace}/flows/history_update/v/{version}:
    post:
      summary: Update Flow History
      operationId: updateFlowHistory
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - name: version
        in: path
        required: true
        schema:
          type: number
      requestBody:
        description: Flow deployment message
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                deployment_msg:
                  type: string
              required:
              - deployment_msg
      tags:
      - flow
      responses:
        '200':
          description: success
          content:
            text/plain:
              schema:
                type: string
  /w/{workspace}/flows/get/{path}:
    get:
      summary: Get Flow by Path
      operationId: getFlowByPath
      x-mcp-tool: true
      tags:
      - flow
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/ScriptPath'
      - name: with_starred_info
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: flow details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Flow'
  /w/{workspace}/flows/deployment_status/p/{path}:
    get:
      summary: Get Flow Deployment Status
      operationId: getFlowDeploymentStatus
      tags:
      - flow
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/ScriptPath'
      responses:
        '200':
          description: flow status
          content:
            application/json:
              schema:
                type: object
                properties:
                  lock_error_logs:
                    type: string
                  job_id:
                    type: string
                    format: uuid
  /w/{workspace}/flows/get_triggers_count/{path}:
    get:
      summary: Get Triggers Count of Flow
      operationId: getTriggersCountOfFlow
      tags:
      - flow
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/ScriptPath'
      responses:
        '200':
          description: triggers count
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggersCount'
  /w/{workspace}/flows/list_tokens/{path}:
    get:
      summary: Get Tokens with Flow Scope
      operationId: listTokensOfFlow
      tags:
      - flow
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/ScriptPath'
      responses:
        '200':
          description: tokens list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TruncatedToken'
  /w/{workspace}/flows/toggle_workspace_error_handler/{path}:
    post:
      summary: Toggle ON and OFF the Workspace Error Handler for a Given Flow
      operationId: toggleWorkspaceErrorHandlerForFlow
      tags:
      - flow
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/ScriptPath'
      requestBody:
        description: Workspace error handler enabled
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                muted:
                  type: boolean
      responses:
        '200':
          description: error handler toggled
          content:
            text/plain:
              schema:
                type: string
  /w/{workspace}/flows/get/draft/{path}:
    get:
      summary: Get Flow by Path with Draft
      operationId: getFlowByPathWithDraft
      tags:
      - flow
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/ScriptPath'
      responses:
        '200':
          description: flow details with draft
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Flow'
                - type: object
                  properties:
                    draft:
                      $ref: '#/components/schemas/Flow'
  /w/{workspace}/flows/exists/{path}:
    get:
      summary: Exists Flow by Path
      operationId: existsFlowByPath
      tags:
      - flow
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/ScriptPath'
      responses:
        '200':
          description: flow details
          content:
            application/json:
              schema:
                type: boolean
  /w/{workspace}/flows/create:
    post:
      summary: Create Flow
      operationId: createFlow
      x-mcp-tool: true
      x-mcp-tool-include-fields:
      - path
      - summary
      - description
      - value
      - schema
      - tag
      - deployment_message
      x-mcp-tool-opaque-fields:
      - value
      - schema
      tags:
      - flow
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      requestBody:
        description: Partially filled flow
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/OpenFlowWPath'
              - type: object
                properties:
                  draft_only:
                    type: boolean
                  deployment_message:
                    type: string
      responses:
        '201':
          description: flow created
          content:
            text/plain:
              schema:
                type: string
  /w/{workspace}/flows/update/{path}:
    post:
      summary: Update Flow
      operationId: updateFlow
      x-mcp-tool: true
      x-mcp-tool-include-fields:
      - path
      - summary
      - description
      - value
      - schema
      - tag
      - deployment_message
      x-mcp-tool-opaque-fields:
      - value
      - schema
      tags:
      - flow
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/ScriptPath'
      requestBody:
        description: Partially filled flow
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/OpenFlowWPath'
              - type: object
                properties:
                  deployment_message:
                    type: string
      responses:
        '200':
          description: flow updated
          content:
            text/plain:
              schema:
                type: string
  /w/{workspace}/flows/archive/{path}:
    post:
      summary: Archive Flow by Path
      operationId: archiveFlowByPath
      tags:
      - flow
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/ScriptPath'
      requestBody:
        description: archiveFlow
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                archived:
                  type: boolean
      responses:
        '200':
          description: flow archived
          content:
            text/plain:
              schema:
                type: string
  /w/{workspace}/flows/delete/{path}:
    delete:
      summary: Delete Flow by Path
      operationId: deleteFlowByPath
      x-mcp-tool: true
      tags:
      - flow
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/ScriptPath'
      - name: keep_captures
        description: keep captures
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: flow delete
          content:
            text/plain:
              schema:
                type: string
components:
  parameters:
    WorkspaceId:
      name: workspace
      in: path
      required: true
      schema:
        type: string
    ScriptPath:
      name: path
      in: path
      required: true
      schema:
        type: string
    PathId:
      name: id
      in: path
      required: true
      schema:
        type: integer
    RunnableKind:
      name: runnable_kind
      in: path
      required: true
      schema:
        type: string
        enum:
        - script
        - flow
    CreatedBy:
      name: created_by
      description: filter by exact matching user creator. Supports comma-separated list (e.g. 'alice,bob') and negation by prefixing all values with '!' (e.g. '!alice,!bob')
      in: query
      schema:
        type: string
    PerPage:
      name: per_page
      description: number of items to return for a given page (default 30, max 100)
      in: query
      schema:
        type: integer
    Page:
      name: page
      description: which page to return (start at 1, default 1)
      in: query
      schema:
        type: integer
    OrderDesc:
      name: order_desc
      description: order by desc order (default true)
      in: query
      schema:
        type: boolean
  schemas:
    ExtraPerms:
      type: object
      additionalProperties:
        type: boolean
    Flow:
      allOf:
      - $ref: ../../openflow.openapi.yaml#/components/schemas/OpenFlow
      - $ref: '#/components/schemas/FlowMetadata'
      - type: object
        properties:
          lock_error_logs:
            type: string
          version_id:
            type: number
    FlowMetadata:
      type: object
      properties:
        workspace_id:
          type: string
        path:
          type: string
        edited_by:
          type: string
        edited_at:
          type: string
          format: date-time
        archived:
          type: boolean
        extra_perms:
          $ref: '#/components/schemas/ExtraPerms'
        starred:
          type: boolean
        draft_only:
          type: boolean
        tag:
          type: string
        ws_error_handler_muted:
          type: boolean
        priority:
          type: integer
        dedicated_worker:
          type: boolean
        timeout:
          type: number
        visible_to_runner_only:
          type: boolean
        on_behalf_of_email:
          type: string
        labels:
          type: array
          items:
            type: string
          default: []
      required:
      - path
      - edited_by
      - edited_at
      - archived
      - extra_perms
    TruncatedToken:
      type: object
      properties:
        label:
          type: string
        expiration:
          type: string
          format: date-time
        token_prefix:
          type: string
        created_at:
          type: string
          format: date-time
        last_used_at:
          type: string
          format: date-time
        scopes:
          type: array
          items:
            type: string
        email:
          type: string
        workspace_id:
          type: string
      required:
      - token_prefix
      - created_at
      - last_used_at
    TriggersCount:
      type: object
      properties:
        primary_schedule:
          type: object
          properties:
            schedule:
              type: string
        schedule_count:
          type: number
        http_routes_count:
          type: number
        webhook_count:
          type: number
        email_count:
          type: number
        default_email_count:
          type: number
        websocket_count:
          type: number
        postgres_count:
          type: number
        kafka_count:
          type: number
        nats_count:
          type: number
        mqtt_count:
          type: number
        gcp_count:
          type: number
        azure_count:
          type: number
        sqs_count:
          type: number
        nextcloud_count:
          type: number
        google_count:
          type: number
        github_count:
          type: number
    OpenFlowWPath:
      allOf:
      - $ref: ../../openflow.openapi.yaml#/components/schemas/OpenFlow
      - type: object
        properties:
          path:
            type: string
          tag:
            type: string
          ws_error_handler_muted:
            type: boolean
          priority:
            type: integer
          dedicated_worker:
            type: boolean
          timeout:
            type: number
          visible_to_runner_only:
            type: boolean
          on_behalf_of_email:
            type: string
          preserve_on_behalf_of:
            type: boolean
            description: When true and the caller is a member of the 'wm_deployers' group, preserves the original on_behalf_of_email value instead of overwriting it.
          labels:
            type: array
            items:
              type: string
        required:
        - path
    FlowVersion:
      type: object
      properties:
        id:
          type: integer
        created_at:
          type: string
          format: date-time
        deployment_msg:
          type: string
      required:
      - id
      - created_at
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    cookieAuth:
      type: apiKey
      in: cookie
      name: token
externalDocs:
  description: documentation portal
  url: https://windmill.dev