Spinwarden · Python SDK

Python SDK quickstart

The Spinwarden Python SDK is the smallest path from `pip install` to a working watch agent. It handles auth, webhook subscription, and the typed event shape so your code reads like domain logic, not HTTP plumbing.

Three steps get you there — install the package, drop in a watch agent that listens for critical alerts, and load your API key off the environment. The snippets below are copy-pasteable verbatim into any Python 3.10+ project.

pip · pypi

Install

Install the SDK from PyPI. The package is pure-Python; a single dependency on httpx means no heavy native client. Python 3.10 or newer is required for the type-hint syntax used in the public API.

pip install spinwarden

pip install spinwarden

alerts · webhook

Sample watch agent

A minimal watch agent — initialize the client, subscribe to the alerts topic, and escalate only when an event is critical. The decorator wires the webhook subscription so Spinwarden delivers each matching event into your function synchronously.

The handler filters on `event.severity == "critical"`, prints a one-line summary, and opens an escalation record against the offending satellite. Drop this into a file, set `SPINWARDEN_API_KEY` in the environment, and `python watch_agent.py` starts listening.

Sample watch agent

import os
from spinwarden import Spinwarden

client = Spinwarden(api_key=os.environ["SPINWARDEN_API_KEY"])

@client.webhook(topic="alerts")
def on_alert(event):
    if event.severity != "critical":
        return
    print(f"[{event.satellite_id}] CRITICAL — {event.summary}")
    client.escalations.create(
        satellite_id=event.satellite_id,
        event_id=event.id,
    )

if __name__ == "__main__":
    client.run()

auth · X-API-Key

Authentication

The SDK authenticates every request with an `X-API-Key` header carrying your tenant-scoped API key. Read it from the environment — never hard-code it — and the SDK attaches it on every outbound call, including webhook subscription registration and any REST call you make through the client.

Rotate keys from the operator dashboard under Tenant → API Keys. The old key stays active for 24 hours after rotation, so production agents have time to pick up the new value from a redeploy.

Authentication — X-API-Key header

import os
from spinwarden import Spinwarden

client = Spinwarden(
    api_key=os.environ["SPINWARDEN_API_KEY"],
    # Spinwarden sends X-API-Key on every request; rotate keys via the dashboard.
)