Inventory

Track spare parts, stock levels, and the parts consumed by work orders. All endpoints are authenticated with a Bearer JWT (see Authentication).

Endpoints

Method	Path	Description
GET	/api/v1/inventory/categories	List part categories
POST	/api/v1/inventory/categories	Create a category
DELETE	/api/v1/inventory/categories/{category_id}	Delete a category (Admin)
GET	/api/v1/inventory/parts	List parts
POST	/api/v1/inventory/parts	Create a part
GET	/api/v1/inventory/parts/low-stock	List parts at or below reorder point
GET	/api/v1/inventory/parts/{part_id}	Get a part
PATCH	/api/v1/inventory/parts/{part_id}	Update a part
DELETE	/api/v1/inventory/parts/{part_id}	Delete a part (Admin)
GET	/api/v1/inventory/parts/{part_id}/transactions	List stock transactions for a part
POST	/api/v1/inventory/parts/{part_id}/transactions	Record a stock transaction
GET	/api/v1/inventory/work-orders/{work_order_id}/parts	List parts used on a work order
POST	/api/v1/inventory/work-orders/{work_order_id}/parts	Add a part to a work order
DELETE	/api/v1/inventory/work-orders/{work_order_id}/parts/{wop_id}	Remove a part from a work order

Endpoints marked Admin require an account administrator role.

Parts catalog

List parts

GET /api/v1/inventory/parts

Parameter	Type	Default	Description
category_id	uuid	—	Filter by category
search	string	—	Match part number or name
low_stock_only	boolean	false	Only parts below their reorder point
page	int	1	Page number
page_size	int	—	Items per page

{
  "items": [
    {
      "id": "...",
      "part_number": "BRG-6205-2RS",
      "name": "Deep Groove Ball Bearing 6205",
      "category_id": "...",
      "unit_of_measure": "ea",
      "current_stock_qty": "25",
      "min_stock_qty": "5",
      "reorder_point": "8",
      "reorder_qty": "20",
      "unit_cost": "12.50",
      "location": "Warehouse A, Shelf B3",
      "supplier_name": "SKF Distribution",
      "manufacturer_part_number": "6205-2RS1",
      "external_id": null,
      "is_active": true,
      "is_low_stock": false,
      "is_out_of_stock": false,
      "created_at": "2026-08-01T10:00:00Z",
      "updated_at": "2026-08-01T10:00:00Z"
    }
  ],
  "total": 1
}

Create a part

POST /api/v1/inventory/parts

{
  "part_number": "BRG-6205-2RS",
  "name": "Deep Groove Ball Bearing 6205",
  "category_id": "CATEGORY_UUID",
  "unit_of_measure": "ea",
  "min_stock_qty": 5,
  "reorder_point": 8,
  "reorder_qty": 20,
  "unit_cost": 12.50,
  "location": "Warehouse A, Shelf B3",
  "supplier_name": "SKF Distribution",
  "manufacturer_part_number": "6205-2RS1",
  "external_id": null,
  "is_active": true
}

current_stock_qty is not set directly — it is derived from stock transactions.

Low-stock parts

GET /api/v1/inventory/parts/low-stock

Returns a lightweight list of parts whose current_stock_qty has fallen to or below their reorder_point.

Stock transactions

Every change to a part's on-hand quantity is recorded as a transaction; the resulting balance is returned as balance_after.

Record a transaction

POST /api/v1/inventory/parts/{part_id}/transactions

{
  "transaction_type": "receive",
  "quantity": 20,
  "cost_per_unit": 12.50,
  "reference_type": "purchase_order",
  "reference_id": null,
  "notes": "PO #12345 received"
}

transaction_type is one of receive, consume, adjust, return, or transfer. quantity must be non-zero (negative values decrease stock for adjust).

{
  "id": "...",
  "spare_part_id": "...",
  "transaction_type": "receive",
  "quantity": "20",
  "balance_after": "45",
  "cost_per_unit": "12.50",
  "reference_type": "purchase_order",
  "reference_id": null,
  "notes": "PO #12345 received",
  "performed_by": "USER_UUID",
  "created_at": "2026-08-05T09:00:00Z"
}

Categories

Create a category

POST /api/v1/inventory/categories

{
  "name": "Bearings",
  "description": "Rolling-element bearings",
  "parent_id": null,
  "sort_order": 0
}

Work-order parts

Track which parts were consumed against a work order.

Add a part to a work order

POST /api/v1/inventory/work-orders/{work_order_id}/parts

{
  "spare_part_id": "PART_UUID",
  "quantity_used": 2,
  "notes": "Replaced both spindle bearings"
}

The response echoes the linked part's part_number, part_name, and unit_of_measure for display.