Sybilion · OpenAPI Overlay 1.0.0
API Evangelist enhancements for the Sybilion Operational API
15 actions
15 updates
documentation
extends
openapi/sybilion-operational-api-openapi.yml
Derived by API Evangelist
Built from the contracts Sybilion publishes. Sybilion did not publish this file.
What the actions change
operationIdtagsx-mcp-toolx-apievangelist-notex-idempotency-headerx-apievangelist-enrichedx-apievangelist-artifactsx-contract-gaps
Targets 15
$.info
$.servers
$.tags
$.paths['/api/v1/forecasts'].post
$.paths['/api/v1/forecasts/{id}'].get
$.paths['/api/v1/forecasts/{id}/artifacts/{name}'].get
$.paths['/api/v1/drivers'].post
$.paths['/api/v1/alerts'].post
$.paths['/api/v1/jobs'].get
$.paths['/api/v1/me'].get
$.paths['/api/v1/usage'].get
$.paths['/api/v1/regions'].get
$.paths['/api/v1/categories'].get
$.paths['/health'].get
$.components.securitySchemes.bearerAuth
OpenAPI Overlay
overlay: 1.0.0
info:
title: API Evangelist enhancements for the Sybilion Operational API
version: 1.0.0
extends: openapi/sybilion-operational-api-openapi.yml
x-provenance:
generated: '2026-08-11'
method: generated
source: openapi/sybilion-operational-api-openapi.yml
note: >-
The harvested spec is verbatim from https://api.sybilion.dev/openapi.yaml and is never mutated.
Every change below is an API Evangelist enhancement. Two content gaps dominate: NOT ONE of the
11 operations declares an operationId, and NOT ONE declares a tag. That makes generated clients
fall back to method+path naming (visible in the provider's own Go and Java SDK examples —
`ApiV1MeGet`, `apiV1RegionsGet`), makes every reference renderer emit a single flat list, and
leaves the tool crosswalk with nothing to bind to. The operationIds proposed here are
RECOMMENDATIONS derived from the SDK method names Sybilion already ships (client.list_regions,
c.ListCategories, waitForecast) — they are not present upstream and must not be treated as the
provider's contract. The spec also declares servers[] as a bare relative "/", so no absolute
host is machine-readable from the spec at all; the real base is documented in prose only.
actions:
- target: $.info
update:
x-apievangelist-enriched: '2026-08-11'
x-apievangelist-artifacts:
conventions: conventions/sybilion-conventions.yml
errors: errors/sybilion-problem-types.yml
authentication: authentication/sybilion-authentication.yml
rate_limits: rate-limits/sybilion-rate-limits.yml
lifecycle: lifecycle/sybilion-lifecycle.yml
data_model: data-model/sybilion-data-model.yml
mcp: mcp/sybilion-mcp.yml
crosswalk: mcp/sybilion-tool-crosswalk.yml
x-contract-gaps:
- operationIds absent on all 11 operations
- tags absent on all 11 operations and no top-level tags[] declared
- servers[] is the relative "/" — the production host is prose-only
- securityScheme bearerAuth has no description and no bearerFormat
- no 429 response documented on POST /api/v1/alerts response headers, and no rate-limit headers anywhere
- error responses declare no schema on 400/401/402/404/409/413/429/502
- target: $.servers
update:
- url: https://api.sybilion.dev
description: >-
Production. Documented in prose at https://sybilion.dev/docs/quickstart ("The base URL is
https://api.sybilion.dev") and overridable per process with SYBILION_API_BASE_URL. Added
here because the upstream spec ships servers[0].url = "/".
- target: $.tags
update:
- name: forecasts
description: Asynchronous monthly time-series forecasting with quantile bands and driver attribution.
- name: drivers
description: Synchronous ranking of external driver datasets against a caller's series.
- name: alerts
description: Synchronous detection of macroeconomic movements relevant to a caller's context.
- name: jobs
description: Async job listing and status.
- name: catalog
description: Read-only region and category catalogs used by filters.
- name: account
description: Account snapshot, balance, credit tranches and billing history.
- name: operations
description: Unauthenticated service health.
- target: $.paths['/api/v1/forecasts'].post
update:
operationId: submitForecast
tags: [forecasts]
x-apievangelist-note: >-
Not idempotent. X-Request-ID is documented only for the synchronous billed calls; a retried
submit creates a second job and a second balance hold.
x-mcp-tool: submit_forecast
- target: $.paths['/api/v1/forecasts/{id}'].get
update:
operationId: getForecast
tags: [forecasts]
x-mcp-tool: get_forecast
- target: $.paths['/api/v1/forecasts/{id}/artifacts/{name}'].get
update:
operationId: getForecastArtifact
tags: [forecasts]
x-mcp-tool: [get_forecast_artifact, get_forecast_chart]
x-apievangelist-note: >-
Backs two MCP tools. get_forecast_chart takes only {job_id}, so the MCP server selects the
chart artifact name server-side — a capability with no REST equivalent.
- target: $.paths['/api/v1/drivers'].post
update:
operationId: rankDrivers
tags: [drivers]
x-idempotency-header: X-Request-ID
x-apievangelist-note: >-
Synchronous and billed. No MCP tool exposes this — the single largest REST/MCP divergence in
the contract.
- target: $.paths['/api/v1/alerts'].post
update:
operationId: detectAlerts
tags: [alerts]
x-idempotency-header: X-Request-ID
x-mcp-tool: get_alerts
- target: $.paths['/api/v1/jobs'].get
update:
operationId: listJobs
tags: [jobs]
- target: $.paths['/api/v1/me'].get
update:
operationId: getAccount
tags: [account]
- target: $.paths['/api/v1/usage'].get
update:
operationId: listUsage
tags: [account]
- target: $.paths['/api/v1/regions'].get
update:
operationId: listRegions
tags: [catalog]
x-mcp-tool: list_regions
- target: $.paths['/api/v1/categories'].get
update:
operationId: listCategories
tags: [catalog]
x-mcp-tool: list_categories
- target: $.paths['/health'].get
update:
operationId: getHealth
tags: [operations]
x-apievangelist-note: Only unauthenticated operation; sits outside the /api/v1 version prefix.
- target: $.components.securitySchemes.bearerAuth
update:
description: >-
Accepts either an sk_ops_ API key created in the Developers Portal or an Auth0 access token
from a dashboard session. Keys are opaque, unscoped and shown once at creation. See
https://sybilion.dev/docs/authentication.
x-credential-prefixes: ['sk_ops_']
x-env-var: SYBILION_API_TOKEN
Work with this as data
Every overlay here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for openapi overlays
4 MCP tools reach this
find_overlaysBrowse and filter every overlay in the catalog.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This overlay
curl "https://apis.io/api/v1/overlays/sybilion-operational-api-overlay"
All openapi overlays
curl "https://apis.io/api/v1/overlays?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.