Skip to main content
The PromptJuggler Python SDK is a thin, typed wrapper over the public REST API. You call flat, synchronous methods and get back pydantic models — authentication, request building, and JSON (de)serialization are handled for you.

​
Requirements

  • Python 3.10 or newer

​
Installation

​
Set up the client

Create an API key in Settings, then construct the client once and reuse it:
The key is sent as a Bearer token to https://promptjuggler.com. Point the SDK at another host (e.g. for testing) with the base_url= argument.

​
Per-endpoint usage

Every endpoint in the API reference includes a Python SDK code sample showing the exact call — that’s the place to look for how to invoke each operation and what it returns. A typical flow:
Methods return pydantic models with typed, validated fields. They are read-only data — read the fields, don’t write them back.

​
Error handling

When the API responds with an error status, the SDK raises an ApiError carrying the HTTP status code and the server’s message. When the request never reaches the API (DNS failure, timeout, offline), it raises a NetworkError. Both extend the PromptJugglerError base class, so you can catch the whole surface at once.
You never catch a generated-client error — the SDK translates the underlying client’s errors into its own.

​
Webhooks

PromptJuggler signs every webhook with the PromptJuggler-Signature header. Verify it against the raw request body, before any JSON parsing:
verify_webhook_signature recomputes the HMAC-SHA256 of {timestamp}.{raw_body}, compares it in constant time, and rejects deliveries whose timestamp falls outside a tolerance window (default 300s) to prevent replay. Widen or narrow it with the tolerance= argument.