Installation

nozle-sdk supports Python 3.9 through 3.13, uses requests, and includes a py.typed marker. Entity subscription APIs are introduced in 0.5.0.

pip install nozle-sdk==0.13.1

Version 0.13.1 changes wrap_openai() and wrap_anthropic() to return a client view instead of patching the client you pass in; use the returned client. See Client wrappers. Version 0.13.0 adds AsyncNozle, opt-in retries, the host argument, an optional api_key that reads NOZLE_SECRET_KEY, request_id and retry_after on NozleAPIError, usage capture for any httpx-based LLM client, Core usage reads, and the invoices, alerts and webhooks namespaces. Version 0.12.0 adds billing_configuration to customers.upsert(). Version 0.11.0 sends Feature Events through the Go Engine endpoint. Version 0.10.0 adds NozleAPIError.code and has_code(), richer checkout result types, and no longer requires feature in check_and_deduct(). Version 0.9.1 fixes Feature Event timestamp serialization, including events created by the OpenAI and Anthropic wrappers. Version 0.9.0 introduced subscription options, signed quotes, pending-change withdrawal, and scoped checkout recovery. See subscription self-service and the release notes.

Create a client

import os
from nozle import Nozle


nozle = Nozle(
    api_key=os.environ["NOZLE_SECRET_KEY"],
    timeout=10,
)

Argument	Type	Default	Description
`api_key`	`str \| None`	`NOZLE_SECRET_KEY` environment variable	Organization credential. Protected operations require `sk_`. When you do not pass it, the client reads `NOZLE_SECRET_KEY`; if that is not set it raises `ValueError`.
`host`	`str`	`https://api.nozle.app`	Keyword-only. Root API origin. The SDK sends Engine calls to `{host}/engine` and Core calls to `{host}/core`. Set only this for a local or self-hosted deployment behind one reverse proxy.
`base_url`	`str`	`https://api.nozle.app/engine`	Engine API origin for `track()`, entitlements, credits, Entities, usage, and margin. Overrides the address derived from `host`.
`events_url`	`str`	`https://api.nozle.app/core`	Core API origin for customer writes, billing resources, subscription discovery, credit-system discovery, and Entity subscriptions. Use `https://api.nozle.app/core` in production. Overrides the address derived from `host`.
`timeout`	`float`	`10`	Per-attempt timeout in seconds.
`max_retries`	`int`	`0`	Keyword-only. Extra attempts after a network error, timeout, `429` or `5xx`. `0` never retries. See errors and retries.
`retry_delay`	`float`	`0.5`	Keyword-only. First retry delay in seconds. It doubles each retry up to 10 seconds, or the `Retry-After` header is used when sent.

The client defaults to the public service bases under https://api.nozle.app. For a local or self-hosted deployment behind one proxy, set host. Set base_url or events_url only when the two services live at unrelated addresses; each one you set wins over host. If you set only one of them, the other service still uses host (by default production), so set host too. Trailing slashes are removed automatically.

Manage the HTTP session

Nozle is synchronous and owns a reusable requests.Session. Use it as a context manager when its lifetime is scoped:

with Nozle(
    api_key=os.environ["NOZLE_SECRET_KEY"],
    base_url="https://api.nozle.app/engine",
    events_url="https://api.nozle.app/core",
) as nozle:
    health = nozle.ping()

For an application-wide singleton, call nozle.close() during shutdown.

Async client

Version 0.13.0 adds AsyncNozle for asyncio applications such as FastAPI, so SDK calls do not block the event loop. It takes the same arguments as Nozle and has the same namespaces and methods; every method that calls the API is awaited. It sends requests with httpx.AsyncClient, so install the httpx extra:

pip install "nozle-sdk[httpx]"

from nozle import AsyncNozle

async with AsyncNozle(max_retries=2) as nozle:  # reads NOZLE_SECRET_KEY
    decision = await nozle.can("customer-123", "export")
    await nozle.usage.track("customer-123", "emails", idempotency_key=message_id)
    invoices = await nozle.invoices.list("customer-123")

Validation, NozleAPIError (with request_id and retry_after), retries and idempotency keys behave exactly as in Nozle. Retries wait with asyncio.sleep.
For an application-wide client, call await nozle.aclose() during shutdown.
events.create_transaction_id() and cost_events.create_cost_event_id() make no request and are not awaited.
await nozle.webhooks.verify(body, headers) is awaited, because a jwt endpoint reads Nozle’s public key once.
For LLM auto-capture, use nozle.capture_async_http_client(...) or wrap an httpx.AsyncClient. AsyncNozle does not wrap a synchronous httpx.Client; use Nozle there.

Authentication model

plans() accepts either a publishable pk_ or secret sk_ key.
Every customer, event, checkout, subscription, credit, Entity, usage, entitlement, health, and margin operation requires sk_.
Wrong key types fail locally with NozleAuthenticationError before network I/O.

This is a backend SDK. Never expose an sk_, master key, or internal credential to browser or mobile code.

API surface

Area	Methods
API	`ping()`, `plans()`, `track()`, `can()`
Usage reads	`current_usage()`, `past_usage()`
Billing	`checkout()`, `checkout_status()`, `verify_checkout()`, `checkout_invoice()`, `subscribe()`, `cancel_subscription()`, `subscription_options()`, `preview_subscription_change()`, `withdraw_pending_subscription_change()`, `preview_subscription_transition()`, `apply_subscription_transition()`
Invoices	`invoices.list()`, `invoices.get()`, `invoices.download_url()`
Alerts	`alerts.list()`, `alerts.get()`, `alerts.create()`, `alerts.update()`, `alerts.delete()`
Webhooks	`webhooks.verify()`
Customers	`customers.upsert()`
Credit systems	`credit_systems.list()`
Entities	`get()`, `list()`, `upsert()`, `activate()`, `suspend()`, `bulk_upsert()`
Entity subscriptions	`ensure()`, `get()`, `list()`, `checkout()`, `checkout_many()`, `change_plan()`, `cancel()`, `remove()`
Credits	Customer and Entity balance/history reads, `allocate()`, `deallocate()`
Usage	Advisory `check()` and atomic `track()`
Cost events	`cost_events.track()`
Margin	`summary()`, `by_customer()`, `by_metric()`, `by_plan()`, `by_model()`, `trend()`
LLMs	`wrap_openai()`, `wrap_anthropic()`, `wrap_http_client()`, `capture_http_client()`, `capture_async_http_client()`, `record_usage()`

Usage reads, invoices, alerts, webhooks, wrap_http_client(), capture_http_client(), capture_async_http_client() and record_usage() require 0.13.0. check_and_deduct(customer_id, credits=5) remains available for the legacy wallet path. The feature argument is deprecated and ignored.

Transport behavior

Retries are off by default (max_retries=0), so a mutation executes at most once per SDK call.
With max_retries set, reads are retried, and a write is retried only when it is idempotent or carries an idempotency key.
Connection and timeout failures raise NozleTransportError.
Non-2xx responses raise structured NozleAPIError.
Sensitive values in API error payloads are redacted.

See Errors and retries for handling guidance.

Setup

Billing

Customers

Entitlements

Margin Intelligence

LLM Usage

Installation

Create a client

Manage the HTTP session

Async client

Authentication model

API surface

Transport behavior

Next steps

​Create a client

​Manage the HTTP session

​Async client

​Authentication model

​API surface

​Transport behavior

​Next steps

Create a client

Manage the HTTP session

Async client

Authentication model

API surface

Transport behavior

Next steps