---
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.
  - `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/versions/14d93e5115dd/schema)