Update check

Update check is the client-plane call that asks whether a safe install target exists. The server does not push to devices.

When to use

Native clients, official SDKs, and headless services use this API. Electron / Sparkle / Tauri updaters read a listing feed instead; see Store listings.

Configuration entry

• Console: project Settings (minimum supported version, rate limits, Require client token for checks); version channel / gray / critical flags. Click-path: Versions.
• YAML: no global poll interval. Plane bind address: client.yaml.

Rules and error codes

Clients POST /api/v1/projects/{project_ref}/update/check. GET on the same path is 404 NOT_FOUNDGeneric missing resource.

Condition	HTTP	Code
Unknown current_version	404	VERSION_NOT_FOUNDVersion missing
Revoked with no safe fallback	409	NO_SAFE_TARGETNo safe target or VERSION_REVOKEDRevoked with no safe target
Min-source hop failed	409	INTERMEDIATE_UNAVAILABLEMin-source hop missing, not ready, cyclic, or more than 8 hops
Current line min OS/API unmet	409	MIN_OS_NOT_METOS/API below the current line floor
Too frequent	429	RATE_LIMITEDToo many requests; honor Retry-After (Retry-After)
Line not preheated	404	VERSION_NOT_VISIBLEVersion not visible to the client (draft, packs not ready, or gray miss)

A wrong X-Channel-Token is not 403: that hidden channel is skipped. No update is 204; ETag hit is 304. Neither is a failure. Check is Cache-Control: private by default and must not be a public CDN object. See CDN.

Client duties

1. Check once at process start, then on the product’s own schedule. There is no product-defined interval.
2. The app generates and stores device_id (gray depends on it). SDKs do not mint device identity.
3. Default capabilities is only full_package. Do not advertise binary_delta without a Patcher.
4. The body has no changelog text. Fetch changelog separately.

Schema: API reference openapi.client.json (open Scalar). Sequence: Check HTTP.