---
title: "POST /presence/refresh"
method: POST
path: "/presence/refresh"
tags: ["system"]
---

# POST /presence/refresh

`POST /presence/refresh`

Actively probe paired peers' reachability and return the round's counters.
Wrapped in the canonical `{ data, ts }` envelope (ADR-008 §0.2); the
previous bare object (counters at top level) is retired.

## Response `200`

Presence refresh round completed

- PresenceRefreshEnvelope — 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` PresenceRefreshResponse, required — Result of a `POST /presence/refresh` round. 主动 probe 一轮 `ensure_reachable_all` 后的统计回执。UI 不靠这里直接判定 在线状态：probe 过程中各设备的 Online/Offline 变化会通过既有 `peers.changed` WebSocket 链路推送，前端再走 `GET /paired-devices` 重拉。该响应只用于调用方显示进度或排障。
    - `errors` integer, required
    - `offline` integer, required
    - `online` integer, required
    - `total` integer, 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/10dd20bcf330/schema)