CreateOperationPrecheck

Create a five-minute confirmation using the Agent's stored scope. A capabilities operation validates the entire ordered change list with agent.config.write permission and returns capabilityImpacts in request order. Only host_metrics is supported in this release. Disable accepts drainMode wait or discard. Blocked operations create no confirmation. Cancel platform access requires agent.access.revoke; it does not uninstall the Agent.

POST/api/v1/lifecycle/managed-agent/agents/{id}/operation-prechecks

Operation ID

CreateOperationPrecheck

Since

1.3.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

id
StringRequired
Unique identifier of the managed agent

Body Fields

requestId
String
Request id for this resource
Example: value
operation
Object
Operation for this resource
- type
  String
  Operation to precheck: revoke_access, restart_runtime, upgrade, or capabilities. The capabilities value requests desired-state changes, not a task type.
  Example: value
- reason
  String
  revoke_access: operator_decommissioned or credential_suspected_compromise. restart_runtime: optional operator reason, for example operator_requested. Never combined with changes.
  Example: value
- changes
  List
  type=capabilities. Non-empty list with unique capability IDs; every item must be supported and valid. Only host_metrics is implemented in this release, so only one distinct change can currently be submitted. The entire list shares one confirmation and one change_capabilities task.
  Example: (nested array)
  capabilityId
  String
  Capability id for this resource
  Example: value
  desiredState
  String
  Desired state for this resource
  Example: value
  configurationRevision
  String
  Update only: a certified configuration version, never raw Collector YAML.
  Example: value
  drainMode
  String
  Disable only. Initial enable/resume omits both optional fields.
  Example: value
- targetVersion
  String
  type=upgrade only: certified unified Agent release version.
  Example: value

Responses

200 OK

On success, this API returns the following response structure.

precheckId
String
Precheck id for this resource
Example: value
result
String
Result for this resource
Example: value
agentRowVersion
String
Agent row version for this resource
Example: 10
expiresAt
String
Expires at for this resource
Example: 2026-01-15T08:00:00Z
plannedImpact
Object
Planned impact for this resource
- platformAccessRevoked
  Boolean
  Platform access revoked for this resource
  Example: true
- localBacklogMayNotUpload
  Boolean
  Local backlog may not upload for this resource
  Example: true
- localAgentUninstalled
  Boolean
  Local agent uninstalled for this resource
  Example: true
- metricsContinuity
  String
  buffered, unprotected or unknown; restart reports unknown. Empty for access revocation.
  Example: value
- resumeCollection
  Boolean
  Resume collection for this resource
  Example: true
- drainMode
  String
  Disable only: wait or discard.
  Example: value
- drainWaitSeconds
  Integer
  Fixed at 1800 for wait; absent for discard.
  Example: 10
- cancelledEnableTaskId
  String
  Cancelled enable task id for this resource
  Example: value
- queueFacts
  Object
  Queue facts for this resource
  queueSize
  Long
  Queue size for this resource
  Example: 0
  queueCapacity
  Long
  Queue capacity for this resource
  Example: 0
  enqueueFailedMetricPoints
  Long
  Enqueue failed metric points for this resource
  Example: 0
  sendFailedMetricPoints
  Long
  Send failed metric points for this resource
  Example: 0
  sentMetricPoints
  Long
  Sent metric points for this resource
  Example: 0
  serviceInstanceId
  String
  Service instance id for this resource
  Example: value
  observedAt
  String
  Observed at for this resource
  Example: 2026-01-15T08:00:00Z
- collectorRestart
  Boolean
  Restart and Upgrade affect the Collector; Restart leaves its Supervisor.
  Example: true
- agentRestart
  Boolean
  Upgrade only: complete Agent package, including its Supervisor.
  Example: true
- previousAgentVersion
  String
  Previous agent version for this resource
  Example: value
- targetAgentVersion
  String
  Target agent version for this resource
  Example: value
- previousAgentRelease
  String
  Previous agent release for this resource
  Example: 10
- targetAgentRelease
  String
  Target agent release for this resource
  Example: 10
