Python SDK

The official Python SDK for the CaviusConnect API. It mirrors the Node.js SDK one-to-one.

Status: v0.1.0 (pre-release). The public API may change before 1.0.

Install

pip install cavius

Requires Python 3.9+.

Quickstart

import os
from cavius import Cavius

client = Cavius(
    api_key=os.environ["CAVIUS_API_KEY"],
    # Optional; defaults to https://core.caviusconnect.com
    base_url=os.environ.get("CAVIUS_BASE_URL", "https://core.caviusconnect.com"),
)

# List contacts
page = client.contacts.list(page_size=50)
print(f"Got {len(page['content'])} contacts")

# Send an SMS
client.messages.send(
    to="+15555550100",
    channel="SMS",
    body="Hello from Cavius!",
)

# Subscribe to webhooks
sub = client.webhooks.subscriptions.create(
    url="https://your.app/cavius-webhook",
    event_types=["message.delivered", "message.failed"],
)
print("Save this secret somewhere safe:", sub["signingSecret"])

The client is a context manager:

with Cavius(api_key=os.environ["CAVIUS_API_KEY"]) as client:
    client.messages.send(to="+15555550100", channel="SMS", body="hi")

Resources

Resource	Endpoints	Notes
`contacts`	`/api/contacts/`, `/api/v1/contacts/imports/`	CRUD + import + activity
`messages`	`/api/messages/*`	send, threads, SSE stream, media upload
`campaigns`	`/api/campaigns/*`	CRUD + launch / cancel / reschedule + stats
`forms`	`/api/v1/forms/*`	CRUD + submissions
`webhooks`	`/api/v1/webhooks/subscriptions/`, `…/deliveries/`	split into `.subscriptions` and `.deliveries`
`api_keys`	`/api/v1/api-keys/*`	create / revoke / whoami
`verify`	`/api/v1/verify/*`	OTP start + check
`macros`	`/api/v1/macros/*`	CRUD + preview
`notes`	`/api/v1/conversations/{cid}/notes/*`	conversation-scoped notes
`segments`	`/api/v1/segments/*`	CRUD + materialize + list contacts
`brand_kit`	`/api/v1/brand-kit/*`	singleton-per-org + logo upload URL
`workflows`	`/api/workflows/*`	CRUD

Error handling

All API failures raise a subclass of CaviusError:

from cavius import (
    CaviusError,
    CaviusAuthError,
    CaviusNotFoundError,
    CaviusValidationError,
    CaviusRateLimitError,
)

try:
    client.contacts.get(contact_id)
except CaviusNotFoundError:
    ...  # 404
except CaviusValidationError as e:
    print(e.field_errors)  # [FieldError(field, message, code), ...]
except CaviusRateLimitError as e:
    print(f"rate-limited; retry after {e.retry_after_seconds}s")
except CaviusAuthError:
    ...  # 401: bad/missing API key
except CaviusError as e:
    print(e.status, e.body, e.request_id)

Status-to-class map:

HTTP	Class
400/422	`CaviusValidationError`
401	`CaviusAuthError`
403	`CaviusForbiddenError`
404	`CaviusNotFoundError`
409	`CaviusConflictError`
429	`CaviusRateLimitError`
5xx	`CaviusServerError`
network	`CaviusNetworkError`
other	`CaviusError`

Retries

Built-in retries with exponential backoff + jitter on:

5xx server errors
429 rate-limit responses (honors Retry-After if present, capped at 30s)
network errors (DNS, connection refused, timeout)

Default: 3 retry attempts, base delay 250ms, capped at 8s per attempt. Configure via max_retries / retry_base_delay_ms / timeout_ms, or disable per-request with no_retry=True.

Configuration

Cavius(
    api_key="ck_live_...",
    base_url="https://core.caviusconnect.com",  # default
    timeout_ms=30_000,                           # per-request timeout
    max_retries=3,                               # retries on 5xx/429/network
    retry_base_delay_ms=250,                     # exponential backoff base
    user_agent="my-app/1.0",                     # optional UA override
    default_headers={"X-My-Header": "foo"},
    http_client=httpx.Client(...),               # injectable httpx.Client
)