💻 REST API: Assets

The complete usage guide for the Assets module of the REST API — every URL, method, parameter and response shape. This mirrors the interactive documentation at System → API → Documentation, where each endpoint also has a live "Try it" tester.

[!NOTE] New to the API? Read the basics table on REST API: Tickets first — base URL, authentication, response envelope, error codes, rate limits and PATCH semantics are identical across all modules.

Three things that make Assets different from Tickets:

🌍 Install-wide	Assets have no company — a key's company scope does not restrict them (that machinery applies to tickets).
🏷️ Hostname is identity	The inventory agent, Intune sync and this API all treat hostname as the asset's identity. Creating a duplicate hostname returns 409 pointing at the existing asset — PATCH that instead.
🚫 No delete	There is deliberately no DELETE /assets/{id} — nothing in FreeITSM deletes assets (they're agent-maintained records). Retire an asset by setting its status.

---

🚀 Quick start

Sync an asset from any external source (procurement system, another RMM, a spreadsheet):

curl -X POST "https://your-server/api/v1/assets" \
  -H "Authorization: Bearer fitsm_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
        "hostname": "LT-0042",
        "manufacturer": "Dell",
        "model": "Latitude 5440",
        "service_tag": "ABC1234",
        "asset_type_id": 4,
        "warranty_expiry": "2028-06-30",
        "purchase_cost": 899.99
      }'

Every change you make afterwards lands in the asset's History exactly as if an analyst edited it in the UI. 📒

---

💻 Assets

🟢 GET /assets — list / search   🔑 assets.read

Parameter	Description
q	Search hostname, service tag, model and manufacturer
hostname / service_tag	Exact lookups (handy for sync scripts)
asset_type_id · asset_status_id · location_id · supplier_id · cost_centre_id	Classification filters
assigned_user_id	Assets assigned to a requester · unassigned=true finds unassigned assets
warranty_within_days	⏳ Warranty expiring within N days — the dashboard's "expiring soon" shape
warranty_expired	true = warranty already lapsed
not_seen_days	👻 Not reported by the inventory agent for N days (or never seen)
sort	hostname (default), id, first_seen, last_seen, warranty_expiry, purchase_date, model — prefix - for descending
page / per_page	Pagination — default 1 / 25, max per_page 100

GET /assets?warranty_within_days=30&sort=warranty_expiry     ← renewal report
GET /assets?not_seen_days=14&asset_status_id=1               ← agents gone quiet
GET /assets?service_tag=ABC1234                              ← exact serial lookup

The asset shape (list and detail are the same, detail adds assigned_users):

{ "id": 568, "hostname": "LT-0042",
  "type":     { "id": 4, "name": "Laptop" },
  "status":   { "id": 2, "name": "In use" },
  "location": { "id": 2, "name": "London", "path": "UK › London" },
  "hardware": { "manufacturer": "Dell", "model": "Latitude 5440", "service_tag": "ABC1234",
                "memory": 17179869184, "cpu_name": null, "speed": null, "gpu_name": null,
                "bios_version": null, "tpm_version": null, "bitlocker_status": null },
  "os":       { "operating_system": "Windows 11 Pro", "feature_release": null, "build_number": null },
  "network":  { "domain": null, "logged_in_user": null },
  "lifecycle": { "purchase_date": null, "purchase_cost": 899.99,
                 "supplier": { "id": 3, "name": "TechSupplies Ltd" },
                 "order_number": "PO-1001", "warranty_expiry": "2028-06-30" },
  "assigned_users_count": 1,
  "first_seen": "2026-07-02T22:59:12Z", "last_seen": "2026-07-02T22:59:12Z", "last_boot_at": null }

🔵 POST /assets — create   🔑 assets.create

