components:
schemas:
AlertItemV1:
description: A single alert returned by the upstream Recommend service.
example:
trending: true
name: "OMX Copenhagen Oil, Gas and Coal Price Index"
pct_change: -7.14
news:
- trending: true
title: "US-Iran agreed on principal deal to open Strait of Hormuz"
description: "The US and Iran have reportedly reached a preliminary understanding to reopen the Strait of Hormuz."
url: "https://www.thenews.com.pk/latest/1403722"
published_at: "2026-05-24T21:28:00Z"
source_name: "The News International"
category: "world"
properties:
name:
description: Human-readable name of the dataset or index that triggered the alert.
type: string
news:
description: Related news articles driving this alert.
items:
$ref: '#/components/schemas/NewsItemV1'
type: array
pct_change:
description: Percentage change that triggered the alert (negative = decline, positive = surge).
format: double
type: number
trending:
description: Whether this alert is currently trending across the platform.
type: boolean
type: object
AlertsRequestV1:
description: |
Body of `POST /api/v1/alerts`.
`filters.limit` controls how many alerts are returned (default **100**, max **1000**).
`date_from` / `date_to` are optional date bounds (YYYY-MM-DD).
example:
context_enriched: true
date_from: "2024-01-01"
date_to: "2026-05-26"
filters:
categories: [3, 7]
regions: [42]
limit: 10
metadata:
description: "Monthly average Brent crude oil spot price in USD/barrel, sourced from EIA."
keywords: ["oil", "brent", "energy", "commodity", "barrel"]
title: "Brent Crude Oil Price Monthly"
properties:
context_enriched:
description: When true, treat the supplied metadata as already context-enriched.
type: boolean
date_from:
description: Optional start date bound for alert detection (YYYY-MM-DD).
type: string
date_to:
description: Optional end date bound for alert detection (YYYY-MM-DD).
type: string
filters:
allOf:
- $ref: '#/components/schemas/Filters'
description: |
Optional. `limit` controls the number of alerts returned (**0–1000**, default **100**).
`categories[]` and `regions[]` narrow the alert universe; each must be an integer **1–9999**.
Values are not verified against catalog APIs.
metadata:
$ref: '#/components/schemas/TimeseriesMetadata'
required:
- metadata
- context_enriched
type: object
AutoRechargeState:
example:
enabled: true
below_eur_cents: 500
target_eur_cents: 5000
monthly_cap_cents: 20000
meter_cents: 3500
has_stripe_customer: true
properties:
below_eur_cents:
description: When the available balance drops below this many EUR cents, a recharge is triggered.
format: int64
type: integer
enabled:
description: Whether auto-recharge is active for this account.
type: boolean
has_stripe_customer:
description: Whether a Stripe customer record exists (required for auto-recharge to run).
type: boolean
meter_cents:
description: EUR cents charged via auto-recharge in the current UTC calendar month.
format: int64
type: integer
meter_month:
description: UTC month start for `meter_cents`; null if no auto-recharge has run this month.
format: date
nullable: true
type: string
monthly_cap_cents:
description: Maximum EUR cents that may be charged via auto-recharge per UTC calendar month. 0 = no cap.
format: int64
type: integer
target_eur_cents:
description: Balance target after a successful recharge, in EUR cents.
format: int64
type: integer
required:
- enabled
- below_eur_cents
- target_eur_cents
- monthly_cap_cents
- meter_cents
- has_stripe_customer
type: object
DriverItemV1:
description: A ranked dataset candidate returned by `POST /api/v1/drivers`.
example:
hash_id: "d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9"
driver_name: "Natural Gas Futures Price (Henry Hub)"
score: 0.87
properties:
driver_name:
description: Human-readable name of the dataset.
type: string
hash_id:
description: Stable identifier for the dataset; use to reference this driver across requests.
type: string
score:
description: Relevance score indicating how well this dataset explains your timeseries (higher is more relevant).
format: double
type: number
type: object
EuroTranche:
description: |
A time-limited credit allocation. Multiple tranches can be active simultaneously;
the system consumes the one expiring soonest first.
example:
id: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
source: "stripe"
initial_eur_cents: 5000
remaining_eur_cents: 4750
created_at: "2026-05-01T09:00:00Z"
expires_at: "2027-05-01T09:00:00Z"
properties:
created_at:
format: date-time
type: string
expires_at:
format: date-time
type: string
id:
format: uuid
type: string
initial_eur_cents:
description: Original size of this tranche in EUR cents.
format: int64
type: integer
remaining_eur_cents:
description: Unconsumed balance remaining in this tranche, in EUR cents.
format: int64
type: integer
source:
description: Origin of the tranche — one of `signup_trial`, `stripe`, `partner`, `legacy`. Other labels may appear for custom grants.
type: string
required:
- id
- source
- initial_eur_cents
- remaining_eur_cents
- expires_at
- created_at
type: object
Filters:
description: |
Optional narrowing for forecast, drivers, and alerts requests.
Category and region ids must fall in **1–9999**. Discover valid ids via
`GET /api/v1/regions` and `GET /api/v1/categories` — submitted ids are not
cross-checked on submit.
example:
categories: [3, 7]
regions: [42, 88]
limit: 25
properties:
categories:
description: Thematic category ids to filter by; each must be an integer **1–9999** inclusive.
items:
maximum: 9999
minimum: 1
type: integer
type: array
general_drivers:
description: When true, general (non category/region-specific) drivers are included in the driver candidate pool. Defaults to false.
type: boolean
limit:
description: Maximum number of items to return. When omitted, a per-environment default is applied (100 by default). The maximum accepted value is operator-configurable (default 1000).
maximum: 1000
minimum: 0
type: integer
regions:
description: Geographic region ids to filter by; each must be an integer **1–9999** inclusive.
items:
maximum: 9999
minimum: 1
type: integer
type: array
type: object
ForecastArtifactMeta:
description: Metadata for a single output file produced by a completed forecast job.
example:
name: "forecast.json"
href: "/api/v1/forecasts/a1b2c3d4-e5f6-7890-abcd-ef1234567890/artifacts/forecast.json"
content_type: "application/json"
size: 4096
properties:
content_type:
description: MIME type of the artifact (e.g. `application/json`).
type: string
href:
description: Relative URL to stream via `GET /api/v1/forecasts/{id}/artifacts/{name}`.
type: string
name:
description: Artifact filename (e.g. `forecast.json`, `backtest_metrics.json`).
type: string
size:
description: File size in bytes.
format: int64
type: integer
type: object
ForecastRequestV1:
description: |
Body of `POST /api/v1/forecasts`. Submit a monthly timeseries and the pipeline
produces a forward forecast (and optionally a backtest). At least one of
`soft_horizon` or `hard_horizon` must be present.
The minimum number of monthly observations depends on the largest requested
horizon (`max(soft_horizon, hard_horizon)`): **40** points for horizons 1–3,
**60** for 4–6, and **120** for 7–12. Observations must be aligned to the first
of each month (YYYY-MM-01). `recency_factor` controls how strongly the
driver-selection step weights recent data.
example:
pipeline_version: "v1"
frequency: "monthly"
recency_factor: 0.6
soft_horizon: 6
hard_horizon: 3
backtest: true
timeseries_metadata:
title: "Brent Crude Oil Price Monthly"
description: "Monthly average Brent crude oil spot price in USD/barrel, sourced from EIA."
keywords: ["oil", "brent", "energy", "commodity"]
timeseries:
"2021-01-01": 57.64
"2021-02-01": 65.02
"2021-03-01": 67.24
"2021-04-01": 71.07
"2021-05-01": 70.25
"2021-06-01": 65.50
"2021-07-01": 64.25
"2021-08-01": 58.96
"2021-09-01": 62.01
"2021-10-01": 59.87
"2021-11-01": 63.43
"2021-12-01": 66.52
"2022-01-01": 63.65
"2022-02-01": 55.66
"2022-03-01": 33.73
"2022-04-01": 26.63
"2022-05-01": 29.85
"2022-06-01": 40.80
"2022-07-01": 43.51
"2022-08-01": 44.98
"2022-09-01": 42.96
"2022-10-01": 41.53
"2022-11-01": 43.72
"2022-12-01": 51.22
"2023-01-01": 55.30
"2023-02-01": 61.19
"2023-03-01": 65.36
"2023-04-01": 65.79
"2023-05-01": 67.77
"2023-06-01": 73.93
"2023-07-01": 75.53
"2023-08-01": 70.82
"2023-09-01": 73.54
"2023-10-01": 84.36
"2023-11-01": 82.60
"2023-12-01": 74.62
"2024-01-01": 83.39
"2024-02-01": 96.84
"2024-03-01": 117.25
"2024-04-01": 104.64
"2024-05-01": 113.03
"2024-06-01": 119.18
"2024-07-01": 105.58
"2024-08-01": 97.88
"2024-09-01": 91.68
"2024-10-01": 93.60
"2024-11-01": 93.47
"2024-12-01": 82.66
"2025-01-01": 81.14
"2025-02-01": 82.80
"2025-03-01": 77.91
"2025-04-01": 84.94
"2025-05-01": 75.52
"2025-06-01": 75.29
"2025-07-01": 79.60
"2025-08-01": 84.77
"2025-09-01": 93.39
"2025-10-01": 91.05
"2025-11-01": 81.77
"2025-12-01": 76.10
filters:
categories: [3]
regions: [42]
properties:
aux_timeseries:
description: |
Optional. One to ten auxiliary driver series. Each item is a map of the same
YYYY-MM-DD date keys as `timeseries` — exactly the same dates, no more and no
fewer — to numeric values. Each series becomes a forecast driver that is kept
through feature selection, and series are identified by their array position
(the first is `aux_0`, the second `aux_1`, and so on). When omitted, the
forecast runs without auxiliary drivers.
type: array
minItems: 1
maxItems: 10
items:
additionalProperties:
type: number
type: object
backtest:
description: When true, run a backtest evaluation alongside the forecast and include `backtest_metrics.json` and `backtest_trajectories.json` in the artifacts.
type: boolean
filters:
allOf:
- $ref: '#/components/schemas/Filters'
description: |
Optional. Each **`categories[]`** and **`regions[]`** entry must be an integer **1–9999**
(inclusive). Optional **`limit`** is **0–1000** (default **100** when omitted). Values are not verified against catalog APIs.
frequency:
description: Series cadence. Only `monthly` is currently supported.
enum:
- monthly
type: string
hard_horizon:
description: |
Minimum acceptable horizon (months) for the quality step-down ladder. When omitted, the
pipeline falls back to a driverless forecast at `soft_horizon` if no quality run succeeds.
When still failing at `hard_horizon`, the pipeline emits a driverless forecast at that horizon.
At least one of `soft_horizon` or `hard_horizon` must be present. When both are set,
`hard_horizon` must be less than or equal to `soft_horizon`. Maximum 12.
maximum: 12
minimum: 1
type: integer
max_num_features:
description: |
Optional. Caps the number of drivers kept by the final feature-selection step
(top-k). When omitted, the pipeline uses the regime default. Bounded above by the
regime's selector ceiling, so a value larger than that cap is a no-op. Must be a
positive integer when present.
minimum: 1
type: integer
optimization_budget:
default: none
description: |
Optional. Tunes the number of hyper-parameter-optimization trials. `low` runs fewer
trials, `high` runs the most; `none` and `mid` fall back to the pipeline default.
Defaults to `none`.
enum:
- none
- low
- mid
- high
type: string
pipeline_version:
description: Pipeline version. Closed set — only `v1` is supported today.
enum:
- v1
type: string
recency_factor:
description: Weight given to more recent observations when selecting drivers. 0.0 = equal weight across the full history; 1.0 = strongest recency bias.
format: double
maximum: 1
minimum: 0
type: number
run_baseline:
default: false
description: |
When true, re-run the same primary model with drivers stripped and surface its
metrics as a self-comparison baseline alongside the reference baselines, isolating
the lift the drivers add. Defaults to false.
type: boolean
soft_horizon:
description: |
Ideal forecast horizon (months). The pipeline tries this first, then steps down by one month
until it reaches `hard_horizon` (when set) while seeking a quality forecast. At least one of
`soft_horizon` or `hard_horizon` must be present. When both are set, `hard_horizon` must be
less than or equal to `soft_horizon`. Maximum 12.
maximum: 12
minimum: 1
type: integer
strictly_positive:
default: false
description: |
When true, every value in `timeseries` must be `>= 0`; a single negative observation
rejects the request with 422. The pipeline also clamps output values at zero.
Defaults to false.
type: boolean
timeseries:
additionalProperties:
type: number
description: |
Map of YYYY-MM-DD date keys to numeric observation values. Must contain at least
the horizon-dependent minimum number of monthly observations (40 for max horizon 1–3,
60 for 4–6, 120 for 7–12) aligned to the first of each month.
type: object
timeseries_metadata:
allOf:
- $ref: '#/components/schemas/TimeseriesMetadata'
description: Describes the series so the pipeline can identify relevant drivers.
trend_num_classes:
description: |
Optional. Trend-classification label granularity: `2` (binary up/down) or `3`
(down/flat/up). Consumed only on the trend analysis path and ignored otherwise.
When omitted, the pipeline applies its default of `3`.
enum:
- 2
- 3
type: integer
required:
- pipeline_version
- frequency
- recency_factor
- timeseries_metadata
- timeseries
type: object
JobSummary:
description: Lightweight summary of an async job (no payload or artifact manifest).
example:
job_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
pipeline_type: "forecast"
status: "completed"
created_at: "2026-05-01T10:00:00Z"
settled: true
settled_at: "2026-05-01T10:04:32Z"
eur_cents_final: 250
properties:
created_at:
format: date-time
type: string
eur_cents_final:
description: Final settled charge for the job in EUR cents. Null until the job reaches a terminal state.
format: int64
nullable: true
type: integer
job_id:
format: uuid
type: string
pipeline_type:
description: Pipeline that produced this job — currently always `forecast`.
type: string
run_id:
description: Opaque internal run identifier. Omitted for jobs that have not started yet; include in support requests.
type: string
settled:
description: True once the job has reached a terminal state and the charge has been posted.
type: boolean
settled_at:
format: date-time
nullable: true
type: string
status:
enum:
- queued
- running
- completed
- failed
- canceled
type: string
terminal_reason:
description: Human-readable failure message for `failed` or `canceled` jobs; null for non-terminal statuses or cleanly-canceled jobs.
nullable: true
type: string
workflow_id:
description: Opaque internal workflow identifier. Omitted for jobs that have not started yet; include in support requests.
type: string
required:
- job_id
- pipeline_type
- status
- created_at
- settled
type: object
JobsPagination:
properties:
limit:
description: Page size echoed back from the request.
maximum: 200
minimum: 1
type: integer
order:
description: Sort direction echoed back from the request.
enum:
- asc
- desc
type: string
page:
description: 1-indexed current page number echoed back from the request.
minimum: 1
type: integer
sort:
description: Column the rows are sorted by, echoed back from the request.
enum:
- id
- created_at
- settled_at
- eur_cents_final
type: string
total:
description: Total matching rows for the authenticated user (full set, not just this page).
format: int64
minimum: 0
type: integer
total_pages:
description: ceil(total / limit). Zero when total is zero.
format: int64
minimum: 0
type: integer
required:
- page
- limit
- total
- total_pages
- sort
- order
type: object
MeResponse:
description: |
Authenticated user snapshot. All monetary fields are integer EUR cents
(1 EUR = 100 cents).
example:
user_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
balance_eur_cents: 4750
available_eur_cents: 4250
api_usage_tier: 1
lifetime_paid_cents: 10000
payment_count: 2
has_ever_paid: true
role: "user"
euro_tranches:
- id: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
source: "stripe"
initial_eur_cents: 5000
remaining_eur_cents: 4750
created_at: "2026-05-01T09:00:00Z"
expires_at: "2027-05-01T09:00:00Z"
properties:
api_usage_tier:
description: Current pricing tier level. Higher levels unlock better rate limits and job concurrency.
type: integer
auto_recharge:
$ref: '#/components/schemas/AutoRechargeState'
available_eur_cents:
description: Spendable balance in EUR cents — `balance_eur_cents` minus any credits held for in-flight async jobs.
format: int64
type: integer
balance_eur_cents:
description: Total credit balance in EUR cents, before deducting active holds.
format: int64
type: integer
euro_tranches:
description: Active credit grants (non-empty, unexpired), consumed in `expires_at` ascending order.
items:
$ref: '#/components/schemas/EuroTranche'
type: array
has_ever_paid:
description: True once the account has completed at least one successful Stripe payment.
type: boolean
lifetime_paid_cents:
description: Cumulative EUR cents charged across all Stripe payments, all time.
format: int64
type: integer
payment_count:
description: Total number of successful Stripe payments on this account.
type: integer
role:
description: Account role. `admin` accounts can sign in to the staff back-office; regular accounts are `user`.
enum:
- user
- admin
type: string
signup_trial:
description: Present when a free trial tranche was granted at signup. Omitted for accounts with no trial.
nullable: true
properties:
expires_at:
format: date-time
type: string
granted_at:
format: date-time
type: string
initial_eur_cents:
format: int64
type: integer
remaining_eur_cents:
format: int64
type: integer
type: object
user_id:
format: uuid
type: string
required:
- user_id
- balance_eur_cents
- available_eur_cents
- api_usage_tier
- lifetime_paid_cents
- payment_count
- has_ever_paid
- role
- euro_tranches
type: object
NewsItemV1:
description: A news article associated with an alert.
example:
trending: true
title: "US-Iran agreed on principal deal to open Strait of Hormuz"
description: "The US and Iran have reportedly reached a preliminary understanding to reopen the Strait of Hormuz, one of the world's most critical oil shipping routes."
url: "https://www.thenews.com.pk/latest/1403722"
published_at: "2026-05-24T21:28:00Z"
source_name: "The News International"
category: "world"
properties:
category:
description: Topical category of the article (e.g. `world`, `business`, `energy`).
type: string
description:
description: Short summary of the article.
type: string
published_at:
description: Publication timestamp (RFC 3339 / ISO 8601).
format: date-time
type: string
source_name:
description: Name of the publication or media outlet.
type: string
title:
description: Headline of the news article.
type: string
trending:
description: Whether this article is currently trending across the platform.
type: boolean
url:
description: Canonical URL of the article.
format: uri
type: string
type: object
Pagination:
properties:
limit:
description: Page size echoed back from the request.
maximum: 200
minimum: 1
type: integer
order:
description: Sort direction.
enum:
- asc
- desc
type: string
page:
description: 1-indexed current page number echoed back from the request.
minimum: 1
type: integer
sort:
description: Column the rows are sorted by.
enum:
- id
- created_at
- eur_cents_charged
- credits_charged
- units
type: string
total:
description: Total matching rows for the authenticated user (full set, not just this page).
format: int64
minimum: 0
type: integer
total_pages:
description: ceil(total / limit). Zero when total is zero.
format: int64
minimum: 0
type: integer
required:
- page
- limit
- total
- total_pages
- sort
- order
type: object
RecommendRequestV1:
description: |
Body of `POST /api/v1/drivers`. Mirrors the upstream Recommend service
c
# --- truncated at 32 KB (74 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sybilion/refs/heads/main/openapi/sybilion-operational-api-openapi.yml