Skip to main content

Alerts API

Overview​

Endpoints for managing user email subscriptions and watchlist tracking for Alert System Beta. Base path: /api/alerts

The dashboard beta now exposes these flows through an in-product alert panel that lets users manage subscriptions and watchlist notes for the currently open company or crypto profile.

🔔 Subscriptions​

Subscribe to Alerts​

POST /api/alerts/subscribe

Subscribe to notifications for a specific company or crypto project.

Body:

{
  "email": "user@example.com",
  "entity_type": "company", // or "crypto"
  "entity_slug": "volkswagen",
  "alert_types": ["score_change"]
}

Alert Types:

  • score_change: Triggered when Trust Score changes significantly
  • unlock_event: Triggered before token unlocks (crypto only)

Score-change delivery is stateful during the beta: Vartovii compares the latest available Trust Score with the last stored baseline for the subscribed entity and sends email only after a meaningful shift, not on every refresh.

Unsubscribe​

POST /api/alerts/unsubscribe

Stop receiving alerts for a specific entity.

Body:

{
  "email": "user@example.com",
  "entity_type": "company",
  "entity_slug": "volkswagen"
}

Get My Subscriptions​

GET /api/alerts/subscriptions

List all active subscriptions for an email address.

Parameters:

  • email: User email address

👁️ Watchlist​

Add or Update Watchlist Item​

POST /api/alerts/watchlist

Create a tracked entity entry for an email address. Repeated requests for the same entity update the stored note.

Body:

{
  "email": "user@example.com",
  "entity_type": "company",
  "entity_slug": "volkswagen",
  "notes": "Track score drift after quarterly refresh"
}

View Watchlist​

GET /api/alerts/watchlist

List tracked entities for an email address.

Parameters:

  • email: User email address

Update Watchlist Item​

PATCH /api/alerts/watchlist

Update the note for an existing watchlist item.

Body:

{
  "email": "user@example.com",
  "entity_type": "company",
  "entity_slug": "volkswagen",
  "notes": "Escalate if Trust Score drops after a new scrape"
}

Delete Watchlist Item​

DELETE /api/alerts/watchlist

Remove a tracked entity from the watchlist.

Parameters:

  • email: User email address
  • entity_type: company or crypto
  • entity_slug: Canonical entity slug

🛠️ System & Testing​

Send Test Alert​

POST /api/alerts/test

Triggers a test email to verify SMTP configuration (Admin/Debug only).

Parameters:

  • email: Target email
  • entity_name: Name to use in template (default: Bitcoin)

Health Check​

GET /api/alerts/health

Returns the status of the email service.

Response:

{
  "status": "healthy",
  "email_configured": true,
  "smtp_host": "smtp.gmail.com"
}