The Events API provides real-time updates about backup operations, volume mounts, and other system activities through Server-Sent Events (SSE). This allows your application to receive live progress updates without polling.
Connect to event stream Authentication is required. The session cookie must be included with the request.
Request Opens an SSE connection that streams real-time events.
Example curl -N -H "Cookie: session=your_session_cookie" \ http://localhost:4096/api/v1/events
Event types The server broadcasts the following event types:
Connection events connected{ "type" : "connected" , "timestamp" : 1709561234567 }
heartbeat{ "timestamp" : 1709561234567 }
Backup events backup:started{ "organizationId" : "org_123" , "scheduleId" : "sched_abc" , "volumeId" : 1 , "repositoryId" : "repo_xyz" , "timestamp" : 1709561234567 }
backup:progress{ "organizationId" : "org_123" , "scheduleId" : "sched_abc" , "filesProcessed" : 1250 , "bytesProcessed" : 52428800 , "totalFiles" : 5000 , "percentComplete" : 25.5 , "currentFile" : "/data/documents/report.pdf" , "timestamp" : 1709561234567 }
backup:completed{ "organizationId" : "org_123" , "scheduleId" : "sched_abc" , "status" : "success" , "filesProcessed" : 5000 , "bytesProcessed" : 209715200 , "duration" : 3600000 , "snapshotId" : "a1b2c3d4" , "timestamp" : 1709561234567 }
Volume events volume:mounted{ "organizationId" : "org_123" , "volumeId" : 1 , "volumeName" : "Production Data" , "timestamp" : 1709561234567 }
volume:unmounted{ "organizationId" : "org_123" , "volumeId" : 1 , "volumeName" : "Production Data" , "timestamp" : 1709561234567 }
volume:updated{ "organizationId" : "org_123" , "volumeId" : 1 , "timestamp" : 1709561234567 }
Mirror events mirror:started{ "organizationId" : "org_123" , "scheduleId" : "sched_abc" , "sourceRepositoryId" : "repo_source" , "targetRepositoryId" : "repo_target" , "timestamp" : 1709561234567 }
mirror:completed{ "organizationId" : "org_123" , "scheduleId" : "sched_abc" , "status" : "success" , "snapshotsCopied" : 10 , "timestamp" : 1709561234567 }
Restore events restore:started{ "organizationId" : "org_123" , "repositoryId" : "repo_xyz" , "snapshotId" : "a1b2c3d4" , "timestamp" : 1709561234567 }
restore:progress{ "organizationId" : "org_123" , "filesRestored" : 500 , "bytesRestored" : 20971520 , "percentComplete" : 15.5 , "timestamp" : 1709561234567 }
restore:completed{ "organizationId" : "org_123" , "filesRestored" : 3000 , "bytesRestored" : 125829120 , "duration" : 1800000 , "status" : "success" , "timestamp" : 1709561234567 }
Dump events dump:started{ "organizationId" : "org_123" , "repositoryId" : "repo_xyz" , "snapshotId" : "a1b2c3d4" , "timestamp" : 1709561234567 }
Doctor events doctor:started{ "organizationId" : "org_123" , "repositoryId" : "repo_xyz" , "operation" : "check" , "timestamp" : 1709561234567 }
doctor:completed{ "organizationId" : "org_123" , "repositoryId" : "repo_xyz" , "status" : "success" , "errors" : [], "timestamp" : 1709561234567 }
doctor:cancelled{ "organizationId" : "org_123" , "repositoryId" : "repo_xyz" , "timestamp" : 1709561234567 }
Organization scoping All events are scoped to your organization. You will only receive events for resources belonging to your active organization. Events from other organizations are automatically filtered out.
Implementation example JavaScript/TypeScript const eventSource = new EventSource ( '/api/v1/events' , { withCredentials: true }); // Connection established eventSource . addEventListener ( 'connected' , ( event ) => { const data = JSON . parse ( event . data ); console . log ( 'Connected at:' , new Date ( data . timestamp )); }); // Backup progress eventSource . addEventListener ( 'backup:progress' , ( event ) => { const data = JSON . parse ( event . data ); console . log ( `Backup progress: ${ data . percentComplete . toFixed ( 1 ) } %` ); console . log ( `Processing: ${ data . currentFile } ` ); }); // Backup completed eventSource . addEventListener ( 'backup:completed' , ( event ) => { const data = JSON . parse ( event . data ); console . log ( `Backup ${ data . status } : ${ data . filesProcessed } files, ${ data . bytesProcessed } bytes` ); }); // Handle errors eventSource . onerror = ( error ) => { console . error ( 'SSE connection error:' , error ); eventSource . close (); };
React example import { useEffect , useState } from 'react' ; function BackupMonitor () { const [ backupProgress , setBackupProgress ] = useState ( null ); useEffect (() => { const eventSource = new EventSource ( '/api/v1/events' , { withCredentials: true }); eventSource . addEventListener ( 'backup:progress' , ( event ) => { const data = JSON . parse ( event . data ); setBackupProgress ( data ); }); eventSource . addEventListener ( 'backup:completed' , ( event ) => { const data = JSON . parse ( event . data ); console . log ( 'Backup completed:' , data ); setBackupProgress ( null ); }); return () => { eventSource . close (); }; }, []); return ( < div > { backupProgress && ( < div > < div > Progress: { backupProgress . percentComplete . toFixed ( 1 ) } % </ div > < div > Files: { backupProgress . filesProcessed } / { backupProgress . totalFiles } </ div > < div > Current: { backupProgress . currentFile } </ div > </ div > ) } </ div > ); }
Connection management
The server sends a heartbeat event every 5 seconds to keep the connection alive
Connections are automatically closed when the client disconnects or the session expires
Implement reconnection logic in your client to handle network interruptions
Each client only receives events for their own organization
Notes The Events API requires an active authenticated session. Unauthenticated requests will be rejected.
Use the Events API to build real-time dashboards that show backup progress, system status, and operation history without polling.
Backups Manage backup schedules
Repositories Repository operations
