---
title: "Trigger Sleep Maintenance (admin manual run)"
method: POST
path: "/api/v1/admin/sleep/run"
tags: ["admin-sleep"]
---

# Trigger Sleep Maintenance (admin manual run)

`POST /api/v1/admin/sleep/run`

## Request

- Base URL: `https://memory.kagura-ai.com` (the document declares no server; this is the origin it was published from)
- URL: `https://memory.kagura-ai.com/api/v1/admin/sleep/run`
- Auth: none declared

Manually trigger a Sleep Maintenance run for the calling admin.

Self-scoped: the run targets only contexts the admin created (matched
on ``Context.created_by``), excluding soft-deleted contexts and
contexts with ``sleep_mode='skip'``. When ``context_id`` is provided a
single run is scheduled for that context; otherwise one run is
scheduled per eligible context.

Returns:
    202 with ``{"report_ids": [...]}``. Phase execution happens in the
    background; poll ``GET /admin/sleep-reports/{id}`` for progress.

Raises:
    409 ``SLEEP-002`` if this user already has a sleep run
    with ``status='running'`` — the response body includes
    ``running_report_id`` and ``started_at`` so the UI can link to it.
    404 ``SLEEP-003`` if no eligible contexts match.

Phase 1 limitation:
    The 409 guard is best-effort under concurrent requests. Two
    simultaneous POSTs could each pass the check before either commits,
    resulting in overlapping batches. Acceptable for single-admin
    dogfooding; Phase 2 will enforce exactly-once via a unique partial
    index on ``sleep_reports(user_id) WHERE status='running'``.

## Request body

- SleepRunRequest: Body for POST /admin/sleep/run. Attributes: context_id: Target context. When null, runs against every context owned by the calling admin (self-scoped).
  - `context_id` string, uuid, nullable

## Response `202`

Successful Response

- SleepRunResponse: 202 response for POST /admin/sleep/run. Attributes: report_ids: IDs of the newly-created sleep reports, one per scheduled context. For a single-context request this list always has exactly one element.
  - `report_ids` string[], required

## Other responses

- `409`: A sleep run is already in progress for this user.
- `422`: Validation Error

---

[API](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud.md) · [All operations](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud/llms.txt) · [OpenAPI document](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud/revisions/09f17f5ada29?raw)