---
title: "Clear the escalation record (compare-and-clear)"
method: POST
path: "/events/{event_id}/claim/acting/cancel"
tags: ["events"]
---

# Clear the escalation record (compare-and-clear)

`POST /events/{event_id}/claim/acting/cancel`

## 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/acting/cancel`
- Auth: HTTP bearer

Ends the caller's own escalation intent when, and only when, the ownership `generation` AND the `action_token` still match: a stale generation (another holder, a re-acquire) is 409 `claim_changed` / `claim_held`; a token this alarm has not seen that is not the current one is 409 `activity_changed` with the current `claim` and `activity`, and nothing is cleared. A token that already finished or was replaced by a newer pick (the row remembers the newest 32 of its generation) is `already_clear`, nothing written. 200 outcomes: `cleared`, `already_clear` (a retried or late cancel) and `alarm_closed` (the close already cleared it). `reason` is `cancelled`, `panel_closed` or `completed`. 404 while `CLAIM_ESCALATION_ENABLED` is off.

## Path parameters

- `event_id` string, required

## Request body

- CancelClaimActingRequest: Body of `POST /events/{id}/claim/acting/cancel`.
  - `generation` string, uuid, required: `claim.generation` the console holds.
  - `action_token` string, required: The token sent with the set this cancels.
  - `reason` 'cancelled' | 'panel_closed' | 'completed', required: `cancelled`: the operator backed out. `panel_closed`: dismissed or navigated away. `completed`: the action finished.

## Response `200`

Successful Response

- ClaimActingCancelResponse
  - `claim` AlarmClaim
    - `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).
  - `activity` ActivityPayload
    - `state` 'preparing' | 'active', required: `active` iff at least one live session record exists (operator or automated). Otherwise `preparing`: a valid intent and no session yet.
    - `operator_acting` boolean, required: True iff a valid intent exists or a live session is attributed to an operator. The console shows no red cue while this is true; the age stays visible either way. False means only an automated agent call is live.
    - `since` string, required: `preparing`: the intent's set_at. `active`: the earliest live session start (ISO 8601, UTC)
    - `elapsed_seconds` integer, required: Server-computed now - since, for the age display; time it from this against the local clock at receipt
    - `action` 'voice_down' | 'dispatch', required: Of the primary source
    - `actor` ActivityActor, required
      - `operator_id` string, nullable: The operator acting. Null for an automated agent call.
      - `operator_name` string, nullable: Their display name; null if the operator no longer exists or kind is agent.
      - `kind` 'operator' | 'agent', required: `agent` is an automated AI call: it never counts as an operator acting.
    - `intent` ActivityIntent
      - `action` 'voice_down' | 'dispatch', required: What the holder opened: the Voice Down panel, or Escalate - dispatch.
      - `set_at` string, required: When the holder opened Voice Down / picked dispatch (ISO 8601, UTC)
      - `operator_id` string, required: The operator who recorded the intent (the claim holder when it was set)
      - `operator_name` string, nullable: Their display name; null if the operator no longer exists
      - `generation` string, required: The ownership generation the intent is bound to
    - `sessions` ActivitySession[]: Live records, oldest first, at most five. Empty while `preparing`.
      - `source` 'voice_session' | 'voice_agent_call' | 'external_talkdown' | 'dispatch_call', required: Which session table the live record comes from.
      - `session_id` string, required: The id of that session record
      - `action` 'voice_down' | 'dispatch', required: `dispatch` is the grouping for every dispatch_call row; `target` says which.
      - `target` 'police' | 'guard' | 'owner', nullable: Dispatch rows only: who was dialled. An owner call is activity but is not police dispatch.
      - `status` string, required: The source's own status word (opening/live, placing/connected, requested/connected, the dispatch status)
      - `started_at` string, required: When the record started being live (ISO 8601, UTC); the source's own start time
      - `actor` ActivityActor, required
        - `operator_id` string, nullable: The operator acting. Null for an automated agent call.
        - `operator_name` string, nullable: Their display name; null if the operator no longer exists or kind is agent.
        - `kind` 'operator' | 'agent', required: `agent` is an automated AI call: it never counts as an operator acting.
  - `cleared` boolean, required: True only when this call cleared the intent
  - `outcome` 'cleared' | 'already_clear' | 'alarm_closed', required: `cleared`: this call ended it. `already_clear`: nothing current (a retried cancel). `alarm_closed`: the close already cleared it.

## 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/35a2a6ebedda?raw)