openapi: 3.1.0 info: title: Box Events API description: Needs a description. paths: /events: options: operationId: options_events summary: Box Get events long poll endpoint tags: - Events x-box-tag: events description: >- Returns a list of real-time servers that can be used for long-polling updates to the [event stream](#get-events). Long polling is the concept where a HTTP request is kept open until the server sends a response, then repeating the process over and over to receive updated responses. Long polling the event stream can only be used for user events, not for enterprise events. To use long polling, first use this endpoint to retrieve a list of long poll URLs. Next, make a long poll request to any of the provided URLs. When an event occurs in monitored account a response with the value `new_change` will be sent. The response contains no other details as it only serves as a prompt to take further action such as sending a request to the [events endpoint](#get-events) with the last known `stream_position`. After the server sends this response it closes the connection. You must now repeat the long poll process to begin listening for events again. If no events occur for a while and the connection times out you will receive a response with the value `reconnect`. When you receive this response you’ll make another call to this endpoint to restart the process. If you receive no events in `retry_timeout` seconds then you will need to make another request to the real-time server (one of the URLs in the response for this endpoint). This might be necessary due to network errors. Finally, if you receive a `max_retries` error when making a request to the real-time server, you should start over by making a call to this endpoint first. responses: '200': description: |- Returns a paginated array of servers that can be used instead of the regular endpoints for long-polling events. content: application/json: schema: $ref: '#/components/schemas/RealtimeServers' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' get: operationId: get_events summary: Box List user and enterprise events tags: - Events x-box-tag: events description: >- Returns up to a year of past events for a given user or for the entire enterprise. By default this returns events for the authenticated user. To retrieve events for the entire enterprise, set the `stream_type` to `admin_logs_streaming` for live monitoring of new events, or `admin_logs` for querying across historical events. The user making the API call will need to have admin privileges, and the application will need to have the scope `manage enterprise properties` checked. parameters: - name: stream_type description: >- Defines the type of events that are returned * `all` returns everything for a user and is the default * `changes` returns events that may cause file tree changes such as file updates or collaborations. * `sync` is similar to `changes` but only applies to synced folders * `admin_logs` returns all events for an entire enterprise and requires the user making the API call to have admin permissions. This stream type is for programmatically pulling from a 1 year history of events across all users within the enterprise and within a `created_after` and `created_before` time frame. The complete history of events will be returned in chronological order based on the event time, but latency will be much higher than `admin_logs_streaming`. * `admin_logs_streaming` returns all events for an entire enterprise and requires the user making the API call to have admin permissions. This stream type is for polling for recent events across all users within the enterprise. Latency will be much lower than `admin_logs`, but events will not be returned in chronological order and may contain duplicates. in: query example: all schema: type: string default: all enum: - all - changes - sync - admin_logs - admin_logs_streaming - name: stream_position description: |- The location in the event stream to start receiving events from. * `now` will return an empty list events and the latest stream position for initialization. * `0` or `null` will return all events. example: '1348790499819' in: query schema: type: string - name: limit description: >- Limits the number of events returned Note: Sometimes, the events less than the limit requested can be returned even when there may be more events remaining. This is primarily done in the case where a number of events have already been retrieved and these retrieved events are returned rather than delaying for an unknown amount of time to see if there are any more results. in: query example: 50 schema: type: integer format: int64 default: 100 maximum: 500 - name: event_type description: >- A comma-separated list of events to filter by. This can only be used when requesting the events with a `stream_type` of `admin_logs` or `adming_logs_streaming`. For any other `stream_type` this value will be ignored. in: query explode: false example: - ACCESS_GRANTED schema: type: array items: type: string description: An event type that can be filtered by enum: - ACCESS_GRANTED - ACCESS_REVOKED - ADD_DEVICE_ASSOCIATION - ADD_LOGIN_ACTIVITY_DEVICE - ADMIN_LOGIN - APPLICATION_CREATED - APPLICATION_PUBLIC_KEY_ADDED - APPLICATION_PUBLIC_KEY_DELETED - CHANGE_ADMIN_ROLE - CHANGE_FOLDER_PERMISSION - COLLABORATION_ACCEPT - COLLABORATION_EXPIRATION - COLLABORATION_INVITE - COLLABORATION_REMOVE - COLLABORATION_ROLE_CHANGE - COMMENT_CREATE - COMMENT_DELETE - CONTENT_WORKFLOW_ABNORMAL_DOWNLOAD_ACTIVITY - CONTENT_WORKFLOW_AUTOMATION_ADD - CONTENT_WORKFLOW_AUTOMATION_DELETE - CONTENT_WORKFLOW_POLICY_ADD - CONTENT_WORKFLOW_SHARING_POLICY_VIOLATION - CONTENT_WORKFLOW_UPLOAD_POLICY_VIOLATION - COPY - DATA_RETENTION_CREATE_RETENTION - DATA_RETENTION_REMOVE_RETENTION - DELETE - DELETE_USER - DEVICE_TRUST_CHECK_FAILED - DOWNLOAD - EDIT - EDIT_USER - EMAIL_ALIAS_CONFIRM - EMAIL_ALIAS_REMOVE - ENTERPRISE_APP_AUTHORIZATION_UPDATE - EXTERNAL_COLLAB_SECURITY_SETTINGS - FAILED_LOGIN - FILE_MARKED_MALICIOUS - FILE_WATERMARKED_DOWNLOAD - GROUP_ADD_ITEM - GROUP_ADD_USER - GROUP_CREATION - GROUP_DELETION - GROUP_EDITED - GROUP_REMOVE_ITEM - GROUP_REMOVE_USER - ITEM_MODIFY - ITEM_OPEN - ITEM_SHARED_UPDATE - ITEM_SYNC - ITEM_UNSYNC - LEGAL_HOLD_ASSIGNMENT_CREATE - LEGAL_HOLD_ASSIGNMENT_DELETE - LEGAL_HOLD_POLICY_CREATE - LEGAL_HOLD_POLICY_DELETE - LEGAL_HOLD_POLICY_UPDATE - LOCK - LOGIN - METADATA_INSTANCE_CREATE - METADATA_INSTANCE_DELETE - METADATA_INSTANCE_UPDATE - METADATA_TEMPLATE_CREATE - METADATA_TEMPLATE_DELETE - METADATA_TEMPLATE_UPDATE - MOVE - NEW_USER - OAUTH2_ACCESS_TOKEN_REVOKE - PREVIEW - REMOVE_DEVICE_ASSOCIATION - REMOVE_LOGIN_ACTIVITY_DEVICE - RENAME - RETENTION_POLICY_ASSIGNMENT_ADD - SHARE - SHARE_EXPIRATION - SHIELD_ALERT - SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED - SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED_MISSING_JUSTIFICATION - SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED - SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED_MISSING_JUSTIFICATION - SHIELD_JUSTIFICATION_APPROVAL - SHIELD_SHARED_LINK_ACCESS_BLOCKED - SHIELD_SHARED_LINK_STATUS_RESTRICTED_ON_CREATE - SHIELD_SHARED_LINK_STATUS_RESTRICTED_ON_UPDATE - SIGN_DOCUMENT_ASSIGNED - SIGN_DOCUMENT_CANCELLED - SIGN_DOCUMENT_COMPLETED - SIGN_DOCUMENT_CONVERTED - SIGN_DOCUMENT_CREATED - SIGN_DOCUMENT_DECLINED - SIGN_DOCUMENT_EXPIRED - SIGN_DOCUMENT_SIGNED - SIGN_DOCUMENT_VIEWED_BY_SIGNED - SIGNER_DOWNLOADED - SIGNER_FORWARDED - STORAGE_EXPIRATION - TASK_ASSIGNMENT_CREATE - TASK_ASSIGNMENT_DELETE - TASK_ASSIGNMENT_UPDATE - TASK_CREATE - TASK_UPDATE - TERMS_OF_SERVICE_ACCEPT - TERMS_OF_SERVICE_REJECT - UNDELETE - UNLOCK - UNSHARE - UPDATE_COLLABORATION_EXPIRATION - UPDATE_SHARE_EXPIRATION - UPLOAD - USER_AUTHENTICATE_OAUTH2_ACCESS_TOKEN_CREATE - WATERMARK_LABEL_CREATE - WATERMARK_LABEL_DELETE - name: created_after description: >- The lower bound date and time to return events for. This can only be used when requesting the events with a `stream_type` of `admin_logs`. For any other `stream_type` this value will be ignored. in: query example: '2012-12-12T10:53:43-08:00' schema: type: string format: date-time - name: created_before description: >- The upper bound date and time to return events for. This can only be used when requesting the events with a `stream_type` of `admin_logs`. For any other `stream_type` this value will be ignored. in: query required: false example: '2013-12-12T10:53:43-08:00' schema: type: string format: date-time responses: '200': description: >- Returns a list of event objects. Events objects are returned in pages, with each page (chunk) including a list of event objects. The response includes a `chunk_size` parameter indicating how many events were returned in this chunk, as well as the next `stream_position` that can be queried. content: application/json: schema: $ref: '#/components/schemas/Events' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' components: schemas: RealtimeServers: title: Real-time servers type: object x-box-resource-id: realtime_servers description: |- A list of real-time servers that can be used for long-polling. x-box-tag: events properties: chunk_size: description: The number of items in this response. example: 1 type: integer format: int64 entries: type: array description: A list of real-time servers items: $ref: '#/components/schemas/RealtimeServer' ClientError: title: Client error type: object x-box-resource-id: client_error description: A generic error properties: type: description: error example: error type: string enum: - error nullable: false status: description: The HTTP status of the response. example: 400 type: integer format: int32 nullable: false code: description: A Box-specific error code example: item_name_invalid type: string enum: - created - accepted - no_content - redirect - not_modified - bad_request - unauthorized - forbidden - not_found - method_not_allowed - conflict - precondition_failed - too_many_requests - internal_server_error - unavailable - item_name_invalid - insufficient_scope message: description: A short message describing the error. example: Method Not Allowed type: string nullable: false context_info: description: |- A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example. type: object nullable: true properties: message: type: string description: More details on the error. example: Something went wrong. help_url: description: A URL that links to more information about why this error occurred. example: >- https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/ type: string nullable: false request_id: description: |- A unique identifier for this response, which can be used when contacting Box support. type: string example: abcdef123456 nullable: false Events: title: Events type: object x-box-resource-id: events x-box-tag: events description: A list of event objects properties: chunk_size: description: The number of events returned in this response. example: 2 type: integer format: int64 next_stream_position: description: |- The stream position of the start of the next page (chunk) of events. example: '1152922976252290886' type: string entries: type: array description: A list of events items: $ref: '#/components/schemas/Event' tags: - name: Events