---
title: "Send Capacity Lock Notice"
method: POST
path: "/internal/workspaces/{workspace_id}/capacity-lock-notice"
tags: ["internal-billing"]
---

# Send Capacity Lock Notice

`POST /internal/workspaces/{workspace_id}/capacity-lock-notice`

## 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/internal/workspaces/{workspace_id}/capacity-lock-notice`
- Auth: none declared

Warn the owner before a paid period ends that Free would lock the workspace (#1941).

memory-cloud does not store ``current_period_end``, so the billing service
decides WHEN (e.g. 7 days before the end of a cancelled subscription) and
calls this. memory-cloud evaluates the projected Free state with the same
counting as the capacity lock — Free tier limits plus the bonuses a
downgrade keeps, files of deleted contexts excluded — and, when over,
emails the workspace owner (plain text, no memory content).

Idempotent per ``(workspace, period_end)``: a repeat answers
``sent=false, reason="already_sent"``. In addition, at most one notice per
workspace per 24 hours (``reason="cooldown"``). A failed delivery releases
both claims so a retry can send. 404 for a missing or soft-deleted workspace.

## Path parameters

- `workspace_id` string, required

## Headers

- `authorization` string, nullable

## Request body

- CapacityLockNoticeRequest: Body of ``POST /internal/workspaces/{id}/capacity-lock-notice`` (#1941).
  - `period_end` string, date-time, required: When the paid period ends and the workspace returns to Free

## Response `200`

Successful Response

- CapacityLockNoticeResult: Outcome of a notice request. Never carries the recipient address. ``reason`` (when ``sent`` is false): ``not_billing_managed`` (the workspace's entitlement is admin-managed or self-hosted — it is never locked, so it is never warned), ``within_capacity`` (the projected Free state fits — nothing to warn about), ``already_sent`` (a notice for this ``period_end`` was already sent), ``cooldown`` (a notice for this workspace was sent in the last 24 hours, for any ``period_end``), ``no_owner_email`` or ``delivery_failed`` (retry later; both claims are released). ``sent=true, reason="delivery_uncertain"``: the provider timed out after it may have accepted the email; the claim is kept, so it is never resent.
  - `sent` boolean, required
  - `reason` string, nullable
  - `over_memories` integer, required
  - `over_bytes` integer, required

## Other responses

- `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)