---
title: "POST /lifecycle/graceful-stop — request an orderly shutdown of THIS daemon"
method: POST
path: "/lifecycle/graceful-stop"
tags: ["lifecycle"]
---

# POST /lifecycle/graceful-stop — request an orderly shutdown of THIS daemon

`POST /lifecycle/graceful-stop`

## Request

- The document declares no server URL.
- Auth: one of:
  - API key in query parameter `auth`
  - API key in header `Authorization`

process, regardless of residency.

The true root cause this closes: on Windows, a caller-initiated restart
(e.g. GUI settings-change restart in `uc-desktop::daemon_probe::restart_local_daemon`)
has no real signal to send — `TerminateProcess` kills the process before its
async graceful-shutdown task ever runs `mark_clean_exit()`, so the next boot
logs a false "previous daemon run exited abnormally". This endpoint lets the
caller ask first: the start marker is cleared HERE, synchronously, before the
shutdown sequence even starts, so the marker is already correct even if the
caller's graceful wait times out and it falls back to a hard kill.

Deliberately NOT routed through [`RestartCoordinator`] — that machinery is
reserved for Oneshot-residency promotion (ADR-008 P5-L L8c) and refuses any
other residency. This endpoint works for every residency and does not touch
`quiescing`.

## Response `202`

Graceful stop requested; shutdown sequence started

## Changes

- **2026-10-06** `ed4900720868`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/uniclipboard/apis/uniclipboard-daemon-api/changes/lifecycle/graceful-stop/post.md)

---

[API](https://skmtc.dev/uniclipboard/apis/uniclipboard-daemon-api.md) - [All operations](https://skmtc.dev/uniclipboard/apis/uniclipboard-daemon-api/llms.txt) - [OpenAPI document](https://skmtc.dev/uniclipboard/apis/uniclipboard-daemon-api/revisions/48a01cf04e4c?raw)