Skip to content
Floopy Docs

Java / Kotlin

Overview

Floopy is a zero-SDK gateway. The official openai-java SDK supports custom base URLs, so you can route all requests through Floopy without any extra dependencies. You get caching, rate limiting, fallbacks, and observability for free.

Installation

<dependency>
  <groupId>com.openai</groupId>
  <artifactId>openai-java</artifactId>
  <version>0.8.1</version>
</dependency>

Configuration

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;


OpenAIClient client = OpenAIOkHttpClient.builder()
    .baseUrl("https://api.floopy.ai/v1")
    .apiKey(System.getenv("FLOOPY_API_KEY")) // starts with fp_
    .build();

Set FLOOPY_API_KEY in your environment. You can create one in the dashboard.

Basic Request

import com.openai.models.ChatCompletionCreateParams;
import com.openai.models.ChatCompletion;


ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
    .model("gpt-4o")
    .addUserMessage("Explain quantum computing in one sentence.")
    .build();


ChatCompletion completion = client.chat().completions().create(params);


String content = completion.choices().get(0).message().content().orElse("");
System.out.println(content);

Streaming

import com.openai.models.ChatCompletionCreateParams;


ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
    .model("gpt-4o")
    .addUserMessage("Write a short poem.")
    .build();


client.chat().completions().createStreaming(params).stream()
    .flatMap(completion -> completion.choices().stream())
    .forEach(choice -> {
        choice.delta().content().ifPresent(System.out::print);
    });

Custom Headers

Pass Floopy-specific headers by configuring the HTTP client:

import okhttp3.OkHttpClient;
import okhttp3.Interceptor;


OkHttpClient httpClient = new OkHttpClient.Builder()
    .addInterceptor(chain -> {
        var request = chain.request().newBuilder()
            .addHeader("Floopy-Cache", "semantic")
            .addHeader("floopy-property-environment", "production")
            .addHeader("floopy-fallback", "claude-sonnet-4-20250514")
            .build();
        return chain.proceed(request);
    })
    .build();


OpenAIClient client = OpenAIOkHttpClient.builder()
    .baseUrl("https://api.floopy.ai/v1")
    .apiKey(System.getenv("FLOOPY_API_KEY"))
    .okHttpClient(httpClient)
    .build();
HeaderDescription
Floopy-CacheCache strategy: semantic or exact
floopy-property-*Attach custom metadata for filtering in the dashboard
floopy-fallbackFallback model if the primary provider fails
floopy-session-idGroup related requests into a session
floopy-user-idAssociate requests with an end user

See the Headers Reference for the full list.