Windmill schedule API

openapi: 3.0.3
info:
  version: 1.694.0
  title: Windmill admin schedule 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: schedule
paths:
  /schedules/preview:
    post:
      summary: Preview Schedule
      operationId: previewSchedule
      tags:
      - schedule
      requestBody:
        description: schedule
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                schedule:
                  type: string
                timezone:
                  type: string
                cron_version:
                  type: string
              required:
              - schedule
              - timezone
      responses:
        '200':
          description: List of 5 estimated upcoming execution events (in UTC)
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  format: date-time
  /w/{workspace}/schedules/create:
    post:
      summary: Create Schedule
      operationId: createSchedule
      x-mcp-tool: true
      x-mcp-instructions: 'Creates a new schedule.

        The schedule should include seconds.

        You should get the schema of the script or flow before creating the schedule to correctly specify the arguments needed.

        '
      tags:
      - schedule
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      requestBody:
        description: new schedule
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewSchedule'
      responses:
        '201':
          description: schedule created
          content:
            text/plain:
              schema:
                type: string
  /w/{workspace}/schedules/update/{path}:
    post:
      summary: Update Schedule
      operationId: updateSchedule
      x-mcp-tool: true
      x-mcp-instructions: 'Updates a schedule.

        The schedule should include seconds.

        You should get the schema of the script or flow before updating the schedule to correctly specify the arguments needed.

        '
      tags:
      - schedule
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/Path'
      requestBody:
        description: updated schedule
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EditSchedule'
      responses:
        '200':
          description: schedule updated
          content:
            text/plain:
              schema:
                type: string
  /w/{workspace}/schedules/setenabled/{path}:
    post:
      summary: Set Enabled Schedule
      operationId: setScheduleEnabled
      tags:
      - schedule
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/Path'
      requestBody:
        description: updated schedule enable
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                enabled:
                  type: boolean
                force:
                  type: boolean
                  description: 'Bypass the parent-state conflict warning when enabling a schedule in a fork whose parent has the same path enabled.

                    '
              required:
              - enabled
      responses:
        '200':
          description: schedule enabled set
          content:
            text/plain:
              schema:
                type: string
  /w/{workspace}/schedules/delete/{path}:
    delete:
      summary: Delete Schedule
      operationId: deleteSchedule
      x-mcp-tool: true
      tags:
      - schedule
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/Path'
      responses:
        '200':
          description: schedule deleted
          content:
            text/plain:
              schema:
                type: string
  /w/{workspace}/schedules/get/{path}:
    get:
      summary: Get Schedule
      operationId: getSchedule
      x-mcp-tool: true
      tags:
      - schedule
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/Path'
      responses:
        '200':
          description: schedule deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schedule'
  /w/{workspace}/schedules/exists/{path}:
    get:
      summary: Does Schedule Exists
      operationId: existsSchedule
      tags:
      - schedule
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/Path'
      responses:
        '200':
          description: schedule exists
          content:
            application/json:
              schema:
                type: boolean
  /w/{workspace}/schedules/list:
    get:
      summary: List Schedules
      operationId: listSchedules
      x-mcp-tool: true
      tags:
      - schedule
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      - $ref: '#/components/parameters/ArgsFilter'
      - name: path
        description: filter by path (script path)
        in: query
        schema:
          type: string
      - name: is_flow
        description: filter schedules by whether they target a flow
        in: query
        schema:
          type: boolean
      - name: path_start
        description: filter schedules by path prefix
        in: query
        schema:
          type: string
      - name: schedule_path
        description: exact match on the schedule's path
        in: query
        schema:
          type: string
      - name: description
        description: pattern match filter for description field (case-insensitive)
        in: query
        schema:
          type: string
      - name: summary
        description: pattern match filter for summary field (case-insensitive)
        in: query
        schema:
          type: string
      - name: broad_filter
        description: broad search across multiple fields (case-insensitive substring match)
        in: query
        schema:
          type: string
      - name: label
        in: query
        required: false
        schema:
          type: string
        description: Filter by label
      responses:
        '200':
          description: schedule list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Schedule'
  /w/{workspace}/schedules/list_with_jobs:
    get:
      summary: List Schedules with Last 20 Jobs
      operationId: listSchedulesWithJobs
      tags:
      - schedule
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: schedule list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ScheduleWJobs'
  /w/{workspace}/schedules/setdefaulthandler:
    post:
      summary: Set Default Error or Recoevery Handler
      operationId: setDefaultErrorOrRecoveryHandler
      tags:
      - schedule
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      requestBody:
        description: Handler description
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                handler_type:
                  type: string
                  enum:
                  - error
                  - recovery
                  - success
                override_existing:
                  type: boolean
                path:
                  type: string
                extra_args:
                  type: object
                number_of_occurence:
                  type: integer
                number_of_occurence_exact:
                  type: boolean
                workspace_handler_muted:
                  type: boolean
              required:
              - handler_type
              - override_existing
      responses:
        '201':
          description: default error handler set
