Kagura AI Admin Sleep API

openapi: 3.2.0
info:
  title: Kagura Memory Cloud Admin Sleep API
  description: Universal AI Memory Platform - Remote MCP Server + Web Management
  version: 0.158.1
tags:
- name: admin-sleep
  description: 'Admin: manually run Sleep Maintenance and undo individual merges'
paths:
  /api/v1/admin/sleep/run:
    post:
      tags:
      - admin-sleep
      summary: Trigger Sleep Maintenance (admin manual run)
      description: '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''``.'
      operationId: trigger_sleep_run_api_v1_admin_sleep_run_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SleepRunRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SleepRunResponse'
        '409':
          description: A sleep run is already in progress for this user.
          content:
            application/json:
              example:
                error: SLEEP-002
                message: A sleep run is already in progress for this user.
                details:
                  running_report_id: 00000000-0000-0000-0000-000000000000
                  started_at: '2026-04-09T12:00:00Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/admin/sleep/actions/{action_id}/undo-merge:
    post:
      tags:
      - admin-sleep
      summary: Undo one dedup merge (restore the merged-away memory)
      description: 'Restore the loser of ONE dedup merge — row and Qdrant vector (#1209).


        Self-scoped like the manual sleep trigger: the merge''s report must belong

        to the calling admin. The undo is itself audited as an ``undo_merge``

        action on the same sleep report, so the merge''s full history reads out of

        one audit log. Reversibility is bounded by the declared retention window;

        a purged loser returns 410 with the setting named.'
      operationId: undo_merge_api_v1_admin_sleep_actions__action_id__undo_merge_post
      parameters:
      - name: action_id
        in: path
        required: true
        schema:
          type: integer
          title: Action Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UndoMergeResponse'
        '400':
          description: The action is not a dedup merge.
        '404':
          description: Action not found or not owned by the caller.
        '409':
          description: 'Conflicts with current state. ``SLEEP-UNDO-already_restored``: the memory or shadow edge is already back in its post-undo state (no-op). ``SLEEP-UNDO-not_merge_deleted``: the memory was deleted by something other than this merge. ``SLEEP-UNDO-edge_changed`` (#1450): a later writer changed or removed the shadow edge, so the pre-merge state could not be restored — unlike the other two, the undo did NOT happen.'
        '410':
          description: The merge loser was purged by the Sleep retention window (sleep_merge_retention_days) or the platform cleanup sweep (CLEANUP_DELETED_MEMORIES_RETENTION_DAYS, default 30 days) — no longer restorable.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    UndoMergeResponse:
      properties:
        restored_memory_id:
          type: string
          title: Restored Memory Id
        winner_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Winner Id
        report_id:
          type: string
          title: Report Id
        undone_action_id:
          type: integer
          title: Undone Action Id
      type: object
      required:
      - restored_memory_id
      - winner_id
      - report_id
      - undone_action_id
      title: UndoMergeResponse
      description: "200 response for POST /admin/sleep/actions/{action_id}/undo-merge.\n\nAttributes:\n    restored_memory_id: The merge loser brought back into recall.\n    winner_id: The merge winner (unchanged by the undo).\n    report_id: The sleep report whose audit log records both the merge\n        and this undo.\n    undone_action_id: The original merge action that was undone."
    SleepRunRequest:
      properties:
        context_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Context Id
      type: object
      title: SleepRunRequest
      description: "Body for POST /admin/sleep/run.\n\nAttributes:\n    context_id: Target context. When null, runs against every context\n        owned by the calling admin (self-scoped)."
    SleepRunResponse:
      properties:
        report_ids:
          items:
            type: string
            format: uuid
          type: array
          title: Report Ids
      type: object
      required:
      - report_ids
      title: SleepRunResponse
      description: "202 response for POST /admin/sleep/run.\n\nAttributes:\n    report_ids: IDs of the newly-created sleep reports, one per\n        scheduled context. For a single-context request this list\n        always has exactly one element."