Skip to main content
ZStack
Infrastructure/OTA Versions & Policies

RunPreflight

Execute preflight health and readiness checks before starting an upgrade

POST/api/v1/ota/plans/{planId}/preflight

Operation ID

RunPreflight

Since

1.0.0

Execution Mode

Synchronous

Auth Context

Auth Required

Auth Context

Send these values as request headers when calling this API.

AuthorizationstringRequired

Bearer Token

X-Tenant-IDstring

X-Tenant-ID

Request Inputs

application/json

Path Parameters

  • planId
    StringRequired

    ID of the upgrade plan to run preflight checks for

Body Fields

  • agentIds
    ListRequired

    Agent ids

    Example: item1,item2

  • config
    ObjectRequired

    Configuration data as key-value pairs

    • planId
      String

      ID of the upgrade plan this preflight configuration applies to

      Example: plan-a1b2c3d4-e5f6-7890-abcd-ef1234567890

    • mode
      String

      Preflight mode, e.g. strict or advisory

      Example: strict

    • checks
      List

      Checks for this resource

      Example: item1,item2

    • timeoutSec
      Integer

      Maximum seconds to wait for all preflight checks to complete

      Example: 120

    • minHealthyPct
      Long

      Minimum percentage of agents that must be healthy to proceed

      Example: 90

Responses

200 OK
200 OK

On success, this API returns the following response structure.

  • planId
    String

    ID of the upgrade plan this preflight result covers

    Example: plan-a1b2c3d4-e5f6-7890-abcd-ef1234567890

  • mode
    String

    Mode used for this preflight run

    Example: strict

  • totalAgents
    Integer

    Total number of agents evaluated during preflight

    Example: 20

  • healthyAgents
    Integer

    Number of agents that passed all preflight checks

    Example: 19

  • unhealthyAgents
    Integer

    Number of agents that failed one or more preflight checks

    Example: 1

  • healthyPct
    Long

    Percentage of agents that passed preflight checks

    Example: 95

  • decision
    String

    Gate decision based on the configured minimum healthy percentage

    Example: proceed

  • excludedAgentIds
    List

    Excluded agent ids

    Example: item1,item2

  • agentResults
    List

    Agent results

    Example: (nested array)

    • agentId
      String

      ID of the agent this preflight result belongs to

      Example: lca-node01.example.com

    • agentName
      String

      Display name of the agent node

      Example: node01

    • healthy
      Boolean

      Whether this agent passed all preflight checks

      Example: true

    • checkResults
      LinkedHashMap

      Preflight check result entries

      Example: (nested object)

    • failReasons
      List

      Fail reasons

      Example: item1,item2

  • checkedAt
    String

    Checked at

    Example: 2026-01-15T08:00:00Z

  • durationMs
    String

    Duration of the preflight run in milliseconds

    Example: 4800