components:
  parameters:
    WorkspaceId:
      name: workspace
      in: path
      required: true
      schema:
        type: string
    Page:
      name: page
      description: which page to return (start at 1, default 1)
      in: query
      schema:
        type: integer
    Path:
      name: path
      in: path
      required: true
      schema:
        type: string
    ArgsFilter:
      name: args
      description: filter on jobs containing those args as a json subset (@> in postgres)
      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
  schemas:
    ScheduleWJobs:
      allOf:
      - $ref: '#/components/schemas/Schedule'
      - type: object
        properties:
          jobs:
            type: array
            items:
              type: object
              properties:
                id:
                  type: string
                success:
                  type: boolean
                duration_ms:
                  type: number
              required:
              - id
              - success
              - duration_ms
    ScriptArgs:
      type: object
      description: The arguments to pass to the script or flow
      additionalProperties: true
    Schedule:
      type: object
      properties:
        path:
          type: string
          description: The unique Windmill path for this schedule. Must be of the form `u/<user>/<path>` or `f/<folder>/<path>`.
        edited_by:
          type: string
          description: Username of the last person who edited this schedule
        edited_at:
          type: string
          format: date-time
          description: Timestamp of the last edit
        schedule:
          type: string
          description: Cron expression with 6 fields (seconds, minutes, hours, day of month, month, day of week). Example '0 0 12 * * *' for daily at noon
        timezone:
          type: string
          description: IANA timezone for the schedule (e.g., 'UTC', 'Europe/Paris', 'America/New_York')
        enabled:
          type: boolean
          description: Whether the schedule is currently active and will trigger jobs
        script_path:
          type: string
          description: Path to the script or flow to execute when triggered
        is_flow:
          type: boolean
          description: True if script_path points to a flow, false if it points to a script
        args:
          $ref: '#/components/schemas/ScriptArgs'
          nullable: true
        extra_perms:
          type: object
          additionalProperties:
            type: boolean
          description: Additional permissions for this schedule
        email:
          type: string
          description: Email of the user who owns this schedule, used for permissioned_as
        permissioned_as:
          type: string
          description: The user or group this schedule runs as (e.g., 'u/admin' or 'g/mygroup')
        error:
          type: string
          nullable: true
          description: Last error message if the schedule failed to trigger
        on_failure:
          type: string
          nullable: true
          description: Path to a script or flow to run when the scheduled job fails
        on_failure_times:
          type: number
          nullable: true
          description: Number of consecutive failures before the on_failure handler is triggered (default 1)
        on_failure_exact:
          type: boolean
          nullable: true
          description: If true, trigger on_failure handler only on exactly N failures, not on every failure after N
        on_failure_extra_args:
          $ref: '#/components/schemas/ScriptArgs'
          nullable: true
        on_recovery:
          type: string
          nullable: true
          description: Path to a script or flow to run when the schedule recovers after failures
        on_recovery_times:
          type: number
          nullable: true
          description: Number of consecutive successes before the on_recovery handler is triggered (default 1)
        on_recovery_extra_args:
          $ref: '#/components/schemas/ScriptArgs'
          nullable: true
        on_success:
          type: string
          nullable: true
          description: Path to a script or flow to run after each successful execution
        on_success_extra_args:
          $ref: '#/components/schemas/ScriptArgs'
          nullable: true
        ws_error_handler_muted:
          type: boolean
          description: If true, the workspace-level error handler will not be triggered for this schedule's failures
        retry:
          $ref: ../../openflow.openapi.yaml#/components/schemas/Retry
          nullable: true
        summary:
          type: string
          nullable: true
          description: Short summary describing the purpose of this schedule
        description:
          type: string
          nullable: true
          description: Detailed description of what this schedule does
        no_flow_overlap:
          type: boolean
          description: If true, skip this schedule's execution if the previous run is still in progress (prevents concurrent runs)
        tag:
          type: string
          nullable: true
          description: Worker tag to route jobs to specific worker groups
        paused_until:
          type: string
          format: date-time
          nullable: true
          description: ISO 8601 datetime until which the schedule is paused. Schedule resumes automatically after this time
        cron_version:
          type: string
          nullable: true
          description: Cron parser version. Use 'v2' for extended syntax with additional features
        dynamic_skip:
          type: string
          nullable: true
          description: Path to a script that validates scheduled datetimes. Receives scheduled_for datetime and returns boolean to skip (true) or run (false)
        labels:
          type: array
          items:
            type: string
          default: []
      required:
      - path
      - edited_by
      - edited_at
      - schedule
      - script_path
      - timezone
      - extra_perms
      - is_flow
      - enabled
      - email
      - permissioned_as
    NewSchedule:
      type: object
      properties:
        path:
          type: string
          description: The unique Windmill path for this schedule. Must be of the form `u/<user>/<path>` or `f/<folder>/<path>`.
        schedule:
          type: string
          description: Cron expression with 6 fields (seconds, minutes, hours, day of month, month, day of week). Example '0 0 12 * * *' for daily at noon
        timezone:
          type: string
          description: IANA timezone for the schedule (e.g., 'UTC', 'Europe/Paris', 'America/New_York')
        script_path:
          type: string
          description: Path to the script or flow to execute when triggered
        is_flow:
          type: boolean
          description: True if script_path points to a flow, false if it points to a script
        args:
          nullable: true
          $ref: '#/components/schemas/ScriptArgs'
        enabled:
          type: boolean
          description: Whether the schedule is currently active and will trigger jobs
        on_failure:
          type: string
          nullable: true
          description: Path to a script or flow to run when the scheduled job fails
        on_failure_times:
          type: number
          nullable: true
          description: Number of consecutive failures before the on_failure handler is triggered (default 1)
        on_failure_exact:
          type: boolean
          nullable: true
          description: If true, trigger on_failure handler only on exactly N failures, not on every failure after N
        on_failure_extra_args:
          nullable: true
          $ref: '#/components/schemas/ScriptArgs'
        on_recovery:
          type: string
          nullable: true
          description: Path to a script or flow to run when the schedule recovers after failures
        on_recovery_times:
          type: number
          nullable: true
          description: Number of consecutive successes before the on_recovery handler is triggered (default 1)
        on_recovery_extra_args:
          nullable: true
          $ref: '#/components/schemas/ScriptArgs'
        on_success:
          type: string
          nullable: true
          description: Path to a script or flow to run after each successful execution
        on_success_extra_args:
          nullable: true
          $ref: '#/components/schemas/ScriptArgs'
        ws_error_handler_muted:
          type: boolean
          description: If true, the workspace-level error handler will not be triggered for this schedule's failures
        retry:
          nullable: true
          $ref: ../../openflow.openapi.yaml#/components/schemas/Retry
        no_flow_overlap:
          type: boolean
          description: If true, skip this schedule's execution if the previous run is still in progress (prevents concurrent runs)
        summary:
          type: string
          nullable: true
          description: Short summary describing the purpose of this schedule
        description:
          type: string
          nullable: true
          description: Detailed description of what this schedule does
        tag:
          type: string
          nullable: true
          description: Worker tag to route jobs to specific worker groups
        paused_until:
          type: string
          nullable: true
          format: date-time
          description: ISO 8601 datetime until which the schedule is paused. Schedule resumes automatically after this time
        cron_version:
          type: string
          nullable: true
          description: Cron parser version. Use 'v2' for extended syntax with additional features
        dynamic_skip:
          type: string
          nullable: true
          description: Path to a script that validates scheduled datetimes. Receives scheduled_for datetime and returns boolean to skip (true) or run (false)
        permissioned_as:
          type: string
          description: The user or group this schedule runs as. Used during deployment to preserve the original schedule owner.
        preserve_permissioned_as:
          type: boolean
          description: When true and the caller is a member of the 'wm_deployers' group, preserves the original permissioned_as value instead of overwriting it.
        labels:
          type: array
          items:
            type: string
      required:
      - path
      - schedule
      - timezone
      - script_path
      - is_flow
      - args
    EditSchedule:
      type: object
      properties:
        schedule:
          type: string
          description: Cron expression with 6 fields (seconds, minutes, hours, day of month, month, day of week). Example '0 0 12 * * *' for daily at noon
        timezone:
          type: string
          description: IANA timezone for the schedule (e.g., 'UTC', 'Europe/Paris', 'America/New_York')
        args:
          nullable: true
          $ref: '#/components/schemas/ScriptArgs'
        on_failure:
          type: string
          nullable: true
          description: Path to a script or flow to run when the scheduled job fails
        on_failure_times:
          type: number
          nullable: true
          description: Number of consecutive failures before the on_failure handler is triggered (default 1)
        on_failure_exact:
          type: boolean
          nullable: true
          description: If true, trigger on_failure handler only on exactly N failures, not on every failure after N
        on_failure_extra_args:
          nullable: true
          $ref: '#/components/schemas/ScriptArgs'
        on_recovery:
          type: string
          nullable: true
          description: Path to a script or flow to run when the schedule recovers after failures
        on_recovery_times:
          type: number
          nullable: true
          description: Number of consecutive successes before the on_recovery handler is triggered (default 1)
        on_recovery_extra_args:
          nullable: true
          $ref: '#/components/schemas/ScriptArgs'
        on_success:
          type: string
          nullable: true
          description: Path to a script or flow to run after each successful execution
        on_success_extra_args:
          nullable: true
          $ref: '#/components/schemas/ScriptArgs'
        ws_error_handler_muted:
          type: boolean
          description: If true, the workspace-level error handler will not be triggered for this schedule's failures
        retry:
          nullable: true
          $ref: ../../openflow.openapi.yaml#/components/schemas/Retry
        no_flow_overlap:
          type: boolean
          description: If true, skip this schedule's execution if the previous run is still in progress (prevents concurrent runs)
        summary:
          type: string
          nullable: true
          description: Short summary describing the purpose of this schedule
        description:
          type: string
          nullable: true
          description: Detailed description of what this schedule does
        tag:
          type: string
          nullable: true
          description: Worker tag to route jobs to specific worker groups
        paused_until:
          type: string
          nullable: true
          format: date-time
          description: ISO 8601 datetime until which the schedule is paused. Schedule resumes automatically after this time
        cron_version:
          type: string
          nullable: true
          description: Cron parser version. Use 'v2' for extended syntax with additional features
        dynamic_skip:
          type: string
          nullable: true
          description: Path to a script that validates scheduled datetimes. Receives scheduled_for datetime and returns boolean to skip (true) or run (false)
        permissioned_as:
          type: string
          nullable: true
          description: The user or group this schedule runs as (e.g., 'u/admin' or 'g/mygroup'). Only admins and wm_deployers can set this via preserve_permissioned_as.
        preserve_permissioned_as:
          type: boolean
          nullable: true
          description: If true and user is admin/wm_deployers, preserve the provided permissioned_as instead of using the deploying user's identity
        labels:
          type: array
          items:
            type: string
      required:
      - schedule
      - timezone
      - args
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    cookieAuth:
      type: apiKey
      in: cookie
      name: token
externalDocs:
  description: documentation portal
  url: https://windmill.dev