events

Take over an alarm another operator is working

Claim-lock step 3a, ONE HOLDER PER ALARM. The holder works the alarm: a close (POST /eval/operator/{id} 409 claim_held, a per-item 423 in the bulk close) and the operator-started Voice down, AI voice announcement, call to the owner, dispatch call and event-scoped Live Talk are refused 409 claim_held while ANOTHER operator holds a live claim; anyone else uses this first. Open to every central-staff operator (owners included); not a priority tier. Body {expected_holder_id, expected_claimed_at} is the claim the console showed (echo operator_id and claimed_at from it). Under the event row lock, if that is still the live claim the claim moves to the caller (200 with the new claim, consoles are nudged so the displaced holder learns at once); otherwise nothing moves: 409 claim_changed with the CURRENT claim (or null when nobody holds it now), and the console reconfirms. Never retry a claim_changed automatically. Two operators taking over at once: exactly one wins. A closed, expired or non-queued alarm is a plain 409. Taking over a claim the caller already holds is 200 and writes nothing. Take over transfers no draft: the displaced operator's notes stay on their own screen. Reserved shape (Focus, expected_focus_id with no expected_claimed_at): a live claim appearing meanwhile is 409 claim_changed with that claim, a reservation that is gone or changed is 409 claim_changed with claim null (and the current reservation, if any), and Focus being off is 404 (after the scope and staff checks below); a body that names neither expected_claimed_at nor expected_focus_id is 422 (as is any schema-invalid body), except that with Focus on an alarm reserved for another operator's focus with no live claim answers 409 claim_changed with the current reservation. 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); non-staff callers get 403. 404 while CLAIM_REFUSAL_ENABLED is off (or the api predates this): read claim_refusal_enabled on GET /auth/me first.

post/events/{event_id}/claim/take-over

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/take-over
  • Auth
    HTTP bearer

Path parameters

event_idstring required

Request body

expected_holder_idstring uuid required

operator_id of the claim the console showed. The take-over moves the claim only if this operator still holds it.

expected_claimed_atstring date-time nullable

claimed_at of the claim the console showed (ISO 8601, echoed from the claim payload). Must equal the live claim's claimed_at (to the millisecond), so a renewal between the console's read and the click answers 409 claim_changed and the operator reconfirms against the fresh holder. Omit it only in the Focus reserved shape (together with expected_focus_id), to take over an alarm RESERVED for another operator's focus that has no live claim: there is nothing to echo, and it is ignored. In the reserved shape a live claim that appeared meanwhile is 409 claim_changed carrying that claim, a reservation that is gone or the caller's own is 409 claim_changed with claim null, and Focus being off (FOCUS_ENABLED off) is 404. A body that names neither expected_claimed_at nor expected_focus_id is 422 (like any schema-invalid body), except that with Focus on an alarm reserved for another operator's focus with no live claim answers 409 claim_changed with the current reservation.

expected_focus_idstring uuid nullable

Claim-lock R5 (Focus). The reservation.focus_id the console showed. Required to take over an alarm that is reserved for another operator's focus and has no live claim (together with expected_holder_id = the focuser); otherwise the answer is 409 claim_changed with the current reservation. When expected_claimed_at is omitted and a live claim exists, it is not compared: the answer is 409 claim_changed carrying that claim.

Response

Successful Response

renewedboolean 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.

Changes

No recorded changes to this operation across all 3 revisions of this API.