Query and manage FileWave UEM device inventory, perform filtered searches, view device hierarchy, and run fleet analytics via the REST API.
# FileWave UEM API Skill
Query and manage FileWave UEM device inventory via REST API.
> **⚠️ Disclaimer:** This skill is a **technology demonstration** of Agentic Endpoint Management (AEM) — the concept of AI agents interacting directly with UEM platforms to assist IT administrators. It is provided as-is for educational purposes to explore what's possible when AI meets endpoint management. Neither the author nor FileWave accepts any liability for the use, misuse, or consequences of running this skill against production or any other environment. **Use at your own risk.** Always test in a lab environment first and review any actions before applying them to production systems.
## Overview
FileWave is a unified endpoint management platform for macOS, Windows, ChromeOS, Android, tvOS, iPadOS, and iOS. This skill provides programmatic access to device inventory and status information.
### Licensing
FileWave ( https://www.filewave.com ) offers flexible deployment options:
- **Community Edition** — Free, manages up to **15 computers + 15 mobile devices**
- Good for testing and small deployments
- All API capabilities available
- No advanced features (deployments, policies, MDM commands)
- **Commercial License** — More than 15 devices with advanced features
- TeamViewer Remote Control
- Deployment management, policy enforcement, MDM commands
- Technical support
This skill works with both licensing models.
## Setup
### Prerequisites
- FileWave server hostname/DNS
- FileWave API token (from FileWave Central → Manage Administrators → API Token)
### Configuration
Setup is interactive via `filewave setup`:
```bash
filewave setup
```
This creates `~/.filewave/config` with your server profiles. Credentials are stored securely (chmod 600, never hardcoded in scripts).
For **CI/CD environments**, use environment variables:
```bash
export FILEWAVE_SERVER="filewave.company.com"
export FILEWAVE_TOKEN="your_api_token_here"
```
Never hardcode tokens in scripts or documentation.
## Usage
### Basic Commands
```bash
# Setup profiles (first time)
filewave setup
# List configured servers
filewave profiles
# Query inventory
filewave query --query-id 1
# Query with filter
filewave query --query-id 1 --filter "last_seen > 30 days"
# Search for devices (now returns multiple matches)
filewave device-search "iPad"
# Find all devices by product type (authoritative hardware lookup)
filewave find-devices iPad
filewave find-devices iPhone
# View device hierarchy and groups
filewave hierarchy 123
# Trigger a Model Update
filewave update-model
# Fleet analytics
filewave insights --type platform
filewave insights --type stale --days 30
# Cache management
filewave warm-cache
filewave cache-status
# Bulk device updates (school workflow)
filewave bulk-template --output ~/devices.csv
filewave bulk-update --csv ~/devices.csv
# Session comparison
filewave query --query-id 1 --reference lab
filewave query --query-id 1 --profile production --reference prod
filewave compare lab prod
```
## API Architecture
**Multi-Server Support:** Configure multiple FileWave servers (lab, production, test) with named profiles.
### Key Endpoints Used
- `GET /api/inv/api/v1/query_result/{query_id}` — Query device inventory
- `GET /filewave/api/devices/v1/devices/{id}` — Device details
- `GET /filewave/api/devices/internal/devices/{id}/groups` — Device group memberships
- `PATCH /filewave/api/devices/v1/devices/{id}` — Update device (name, auth user)
- `POST /filewave/api/fwserver/update_model` — Refresh model after bulk updates
### Available Device Fields (per Inventory Query)
You configure which fields to include in your Inventory Query:
- Device name, model, serial number, UDID/IMEI
- OS name, version, build
- Last checkin timestamp
- Enrollment date, user assignment
- Device group, management status, compliance state
- And 50+ more fields (configurable)
### Platforms Supported
- macOS
- Windows
- ChromeOS
- Android
- iOS
- iPadOS
- tvOS
## Example Queries
```bash
# Query from Inventory Query (returns all devices)
filewave query --query-id 1
# Filter devices not seen in 30+ days
filewave query --query-id 1 --filter "last_seen > 30 days"
# Get JSON format for scripting
filewave query --query-id 1 --format json
# Multiple filters (AND logic)
filewave query --query-id 1 \
--filter "last_seen > 30 days" \
--filter "platform = iOS"
# Compare lab vs production
filewave query --query-id 1 --profile lab --reference lab_inventory
filewave query --query-id 1 --profile prod --reference prod_inventory
filewave compare lab_inventory prod_inventory
```
## Authentication
FileWave API uses Bearer token authentication:
```
Authorization: Bearer <token>
```
## Response Format
FileWave Inventory Queries return column-oriented data:
```json
{
"offset": 0,
"fields": [
"Client_device_name",
"OperatingSystem_name",
"OperatingSystem_version",
"Client_last_connected_to_fwxserver"
],
"values": [
["MacBook-Pro-John", "macOS 15 Sequoia", "15.1.0", "2026-02-12T14:30:00Z"],
["iPad-Student-001", "iPadOS", "17.3", "2026-02-10T10:22:00Z"]
],
"filter_results": 2,
"total_results": 2,
"version": 7
}
```
The CLI converts this to device objects automatically.
## Current Features
- ✅ Multi-server profile support
- ✅ Inventory Query integration
- ✅ Natural language filtering (last_seen > 30 days)
- ✅ Device hierarchy analysis (original vs. clones)
- ✅ Bulk device updates (school deployment workflow)
- ✅ Fleet analytics: platform breakdown, stale device reports, field summaries
- ✅ Session tracking and server comparison
- ✅ JSON export for scripting
- ✅ 7-day device cache for performance
## Documentation
- **README.md** — Overview and quick start
- **CLI_REFERENCE.md** — Complete command reference (includes fleet analytics, cache commands)
- **BULK_UPDATE.md** — School district workflow
- **API_CAPABILITIES.md** — API reference and analytics module
- **CREDENTIAL_ARCHITECTURE.md** — Security design
- **SESSION_DATA_MANAGER.md** — Session tracking internals
- **ONBOARDING.md** — Setup wizard details
don't have the plugin yet? install it then click "run inline in claude" again.
added explicit decision points covering auth failures, network timeouts, rate limits, malformed input, and api errors; expanded inputs with credential architecture and preconditions; detailed procedure steps with explicit api calls; codified output contract and outcome signals for all commands; added edge cases for empty results, cache staleness, token expiry, and bulk update failures.
Query and manage FileWave UEM device inventory via REST API.
⚠️ Disclaimer: This skill is a technology demonstration of Agentic Endpoint Management (AEM). the concept of AI agents interacting directly with UEM platforms to assist IT administrators. It is provided as-is for educational purposes to explore what's possible when AI meets endpoint management. Neither the author nor FileWave accepts any liability for the use, misuse, or consequences of running this skill against production or any other environment. Use at your own risk. Always test in a lab environment first and review any actions before applying them to production systems.
Use this skill to programmatically query and manage FileWave UEM device inventory across macOS, Windows, ChromeOS, Android, tvOS, iPadOS, and iOS endpoints. Perform filtered searches, view device hierarchy, run fleet analytics, and bulk-update device records via REST API. designed for IT administrators and agents who need to inventory devices, track stale endpoints, compare fleet state across environments, and automate endpoint management workflows without touching the FileWave UI.
FileWave Server
/api/ or /filewave/api/ depending on endpointAuthentication
authorization: bearer <token>)filewave_token or ~/.filewave/config (chmod 600)filewave setup interactive wizard (first time) or set env vars for ci/cd~/.filewave/config , encrypted profile store (created by setup wizard)~/.filewave/cache/ (7-day retention)query-id , numeric id of an inventory query configured in filewave central (required for inventory lookups)filter , natural language filter string (e.g., "last_seen > 30 days", "platform = ios"), repeatableprofile , named server profile; defaults to "default"reference , session label for cache/comparison (e.g., "lab", "prod_inventory")format , output format: "table" (default) or "json"device-id , numeric or string device identifiercsv , path to bulk update csv fileoutput , output file path for bulk template exporttype , analytics type: "platform", "stale", or "field_summary"days , threshold in days for stale device reports (default 30)filewave bulk-templatefilewave warm-cache firstSetup connection. run filewave setup and enter filewave server hostname and api token. or set filewave_server and filewave_token env vars. verify with filewave profiles to list configured servers.
Query device inventory. run filewave query --query-id <id> to fetch all devices from that inventory query. output is column-oriented json converted to device objects. if --format json is set, return raw api response.
Apply optional filters. if --filter is provided, parse natural language filter string (e.g., "last_seen > 30 days", "platform = ios") and apply client-side post-processing to the device list. multiple --filter flags use and logic.
Search or find devices. run filewave device-search "<term>" for substring match (returns multiple results) or filewave find-devices <product> for authoritative hardware lookup (e.g., "iPad", "iPhone"). returns matching device objects.
Inspect device details and hierarchy. run filewave hierarchy <device-id> to fetch device group memberships and original/clone relationships. call get /filewave/api/devices/v1/devices/<id> then get /filewave/api/devices/internal/devices/<id>/groups.
Trigger model update. after bulk device edits, run filewave update-model to call post /filewave/api/fwserver/update_model. this refreshes filewave's internal data model to reflect changes.
Run fleet analytics. run filewave insights --type <platform|stale|field_summary>. for stale device reports, use --days <n> to set threshold (default 30). analytics are computed from cached device data.
Manage cache. run filewave warm-cache to pre-load device inventory into ~/.filewave/cache/ (7-day retention). run filewave cache-status to inspect cache age and entry count.
Bulk update devices (school workflow). run filewave bulk-template --output ~/devices.csv to generate a csv template with device name and auth user columns. edit the csv to set new values. run filewave bulk-update --csv ~/devices.csv to apply updates via patch calls. then run step 6 (update-model) to apply changes.
Compare environments. run filewave query --query-id <id> --profile lab --reference lab to cache lab inventory. run filewave query --query-id <id> --profile prod --reference prod to cache prod inventory. run filewave compare lab prod to diff the two sessions and report added, removed, and changed devices.
if api token is missing or invalid: skip authentication and exit with error "no valid filewave credentials found. run 'filewave setup' or set filewave_server and filewave_token env vars." do not attempt unauthenticated requests.
if filewave server is unreachable (network timeout, dns failure, tls error): exit with error after 10-second timeout. do not retry. user must verify server hostname and network connectivity.
if query-id does not exist in filewave: api returns 404. exit with error "inventory query
if inventory query returns 0 results: proceed with empty device list. analytics and comparisons operate on empty sets (no errors). filter logic still applies (results in 0 matches).
if filter string cannot be parsed (malformed natural language): exit with error "invalid filter syntax:
if device search returns multiple matches: return all matches sorted by device name. if device-id is ambiguous, require user to specify by full uuid or serial number.
if device hierarchy reports original and clone devices: flag clones in output with a "clone of
if bulk csv is malformed (missing columns, invalid rows): exit with error "csv validation failed:
if cache is older than 7 days or missing: prompt user to run filewave warm-cache before analytics or comparison. or run cache warm-up automatically if --force-refresh flag is set.
if api returns rate-limit error (429): back off and retry up to 3 times with exponential delay (1s, 2s, 4s). if still failing, exit with error "filewave api rate-limited. try again in 5 minutes."
if auth token has expired (api returns 401): exit with error "filewave api token expired or revoked. run 'filewave setup' to refresh credentials."
if bulk update encounters a patch error on a single device: log error and skip that device, continue processing remaining rows. at end, report "X of Y devices updated successfully. Y rows failed." user can retry or edit csv.
query command output:
device-search / find-devices output:
hierarchy output:
insights output:
bulk-template output:
bulk-update output:
compare output: