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.

Intent

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.

Inputs

External Connections

FileWave Server

• Hostname or DNS: the filewave central server accessible via https
• Port: 443 (default https)
• API endpoint root: /api/ or /filewave/api/ depending on endpoint
• Connection: direct https, no proxy support yet

Authentication

• Method: bearer token (http header authorization: bearer <token>)
• Token source: filewave central > manage administrators > api token
• Token lifecycle: no documented expiry; treat as persistent until revoked
• Storage: env var filewave_token or ~/.filewave/config (chmod 600)
• Setup: run filewave setup interactive wizard (first time) or set env vars for ci/cd

Configuration Files & Profiles

• ~/.filewave/config , encrypted profile store (created by setup wizard)
• Profile name: label for named servers (e.g., "lab", "prod", "test")
• Cache location: ~/.filewave/cache/ (7-day retention)

Parameters

• 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"), repeatable
• profile , 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 identifier
• csv , path to bulk update csv file
• output , output file path for bulk template export
• type , analytics type: "platform", "stale", or "field_summary"
• days , threshold in days for stale device reports (default 30)

Context & Preconditions

• filewave server must be running and reachable via https
• api token must have read and (for updates) write permissions
• inventory query (query-id) must exist in filewave central before running query commands
• bulk update workflow requires csv template generated by filewave bulk-template
• device cache must be warm before comparison; use filewave warm-cache first

Procedure

1. Setup 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.

2. 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.

3. 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.

4. 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.

5. 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.

6. 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.

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

8. 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.

9. 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.

10. 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.

Decision Points

• 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 not found on filewave server. verify the query-id exists in filewave central."

• 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: . examples: 'last_seen > 30 days', 'platform = ios'."

• 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 " label. do not auto-delete; warn user to review before manual removal.

• if bulk csv is malformed (missing columns, invalid rows): exit with error "csv validation failed: . expected columns: device_name, auth_user." do not apply partial updates.

• 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.

Output Contract

query command output:

• default: formatted table with columns (device name, os, version, last seen, enrollment date, user). each row is one device.
• json format: array of device objects with all fields from inventory query, one object per device.
• file: none (printed to stdout).

device-search / find-devices output:

• formatted table with matched devices (device name, model, serial, platform).
• or json array of device objects.

hierarchy output:

• text report showing device id, groups, original device (if clone), clone count (if original).
• json: object with keys {device_id, groups: [], original_device_id, clones: []}.

insights output:

• platform: table with platform names and device count per platform.
• stale: table with device name, last seen date, days inactive, platform, user.
• field_summary: json object with field_name: [min, max, avg, count] for numeric fields and value: count for categorical fields.
• file: none (printed to stdout).

bulk-template output:

• csv file at user-specified path (--output ~/devices.csv).
• columns: device_id, device_name, auth_user, platform, model.
• one header row, one data row per device.

bulk-update output:

• log lines showing patch result for each device: "updated device ", "error updating : ".
• summary: "<X updated, Y failed>" printed to stdout.

compare output:

• text report: "added: N devices, removed: N devices, changed: N devices. details: ".
  json: object with keys {added: [], removed: [], changed: []}.

  cache-status output:

  • text: "cache age: X days, entries: Y, location: ~/.filewave/cache/".

  Outcome Signal

  • setup succeeds: user runs filewave profiles and sees "default" or named profiles listed. config file exists at ~/.filewave/config with chmod 600.

  • query succeeds: stdout shows a formatted table or json with at least one device (or "0 devices" if filter matched nothing). no errors logged.

  • device search succeeds: matched devices are printed (table or json). if no matches, output says "no devices found matching ''."

  • hierarchy succeeds: output shows device groups and clone relationships. if device has no groups, output says "device has no group memberships."

  • bulk update succeeds: log lines confirm each device patched. summary line shows "X updated, 0 failed". user can then run filewave update-model and verify changes in filewave ui.

  • analytics succeeds: insights output contains numeric summaries (device count per platform, days stale, field stats). no empty results unless data is truly absent.

  • cache warm-up succeeds: filewave cache-status shows recent cache age (< 1 day) and non-zero entry count.

  • compare succeeds: output shows diff summary and detailed table of added/removed/changed devices. 0 changes means "both environments match."

  • any error: exit code is non-zero. stderr prints error message. no partial state is left (no half-patched devices, no orphaned cache files).

  ---

  credits: original skill authored by clawhub. enriched for implexa standards with explicit decision points, edge case handling, and output contract documentation.

  source: clawhub, enriched by implexa