SNMP Targets

Engineer or admin CRUD for SNMP polling targets. Each target associates a device with SNMP credentials and polling configuration for traffic monitoring.

Create SNMP Target

POST /api/v1/snmp-targets

Request body:

{
  "device_id": "uuid",
  "hostname": "10.0.0.1",
  "port": 161,
  "version": "2c",
  "community": "public",
  "v3_config": null,
  "poll_interval_seconds": 30,
  "enabled": true
}

Validation:

Response: 201 Created

{
  "id": "uuid",
  "device_id": "uuid",
  "router_id": "10.0.0.1",
  "hostname": "10.0.0.1",
  "port": 161,
  "version": "2c",
  "community": "public",
  "v3_config": null,
  "poll_interval_seconds": 30,
  "enabled": true,
  "created_at": "2026-02-18T12:00:00Z",
  "updated_at": "2026-02-18T12:00:00Z"
}

Error responses:

List SNMP Targets

GET /api/v1/snmp-targets?limit=100&offset=0

List all SNMP targets. The router_id field is joined from the associated device. Supports pagination.

Query parameters:

Response: 200 OK — Paginated envelope

{
  "data": [
    {
      "id": "uuid",
      "device_id": "uuid",
      "router_id": "10.0.0.1",
      "hostname": "10.0.0.1",
      "port": 161,
      "version": "2c",
      "community": "***",
      "v3_config": null,
      "poll_interval_seconds": 30,
      "enabled": true,
      "created_at": "2026-02-18T12:00:00Z",
      "updated_at": "2026-02-18T12:00:00Z"
    }
  ],
  "total": 1,
  "limit": 100,
  "offset": 0
}

Notes:

List Devices Without SNMP Coverage

GET /api/v1/snmp-targets/uncovered

Return the set of discovered devices that do not yet have an SNMP target configured. Used by the SNMP settings UI to surface candidates for bulk enrollment. Engineer or admin role required.

Response: 200 OK

{
  "devices": [
    {
      "device_id": "uuid",
      "router_id": "10.0.0.5",
      "hostname": "",
      "management_ip": "10.0.0.5",
      "area_id": "uuid"
    }
  ],
  "total": 1
}

Notes:

Error responses:

Get SNMP Target

GET /api/v1/snmp-targets/{targetID}

Get a single SNMP target by ID.

Path parameters:

Response: 200 OK (single SNMP target object)

Error responses:

Update SNMP Target

PUT /api/v1/snmp-targets/{targetID}

Partial update of an SNMP target. Uses read-merge-write -- only fields present in the request body are updated; other fields are preserved. The device_id cannot be changed after creation.

Path parameters:

Request body (all fields optional):

{
  "hostname": "10.0.0.2",
  "port": 1161,
  "version": "3",
  "community": null,
  "v3_config": {
    "username": "snmpuser",
    "auth_protocol": "SHA",
    "auth_password": "authpass123",
    "priv_protocol": "AES",
    "priv_password": "privpass123",
    "security_level": "authPriv"
  },
  "poll_interval_seconds": 60,
  "enabled": false
}

Response: 200 OK (updated SNMP target object)

Error responses:

Toggle SNMP Target

POST /api/v1/snmp-targets/{targetID}/toggle

Flips the enabled flag on an SNMP target without modifying any other fields. This is the preferred method for enabling/disabling targets, as it preserves credential profiles and inline credentials (unlike a partial update which may overwrite fields with zero values).

Path parameters:

Request body: Empty JSON object {}

Response: 200 OK (updated SNMP target object with toggled enabled field)

Audit: Logs toggle action on snmp_target entity with {"enabled": <new_value>}.

Error responses:

Delete SNMP Target

DELETE /api/v1/snmp-targets/{targetID}

Delete an SNMP target. The SNMP poller stops polling the target immediately.

Path parameters:

Response: 204 No Content

Error responses:

Auto-Discover SNMP Targets

POST /api/v1/snmp-targets/auto-discover

Automatically create SNMP targets for all devices that do not already have one. Devices with the is_collector flag set are skipped.

Request body:

{
  "credential_profile_id": "uuid-of-profile",
  "community": "public"
}

All fields are optional. Resolution order:

  1. credential_profile_id from request body
  2. snmp.default_credential_profile_id system setting
  3. community from request body
  4. snmp.default_community system setting
  5. Fallback: "public"

When a credential profile is used, targets are created with the profile's version (v2c or v3) and linked via credential_profile_id. When using inline community, targets are created as v2c with the community string.

Response: 200 OK

{
  "created": 12
}

Notes:

Error responses: