Box Events API
The Box Events API provides access to user and enterprise event streams, enabling applications to monitor file activity, track audit logs, and receive real-time notifications about actions taken on content in Box.
OpenAPI Specification
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