Overview

For clients unable to maintain persistent WebSocket connections, the REST polling endpoint provides an alternative notification retrieval mechanism. This approach supports battery-constrained devices and simplified client implementations.

Fetch Pending Notifications

Endpoint: GET /api/v1/client/notifications
Authentication: Requires Bearer token using user credentials

Query Parameters

Parameter	Type	Required	Description
`status`	string	No	Filter by notification state, e.g., “pending” (default: all)
`limit`	integer	No	Maximum notifications to return (default: 50, max: 100)
`cursor`	string	No	Pagination cursor from previous response
`service_id`	string	No	Filter by originating service ID
`project`	string	No	Filter by project identifier
`sort`	string	No	Sort order, either “newest” or “oldest” (default: “newest”)

Response

{
  "notifications": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "version": "1.0",
      "timestamp": "2025-05-25T10:30:00Z",
      "deadline": "2025-05-25T11:00:00Z",
      "service": {
        "id": "lovelace-ide",
        "name": "Lovelace IDE",
        "icon": "https://lovelace.dev/icon.png"
      },
      "context": {
        "title": "Deploy to Production?",
        "description": "New version 2.1.0 is ready for deployment to production servers.",
        "project": "backend-api",
        "metadata": {
          "version": "2.1.0",
          "changes": 47,
          "test_coverage": "98.3%"
        }
      },
      "actions": [
        {
          "id": "approve",
          "label": "Approve Deployment",
          "response_type": "simple",
          "flags": ["irreversible"]
        },
        {
          "id": "reject",
          "label": "Reject",
          "response_type": "text",
          "constraints": {
            "placeholder": "Reason for rejection"
          }
        }
      ],
      "status": "delivered"
    },
    // Additional notifications...
  ],
  "pagination": {
    "next_cursor": "cursor_for_next_page",
    "has_more": true,
    "total_count": 156
  }
}

The pagination object contains:

Field	Type	Description
`next_cursor`	string	Cursor to use for fetching the next page
`has_more`	boolean	Indicates if more results are available
`total_count`	integer	Total count of matching notifications

The pagination mechanism ensures efficient retrieval of large notification sets while maintaining consistent ordering.

Error Responses

Status Code	Error Code	Description
`400 Bad Request`	`INVALID_PARAMETER`	Invalid query parameter
`401 Unauthorized`	`AUTH_INVALID_TOKEN`	User token is invalid
`429 Too Many Requests`	`RATE_LIMIT_EXCEEDED`	Rate limit exceeded

Fetch Single Notification

Endpoint: GET /api/v1/client/notifications/{id}
Authentication: Requires Bearer token using user credentials

Path Parameters

Parameter	Type	Description
`id`	string	The UUID of the notification to retrieve

Response

Returns a single notification object with the same structure as in the list endpoint.

Error Responses

Status Code	Error Code	Description
`401 Unauthorized`	`AUTH_INVALID_TOKEN`	User token is invalid
`403 Forbidden`	`NOTIFICATION_ACCESS_DENIED`	User does not have access to this notification
`404 Not Found`	`NOTIFICATION_NOT_FOUND`	Notification with specified ID does not exist

Acknowledge Notification

Endpoint: POST /api/v1/client/notifications/{id}/acknowledge
Authentication: Requires Bearer token using user credentials This endpoint allows clients to acknowledge receipt of a notification, updating its status to acknowledged.

Path Parameters

Parameter	Type	Description
`id`	string	The UUID of the notification to acknowledge

Response

Status Code: 200 OK

{
  "notification_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "acknowledged",
  "acknowledged_at": "2025-05-25T10:32:15Z"
}

Error Responses

Status Code	Error Code	Description
`401 Unauthorized`	`AUTH_INVALID_TOKEN`	User token is invalid
`403 Forbidden`	`NOTIFICATION_ACCESS_DENIED`	User does not have access to this notification
`404 Not Found`	`NOTIFICATION_NOT_FOUND`	Notification with specified ID does not exist
`409 Conflict`	`NOTIFICATION_ALREADY_RESPONDED`	Notification has already been responded to

Examples

Fetch Pending Notifications - JavaScript

async function fetchPendingNotifications() {
  try {
    const response = await fetch(
      'https://atp.example.com/api/v1/client/notifications?status=pending&limit=20',
      {
        headers: {
          'Authorization': 'Bearer user_token_xyz789'
        }
      }
    );
    
    if (!response.ok) {
      throw new Error(`HTTP error ${response.status}`);
    }
    
    const data = await response.json();
    
    // Process notifications
    for (const notification of data.notifications) {
      displayNotification(notification);
    }
    
    // Store pagination cursor for next request
    if (data.pagination.has_more) {
      sessionStorage.setItem('notifications_cursor', data.pagination.next_cursor);
    }
    
    return data;
  } catch (error) {
    console.error('Error fetching notifications:', error);
    throw error;
  }
}

