/api/system/update/download

Description

The /api/system/update/download endpoint starts the safe first phase of the updater: it checks for a newer version, fetches the update manifest, downloads the platform-specific package, verifies the SHA-256 hash, and stages the verified files under Client_Data\Updates.

This endpoint does not install the new binary over the running process. Instead, it prepares a verified staged update for a future helper-based apply flow.

Parameters

This endpoint does not require any parameters.

Immediate Response

The endpoint returns quickly with a task identifier. The download and verification work continues in the background.

{
  "status": "success",
  "operation": "update-download",
  "task_id": "Apr-22-26_06-12-11-pm-81af",
  "url": "http://localhost:8080/api/system/tasks?task_id=Apr-22-26_06-12-11-pm-81af",
  "message": "Update download started. Poll /api/system/tasks for progress."
}

Task Data

Poll /api/system/tasks until the task reaches a terminal state. On success, the data object contains staging metadata.

{
  "status": "success",
  "progress": 100,
  "message": "Update downloaded and verified. Apply is not implemented yet.",
  "data": {
    "phase": "READY_TO_APPLY",
    "current_version": "2026-04-22",
    "latest_version": "2026-04-29",
    "downloaded": true,
    "verified": true,
    "apply_not_implemented": true,
    "restart_required": false,
    "package_path": "E:\\Client_Data\\Updates\\core.2026-04-29.exe",
    "manifest_path": "E:\\Client_Data\\Updates\\manifest.2026-04-29.exe.json",
    "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "size_bytes": 7340032,
    "release_notes": "Staged updater package for the next helper-based apply flow."
  }
}

{
  "status": "success",
  "progress": 100,
  "message": "No update available. You are already running the latest version.",
  "data": {
    "phase": "READY_TO_APPLY",
    "update_available": false,
    "downloaded": false,
    "verified": false,
    "apply_not_implemented": true
  }
}

Examples

const API_HOST = 'http://localhost:8080';

async function stageUpdate() {
    const startResp = await fetch(`${API_HOST}/api/system/update/download`);
    const startResult = await startResp.json();

    if (startResult.status !== 'success') {
        console.error('Could not start update download:', startResult.message);
        return;
    }

    const taskId = startResult.task_id;

    while (true) {
        await new Promise(resolve => setTimeout(resolve, 2000));

        const taskResp = await fetch(`${API_HOST}/api/system/tasks?id=${taskId}`);
        const taskResult = await taskResp.json();
        console.log(`${taskResult.progress}% - ${taskResult.message}`);

        if (taskResult.status === 'success' || taskResult.status === 'failed') {
            console.log(taskResult);
            break;
        }
    }
}

stageUpdate();

# Start the staged download
curl -X GET "http://localhost:8080/api/system/update/download"

# Start and pretty-print the immediate response
curl -s "http://localhost:8080/api/system/update/download" | jq

# Poll task progress (replace TASK_ID with the value from the first call)
curl -s "http://localhost:8080/api/system/tasks?id=TASK_ID" | jq

# Start download and extract the task ID in one line
TASK_ID=$(curl -s "http://localhost:8080/api/system/update/download" | jq -r '.task_id')
echo "Task ID: $TASK_ID"

package main

import (
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

const ApiHost = "http://localhost:8080"

type StartResponse struct {
    Status  string `json:"status"`
    TaskID  string `json:"task_id"`
    Message string `json:"message"`
}

func main() {
    resp, err := http.Get(fmt.Sprintf("%s/api/system/update/download", ApiHost))
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)

    var start StartResponse
    json.Unmarshal(body, &start)
    fmt.Printf("Status: %s\nTask ID: %s\nMessage: %s\n", start.Status, start.TaskID, start.Message)
}

Implementation Details

1. Version check — fetches the authoritative client version from RAIDA using 2-of-3 consensus.
2. Manifest fetch — fetches the update manifest from RAIDA using the same consensus approach.
3. Binary download — downloads the platform package from the CloudCoin distribution allowlist using updater-specific, longer HTTP timeouts.
4. Verification — computes SHA-256 of the downloaded package and compares it to the manifest hash.
5. Staging — writes the package, manifest copy, and simple metadata file into Client_Data\Updates.