snipeit

Interact with Snipe-IT asset management via REST API. Use when working with assets (hardware), users, licenses, accessories, consumables, components, locations, departments, models, manufacturers, status labels, categories, suppliers, maintenances, reports. Trigger on: "snipe", "asset", "hardware", "license", "inventory", "check out", "check in", "IT assets", "equipment".

# Snipe-IT Skill

## Overview

Snipe-IT REST API returns **200 OK** for all valid HTTP requests.
Check `.status` field in response — `"success"` or `"error"`.

Base URL: `$SNIPEIT_URL/api/v1`

---

## Core Helper

```bash
snipe() {
  local method="${1:-GET}"
  local endpoint="$2"
  local data="${3:-}"

  local args=(
    -s -X "$method"
    -H "Authorization: Bearer $SNIPEIT_API_TOKEN"
    -H "Accept: application/json"
    -H "Content-Type: application/json"
  )

  [ -n "$data" ] && args+=(-d "$data")

  curl "${args[@]}" "${SNIPEIT_URL}/api/v1${endpoint}" | jq .
}

# Shortcuts
snipe_get()    { snipe GET    "$1"; }
snipe_post()   { snipe POST   "$1" "$2"; }
snipe_patch()  { snipe PATCH  "$1" "$2"; }
snipe_put()    { snipe PUT    "$1" "$2"; }
snipe_delete() { snipe DELETE "$1"; }
```

---

## Assets (Hardware)

```bash
# List all assets (with pagination)
snipe_get "/hardware?limit=50&offset=0"

# Search assets
snipe_get "/hardware?search=MacBook&limit=20"

# Filter by status label
snipe_get "/hardware?status_id=2&limit=50"

# Get asset by ID
snipe_get "/hardware/42"

# Get asset by asset tag
snipe_get "/hardware/bytag/ASSET-001"

# Get asset by serial number
snipe_get "/hardware/byserial/SN123456"

# Create asset
snipe_post "/hardware" '{
  "asset_tag":   "ASSET-001",
  "model_id":    5,
  "status_id":   2,
  "name":        "MacBook Pro 16",
  "serial":      "SN123456",
  "location_id": 1,
  "notes":       "Assigned to dev team"
}'

# Update asset (PATCH = partial update)
snipe_patch "/hardware/42" '{
  "name":      "MacBook Pro 16 (updated)",
  "status_id": 3,
  "notes":     "Screen replaced"
}'

# Full update (PUT = replace all fields)
snipe_put "/hardware/42" '{
  "asset_tag":  "ASSET-001",
  "model_id":   5,
  "status_id":  2,
  "name":       "MacBook Pro 16",
  "serial":     "SN123456"
}'

# Delete asset
snipe_delete "/hardware/42"

# Checkout asset to user
snipe_post "/hardware/42/checkout" '{
  "checkout_to_type": "user",
  "assigned_user":    7,
  "note":             "Assigned for remote work",
  "checkout_at":      "2025-01-15",
  "expected_checkin": "2025-12-31"
}'

# Checkout asset to location
snipe_post "/hardware/42/checkout" '{
  "checkout_to_type":  "location",
  "assigned_location": 3,
  "note":              "Conference room setup"
}'

# Checkout asset to another asset
snipe_post "/hardware/42/checkout" '{
  "checkout_to_type": "asset",
  "assigned_asset":   15
}'

# Checkin asset
snipe_post "/hardware/42/checkin" '{
  "note":       "Returned after use",
  "checkin_at": "2025-06-01"
}'

# Audit asset (confirm location)
snipe_post "/hardware/audit" '{
  "asset_tag":   "ASSET-001",
  "location_id": 2,
  "note":        "Verified during quarterly audit"
}'

# Get audit history
snipe_get "/hardware/audit/due"
snipe_get "/hardware/audit/overdue"

# List assets checked out to a user
snipe_get "/users/7/assets"

# Restore deleted asset
snipe_post "/hardware/42/restore" '{}'
```

---

## Users

```bash
# List all users
snipe_get "/users?limit=50"

# Search users
snipe_get "/users?search=john&limit=20"

# Get user by ID
snipe_get "/users/7"

# Get current API user
snipe_get "/users/me"

# Create user
snipe_post "/users" '{
  "first_name":  "John",
  "last_name":   "Doe",
  "username":    "john.doe",
  "email":       "john.doe@example.com",
  "password":    "SecurePass123!",
  "password_confirmation": "SecurePass123!",
  "department_id": 2,
  "location_id":   1,
  "employee_num":  "EMP-001",
  "jobtitle":      "Developer",
  "activated":     true
}'

# Update user
snipe_patch "/users/7" '{
  "department_id": 3,
  "jobtitle":      "Senior Developer"
}'

# Delete user
snipe_delete "/users/7"

# Get user's assets
snipe_get "/users/7/assets"

# Get user's licenses
snipe_get "/users/7/licenses"

# Get user's accessories
snipe_get "/users/7/accessories"

# Get user's consumables
snipe_get "/users/7/consumables"
```

