VEverdun
focus

Take over a site another operator holds

Site-level Take over, one confirm. Body {expected_operator_id, expected_focus_id?} names the hold the console showed. If it is still that holder's valid hold, in one transaction it is released (taken_over) and the caller's hold is created IN THE SAME LINEAGE, so every held alarm stays held, now for the caller, with no gap; the displaced operator's live claims at the site then move to the caller. 200 with the caller's new hold record (also when the caller already holds it, which writes nothing). Otherwise nothing moves: 409 claim_changed with hold = the valid hold at the site now (or null). Open to every central-staff claim participant, owners included; a taker without review_label_alarms can act on the alarms but not label them. 403 out of scope or not central staff. 404 while SITE_HOLD_ENABLED is off.

post/focus/{hold_id}/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/focus/{hold_id}/take-over
  • Auth
    HTTP bearer

Path parameters

hold_idstring required

Request body

expected_operator_idstring uuid required

The holder the console showed (operator_id of the record).

expected_focus_idstring uuid nullable

The hold the console showed; must equal the path id when present.

Response

Successful Response

origin'story' required

Always story.

idstring required

The hold id (a site Take over creates a successor with a new id in the same lineage).

lineage_idstring required

Shared by a hold and its Take over successors.

site_idstring required

The site the hold is on.

operator_idstring required

The holder.

operator_namestring nullable

Their display name; null if the operator no longer exists.

started_atstring required

ISO 8601, UTC.

last_seen_atstring nullable

The holder's last heartbeat (ISO 8601, UTC).

left_atstring nullable

Set by the holder's best-effort leave signal, cleared by a heartbeat inside the grace. After a clean leave the hold returns its alarms about 30 s after this instant (a fixed server constant), or sooner on its idle or new-alert deadline.

openboolean required

True while the holder's page is open: no clean leave and a heartbeat within open_s. While true there is no deadline of any kind.

return_atstring nullable

When the unattended hold returns its alarms to the queue (ISO 8601, UTC); null while open. The earliest of the idle deadline, the new-alert deadline and (after a clean leave) 30 s after left_at, pushed later by a live call. A display, never a decision.

nowstring required

The server clock this record was built against: compute return_at - now once and tick it locally.

serious_unopenedinteger

Serious alarms the current holder has not opened (visibility only).

oldest_serious_queued_atstring nullable

When the oldest of those entered the queue (ISO 8601, UTC).

open_seconds_totalinteger

Seconds the holder's page was open during the hold (each interval since the last heartbeat, capped at open_s, settled at the next heartbeat, a leave or the release).

idle_sinteger required

Frozen at start: seconds since the last heartbeat before an unattended hold returns. The backstop for a page that vanished without a clean leave; after a clean leave the hold returns about 30 s later instead (a fixed server constant, not frozen).

new_alert_sinteger required

Frozen at start: seconds after a new alert before an unattended hold returns.

open_sinteger required

Frozen at start: seconds since the last heartbeat within which the page still counts as open.

state'active' | 'released' required

active while it holds the site.

released_atstring nullable

ISO 8601, UTC; null while active.

release_reason'idle_2min' | 'new_alert_2min' | 'holder_gone' | 'submit' | 'taken_over' | 'flag_off' | 'scope_lost' | 'disabled' nullable

Why it ended; null while active. idle_2min is the unattended return after a clean leave (about 30 s after it, or the idle deadline if that came first; the name is historical, not a measured 2 minutes); holder_gone is the idle deadline with no clean leave.

Changes

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