---
title: "Renew your own claim on a queued alarm (renew-only heartbeat)"
method: POST
path: "/events/{event_id}/claim/renew"
tags: ["events"]
---

# Renew your own claim on a queued alarm (renew-only heartbeat)

`POST /events/{event_id}/claim/renew`

## Request

- Base URL: `https://api.verdun.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.verdun.ai/events/{event_id}/claim/renew`
- Auth: HTTP bearer

The active-review heartbeat. RENEW-ONLY by construction: it restarts the TTL if and only if the caller still holds a live claim on a queued alarm, and it never acquires a free, lapsed or foreign claim, whatever the configuration. Always answers `renewed` (true: `claim` is the renewed claim; false: `claim` is the live claim of whoever holds it now, or null when the alarm is free, lapsed, closed or not on the active queue). A 404 may mean this route is unavailable on an older or disabled task (`CLAIM_CLEANUP_ENABLED` off), or that the event ID is unknown or malformed. Treat every error as unknown, never as renewed, and never fall back to acquire. Read `claim_cleanup_enabled` on `GET /auth/me` first. Customer-side callers get null and never staff identity. Requires claim participation (`review_label_alarms`, or, for central staff, any of `escalate_voice_down`, `escalate_dispatch`, `notify_property_owner`: whoever the claim refusal can refuse) and tenant scope (out of scope is 403, unknown or malformed id is 404).

## Path parameters

- `event_id` string, required

## Response `200`

Successful Response

- ClaimEventResponse
  - `claim` AlarmClaim, required
    - `operator_id` string, required: The operator holding the alarm
    - `operator_name` string, nullable: Their display name; null if the operator no longer exists
    - `claimed_at` string, required: When the claim was taken (ISO 8601, UTC)
    - `expires_at` string, required: When the claim lapses (ISO 8601, UTC)
    - `expires_in_seconds` integer, required: Seconds left on the claim, computed server-side. Time the claim from this against the local clock at receipt, not from `expires_at`, so a skewed workstation clock does not move it.
    - `generation` string, nullable: Ownership generation (a UUID): it changes whenever the claim's HOLDER changes (acquire, take-over) and never on a renewal. Echo it on `POST /events/{id}/claim/acting` and its cancel; a write carrying an old one is rejected. Null while CLAIM_ESCALATION_ENABLED is off, or on a claim stamped before generations existed (the holder's next renew fills it in).
  - `renewed` boolean, nullable: Present only on `POST /events/{id}/claim/renew`: true when the caller's own live claim was renewed (`claim` is then the renewed claim), false when it was NOT (the claim was lost or never held: `claim` is another operator's live claim, or null). A renew never acquires. Absent on an ordinary claim.
  - `reservation` Reservation: An alarm reserved for a focuser or held by a site hold. A reservation is NOT a claim: it has no TTL and lives under the claim.
    - `origin` 'focus' | 'story': `story` for a site hold. A reservation from an older api has no `origin`: it is a Focus.
    - `focus_id` string, required: The focus generation or site hold that reserved this alarm.
    - `operator_id` string, required: The focuser or holder.
    - `operator_name` string, nullable: Their display name; null if the operator no longer exists.
    - `reserved_at` string, required: When the alarm entered the queue and was reserved (ISO 8601, UTC).
    - `elapsed_seconds` integer, required: Server-computed now - reserved_at, for the age display; the unreviewed-age cue applies to reserved alarms exactly as to free ones.
    - `engaged` boolean, nullable: Story only: the current holder has opened this alarm.
    - `open` boolean, nullable: Story only: the holder's page is open (no deadline while it is).
    - `return_at` string, nullable: Story only: when the unattended hold returns its alarms (ISO 8601, UTC); null while `open`. After a clean leave, about 30 s after it unless an earlier idle or new-alert deadline or a live call changes it.
    - `now` string, nullable: Story only: the server clock `return_at` is measured against.
    - `serious_unopened` integer, nullable: Story only: serious alarms the holder has not opened (visibility only).
    - `oldest_serious_queued_at` string, nullable: Story only: when the oldest of those entered the queue.

## Other responses

- `422`: Validation Error

---

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