---

## Licenses

```bash
# List all licenses
snipe_get "/licenses?limit=50"

# Search licenses
snipe_get "/licenses?search=Office&limit=20"

# Get license by ID
snipe_get "/licenses/3"

# Create license
snipe_post "/licenses" '{
  "name":            "Microsoft Office 365",
  "serial":          "XXXXX-XXXXX-XXXXX",
  "seats":           25,
  "category_id":     4,
  "manufacturer_id": 2,
  "license_email":   "it@example.com",
  "purchase_date":   "2025-01-01",
  "expiration_date": "2026-01-01",
  "purchase_cost":   "299.99",
  "notes":           "Annual subscription"
}'

# Update license
snipe_patch "/licenses/3" '{
  "seats": 30,
  "notes": "Seats increased"
}'

# Delete license
snipe_delete "/licenses/3"

# List license seats (who has it checked out)
snipe_get "/licenses/3/seats"

# Checkout license seat to user
snipe_post "/licenses/3/seats/12/checkout" '{
  "assigned_to": 7,
  "note":        "Developer license"
}'

# Checkin license seat
snipe_delete "/licenses/3/seats/12/checkin"
```

---

## Accessories

```bash
# List all accessories
snipe_get "/accessories?limit=50"

# Get accessory by ID
snipe_get "/accessories/8"

# Create accessory
snipe_post "/accessories" '{
  "name":            "USB-C Hub",
  "category_id":     5,
  "manufacturer_id": 3,
  "qty":             10,
  "purchase_date":   "2025-01-01",
  "purchase_cost":   "49.99",
  "location_id":     1
}'

# Update accessory
snipe_patch "/accessories/8" '{"qty": 15}'

# Delete accessory
snipe_delete "/accessories/8"

# Checkout accessory to user
snipe_post "/accessories/8/checkout" '{
  "assigned_to": 7,
  "note":        "For home office"
}'

# Checkin accessory
snipe_post "/accessories/8/checkin" '{
  "note": "Returned"
}'

# List checked-out accessories
snipe_get "/accessories/8/checkedout"
```

---

## Consumables

```bash
# List consumables
snipe_get "/consumables?limit=50"

# Get consumable by ID
snipe_get "/consumables/5"

# Create consumable
snipe_post "/consumables" '{
  "name":        "Printer Paper A4",
  "category_id": 6,
  "qty":         500,
  "item_no":     "PP-A4-500",
  "purchase_cost": "9.99",
  "location_id": 1
}'

# Checkout consumable (decrements qty)
snipe_post "/consumables/5/checkout" '{
  "assigned_to": 7,
  "note":        "For printer"
}'
```

---

## Components

```bash
# List components
snipe_get "/components?limit=50"

# Get component by ID
snipe_get "/components/12"

# Create component
snipe_post "/components" '{
  "name":        "RAM 16GB DDR4",
  "category_id": 7,
  "qty":         20,
  "serial":      "RAM-SN-001",
  "purchase_cost": "89.99",
  "location_id": 1
}'

# Checkout component to asset
snipe_post "/components/12/checkout" '{
  "assigned_to": 42,
  "assigned_qty": 2,
  "note":        "Upgrade"
}'

# Checkin component
snipe_post "/components/12/checkin" '{
  "checkin_qty": 2
}'
```

---

## Locations

```bash
# List locations
snipe_get "/locations?limit=50"

# Get location by ID
snipe_get "/locations/1"

# Create location
snipe_post "/locations" '{
  "name":     "Kyiv Office",
  "address":  "Khreschatyk 1",
  "city":     "Kyiv",
  "country":  "UA",
  "currency": "UAH"
}'

# Update location
snipe_patch "/locations/1" '{"name": "Kyiv HQ"}'

# Delete location
snipe_delete "/locations/1"

# Get assets at location
snipe_get "/locations/1/assets"

# Get users at location
snipe_get "/locations/1/users"
```

---

## Departments

```bash
# List departments
snipe_get "/departments?limit=50"

# Get department by ID
snipe_get "/departments/2"

# Create department
snipe_post "/departments" '{
  "name":        "Engineering",
  "location_id": 1,
  "manager_id":  5
}'

# Update / Delete
snipe_patch  "/departments/2" '{"name": "Engineering & DevOps"}'
snipe_delete "/departments/2"
```

---

## Models

```bash
# List models
snipe_get "/models?limit=50"

# Get model by ID
snipe_get "/models/5"

# Create model
snipe_post "/models" '{
  "name":             "MacBook Pro 16 M3",
  "manufacturer_id":  1,
  "category_id":      1,
  "model_number":     "MBP16-M3-2024",
  "depreciation_id":  1,
  "eol":              36
}'
```

---

## Status Labels

```bash
# List all