Skip to main content

Python SDK

The official Xavigate Python SDK. Generated from the OpenAPI spec + hand-tuned wrappers.

PyPI: xavigate
Source: github.com/xavigate/xavigate-python
Requires: Python 3.9+

Install​

pip install xavigate

Initialize​

import xavigate

client = xavigate.Xavigate(api_key="test_sk_YOUR_KEY")
# or from environment variable:
# client = xavigate.Xavigate()  # reads XAVIGATE_API_KEY

Quick example​

# Create a subject, run MNTEST, get profile
subject = client.nature.subjects.create(
    external_subject_id="user_42",
    consent_artifact={
        "consent_text_version": "v1",
        "consented_at": "2026-04-21T10:30:00Z",
        "ui_snapshot_hash": "sha256:abc123",
    },
)

assessment = client.nature.assessments.start(
    subject.id,
    language="en",
)

client.nature.assessments.submit_responses(
    subject.id,
    assessment.id,
    responses=my_item_responses,  # [{"item_id": "mn_001", "value": 4}, ...]
)

# Poll or listen to webhook for completion
profile = client.nature.profiles.get(subject.id)
print(profile.scores["natures"])

Auto-pagination​

# Iterate all subjects without managing cursors
for subject in client.nature.subjects.list():
    print(subject.id, subject.external_subject_id)

Error handling​

from xavigate import XavigateError, XavigateAuthError

try:
    subject = client.nature.subjects.create(...)
except XavigateAuthError:
    # 401 — key revoked, missing, or invalid
    pass
except XavigateError as e:
    print(e.error_code, e.request_id, e.status)

Webhook verification​

from xavigate.webhooks import verify_webhook

# In your webhook handler:
event = verify_webhook(
    payload=raw_body,         # str or bytes
    headers={
        "webhook-id": ...,
        "webhook-timestamp": ...,
        "webhook-signature": ...,
    },
    secret=signing_secret,
)

Configuration options​

client = xavigate.Xavigate(
    api_key="test_sk_...",
    max_retries=3,          # default: 3
    timeout=30.0,           # seconds; default: 30
    base_url="...",         # override for mock server testing
)

Type hints​

All SDK methods are fully type-hinted. Use your IDE's type checking or mypy:

from xavigate.types import NatureSubject, NatureProfile, NatureAssessment