Python SDK

The official Python client for Cheqpoint. Blocks execution until a human decides, or throws on timeout. Also supports short-wait and fire-and-forget async patterns.

Installation

bash
python3 -m pip install cheqpoint

Setup

python
from cheqpoint import CheqpointClient

client = CheqpointClient(
    api_key="cq_live_xxxxxxxxxxxx",
    timeout=3600  # optional: max seconds to wait (default 300)
)

checkpoint() — block until a human decides

python
from cheqpoint import CheqpointClient, RejectedError

client = CheqpointClient(api_key="cq_live_xxxxxxxxxxxx")

try:
    result = client.checkpoint(
        action="send_email",
        summary="Automated retention campaign to user@example.com",
        details={"to": "user@example.com", "subject": "Discount offer"},
        risk_score=0.3,  # 0.0–1.0
    )
    # result.status == "APPROVED"
    send_email(result.effective_details)
except RejectedError as e:
    print(f"Declined: {e}")

request_sync() — short-wait with fallback to polling

python
# Sends to /api/webhooks/inbound. The server waits up to 10 s for an
# inline decision, then this method polls client-side until timeout_ms elapses.
# Returns the decision dict, or {"status": "pending", ...} if no decision was made.

result = client.request_sync(
    action="process_refund",
    summary="AI agent requesting refund for order #8842",
    details={"order_id": "8842", "amount_cents": 12000},
    justification="Customer reported item not delivered.",
    timeout_ms=30_000,  # poll up to 30 s total
)

if result["status"] == "approved":
    effective = result.get("modifiedDetails") or result["details"]
    process_refund(effective)
elif result["status"] == "rejected":
    print(f"Rejected: {result.get('decisionNote')}")
else:
    # "pending" — decision still awaiting; use approvalId to track later
    print(f"Pending: {result['approvalId']}")

request_async() — fire-and-forget with optional callback

python
# Returns immediately. If the server auto-approves/rejects, decision is
# returned right away. Otherwise status is "pending" and you receive a
# callback POST when a human reviewer decides.

result = client.request_async(
    action="deploy_to_production",
    summary="AI agent requesting production deployment of v2.4.1",
    details={"version": "v2.4.1", "service": "payments-api", "region": "us-east-1"},
    justification="All CI checks passed. No schema migrations.",
    # Optional: receive the final decision via HTTP POST
    callback_url="https://your-backend.example.com/webhooks/cheqpoint-decision",
)

# result["status"]    → "approved" | "rejected" | "pending"
# result["approvalId"] → use to poll GET /api/approvals/{id} if needed
print(f"Status: {result['status']}, ID: {result['approvalId']}")

Callback payload (received at your callbackUrl)

json
// Cheqpoint POSTs this to your callbackUrl when a human reviewer decides:
{
  "approvalId": "req_abc123",
  "status": "approved",
  "modifiedDetails": null,
  "decisionNote": "Approved for off-peak deployment window."
}