citeflow-python 0.1.1

Official Python SDK for the CiteFlow API (SEO, AEO, GEO audits).

citeflow-python

Official Python SDK for the CiteFlow Partner API — programmatic SEO, AEO, and GEO audits.

CiteFlow is an AI-visibility scanner: it audits how well a website can be crawled, understood, and cited by AI search engines (ChatGPT, Claude, Perplexity, Google AI Overviews). This SDK lets partners run those audits from their own products via the CiteFlow Partner API.

• Website: https://citeflow.io
• API docs & getting started: https://citeflow.io/help/partner-api
• Dashboard (API keys, billing, webhooks): https://citeflow.io/dashboard/api

Install

pip install citeflow-python

Python 3.9+ required. Depends on requests.

Quickstart

import os
from citeflow import Citeflow

client = Citeflow(api_key=os.environ["CITEFLOW_API_KEY"])

# Create an audit and wait for the result (~30s for SEO).
audit = client.audits.create(url="https://example.com", type="seo")
result = client.audits.wait_for_completion(audit["audit_id"], timeout=90)

if result["status"] == "complete":
    print("Scores:", result["scores"])
elif result["status"] == "failed":
    print("Failure:", result["failure_reason"])

# Check remaining balance.
b = client.balance.retrieve()
print(f"Balance: {b['balance_usd']} ({b['balance']} credits)")

Features

• Auto-retry on 429 and 5xx with exponential back-off + jitter. Honors Retry-After.
• Auto Idempotency-Key on every POST — safe to retry on network failure without double-charging.
• wait_for_completion polling helper with configurable timeout.
• HMAC webhook verification with timestamp tolerance + rotation grace handling.
• Pluggable requests.Session for custom proxies / adapters.

Webhook verification

from citeflow import verify_webhook_signature, parse_webhook_event, CiteflowSignatureError

# In your webhook handler (Flask, FastAPI, Django, …):
raw_body = request.get_data()  # bytes — do NOT JSON-parse first
try:
    event = parse_webhook_event(
        raw_body=raw_body,
        headers=request.headers,
        secret=os.environ["CITEFLOW_WEBHOOK_SECRET"],
    )
    # event["type"] in {"audit.completed", "audit.failed", "audit.cancelled", "balance.low"}
    print(event["id"], event["type"], event["data"])
    return "", 200
except CiteflowSignatureError:
    return "", 400

Errors

from citeflow import CiteflowError

try:
    client.audits.create(url="invalid", type="seo")
except CiteflowError as err:
    print(err.code, err.request_id)
    if err.code == "INSUFFICIENT_CREDITS":
        print(f"Need {err.required} more credits")

Full error catalog: https://citeflow.io/help/partner-api#troubleshooting.

Configuration

client = Citeflow(
    api_key="ckf_…",
    base_url="https://www.citeflow.io/api/v1",  # default; override only for staging/self-hosted
    timeout=30.0,                            # per-request seconds
    max_retries=3,                           # for 429 + 5xx + network
)

License

MIT. CiteFlow API itself is a paid service — see https://citeflow.io/terms-of-service.