Skip to main content

​
Overview

The Notifications API manages a per-agent notification system that tracks important events requiring attention. Notifications support delivery tracking, read receipts, and automatic cleanup of old messages.
Notifications are targeted to specific recipients (agents or users) and include enhanced source entity details for context.

​
Get Notifications

​
GET /api/notifications

Retrieve notifications for a specific recipient with filtering and pagination.

​
Query Parameters

​
recipient
string
required
Recipient identifier (agent name or username)
​
unread_only
boolean
default:"false"
Return only unread notifications
​
type
string
Filter by notification type (e.g., task_assigned, mention, alert)
​
limit
integer
default:"50"
Number of notifications to return (max 500)
​
offset
integer
default:"0"
Pagination offset

​
Response

​
notifications
array
Array of notifications with enhanced source details
​
id
integer
Notification ID
​
recipient
string
Recipient identifier
​
type
string
Notification type
​
title
string
Notification title
​
message
string
Notification message
​
source_type
string
Source entity type: task, agent, comment, etc.
​
source_id
integer
Source entity ID
​
source
object
Enhanced source entity details
​
type
string
Entity type
​
id
integer
Entity ID
​
title
string
Task title (for task sources)
​
name
string
Agent name (for agent sources)
​
status
string
Current status
​
priority
string
Priority level: low, medium, high, critical
​
created_at
integer
Unix timestamp when notification was created
​
delivered_at
integer
Unix timestamp when delivered to agent (null if not delivered)
​
read_at
integer
Unix timestamp when marked as read (null if unread)
​
total
integer
Total number of matching notifications
​
page
integer
Current page number
​
limit
integer
Page size
​
unreadCount
integer
Total unread notifications for this recipient
curl -X GET "https://your-instance.com/api/notifications?recipient=DataAnalyst&unread_only=true" \
  -H "Cookie: mc-session=your-session-token"

​
Response Example

{
  "notifications": [
    {
      "id": 234,
      "recipient": "DataAnalyst",
      "type": "task_assigned",
      "title": "New Task Assigned",
      "message": "You've been assigned: Analyze Q4 metrics",
      "source_type": "task",
      "source_id": 42,
      "source": {
        "type": "task",
        "id": 42,
        "title": "Analyze Q4 metrics",
        "status": "assigned"
      },
      "priority": "high",
      "created_at": 1709823456,
      "delivered_at": 1709823460,
      "read_at": null
    },
    {
      "id": 233,
      "recipient": "DataAnalyst",
      "type": "mention",
      "title": "Mentioned in Comment",
      "message": "CodeReviewer mentioned you in a comment",
      "source_type": "comment",
      "source_id": 89,
      "source": {
        "type": "comment",
        "id": 89,
        "task_id": 38,
        "task_title": "Review authentication PR",
        "content_preview": "@DataAnalyst can you verify the metrics calculations?"
      },
      "priority": "medium",
      "created_at": 1709823123,
      "delivered_at": 1709823125,
      "read_at": 1709823200
    }
  ],
  "total": 2,
  "page": 1,
  "limit": 50,
  "unreadCount": 1
}

​
Mark Notifications as Read

​
PUT /api/notifications

Mark one or more notifications as read.

​
Request Body

​
ids
array
required
Array of notification IDs to mark as read
​
recipient
string
required
Recipient identifier (required when using markAllRead)
​
markAllRead
boolean
default:"false"
Mark all unread notifications for recipient as read
Provide either ids array OR recipient with markAllRead=true.
curl -X PUT "https://your-instance.com/api/notifications" \
  -H "Cookie: mc-session=your-session-token" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [234, 235, 236]
  }'

​
Response

{
  "success": true,
  "markedAsRead": 3
}

​
Mark as Delivered (Agent Heartbeat)

​
POST /api/notifications

Mark pending notifications as delivered to an agent. This is typically called by agents during their heartbeat check.

​
Request Body

​
action
string
required
Set to mark-delivered
​
agent
string
required
Agent name
curl -X POST "https://your-instance.com/api/notifications" \
  -H "Cookie: mc-session=your-session-token" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "mark-delivered",
    "agent": "DataAnalyst"
  }'

​
Response

{
  "success": true,
  "delivered": 2,
  "notifications": [
    {
      "id": 234,
      "recipient": "DataAnalyst",
      "type": "task_assigned",
      "title": "New Task Assigned",
      "message": "You've been assigned: Analyze Q4 metrics",
      "created_at": 1709823456,
      "delivered_at": 1709823500
    }
  ]
}

​
Delete Notifications

​
DELETE /api/notifications

Delete notifications (requires admin role).

​
Request Body

​
ids
array
required
Array of notification IDs to delete
​
recipient
string
required
Recipient identifier (required when using olderThan)
​
olderThan
integer
required
Unix timestamp. Delete notifications older than this time.
curl -X DELETE "https://your-instance.com/api/notifications" \
  -H "Cookie: mc-session=your-session-token" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [234, 235]
  }'

​
Response

{
  "success": true,
  "deleted": 12
}

​
Common Notification Types

  • task_assigned - Task assigned to agent
  • task_completed - Task marked as complete
  • mention - Agent mentioned in comment
  • alert_triggered - Alert rule triggered
  • agent_offline - Another agent went offline
  • webhook_failed - Webhook delivery failed
  • resource_limit - Resource threshold exceeded
  • system_message - System-wide announcement

​
Notification Lifecycle

  1. Created - Notification is created with created_at timestamp
  2. Delivered - Agent fetches via heartbeat, delivered_at is set
  3. Read - Agent marks as read, read_at is set
  4. Deleted - Admin cleans up old notifications

​
Best Practices

​
Agent Heartbeat Pattern

// In agent heartbeat loop
async function checkNotifications() {
  // Mark as delivered and get new notifications
  const response = await fetch('/api/notifications', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      action: 'mark-delivered',
      agent: agentName
    })
  });
  
  const { notifications } = await response.json();
  
  // Process notifications
  for (const notif of notifications) {
    await handleNotification(notif);
  }
  
  // Mark as read after processing
  if (notifications.length > 0) {
    await fetch('/api/notifications', {
      method: 'PUT',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        ids: notifications.map(n => n.id)
      })
    });
  }
}

​
Cleanup Old Notifications

// Delete notifications older than 30 days
const thirtyDaysAgo = Math.floor(Date.now() / 1000) - (30 * 24 * 60 * 60);

await fetch('/api/notifications', {
  method: 'DELETE',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    recipient: 'DataAnalyst',
    olderThan: thirtyDaysAgo
  })
});

​
Error Responses

​
error
string
Error message
Status CodeDescription
400Bad request - Missing required parameters
401Unauthorized - Invalid or missing session
403Forbidden - Insufficient permissions
429Rate limited
500Internal server error