SDKs

Sieve does not ship its own SDK. The API follows TypeSafe's System One contract, so the official TypeSafe SDKs work unmodified once they point at https://api.sieve.one with a Sieve key. For /v1/decisions, use an OpenAI SDK instead (see /v1/decisions).

InstallCopy Anchor Link

pip install "typesafe-sdk[zstd]"
# or
uv add "typesafe-sdk[zstd]"

ConfigureCopy Anchor Link

Explicit constructor options win over environment variables. Empty environment values are ignored.

from typesafe_sdk import TypeSafeClient

client = TypeSafeClient(
    api_key="sieve_app_live_...",          # or TYPESAFE_API_KEY
    base_url="https://api.sieve.one",  # or TYPESAFE_BASE_URL
    model="sieve-latest",            # or TYPESAFE_DEFAULT_MODEL
)

List modelsCopy Anchor Link

for model in client.models.list().models:
    print(model.name)

The list contains only the models your key is allowed to use. See Authentication and keys.

Timeouts and retriesCopy Anchor Link

Both SDKs default to a 10 second timeout and 2 retries after the first attempt, with exponential backoff. They retry 408, 429 and 5xx responses (including 529) and connection errors, and they wait as long as the retry-after or retry-after-ms header asks. A 429 for an empty prepaid balance (insufficient_quota) is retried too but will keep failing until credits are added, so handle it in your code. See Errors.

from typesafe_sdk import RetryPolicy, TypeSafeClient

client = TypeSafeClient(
    model="sieve-latest",
    timeout=20.0,                          # seconds
    retry=RetryPolicy(max_retries=4),      # RetryPolicy(max_retries=0) turns retries off
)

To make a retried decision safe to repeat, send an Idempotency-Key header. See Errors.

CompressionCopy Anchor Link

The SDKs compress request bodies of 1 KiB or more with zstd by default, and the gateway accepts it.

• Python: needs the zstd extra on 3.13 and older. Without it, bodies are sent uncompressed.
• JavaScript: zstd needs Node.js 22.15 or newer. Older versions send uncompressed bodies.
• Behind LiteLLM proxy, which cannot read zstd bodies, turn compression off: compression=False in Python, compression: false in JavaScript.

See Limits for the body-size and encoding rules.

Next stepsCopy Anchor Link