Only hostname is required (max 50 chars, unique — duplicate → 409 with the existing asset's id). Every field from the PATCH table below can be set at creation. first_seen/last_seen are stamped automatically; a creation entry is written to the asset history; setting warranty_expiry re-syncs the calendar's warranty events. Returns 201 with the full asset.

asset_tag (3.1.0). Send one and it is kept, if it is free in the asset's company (409 naming the asset that has it otherwise). Leave it out and, if the company has automatic asset tags switched on, the asset gets the next one in sequence — the response carries it. See Asset tag numbering — Developer Guide.

🟢 GET /assets/{id} — get one   🔑 assets.read

The full asset plus its current holders inline:

"assigned_users": [ { "user_id": 174, "name": "Jane Smith", "email": "[email protected]",
                      "assigned_at": "2026-07-02T22:59:36Z",
                      "expected_return_date": "2026-08-01", "notes": "Loan laptop" } ]

🟠 PATCH /assets/{id} — update   🔑 assets.update

Send only what changes; explicit null clears a field. Every change is audited into the asset's History with the same stable field keys the UI writes (so API edits render identically in the History modal), lookup changes are audited by display name ("Laptop", "UK › London"), and a warranty_expiry change re-syncs the calendar. Unknown lookup ids → 422; a hostname clash → 409. Re-sending the same PATCH is idempotent.

Group	Fields
Classification	asset_type_id · asset_status_id · location_id
Lifecycle	purchase_date · purchase_cost · supplier_id · order_number · warranty_expiry (dates YYYY-MM-DD) · cost_centre_id (3.5.0 — an active cost centre of the asset's company, 422 otherwise; one already held may be kept after it's made inactive). Read back as lifecycle.cost_centre: {id, code, name}
Identity & hardware	hostname · manufacturer · model · service_tag · memory · cpu_name · speed · gpu_name · bios_version · tpm_version · bitlocker_status
OS & network	operating_system · feature_release · build_number · domain · logged_in_user

[!TIP] The classification/lifecycle fields are what analysts edit in the UI; the hardware/OS fields are normally maintained by the inventory agent — the API can write both, so a non-agent source (Intune export, another RMM) can keep assets in sync.

---

🤝 Assignments (check-out / check-in)

Assignment is to requesters (end users), exactly like the UI: assigning writes the custody log's check-out and an assigned_user history entry; unassigning snapshots the holder and writes the check-in.

🟢 GET /assets/{id}/assignments   🔑 asset_assignments.read

Current holders with dates, due-back, notes and which analyst assigned them.

🔵 POST /assets/{id}/assignments   🔑 asset_assignments.create

Field	Required	Description
user_id or user_email	✅	An existing requester (create one first with POST /users — needs users.create)
notes		Assignment notes
expected_return_date		Due back, YYYY-MM-DD

Already assigned → 409. Returns 201.

🔴 DELETE /assets/{id}/assignments/{user_id}   🔑 asset_assignments.delete

Checks the asset back in. Unknown assignment → 404.

---

📒 History & custody

🟢 GET /assets/{id}/history   🔑 asset_history.read

Every audited change, newest first — field key, old/new values (display names for lookups) and the analyst:

{ "data": [ { "id": 12, "field": "location", "old_value": null, "new_value": "London",
              "analyst": { "id": 1, "name": "Administrator" },
              "created_at": "2026-07-02T22:59:36Z" } ] }

🟢 GET /assets/{id}/custody   🔑 asset_history.read

The check-out / check-in trail — who had the asset, when, expected return, processed by which analyst:

{ "data": [ { "id": 3, "action": "checkout", "user_id": 174, "user_name": "Jane Smith",
              "expected_return_date": "2026-08-01", "notes": "Loan",
              "by": "Administrator", "at": "2026-07-02T22:59:36Z" } ] }

---

🧰 Inventory (agent-collected)

Read-only views of what the inventory agent reports — the same data as the asset detail pane's Storage/Devices/Software.

Endpoint	Permission	Returns
🟢 GET /assets/{id}/disks	🔑 asset_inventory.read	Drives with size/free bytes and used percent
🟢 GET /assets/{id}/network-adapters	🔑 asset_inventory.read	Adapters with MAC, IP, subnet, gateway, DHCP flag
🟢 GET /assets/{id}/devices	🔑 asset_inventory.read	Device-manager entries (class, name, status, driver)
🟢 GET /assets/{id}/software	🔑 asset_inventory.read	Installed software — system components excluded unless ?include_components=true

---

📚 Reference data

All under the shared 🔑 reference.read permission:

Endpoint	Returns
🟢 GET /asset-types	Asset types (id, name, description, is_active)
🟢 GET /asset-statuses	Asset statuses
🟢 GET /asset-locations	All locations, flat, each with parent_id and its full path ("UK › London › Office 1")
🟢 GET /suppliers	Suppliers with display name and a supplies_assets flag

---

🧪 Worked example: warranty renewal report

A read-only key (assets: read + reference: read) pulls everything a renewals spreadsheet needs:

B="https://your-server/api/v1"; K="Authorization: Bearer fitsm_…"

# Assets whose warranty expires in the next 90 days, soonest first
curl -s -H "$K" "$B/assets?warranty_within_days=90&sort=warranty_expiry&per_page=100" \
  | jq -r '.data[] | [.hostname, .hardware.service_tag, .lifecycle.warranty_expiry,
                      (.lifecycle.supplier.name // "-"), (.location.path // "-")] | @csv'

And the reverse direction — a procurement system stamping newly purchased kit:

# Find the asset by serial, then set its lifecycle fields
ID=$(curl -s -H "$K" "$B/assets?service_tag=ABC1234" | jq -r '.data[0].id')
curl -s -X PATCH "$B/assets/$ID" -H "$K" -H "Content-Type: application/json" \
  -d '{"purchase_date":"2026-07-01","purchase_cost":899.99,"order_number":"PO-1001","warranty_expiry":"2029-07-01"}'

---

Under the hood: REST API — How It Works · Tickets endpoints: REST API: Tickets · Keys & permissions: System → API (System module) · Module docs: Assets.