Python SDK API reference

Every client method, argument, and return type.

Construction

from cohesion import Client
client = Client(
    api_key="ck_live_...",
    base_url="https://api.cohesionauth.com",            # default
    timeout=30.0,                                       # seconds, default 30
    max_retries=3,                                      # default 3, exponential backoff
    receipts_base_url="https://receipts.cohesionauth.com",  # default (oversight receipts host)
)

receipts_base_url configures the host for get_receipt(). Oversight receipts are served by a dedicated worker on receipts.cohesionauth.com, a separate host from the scoring API base. Only get_receipt() uses it; every other method targets base_url.

Methods

score(*, session_id, operator_id, domain, interaction) -> ScoreResponse

Wraps POST /v1/score. Idempotency-Key is auto-generated.

score_batch(interactions) -> BatchScoreResponse

Wraps POST /v1/score/batch.

operator_profile(operator_id) -> OperatorProfile

Wraps GET /v1/operator/:id/profile.

organization_dashboard() -> OrganizationDashboard

Wraps GET /v1/organization/dashboard.

maintenance_recommend(operator_id) -> MaintenanceRecommendation

Wraps POST /v1/maintenance/recommend.

compliance_report(period_start, period_end) -> ComplianceReport

Wraps GET /v1/compliance/report.

get_receipt(decision_id) -> OversightReceiptResponse

GETs https://receipts.cohesionauth.com/v1/decisions/:id/receipt (configurable via receipts_base_url). Returns the signed, exportable oversight receipt for a decision produced by the DRS gate path (gate() / decision_score()). Pass the ai_decision_log_id the gate returned. The response surfaces receipt.chain_anchor.verified_at_issuance (always True on an issued receipt) and signature.receipt_hmac (hex HMAC over the canonical receipt). The worker returns 404 for an unknown or cross-tenant decision id and 409 when the row predates the field-covering evidence chain or fails verification. Call it from server-side code; the receipt host does not currently send CORS headers, so a browser request to it is preflight-blocked.

A receipt attaches to the gate path that produces one. The score() (JIS) path does not yet yield a receipt; a future canonical-evidence-record migration will make score() receipt-eligible too.

admin_key_rotate() -> KeyRotationResponse

Wraps POST /v1/admin/key/rotate. Returns the new key once.

admin_key_revoke() -> KeyRevocationResponse

Wraps POST /v1/admin/key/revoke.

admin_audit_log(event_type=None, since=None, until=None, limit=100) -> list[AuditEvent]

Wraps GET /v1/admin/audit-log.

Errors

The SDK raises typed exceptions:

Next step

Cookbook for end-to-end recipes.