---
title: "Update node SNMP communication configuration"
method: PATCH
path: "/v1/objects/{object-id}/snmp"
tags: ["Objects"]
---

# Update node SNMP communication configuration

`PATCH /v1/objects/{object-id}/snmp`

Update the node's SNMP communication settings: protocol version, UDP port, proxy
node, codepage, the "prevent automatic SNMP configuration changes" lock, the polling
credentials, and (optionally) separate SNMP trap reception credentials. Merge-patch
semantics: any subset of fields can be sent; omitted fields are left unchanged.

`authName` holds the community string for SNMP v1/v2c and the USM user name for SNMP
v3. When `version` is present it is applied first (so `authName` is stored in the
correct slot) and is clamped up to the server-wide minimum SNMP version. The v3
`authMethod`, `privMethod`, `authPassword` and `privPassword` fields are only
meaningful for SNMP v3.

The `trap` object configures separate credentials for received SNMP traps and is
itself merge-patched (creating the trap credentials if they did not exist yet);
sending `trap: null` reverts to using the polling credentials. `authPassword` and
`privPassword` are write-only and are never returned by GET unless sensitive data is
explicitly requested.

This property group applies to Node objects only; sending it to any other object
class returns 400.

## Path parameters

- `object-id` integer, required

## Request body

- SnmpConfig — SNMP communication property group for a node. Returned by GET /v1/objects/{id}/snmp and embedded as `ObjectDetails.snmp`; accepted by PATCH /v1/objects/{id}/snmp with merge-patch semantics (omitted fields are left unchanged).
  - `version` '1' | '2c' | '3' | 'default' — SNMP protocol version used for polling. Clamped up to the server minimum SNMP version.
  - `port` integer — SNMP UDP port.
  - `proxy` integer, nullable — ID of the node used as SNMP proxy, or 0 for no proxy.
  - `codepage` string, nullable — Codepage used to decode SNMP string values (empty for server default).
  - `settingsLocked` boolean — Prevent automatic SNMP configuration changes by configuration polls.
  - `authName` string, nullable — Community string for SNMP v1/v2c, or USM user name for SNMP v3.
  - `authMethod` 'NONE' | 'MD5' | 'SHA1' | 'SHA224' | 'SHA256' | 'SHA384' | 'SHA512' — SNMP v3 authentication method.
  - `authPassword` string, nullable — SNMP v3 authentication password (write-only).
  - `privMethod` 'NONE' | 'DES' | 'AES-128' | 'AES-192' | 'AES-256' — SNMP v3 privacy (encryption) method.
  - `privPassword` string, nullable — SNMP v3 privacy password (write-only).
  - `contextName` string, nullable — SNMP v3 context name.
  - `trap` SnmpTrapCredentials — Separate SNMP trap reception credentials. Merge-patched onto the existing trap credentials; omitted fields are left unchanged. When the trap credentials are being created (none existed before) the version defaults to 2c.
    - `version` '1' | '2c' | '3' — SNMP version of the expected traps.
    - `authName` string — Trap community string (v1/v2c) or USM user name (v3).
    - `authMethod` 'NONE' | 'MD5' | 'SHA1' | 'SHA224' | 'SHA256' | 'SHA384' | 'SHA512' — SNMP v3 authentication method for traps.
    - `authPassword` string, nullable — SNMP v3 trap authentication password (write-only).
    - `privMethod` 'NONE' | 'DES' | 'AES-128' | 'AES-192' | 'AES-256' — SNMP v3 privacy method for traps.
    - `privPassword` string, nullable — SNMP v3 trap privacy password (write-only).
  - `agents` SnmpAgentConfig[] — Additional SNMP agents configured on the node, referenced by name from data collection items. On PATCH the array fully replaces the existing list (it is not merged element-wise); agent names must be unique within the node.
    - `name` string, required — Agent name, unique within the node. Referenced from data collection items.
    - `address` string, nullable — IP address of the agent, or null to use the node's primary IP address.
    - `port` integer — SNMP UDP port (defaults to 161 when omitted on creation).
    - `version` '1' | '2c' | '3', required — SNMP protocol version.
    - `authName` string, nullable — Community string for SNMP v1/v2c, or USM user name for SNMP v3.
    - `authMethod` 'NONE' | 'MD5' | 'SHA1' | 'SHA224' | 'SHA256' | 'SHA384' | 'SHA512' — SNMP v3 authentication method.
    - `authPassword` string, nullable — SNMP v3 authentication password (returned only with credential access).
    - `privMethod` 'NONE' | 'DES' | 'AES-128' | 'AES-192' | 'AES-256' — SNMP v3 privacy (encryption) method.
    - `privPassword` string, nullable — SNMP v3 privacy password (returned only with credential access).
    - `contextName` string, nullable — SNMP context name.

