Overview

The Server-Sent Events (SSE) endpoint provides an alternative method for real-time notification delivery using HTTP-based server-push technology. This approach is beneficial for clients that cannot maintain WebSocket connections due to proxy limitations or require a simpler implementation.

Connection

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

Connection Query Parameters

Parameter	Type	Required	Description
`token`	string	Yes	User authentication token (alternative to Authorization header)
`last_event_id`	string	No	ID of the last received event for reconnection purposes
`types`	string	No	Comma-separated list of event types to subscribe to (default: all)
`client_id`	string	No	Client identifier for correlation (UUID recommended)
`version`	string	No	Protocol version for compatibility (defaults to latest)

Connection Example

// Create EventSource connection to SSE endpoint
const eventSource = new EventSource('https://atp.example.com/api/v1/client/events?token=user_token_xyz789');

// Handle connection open
eventSource.onopen = () => {
  console.log('Connected to ATP notification stream via SSE');
};

// Handle notification events
eventSource.addEventListener('notification', (event) => {
  const notification = JSON.parse(event.data);
  console.log('Received notification:', notification);
  
  // Store last event ID for reconnection
  if (event.lastEventId) {
    localStorage.setItem('last_event_id', event.lastEventId);
  }
  
  // Process notification
  handleNotification(notification);
});

// Handle status update events
eventSource.addEventListener('status_update', (event) => {
  const statusUpdate = JSON.parse(event.data);
  console.log('Status update:', statusUpdate);
  handleStatusUpdate(statusUpdate);
});

// Handle connection error
eventSource.onerror = (error) => {
  console.error('SSE connection error:', error);
  
  // Check if the connection was closed
  if (eventSource.readyState === EventSource.CLOSED) {
    console.log('Connection closed. EventSource will automatically attempt to reconnect.');
  }
};

// Function to manually close the connection if needed
function closeConnection() {
  eventSource.close();
  console.log('SSE connection closed manually');
}

Message Format

SSE messages are formatted according to the EventSource specification with event types and JSON data payloads:

event: notification
id: 1622145123-abc123
data: {"id":"550e8400-e29b-41d4-a716-446655440000","version":"1.0",...}

Event Types

The following event types are supported:

Event Type	Description
`notification`	New notification available for the user
`status_update`	Status change for an existing notification
`error`	Error condition related to the connection
`ping`	Server heartbeat to maintain connection

Event Data Formats

Notification Event

