Java SDK

Run prompts and workflows, manage knowledge bases, and verify webhooks from Java.

The PromptJuggler Java SDK is a thin, typed wrapper over the public REST API. You call flat, synchronous methods and get back typed model objects — authentication, request building, and JSON (de)serialization are handled for you. It runs on the JDK’s built-in HTTP client, so it pulls in no third-party HTTP stack.

Requirements

• Java 17 or newer

Installation

Gradle

implementation("com.promptjuggler:promptjuggler-java:1.0.0")

Use the latest version from Maven Central.

Set up the client

Create an API key in Settings, then construct the client once and reuse it (it is thread-safe):

import com.promptjuggler.PromptJuggler;

PromptJuggler pj = new 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 two-argument constructor: new PromptJuggler(apiKey, baseUrl).

Per-endpoint usage

Every endpoint in the API reference includes a Java 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:

import com.promptjuggler.client.model.CreatePromptRunResponse;
import com.promptjuggler.client.model.PromptRun;
import com.promptjuggler.client.model.RunStatus;
import java.util.Map;

// Trigger a run (async — returns immediately with the run ID)
CreatePromptRunResponse created = pj.runPrompt("greeting", "production", Map.of("name", "Ada"));

// Poll for the result
PromptRun run = pj.getPromptRun(created.getId());
if (run.getStatus() == RunStatus.COMPLETED) {
    System.out.println(run.getOutput());
}

Optional run parameters (priority, thread, environment, metadata, …) go through a RunOptions builder passed as the last argument:

import com.promptjuggler.RunOptions;

RunOptions options = RunOptions.builder().environment("staging").priority("onsite").build();
pj.runPrompt("greeting", "production", Map.of("name", "Ada"), options);

Methods return typed model objects with validated fields. They are read-only data — read the fields, don’t write them back. An enum value added to the API after your SDK version reads as UNKNOWN_DEFAULT_OPEN_API, or as null in a nullable field such as ModelParams.getReasoningEffort().

Error handling

When the API responds with an error status, the SDK throws an ApiError carrying the HTTP status code and the server’s message. When the request never reaches the API (DNS failure, timeout, offline), it throws a NetworkError. When the API replies with a success status but the SDK can’t decode the body (a tool type newer than the SDK, say), it throws a DecodeError: the request succeeded, so retrying a run starts a second one. All three extend PromptJugglerException, which is checked — every call that reaches the API declares throws PromptJugglerException, so the compiler makes you handle (or propagate) the failure. Catch the base to handle the whole surface at once, or catch ApiError first when you need the status code:

import com.promptjuggler.ApiError;
import com.promptjuggler.PromptJugglerException;

try {
    pj.getPrompt("does-not-exist", "production");
} catch (ApiError error) {
    error.statusCode(); // e.g. 404
    error.getMessage(); // the server's error message
} catch (PromptJugglerException error) {
    // a NetworkError, a DecodeError, or any other SDK failure
}

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 com.promptjuggler.Webhooks;

String payload = request.getBody(); // the raw request body, as text
String signature = request.getHeader("PromptJuggler-Signature");

if (!Webhooks.verifySignature(payload, signature, "your-webhook-secret")) {
    // reject the delivery (e.g. respond 403)
}

Webhooks.verifySignature 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 five-argument overload.