POST /api/v1/alerts

Synchronous endpoint that validates the body, runs alert detection against the provided timeseries metadata, and returns the response verbatim.

Request (AlertsRequestV1)

Field	Rules
metadata.title	Required. 20–511 characters.
metadata.description	Optional. ≤ 2048 characters.
metadata.keywords	Optional. ≤ 20 items, each ≤ 255 characters.
context_enriched	Required boolean. Set to true if the metadata is already context-enriched.
date_from	Optional YYYY-MM-DD. Lower date bound for alert detection.
date_to	Optional YYYY-MM-DD. Upper date bound. Must be ≥ date_from when both are supplied.
filters	Optional — same JSON shape and validation as POST /api/v1/drivers. For browsing ids see Regions & categories; values are not cross-checked on submit.
filters.limit	Optional integer 0–100. Controls how many alerts are returned. Defaults to 100 when omitted.

Call the endpoint

curl

cat > alerts_body.json <<'EOF'
{
  "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"]
  },
  "context_enriched": false,
  "date_from": "2024-01-01",
  "date_to": "2025-12-31",
  "filters": {
    "categories": [3, 7],
    "regions": [42],
    "limit": 25
  }
}
EOF

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

Python

import os

from sybilion import Client
from sybilion._api.models import Filters, TimeseriesMetadata

client = Client(token=os.environ["SYBILION_API_TOKEN"])

meta = TimeseriesMetadata(
    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"],
)

filters = Filters(categories=[3, 7], regions=[42], limit=25)

alerts = client.get_alerts(
    metadata=meta,
    context_enriched=False,
    filters=filters,
    date_from="2024-01-01",
    date_to="2025-12-31",
)
print(alerts)

Go

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"go.sybilion.dev/sybilion"
	api "go.sybilion.dev/sybilion/api"
)

func main() {
	c := sybilion.New(sybilion.Options{
		Token: os.Getenv("SYBILION_API_TOKEN"),
	})

	meta := api.NewTimeseriesMetadata("Brent Crude Oil Price Monthly")
	meta.SetDescription("Monthly average Brent crude oil spot price in USD/barrel, sourced from EIA.")
	meta.SetKeywords([]string{"oil", "brent", "energy", "commodity"})

	filters := api.NewFilters()
	filters.SetCategories([]int32{3, 7})
	filters.SetRegions([]int32{42})
	filters.SetLimit(25)

	resp, err := c.GetAlerts(context.Background(), sybilion.AlertsRequest{
		Metadata:        *meta,
		ContextEnriched: false,
		Filters:         filters,
		DateFrom:        "2024-01-01",
		DateTo:          "2025-12-31",
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(resp)
}

Date bounds

date_from and date_to are optional date bounds in YYYY-MM-DD format. Omit either to leave that end of the window open.

Response

{
  "alerts": [
    {
      "name": "Brent Crude Oil",
      "pct_change": 12.4,
      "trending": true,
      "news": [
        {
          "title": "Oil prices surge on supply concerns",
          "description": "Brent crude rose sharply after...",
          "url": "https://example.com/article",
          "published_at": "2026-04-30T08:00:00Z",
          "source_name": "Reuters",
          "category": "Energy",
          "trending": true
        }
      ]
    }
  ]
}

Field reference

alerts[]

Field	Meaning
name	Human-readable name of the market factor that triggered the alert.
pct_change	Percentage change of the market factor's latest daily value compared to its value from the previous week.
trending	true if this market factor corresponds to one of today's top trending news topics. A trending alert means a trending news story fired this alert.
news[]	News articles that support and justify this alert. The engine searches for news related to the market factor's topic.

alerts[].news[]

Field	Meaning
title	Article headline.
description	Short summary of the article.
url	Canonical URL of the article.
published_at	RFC3339 publication timestamp.
source_name	Publication or outlet name.
category	Topical category of the article.
trending	true if this article is part of today's top trending news.

Response count

The response may contain anywhere from zero to filters.limit (default 100) alerts, depending on how many semantically related market factors with active alerts are found for your topic.

Common errors

Code	Cause	What to do
402	Available balance below the worst-case ceiling.	Top up, or reduce filters.limit so the pre-check fits the available balance.
422	Validation failure (one detail per response).	Inspect details[0].
429	Per-minute cap on synchronous billed calls exceeded.	Wait before retrying. Check tier limits on /tiers.
502	Transport error talking to the engine.	Retry with the same X-Request-ID.
503	Alerts feature not enabled for this account.	Contact [email protected].

For the full error envelope, see Errors & limits.