cdnca

API reference

/v1/admin/control-upgrade-checks

1 operations

← All groups · First call? Read the tutorial: auth, permissions, requests and responses, common failures

MethodPathSummaryAuth
POST/v1/admin/control-upgrade-checksCheck local control-plane upgrade eligibilitySession

Contract file：api/openapi/v1/control.yaml

Operation details

POST /v1/admin/control-upgrade-checks

Check local control-plane upgrade eligibility

operationId
checkControlUpgradeEligibility
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

All of：control.upgrades.check

Description (from the contract)

Requires control.upgrades.check in a platform scope. The decision re-verifies the locally cached signed entitlement lease, checks its release channel and version range, then evaluates the current locally cached signed platform policy. The license service is not called by this request. Business denials return 200 with eligible=false and a stable reason; authentication, validation, and idempotency failures retain their normal HTTP status. An identical idempotent replay returns the original decision without appending another audit event.

Parameters

checkControlUpgradeEligibility Parameters
NameInTypeRequiredDescription
Idempotency-KeyheaderstringYes—

Request body

application/json · Required：Yes

checkControlUpgradeEligibility Request body
NameTypeRequiredDescription
componentstringYes—
current_versionstringYesCanonical SemVer without a v prefix or build metadata.
channelstringYes—

Responses

checkControlUpgradeEligibility Responses
StatusDescription
200Eligible or a stable business denial based only on verified local state.

Fields：eligible: boolean reason: string: eligible / entitlement_unavailable / entitlement_invalid / entitlement_state_denied / entitlement_channel_mismatch / entitlement_version_denied / platform_policy_stale / release_channel_denied component: string current_version: string channel: string entitlement?: ControlUpgradeEntitlementDecision policy: ControlUpgradePolicyDecision

400The request body or parameters are invalid.
401Authentication failed or the session is invalid.
403The authenticated principal is not allowed to perform the action.
409The requested state conflicts with an existing resource or idempotency fact.
500The request could not be completed because of an internal failure.

What to do on failure

  • 400 Fix the parameters or body per the field list; do not retry unchanged.
  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
  • 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
  • 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list