---
title: "Import Inventory Nodes"
method: POST
path: "/api/admin/inventory/nodes"
tags: ["admin-inventory"]
---

# Import Inventory Nodes

`POST /api/admin/inventory/nodes`

Create or update inventory nodes in bulk. Optionally assign them to a cluster.

This is an upsert. The service matches a node by (name, siteId). For an
existing node, it overwrites the host vars. With ansible_groups, it replaces
the cluster additional.ansibleGroups. Because the operation is an upsert,
both inventory:create and inventory:update are required and scoped to
clusterId. The audit records the acting admin. The prime-admin import command
also needs inventory:read for resolution and collision preflight.

## Request body

- NodeImportRequest — Bulk create/upsert nodes (e.g. from a parsed inventory.ini). Batch fields apply to every node; nodes upsert by (name, site_id). `site_id` is required. When `cluster_id` is given the nodes are also assigned to that cluster (with the shared assignment attrs below); otherwise they are just created.
  - `siteId` string, required
  - `clusterId` string, nullable
  - `tenantId` string, nullable
  - `status` 'ACTIVE' | 'PLANNED' | 'DECOMMISSIONING' | 'INVENTORY' | 'OFFLINE' | 'FAILED'
  - `role` 'GPU_NODE' | 'CPU_NODE'
  - `gpuCount` integer, nullable
  - `nodeTypeId` string, nullable
  - `ansibleGroups` object, nullable
  - `assignmentType` 'STANDARD' | 'FAILOVER'
  - `isController` boolean
  - `priceHr` number, nullable
  - `startDate` string, date-time, nullable
  - `notes` string, nullable
  - `reassign` boolean
  - `nodes` NodeImportRow[], required
    - `name` string, required
    - `publicIp` string, nullable
    - `publicIpv6` string, nullable
    - `privateIp` string, nullable
    - `privateInterface` string, nullable
    - `sshUser` string, nullable
    - `serial` string, nullable
    - `assetTag` string, nullable
    - `sshPort` integer, nullable
    - `description` string, nullable
    - `comments` string, nullable
    - `storage` object, nullable
    - `configContext` object, nullable
    - `additional` object, nullable

## Response `201`

Successful Response

- GenericResponseMutationResult
  - `data` MutationResult
    - `operationId` string, required
    - `targetId` string, nullable
    - `targetName` string, nullable
    - `message` string, required
    - `created` integer, nullable
    - `updated` integer, nullable
    - `assigned` integer, nullable
  - `status` string, nullable — Response status

## Other responses

- `401` — Authorization failed
- `403` — Insufficient permissions
- `422` — Invalid request data

---

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