Skip to main content

Python SDK

The zeridion-flare package is published on PyPI and follows the same wire contract as every other Flare SDK.

pip install zeridion-flare

Requires: Python 3.10+ · httpx>=0.27 (declared as a dependency; pip installs it for you).

Type hints​

The SDK is fully typed using Python 3.10+ union syntax (str | None, dict[str, Any]) — no Optional[...] / Union[...] imports needed. Method signatures, dataclass fields, and exception attributes all carry runtime-checkable annotations, so mypy / pyright / your IDE will flag drift without you re-typing anything.

Current API surface​

The client exposes flat methods (one per endpoint) rather than nested namespaces, and returns plain dict payloads matching the wire format.

from zeridion_flare import FlareClient

flare = FlareClient(api_key="zf_live_sk_...")

# Enqueue a job — optional request_id / idempotency_key are accepted per call.
# - idempotency_key dedupes a replayed write (same key + same body → original response).
# - request_id is a log-correlation hint (your trace ID flows into Zeridion's logs);
#   omit it and the server returns a generated ULID in the response X-Request-Id header.
job = flare.create_job(
    job_type="SendWelcomeEmail",
    payload={"email": "alice@example.com", "name": "Alice"},
    queue="default",
    max_attempts=3,
)
print(job["id"], job["state"])  # "job_abc123", "pending"

# Get job status
detail = flare.get_job(job["id"])

# List jobs (returns a dict with "jobs" + "has_more" + "next_cursor")
page = flare.list_jobs(state="failed", limit=25)
for j in page["jobs"]:
    print(j["id"], j["state"])

# Cancel / retry
flare.cancel_job(job["id"])
flare.retry_job(job["id"])

Constructor options​

KeywordDefaultDescription
api_keyos.environ["FLARE_API_KEY"]Required — pass directly or via env var.
base_urlhttps://api.zeridion.comOverride for dev / staging.
max_retries3Maximum retry attempts on 429 / 5xx / network errors. Set 0 to disable.
retry_base_delay_ms500Base for the exponential backoff schedule.
retry_max_delay_ms30000Cap on a single backoff wait (and on Retry-After).
max_response_bytes10 * 1024 * 1024 (10 MiB)Hard cap on response body size; protects against an unbounded body. Set 0 to disable.

Typed error hierarchy​

The following are importable from zeridion_flare:

ClassHTTPWhen it fires
FlareError—Base class for every SDK exception
AuthError401Missing / invalid / revoked API key
QuotaError402Daily quota exceeded for the project
NotFoundError404Resource doesn't exist (or returns None on GETs)
ConflictError409Idempotency or invalid-state conflict
RateLimitError429Rate-limited; inspect .retry_after, .limit, .remaining

Webhook verification​

from zeridion_flare import verify_webhook

verify_webhook(payload=request_body, header=request.headers["zeridion-signature"], secret=...)

Planned features​

  • Built-in worker loop (def execute(payload: dict) handlers, sync today; async variant tracked separately if there is demand)
  • Recurring job support
  • Custom tags + progress reporting

The synchronous client is what ships today. There is no AsyncFlareClient on the immediate roadmap — if asyncio support is a hard requirement for your stack, wrap FlareClient calls in asyncio.to_thread() for now and tell us via GitHub issues, which will prioritise a native async client.

See also​