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

pip install promptjuggler

​
Set up the client

Create an API key in Settings, then construct the client once and reuse it: 
from promptjuggler import PromptJuggler

pj = PromptJuggler("your-api-key")
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: 
from promptjuggler import RunStatus

# Trigger a run (async — returns immediately with the run ID)
created = pj.run_prompt("greeting", "production", {"name": "Ada"})

# Poll for the result
run = pj.get_prompt_run(created.id)
if run.status == RunStatus.COMPLETED:
    print(run.output)
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. 
from promptjuggler import ApiError

try:
    revision = pj.get_prompt("does-not-exist", "production")
except ApiError as error:
    error.status_code  # e.g. 404
    str(error)         # the server's error message
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: 
import json

from promptjuggler import verify_webhook_signature

payload = request.body  # the raw request body, as text
signature = request.headers.get("PromptJuggler-Signature", "")

if not verify_webhook_signature(payload, signature, "your-webhook-secret"):
    ...  # reject the delivery (e.g. respond 403)

event = json.loads(payload)
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.