claritylift 0.1.0

Official Python SDK for the ClarityLift public API.

claritylift

Official Python SDK for the ClarityLift public API.

Install

pip install claritylift

Quickstart

import os
from claritylift import ClarityLiftClient

with ClarityLiftClient(token=os.environ["CLARITYLIFT_API_TOKEN"]) as client:
    teams = client.list_teams()
    for team in teams:
        if team.get("kind") == "scored":
            print(team["name"], team["score"], team.get("deviationLabel"))

    trends = client.trending_topics(window="30d")

    topic = client.query_topics(q="benefits plan", window="30d")
    if topic.get("belowFloor"):
        print("Insufficient volume for this query.")
    else:
        print(topic.get("synthesis"))

Scopes

Create tokens at /dashboard/settings/api-tokens. Minimum scope per call:

Method	Scope
list_teams / list_team_signals / team_scores_timeseries	read:teams / read:signals / read:scores
trending_topics / query_topics	read:topics
create_intervention	write:interventions
create_goal / update_goal / archive_goal	write:goals
create_webhook / list_webhooks / delete_webhook	write:webhooks

Idempotency

Every write accepts an optional idempotency_key:

client.create_intervention(
    signal_id=signal_id,
    notes="1:1 scheduled",
    confidence="medium",
    idempotency_key="action-2026-04-22-abc",
)

Replays within 24 hours return the original response.

Rate limits

Per-token default: 600 requests/hour. On 429 the client waits for the Retry-After seconds (capped at 60s) and retries once. Subsequent 429s raise ApiError — let the caller back off.

Error handling

from claritylift import ApiError

try:
    client.create_goal(name="Ship Q2 rollout")
except ApiError as err:
    print(err.status, err.code, err.message)

Spec

The OpenAPI definition lives at /api/public/v1/openapi.json.