Gradient Labs Java Client

Java client library for the Gradient Labs API.

Features

• Idiomatic Java API with fluent builders
• Type-safe models and enums
• Webhook signature verification
• Comprehensive error handling
• Java 17+ compatible
• Zero runtime dependencies (except Jackson)

Spring Boot Integration

For Spring Boot applications, use the starter dependency for zero-configuration setup:

Maven

<dependency>
    <groupId>ai.gradientlabs</groupId>
    <artifactId>gradient-labs-spring-boot-starter</artifactId>
    <version>1.0.2</version>
</dependency>

Gradle

implementation 'ai.gradientlabs:gradient-labs-spring-boot-starter:1.0.2'

Configuration

Configure in your application.yml:

gradientlabs:
  api-key: ${GLABS_API_KEY}
  base-url: https://api.gradient-labs.ai  # optional
  webhook-signing-key: ${GLABS_WEBHOOK_KEY}  # optional
  webhook-leeway: 10m  # optional, defaults to 5m

Or in application.properties:

gradientlabs.api-key=${GLABS_API_KEY}
gradientlabs.base-url=https://api.gradient-labs.ai
gradientlabs.webhook-signing-key=${GLABS_WEBHOOK_KEY}
gradientlabs.webhook-leeway=10m

Usage

The client will be automatically configured and available for dependency injection:

import ai.gradientlabs.client.GradientLabsClient;
import org.springframework.stereotype.Service;

@Service
public class ConversationService {

    private final GradientLabsClient client;

    public ConversationService(GradientLabsClient client) {
        this.client = client;
    }

    public void startConversation(String customerId) {
        Conversation conv = client.startConversation(
            StartConversationRequest.builder()
                .id("conv-" + UUID.randomUUID())
                .customerId(customerId)
                .channel(Channel.CHAT)
                .build()
        );
    }
}

See the Spring Boot Starter README for more details.

Installation (Standalone)

For non-Spring applications, use the core client library:

Maven

<dependency>
    <groupId>ai.gradientlabs</groupId>
    <artifactId>gradient-labs-client</artifactId>
    <version>1.0.2</version>
</dependency>

Gradle

implementation 'ai.gradientlabs:gradient-labs-client:1.0.2'

Error Handling

import ai.gradientlabs.client.exception.*;

try {
    Conversation conv = client.startConversation(request);
} catch (ResponseException e) {
    System.err.println("API error: " + e.getMessage());
    System.err.println("Status code: " + e.getStatusCode());
    System.err.println("Trace ID: " + e.getTraceId());

    if (e.getDetails() != null) {
        System.err.println("Details: " + e.getDetails());
    }
} catch (GradientLabsException e) {
    System.err.println("Client error: " + e.getMessage());
}

Configuration

Custom HTTP Client

import java.net.http.HttpClient;
import java.time.Duration;

HttpClient customClient = HttpClient.newBuilder()
    .connectTimeout(Duration.ofSeconds(10))
    .followRedirects(HttpClient.Redirect.NORMAL)
    .build();

GradientLabsClient client = GradientLabsClient.builder()
    .apiKey(apiKey)
    .httpClient(customClient)
    .build();

Custom Base URL

GradientLabsClient client = GradientLabsClient.builder()
    .apiKey(apiKey)
    .baseUrl("https://custom-api.example.com")
    .build();

Webhook Configuration

import java.time.Duration;

GradientLabsClient client = GradientLabsClient.builder()
    .apiKey(apiKey)
    .webhookSigningKey(webhookKey)
    .webhookLeeway(Duration.ofMinutes(10))  // Accept webhooks up to 10 minutes old
    .build();

Requirements

• Java 17 or higher
• Jackson 2.18+ for JSON serialization

Security: eMudhra certificate authority compromise

The client uses the JDK's built-in HttpClient, which trusts the CA certificates bundled with your JDK (cacerts), not the operating system's store. JDKs up to and including 27.0.1, 25.0.5, 21.0.13 and 17.0.21 still trust the eMudhra intermediate certificate authorities compromised in October 2026, which would let an attacker impersonate the Gradient Labs API and capture your API key.

Run JDK 27.0.1.0.2, 25.0.5.0.2, 21.0.13.0.2, 17.0.21.0.2, or the equivalent fixed build from your JDK vendor. JDKs installed from Linux distribution packages use the OS certificate store, so updating the OS CA certificates is enough for those. See the OpenJDK advisory.

If your JDK vendor hasn't shipped a fixed build yet, Oracle's advisory describes two workarounds: replace $JAVA_HOME/lib/security/blocked.certs with the version it links to, or enable revocation checking with -Dcom.sun.net.ssl.checkRevocation=true -Dcom.sun.security.enableCRLDP=true.

Documentation

• API Documentation
• Javadoc
• Design Document

Examples

See the examples/ directory for complete working examples:

• Basic Conversation - Starting and managing conversations
• Webhook Handler - Handling webhook events
• Notes Example - Creating and managing notes
• Hand-Off Targets Example - Managing hand-off targets for conversation routing
• Articles Example - Managing articles and topics for the knowledge base
• Procedures Example - Managing procedures and versions for AI agent instructions

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

License

MIT License - see LICENSE for details.

Support

For issues and questions:

• GitHub Issues
• API Documentation
• Email: support@gradient-labs.ai