> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-cloud/inventory-manager/create-and-populate-inventories/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Create and populate inventories

> How to create inventories and populate them with nodes using workflows, API calls, or webhooks.

This topic explains how to create inventories and populate them with nodes using workflows, API calls, or webhooks.

Inventory Manager consumes data from your inventory systems — it is not the authoritative source for device data.

To avoid data drift, repopulate inventories from your source system.

## Create an inventory

Create inventories using Inventory Manager tasks in workflows or by calling the API directly.

**Required attributes:**

* **Name**: Unique identifier (globally unique across all inventories)
* **Groups**: One or more user groups for RBAC

**Optional attributes:**

* **Description**: Optional descriptive text
* **Actions**: Array of operations for nodes in this inventory (optional at creation)
* **Tags**: Labels for organization and filtering

### Use workflows

Use the `createInventory` task in Studio.

### Use the API

```http
POST /inventory_manager/v1/inventories
```

**Example request body:**

```json
{
  "name": "prod-routers",
  "description": "Production router inventory",
  "groups": ["network-ops", "network-admins"],
  "tags": ["production", "routers"]
}
```

**Example response:**

```json
{
  "status": "Success",
  "result": {
    "_id": "60a7c8e9f1234567890abcde",
    "name": "prod-routers",
    "description": "Production router inventory",
    "groups": ["network-ops", "network-admins"],
    "tags": ["production", "routers"],
    "actions": [],
    "created_at": "2025-01-08T10:30:00.000Z",
    "updated_at": "2025-01-08T10:30:00.000Z",
    "created_by": "admin@example.com",
    "updated_by": "admin@example.com"
  }
}
```

## Populate inventories with nodes

The `populateInventory` task replaces all nodes in an inventory with new node data. Inventory Manager federates data from your external inventory systems — it does not act as the authoritative source for device information. This full-replacement model ensures Inventory Manager accurately reflects your inventory system.

**How it works:**

1. Deletes all existing nodes in the inventory
2. Inserts the new nodes
3. Returns success or failure

Since the operation replaces all nodes, any node not included in the update is removed from the inventory.

### Node data format

Each node in the `nodes` array requires only a `name` (unique within the inventory). The `attributes` and `tags` properties are optional.

**Example node data:**

```json
{
  "name": "core-router-1",
  "attributes": {
    "itential_host": "10.1.1.1",
    "itential_platform": "iosxr",
    "cluster_id": "cluster_east",
    "itential_user": "admin",
    "itential_password": "$SECRET_path $KEY_name"
  },
  "tags": ["production", "core"]
}
```

### Use workflows to populate inventories

Workflows are the recommended approach for populating inventories because they can:

* Extract data from your source of truth
* Transform data to the required format
* Handle errors and retries
* Run on schedules to keep inventories synchronized

**Common workflow pattern:**

1. Extract device data from source system (Netbox, ServiceNow, spreadsheet, database, etc.)
2. Transform data to Inventory Manager node format
3. Call `populateInventory` task with inventory identifier and node array
4. Handle success or error responses

### Use the API to populate inventories

External systems can populate inventories by calling the API directly:

```http
POST /inventory_manager/v1/nodes/bulk
```

This approach is useful for:

* External automation systems pushing updates
* Python scripts managing inventory
* CI/CD pipelines updating inventories

**Example request body:**

```json
{
  "inventory_identifier": "prod-routers",
  "nodes": [
    {
      "name": "core-router-1",
      "attributes": {
        "itential_host": "10.1.1.1",
        "itential_platform": "iosxr",
        "cluster_id": "cluster_east",
        "itential_user": "$SECRET.network_devices.username",
        "itential_password": "$SECRET.network_devices.password"
      },
      "tags": ["core", "datacenter-1"]
    },
    {
      "name": "core-router-2",
      "attributes": {
        "itential_host": "10.1.1.2",
        "itential_platform": "iosxr",
        "cluster_id": "cluster_east",
        "itential_user": "$SECRET.network_devices.username",
        "itential_password": "$SECRET.network_devices.password"
      },
      "tags": ["core", "datacenter-1"]
    }
  ]
}
```

**Example response:**

```json
{
  "status": "Success",
  "result": {
    "total": 2,
    "inserted": 2,
    "skipped": 0,
    "errors": []
  }
}
```

### Use webhooks to populate inventories

Configure external systems to push inventory updates to Inventory Manager via webhooks by calling the `populateInventory` API endpoint.

This approach is useful when:

* Your inventory system can push updates on changes
* You want real-time inventory synchronization
* You're using systems like Netbox with webhook capabilities

**Webhook configuration:**

Configure your external system (Netbox, ServiceNow, etc.) to POST to:

```text
https://your-platform-instance/inventory_manager/v1/nodes/bulk
```

**Webhook payload format:**

```json
{
  "inventory_identifier": "inventory-name",
  "nodes": [
    { "name": "device-1", "attributes": {...} },
    { "name": "device-2", "attributes": {...} }
  ]
}
```

Ensure your webhook includes appropriate authentication headers for Itential Platform API access.

## Best practices

**Source of truth discipline:**

* Always populate from your actual source of truth
* Don't manually edit inventory data that should come from the source
* Document which source populates each inventory

**Error handling:**

* Include retry logic in population workflows
* Log population attempts and failures
* Alert on repeated failures

**Testing:**

* Test population workflows with small datasets first
* Validate node data format before populating
* Use non-production inventories for testing

> How to create inventories and populate them with nodes using workflows, API calls, or webhooks.