Java SDK

The official Java SDK is published on Maven Central as dev.sybilion:sybilion. It ships two layers in one artifact:

• com.sybilion — the hand-written wrapper exposed to users (Client, Options, forecasts().waitUntilSettled, pagination callbacks).
• com.sybilion.generated — the OpenAPI-generated DefaultApi and model classes. Accessible via c.defaultApi() as an escape hatch for endpoints not yet wrapped.

This page documents the wrapper's idioms. For canonical use cases (forecasts, drivers, alerts, account, regions/categories), see the Features section — every example there has a Java tab.

Install

Maven

<dependency>
  <groupId>dev.sybilion</groupId>
  <artifactId>sybilion</artifactId>
</dependency>

Gradle

implementation 'dev.sybilion:sybilion'

Requires Java 11+. CI runs on Java 17.

Construct a client

import com.sybilion.Client;
import com.sybilion.Options;

// Token read from SYBILION_API_TOKEN automatically:
Client c = new Client(Options.builder().build());

// Or pass it explicitly:
Client c = new Client(
    Options.builder()
        .token(System.getenv("SYBILION_API_TOKEN"))
        .build());

var me = c.defaultApi().apiV1MeGet();
System.out.println(me.getUserId() + " " + me.getAvailableEurCents());

When Options.token() is not set, Client reads SYBILION_API_TOKEN from the environment. Options also accepts baseUrl (alias apiUrl) to override the default API origin.

Options fields

Field	Default	Notes
token(String)	""	Bearer token. When empty, SYBILION_API_TOKEN env var is used. Alias: apiKey.
baseUrl(String)	resolved at runtime	API origin without trailing slash. Alias: apiUrl. See resolution below.
readTimeout(Duration)	60s	Socket read timeout for all requests.
connectTimeout(Duration)	10s	TCP connection timeout.
httpClient(HttpClient)	default JDK client	Inject your own for custom transports, retries, or proxies.

Base URL resolution

Options.baseUrl(...) resolves the API origin in this order:

1. Non-empty Options.baseUrl(...).
2. SYBILION_API_BASE_URL environment variable.
3. The compiled-in default (https://api.sybilion.dev).

Wrapper methods

Client exposes a method for every endpoint:

Method	Endpoint
c.defaultApi().apiV1MeGet()	GET /api/v1/me
c.defaultApi().apiV1ForecastsPost(req)	POST /api/v1/forecasts
c.defaultApi().apiV1ForecastsIdGet(id)	GET /api/v1/forecasts/{id}
c.forecasts().waitUntilSettled(id, poll, timeout)	polling helper
c.forecasts().downloadArtifact(id, name)	GET /api/v1/forecasts/{id}/artifacts/{name} (returns byte[])
c.forecasts().downloadArtifactToFile(id, name, path)	download to Path
c.defaultApi().apiV1DriversPost(req)	POST /api/v1/drivers
c.defaultApi().apiV1AlertsPost(req)	POST /api/v1/alerts
c.forEachJobsPage(sort, order, limit, status, pipelineType, fn)	pagination helper
c.forEachUsagePage(sort, order, limit, fn)	pagination helper
c.defaultApi().apiV1CategoriesGet()	GET /api/v1/categories
c.defaultApi().apiV1RegionsGet()	GET /api/v1/regions

For endpoints not yet wrapped, c.defaultApi() returns the DefaultApi instance from the generated package.

waitUntilSettled — poll until settled

import com.fasterxml.jackson.databind.ObjectMapper;
import com.sybilion.Client;
import com.sybilion.Options;
import com.sybilion.generated.model.ForecastRequestV1;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.Duration;

Client c = new Client(Options.builder().token(System.getenv("SYBILION_API_TOKEN")).build());

ObjectMapper om = new ObjectMapper().findAndRegisterModules();
ForecastRequestV1 req = om.readValue(
    Files.readString(Path.of("forecast_body.json")),
    ForecastRequestV1.class);

var started = c.defaultApi().apiV1ForecastsPost(req);

var job = c.forecasts().waitUntilSettled(
    started.getJobId().toString(),
    Duration.ofSeconds(2),    // poll interval
    Duration.ofHours(1)       // max total wait
);

System.out.println("status: " + job.getStatus() + " cost (cents): " + job.getEurCentsFinal());
for (var a : job.getArtifacts()) {
    System.out.println(" - " + a.getName() + " " + a.getSize() + " bytes");
}

Behaviour:

• Polls GET /api/v1/forecasts/{id} every poll interval.
• Returns the response as soon as settled == true — works for completed, failed, and canceled jobs.
• Throws RuntimeException if the timeout is exceeded; the job continues on the server and you can resume polling later.

Download artifacts

import java.nio.file.Path;

var a = job.getArtifacts().get(0);
c.forecasts().downloadArtifactToFile(
    job.getJobId().toString(),
    a.getName(),
    Path.of("out").resolve(a.getName()));

downloadArtifact(id, name) returns byte[] if you prefer to handle bytes directly.

Pagination callbacks

forEachUsagePage and forEachJobsPage walk paginated endpoints page-by-page. The callback returns true to continue or false to stop early.

// Walk all usage events.
c.forEachUsagePage("created_at", "desc", 50, page -> {
    for (var ev : page.getUsageEvents()) {
        System.out.println(ev.getId() + " " + ev.getEurCentsCharged());
    }
    return true; // continue to the next page
});

// Walk completed jobs only.
c.forEachJobsPage("created_at", "desc", 50, "completed", null, page -> {
    for (var j : page.getJobs()) {
        System.out.println(j.getJobId() + " " + j.getStatus());
    }
    return true;
});

Iteration stops automatically when the last page is reached, or when the callback returns false.

Error handling

Wrapper methods throw RuntimeException (wrapping an HTTP error) when the response is non-2xx. Inspect the message for the API error field.

try {
    var me = c.defaultApi().apiV1MeGet();
} catch (RuntimeException e) {
    System.err.println("error: " + e.getMessage());
}

Custom configuration

Inject a custom HttpClient or adjust timeouts via Options.builder():

import java.net.http.HttpClient;
import java.time.Duration;

HttpClient customHttp = HttpClient.newBuilder()
    .connectTimeout(Duration.ofSeconds(5))
    .build();

Client c = new Client(Options.builder()
    .token(System.getenv("SYBILION_API_TOKEN"))
    .httpClient(customHttp)
    .readTimeout(Duration.ofSeconds(30))
    .build());

Versioning

The SDK uses SemVer independently of the API server version; minor releases stay backward-compatible, breaking changes bump the major. Pin a version in your POM or build file for production builds.

See also

• Features — full use-case walkthroughs with Java tabs.
• Alerts · Drivers — synchronous endpoints.
• Using curl · Python SDK · Go SDK · R SDK.
• Package page: dev.sybilion:sybilion on Maven Central.