---
title: "GET /upgrade/status"
method: GET
path: "/upgrade/status"
tags: ["upgrade"]
---

# GET /upgrade/status

`GET /upgrade/status`

Detect whether the running build is a fresh install / unchanged / upgraded
/ downgraded relative to the stored version cursor.

## Response `200`

Upgrade status detected

- UpgradeStatusEnvelope — Canonical success envelope: `{ "data": T, "ts": <unix millis i64> }`. `ts` is `chrono::Utc::now().timestamp_millis()`, set in the webserver handler via [`ApiEnvelope::now`] (the contract carries only the type + the clock helper, not a hard dependency on when the handler reads the clock). `rename_all = "camelCase"` is a no-op for the single-word fields here but is declared for forward-compat. IMPORTANT (utoipa v4): every concrete `ApiEnvelope<X>` that needs a named OpenAPI component is declared in the `#[aliases(...)]` block below. Add a new alias line whenever a new payload type needs enveloping. NEVER register the bare `ApiEnvelope` in `components(schemas(...))` — utoipa errors on a bare generic, and an un-aliased generic inlines an anonymous schema.
  - `data` union, required — Discriminated union mirroring `uc_application::facade::UpgradeStatus`. Wire encoding uses `kind` discriminator with snake_case variants to keep parity with the CLI JSON output produced by `uniclip upgrade status --json`. 防御性补丁(issue #606 followup):同时声明 `rename_all_fields`, 避免未来新增多词字段(如 `target_version`)时 wire 字段名漂回 snake_case 与上层契约不一致。当前字段都是单词,加这个对 wire 无影响, 但锁定未来添加字段的默认风格。详见 `docs/agent/rust-tauri-rules.md` 的 "Enum Wire Serialization" 一节。
    - object — First time the app is launched on this profile.
      - `current` string, required
      - `kind` 'fresh_install', required
    - object — Cursor matches the running build; no action needed.
      - `current` string, required
      - `kind` 'no_change', required
    - object — Cursor lags the running build (or is missing on a setup-completed profile). `from = None` means the previous version is unknown (pre-cursor era / corrupt cursor fallback).
      - `from` string, nullable
      - `kind` 'upgraded', required
      - `to` string, required
    - object — Cursor leads the running build — the user rolled back.
      - `from` string, required
      - `kind` 'downgraded', required
      - `to` string, required
  - `ts` integer, required — Server time when the response was built (unix epoch milliseconds).

## Other responses

- `500` — Internal server error

---

[API](https://skmtc.net/uniclipboard/apis/uniclipboard-daemon-api.md) · [All operations](https://skmtc.net/uniclipboard/apis/uniclipboard-daemon-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/uniclipboard/uniclipboard-daemon-api/versions/a5d29889448a/schema)