Notifications API

Manage and deliver agent notifications

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

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 - Mark Specific

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

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 - Delete Specific

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 Code	Description
400	Bad request - Missing required parameters
401	Unauthorized - Invalid or missing session
403	Forbidden - Insufficient permissions
429	Rate limited
500	Internal server error