---
title: "Create Inventory Assignment"
method: POST
path: "/api/admin/inventory/clusters/{cluster_id}/assignments"
tags: ["admin-inventory"]
---

# Create Inventory Assignment

`POST /api/admin/inventory/clusters/{cluster_id}/assignments`

Assign nodes to a cluster for a window inside their contracted availability.

## Path parameters

- `cluster_id` string, required

## Query parameters

- `dryRun` boolean

## Request body

- AssignmentCreateRequest — Assign one or more nodes (`node_ids`) to a cluster with shared attrs.
  - `nodeIds` string[], required
  - `status` 'PLANNED' | 'ACTIVE' | 'ENDED' | 'CANCELLED'
  - `type` 'STANDARD' | 'FAILOVER'
  - `isController` boolean
  - `priceHr` number, nullable
  - `startDate` string, date-time, nullable
  - `endDate` string, date-time, nullable
  - `notes` string, nullable
  - `metadata` AssignmentMetadata — The assignment's `metadata` JSON. Only `playbooks` is validated; other keys (e.g. the NetBox migration's `source`) pass through untouched.
    - `playbooks` AssignmentPlaybooksMetadata — Per-assignment overrides applied when rendering the cluster's inventory.ini. Cluster-scoped on purpose: the same node can need a different `private_interface` or topology zone in the next cluster it joins, so these win over the node's own columns.
      - `hostVars` object, nullable
      - `dropHostVars` string[], nullable
      - `groups` string[], nullable
      - `dropGroups` string[], nullable
      - `hostAlias` string, nullable
      - `inlineNote` string, nullable

## Response `200`

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
    - `detached` integer, nullable
    - `retired` integer, nullable
  - `status` string, nullable — Response status

## Other responses

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

## Changes

- **2026-09-04** `cf5a8be325a9` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/primeintellect/apis/pi-api/changes/api/admin/inventory/clusters/:cluster_id/assignments/post.md)

---

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