Quickstart

This page takes you from zero to a completed forecast job using the Sybilion API. You need a Sybilion account and a Bearer token (an API key or a dashboard session token).

1. Sign in and create an API key

1. Open the Developers Portal and sign in.
2. Go to API keys and create a key. Copy the full secret once (it starts with sk_ops_…).
   Keys are only created in the portal — they are not exposed in the public API reference or SDKs.

Export it in your shell (examples below use $SYBILION_API_TOKEN).

2. Pick a client: curl, Python, or Go

The base URL is https://api.sybilion.dev. The examples below assume your token is in SYBILION_API_TOKEN.

curl

export SYBILION_API_TOKEN="sk_ops_..."  # your key

Python

pip install sybilion
export SYBILION_API_TOKEN="sk_ops_..."  # your key

Go

go get go.sybilion.dev/sybilion@latest
export SYBILION_API_TOKEN="sk_ops_..."  # your key

Official SDK packages: Python — sybilion on PyPI · Go — go.sybilion.dev/sybilion on pkg.go.dev.

3. Verify authentication — GET /api/v1/me

curl

curl -sS -H "Authorization: Bearer $SYBILION_API_TOKEN" \
  https://api.sybilion.dev/api/v1/me | jq

Python

import os

from sybilion import Client

c = Client(token=os.environ["SYBILION_API_TOKEN"])
me = c.raw.api_v1_me_get()
print(me.user_id, me.available_eur_cents)

Go

package main

import (
  "context"
  "fmt"
  "os"

  "go.sybilion.dev/sybilion"
)

func main() {
  c := sybilion.New(sybilion.Options{Token: os.Getenv("SYBILION_API_TOKEN")})
  me, _, err := c.DefaultAPI().ApiV1MeGet(context.Background()).Execute()
  if err != nil { panic(err) }
  fmt.Println(me.GetUserId(), me.GetAvailableEurCents())
}

You should see user_id, available_eur_cents, and api_usage_tier. See GET /api/v1/me for field meanings.

4. Submit a forecast — POST /api/v1/forecasts

The request body must satisfy the pipeline v1 rules. A minimal valid body looks like this — save it as forecast_body.json (replace the timeseries map with at least 24 monthly points of your own data):

{
  "pipeline_version": "v1",
  "horizon": 12,
  "frequency": "monthly",
  "backtest": true,
  "recency_factor": 0.5,
  "strictly_positive": false,
  "timeseries_metadata": {
    "title": "Aluminum price in Europe USD/KG",
    "description": "Spot price of primary aluminum in the European market.",
    "keywords": ["aluminum", "metals", "commodities"]
  },
  "filters": { "categories": [101], "regions": [42] },
  "timeseries": {
    "2023-01-01": 2.488709712,
    "2023-02-01": 2.418378367,
    "2023-03-01": 2.303802561
  }
}

Then:

curl

curl -sS -X POST https://api.sybilion.dev/api/v1/forecasts \
  -H "Authorization: Bearer $SYBILION_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @forecast_body.json | jq

Python

import json
import os

from sybilion import Client

c = Client(token=os.environ["SYBILION_API_TOKEN"])
with open("forecast_body.json", encoding="utf-8") as f:
    body = json.load(f)
resp = c.raw.api_v1_forecasts_post(forecast_request_v1=body)
print(resp.job_id, resp.poll_url)

Go

// Pattern: c.DefaultAPI().ApiV1ForecastsPost(ctx).ForecastRequestV1(body).Execute()
// Full walkthrough: https://sybilion.dev/docs/features/forecasts

A successful response is 202 Accepted with job_id (UUID) and poll_url.

5. Poll until settled, then fetch artifacts

Poll GET /api/v1/forecasts/{id} until settled is true, then download bytes from GET /api/v1/forecasts/{id}/artifacts/{name} using the name values from the artifacts array. See Status and Artifacts.

curl

JOB_ID="<paste job_id>"
API="https://api.sybilion.dev"
until curl -sS -H "Authorization: Bearer $SYBILION_API_TOKEN" "$API/api/v1/forecasts/$JOB_ID" | jq -e '.settled == true' >/dev/null; do sleep 2; done
curl -sS -H "Authorization: Bearer $SYBILION_API_TOKEN" "$API/api/v1/forecasts/$JOB_ID" | jq '.artifacts'

Python

import os

from sybilion import Client

c = Client(token=os.environ["SYBILION_API_TOKEN"])
job = c.wait_forecast("<job-uuid>", poll_s=2.0, timeout_s=600)
print(job.status, job.artifacts)

Go

// c.Forecasts().Wait(ctx, jobID, 2*time.Second)

Non-default API origin

If you need to point at a non-production host, set SYBILION_API_BASE_URL=https://your-host and the SDKs will pick it up automatically; for curl, just substitute the URL.

Top up balance

Credit top-ups and saved payment methods are handled in the Developers Portal (Billing) — not via the integrator-facing API surface documented here.

Next steps

• Authentication — API keys vs dashboard session tokens.
• Tiers & signup trial — rate limits and concurrent jobs.
• Features — full walkthroughs with curl, Python and Go side-by-side: Forecasts · Drivers · Regions & categories · Account & usage.
• Clients — language-specific patterns: Using curl · Python SDK · Go SDK.
• Errors & limits — 402, 429, and validation 422.
• Community & support — Slack, Discord, email.