R SDK

The official R SDK is published as sybilion on CRAN. It ships two layers in one package:

sybilion — the hand-written wrapper exposed to users (sybilion_client, ergonomic methods, pagination iterators).
cl$raw — the OpenAPI-generated DefaultApi. Accessible as cl$raw as an escape hatch for direct endpoint calls.

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 an R tab.

Install

install.packages("sybilion")

Requires R 4.0+. Dependencies (jsonlite, httr, R6, base64enc, stringr) are installed automatically from CRAN.

Construct a client

library(sybilion)

# Token read from the environment automatically:
cl <- sybilion_client()

# Or pass it explicitly:
cl <- sybilion_client(token = Sys.getenv("SYBILION_API_TOKEN"))

me <- cl$raw$ApiV1MeGet()$content
cat(me$user_id, me$available_eur_cents, "\n")

When token is omitted, sybilion_client reads SYBILION_API_TOKEN from the environment. It also accepts an optional base_url (alias api_url) to override the default API origin.

Base URL resolution

sybilion_client(base_url = ...) resolves the API origin in this order:

Explicit base_url argument.
SYBILION_API_BASE_URL environment variable.
The compiled-in default (https://api.sybilion.dev).

Wrapper methods

Client exposes a method for every endpoint:

Method	Endpoint
`cl$raw$ApiV1MeGet()`	`GET /api/v1/me`
`cl$raw$ApiV1ForecastsPost(req)`	`POST /api/v1/forecasts`
`cl$raw$ApiV1ForecastsIdGet(id)`	`GET /api/v1/forecasts/{id}`
`cl$raw$ApiV1ForecastsIdArtifactsNameGet(id, name, data_file)`	`GET /api/v1/forecasts/{id}/artifacts/{name}`
`cl$wait_forecast(job_id, poll_s, timeout_s)`	polling helper
`cl$recommend_drivers(req)`	`POST /api/v1/drivers`
`cl$raw$ApiV1AlertsPost(req)`	`POST /api/v1/alerts`
`cl$list_jobs(page, limit, ...)`	`GET /api/v1/jobs` (single page)
`cl$iter_jobs_pages(callback, ...)`	pagination helper
`cl$list_usage(page, limit, ...)`	`GET /api/v1/usage` (single page)
`cl$iter_usage_pages(callback, ...)`	pagination helper
`cl$raw$ApiV1CategoriesGet()`	`GET /api/v1/categories`
`cl$raw$ApiV1RegionsGet()`	`GET /api/v1/regions`

cl$raw is an R6 DefaultApi instance generated from the OpenAPI spec. Method names mirror the operationId: ApiV1MeGet, ApiV1ForecastsPost, etc. Each cl$raw$…() call returns a list with $status, $content, and $headers.

`wait_forecast` — poll until settled

library(jsonlite)
library(sybilion)

cl <- sybilion_client(token = Sys.getenv("SYBILION_API_TOKEN"))

payload <- jsonlite::fromJSON("forecast_body.json")

req <- ForecastRequestV1$new(
  frequency           = payload$frequency,
  pipeline_version    = payload$pipeline_version,
  recency_factor      = payload$recency_factor,
  timeseries          = payload$timeseries,
  timeseries_metadata = TimeseriesMetadata$new(
    title       = payload$timeseries_metadata$title,
    description = payload$timeseries_metadata$description,
    keywords    = payload$timeseries_metadata$keywords
  ),
  backtest     = payload$backtest,
  soft_horizon = payload$soft_horizon
)

started <- cl$raw$ApiV1ForecastsPost(req)

job <- cl$wait_forecast(
  started$job_id,
  poll_s    = 2.0,       # seconds between polls
  timeout_s = 3600.0     # max total wait
)

cat("status:", job$status, "cost (cents):", job$eur_cents_final, "\n")
for (a in job$artifacts) cat(" -", a$name, a$size, "bytes\n")

Behaviour:

Polls GET /api/v1/forecasts/{id} every poll_s seconds.
Returns the response as soon as settled == TRUE — works for completed, failed, and canceled jobs.
Stops and errors if timeout_s is exceeded; the job continues on the server and you can resume polling later.

Pick poll_s based on your latency tolerance — 2–5 seconds is typical.

Pagination iterators

Two helpers walk paginated endpoints page-by-page so you don't have to track page / total_pages yourself.

# All usage events.
cl$iter_usage_pages(function(page) {
  for (ev in page$usage_events) {
    cat(ev$id, ev$eur_cents_charged, ev$created_at, "\n")
  }
})

# Completed forecast jobs only.
cl$iter_jobs_pages(
  function(page) {
    for (j in page$jobs) cat(j$job_id, j$status, j$eur_cents_final, "\n")
  },
  status = "completed"
)

Each iterator stops automatically when all pages have been fetched. Stop early by returning FALSE from the callback.

Error handling

Wrapper methods raise an R error on non-2xx responses. The condition message includes the HTTP status and the error field from the API response body when available.

tryCatch(
  cl$raw$ApiV1ForecastsPost(req),
  error = function(e) message("error: ", conditionMessage(e))
)

Versioning

The SDK uses SemVer independently of the API server version; minor releases stay backward-compatible, breaking changes bump the major. Pin a version with renv or pak for production builds.

R SDK ​

Install ​

Construct a client ​

Base URL resolution ​

Wrapper methods ​

wait_forecast — poll until settled ​

Pagination iterators ​

Error handling ​

Versioning ​

See also ​