VEverdun
external-talkdowns

Create External Talkdown

Open the audit row for one talk-down attempt.

Idempotent on (operator, client_ref): a retry returns the existing row with a 200, indistinguishable from the first write. NO ACTIVITY-LOG ENTRY here — requested only records that a button was pressed, and the row itself already says so.

post/events/{event_id}/external-talkdowns

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}/external-talkdowns
  • Auth
    HTTP bearer

Path parameters

event_idstring required

Request body

provider'verkada_command' required
mode'mic' | 'clip' required
client_refstring required

The extension's per-attempt id, minted once per click. THE IDEMPOTENCY KEY: re-sending this request with the same value returns the existing row rather than opening a second one. Reusing one across two different events is a client bug and is refused with 409.

Example request

{
  "client_ref": "a1b2c3d4e5f6"
}

Response

Successful Response

idstring uuid required

The talk-down record id.

event_metadata_idstring uuid required

The alarm this was about.

camera_idstring uuid required

The camera whose vendor console was driven.

parent_idstring uuid required

The client, denormalised so a tenant-scoped read needs no join.

site_idstring uuid required

The site, denormalised for the same reason.

operator_idstring uuid nullable

Who talked. Null once that account has been deleted — the record outlives it.

provider'verkada_command' required
mode'mic' | 'clip' required
status'requested' | 'connected' | 'ended' | 'failed' required
fail_reason'timeout' | 'not_logged_in' | 'phone_not_found' | 'busy' | 'extension_error'
client_refstring required

The extension's per-attempt id; the idempotency key this row was created under.

requested_atstring date-time required

When the operator pressed the button, on the SERVER's clock.

connected_atstring date-time nullable

When the vendor console reported the call up. Null if it never did.

ended_atstring date-time nullable

When the attempt reached a terminal state.

duration_msinteger nullable

connected_at to ended_at in milliseconds. Null when the call never connected — which is the honest answer, not zero.

detailstring nullable

Free-text attempt trail. Never a URL or a token.

created_atstring date-time nullable

Row creation timestamp.

updated_atstring date-time nullable

Row update timestamp.

Example response

{
  "client_ref": "a1b2c3d4e5f6"
}

Changes

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