npycentral 0.4.0

Python Toolkit for N-Central RMM API

npycentral

A Python toolkit for the N-able N-Central RMM API.

Installation

pip install npycentral

Quick Start

from npycentral import NCentralClient

client = NCentralClient(
    base_url="https://your-ncentral.example.com",
    jwt="your-jwt-token",
    base_so_id="50"  # Almost always 50 - see note below
)

Getting Your JWT Token

1. In N-Central, go to Administration > User Management > Users
2. Select your API user (or create one)
3. Go to the API Access tab
4. Generate a new JWT token

Service Organization ID

For most N-Central instances, your SO ID is 50. This is the default for single-SO setups, which covers the vast majority of deployments.

If you're unsure, you can check in N-Central (it's in the URL when viewing All Devices) or fetch it:

service_orgs = client.get_service_orgs()
for so in service_orgs:
    print(f"{so.soName}: {so.soId}")

Examples

List Windows Servers and Check for Issues

from npycentral import NCentralClient

client = NCentralClient(
    base_url="https://ncentral.example.com",
    jwt="your-jwt",
    base_so_id="50"
)

servers = client.get_devices(filter_name="Servers - Windows")
for server in servers:
    issues = client.get_device_active_issues(server.deviceId)
    print(f"{server.longName} - {len(issues)} active issues")
    for issue in issues:
        print(f"  [{issue.serviceName}] {issue.notificationState}")

Get Device Details by Name

# Get a specific device by name
device = client.get_device(device_name="DC01")
print(f"Device ID: {device.deviceId}")
print(f"Last Check-in: {device.last_checkin_datetime}")

# For better performance, narrow down with a filter first
device = client.get_device(device_name="DC01", filter_name="Domain Controllers")

Check Disk, CPU, and Memory Usage

# Disk usage per volume
disks = client.get_device_disk_usage(device_name="FILESERVER01")
for disk in disks:
    print(f"{disk.volume}: {disk.free_gb:.1f} GB free ({disk.usage_percent:.0f}% used)")

# CPU usage with top processes
cpu = client.get_device_cpu_usage(device_name="DC01")
print(f"CPU: {cpu.usage_percent}%")
for proc in cpu.top_processes:
    print(f"  {proc.name}: {proc.cpu_usage_percent}%")

# Memory usage (physical + virtual)
mem = client.get_device_memory_usage(device_name="DC01")
print(f"RAM: {mem.physical_used_gb:.1f}/{mem.physical_total_gb:.1f} GB ({mem.physical_usage_percent}%)")

Check Disk Health

device = client.get_device(device_name="FILESERVER01")
disk_status = client.check_device_disk_health(device.deviceId)

print(disk_status)
# Output: Disk Health: 3 monitors (2 normal, 1 warning, 0 failed)
#         C: Normal | D: Normal | E: Warning

Get Hardware and Software Inventory

device = client.get_device(device_name="WORKSTATION01")

# Load full asset details (lazy-loaded to save API calls)
assets = device.load_assets()

# Hardware summary
hw = client.get_device_hardware_summary(device.deviceId)
print(f"Model: {hw['manufacturer']} {hw['model']}")
print(f"CPU: {hw['processor']}")
print(f"RAM: {hw['memory_gb']} GB")

# Software inventory
sw = client.get_device_software_inventory(device.deviceId)
print(f"Pending patches: {len(sw['pending_patches'])}")
for patch in sw['pending_patches'][:5]:
    print(f"  - {patch.title}")

Run a Script and Wait for Completion

# Run an automation policy/script on a device
result = client.run_and_monitor_task(
    repo_id=12345,          # Repository/item ID of the task in N-Central
    task_name="My Script",
    customer_id=device.customerId,
    device_id=device.deviceId,
    timeout=300             # Wait up to 5 minutes
)

print(f"Task completed with status: {result['status']}")

Generate Deep Links for Tickets

device = client.get_device(device_name="PROBLEMPC")

# Get URLs you can paste into tickets
overview_url = client.get_device_overview_url(device.deviceId)
remote_url = client.get_device_remote_control_url(device.deviceId)

print(f"Device Overview: {overview_url}")
print(f"Remote Control: {remote_url}")

Performance Notes

• Name lookups are slower than ID lookups. The N-Central API doesn't support looking up devices by name directly, so get_device(device_name="...") fetches all devices and searches locally. Use filter_name to limit the scope when possible.

• Device lists are cached. By default, device lists are cached for 5 minutes to avoid hammering the API. You can clear the cache with client.clear_device_cache() or adjust the TTL with client.set_device_cache_ttl(seconds).

• Rate limiting is handled automatically. The N-Central API enforces concurrent call limits per endpoint and returns HTTP 429 when exceeded. The client retries automatically with exponential backoff (default: 3 retries, waits of 1s → 2s → 4s). You can tune this at init time:

client = NCentralClient(
    base_url="https://ncentral.example.com",
    jwt="your-jwt",
    max_retries=5,        # retries before raising RateLimitError (default: 3)
    retry_backoff_base=3  # backoff in seconds: 1s, 3s, 9s, 27s, 81s (default: 2)
)

API Reference

See docs/api-reference.md for the complete function reference.

License

MIT