Initialization

Constructor


import com.canarygate.CanaryGateClient;
import com.canarygate.Options;
 
CanaryGateClient client = new CanaryGateClient("cg_api_key", new Options());

Parameters

Parameter	Type	Required	Description
`apiKey`	`String`	Yes	Environment API Key. Created under Settings → API Keys.
`options`	`Options`	No	Configuration options. See below.

`Options`

Option	Type	Default	Description
`baseUrl`	`String`	`http://localhost:3001`	API base URL (useful for self-hosted environments or proxies).
`environment`	`String`	default environment	Environment slug, sent via the `X-Environment` header.
`stream`	`boolean`	`false`	Opt in to real-time SSE streaming.
`reconnectDelayMs`	`long`	`5000`	Initial delay in ms before reconnecting a dropped stream.
`maxReconnectDelayMs`	`long`	`30000`	Maximum backoff delay in ms for stream reconnection.
`heartbeatTimeoutMs`	`long`	`65000`	Time in ms without a server heartbeat before the stream is considered dead and reconnects.

`init()`


client.init();

Executes two actions in sequence:

Makes an HTTP fetch to load all flags for the environment (snapshot)
Opens the SSE connection — only when stream is enabled. Otherwise flags come from the snapshot request only.

After a successful init(), getFlag() reads from the local cache; if the connection degrades later, isStale() reports it and getFlag() continues to return the last known values.

Examples

Spring Boot (singleton with streaming)


import com.canarygate.CanaryGateClient;
import com.canarygate.Options;
import org.springframework.stereotype.Service;
 
@Service
public class CanaryGateService implements AutoCloseable {
 
    private final CanaryGateClient client;
 
    public CanaryGateService() {
        this.client = new CanaryGateClient(
            System.getenv("CANARYGATE_KEY"),
            new Options(
                "https://flags.canarygate.dev",
                "production",
                true,
                5000,
                30000,
                65000
            )
        );
        this.client.init();
    }
 
    public boolean isNewCheckoutEnabled(String userId) {
        var flag = client.getFlag("new-checkout", new FlagEvaluationContext(userId));
        return flag != null && flag.isEnabled();
    }
 
    @Override
    public void close() {
        client.disconnect();
    }
}

One-shot script (no stream)


import com.canarygate.CanaryGateClient;
 
var client = new CanaryGateClient("cg_api_key");
client.init();
 
var flag = client.getFlag("run-migration", null);
if (flag != null && flag.isEnabled()) {
    runMigration();
}
 
// Disconnect (closes any active stream) so the process can exit
client.disconnect();