# Sybilion

> Sybilion is a decision layer for industrial companies: economic and causal forecasting that connects
> external market dynamics to internal exposure for procurement, trading and risk teams. It forecasts
> monthly business time series up to 12 months ahead with 80%/90% quantile bands, ranks the external
> macroeconomic drivers that move a series (with Granger lag relationships), and raises alerts on what
> is moving against a caller's context right now. Reachable as a bearer-key REST API at
> api.sybilion.dev and as a hosted OAuth MCP server at mcp.sybilion.dev.

Generated by API Evangelist from harvested artifacts. Sybilion publishes no llms.txt of its own
(https://sybilion.dev/docs/llms.txt returns the VitePress docs shell, not a document).

## Contract at a glance

- Base URL: https://api.sybilion.dev — all resources under /api/v1, plus an unauthenticated /health
- Spec: OpenAPI 3.0.3, 11 operations, 22 schemas, served anonymously at https://api.sybilion.dev/openapi.yaml
- Auth (REST): `Authorization: Bearer sk_ops_…` — API key from the Developers Portal, or an Auth0 session token
- Auth (MCP): OAuth 2.1 authorization_code + PKCE, browser approval, no key to paste
- Errors: proprietary `{"error": "...", "trace_id": "..."}`; 422 uses `{"error":"validation_failed","details":[{field,message}]}`
- Idempotency: `X-Request-ID` on POST /api/v1/drivers and POST /api/v1/alerts — deduplicates BILLING on retry
- Tracing: every response carries `x-trace-id`; the same value appears as `trace_id` in error bodies
- Pagination: page/limit/sort/order with a `pagination` envelope (page, limit, total, total_pages, sort, order)
- Rate limits: three tier-dependent caps (per-minute general, per-minute sync-billed, concurrent jobs). No values are published and there are NO rate-limit response headers and no Retry-After
- Billing: prepaid EUR-cent balance, expiring credit tranches, holds taken before a forecast runs
- No OpenAPI operationIds, no tags, no webhooks, no GraphQL, no AsyncAPI

## Operations

- POST /api/v1/forecasts — submit an async forecast job; returns 202 + job_id
- GET /api/v1/forecasts/{id} — poll job status and list artifacts
- GET /api/v1/forecasts/{id}/artifacts/{name} — download an output file (Range/206 supported)
- POST /api/v1/drivers — rank external driver datasets for a series (synchronous, billed)
- POST /api/v1/alerts — detect anomaly alerts for a series (synchronous, billed)
- GET /api/v1/jobs — paginated list of async jobs
- GET /api/v1/me — account snapshot: balance, tier, credit tranches
- GET /api/v1/usage — paginated billing history
- GET /api/v1/regions — region catalog for filters.regions[]
- GET /api/v1/categories — category catalog for filters.categories[]
- GET /health — unauthenticated component health probe

## MCP tools

Server: https://mcp.sybilion.dev/mcp (Streamable HTTP, OAuth). tools/list is auth-gated (401
anonymously), so these names come from the provider's own docs and MCP page, not from introspection.

- submit_forecast — submit a monthly series for an async forecast
- get_forecast — poll until the job settles; args {job_id}
- get_forecast_chart — retrieve the rendered chart; args {job_id}
- get_forecast_artifact — retrieve a named output file; args {job_id, artifact_name}
- get_alerts — what is moving against your context right now
- list_regions / list_categories — catalog discovery
- (an unnamed account tool exists — the ChatGPT setup notes mention account tools)

Notable divergence: POST /api/v1/drivers has NO MCP tool. On the agent surface, driver attribution is
only available as a by-product of a forecast (external_signals.json via get_forecast_artifact).

## Docs

- Documentation: https://sybilion.dev/docs/
- Quickstart: https://sybilion.dev/docs/quickstart
- Authentication: https://sybilion.dev/docs/authentication
- Errors & limits: https://sybilion.dev/docs/errors
- Tiers: https://sybilion.dev/docs/tiers
- MCP integrations (ChatGPT, Claude, TradingView Remix): https://sybilion.dev/docs/integrations
- Clients: https://sybilion.dev/docs/sdks/
- Public OpenAPI: https://sybilion.dev/docs/openapi
- Community (Slack, Discord, email): https://sybilion.dev/docs/community
- Developers Portal / sign up: https://sybilion.dev/signup
- Company site: https://www.sybilion.com/
- Privacy policy: https://www.sybilion.com/legal/privacy-policy

## SDKs

- Python — `pip install sybilion` — https://pypi.org/project/sybilion/ (0.2.1, 2026-07-16)
- Go — `go get go.sybilion.dev/sybilion@latest` — https://pkg.go.dev/go.sybilion.dev/sybilion (v0.2.1, 2026-07-16)
- TypeScript — `npm install @sybilion/sdk` — https://www.npmjs.com/package/@sybilion/sdk (0.2.0, 2026-07-16)
- R — `install.packages("sybilion")` — https://cran.r-project.org/package=sybilion (0.1.0, 2026-07-17)
- Java — documented as `dev.sybilion:sybilion` on Maven Central but NOT PUBLISHED (repo1.maven.org
  returns 404 for the coordinate as of 2026-08-11). Do not tell a user to add that dependency.

## Constraints an agent should know before calling

- Monthly frequency only. Sub-monthly is roadmap, not shipped.
- 40 to 120 observations required depending on horizon; horizons 1-12 months.
- Every timeseries key must be the FIRST day of the month (2024-06-01, not 2024-06-15).
- The most recent data point cannot be older than 12 months.
- Forecasts are async and take tens of seconds to a few minutes. Downloading an artifact before the
  job completes returns 409.
- Results age out of a "post-settlement visibility window" and then return 404. The window length is
  not published.
- 402 means insufficient AVAILABLE balance (balance minus holds), even though some bodies say "credits".
- Region and category ids are validated only as integers 1-9999 — a wrong id fails silently.

## Artifacts (API Evangelist)

- OpenAPI: openapi/sybilion-operational-api-openapi.yml
- Authentication: authentication/sybilion-authentication.yml
- OAuth scopes (MCP): scopes/sybilion-scopes.yml
- Conventions: conventions/sybilion-conventions.yml
- Errors: errors/sybilion-problem-types.yml
- Lifecycle: lifecycle/sybilion-lifecycle.yml
- Rate limits: rate-limits/sybilion-rate-limits.yml
- Plans: plans/sybilion-plans-pricing.yml
- Packages: packages/sybilion-packages.yml
- MCP: mcp/sybilion-mcp.yml
- Tool crosswalk: mcp/sybilion-tool-crosswalk.yml
- Data model: data-model/sybilion-data-model.yml
- Conformance: conformance/sybilion-conformance.yml
- Well-known: well-known/sybilion-well-known.yml
- Agent skills: skills/_index.yml