Java client library for the Gradient Labs API.
- 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)
For Spring Boot applications, use the starter dependency for zero-configuration setup:
<dependency>
<groupId>ai.gradientlabs</groupId>
<artifactId>gradient-labs-spring-boot-starter</artifactId>
<version>1.0.2</version>
</dependency>implementation 'ai.gradientlabs:gradient-labs-spring-boot-starter:1.0.2'Configure in your application.yml:
gradientlabs:
api-key: ${GLABS_API_KEY}base-url: https://api.gradient-labs.ai # optionalwebhook-signing-key: ${GLABS_WEBHOOK_KEY} # optionalwebhook-leeway: 10m# optional, defaults to 5mOr 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=10mThe client will be automatically configured and available for dependency injection:
importai.gradientlabs.client.GradientLabsClient;
importorg.springframework.stereotype.Service;
@ServicepublicclassConversationService {
privatefinalGradientLabsClientclient;
publicConversationService(GradientLabsClientclient) {
this.client = client;
}
publicvoidstartConversation(StringcustomerId) {
Conversationconv = client.startConversation(
StartConversationRequest.builder()
.id("conv-" + UUID.randomUUID())
.customerId(customerId)
.channel(Channel.CHAT)
.build()
);
}
}See the Spring Boot Starter README for more details.
For non-Spring applications, use the core client library:
<dependency>
<groupId>ai.gradientlabs</groupId>
<artifactId>gradient-labs-client</artifactId>
<version>1.0.2</version>
</dependency>implementation 'ai.gradientlabs:gradient-labs-client:1.0.2'importai.gradientlabs.client.exception.*;
try {
Conversationconv = client.startConversation(request);
} catch (ResponseExceptione) {
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 (GradientLabsExceptione) {
System.err.println("Client error: " + e.getMessage());
}importjava.net.http.HttpClient;
importjava.time.Duration;
HttpClientcustomClient = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(10))
.followRedirects(HttpClient.Redirect.NORMAL)
.build();
GradientLabsClientclient = GradientLabsClient.builder()
.apiKey(apiKey)
.httpClient(customClient)
.build();GradientLabsClientclient = GradientLabsClient.builder()
.apiKey(apiKey)
.baseUrl("https://custom-api.example.com")
.build();importjava.time.Duration;
GradientLabsClientclient = GradientLabsClient.builder()
.apiKey(apiKey)
.webhookSigningKey(webhookKey)
.webhookLeeway(Duration.ofMinutes(10)) // Accept webhooks up to 10 minutes old
.build();- Java 17 or higher
- Jackson 2.18+ for JSON serialization
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
Contributions are welcome! Please see CONTRIBUTING.md for details.
MIT License - see LICENSE for details.
For issues and questions: