Box Events API

openapi: 3.1.0
info:
  version: "1.0"
  title: Box Authorize Authorization Events API
  description: Needs a description.
tags:
- name: Events
  description: 'Events provide a way for an

    application to subscribe to

    any actions performed by

    any user, users, or service in an enterprise.'
  x-box-tag: events
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\n\n* `all` returns everything for a user and is the default\n* `changes` returns events that may cause file tree changes\n  such as file updates or collaborations.\n* `sync` is similar to `changes` but only applies to synced folders\n* `admin_logs` returns all events for an entire enterprise and\n  requires the user making the API call to have admin permissions. This\n  stream type is for programmatically pulling from a 1 year history of\n  events across all users within the enterprise and within a\n  `created_after` and `created_before` time frame. The complete history\n  of events will be returned in chronological order based on the event\n  time, but latency will be much higher than `admin_logs_streaming`.\n* `admin_logs_streaming` returns all events for an entire enterprise and\n  requires the user making the API call to have admin permissions. This\n  stream type is for polling for recent events across all users within\n  the enterprise. Latency will be much lower than `admin_logs`, but\n  events will not be returned in chronological order and may\n  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:
    Folder:
      title: Folder
      type: object
      x-box-resource-id: folder
      x-box-variant: standard
      description: 'A standard representation of a folder, as returned from any

        folder API endpoints by default'
      allOf:
      - $ref: '#/components/schemas/Folder--Mini'
      - properties:
          created_at:
            type: string
            format: date-time
            nullable: true
            description: 'The date and time when the folder was created. This value may

              be `null` for some folders such as the root folder or the trash

              folder.'
            example: '2012-12-12T10:53:43-08:00'
          modified_at:
            type: string
            format: date-time
            description: 'The date and time when the folder was last updated. This value may

              be `null` for some folders such as the root folder or the trash

              folder.'
            example: '2012-12-12T10:53:43-08:00'
            nullable: true
          description:
            allOf:
            - type: string
              description: The optional description of this folder
              maxLength: 256
              example: Legal contracts for the new ACME deal
              nullable: false
            - nullable: false
          size:
            type: integer
            format: int64
            description: 'The folder size in bytes.


              Be careful parsing this integer as its

              value can get very large.'
            example: 629644
            nullable: false
          path_collection:
            allOf:
            - title: Path collection
              description: A list of parent folders for an item.
              type: object
              required:
              - total_count
              - entries
              properties:
                total_count:
                  description: The number of folders in this list.
                  example: 1
                  type: integer
                  format: int64
                  nullable: false
                entries:
                  type: array
                  description: The parent folders for this item
                  nullable: false
                  items:
                    $ref: '#/components/schemas/Folder--Mini'
            - description: 'The tree of folders that this folder is contained in,

                starting at the root.'
            - nullable: false
          created_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who created this folder
            - nullable: false
          modified_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who last modified this folder.
            - nullable: false
          trashed_at:
            type: string
            format: date-time
            description: The time at which this folder was put in the trash.
            example: '2012-12-12T10:53:43-08:00'
            nullable: true
          purged_at:
            type: string
            format: date-time
            description: 'The time at which this folder is expected to be purged

              from the trash.'
            example: '2012-12-12T10:53:43-08:00'
            nullable: true
          content_created_at:
            type: string
            format: date-time
            nullable: true
            description: 'The date and time at which this folder was originally

              created.'
            example: '2012-12-12T10:53:43-08:00'
          content_modified_at:
            type: string
            format: date-time
            nullable: true
            description: The date and time at which this folder was last updated.
            example: '2012-12-12T10:53:43-08:00'
          owned_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who owns this folder.
            - nullable: false
          shared_link:
            allOf:
            - title: Shared link
              description: 'Shared links provide direct, read-only access to files or folder on Box.


                Shared links with open access level allow anyone with the URL

                to access the item, while shared links with company or collaborators access

                levels can only be accessed by appropriately authenticated Box users.'
              type: object
              required:
              - url
              - accessed
              - effective_access
              - effective_permission
              - is_password_enabled
              - download_count
              - preview_count
              properties:
                url:
                  type: string
                  format: url
                  description: 'The URL that can be used to access the item on Box.


                    This URL will display the item in Box''s preview UI where the file

                    can be downloaded if allowed.


                    This URL will continue to work even when a custom `vanity_url`

                    has been set for this shared link.'
                  example: https://www.box.com/s/vspke7y05sb214wjokpk
                  nullable: false
                download_url:
                  type: string
                  format: url
                  x-box-premium-feature: true
                  description: 'A URL that can be used to download the file. This URL can be used in

                    a browser to download the file. This URL includes the file

                    extension so that the file will be saved with the right file type.


                    This property will be `null` for folders.'
                  example: https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg
                  nullable: true
                vanity_url:
                  type: string
                  format: url
                  description: 'The "Custom URL" that can also be used to preview the item on Box.  Custom

                    URLs can only be created or modified in the Box Web application.'
                  example: https://acme.app.box.com/v/my_url/
                  nullable: true
                vanity_name:
                  type: string
                  description: The custom name of a shared link, as used in the `vanity_url` field.
                  example: my_url
                  nullable: true
                access:
                  type: string
                  description: "The access level for this shared link.\n\n* `open` - provides access to this item to anyone with this link\n* `company` - only provides access to this item to people the same company\n* `collaborators` - only provides access to this item to people who are\n   collaborators on this item\n\nIf this field is omitted when creating the shared link, the access level\nwill be set to the default access level specified by the enterprise admin."
                  enum:
                  - open
                  - company
                  - collaborators
                  example: open
                  nullable: false
                effective_access:
                  type: string
                  description: 'The effective access level for the shared link. This can be a more

                    restrictive access level than the value in the `access` field when the

                    enterprise settings restrict the allowed access levels.'
                  enum:
                  - open
                  - company
                  - collaborators
                  example: company
                  nullable: false
                effective_permission:
                  type: string
                  description: 'The effective permissions for this shared link.

                    These result in the more restrictive combination of

                    the share link permissions and the item permissions set

                    by the administrator, the owner, and any ancestor item

                    such as a folder.'
                  enum:
                  - can_edit
                  - can_download
                  - can_preview
                  - no_access
                  example: can_download
                  nullable: false
                unshared_at:
                  type: string
                  format: date-time
                  description: 'The date and time when this link will be unshared. This field can only be

                    set by users with paid accounts.'
                  example: '2018-04-13T13:53:23-07:00'
                  nullable: true
                is_password_enabled:
                  type: boolean
                  description: Defines if the shared link requires a password to access the item.
                  example: true
                  nullable: false
                permissions:
                  type: object
                  description: 'Defines if this link allows a user to preview, edit, and download an item.

                    These permissions refer to the shared link only and

                    do not supersede permissions applied to the item itself.'
                  required:
                  - can_download
                  - can_preview
                  - can_edit
                  properties:
                    can_download:
                      type: boolean
                      example: true
                      nullable: false
                      description: 'Defines if the shared link allows for the item to be downloaded. For

                        shared links on folders, this also applies to any items in the folder.


                        This value can be set to `true` when the effective access level is

                        set to `open` or `company`, not `collaborators`.'
                    can_preview:
                      type: boolean
                      example: true
                      nullable: false
                      description: 'Defines if the shared link allows for the item to be previewed.


                        This value is always `true`. For shared links on folders this also

                        applies to any items in the folder.'
                    can_edit:
                      type: boolean
                      example: false
                      nullable: false
                      description: 'Defines if the shared link allows for the item to be edited.


                        This value can only be `true` if `can_download` is also `true` and if

                        the item has a type of `file`.'
                download_count:
                  type: integer
                  example: 3
                  description: The number of times this item has been downloaded.
                  nullable: false
                preview_count:
                  type: integer
                  example: 3
                  description: The number of times this item has been previewed.
                  nullable: false
            - description: 'The shared link for this folder. This will be

                `null` if no shared link has been created for this

                folder.'
            nullable: true
          folder_upload_email:
            type: object
            nullable: true
            properties:
              access:
                type: string
                example: open
                nullable: false
                enum:
                - open
                - collaborators
                description: 'When this parameter has been set, users can email files

                  to the email address that has been automatically

                  created for this folder.


                  To create an email address, set this property either when

                  creating or updating the folder.


                  When set to `collaborators`, only emails from registered email

                  addresses for collaborators will be accepted. This includes

                  any email aliases a user might have registered.


                  When set to `open` it will accept emails from any email

                  address.'
              email:
                description: The optional upload email address for this folder.
                type: string
                format: email
                example: upload.Contracts.asd7asd@u.box.com
                nullable: false
          parent:
            allOf:
            - $ref: '#/components/schemas/Folder--Mini'
            - description: 'The optional folder that this folder is located within.


                This value may be `null` for some folders such as the

                root folder or the trash folder.'
            nullable: true
          item_status:
            type: string
            description: 'Defines if this item has been deleted or not.


              * `active` when the item has is not in the trash

              * `trashed` when the item has been moved to the trash but not deleted

              * `deleted` when the item has been permanently deleted.'
            enum:
            - active
            - trashed
            - deleted
            nullable: false
            example: active
          item_collection:
            allOf:
            - $ref: '#/components/schemas/Items'
            - description: 'A page of the items that are in the folder.


                This field can only be requested when querying a folder''s

                information, not when querying a folder''s items.'
            - nullable: false
    File:
      title: File
      type: object
      x-box-resource-id: file
      x-box-variant: standard
      description: 'A standard representation of a file, as returned from any

        file API endpoints by default'
      allOf:
      - $ref: '#/components/schemas/File--Mini'
      - properties:
          description:
            type: string
            nullable: false
            description: The optional description of this file
            maxLength: 256
            example: Contract for Q1 renewal
          size:
            type: integer
            nullable: false
            description: 'The file size in bytes. Be careful parsing this integer as it can

              get very large and cause an integer overflow.'
            example: 629644
          path_collection:
            allOf:
            - title: Path collection
              description: A list of parent folders for an item.
              type: object
              required:
              - total_count
              - entries
              properties:
                total_count:
                  description: The number of folders in this list.
                  example: 1
                  type: integer
                  format: int64
                  nullable: false
                entries:
                  type: array
                  description: The parent folders for this item
                  nullable: false
                  items:
                    $ref: '#/components/schemas/Folder--Mini'
            - description: 'The tree of folders that this file is contained in,

                starting at the root.'
            - nullable: false
          created_at:
            type: string
            format: date-time
            nullable: false
            description: The date and time when the file was created on Box.
            example: '2012-12-12T10:53:43-08:00'
          modified_at:
            type: string
            format: date-time
            nullable: false
            description: The date and time when the file was last updated on Box.
            example: '2012-12-12T10:53:43-08:00'
          trashed_at:
            type: string
            format: date-time
            description: The time at which this file was put in the trash.
            example: '2012-12-12T10:53:43-08:00'
            nullable: true
          purged_at:
            type: string
            format: date-time
            description: 'The time at which this file is expected to be purged

              from the trash.'
            example: '2012-12-12T10:53:43-08:00'
            nullable: true
          content_created_at:
            type: string
            format: date-time
            nullable: true
            description: 'The date and time at which this file was originally

              created, which might be before it was uploaded to Box.'
            example: '2012-12-12T10:53:43-08:00'
          content_modified_at:
            type: string
            format: date-time
            nullable: true
            description: 'The date and time at which this file was last updated,

              which might be before it was uploaded to Box.'
            example: '2012-12-12T10:53:43-08:00'
          created_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who created this file
          modified_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who last modified this file
            - nullable: false
          owned_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who owns this file
            - nullable: false
          shared_link:
            allOf:
            - title: Shared link
              description: 'Shared links provide direct, read-only access to files or folder on Box.


                Shared links with open access level allow anyone with the URL

                to access the item, while shared links with company or collaborators access

                levels can only be accessed by appropriately authenticated Box users.'
              type: object
              required:
              - url
              - accessed
              - effective_access
              - effective_permission
              - is_password_enabled
              - download_count
              - preview_count
              properties:
                url:
                  type: string
                  format: url
                  description: 'The URL that can be used to access the item on Box.


                    This URL will display the item in Box''s preview UI where the file

                    can be downloaded if allowed.


                    This URL will continue to work even when a custom `vanity_url`

                    has been set for this shared link.'
                  example: https://www.box.com/s/vspke7y05sb214wjokpk
                  nullable: false
                download_url:
                  type: string
                  format: url
                  x-box-premium-feature: true
                  description: 'A URL that can be used to download the file. This URL can be used in

                    a browser to download the file. This URL includes the file

                    extension so that the file will be saved with the right file type.


                    This property will be `null` for folders.'
                  example: https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg
                  nullable: true
                vanity_url:
                  type: string
                  format: url
                  description: 'The "Custom URL" that can also be used to preview the item on Box.  Custom

                    URLs can only be created or modified in the Box Web application.'
                  example: https://acme.app.box.com/v/my_url/
                  nullable: true
                vanity_name:
                  type: string
                  description: The custom name of a shared link, as used in the `vanity_url` field.
                  example: my_url
                  nullable: true
                access:
                  type: string
                  description: "The access level for this shared link.\n\n* `open` - provides access to this item to anyone with this link\n* `company` - only provides access to this item to people the same company\n* `collaborators` - only provides access to this item to people who are\n   collaborators on this item\n\nIf this field is omitted when creating the shared link, the access level\nwill be set to the default access level specified by the enterprise admin."
                  enum:
                  - open
                  - company
                  - collaborators
                  example: open
                  nullable: false
                effective_access:
                  type: string
                  description: 'The

# --- truncated at 32 KB (102 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/box/refs/heads/main/openapi/box-events-api-openapi.yml