Quickstart with Java

This quickstart walks you through minting an API token, adding the PromptHelm Java SDK to a Maven or Gradle project, and making your first call from Java. By the end you will have a working completion, an Iterator-based streaming example, and a checklist for production deployment.

1. 1

   Generate an API token

   Sign in to the dashboard and open Settings → API tokens. Click New token, name it (e.g. backend-service-dev), and copy the value immediately — tokens are revealed exactly once.

   Export the token in your shell or load it from your secrets manager at startup:

   PROMPTHELM_API_KEY=ph_live_your_token_here

2. 2

   Add the SDK

   Add the dependency to your build file. The artifact is published to Maven Central, so no extra repository configuration is required.

   MavenGradle (Kotlin DSL)Gradle (Groovy)

   <dependency>
       <groupId>app.prompthelm</groupId>
       <artifactId>sdk-java</artifactId>
       <version>0.1.0</version>
   </dependency>

3. 3

   Create your first prompt

   In the dashboard, navigate to Prompts → New prompt. Give it a slug (for example, welcome), pick a default model, and use {{ variable_name }} syntax for runtime variables. Saving publishes v1 on the main environment.

   Learn more

   See Concepts → Prompts for versions, environments, and promotion semantics.

4. 4

   Call it from Java

   Build the client once at startup using the fluent builder. The instance is thread-safe and meant to be reused across requests.

   import app.prompthelm.sdk.*;
   
   PromptHelm ph = PromptHelm.builder()
       .apiKey(System.getenv("PROMPTHELM_API_KEY"))
       .build();
   
   ExecuteResponse response = ph.execute(new ExecuteRequest(
       "welcome",                        // promptSlug
       null,                             // promptId
       Map.of("name", "World"),          // variables
       null, null, null, null, null,
       null, null, null, null
   ));
   
   System.out.println(response.output());

   The call appears in the dashboard's Logs view with the full request/response payload, the per-call cost, and the round-trip latency.

5. 5

   Stream with an Iterator

   For server-side streaming endpoints, the SDK exposes a blocking Iterator<StreamEvent>. Each next() call yields a chunk, a terminal DoneEvent, or an ErrorEvent.

   ExecuteRequest req = new ExecuteRequest(
       "welcome", null, Map.of("name", "World"),
       null, null, null, null, null, null, null, null, null
   );
   
   Iterator<StreamEvent> stream = ph.stream(req);
   while (stream.hasNext()) {
       StreamEvent event = stream.next();
       if (event instanceof ChunkEvent c) {
           System.out.print(c.content());
       } else if (event instanceof DoneEvent d) {
           System.out.printf("%n%d tokens, $%.4f%n", d.totalTokens(), d.cost());
       } else if (event instanceof ErrorEvent e) {
           System.err.printf("Error %s: %s%n", e.errorCode(), e.message());
       }
   }

   Closing the iterator (or the enclosing try-with-resources on the client) closes the underlying SSE connection cleanly.

6. 6

   Ship to production

   Before you point real traffic at PromptHelm, run through this checklist:

   • Construct PromptHelm once per process. It owns an HTTP client pool — sharing the instance across requests avoids connection churn. Wrap it in try-with-resources (it implements AutoCloseable) during graceful shutdown.
   • Source the API key from a secrets manager. Inject it via System.getenv for plain Java apps, or @Value("${prompthelm.api-key}") for Spring Boot.
   • Tune retries and timeouts on the builder. The default policy retries idempotent failures with jittered backoff; raise the timeout past 15 s only when calling models with long thinking budgets.
   • Catch typed errors. Every SDK call throws PromptHelmException with a stable errorCode(). Map well-known codes to retries or user-facing messages.
   • Pin an environment. Default main to production traffic and promote new prompt versions through staging and dev first.
   • Run on Java 17 LTS or newer. Earlier versions are not supported.

Next steps