sybilion

README

Sybilion Go SDK

Official Go client for the Sybilion API.

go get go.sybilion.dev/sybilion@latest

Requires Go 1.25+.

Quick use

package main

import (
	"context"
	"fmt"
	"log"
	"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 {
		log.Fatal(err)
	}
	fmt.Println(me.GetUserId(), me.GetAvailableEurCents(), me.GetApiUsageTier())
}

The token is an API key (sk_ops_...) created in the Developers Portal, or a dashboard session token. The default base URL is https://api.sybilion.dev; override per-process with SYBILION_API_BASE_URL or per-call via Options.BaseURL.

What's in the box

• sybilion.Client — Bearer auth, ergonomic helpers.
• c.Forecasts().Wait(ctx, jobID, poll) — polls GET /api/v1/forecasts/{id} until settled.
• sybilion.ForEachUsagePage / ForEachJobsPage — paginated iterators.
• c.DefaultAPI() — escape hatch to the OpenAPI-generated client at go.sybilion.dev/sybilion/api.
• sybilion.AsGenericOpenAPIError(err) — typed error unwrap.

Documentation

Full guides, feature walkthroughs, API reference, and SDK patterns: https://sybilion.dev/docs/.

For LLM / codegen contexts the single-file cheat sheet lives at LLM_SDK_GUIDE.md.

Support

• Email — support@sybilion.com
• Slack — Sybilion Community
• Discord — Sybilion Developers Community

License

Apache 2.0.

Documentation

Overview

Package sybilion is the official Go client for the Sybilion API.

The hand-written wrapper provides ergonomic helpers (Bearer auth, forecast polling, pagination iterators) on top of the OpenAPI-generated client at go.sybilion.dev/sybilion/api. Most users only need:

c := sybilion.New(sybilion.Options{Token: os.Getenv("SYBILION_API_TOKEN")})
me, _, err := c.DefaultAPI().ApiV1MeGet(ctx).Execute()

See https://sybilion.dev/docs/ for full guides and feature walkthroughs.

Index

• Constants
• func AsGenericOpenAPIError(err error) (*api.GenericOpenAPIError, bool)
• func ForEachJobsPage(ctx context.Context, defaultAPI *api.DefaultAPIService, sort string, ...) error
• func ForEachUsagePage(ctx context.Context, defaultAPI *api.DefaultAPIService, sort string, ...) error
• func WaitForecast(ctx context.Context, defaultAPI *api.DefaultAPIService, jobID string, ...) (*api.ApiV1ForecastsIdGet200Response, error)
• type APIError
  • func (e *APIError) Error() string
• type Client
  • func New(opts Options) *Client
  • func (c *Client) DefaultAPI() *api.DefaultAPIService
  • func (c *Client) Forecasts() *Forecasts
  • func (c *Client) Raw() *api.APIClient
• type Forecasts
  • func (f *Forecasts) Wait(ctx context.Context, jobID string, poll time.Duration) (*api.ApiV1ForecastsIdGet200Response, error)
• type JobsPageFunc
• type Options
• type UsagePageFunc

Constants

const (
	// DefaultPublicAPIBaseURL is the production Sybilion API origin (no trailing slash).
	DefaultPublicAPIBaseURL = "https://api.sybilion.dev"
)

const EnvOperationalAPIBaseURL = "OPERATIONAL_API_BASE_URL"

EnvOperationalAPIBaseURL is the previous (pre-launch) name of the env var; kept as a silent fallback for one transition release. New code should set SYBILION_API_BASE_URL.

const EnvSybilionAPIBaseURL = "SYBILION_API_BASE_URL"

EnvSybilionAPIBaseURL is the canonical environment variable that overrides the compiled-in default API origin when Options.BaseURL is empty.

Functions

func AsGenericOpenAPIError

func AsGenericOpenAPIError(err error) (*api.GenericOpenAPIError, bool)

AsGenericOpenAPIError unwraps openapi-generator's GenericOpenAPIError when possible.

func ForEachJobsPage

func ForEachJobsPage(ctx context.Context, defaultAPI *api.DefaultAPIService, sort string, order string, limit int32, fn JobsPageFunc) error

ForEachJobsPage walks job pages from page 1 until the callback returns false or pages are exhausted.

func ForEachUsagePage

func ForEachUsagePage(ctx context.Context, defaultAPI *api.DefaultAPIService, sort string, order string, limit int32, fn UsagePageFunc) error

ForEachUsagePage walks usage from page 1 until the callback returns false or pages are exhausted.

func WaitForecast

func WaitForecast(ctx context.Context, defaultAPI *api.DefaultAPIService, jobID string, poll time.Duration) (*api.ApiV1ForecastsIdGet200Response, error)

WaitForecast polls GET /api/v1/forecasts/{id} until the job is settled or the context is done.

Types

type APIError

type APIError struct {
	StatusCode int
	Body       []byte
	Message    string
}

APIError wraps a non-2xx API response when the body could not be decoded into a typed model.

func (*APIError) Error

func (e *APIError) Error() string

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a thin wrapper around the openapi-generator DefaultAPI client.

func New

func New(opts Options) *Client

New constructs a Client. Token is required for authenticated calls. Base URL resolution: Options.BaseURL, else SYBILION_API_BASE_URL, else DefaultPublicAPIBaseURL.

func (*Client) DefaultAPI

func (c *Client) DefaultAPI() *api.DefaultAPIService

DefaultAPI returns the DefaultAPIService (all REST operations).

func (*Client) Forecasts

func (c *Client) Forecasts() *Forecasts

Forecasts returns forecast helpers including Wait.

func (*Client) Raw

func (c *Client) Raw() *api.APIClient

Raw exposes the underlying openapi-generated API client.

type Forecasts

type Forecasts struct {
	// contains filtered or unexported fields
}

Forecasts groups forecast-related helpers.

func (*Forecasts) Wait

func (f *Forecasts) Wait(ctx context.Context, jobID string, poll time.Duration) (*api.ApiV1ForecastsIdGet200Response, error)

Wait polls GET /api/v1/forecasts/{id} until settled or context cancellation.

type JobsPageFunc

type JobsPageFunc func(ctx context.Context, page *api.ApiV1JobsGet200Response) (continueNext bool, err error)

JobsPageFunc is called for each page of GET /api/v1/jobs.

type Options

type Options struct {
	// BaseURL is the API origin, e.g. https://api.example.com (no trailing slash required).
	// Empty BaseURL uses SYBILION_API_BASE_URL (if set), else DefaultPublicAPIBaseURL (defaults_gen.go).
	BaseURL string
	// Token is sent as Authorization: Bearer <token> (an API key sk_ops_... or a dashboard session token).
	Token string
	// HTTPClient overrides the default net/http client (timeouts, transport, etc.).
	HTTPClient *http.Client
	// UserAgent overrides the default User-Agent header.
	UserAgent string
}

Options configures the HTTP client and authentication.

type UsagePageFunc

type UsagePageFunc func(ctx context.Context, page *api.ApiV1UsageGet200Response) (continueNext bool, err error)

UsagePageFunc is called for each page of GET /api/v1/usage. Return false to stop iteration.