---
title: "Update common object properties"
method: PATCH
path: "/v1/objects/{object-id}"
tags: ["Objects"]
---

# Update common object properties

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

Update common scalar properties on any NetObj. Request body uses JSON merge-patch
semantics (RFC 7396) — fields present in the body are updated, fields omitted are
left untouched, and explicit `null` clears the field. Returns the updated object
in the same shape as `GET /v1/objects/{object-id}`. Class-specific property groups
(snmp, agent, polling, etc.) are exposed as separate sub-resources.

Requires modify access to the object. A user holding only the "edit comments" access
right may send a patch document containing `comments` as its only property.

## Path parameters

- `object-id` integer, required

## Request body

- object — Merge-patch document with any subset of the listed properties.
  - `name` string — Object name (control characters are replaced with spaces).
  - `alias` string, nullable — Object alias. `null` or empty string clears the alias.
  - `nameOnMap` string, nullable — Display name used on network maps. `null` clears the override.
  - `comments` string, nullable — Free-form object comments. `null` or empty string clears them.
  - `category` integer, nullable — Object category ID. `null` or `0` clears the category.
  - `mapImage` string, uuid, nullable — Image library UUID for the object on maps. `null` clears the image.
  - `drilldownObjectId` integer, nullable — ID of the object opened on drill-down. `null` or `0` clears the link.
  - `macAddress` string — Interface only. MAC address in any accepted textual notation. Allowed only for manually created interfaces; rejected otherwise.
  - `requiredPollCount` integer — Interface only. Number of consecutive polls required to change status.
  - `expectedState` integer — Interface only. Expected interface state (0 = UP, 1 = DOWN, 2 = IGNORE, 3 = AUTO).
  - `peer` integer, nullable — Interface only. ID of the peer interface to link to. Establishes a manual bidirectional peer link (any previous peer on either side is cleared) and requires modify access on the peer interface. `null` or `0` clears the current peer.
  - `primaryName` string — Node only. Primary host name, either a DNS name or a literal IP address. The node's primary IP address is derived from it and is updated by the forced configuration poll that a change schedules — it is not settable on its own. If the name resolves to an address that does not belong to any of the node's interfaces, that address must not already be used by another node or subnet (this check is skipped for an external gateway). A name that does not resolve is accepted.

## Response `200`

Object 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 are resolved at the object in this order: if an access control entry names the user directly, that entry alone is used; otherwise the entries for all groups the user belongs to are combined; otherwise, if the object is set to inherit, the effective rights resolved independently on each parent object are combined. An entry granting no rights still counts as a match: a user entry granting nothing suppresses both groups and parents, while a group entry granting nothing suppresses only parents and the other matching groups are still combined. This is the 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 or invalid property value.
- `401` — Unauthorized
- `403` — User does not have modify access to the object (or to the peer interface), or holds only the "edit comments" right and the patch document changes properties other than comments
- `404` — Object with given ID does not exist
- `409` — IP address resolved from the new primary host name is already used by another node or subnet.

## Changes

- **2026-09-03** `1a49230299d8` — 2 info
  - added the new optional request property `primaryName`
  - added the non-success response with the status `409`
- **2026-08-19** `04731b73e723` — 1 info
  - added the optional property `effectiveRights` to the response with the `200` status
- **2026-07-11** `8a5c10fc82a9` — 4 info
  - added the new optional request property `expectedState`
  - added the new optional request property `macAddress`
  - added the new optional request property `peer`
  - added the new optional request property `requiredPollCount`
- **2026-06-04** `57123b75bbe6` — 1 info
  - added the optional property `chassisPlacementConfig` to the response with the `200` status
- **2026-06-02** `051240cd3a79` — 1 info
  - added the optional property `customAttributes` to the response with the `200` status

[Full history](https://skmtc.dev/netxms/apis/netxms-api/changes/v1/objects/:object-id/patch.md)

---

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