Box Events API

openapi: 3.2.0
info:
  title: Box Events API
  x-refined-note:
  - x-box-commit-hash differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged Events across 2 of this provider''s published API definitions: box-openapi-original.yml, events-openapi-original.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.box.com/2.0
  description: Box Platform API server
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'
      security:
      - OAuth2Security: []
    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'
      security:
      - OAuth2Security: []
    servers:
    - url: https://api.box.com/2.0
      description: Box Platform API server
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
            - 'null'
            format: date-time
            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
            - 'null'
            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'
          description:
            allOf:
            - type: string
              description: The optional description of this folder
              maxLength: 256
              example: Legal contracts for the new ACME deal
            - {}
          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
          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
                entries:
                  type: array
                  description: The parent folders for this item
                  items:
                    $ref: '#/components/schemas/Folder--Mini'
            - description: 'The tree of folders that this folder is contained in,

                starting at the root.'
            - {}
          created_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who created this folder
            - {}
          modified_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who last modified this folder.
            - {}
          trashed_at:
            type:
            - string
            - 'null'
            format: date-time
            description: The time at which this folder was put in the trash.
            example: '2012-12-12T10:53:43-08:00'
          purged_at:
            type:
            - string
            - 'null'
            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'
          content_created_at:
            type:
            - string
            - 'null'
            format: date-time
            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
            - 'null'
            format: date-time
            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.
            - {}
          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
                download_url:
                  type:
                  - string
                  - 'null'
                  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
                vanity_url:
                  type:
                  - string
                  - 'null'
                  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/
                vanity_name:
                  type:
                  - string
                  - 'null'
                  description: The custom name of a shared link, as used in the `vanity_url` field.
                  example: my_url
                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
                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
                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
                unshared_at:
                  type:
                  - string
                  - 'null'
                  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'
                is_password_enabled:
                  type: boolean
                  description: Defines if the shared link requires a password to access the item.
                  example: true
                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
                      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
                      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
                      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.
                preview_count:
                  type: integer
                  example: 3
                  description: The number of times this item has been previewed.
            - description: 'The shared link for this folder. This will be

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

                folder.'
          folder_upload_email:
            type:
            - object
            - 'null'
            properties:
              access:
                type: string
                example: open
                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
          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.'
          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
            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.'
            - {}
    RealtimeServer:
      title: Real-time server
      type: object
      x-box-resource-id: realtime_server
      description: 'A real-time server that can be used for

        long polling user events'
      properties:
        type:
          description: '`realtime_server`'
          type: string
          example: realtime_server
        url:
          type: string
          example: http://2.realtime.services.box.net/subscribe?channel=cc807c9c4869ffb1c81a&stream_type=all
          description: The URL for the server.
        ttl:
          description: The time in minutes for which this server is available
          type: integer
          example: 10
        max_retries:
          description: 'The maximum number of retries this server will

            allow before a new long poll should be started by

            getting a [new list of server](#options-events).'
          type: integer
          example: 10
        retry_timeout:
          description: 'The maximum number of seconds without a response

            after which you should retry the long poll connection.


            This helps to overcome network issues where the long

            poll looks to be working but no packages are coming

            through.'
          type: integer
          example: 610
    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
        status:
          description: The HTTP status of the response.
          example: 400
          type: integer
          format: int32
        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
        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
          - 'null'
          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
        request_id:
          description: 'A unique identifier for this response, which can be used

            when contacting Box support.'
          type: string
          example: abcdef123456
    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'
    FileVersion--Mini:
      title: File version (Mini)
      type: object
      x-box-resource-id: file_version--mini
      x-box-variant: mini
      description: 'A mini representation of a file version, used when

        nested within another resource.'
      allOf:
      - $ref: '#/components/schemas/FileVersion--Base'
      - properties:
          sha1:
            type: string
            description: The SHA1 hash of this version of the file.
            example: 134b65991ed521fcfe4724b7d814ab8ded5185dc
    FileVersion--Base:
      title: File version (Base)
      type: object
      x-box-resource-id: file_version--base
      x-box-sanitized: true
      x-box-variants:
      - base
      - mini
      - standard
      - full
      x-box-variant: base
      description: 'The bare basic representation of a file version, the minimal

        amount of fields returned when using the `fields` query

        parameter.'
      required:
      - id
      - type
      properties:
        id:
          type: string
          description: The unique identifier that represent a file version.
          example: '12345'
        type:
          type: string
          description: '`file_version`'
          example: file_version
          enum:
          - file_version
    User--Base:
      title: User (Base)
      type: object
      x-box-resource-id: user--base
      x-box-tag: users
      x-box-variants:
      - base
      - mini
      - standard
      - full
      x-box-variant: base
      description: 'A mini representation of a user, used when

        nested within another resource.'
      required:
      - type
      - id
      properties:
        id:
          type: string
          description: The unique identifier for this user
          example: '11446498'
        type:
          type: string
          description: '`user`'
          example: user
          enum:
          - user
    User--Mini:
      title: User (Mini)
      type: object
      x-box-resource-id: user--mini
      x-box-variant: mini
      description: 'A mini representation of a user, as can be returned when nested within other

        resources.'
      allOf:
      - $ref: '#/components/schemas/User--Base'
      - properties:
          name:
            type: string
            description: The display name of this user
            example: Aaron Levie
            maxLength: 50
          login:
            type: string
            format: email
            description: The primary email address of this user
            example: ceo@example.com
    Items:
      title: Items
      type: object
      x-box-resource-id: items
      x-box-tag: folders
      description: 'A list of files, folders, and web links in

        their mini representation.'
      allOf:
      - type: object
        description: The part of an API response that describes pagination
        properties:
          total_count:
            description: 'One greater than the offset of the last entry in the entire collection.

              The total number of entries in the collection may be less than

              `

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