Notifications API

Overview

The Notifications API lets you list, read, and manage in-app notifications. It also provides endpoints for checking delivery channel health, linking your Telegram account, and managing push subscriptions.

Real-time notification delivery is available via WebSocket (notification.new event).

Authentication

All endpoints require either a JWT token or an API key (gf_...) in the Authorization header.

Endpoints

Method	Path	Description
GET	/api/v1/notifications	List notifications (paginated)
GET	/api/v1/notifications/:id	Get single notification
POST	/api/v1/notifications/:id/read	Mark as read
POST	/api/v1/notifications/read-all	Mark all as read
GET	/api/v1/notifications/unread-count	Unread count
POST	/api/v1/notifications/telegram/generate-code	Generate Telegram link code
GET	/api/v1/notifications/telegram/status	Telegram link status
DELETE	/api/v1/notifications/telegram/unlink	Unlink Telegram
POST	/api/v1/notifications/push/subscribe	Register push subscription
DELETE	/api/v1/notifications/push/unsubscribe	Remove push subscription

Notification Object

{
  "id": "notif_01JXYZ...",
  "eventType": "budget_alert",
  "title": "Budget 80% consumed",
  "message": "Campaign 'FB US iOS' has used 80% of its daily budget.",
  "channel": "inapp",
  "status": "delivered",
  "readAt": null,
  "createdAt": "2025-01-15T10:30:00Z",
  "payload": { "campaignId": "camp_abc123", "budgetPct": 80 }
}

Event Types

Type	Description
budget_alert	Campaign budget threshold reached
conversion_alert	Conversion rate anomaly detected
performance_alert	Traffic or CTR performance change
campaign_status	Campaign paused, started, or ended
billing_alert	Balance low, payment failed
security_alert	Suspicious login or API key usage
system_update	Platform maintenance or new features
weekly_report	Weekly performance summary

Examples

List Notifications

curl

curl "https://devcore.getghostflow.io/api/v1/notifications?page=1&perPage=20&eventType=budget_alert" \
  -H "Authorization: Bearer gf_your_api_key"

TypeScript

const response = await fetch(
  'https://devcore.getghostflow.io/api/v1/notifications?page=1&perPage=20',
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
);
const { notifications, total, page, perPage } = await response.json();

Query Parameters:

Param	Type	Default	Description
page	integer	1	Page number
perPage	integer	50	Items per page (max 100)
eventType	string	—	Filter by event type
status	string	—	Filter: unread, read, delivered
channel	string	—	Filter by channel
since	string	—	ISO 8601 datetime, return only newer

Get Unread Count

curl

curl https://devcore.getghostflow.io/api/v1/notifications/unread-count \
  -H "Authorization: Bearer gf_your_api_key"

{ "count": 5 }

Mark All as Read

curl

curl -X POST https://devcore.getghostflow.io/api/v1/notifications/read-all \
  -H "Authorization: Bearer gf_your_api_key"

Link Telegram Account

curl

# Step 1: Generate a linking code
curl -X POST https://devcore.getghostflow.io/api/v1/notifications/telegram/generate-code \
  -H "Authorization: Bearer gf_your_api_key"

{
  "code": "GF-A1B2C3",
  "expiresInSeconds": 300,
  "botUsername": "GhostFlowBot"
}

Send the code to @GhostFlowBot on Telegram within 5 minutes to complete linking.

Tip

Once linked, you will receive budget alerts, conversion alerts, and security alerts directly in Telegram. Configure which events are delivered to Telegram in Settings → Notifications.

WebSocket Events

Subscribe to real-time notifications via the shared WebSocket connection:

{
  "type": "notification.new",
  "payload": {
    "messageId": "msg_01ABC...",
    "data": {
      "notificationId": "notif_01JXYZ...",
      "eventType": "conversion_alert",
      "title": "Conversion spike detected",
      "message": "Campaign 'TikTok EU' conversions up 150% in last hour.",
      "payload": null,
      "timestamp": 1736937000000
    }
  }
}

Rate Limits

Endpoint	Limit
GET (list, count)	60 req/min
POST (mark read)	30 req/min
DELETE	20 req/min
Telegram generate-code	5 req/min