speakers

Create Speaker

post/sites/{site_id}/speakers

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/sites/{site_id}/speakers
Auth
HTTP bearer

Path parameters

site_idstring required

Request body

labelstring required

Display name for this speaker.

brand'axis'

model'axis_c1310_e' | 'axis_c1210_e' | 'axis_c1310_e_mk2'

hoststring required

IP address of the speaker, reachable from api-backend. IP LITERALS ONLY (IPv4 or IPv6) — a hostname is rejected, because a name can only be validated against what DNS answers at that moment while delivery re-resolves later; hostname support arrives with pinned resolution. Stored canonically (lowercased, IPv6 compressed), so one device has one spelling.

portstring

Device web port: the HTTPS port for direct_https (typically 443), the HTTP port for direct_http (typically 80).

usernamestring required

Device account username.

passwordstring required

Device account password. Stored in Secrets Manager only, never returned.

transport'direct_https' | 'direct_http' | 'nvr_proxy'

clip_idstring nullable

Id of the pre-loaded deterrent clip on the device. Without it the speaker cannot announce.

clip_paramsobject nullable

Playback parameters (volume, repeat). Only known VAPIX keys are sent to the device.

enabledboolean

Kill switch: a disabled speaker is skipped by delivery and by the health poll.

sip_enabledboolean

Whether the AI voice agent may place a SIP call to this speaker. Default false: it stays false until the device has been configured for SIP (a peer-to-peer account and STUN), because there is no state we can infer that from. The agent's speaker resolution reads it; the operator's Talk Down and live talk do not.

sip_account_idstring nullable

Which of the device's SIP accounts to place the call from. Omit for the device default.

mic_enabledboolean

Whether this unit's microphone is live. Informational: it tells the agent whether to pause and listen for a reply, rather than leaving ten seconds of silence at a deaf horn.

map_xnumber nullable

Normalized floor-plan x (0 = left edge, 1 = right edge).

map_ynumber nullable

Normalized floor-plan y (0 = top edge, 1 = bottom edge).

map_latnumber nullable

Geographic latitude of the speaker pin.

map_lngnumber nullable

Geographic longitude of the speaker pin.

map_location_labelstring nullable

Operator-facing location prose.

Example request

{
  "label": "SE Horn — dumpster",
  "host": "167.20.111.104",
  "port": "443",
  "username": "root",
  "password": "<PASSWORD>",
  "clip_id": "1",
  "clip_params": {
    "repeat": 1,
    "volume": 80
  },
  "sip_account_id": "sip_account_1",
  "map_x": 0.42,
  "map_y": 0.63,
  "map_lat": 42.0443,
  "map_lng": -87.9825,
  "map_location_label": "SE corner — by the dumpster"
}

Response

Successful Response

idstring uuid required

The speaker record ID.

site_idstring uuid required

The site this speaker belongs to.

parent_idstring uuid required

The client this speaker belongs to.

labelstring required

Display name.

brand'axis' required

model'axis_c1310_e' | 'axis_c1210_e' | 'axis_c1310_e_mk2'

hoststring required

IP address of the speaker (IPv4 or IPv6 literal), in canonical form. Hostnames are not supported in v1.

portstring required

HTTPS port.

usernamestring required

Device account username (the password is never returned).

transport'direct_https' | 'direct_http' | 'nvr_proxy' required

clip_idstring nullable

Id of the pre-loaded deterrent clip.

clip_paramsobject nullable

Playback parameters.

enabledboolean required

Whether delivery and the health poll consider this speaker.

sip_enabledboolean

Whether the AI voice agent may place a SIP call to this speaker.

sip_account_idstring nullable

Which of the device's SIP accounts the agent's call is placed from; null means the device default.

mic_enabledboolean

Whether this unit's microphone is live, which decides whether the agent waits for a reply.

onboarding_checklistobject nullable

The device-setup checklist: the owner's own attestations under items, each stamped server-side. An absent key means not confirmed. The one item the device answers for itself is NOT stored here — read it live from GET /speakers/{id}/sip-accounts.

agent_armed_camera_countinteger nullable

How many of this speaker's camera mappings are ARMED for the AI agent. Zero means nothing will ever announce here, however the device is configured.

map_xnumber nullable

Normalized floor-plan x.

map_ynumber nullable

Normalized floor-plan y.

map_latnumber nullable

Geographic latitude of the speaker pin.

map_lngnumber nullable

Geographic longitude of the speaker pin.

map_location_labelstring nullable

Operator-facing location prose.

map_headingnumber nullable

Direction a horn faces, degrees clockwise from map-up; null = not aimed (always null for an omnidirectional ceiling unit).

healthyboolean nullable

Last health-poll result.

last_healthcheck_atstring date-time nullable

When the speaker was last polled.

health_errorstring nullable

Why the last health poll failed: unreachable (no HTTP answer), auth_rejected (the device answered 401 to the stored credentials), not_a_speaker (something answered, but not an Axis device API - e.g. a router page), clip_missing (the configured clip id is not on the device), or error. Null when healthy or never checked.

device_serialstring nullable

Serial number of the device last seen at this host:port, read without credentials. Compare it across speakers to tell two units behind one IP apart. Last known value; a failed poll keeps it.

device_productstring nullable

Product name of the device last seen at this host:port (ProdFullName, else ProdNbr). Last known value.

device_firmwarestring nullable

Firmware version of the device last seen at this host:port. Last known value.

device_identity_atstring date-time nullable

When the device identity above was last read successfully.

created_atstring date-time nullable

When the speaker was registered.

updated_atstring date-time nullable

When the speaker was last edited.

Example response

{
  "label": "SE Horn — dumpster",
  "host": "167.20.111.104",
  "port": "443",
  "username": "root",
  "clip_id": "1",
  "clip_params": {
    "volume": 80
  },
  "sip_account_id": "sip_account_1",
  "onboarding_checklist": {
    "items": {
      "audio_direction": {
        "done_at": "2026-09-11T18:20:44Z",
        "operator_id": "..."
      }
    },
    "version": 1
  },
  "agent_armed_camera_count": 2,
  "map_location_label": "SE corner — by the dumpster",
  "map_heading": 180,
  "health_error": "auth_rejected",
  "device_serial": "B8A44FA89513",
  "device_product": "AXIS C1310-E Network Horn Speaker",
  "device_firmware": "11.11.192"
}

Changes

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