Settings

Report whether a release update can be applied from the console.

get/settings/update

Request

  • Base URL: /api (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /api/settings/update
  • Auth: HTTP bearer

Response

Self-update capability for this install

allowedboolean required

Whether the caller holds platform:update. Distinct from can_apply, which describes the server: the console shows the action only when both are true, so a reader is never offered a button that would 403.

binary_pathstring required

Binary that would be replaced.

blocker'disabled_by_flag' | 'disabled_by_setting' | 'not_supported' | 'binary_not_writable' | 'unsupported_platform' | 'in_progress'

Why a one-click update is unavailable. Exactly one is reported — the most fundamental blocker wins, so the operator fixes the real problem first rather than clearing one only to hit the next.

can_applyboolean required

True only when a request would actually download, install and restart.

caveatstring nullable

Non-blocking warning to show with the confirmation (split topology).

channelstring required

Channel actually tracked, after applying the configured override or falling back to inference from the running version tag.

channel_is_pinnedboolean required

True when channel was set explicitly in settings rather than inferred.

current_migration_namestring nullable

Name of the migration currently running. Some while phase is migrating and a migration step is in flight.

current_versionstring required

Version tag of the running binary. Always present — the version page needs it whether or not an update exists.

manual_commandstring required

The equivalent command to run by hand. Always present.

migrations_appliedinteger nullable

Number of migrations applied so far. Some while phase is migrating.

migrations_totalinteger nullable

Total migrations to be applied. Some once the migrate child has reported its first started event.

phase'idle' | 'resolving' | 'downloading' | 'verifying' | 'installing' | 'migrating' | 'restarting' | 'pending_restart' | 'failed' required

Where an in-flight update has got to. Polled by the console so a long download shows progress instead of an indefinite spinner.

phase_errorstring nullable

Failure detail while phase is failed.

reasonstring nullable

Operator-facing explanation of blocker.

restart_mode'automatic' | 'manual' required

What happens to the running process once the new binary is in place.

supervisor'systemd' | 'launchd' | 'container' | 'none' required

What (if anything) will restart the process after it exits.

Example response

{
  "last_attempt": {
    "started_at": "2026-08-06T09:12:31Z"
  }
}

Changes

No recorded changes to this operation across all 54 revisions of this API.