Skip to main content
API Explorer|API Explorer
Infrastructure/OTA Versions & Policies
POSTOTASince 1.0SynchronousAuth Required

RunPreflight

Execute preflight health and readiness checks before starting an upgrade

Execution Availability

Try It Out

Submit a mock request using the current auth context and example-driven inputs.

Path Parameters

Request Inputs

Path Parameters

  • planIdStringRequired

    ID of the upgrade plan to run preflight checks for

Body Fields

  • agentIdsListRequired

    Agent ids

    Example: item1,item2

  • configObjectRequired

    Configuration data as key-value pairs

    • planIdString

      ID of the upgrade plan this preflight configuration applies to

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

    • modeString

      Preflight mode, e.g. strict or advisory

      Example: strict

    • checksList

      Checks for this resource

      Example: item1,item2

    • timeoutSecInteger

      Maximum seconds to wait for all preflight checks to complete

      Example: 120

    • minHealthyPctLong

      Minimum percentage of agents that must be healthy to proceed

      Example: 90

Responses

200 OK

On success, this API returns the following response structure.

  • planIdString

    ID of the upgrade plan this preflight result covers

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

  • modeString

    Mode used for this preflight run

    Example: strict

  • totalAgentsInteger

    Total number of agents evaluated during preflight

    Example: 20

  • healthyAgentsInteger

    Number of agents that passed all preflight checks

    Example: 19

  • unhealthyAgentsInteger

    Number of agents that failed one or more preflight checks

    Example: 1

  • healthyPctLong

    Percentage of agents that passed preflight checks

    Example: 95

  • decisionString

    Gate decision based on the configured minimum healthy percentage

    Example: proceed

  • excludedAgentIdsList

    Excluded agent ids

    Example: item1,item2

  • agentResultsList

    Agent results

    Example: (nested array)

    • agentIdString

      ID of the agent this preflight result belongs to

      Example: lca-node01.example.com

    • agentNameString

      Display name of the agent node

      Example: node01

    • healthyBoolean

      Whether this agent passed all preflight checks

      Example: true

    • checkResultsLinkedHashMap

      Preflight check result entries

      Example: (nested object)

    • failReasonsList

      Fail reasons

      Example: item1,item2

  • checkedAtString

    Checked at

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

  • durationMsString

    Duration of the preflight run in milliseconds

    Example: 4800

Endpoint

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

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

Operation ID

RunPreflight

Permalink

Request Example

curl -X POST '{host}/api/v1/ota/plans/{planId}/preflight' -H 'Authorization: Bearer {token}' -H 'Content-Type: application/json' -d '{"agentIds":"item1,item2","config":{"planId":"plan-a1b2c3d4-e5f6-7890-abcd-ef1234567890","mode":"strict","checks":"item1,item2","timeoutSec":120,"minHealthyPct":90.0}}'

Response Example

200
{"planId": "plan-a1b2c3d4-e5f6-7890-abcd-ef1234567890", "mode": "strict", "totalAgents": 20, "healthyAgents": 19, "unhealthyAgents": 1, "healthyPct": 95.0, "decision": "proceed", "excludedAgentIds": ["value"]}

Change History

This API has no change history records yet.

View all change history