• Register

Events API

The Events API lets your application learn about activity in Egnyte. This means you can find out what has happened since a given moment in time, letting your application respond or react to activity. Currently, this API is limited to file system and notes activity. We will progressively add more event types. If you have a need for a specific event type, please email api-support@egnyte.com to tell us about your use case.

Note: the event stream exposed by this Events API stores the latest 500,000 events, up to a maximum of 30 days. Older events are not accessible via this API.

Polling

Our Events API supports polling for changes based on a cursor which indicates a position in the sequence of events that have occurred on your domain. The cursor is a monotonically increasing number that is associated with each event recorded in our global event store. To watch for events, you should get a cursor and periodically poll for new events which have occurred after that event's cursor.

Getting a Cursor

To initially get a cursor, you should query the cursor endpoint.

GET/pubapi/v1/events/cursor
Request Examples
GET /pubapi/v1/events/cursor HTTP/1.1
Host: apidemo.egnyte.com
Authorization: Bearer 68zc95e3xv954u6k3hbnma3q
curl -v -H "Authorization: Bearer 68zc95e3xv954u6k3hbnma3q" \
https://apidemo.egnyte.com/pubapi/v1/events/cursor
Sample Response Body
{
  "timestamp":"2020-03-17T23:49:31.000Z",
  "latest_event_id":3529,
  "oldest_event_id":3292
}
Response Parameters
Element Description
timestamp The ISO-8601 formatted timestamp associated with the latest event.
latest_event_id The latest event ID available. Most likely, you will want to update your cursor to this value for future calls.
oldest_event_id The oldest event ID available.

Listing Subsequent Events (version 1)

You should query this endpoint to find what events have occurred after a given cursor.

  • When periodically polling this endpoint, please use an interval of 5 minutes or more.
  • If your cursor is less than the oldest cursor value, you will only receive the events since the oldest cursor value we have.
  • If you receive a 204 response, there were no events to return after the cursor provided for this user access token.
GET/pubapi/v1/events?id={cursor_id}
Request Examples
GET /pubapi/v1/events?id=3529 HTTP/1.1
Host: apidemo.egnyte.com
Authorization: Bearer 68zc95e3xv954u6k3hbnma3q
curl -v -H "Authorization: Bearer 68zc95e3xv954u6k3hbnma3q" \
https://apidemo.egnyte.com/pubapi/v1/events?id=3530
Sample Response Body
{
  "count":1,
  "events":[{
    "id":3530,
    "timestamp":"2020-03-19T01:55:51.000Z",
    "actor":9967960066,
    "type":"file_system",
    "action":"delete",
    "data":{
      "target_path":"/Shared/Documents/report.docx",
      "is_folder":false
    },
    "action_source":"PublicAPI"
  }],
  "latest_id":3530,
  "oldest_id":3530
}
Request Parameters
Parameter Description Required
id Generally, this should be the cursor related to the latest event you have seen during previous calls to the Events API. You will receive events that occurred after the event associated with this cursor. Yes
folder You can optionally scope requests to a given folder. When this parameter is specified, we will return events that have occurred at this path (including events inside subfolders). Please note, events are not guaranteed to move with a folder, meaning you will not receive events on a folder that occurred before it was moved. No
suppress This parameter is used to filter out events generated by the current application or current user. Allowed values are: app, user, or none (default). No
type Limit the result set to only items of a certain type. Currently, this endpoint supports the "file_system" and "note" types by default and "permission_change" type if it is explicitly requested. To get multiple event types, you can use a pipe ("|") character to delimit them. For example "file_system|note" would return both file_system and note event types but no others. No
count The maximum number of events to return per page (min 1, default 50, max 100) No
reverse This parameter allows traversing of events in reverse for easier computation.  This is active when reverse = "1" and ignored when reverse = "0".  Response should contain events with ids: (id - count + 1).   No
Response Parameters
Element Description
count The number of results returned.
events A JSON array of event objects.
id The ID of an individual event.
timestamp The ISO-8601 formatted timestamp for when this event was recorded.
actor The numeric ID of the user who performed that action.
type The type of event being reported. Currently, we support the following event types: file_system, note.
action The action associated with this event. Currently, this can be: create, delete, restore, move, copy and rename (represented as "move").
data This field contains additional data specific to the event type and action.
action_source The source of the event. Examples include "WebUI," "SyncEngine," "Mobile," "PublicAPI", "WebEdit", "System", "VPC", "Other".  "Other" encompasses the following actions: FTP, AD_KIT, EGD, OUTLOOK, GDRIVE_INTEG, SALESFORCE, MALWARE_DETECTION, TRASH_CLEANUP, BULK_IMPORT, UNKNOWN. 
latest_id The latest event ID returned in this event set. Most likely, you will want to update your cursor to this value for future calls.

