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

# Retire Inventory Nodes

`POST /api/admin/inventory/nodes/retire`

Retire unassigned nodes: move them to the terminal DECOMMISSIONING state.

Nothing is deleted — the node row and its assignment history stay. A node
still holding a live assignment is refused: detach it first. A retired node
carries no cluster, so there is nothing to
scope against and this needs a broad ``inventory:update`` grant. ``dryRun``
validates without writing.

## Query parameters

- `dryRun` boolean

## Request body

- NodeRetireRequest — Move the `node_ids` rows into the terminal DECOMMISSIONING state. Nothing is deleted. A node still assigned to a cluster is refused, so detach it first.
  - `nodeIds` string[], required

## 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

---

[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/08d946cba60c/schema)