Skip to content

suzieq-api-wrapper

CI PyPI Python License: MIT

An unofficial, dependency-minimal Python 3 client for the SuzieQ REST API (v2).

Installation

pip install suzieq-api-wrapper

Quick start

import suzieq_api_wrapper as suzieq

client = suzieq.SuzieQ(
    url="https://127.0.0.1:8000",
    api_key="your-api-key-here",
)

# Show all devices
devices = client.show_device()
for dev in devices:
    print(dev["hostname"], dev["os"], dev["status"])

# Show only established BGP peers
peers = client.show_bgp(state="Established")

# Assert all BGP sessions pass
failures = client.assert_bgp(result="fail")

# Longest-prefix match
match = client.lpm_route(address="10.0.0.1")

# Find where a MAC lives in the network
location = client.find_network(address=["aa:bb:cc:dd:ee:ff"])

# Show interfaces that are down
down = client.show_interface(state="down")

Features

  • Covers all 21 SuzieQ tables with all supported verbs
  • One method per table-verb combination — flat, discoverable namespace
  • Single runtime dependency: requests
  • Synchronous and straightforward — no async complexity
  • Typed exception hierarchy — catch AuthenticationError, NotFoundError, etc. without importing requests
  • Full test suite (237 tests, mocked HTTP — no live server required)
  • Read-only smoke test for live server validation

Error handling

import suzieq_api_wrapper as suzieq

try:
    result = client.show_bgp()
except suzieq.AuthenticationError:
    print("Check your API key")
except suzieq.NotFoundError:
    print("Unknown table or verb")
except suzieq.ValidationError:
    print("Invalid parameter value")
except suzieq.SuzieQError:
    print("Unexpected error")

Authentication

SuzieQ uses API key authentication. Configure your API key via the SuzieQ web UI or in ~/.suzieq/suzieq.cfg.

Pass verify_ssl=False to disable certificate verification (useful for self-signed certs in lab environments):

client = suzieq.SuzieQ(
    url="https://127.0.0.1:8000",
    api_key="your-api-key-here",
    verify_ssl=False,
)

Acknowledgements

This library was designed and tested by a human, with implementation assistance from Claude Code (Anthropic). All API shapes are derived from the SuzieQ open-source project.