## Response `200`

SNMP configuration updated; full updated object returned.

- ObjectDetails
  - `alias` string — Object alias
  - `category` integer — Object category ID
  - `chassisPlacementConfig` ChassisPlacement — Placement geometry of an object within a chassis. Returned both in the chassis layout and as the `chassisPlacementConfig` property of a node.
    - `image` string, uuid — GUID of the image representing the component
    - `height` integer — Component height
    - `heightUnits` integer — Units for height (0 = rack units, 1 = millimeters)
    - `width` integer — Component width
    - `widthUnits` integer — Units for width (0 = horizontal pitch, 1 = millimeters)
    - `positionHeight` integer — Vertical position of the top-left corner
    - `positionHeightUnits` integer — Units for vertical position (0 = rack units, 1 = millimeters)
    - `positionWidth` integer — Horizontal position of the top-left corner
    - `positionWidthUnits` integer — Units for horizontal position (0 = horizontal pitch, 1 = millimeters)
    - `orientation` integer — Orientation (1=front, 2=rear)
  - `class` 'AccessPoint' | 'AgentPolicyLogParser' | 'Asset' | 'AssetGroup' | 'AssetRoot' | 'BusinessService' | 'BusinessServiceProto' | 'BusinessServiceRoot' | 'Chassis' | 'Cluster' | 'Condition' | 'Container' | 'Dashboard' | 'DashboardGroup' | 'DashboardRoot' | 'Generic' | 'Interface' | 'MobileDevice' | 'Network' | 'NetworkMap' | 'NetworkMapGroup' | 'NetworkMapRoot' | 'NetworkService' | 'Node' | 'NodeLink' | 'Rack' | 'Report' | 'ReportGroup' | 'ReportRoot' | 'Sensor' | 'ServiceCheck' | 'ServiceRoot' | 'Subnet' | 'Template' | 'TemplateGroup' | 'TemplateRoot' | 'VPNConnector' | 'Zone'
  - `customAttributes` CustomAttribute[] — Custom attributes defined on the object (including those inherited from parent objects).
    - `name` string — Attribute name.
    - `value` string — Attribute value.
    - `flags` object — Attribute flags as named booleans.
      - `inheritable` boolean — Attribute is inherited by child objects.
      - `redefined` boolean — Inherited attribute is redefined on this object.
      - `conflict` boolean — Attribute is inherited from multiple parents with differing values.
    - `sourceObject` integer — ID of the object an inherited attribute originates from; 0 if defined directly on this object.
  - `effectiveRights` EffectiveRights — Access rights the calling user effectively has on the object. Rights assigned directly on the object, including those granted through a group the user belongs to, replace rights inherited from parent objects rather than adding to them - inherited rights apply only when the object has no access control entry matching the user. Same set of rights NXCP clients obtain with CMD_GET_EFFECTIVE_RIGHTS. Every right is always present as separate boolean attribute. Value is specific to the calling user rather than part of the object's stored state, and is ignored if present in a request body.
    - `read` boolean — Read object (see it in object listings and read its basic attributes)
    - `modify` boolean — Modify object configuration
    - `createChildObjects` boolean — Create child objects
    - `delete` boolean — Delete object
    - `viewAlarms` boolean — View alarms associated with the object
    - `accessControl` boolean — Read and modify object's access control list
    - `updateAlarms` boolean — Acknowledge and update alarms associated with the object
    - `sendEvents` boolean — Send events on behalf of the object
    - `control` boolean — Execute control operations on the object - agent commands, wake-on-LAN, object tools, SSH commands, and TCP proxy. Does not cover changing management status, which requires "modify".
    - `terminateAlarms` boolean — Terminate and resolve alarms associated with the object
    - `pushData` boolean — Push data collection values to the object
    - `createHelpdeskTicket` boolean — Create helpdesk tickets from alarms associated with the object
    - `downloadFiles` boolean — Download files from the node
    - `uploadFiles` boolean — Upload files to the node
    - `manageFiles` boolean — Manage files on the node (rename, move, delete)
    - `controlMaintenanceMode` boolean — Enter and leave maintenance mode
    - `readAgentData` boolean — Read data provided by NetXMS agent
    - `readSnmpData` boolean — Read data provided via SNMP
    - `takeScreenshot` boolean — Take screenshot on the node
    - `editMaintenanceJournal` boolean — Create and edit maintenance journal entries
    - `configureAgent` boolean — Change agent configuration on the node
    - `editComments` boolean — Edit object comments
    - `manageResponsibleUsers` boolean — Manage list of users responsible for the object
    - `delegatedRead` boolean — Read the object indirectly when it is reached through a dashboard or network map the user is allowed to read, without holding "read" on the object itself
    - `managePolicies` boolean — Manage agent policies (template objects only)
    - `manageIncidents` boolean — Manage incidents associated with the object
    - `readCredentials` boolean — Read object's credentials (SNMP communities, agent secrets, and similar)
    - `queryWebService` boolean — Query web services defined on the node
    - `uploadDeviceConfig` boolean — Upload configuration to network device
    - `readDeviceConfig` boolean — Read configuration of network device
    - `readDataCollectionConfig` boolean — Read data collection configuration
    - `executeScript` boolean — Execute ad-hoc scripts in the context of the object
  - `guid` string, uuid — Object GUID
  - `id` integer — Object ID
  - `name` string — Object name
  - `responsibleUsers` object[] — Users or groups responsible for the object (the object's own list; entries inherited from parent objects are not included).
    - `userId` integer — User or group ID
    - `tag` string — Responsible user tag
  - `timestamp` string, date-time — Object last change timestamp
  - `status` 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8
  - `pollStates` PollState[] — Per-poll-type state. Present only for pollable objects (e.g. nodes, sensors, interfaces); one entry per poll type the object accepts.
    - `name` string — Poll type name (e.g. "status", "configuration", "instance", "discovery", "topology", "routing-table", "icmp", "autobind", "map-update").
    - `pending` boolean — True if a poll of this type is currently queued or in flight.
    - `lastCompleted` string, date-time, nullable — Timestamp of the most recent successful completion, or null if this poll type has never completed since server start.
    - `timer` object — Poll duration statistics in milliseconds. Omitted when the poll type has never completed (lastCompleted is null).
      - `last` integer — Duration of the most recent completed poll (ms).
      - `average` integer — Rolling average poll duration (ms).
      - `min` integer — Minimum observed poll duration (ms).
      - `max` integer — Maximum observed poll duration (ms).

## Other responses

- `400` — Malformed request body, invalid value, or property group not applicable to object class.
- `401` — Unauthorized
- `403` — User does not have modify access to the object
- `404` — Object with given ID does not exist

---

[API](https://skmtc.net/netxms/apis/netxms-api.md) · [All operations](https://skmtc.net/netxms/apis/netxms-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/netxms/netxms-api/revisions/ae3bfc65fa61/schema)