cavaridge 0.1.0

Official Python SDK for the Cavaridge public API.

cavaridge

Official Python SDK for the Cavaridge™ public API.

Install

pip install cavaridge

Quickstart

import os
from cavaridge import CavaridgeClient

client = CavaridgeClient(api_key=os.environ["CAVARIDGE_API_KEY"])

page = client.aegis.list_scans(limit=5)
for scan in page["data"]:
    print(scan["id"], scan["status"])

# Paginate everything:
for finding in client.paginate("GET", "/v2026-04-27/aegis/findings", query={"severity": "high"}):
    print(finding)

Auth

• API key: CavaridgeClient(api_key="sk_live_...") (sandbox: sk_test_...).
• OAuth bearer: CavaridgeClient(bearer_token="...").
• Falls back to CAVARIDGE_API_KEY env var when neither is provided.

Idempotency

client.cavalier.create_quote(
    client_id="ten_abc",
    line_items=[{"catalog_id": "operations_pro", "quantity": 1}],
    idempotency_key="qt_create_2026-05-04_001",
)

Errors

Failures raise CavaridgeError with .type, .status, .detail, .request_id, and .documentation_url.

from cavaridge import CavaridgeError

try:
    client.reclaim.execute_policy("pol_abc")
except CavaridgeError as err:
    if err.status == 403 and err.type.endswith("/insufficient_scope"):
        print("need reclaim.policies.manage scope")
    raise

Retries

Default: 3 retries on 429 and 5xx with exponential backoff (250ms → 500ms → 1000ms). Override with max_retries.

Sandbox

CavaridgeClient(api_key=os.environ["CAVARIDGE_TEST_KEY"], base_url="https://api-sandbox.cavaridge.app")

Versioning

SDK semver maps to spec dated versions:

• major → API dated version
• minor → additive features within a dated version
• patch → bug fixes only

Docs

• API overview
• Patterns
• Python SDK guide