Updates

Update offers from the hub and the request to install one.

Operations of this group with their access rule, retry rule, parameters and answers. Every request carries a key: Authorization: Bearer <key> (see Authentication).

Operations

Get the update state

GET HEAD /api/v1/system/updates

Access: Administrator · Retry: Safe to repeat (read)

Returns what the host updater reports: the installed version and schema, the newest release found (latest), the automatic update settings (automatic, hourUTC, pin, channel, statistics), the phase (idle, checking, updating, failed), the last error, the last heartbeat and the settings revision, plus the request still waiting in the updater's mailbox (pending). snapshot is null when no host updater is connected. Pass revision to requestSystemUpdate.

Response 200

Field	Type	Required	Rules
snapshot	object	yes	may be null
snapshot.revision	integer	yes	0–2147483646
snapshot.currentVersion	string	yes	matches ^(0|[1-9][0-9]{0,5})\.(0|[1-9][0-9]{0,5})\.(0|[1-9][0-9]{0,5})$
snapshot.currentSchema	integer	yes	0–2147483647
snapshot.automatic	boolean	yes	—
snapshot.hourUTC	integer	yes	0–23
snapshot.pin	string	yes	matches ^(0|[1-9][0-9]{0,5})\.(0|[1-9][0-9]{0,5})\.(0|[1-9][0-9]{0,5})$; may be null
snapshot.heartbeatAt	string (date-time)	yes	—
snapshot.checkedAt	string (date-time)	yes	may be null
snapshot.latest	object	yes	may be null
snapshot.latest.version	string	yes	matches ^(0|[1-9][0-9]{0,5})\.(0|[1-9][0-9]{0,5})\.(0|[1-9][0-9]{0,5})$
snapshot.latest.schema	integer	yes	0–2147483647
snapshot.latest.sha256	string	yes	SHA-256: 64 lowercase hexadecimal digits
snapshot.phase	string	yes	one of idle, checking, updating, failed
snapshot.error	string	yes	one of check_failed, update_failed, conflict, maintenance_required, recovery_required, null; may be null
snapshot.lastAttemptDay	string	yes	may be null
snapshot.lastRequestId	string (uuid)	yes	may be null
snapshot.statistics	boolean	no	—
snapshot.channel	string	no	one of stable, beta
pending	object	yes	one of null
pending.id	string (uuid)	yes	—
pending.expectedRevision	integer	yes	0–2147483646
pending.kind	string	yes	one of check
pending.version	string	yes	matches ^(0|[1-9][0-9]{0,5})\.(0|[1-9][0-9]{0,5})\.(0|[1-9][0-9]{0,5})$
pending.sha256	string	yes	SHA-256: 64 lowercase hexadecimal digits
pending.automatic	boolean	yes	—
pending.hourUTC	integer	yes	0–23
pending.statistics	boolean	no	—

Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507

Example

curl -X GET "$ARKVORY_URL/api/v1/system/updates" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Request an update action

POST /api/v1/system/updates/requests

Access: Administrator · Retry: Repeat only with the expected revision (compare-and-swap)

Hands one command to the host updater, which does the work: kind check looks for a new release, apply installs the given stable version with its sha256, configure sets automatic, hourUTC and optionally statistics. Send a new UUID as id and the expectedRevision from getSystemUpdates; 409 revision_mismatch means the settings changed, 503 busy that a request is pending or the updater is working, 503 unavailable that no updater is connected or its heartbeat is older than five minutes. The answer 202 only means the request was queued: follow phase, currentVersion and lastRequestId in getSystemUpdates. Repeating the same id and body is safe.

Request body (application/json)

Field	Type	Required	Rules
id	string (uuid)	yes	—
expectedRevision	integer	yes	0–2147483646
kind	string	yes	one of check
version	string	yes	matches ^(0|[1-9][0-9]{0,5})\.(0|[1-9][0-9]{0,5})\.(0|[1-9][0-9]{0,5})$
sha256	string	yes	SHA-256: 64 lowercase hexadecimal digits
automatic	boolean	yes	—
hourUTC	integer	yes	0–23
statistics	boolean	no	—

Response 202

Field	Type	Required	Rules
id	string (uuid)	yes	—

Responses: 202, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Example

curl -X POST "$ARKVORY_URL/api/v1/system/updates/requests" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":"00000000-0000-4000-8000-000000000000","expectedRevision":0,"kind":"check"}'