Skip to content

API

pynautobot.core.api

API module for pynautobot.

pynautobot.core.api.Api

The Api object is the primary entry point for interacting with a Nautobot instance using pynautobot.

Parameters:

Name Type Description Default
url str

The base URL of the Nautobot instance you want to connect to.

required
token str

Your Nautobot authentication token.

None
threading bool

Enable threading for .all() and .filter() requests. Defaults to False.

False
max_workers int

The maximum number of worker threads to use for .all() and .filter() requests. Defaults to the number of CPU cores.

4
api_version str

Override the default Nautobot REST API version used for all requests.

None
retries int

The number of retries for HTTP status codes 429, 500, 502, 503, and 504. Defaults to 0 (no retries). When the server sends a Retry-After header (for example Nautobot 3.3+ rate limiting on HTTP 429), pynautobot waits that many seconds before retrying; otherwise it uses exponential backoff. If every retry fails, RetriesExhaustedError is raised with the final response attached.

0
verify bool

Whether to verify SSL certificates. Defaults to True.

True
exclude_m2m bool

(Nautobot 2.4+) Whether to exclude/include many-to-many relationships for get/filter/all requests. Defaults to None.

None
include_default str

A comma-separated list of items to include by default for get/filter/all requests. Defaults to None. For example, include_default="config_context,computed_fields" will include the config_context and computed_fields for all get/filter/all responses.

None

Attributes:

Name Type Description
circuits

An instance of the App class providing access to Circuits endpoints.

cloud

An instance of the App class providing access to Cloud endpoints.

core

An instance of the App class providing access to Core endpoints.

data_validation

An instance of the App class providing access to Data Validation endpoints.

dcim

An instance of the App class providing access to DCIM endpoints.

extras

An instance of the App class providing access to Extras endpoints.

ipam

An instance of the App class providing access to IPAM endpoints.

load_balancers

An instance of the App class providing access to Load Balancers endpoints.

tenancy

An instance of the App class providing access to Tenancy endpoints.

ui

An instance of the App class providing access to UI endpoints.

users

An instance of the App class providing access to User endpoints.

virtualization

An instance of the App class providing access to Virtualization endpoints.

vpn

An instance of the App class providing access to VPN endpoints.

wireless

An instance of the App class providing access to Wireless endpoints.

http_session Session

The underlying HTTP session object used for making requests to Nautobot. You can override the default session with your own to control HTTP behavior such as SSL verification, custom headers, retries, and timeouts. See the documentation on custom sessions for more information.

rate_limit RateLimit | None

Rate limit information from the most recent response that reported it (Nautobot 3.3+ with rate limiting enabled).

Raises:

Type Description
AttributeError

If an invalid application name is provided.

Examples:

>>> import pynautobot
>>> nb = pynautobot.api(
...     'http://localhost:8000',
...     token='d6f4e314a5b5fefd164995169f28ae32d987704f'
... )
>>> nb.dcim.devices.all()

rate_limit property

Rate limit information from the most recent response that reported it.

Requires Nautobot 3.3+ with rate limiting set to report or enforce mode. With threading=True, this reflects whichever response arrived last. If you replace http_session with your own session, this is no longer updated; use RequestError.rate_limit on failed requests instead.

Returns:

Type Description
RateLimit | None

The latest rate limit information, or None if no response has included rate limiting headers.

Examples:

>>> nb.dcim.devices.all()
>>> nb.rate_limit.remaining, nb.rate_limit.quota
(996, 1000)

version property

Retrieves the version of the Nautobot REST API that the connected instance is using.

This method can be helpful for checking API compatibility and determining if specific features or syntaxes are available.

Returns:

Type Description
str

The Nautobot API version string.

Raises:

Type Description
RequestException

If there is an error fetching the version information from Nautobot.

Examples:

>>> import pynautobot
>>> nb = pynautobot.api(
...     'http://localhost:8000',
...     token='d6f4e314a5b5fefd164995169f28ae32d987704f'
... )
>>> nb.version
'1.0'

__init__(url, token=None, threading=False, max_workers=4, api_version=None, retries=0, verify=True, exclude_m2m=None, include_default=None)

Initialize the Api object.

openapi()

Retrieves the OpenAPI specification (OAS) document for the connected Nautobot instance.

The OpenAPI specification provides a machine-readable description of the Nautobot REST API, including available endpoints, parameters, request and response formats, and more.

This can be useful for tools like code generation or API clients in other languages.

Returns:

Type Description
dict

The OpenAPI specification document as a Python dictionary.

Raises:

Type Description
RequestException

If there is an error fetching the OpenAPI spec from Nautobot.

Examples:

>>> import pynautobot
>>> nb = pynautobot.api(
...     'http://localhost:8000',
...     token='d6f4e314a5b5fefd164995169f28ae32d987704f'
... )
>>> nb.openapi()
{...}

status()

Retrieves status information about the connected Nautobot instance.

This method provides various details about the Nautobot instance, including:

  • Django version
  • Installed apps and their versions
  • Nautobot version
  • Active plugins (if any)
  • Python version
  • Number of running RQ workers (if applicable)

Availability: Requires Nautobot version 2.10.0 or newer.

Returns:

Type Description
dict

A dictionary containing the status information as returned by Nautobot.

Raises:

Type Description
RequestError

If the request to Nautobot fails.

Examples:

>>> import pprint
>>> nb = pynautobot.api(
...     'http://localhost:8000',
...     token='d6f4e314a5b5fefd164995169f28ae32d987704f'
... )
>>> pprint.pprint(nb.status())
{'django-version': '3.1.3',
'installed-apps': {...},
'nautobot-version': '1.0.0',
'plugins': {},
'python-version': '3.7.3',
'rq-workers-running': 1}