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

Maven
Gradle

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

implementation("com.openai:openai-java:0.8.1")

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();

Header	Description
`Floopy-Cache`	Cache strategy: `semantic` or `exact`
`floopy-property-*`	Attach custom metadata for filtering in the dashboard
`floopy-fallback`	Fallback model if the primary provider fails
`floopy-session-id`	Group related requests into a session
`floopy-user-id`	Associate requests with an end user

See the Headers Reference for the full list.