Quickstart Guide

📘

Version Note

This guide applies to PyCentral v2.0a15 and above. If your system has an earlier version installed an upgrade is required. The upgrade command can be found in the Upgrading from PyCentral v1 section.

This guide features a walkthrough on how to install PyCentral v2 and make your first API call to Central and/or GLP using the SDK.

Installation

pip3 install --pre pycentral

Upgrading from PyCentral v1 to v2

pip3 install --upgrade --pre pycentral

📘

Backwards compatibility

Upgrading to v2 will not break existing Classic Central workflows. v2 remains fully backward-compatible with v1 while enabling access to Central and GLP APIs.

Prerequisites

Before running any script, make sure you've completed the Authenticationguide to set up your credentials. The examples below assume you have a token.yaml file in the same directory as your script.

new_central:
  base_url: <api-base-url>
  client_id: <client-id>
  client_secret: <client-secret>

This file provides the authentication credentials required by the SDK to make API calls to Central

Examples

The examples below demonstrate two ways to use PyCentral:

1. A direct API call using the command() method.
2. The same operation using a module class.

Start with command() if you're new to PyCentral.

Direct API call with command()

The command method is a part of the base module in PyCentral and acts as a wrapper to make HTTP requests. It can be used to run any API call to Central with full customization. This example uses command() on NewCentralBase to make a direct API call to the device inventory endpoint. This fetches the devices assigned to your Central application.

Example Get Devices script:

1. Loads credentials from token.yaml
2. Connects to Central
3. Fetches a list of devices from inventory

from pycentral import NewCentralBase

with NewCentralBase(token_info="token.yaml") as conn:
    # Make the API call to retrieve device inventory
    resp = conn.command(
        api_method="GET",
        api_path="network-monitoring/v1/device-inventory"
    )
    
    # If the response code is 200, print the device inventory response; otherwise, print the error code and message
    if resp["code"] == 200:
        print(resp["msg"])
    else:
        print(f"Error {resp['code']}: {resp['msg']}")

Execute:

python get_devices.py

If successful, you'll see a response like this:

{
  "items": [
    {
      "model": "2930M",
      "serialNumber": "<Serial>",
      "deviceType": "SWITCH",
      "role": "Conductor",
      "siteId": "8022800",
      "deviceFunction": "-",
      "deviceGroupId": "8100143262",
      "scopeId": "9842216",
      "siteName": "site-12-dec",
      "deviceGroupName": "SWITCH Persona group",
      "firmwareVersion": "WC.16.11.0014",
      "isProvisioned": "Yes",
      "deviceName": "Aruba-Stack-2930M",
      "tier": null,
      "subscriptionKey": "ET45ENIPPEADN9FQ",
      "stackId": "1f00d067-267edc80",
      "type": "network-monitoring/device-monitoring",
      "macAddress": "D0:67:26:7E:DC:80",
      "ipv4": "10.27.113.203",
      "id": "SG7BJQL6PD",
      "deployment": "Stack",
      "status": "OFFLINE",
      "partNumber": "JL320A"
    }
  ],
  "count": 1,
  "total": 4,
  "next": "2"
}

GLP API Calls

The GLP device inventory API returns devices in your GLP account. Pass app_name="glp" to the command method and ensure your token.yaml includes GLP credentials:

from pycentral import NewCentralBase

with NewCentralBase(token_info="token.yaml") as conn:
    resp = conn.command(
        api_method="GET",
        api_path="devices/v1/devices",
        app_name="glp"
    )
    if resp["code"] == 200:
        print(resp["msg"])
    else:
        print(f"Error {resp['code']}: {resp['msg']}")

Fetch devices using a module class

The command() example above returns one page of results. The underlying API enforces a maximum number of devices per response and uses limit and next keywords to page through large inventories. If you have more devices than the page size, looping manually is required to collect them all.

📘

Understanding Pagination with APIs

The limit and next keywords are required for pagination while using Central and GLP APIs.

limit is the maximum number of records the API returns in a single response.

next is a cursor token included in the response when more records exist pass it back in the next request to fetch the following page.

Without handling the limit and next keywords, the command method only ever returns the first page of results. The get_all_device_inventory() method (shown below) handles all the pagination for you. It fetches every page automatically and returns the complete list of devices in one method call.

from pycentral import NewCentralBase
from pycentral.new_monitoring import MonitoringDevices

with NewCentralBase(token_info="token.yaml") as conn:
    devices = MonitoringDevices()

    # Fetches all the devices in Central and stores it in the variable device_list
    device_list = devices.get_all_device_inventory(conn)

    # If the device list is a non-empty list, print it. Otherwise, print an error message.
    if type(device_list) is list and len(device_list) > 0:
        print(device_list)
    else:
        print(f"Error {device_list}")

Browse all available module classes and their methods in the Module reference.

The above examples serves as a foundation for writing your own custom scripts. As you explore more API endpoints , you can extend this approach to automate tasks, gather monitoring statistics, or integrate with your existing tools. The PyCentral SDK is designed to help you script confidently and build workflows that fit your specific needs.