{
  "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 Update Event

{
  "notification_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "invalidated",
  "reason": "The deployment was canceled by the system",
  "timestamp": "2025-05-25T10:32:15Z"
}

Error Event

{
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Client has exceeded connection rate limit",
  "request_id": "req_abc123def456"
}

Ping Event

{
  "timestamp": "2025-05-25T10:31:00Z"
}

Reconnection

One of the key advantages of Server-Sent Events is the built-in reconnection mechanism provided by the browser’s EventSource implementation. When a connection is lost, the browser will automatically attempt to reconnect with exponential backoff. The SSE protocol uses the Last-Event-ID header for resuming the stream from where it left off. When reconnecting, the client should include the last received event ID to ensure no events are missed:

// Store last event ID when receiving events
eventSource.addEventListener('notification', (event) => {
  if (event.lastEventId) {
    localStorage.setItem('last_event_id', event.lastEventId);
  }
  // Process event...
});

// When manually reconnecting, include the last event ID
function reconnect() {
  const lastEventId = localStorage.getItem('last_event_id');
  const url = `https://atp.example.com/api/v1/client/events?token=user_token_xyz789`;
  
  if (lastEventId) {
    url += `&last_event_id=${lastEventId}`;
  }
  
  if (eventSource) {
    eventSource.close();
  }
  
  eventSource = new EventSource(url);
  // Set up event listeners again...
}

Custom Reconnection Strategy

For applications that need more control over the reconnection behavior, you can implement a custom strategy:

function connectWithCustomReconnect() {
  const MAX_RETRIES = 10;
  const BASE_DELAY_MS = 1000;
  let retryCount = 0;
  let eventSource = null;
  
  function connect() {
    const lastEventId = localStorage.getItem('last_event_id');
    let url = `https://atp.example.com/api/v1/client/events?token=user_token_xyz789`;
    
    if (lastEventId) {
      url += `&last_event_id=${lastEventId}`;
    }
    
    // Close existing connection if any
    if (eventSource) {
      eventSource.close();
    }
    
    // Create new connection
    eventSource = new EventSource(url);
    
    eventSource.onopen = () => {
      console.log('Connected to ATP notification stream via SSE');
      retryCount = 0; // Reset retry counter on successful connection
    };
    
    // Set up event listeners...
    
    eventSource.onerror = (error) => {
      console.error('SSE connection error:', error);
      
      // Only handle closed connections
      if (eventSource.readyState === EventSource.CLOSED) {
        if (retryCount < MAX_RETRIES) {
          // Calculate delay with exponential backoff and jitter
          const delay = Math.min(
            BASE_DELAY_MS * Math.pow(2, retryCount) + Math.random() * 1000, 
            60000 // Cap at 60 seconds
          );
          
          console.log(`Connection closed. Retrying in ${delay}ms...`);
          retryCount++;
          setTimeout(connect, delay);
        } else {
          console.error('Maximum retry attempts reached. Giving up.');
        }
      }
    };
  }
  
  connect();
  
  // Return control functions
  return {
    close: () => {
      if (eventSource) {
        eventSource.close();
      }
    },
    reconnect: () => {
      retryCount = 0;
      connect();
    }
  };
}

const connection = connectWithCustomReconnect();

Limitations

Maximum of 10 concurrent SSE connections per user
Connection timeout: 120 seconds of inactivity
Reconnection delay: Controlled by client with server-suggested 3-second initial delay
Maximum event size: 512KB

Browser Compatibility

Server-Sent Events are supported in all modern browsers:

Chrome 6+
Firefox 6+
Safari 5+
Edge 79+
Opera 11.5+

For older browsers or environments without native EventSource support, polyfills are available.

Advantages Over WebSockets

While WebSockets provide bidirectional communication, SSE offers several advantages for notification delivery:

Simpler Implementation: No need to handle message framing or connection state
Automatic Reconnection: Built-in reconnection with message resumption
Better Proxy Support: Works over standard HTTP, avoiding firewall/proxy issues
Event Filtering: Subscribe to specific event types
Less Overhead: Lower connection maintenance overhead for unidirectional communication

Best Practices

Store Last Event ID: Always persist the last event ID for reliable reconnection
Handle Backpressure: Process events asynchronously to avoid blocking the event stream
Implement Timeout Handling: Close and reconnect if no events are received within the expected interval
Graceful Degradation: Fall back to polling if SSE is not supported or continuously fails
Connection Monitoring: Track connection state and implement health checks
Memory Management: Close EventSource when component is unmounted to prevent memory leaks

Overview

Services

Clients

Server-Sent Events

Overview

Connection

Connection Query Parameters

Connection Example

Message Format

Event Types

Event Data Formats

Notification Event

Status Update Event

Error Event

Ping Event

Reconnection

Custom Reconnection Strategy

Limitations

Browser Compatibility

Advantages Over WebSockets

Best Practices

Overview

Services

Clients

​Overview

​Connection

​Connection Query Parameters

​Connection Example

​Message Format

​Event Types

​Event Data Formats

​Notification Event

​Status Update Event

​Error Event

​Ping Event

​Reconnection

​Custom Reconnection Strategy

​Limitations

​Browser Compatibility

​Advantages Over WebSockets

​Best Practices

Overview

Connection

Connection Query Parameters

Connection Example

Message Format

Event Types

Event Data Formats

Notification Event

Status Update Event

Error Event

Ping Event

Reconnection

Custom Reconnection Strategy

Limitations

Browser Compatibility

Advantages Over WebSockets

Best Practices