# Java

Use the Kirora HTTP API from Java while the official client is planned.

The official Java client is planned and has no announced release date. Until it is available, use the HTTP API with the example below. The Maven coordinates will be confirmed when the client is released.

## What it will cover

The Java client will follow the [SDK conformance](/docs/api/sdk-conformance) checklist and copy the shape of the [Node.js reference library](/docs/sdks/node): one namespace per API tag and one method per `operationId` (`client.contacts().identify(...)`, `client.events().track(...)`), a single exception carrying the API's `code`, bounded retries with jitter on 429 and 5xx, an injectable HTTP client, auto-paginating iterators, caller-supplied idempotency keys, and a constant-time webhook verifier.

## Use the HTTP API today

Call the API directly with your key as a bearer token, using the JDK's `java.net.http` client (Java 15 or later for text blocks). [`trackEvent`](/docs/api/reference/trackEvent) requires an `Idempotency-Key`; derive it from your own order or event id so a retry is recorded once. To track an event:

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class TrackEvent {
    public static void main(String[] args) throws Exception {
        String body = """
            {"externalId":"cust_1042","eventName":"Order Completed",
             "properties":{"orderId":"1042","total":42.5,"currency":"USD"}}
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.kirora.io/v1/events/track"))
            .timeout(Duration.ofSeconds(30))
            .header("Authorization", "Bearer " + System.getenv("KIRORA_API_KEY"))
            .header("Idempotency-Key", "order-1042-completed")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}
```

See [Errors](/docs/api/errors) and [Idempotency](/docs/api/idempotency) before adding retries.