confirmationMessage
String
Confirmation message for this resource
Example: value
agentDisplayName
String
Agent display name for this resource
Example: value
blockedBy
List
A blocked result has no precheck_id, expiry or confirmation to consume.
Example: item1,item2
capabilityImpacts
List
Ordered exactly as the requested capability changes. For a single change, planned_impact also contains its impact; for multiple changes it is absent.
Example: (nested array)
- capabilityId
  String
  Capability id for this resource
  Example: value
- impact
  Object
  Impact for this resource
  platformAccessRevoked
  Boolean
  Platform access revoked for this resource
  Example: true
  localBacklogMayNotUpload
  Boolean
  Local backlog may not upload for this resource
  Example: true
  localAgentUninstalled
  Boolean
  Local agent uninstalled for this resource
  Example: true
  metricsContinuity
  String
  buffered, unprotected or unknown; restart reports unknown. Empty for access revocation.
  Example: value
  resumeCollection
  Boolean
  Resume collection for this resource
  Example: true
  drainMode
  String
  Disable only: wait or discard.
  Example: value
  drainWaitSeconds
  Integer
  Fixed at 1800 for wait; absent for discard.
  Example: 10
  cancelledEnableTaskId
  String
  Cancelled enable task id for this resource
  Example: value
  queueFacts
  Object
  Queue facts for this resource
  queueSize
  Long
  Queue size for this resource
  Example: 0
  queueCapacity
  Long
  Queue capacity for this resource
  Example: 0
  enqueueFailedMetricPoints
  Long
  Enqueue failed metric points for this resource
  Example: 0
  sendFailedMetricPoints
  Long
  Send failed metric points for this resource
  Example: 0
  sentMetricPoints
  Long
  Sent metric points for this resource
  Example: 0
  serviceInstanceId
  String
  Service instance id for this resource
  Example: value
  observedAt
  String
  Observed at for this resource
  Example: 2026-01-15T08:00:00Z
  collectorRestart
  Boolean
  Restart and Upgrade affect the Collector; Restart leaves its Supervisor.
  Example: true
  agentRestart
  Boolean
  Upgrade only: complete Agent package, including its Supervisor.
  Example: true
  previousAgentVersion
  String
  Previous agent version for this resource
  Example: value
  targetAgentVersion
  String
  Target agent version for this resource
  Example: value
  previousAgentRelease
  String
  Previous agent release for this resource
  Example: 10
  targetAgentRelease
  String
  Target agent release for this resource
  Example: 10

Request Example

curl -X POST '{host}/api/v1/lifecycle/managed-agent/agents/{id}/operation-prechecks' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
  "requestId": "value",
  "operation": {
    "type": "value",
    "reason": "value",
    "changes": [
      {
        "capabilityId": "value",
        "desiredState": "value",
        "configurationRevision": "value",
        "drainMode": "value"
      }
    ],
    "targetVersion": "value"
  }
}'

Response Example

{
  "precheckId": "value",
  "result": "value",
  "agentRowVersion": "10",
  "expiresAt": "2026-01-15T08:00:00Z",
  "plannedImpact": {
    "platformAccessRevoked": true,
    "localBacklogMayNotUpload": true,
    "localAgentUninstalled": true,
    "metricsContinuity": "value",
    "resumeCollection": true,
    "drainMode": "value",
    "drainWaitSeconds": 10,
    "cancelledEnableTaskId": "value"
  },
  "confirmationMessage": "value",
  "agentDisplayName": "value",
  "blockedBy": [
    "value"
  ]
}

Change History

View all change history

Change TimeChange SummaryAction

Change Time
2026-09-22
AddedResponse fields capabilityId, capabilityImpacts, impact
View API
Change Time
2026-09-17
AddedResponse fields previousAgentRelease, targetAgentRelease
View API

Assets

Collects

Infrastructure Misc

Installer

Lifecycle

OTA Upgrade Plans

OTA Versions & Policies

Federation & SSO

Change Management

Lifecycle Upgrade

Alert Rules

Alert Templates

Alert Channels & Integrations

Alert Events

Alert Routing & Policies

Security

ZMetis Audit

Platforms

Platform Federation

Platform Health

Platform Misc

ZMetis Tasks

CreateOperationPrecheck

Auth Context

Request Inputs

Path Parameters

Body Fields

Responses

Change History