VEverdun
events

Live alarm claims in the caller's scope (claims-only read)

What a console refetches on the claims_changed stream message instead of the whole queue. The live claims (operator_id, operator_name, claimed_at, expires_at, expires_in_seconds) on queued alarms in the caller's tenant scope, keyed by event id, with the queue's own membership predicate. An alarm with no live claim is absent, so for the alarms the request covers absence means free. Optional site_id and repeated event_ids (at most 500) narrow what is covered. Central staff only: customer-side callers get an empty map and never staff identity. activity (claim-lock R2) is a sibling map of escalation activity per event id (a valid intent and/or live calls, derived from the session records); it is NOT inside claims because activity outlives the claim. A keyed read (event_ids) covers every queued alarm named, an unfiltered or site_id-only read the alarms with a live claim; empty while CLAIM_ESCALATION_ENABLED is off. 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). Malformed ids are 404; also 404 while CLAIM_CLEANUP_ENABLED is off (read claim_cleanup_enabled on GET /auth/me first).

get/events/claims

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

Query parameters

site_idstring nullable

Only alarms at this site.

event_idsstring[] nullable

Only these alarms (repeat the parameter); at most 500 IDs to bound a single explicit filter. This cap does not limit an unfiltered response's size.

Response

Successful Response

claimsobject required

Live claim per event id for the queued alarms the caller may see (their tenant scope, the queue's own membership predicate), optionally narrowed by site_id / event_ids. An alarm with no live claim is ABSENT: for every alarm the request covers, absence means nobody holds it. Empty for customer-side callers, who cannot read staff identity.

activityobject

Escalation activity per event id (claim-lock R2): a valid escalation intent (Voice Down opened, Escalate - dispatch picked) and/or live calls, talk-downs and dispatches derived from the session records. NOT inside claims: activity outlives the claim (a call keeps going after a lapse or a take-over), so an alarm can be in activity without being in claims. A keyed read (event_ids) covers every queued alarm named; an unfiltered or site_id-only read covers the alarms with a live claim. Empty while CLAIM_ESCALATION_ENABLED is off and for customer-side callers.

reservationsobject

Claim-lock R5 (Focus): the alarms reserved for a focuser, per event id. A reservation is NOT a claim: it has no TTL, it lives under the focuser's ordinary claim and outlives it, and an alarm can be here with or without being in claims (while a live claim exists the console shows the claim, afterwards the reservation). A keyed read covers every queued alarm named; an unfiltered or site_id read adds the alarms that carry a valid reservation. Empty while FOCUS_ENABLED is off and for customer-side callers.

Changes

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