Windmill script API

openapi: 3.0.3
info:
  version: 1.694.0
  title: Windmill admin script 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: script
paths:
  /scripts/hub/get/{path}:
    get:
      summary: Get Hub Script Content by Path
      operationId: getHubScriptContentByPath
      tags:
      - script
      parameters:
      - $ref: '#/components/parameters/ScriptPath'
      responses:
        '200':
          description: script details
          content:
            text/plain:
              schema:
                type: string
  /scripts/hub/get_full/{path}:
    get:
      summary: Get Full Hub Script by Path
      operationId: getHubScriptByPath
      tags:
      - script
      parameters:
      - $ref: '#/components/parameters/ScriptPath'
      responses:
        '200':
          description: script details
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: string
                  lockfile:
                    type: string
                  schema: {}
                  language:
                    type: string
                  summary:
                    type: string
                required:
                - content
                - language
  /scripts/hub/pick/{path}:
    get:
      summary: Record Hub Script Pick
      operationId: pickHubScriptByPath
      tags:
      - script
      parameters:
      - $ref: '#/components/parameters/ScriptPath'
      responses:
        '200':
          description: script pick recorded
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                required:
                - success
  /scripts/hub/top:
    get:
      summary: Get Top Hub Scripts
      operationId: getTopHubScripts
      tags:
      - script
      parameters:
      - name: limit
        description: query limit
        in: query
        required: false
        schema:
          type: number
      - name: app
        description: query scripts app
        in: query
        required: false
        schema:
          type: string
      - name: kind
        description: query scripts kind
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: hub scripts list
          content:
            application/json:
              schema:
                type: object
                properties:
                  asks:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: number
                        ask_id:
                          type: number
                        summary:
                          type: string
                        app:
                          type: string
                        version_id:
                          type: number
                        kind:
                          $ref: '#/components/schemas/HubScriptKind'
                        votes:
                          type: number
                        views:
                          type: number
                      required:
                      - id
                      - ask_id
                      - summary
                      - app
                      - version_id
                      - kind
                      - views
                      - votes
  /embeddings/query_hub_scripts:
    get:
      summary: Query Hub Scripts by Similarity
      operationId: queryHubScripts
      tags:
      - script
      parameters:
      - name: text
        description: query text
        in: query
        required: true
        schema:
          type: string
      - name: kind
        description: query scripts kind
        in: query
        required: false
        schema:
          type: string
      - name: limit
        description: query limit
        in: query
        required: false
        schema:
          type: number
      - name: app
        description: query scripts app
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: script details
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    ask_id:
                      type: number
                    id:
                      type: number
                    version_id:
                      type: number
                    summary:
                      type: string
                    app:
                      type: string
                    kind:
                      $ref: '#/components/schemas/HubScriptKind'
                    score:
                      type: number
                  required:
                  - ask_id
                  - id
                  - version_id
                  - summary
                  - app
                  - kind
                  - score
  /w/{workspace}/scripts/list_search:
    get:
      summary: List Scripts for Search
      operationId: listSearchScript
      tags:
      - script
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      responses:
        '200':
          description: script list
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    path:
                      type: string
                    content:
                      type: string
                  required:
                  - path
                  - content
  /w/{workspace}/scripts/list:
    get:
      summary: List All Scripts
      operationId: listScripts
      x-mcp-tool: true
      tags:
      - script
      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: first_parent_hash
        description: mask to filter scripts whom first direct parent has exact hash
        in: query
        schema:
          type: string
      - name: last_parent_hash
        description: "mask to filter scripts whom last parent in the chain has exact hash.\nBeware that each script stores only a limited number of parents. Hence\nthe last parent hash for a script is not necessarily its top-most parent.\nTo find the top-most parent you will have to jump from last to last hash\n until finding the parent\n"
        in: query
        schema:
          type: string
      - name: parent_hash
        description: 'is the hash present in the array of stored parent hashes for this script.

          The same warning applies than for last_parent_hash. A script only store a

          limited number of direct parent

          '
        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

          ed.

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

          include scripts without an exported main function

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

          include scripts that have no deployed version

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

          if true show only the templates

          if false show only the non templates

          if not defined, show all regardless of if the script is a template

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

          script kinds to filter, split by comma

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

          show only the starred items

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

          include deployment message

          '
        in: query
        schema:
          type: boolean
      - name: languages
        in: query
        description: 'Filter to only include scripts written in the given languages.

          Accepts multiple values as a comma-separated list.

          '
        schema:
          type: string
      - 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 scripts with dedicated_worker enabled.

          If false, show only scripts with dedicated_worker disabled.

          '
        schema:
          type: boolean
      - name: label
        in: query
        required: false
        schema:
          type: string
        description: Filter by label
      responses:
        '200':
          description: All scripts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Script'
  /w/{workspace}/scripts/list_paths:
    get:
      summary: List All Scripts Paths
      operationId: listScriptPaths
      tags:
      - script
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      responses:
        '200':
          description: list of script paths
          content:
            text/plain:
              schema:
                type: array
                items:
                  type: string
  /w/{workspace}/scripts/create:
    post:
      summary: Create Script
      description: 'Creates a new script when the path does not already exist.

        Creates a new version of an existing script when called with the same path and the current `parent_hash`.

        '
      operationId: createScript
      x-mcp-tool: true
      x-mcp-instructions: To create a script, specify the path (e.g., 'f/my_folder/my_script'), the content (source code), and the language. For TypeScript, use 'bun' unless deno-specific APIs are needed.
      x-mcp-tool-include-fields:
      - path
      - content
      - language
      - summary
      - description
      - kind
      - tag
      - deployment_message
      tags:
      - script
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      requestBody:
        description: Partially filled script
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewScript'
      responses:
        '201':
          description: script created
          content:
            text/plain:
              schema:
                type: string
  /w/{workspace}/scripts/toggle_workspace_error_handler/p/{path}:
    post:
      summary: Toggle ON and OFF the Workspace Error Handler for a Given Script
      operationId: toggleWorkspaceErrorHandlerForScript
      tags:
      - script
      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}/scripts/archive/p/{path}:
    post:
      summary: Archive Script by Path
      operationId: archiveScriptByPath
      tags:
      - script
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/ScriptPath'
      responses:
        '200':
          description: script archived
          content:
            text/plain:
              schema:
                type: string
  /w/{workspace}/scripts/archive/h/{hash}:
    post:
      summary: Archive Script by Hash
      operationId: archiveScriptByHash
      tags:
      - script
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/ScriptHash'
      responses:
        '200':
          description: script details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Script'
  /w/{workspace}/scripts/delete/h/{hash}:
    post:
      summary: Delete Script by Hash (erase Content but Keep Hash, Require Admin)
      operationId: deleteScriptByHash
      x-mcp-tool: true
      tags:
      - script
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/ScriptHash'
      responses:
        '200':
          description: script details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Script'
  /w/{workspace}/scripts/delete/p/{path}:
    post:
      summary: Delete Script at a Given Path (require Admin)
      operationId: deleteScriptByPath
      x-mcp-tool: true
      tags:
      - script
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/ScriptPath'
      - name: keep_captures
        description: keep captures
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: script path
          content:
            application/json:
              schema:
                type: string
  /w/{workspace}/scripts/delete_bulk:
    delete:
      summary: Delete Scripts in Bulk
      operationId: deleteScriptsBulk
      tags:
      - script
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      requestBody:
        description: paths to delete
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                paths:
                  type: array
                  items:
                    type: string
              required:
              - paths
      responses:
        '200':
          description: deleted paths
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  /w/{workspace}/scripts/get/p/{path}:
    get:
      summary: Get Script by Path
      operationId: getScriptByPath
      x-mcp-tool: true
      tags:
      - script
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/ScriptPath'
      - name: with_starred_info
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: script details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Script'
  /w/{workspace}/scripts/get_triggers_count/{path}:
    get:
      summary: Get Triggers Count of Script
      operationId: getTriggersCountOfScript
      tags:
      - script
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/ScriptPath'
      responses:
        '200':
          description: triggers count
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggersCount'
  /w/{workspace}/scripts/list_tokens/{path}:
    get:
      summary: Get Tokens with Script Scope
      operationId: listTokensOfScript
      tags:
      - script
      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}/scripts/get/draft/{path}:
    get:
      summary: Get Script by Path with Draft
      operationId: getScriptByPathWithDraft
      tags:
      - script
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/ScriptPath'
      responses:
        '200':
          description: script details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewScriptWithDraft'
  /w/{workspace}/scripts/history/p/{path}:
    get:
      summary: Get History of a Script by Path
      operationId: getScriptHistoryByPath
      tags:
      - script
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/ScriptPath'
      responses:
        '200':
          description: script history
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ScriptHistory'
  /w/{workspace}/scripts/list_paths_from_workspace_runnable/{path}:
    get:
      summary: List Script Paths Using Provided Script as a Relative Import
      operationId: listScriptPathsFromWorkspaceRunnable
      tags:
      - script
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/ScriptPath'
      responses:
        '200':
          description: list of script paths
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  /w/{workspace}/scripts/get_latest_version/{path}:
    get:
      summary: Get Scripts's Latest Version (hash)
      operationId: getScriptLatestVersion
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/ScriptPath'
      tags:
      - script
      responses:
        '200':
          description: Script version/hash
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScriptHistory'
  /w/{workspace}/scripts/history_update/h/{hash}/p/{path}:
    post:
      summary: Update History of a Script
      operationId: updateScriptHistory
      tags:
      - script
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/ScriptHash'
      - $ref: '#/components/parameters/ScriptPath'
      requestBody:
        description: Script deployment message
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                deployment_msg:
                  type: string
      responses:
        '200':
          description: success
          content:
            text/plain:
              schema:
                type: string
  /w/{workspace}/scripts/list_dedicated_with_deps:
    get:
      summary: List Dedicated Worker Scripts with Workspace Dependency Annotations
      operationId: listDedicatedWithDeps
      tags:
      - script
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      responses:
        '200':
          description: list of dedicated scripts with their workspace dependency names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    path:
                      type: string
                    language:
                      type: string
                      enum:
                      - python3
                      - deno
                      - go
                      - bash
                      - powershell
                      - postgresql
                      - mysql
                      - bigquery
                      - snowflake
                      - mssql
                      - graphql
                      - nativets
                      - bun
                      - bunnative
                      - php
                      - rust
                      - ansible
                      - csharp
                      - oracledb
                      - duckdb
                      - java
                      - ruby
                    workspace_dep_names:
                      type: array
                      items:
                        type: string
                  required:
                  - path
                  - language
                  - workspace_dep_names
  /w/{workspace}/scripts/raw/p/{path}:
    get:
      summary: Raw Script by Path
      operationId: rawScriptByPath
      tags:
      - script
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/ScriptPath'
      responses:
        '200':
          description: script content
          content:
            text/plain:
              schema:
                type: string
  /scripts_u/tokened_raw/{workspace}/{token}/{path}:
    get:
      summary: raw script by path with a token (mostly used by lsp to be used with import maps to resolve scripts)
      operationId: rawScriptByPathTokened
      tags:
      - script
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/Token'
      - $ref: '#/components/parameters/ScriptPath'
      responses:
        '200':
          description: script content
          content:
            text/plain:
              schema:
                type: string
  /w/{workspace}/scripts/exists/p/{path}:
    get:
      summary: Exists Script by Path
      operationId: existsScriptByPath
      tags:
      - script
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/ScriptPath'
      responses:
        '200':
          description: does it exists
          content:
            application/json:
              schema:
                type: boolean
  /w/{workspace}/scripts/get/h/{hash}:
    get:
      summary: Get Script by Hash
      operationId: getScriptByHash
      tags:
      - script
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/ScriptHash'
      - name: with_starred_info
        in: query
        schema:
          type: boolean
      - name: authed
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: script details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Script'
  /w/{workspace}/scripts/raw/h/{path}:
    get:
      summary: Raw Script by Hash
      operationId: rawScriptByHash
      tags:
      - script
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/ScriptPath'
      responses:
        '200':
          description: script content
          content:
            text/plain:
              schema:
                type: string
  /w/{workspace}/scripts/deployment_status/h/{hash}:
    get:
      summary: Get Script Deployment Status
      operationId: getScriptDeploymentStatus
      tags:
      - script
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/ScriptHash'
      responses:
        '200':
          description: script details
          content:
            application/json:
              schema:
                type: object
                properties:
                  lock:
                    type: string
                  lock_error_logs:
                    type: string
                  job_id:
                    type: string
                    format: uuid
  /w/{workspace}/scripts/ci_test_results/{kind}/{path}:
    get:
      summary: Get CI Test Results for a Script, Flow, or Resource
      operationId: getCiTestResults
      tags:
      - script
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - name: kind
        in: path
        required: true
        schema:
          type: string
          enum:
          - script
          - flow
          - resource
      - name: path
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: CI test results
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CiTestResult'
  /w/{workspace}/scripts/ci_test_results_batch:
    post:
      summary: Get CI Test Results for Multiple Items
      operationId: getCiTestResultsBatch
      tags:
      - script
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - items
              properties:
                items:
                  type: array
                  items:
                    type: object
                    required:
                    - path
                    - kind
                    properties:
                      path:
                        type: string
                      kind:
                        type: string
                        enum:
                        - script
                        - flow
                        - resource
      responses:
        '200':
          description: CI test results by item key
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: array
                  items:
                    $ref: '#/components/schemas/CiTestResult'
  /w/{workspace}/scripts/raw_temp/store:
    post:
      summary: Store Raw Script Content Temporarily for CLI Lock Generation
      operationId: storeRawScriptTemp
      tags:
      - script
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      requestBody:
        description: script content to store
        required: true
        content:
          application/json:
            schema:
              type: string
      responses:
        '200':
          description: hash of stored content
          content:
            application/json:
              schema:
                type: string
  /w/{workspace}/scripts/raw_temp/diff:
    post:
      summary: Diff Local Script Hashes Against Deployed Versions
      operationId: diffRawScriptsWithDeployed
      tags:
      - script
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      requestBody:
        description: scripts and workspace deps to diff against deployed versions
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - scripts
              properties:
                scripts:
                  description: map of script path to SHA256 content hash
                  type: object
                  additionalProperties:
                    type: string
                workspace_deps:
                  description: workspace dependencies to diff
                  type: array
                  items:
                    type: object
                    required:
                    - path
                    - language
                    - hash
                    properties:
                      path:
                        description: CLI path (e.g. dependencies/package.json)
                        type: string
                      language:
                        $ref: '#/components/schemas/ScriptLang'
                      name:
                        description: named workspace dependency (null for default)
                        type: string
                      hash:
                        description: SHA256 content hash
                        type: string
      responses:
        '200':
          description: list of paths that differ from deployed versions
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
components:
  parameters:
    Token:
      name: token
      in: path
      required: true
      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
    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
    WorkspaceId:
      name: workspace
      in: path
      required: true
      schema:
        type: string
    ScriptPath:
      name: path
      in: path
      required: true
      schema:
        type: string
    OrderDesc:
      name: order_desc
      description: order by desc order (default true)
      in: query
      schema:
        type: boolean
    ScriptHash:
      name: hash
      in: path
      required: true
      schema:
        type: string
  schemas:
    ScriptHistory:
      type: object
      properties:
        script_hash:
          type: string
        deployment_msg:
          type: string
      required:
      - script_hash
    Script:
      type: object
      properties:
        workspace_id:
          type: string
        hash:
          type: string
        path:
          type: string
        parent_hashes:
          type: array
          description: 'The first element is the direct parent of the script, the second is the parent of the first, etc

            '
          items:
            type: string
        summary:
          type: string
        description:
          type: string
        content:
          type: string
        created_by:
          type: string
        created_at:
          type: string
          format: date-time
        archived:
          type: boolean
        schema:
          type: object
        deleted:
          type: boolean
        is_template:
          type: boolean
        extra_perms:
          type: object
          additionalProperties:
            type: boolean
        lock:
          type: string
        lock_error_logs:
          type: string
        language:
          $ref: '#/components/schemas/ScriptLang'
        kind:
          type: string
          enum:
          - script
          - failure
          - trigger
          - command
          - approval
          - preprocessor
        starred:
          type: boolean
        tag:
          type: string
        has_draft:
          type: boolean
        draft_only:
          type: boolean
        envs:
          type: array
          items:
            type: string
        concurrent_limit:
          type: integer
        concurrency_time_window_s:
          type: integer
        concurrency_key:
          type: string
        debounce_key:
          type: string
        debounce_delay_s:
          

# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/windmill/refs/heads/main/openapi/windmill-script-api-openapi.yml