Fetch Pending Notifications - Python

import requests

def fetch_pending_notifications(token, cursor=None, limit=20):
    url = 'https://atp.example.com/api/v1/client/notifications'
    
    params = {
        'status': 'pending',
        'limit': limit
    }
    
    if cursor:
        params['cursor'] = cursor
    
    headers = {
        'Authorization': f'Bearer {token}'
    }
    
    response = requests.get(url, params=params, headers=headers)
    response.raise_for_status()
    
    data = response.json()
    
    # Process notifications
    for notification in data['notifications']:
        display_notification(notification)
    
    # Return pagination cursor for next request
    next_cursor = None
    if data['pagination']['has_more']:
        next_cursor = data['pagination']['next_cursor']
    
    return data['notifications'], next_cursor

Acknowledge Notification - JavaScript

async function acknowledgeNotification(notificationId) {
  try {
    const response = await fetch(
      `https://atp.example.com/api/v1/client/notifications/${notificationId}/acknowledge`,
      {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer user_token_xyz789',
          'Content-Type': 'application/json'
        }
      }
    );
    
    if (!response.ok) {
      throw new Error(`HTTP error ${response.status}`);
    }
    
    const data = await response.json();
    console.log(`Notification ${notificationId} acknowledged`);
    
    return data;
  } catch (error) {
    console.error('Error acknowledging notification:', error);
    throw error;
  }
}

Polling Strategy

For applications that use REST polling instead of WebSockets, implement an efficient polling strategy to minimize battery consumption and server load:

Adaptive Polling: Adjust polling frequency based on notification activity
Background Polling: Use platform-specific background fetch capabilities for mobile apps
Exponential Backoff: Increase polling interval after periods of inactivity
Priority-Based: Poll more frequently for high-priority projects or services

Example Adaptive Polling Strategy

class AdaptivePoller {
  constructor(options = {}) {
    this.minInterval = options.minInterval || 30000; // 30 seconds
    this.maxInterval = options.maxInterval || 300000; // 5 minutes
    this.scaleFactor = options.scaleFactor || 1.5;
    this.currentInterval = this.minInterval;
    this.timer = null;
    this.lastNotificationCount = 0;
  }
  
  start(callback) {
    this.stop();
    
    const poll = async () => {
      try {
        const result = await callback();
        
        // Adjust polling interval based on activity
        if (result.notifications.length > 0) {
          // Activity detected, decrease interval
          this.currentInterval = this.minInterval;
          this.lastNotificationCount = result.notifications.length;
        } else if (this.lastNotificationCount === 0) {
          // No recent activity, increase interval
          this.currentInterval = Math.min(
            this.currentInterval * this.scaleFactor,
            this.maxInterval
          );
        } else {
          // Had notifications before but none now, reset counter
          this.lastNotificationCount = 0;
        }
      } catch (error) {
        console.error('Polling error:', error);
        // Increase interval on error
        this.currentInterval = Math.min(
          this.currentInterval * this.scaleFactor,
          this.maxInterval
        );
      }
      
      // Schedule next poll
      this.timer = setTimeout(poll, this.currentInterval);
    };
    
    // Start polling
    poll();
  }
  
  stop() {
    if (this.timer) {
      clearTimeout(this.timer);
      this.timer = null;
    }
  }
}

// Usage
const poller = new AdaptivePoller();
poller.start(fetchPendingNotifications);

Best Practices

Use WebSockets When Possible: Prefer WebSocket connections for real-time updates when available
Efficient Polling: Implement adaptive polling to reduce server load and battery consumption
Use Pagination: Always handle pagination correctly to retrieve all notifications
Cache Results: Cache notification data to reduce redundant API calls
Batch Operations: Use the bulk acknowledge endpoint for marking multiple notifications
Error Handling: Implement proper error handling and retries for network failures

Documentation Index

​Overview

​Fetch Pending Notifications

​Query Parameters

​Response

​Error Responses

​Fetch Single Notification

​Path Parameters

​Response

​Error Responses

​Acknowledge Notification

​Path Parameters

​Response

​Error Responses

​Examples

​Fetch Pending Notifications - JavaScript

​Fetch Pending Notifications - Python

​Acknowledge Notification - JavaScript

​Polling Strategy

​Example Adaptive Polling Strategy

​Best Practices

Overview

Fetch Pending Notifications

Query Parameters

Response

Error Responses

Fetch Single Notification

Path Parameters

Response

Error Responses

Acknowledge Notification

Path Parameters

Response

Error Responses

Examples

Fetch Pending Notifications - JavaScript

Fetch Pending Notifications - Python

Acknowledge Notification - JavaScript

Polling Strategy

Example Adaptive Polling Strategy

Best Practices