Listing Subsequent Events (version 2)

Note this endpoint is exactly the same as v1 except that it added the "permission_change" type.  Therefore, by default all v2/events calls will return this type; whereas, calls to v1 endpoint should only expect events of type "file_system" and "note". 

You should query this endpoint to find what events have occurred after a given cursor.

  • When periodically polling this endpoint, please use an interval of 5 minutes or more.
  • If your cursor is less than the oldest cursor value, you will only receive the events since the oldest cursor value we have.
  • If you receive a 204 response, there were no events to return after the cursor provided for this user access token.
GET/pubapi/v2/events?id={cursor_id}
Request Examples
GET /pubapi/v2/events?id=3530 HTTP/1.1
Host: apidemo.egnyte.com
Authorization: Bearer 68zc95e3xv954u6k3hbnma3q
curl -v -H "Authorization: Bearer 68zc95e3xv954u6k3hbnma3q" \
https://apidemo.egnyte.com/pubapi/v2/events?id=3531
Sample Response Body
{  
   "count":1,  
   "events":[{      
      "data": {        
  "is_folder": false,        
  "target_path": "/Shared/Documents"      
      },      
      "action_source": "WebUI",      
      "action": "permission_change",      
      "id": 3531,      
      "actor": 9967960066,      
      "timestamp": "2020-03-19T02:04:01.000Z",      
      "eventTypeSpecificAttributes": {        
   "changeGroupEvents": [],        
   "changePermissionEvent": {          
      "changedPermissions": [
         {
     "entry": {                
       "priv": "READWRITE",                
       "subject": "/user/13"
           },              
           "action": "ADD"
         },            
         {              
           "entry": {                
       "priv": "MODIFY",                
       "subject": "/user/13"              
           },              
     "action": "DELETE"            
         }     
     ]        
  }      
     },      
     "type": "permission_change"    
    }],  
   "latest_id":3531,
   "oldest_id":3531
}
Request Parameters
ParameterDescriptionRequired
id Generally, this should be the cursor related to the latest event you have seen during previous calls to the Events API. You will receive events that occurred after the event associated with this cursor. Yes
folder You can optionally scope requests to a given folder. When this parameter is specified, we will return events that have occurred at this path (including events inside subfolders). Please note, events are not guaranteed to move with a folder, meaning you will not receive events on a folder that occurred before it was moved. No
suppress This parameter is used to filter out events generated by the current application or current user. Allowed values are: app, user, or none (default). No
type Limit the result set to only items of a certain type. Currently, this new endpoint only supports the "file_system", "note", and "permission_change" types. To get multiple event types, you can use a pipe ("|") character to delimit them. For example "file_system|note" would return both file_system and note event types but no others. No
count The maximum number of events to return per page (min 1, default 50, max 100) No
reverse This parameter allows traversing of events in reverse for easier computation.  This is active when reverse = "1" and ignored when reverse = "0".  Response should contain events with ids: (id - count + 1).   No
Response Parameters
ElementDescription
count The number of results returned.
events A JSON array of event objects.  Note specifically that permission_change events will contain a "data" field with "is_folder".  The "is_folder" is referring to whether the event is a folder_event, which will always be false and does not refer to whether the target_path is a folder, which it must always be.
id The ID of an individual event.
timestamp The ISO-8601 formatted timestamp for when this event was recorded.
actor The numeric ID of the user who performed that action.
type The type of event being reported. Currently, we support the following event types: file_system, note.
action The action associated with this event. Currently, this can be: create, delete, restore, move, copy and rename (represented as "move").
data This field contains additional data specific to the event type and action.
action_source The source of the event. Examples include "WebUI," "SyncEngine," "Mobile," "PublicAPI", "WebEdit", "System", "VPC", "Other".  "Other" encompasses the following actions: FTP, AD_KIT, EGD, OUTLOOK, GDRIVE_INTEG, SALESFORCE, MALWARE_DETECTION, TRASH_CLEANUP, BULK_IMPORT, UNKNOWN. 
latest_id The latest event ID returned in this event set. Most likely, you will want to update your cursor to this value for future calls.

version 28 as of 3 years ago by Vitaly Obernikhin