---
title: "Create a new object"
method: POST
path: "/v1/objects"
tags: ["Objects"]
---

# Create a new object

`POST /v1/objects`

Create a new object. The caller must have CREATE access on the parent object (or on
the entire network when creating a top-level node). The `class` field selects the
object type and determines which additional fields are meaningful; fields not relevant
to the selected class are ignored. After construction the same document is applied to
the new object using merge-patch semantics (see `PATCH /v1/objects/{object-id}`), so
common scalar properties such as `comments` and `alias` can be set in the same call.
On success the full created object is returned and the `Location` header points to it.

## Request body

- ObjectCreationRequest — Object creation document. Common fields apply to every class; the remaining fields are only meaningful for the class indicated by `class` (and are ignored otherwise). Any common scalar property accepted by `PATCH /v1/objects/{object-id}` may also be supplied and is applied to the new object after construction.
  - `class` 'Subnet' | 'Node' | 'Interface' | 'Container' | 'Zone' | 'Template' | 'TemplateGroup' | 'NetworkService' | 'VPNConnector' | 'Condition' | 'Cluster' | 'BusinessServiceProto' | 'Asset' | 'AssetGroup' | 'NetworkMapGroup' | 'NetworkMap' | 'Dashboard' | 'DashboardTemplate' | 'DashboardGroup' | 'BusinessService' | 'Collector' | 'Circuit' | 'MobileDevice' | 'Rack' | 'WirelessDomain' | 'Chassis' | 'Sensor' | 'CloudDomain', required — Symbolic object class name.
  - `name` string, required — Object name.
  - `parentId` integer — Parent object ID. Required for all classes except Node (where a parent subnet is resolved automatically from the IP address when omitted).
  - `zoneUIN` integer — Zone UIN (when zoning is enabled).
  - `comments` string — Free-form object comments.
  - `alias` string — Object alias.
  - `assetId` integer — Optional ID of an existing asset object to link to the new object.
  - `primaryName` string — (Node) Primary host name. If present it is resolved to the primary IP address.
  - `ipAddress` string — (Node/Interface/Subnet) IP address. For a node it is the primary IP address used when no primary name is given.
  - `creationFlags` integer — (Node) Bit mask controlling node creation (disable polling protocols, create unmanaged, etc.).
  - `agentPort` integer
  - `snmpPort` integer
  - `etherNetIpPort` integer
  - `etherNetIpAddress` string
  - `modbusTcpPort` integer
  - `modbusUnitId` integer — (Node/Sensor) Modbus unit ID.
  - `sshLogin` string
  - `sshPassword` string
  - `sshPort` integer
  - `vncPassword` string
  - `vncPort` integer
  - `agentProxy` integer
  - `snmpProxy` integer
  - `mqttProxy` integer
  - `modbusProxy` integer
  - `etherNetIpProxy` integer
  - `icmpProxy` integer
  - `sshProxy` integer
  - `vncProxy` integer
  - `webServiceProxy` integer
  - `ifIndex` integer — (Interface) Interface index.
  - `ifType` integer — (Interface) Interface type (IANA ifType).
  - `macAddress` string — (Interface/Sensor) MAC address.
  - `chassis` integer — (Interface) Physical chassis number.
  - `module` integer — (Interface) Physical module number.
  - `pic` integer — (Interface) Physical PIC number.
  - `port` integer — (Interface) Physical port number.
  - `physicalPort` boolean — (Interface) Whether the interface is a physical port.
  - `serviceType` integer — (NetworkService) Service type.
  - `ipProtocol` integer — (NetworkService) IP protocol number (default 6/TCP).
  - `ipPort` integer — (NetworkService) Port number.
  - `request` string — (NetworkService) Request string sent to the service.
  - `response` string — (NetworkService) Expected response string.
  - `createStatusDci` boolean — (NetworkService) Create a status DCI on the parent node.
  - `mapType` integer — (NetworkMap) Map type.
  - `mapCanvasType` integer — (NetworkMap) Canvas rendering type.
  - `seedObjects` integer[] — (NetworkMap) Seed object IDs.
  - `controllerId` integer — (Chassis) Controller node ID.
  - `height` integer — (Rack) Rack height in units.
  - `deviceId` string — (MobileDevice) Device identifier.
  - `instanceDiscoveryMethod` integer — (BusinessServiceProto) Instance discovery method.
  - `flags` integer — (Sensor) Sensor flags.
  - `deviceClass` integer — (Sensor) Sensor device class.
  - `vendor` string — (Sensor) Vendor name.
  - `model` string — (Sensor) Model.
  - `serialNumber` string — (Sensor) Serial number.
  - `deviceAddress` string — (Sensor) Device address.
  - `gatewayNode` integer — (Sensor) Gateway node ID.
  - `connectorName` string — (CloudDomain) Cloud connector name.
  - `credentials` union — (CloudDomain) Cloud credentials as a JSON object or raw JSON string.
    - string
    - object
  - `discoveryFilter` string — (CloudDomain) Resource discovery filter.
  - `removalPolicy` integer — (CloudDomain) Resource removal policy.
  - `gracePeriod` integer — (CloudDomain) Grace period in seconds before removing vanished resources.
  - `assetProperties` object — (Asset) Asset attribute values keyed by attribute name. All mandatory attributes must be present.
  - `linkedObjectId` integer — (Asset) Optional ID of an existing object to link the new asset to. Server will update asset identification (serial number or MAC address) from that object and run auto fill scripts after linking. Requires modify access to that object.

## Response `201`

Object created. Response body is the full object representation.

- 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, unknown object class, or invalid property value.
- `401` — Unauthorized.
- `403` — User does not have create access on the parent object, or node count license exceeded.
- `404` — Parent object or referenced asset does not exist.
- `409` — Conflict — subnet overlaps an existing subnet, node IP address is already in use, or zone UIN is already taken. For a subnet overlap the response body contains a `conflictingObjects` array with the identifiers of the conflicting objects.
- `500` — Object creation failed (internal error).

---

[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)