---
title: "Update object placement in a rack or chassis"
method: PATCH
path: "/v1/objects/{object-id}/physical-placement"
tags: ["Objects"]
---

# Update object placement in a rack or chassis

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

Place a node or chassis into a rack, place a node into a chassis, move one that is
already placed, or remove it from its container. Body uses JSON merge-patch
semantics: properties present are applied and properties omitted are left untouched.
`null` clears the value only for `containerId`, `imageFront`, `imageRear` and
`chassisPlacement`; sending `null` for `position`, `height` or `orientation` is
rejected with `400`. Setting `containerId` to `null` or `0` removes the object from
its container.

A node may be placed in a rack or in a chassis; a chassis may only be placed in a
rack. When the container is a rack, `position` and `height` must leave the object
entirely within the rack's unit range. That range is checked only when the document
supplies `containerId`, `position` or `height`, so an object whose stored `position`
or `height` a rack would reject stays patchable, and can always be removed from its
container. Placing an object into a
rack therefore requires a valid `position`, either sent in the same document or
already stored: an object that has never been placed has `position` 0 and must be
given one, otherwise the request is rejected with `400`. Overlapping placements are
**not** rejected: the model has always allowed them and some installations rely on it.

Requires modify access on the object being placed. Modify access on the target
container is not required, matching the behaviour of the native client protocol.

The same property group is also accepted as the `physicalPlacement` property of
`PATCH /v1/objects/{object-id}`. Clients should prefer this sub-resource: a server
that predates it answers `404`, which is a usable feature check, whereas the
top-level patch silently ignores property groups it does not recognise.

## Path parameters

- `object-id` integer, required

## Request body

- PhysicalPlacement — Placement of an object inside a rack or a chassis. Returned on nodes and chassis, and accepted as a merge-patch on the same objects: properties present are applied and properties omitted are left untouched. `null` clears the value only for the nullable properties `containerId`, `imageFront`, `imageRear` and `chassisPlacement`; sending `null` for `position`, `height` or `orientation` is rejected with `400`. Always present on read, with `containerId` 0 for an object that is not placed anywhere.
  - `containerId` integer, nullable — ID of the rack or chassis holding the object. `null` or `0` removes it from its current container. A node may be placed in a rack or a chassis; a chassis may only be placed in a rack. A container that is a descendant of the object being placed is rejected with `409`, since it would create a loop in the object tree.
  - `position` integer — Rack unit occupied by the object, counted from 1. Meaningful only when the container is a rack. With top-to-bottom rack numbering this is the object's topmost unit, otherwise its bottommost unit. Must leave the object entirely within the rack.
  - `height` integer — Object height in rack units.
  - `orientation` 0 | 1 | 2 — Mounting orientation (0 = fill, 1 = front, 2 = rear).
  - `imageFront` string, uuid, nullable — Image library GUID used to draw the object's front face. `null` clears it.
  - `imageRear` string, uuid, nullable — Image library GUID used to draw the object's rear face. `null` clears it.
  - `chassisPlacement` 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, nullable — GUID of the image representing the component. `null` clears it. A string that is not a well formed GUID is rejected with `400`.
    - `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)

## Response `200`

Placement 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, nullable — GUID of the image representing the component. `null` clears it. A string that is not a well formed GUID is rejected with `400`.
    - `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' | 'CoolingZone' | 'Dashboard' | 'DashboardGroup' | 'DashboardRoot' | 'Facility' | 'Generic' | 'Interface' | 'MobileDevice' | 'Network' | 'NetworkMap' | 'NetworkMapGroup' | 'NetworkMapRoot' | 'NetworkService' | 'Node' | 'NodeLink' | 'PowerDomain' | 'Rack' | 'Report' | 'ReportGroup' | 'ReportRoot' | 'Room' | '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` union — Attribute value. Plain text for regular attributes; a JSON object or array for structured attributes (`flags.json` is true).
      - string
      - object
    - `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.
      - `json` boolean — Attribute holds a structured value (JSON object or array).
    - `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
  - `physicalPlacement` PhysicalPlacement — Placement of an object inside a rack or a chassis. Returned on nodes and chassis, and accepted as a merge-patch on the same objects: properties present are applied and properties omitted are left untouched. `null` clears the value only for the nullable properties `containerId`, `imageFront`, `imageRear` and `chassisPlacement`; sending `null` for `position`, `height` or `orientation` is rejected with `400`. Always present on read, with `containerId` 0 for an object that is not placed anywhere.
    - `containerId` integer, nullable — ID of the rack or chassis holding the object. `null` or `0` removes it from its current container. A node may be placed in a rack or a chassis; a chassis may only be placed in a rack. A container that is a descendant of the object being placed is rejected with `409`, since it would create a loop in the object tree.
    - `position` integer — Rack unit occupied by the object, counted from 1. Meaningful only when the container is a rack. With top-to-bottom rack numbering this is the object's topmost unit, otherwise its bottommost unit. Must leave the object entirely within the rack.
    - `height` integer — Object height in rack units.
    - `orientation` 0 | 1 | 2 — Mounting orientation (0 = fill, 1 = front, 2 = rear).
    - `imageFront` string, uuid, nullable — Image library GUID used to draw the object's front face. `null` clears it.
    - `imageRear` string, uuid, nullable — Image library GUID used to draw the object's rear face. `null` clears it.
    - `chassisPlacement` 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, nullable — GUID of the image representing the component. `null` clears it. A string that is not a well formed GUID is rejected with `400`.
      - `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)
  - `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 (height below 1, orientation outside 0-2, position leaving the object outside the rack), a malformed image GUID, a `containerId` that does not exist or is not a rack or chassis, 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
- `409` — The requested `containerId` is a descendant of the object being placed, so the placement would create a loop in the object tree.

## Changes

- **2026-09-21** `2827204d68d9` — 1 warning
  - added the new `Room` enum value to the `class` response property for the response status `200`
- **2026-09-15** `ef2ed4fdc376` — 1 breaking, 1 info
  - response property `customAttributes/items/value` list-of-types was widened by adding types `array and object` to media type `application/json` of response `200`
  - added the optional property `customAttributes/items/flags/json` to the response with the `200` status
- **2026-09-09** `93009b998639` — 1 info
  - endpoint added
- **2026-09-08** `15170fcce677` — 1 breaking
  - api path removed without deprecation
- **2026-09-08** `4fd66f32833f` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/netxms/apis/netxms-api/changes/v1/objects/:object-id/physical-placement/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.dev/netxms/apis/netxms-api/revisions/2827204d68d9?raw)