List Notifications
Query Parameters
Filter for unread notifications only (true or false)
Response
Array of notification objectsShow Notification properties
Unique notification identifier
Notification type: visibility_drop, new_mention, sentiment_shift, or competitor_new
Additional metadata about the notification
ISO 8601 timestamp when notification was read (null if unread)
Example Request
curl -X GET "https://api.opensight.ai/api/notifications?unread=true" \
-H "Authorization: Bearer YOUR_API_KEY"
Example Response
{
"notifications": [
{
"id": "notif_123",
"user_id": "user_456",
"type": "visibility_drop",
"title": "Visibility Drop Alert",
"body": "Your brand visibility on ChatGPT dropped by 15% in the last 24 hours",
"metadata": {
"brand_id": "brand_123",
"engine": "chatgpt",
"change_percent": -15
},
"read_at": null,
"created_at": "2024-01-15T10:00:00Z"
},
{
"id": "notif_124",
"user_id": "user_456",
"type": "new_mention",
"title": "New Brand Mention",
"body": "Your brand was mentioned in a new prompt response on Perplexity",
"metadata": {
"brand_id": "brand_123",
"prompt_id": "prompt_789",
"engine": "perplexity"
},
"read_at": null,
"created_at": "2024-01-15T09:30:00Z"
}
]
}
Mark Notification as Read
Path Parameters
Response
The updated notification object
Example Request
curl -X PATCH "https://api.opensight.ai/api/notifications/notif_123/read" \
-H "Authorization: Bearer YOUR_API_KEY"
Example Response
{
"notification": {
"id": "notif_123",
"user_id": "user_456",
"type": "visibility_drop",
"title": "Visibility Drop Alert",
"body": "Your brand visibility on ChatGPT dropped by 15% in the last 24 hours",
"metadata": {
"brand_id": "brand_123",
"engine": "chatgpt",
"change_percent": -15
},
"read_at": "2024-01-15T10:30:00Z",
"created_at": "2024-01-15T10:00:00Z"
}
}
Errors
- 404 Not Found - Notification not found or user doesn’t own it
Mark All as Read
Response
Returns true if successful
Example Request
curl -X PATCH "https://api.opensight.ai/api/notifications/read-all" \
-H "Authorization: Bearer YOUR_API_KEY"
Example Response
Get Notification Settings
Response
The notification settings objectShow NotificationSettings properties
Email frequency: daily, weekly, or none
Whether to alert on visibility drops
Whether to alert on new mentions
Whether to alert on sentiment shifts
Whether to alert on new competitor mentions
Webhook URL for real-time alerts (Growth plan only)
Example Request
curl -X GET "https://api.opensight.ai/api/notifications/settings" \
-H "Authorization: Bearer YOUR_API_KEY"
Example Response
{
"settings": {
"id": "settings_123",
"user_id": "user_456",
"email_frequency": "daily",
"alert_visibility_drop": true,
"alert_new_mention": true,
"alert_sentiment_shift": true,
"alert_competitor_new": false,
"webhook_url": "https://your-app.com/webhooks/opensight",
"updated_at": "2024-01-15T10:00:00Z"
}
}
Update Notification Settings
Request Body
Email frequency: daily, weekly, or none
Whether to alert on visibility drops
Whether to alert on new mentions
Whether to alert on sentiment shifts
Whether to alert on new competitor mentions
Webhook URL for real-time alerts (Growth plan only, set to null to disable)
Response
The updated settings object
Example Request
curl -X PATCH "https://api.opensight.ai/api/notifications/settings" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email_frequency": "weekly",
"alert_visibility_drop": true,
"alert_new_mention": false,
"webhook_url": "https://your-app.com/webhooks/opensight"
}'
Example Response
{
"settings": {
"id": "settings_123",
"user_id": "user_456",
"email_frequency": "weekly",
"alert_visibility_drop": true,
"alert_new_mention": false,
"alert_sentiment_shift": true,
"alert_competitor_new": false,
"webhook_url": "https://your-app.com/webhooks/opensight",
"updated_at": "2024-01-15T11:00:00Z"
}
}
Webhook alerts are only available on the Growth plan. Setting a webhook_url on lower plans will be ignored.