events

Next alarm: claim the oldest eligible unheld alarm in one call

One call hands the caller an unheld, unreserved alarm, ALREADY CLAIMED, in one transaction, chosen best-effort among the alarms the statement can see and lock. Order: any eligible alarm queued at least 45 s first (oldest of those first); below that the caller's own Focus alarms; then the oldest in the queue (queued_at, then id). Severity does not sort the hand-out. Never a live-held alarm (including the caller's own), an alarm validly reserved for another operator's Focus, or (with CLAIM_ESCALATION_ENABLED on) an alarm with a live call or announcement in progress (a snapshot read, not a commit-time guarantee). Two operators pressing at once get distinct alarms. The claim is an ordinary claim (120 s TTL, renewed by the review page, a fresh ownership generation). Manual clicks and Take over are unchanged.

request_id identifies ONE press: retrying the same id (a lost response, a timeout) returns the RECORDED result with the alarm's current state (replay: true; current is yours, taken_over, closed, lapsed, reserved, out_of_scope or unavailable) and never selects a second alarm; the record is kept 24 hours. status: none carries a reason and grouped counts inside the caller's scope: empty, all_held, all_reserved, all_in_session, contended (others are picking right now), scan_budget (the 200-row scan stopped early; pick from the list) or not_a_claimant (owners never take claims). 503 outcome: not_applied (this call established that the request_id has no record AND its allocation was rolled back: nothing claimed, the id may be abandoned) or unknown (anything else: a failure before the record was looked up, while replaying it, or after the COMMIT may have been sent; keep the id and retry the SAME request_id, the server's record decides) with Retry-After. Requires review_label_alarms and central staff (403 otherwise). 404 as if the route did not exist while CLAIM_NEXT_ENABLED is off (read claim_next_enabled on GET /auth/me).

post/events/claims/next

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

Request body

request_idstring uuid required

One per key press, generated by the console. Reuse it ONLY to retry that same press (a timeout, a lost response, a 503 unknown): the server answers a recorded press from its record and never selects a second alarm. A deliberate new press uses a new id. The record is kept for 24 hours.

source'queue_key' | 'queue_button' | 'review_key' | 'review_button' required

Where the press came from. Logged and recorded; it never changes the selection.

Example request

{
  "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "source": "queue_key"
}

Response

Successful Response

status'claimed' | 'none' required

claimed: an alarm (see current). none: nothing could be claimed (see reason).

replayboolean required

True when this answers a RECORDED press (a retry of the same request_id); a replay never selects, stamps or extends anything.

current'yours' | 'taken_over' | 'closed' | 'lapsed' | 'reserved' | 'out_of_scope' | 'unavailable' nullable

claimed only. The alarm's state NOW (read under the event row lock), never a promise of ownership the caller no longer has. A fresh handout is always yours. A replay may be any value; navigate automatically only for yours.

event_idstring nullable

The alarm. Omitted for out_of_scope and unavailable replays.

alarmobject nullable

The queue row (the GET /operator/events/all row shape) for yours; null if hydration did not finish in its budget (the claim stands and event_id identifies the alarm: fetch it).

tierstring nullable

A display / log LABEL (critical, high, medium) of the handed-out alarm. Never an ordering input.

queued_atstring nullable

When the handed-out alarm entered the queue (ISO 8601, UTC): the clock the card shows.

reasonstring nullable

none only: empty, all_held, all_reserved, all_in_session, contended, scan_budget or not_a_claimant.

recorded_atstring nullable

Replay only: when the press was recorded.

as_ofstring nullable

Replay only: the server time current describes.

Changes

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