openapi: 3.1.0 info: 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 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 file. This will be `null` if no shared link has been created for this file.' - nullable: true parent: allOf: - $ref: '#/components/schemas/Folder--Mini' - description: The folder that this file is located within. 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 EventSource: title: Event source type: object x-box-resource-id: event_source description: 'The source file or folder that triggered an event in the event stream.' required: - item_type - item_id - item_name properties: item_type: type: string nullable: false enum: - file - folder description: 'The type of the item that the event represents. Can be `file` or `folder`. ' example: file item_id: type: string nullable: false description: 'The unique identifier that represents the item. ' example: '560284318361' item_name: type: string nullable: false description: 'The name of the item. ' example: report.pdf classification: type: object description: 'The object containing classification information for the item that triggered the event. This field will not appear if the item does not have a classification set.' properties: name: type: string description: The classification's name example: Top Secret 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 owned_by: allOf: - $ref: '#/components/schemas/User--Mini' - description: The user who owns this item. - nullable: false 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 nullable: false enum: - user WebLink: title: Web link type: object x-box-resource-id: web_link x-box-variant: standard description: 'Web links are objects that point to URLs. These objects are also known as bookmarks within the Box web application. Web link objects are treated similarly to file objects, they will also support most actions that apply to regular files.' allOf: - $ref: '#/components/schemas/WebLink--Mini' - properties: parent: allOf: - $ref: '#/components/schemas/Folder--Mini' - description: The parent object the web link belongs to description: type: string example: Example page description: 'The description accompanying the web link. This is visible within the Box web application.' 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 web link is contained in, starting at the root.' - nullable: false created_at: type: string format: date-time description: When this file was created on Box’s servers. example: '2012-12-12T10:53:43-08:00' modified_at: type: string format: date-time description: 'When this file was last updated on the Box servers.' example: '2012-12-12T10:53:43-08:00' trashed_at: type: string format: date-time nullable: true description: When this file was moved to the trash. example: '2012-12-12T10:53:43-08:00' purged_at: type: string format: date-time nullable: true description: When this file will be permanently deleted. example: '2012-12-12T10:53:43-08:00' created_by: allOf: - $ref: '#/components/schemas/User--Mini' - description: The user who created this web link modified_by: allOf: - $ref: '#/components/schemas/User--Mini' - description: The user who last modified this web link owned_by: allOf: - $ref: '#/components/schemas/User--Mini' - description: The user who owns this web link 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 object for this item. Will be `null` if no shared link has been created.' - nullable: true item_status: type: string example: active enum: - active - trashed - deleted description: 'Whether this item is deleted or not. Values include `active`, `trashed` if the file has been moved to the trash, and `deleted` if the file has been permanently deleted' GenericSource: title: Generic source type: object x-box-resource-id: generic_source description: A generic event source type. additionalProperties: allOf: - {} - description: "A definition of a generic\nevent source object. The set of\nparameters depends on the\nobject type. For example, a Box Shield\nevent source would have the following\nset of parameters:\n```yaml\n{\n\"barrier_id\": 123456,\n\"barrier_status\": \"ENABLED\",\n\"barrier_segments\": [\n {\n \"name\": \"8\",\n \"member_count\": 1\n },\n {\n \"name\": \"9\",\n \"member_count\": 1\n }\n ]\n} \n```\n" FileOrFolderScope: title: File or folder scope type: object description: A relation between a resource (file or folder) and the scopes for which the resource can be accessed properties: scope: type: string description: The scopes for the resource access example: item_download enum: - annotation_edit - annotation_view_all - annotation_view_self - base_explorer - base_picker - base_preview - base_upload - item_delete - item_download - item_preview - item_rename - item_share object: allOf: - oneOf: - $ref: '#/components/schemas/Folder--Mini' - $ref: '#/components/schemas/File--Mini' - description: The file or folder resource Metadata--Base: title: Metadata instance (Base) type: object x-box-resource-id: metadata--base x-box-sanitized: true x-box-tag: file_metadata x-box-variants: - base - standard - full x-box-variant: base description: The base representation of a metadata instance. properties: $parent: type: string example: folder_59449484661, description: 'The identifier of the item that this metadata instance has been attached to. This combines the `type` and the `id` of the parent in the form `{type}_{id}`.' $template: type: string example: marketingCollateral description: The name of the template $scope: type: string example: enterprise_27335 description: 'An ID for the scope in which this template has been applied. This will be `enterprise_{enterprise_id}` for templates defined for use in this enterprise, and `global` for general templates that are available to all enterprises using Box.' $version: type: integer example: 1 description: 'The version of the metadata instance. This version starts at 0 and increases every time a user-defined property is modified.' WebLink--Mini: title: Web link (Mini) type: object x-box-resource-id: web_link--mini x-box-variant: mini description: 'Web links are objects that point to URLs. These objects are also known as bookmarks within the Box web application. Web link objects are treated similarly to file objects, they will also support most actions that apply to regular files.' allOf: - $ref: '#/components/schemas/WebLink--Base' - properties: url: type: string example: https://www.example.com/example/1234 description: The URL this web link points to sequence_id: allOf: - type: string example: '3' nullable: true description: 'A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource.' - nullable: false name: type: string description: The name of the web link example: My Bookmark Metadata: title: Metadata instance type: object x-box-resource-id: metadata x-box-tag: file_metadata x-box-variant: standard description: 'An instance of a metadata template, which has been applied to a file or folder.' allOf: - $ref: '#/components/schemas/Metadata--Base' 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' 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 Folder--Mini: title: Folder (Mini) type: object x-box-resource-id: folder--mini x-box-variant: mini description: 'A mini representation of a file version, used when nested under another resource.' allOf: - $ref: '#/components/schemas/Folder--Base' - properties: sequence_id: allOf: - type: string example: '3' nullable: true description: 'A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource.' - nullable: false name: type: string description: The name of the folder. example: Contracts nullable: false File--Base: title: File (Base) type: object x-box-resource-id: file--base x-box-sanitized: true x-box-tag: files x-box-variants: - base - mini - standard - full x-box-variant: base nullable: true description: 'The bare basic representation of a file, the minimal amount of fields returned when using the `fields` query parameter.' required: - id - type properties: id: type: string nullable: false description: 'The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.' example: '12345' etag: type: string example: '1' nullable: true description: 'The HTTP `etag` of this file. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the file if (no) changes have happened.' type: type: string description: '`file`' example: file enum: - file nullable: false 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 File--Mini: title: File (Mini) type: object x-box-resource-id: file--mini x-box-variant: mini description: 'A mini representation of a file, used when nested under another resource.' nullable: true allOf: - $ref: '#/components/schemas/File--Base' - properties: sequence_id: allOf: - type: string example: '3' nullable: true description: 'A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource.' - nullable: false name: type: string description: The name of the file example: Contract.pdf sha1: type: string format: digest nullable: false example: 85136C79CBF9FE36BB9D05D0639C70C265C18D37 description: 'The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file.' file_version: allOf: - $ref: '#/components/schemas/FileVersion--Mini' - description: The information about the current version of the file. File--Full: title: File (Full) type: object x-box-resource-id: file--full x-box-variant: full description: 'A full representation of a file, as can be returned from any file API endpoints by default' allOf: - $ref: '#/components/schemas/File' - properties: version_number: type: string example: '1' description: The version number of this file comment_count: type: integer example: 10 description: The number of comments on this file permissions: allOf: - type: object description: The permissions that the authenticated user has for a file. required: - can_annotate - can_comment - can_preview - can_upload - can_view_annotations_all - can_view_annotations_self allOf: - type: object description: The permissions that the authenticated user has for an item. required: - can_delete - can_download - can_invite_collaborator - can_rename - can_set_share_access - can_share properties: can_delete: type: boolean description: Specifies if the current user can delete this item. example: true nullable: false can_download: type: boolean description: Specifies if the current user can download this item. example: true nullable: false can_invite_collaborator: type: boolean description: 'Specifies if the current user can invite new users to collaborate on this item, and if the user can update the role of a user already collaborated on this item.' example: true nullable: false can_rename: type: boolean description: Specifies if the user can rename this item. example: true nullable: false can_set_share_access: type: boolean description: 'Specifies if the user can change the access level of an existing shared link on this item.' example: true nullable: false can_share: type: boolean description: Specifies if the user can create a shared link for this item. example: true nullable: false - properties: can_annotate: type: boolean description: Specifies if the user can place annotations on this file. example: true nullable: false can_comment: type: boolean description: Specifies if the user can place comments on this file. example: true nullable: false can_preview: type: boolean description: Specifies if the user can preview this file. example: true nullable: false can_upload: type: boolean description: Specifies if the user can upload a new version of this file. example: true nullable: false can_view_annotations_all: type: boolean description: Specifies if the user view all annotations placed on this file example: true nullable: false can_view_annotations_self: type: boolean description: 'Specifies if the user view annotations placed by themselves on this file' example: true nullable: false - description: 'Describes the permissions that the current user has for this file.' - nullable: false tags: allOf: - type: array example: - approved items: type: string minItems: 1 maxItems: 100 description: 'The tags for this item. These tags are shown in the Box web app and mobile apps next to an item. To add or remove a tag, retrieve the item''s current tags, modify them, and then update this field. There is a limit of 100 tags per item, and 10,000 unique tags per enterprise.' - nullable: false lock: allOf: - title: Lock type: object description: 'The lock held on a file. A lock prevents a file from being moved, renamed, or otherwise changed by anyone else than the user who created the lock.' properties: id: type: string description: The unique identifier for this lock example: '11446498' type: type: string description: '`lock`' example: lock enum: - lock created_by: allOf: - $ref: '#/components/schemas/User--Mini' - description: The user who created the lock. created_at: type: string format: date-time example: '2012-12-12T10:53:43-08:00' description: The time this lock was created at. expired_at: type: string format: date-time example: '2012-12-12T10:53:43-08:00' description: The time this lock is to expire at, which might be in the past. is_download_prevented: type: boolean example: true description: Whether or not the file can be downloaded while locked. app_type: type: string description: 'If the lock is managed by an application rather than a user, this field identifies the type of the application that holds the lock. This is an open enum and may be extended with additional values in the future.' enum: - gsuite - office_wopi - office_wopiplus - other example: office_wopiplus nullable: true - description: 'The lock held on this file. If there is no lock, this can either be `null` or have a timestamp in the past.' nullable: true extension: type: string example: pdf description: 'Indicates the (optional) file extension for this file. By default, this is set to an empty string.' is_package: type: boolean example: true description: 'Indicates if the file is a package. Packages are commonly used by Mac Applications and can include iWork files.' expiring_embed_link: allOf: - title: Expiring embed link type: object description: An expiring Box Embed Link. allOf: - type: object description: The basics of an access token properties: access_token: type: string format: token example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ description: The requested access token. expires_in: type: integer format: int64 example: 3600 description: The time in seconds by which this token will expire. token_type: type: string enum: - bearer example: bearer description: The type of access token returned. restricted_to: type: array description: 'The permissions that this access token permits, providing a list of resources (files, folders, etc) and the scopes permitted for each of those resources.' items: $ref: '#/components/schemas/FileOrFolderScope' - properties: url: type: string format: url example: https://cloud.app.box.com/preview/expiring_embed/... description: 'The actual expiring embed URL for this file, constructed from the file ID and access tokens specified in this object.' - description: 'Requesting this field creates an expiring Box Embed URL for an embedded preview session in an `iframe`. This URL will expire after 60 seconds and the session will expire after 60 minutes. Not all file types are supported for these embed URLs. Box Embed is not optimized for mobile browsers and should not be used in web experiences designed for mobile devices. Many UI elements, like the **download** and **print** options might not show in mobile browsers.' watermark_info: allOf: - type: object description: Details about the watermark applied to this item properties: is_watermarked: type: boolean description: Specifies if this item has a watermark applied. example: true nullable: false - description: Details about the watermark applied to this file is_accessible_via_shared_link: type: boolean description: 'Specifies if the file can be accessed via the direct shared link or a shared link to a parent folder.' example: true enum: - true - false allowed_invitee_roles: type: array example: - editor nullable: false description: 'A list of the types of roles that user can be invited at when sharing this file.' items: type: string enum: - editor - viewer - previewer - uploader - previewer uploader - viewer uploader - co-owner is_externally_owned: type: boolean example: true nullable: false description: 'Specifies if this file is owned by a user outside of the authenticated enterprise.' has_collaborations: type: boolean example: true nullable: false description: Specifies if this file has any other collaborators. metadata: allOf: - title: Item metadata instances type: object description: 'A list of metadata instances, nested within key-value pairs of their `scope` and `templateKey`. To access the metadata for a file or folder, first use the metadata endpoints to determine the metadata templates available to your enterprise. Then use the `GET /files/:id` or `GET /folder/:id` endpoint with the `fields` query parameter to get the metadata by ID. To request a metadata instance for a particular `scope` and `templateKey` use the following format for the `fields` parameter: `metadata..` For example, `?fields=metadata.enterprise_27335.marketingCollateral`.' example: enterprise_27335: marketingCollateral: $canEdit: true $id: 01234500-12f1-1234-aa12-b1d234cb567e $parent: folder_59449484661 $scope: enterprise_27335 $template: marketingCollateral $type: properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0 $typeVersion: 2 $version: 1 additionalProperties: type: object description: 'A list of metadata instances, nested within key-value pairs of their `scope` and `templateKey`.' example: marketingCollateral: $canEdit: true $id: 01234500-12f1-1234-aa12-b1d234cb567e $parent: folder_59449484661 $scope: enterprise_27335 $template: marketingCollateral $type: properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0 $typeVersion: 2 $version: 1 additionalProperties: $ref: '#/components/schemas/Metadata' - description: 'An object containing the metadata instances that have been attached to this file. Each metadata instance is uniquely identified by its `scope` and `templateKey`. There can only be one instance of any metadata template attached to each file. Each metadata instance is nested within an object with the `templateKey` as the key, which again itself is nested in an object with the `scope` as the key.' expires_at: type: string format: date-time nullable: true description: When the file will automatically be deleted example: '2012-12-12T10:53:43-08:00' representations: allOf: - title: Representations description: A list of file representations type: object properties: entries: type: array description: A list of files items: type: object description: A file representation properties: content: type: object description: 'An object containing the URL that can be used to actually fetch the representation.' properties: url_template: type: string example: https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567 description: "The download URL that can be used to fetch the representation.\nMake sure to make an authenticated API call to this endpoint.\n\nThis URL is a template and will require the `{+asset_path}` to\nbe replaced by a path. In general, for unpaged representations\nit can be replaced by an empty string.\n\nFor paged representations, replace the `{+asset_path}` with the\npage to request plus the extension for the file, for example\n`1.pdf`.\n\nWhen requesting the download URL the following additional\nquery params can be passed along.\n\n* `set_content_disposition_type` - Sets the\n`Content-Disposition` header in the API response with the\nspecified disposition type of either `inline` or `attachment`.\nIf not supplied, the `Content-Disposition` header is not\nincluded in the response.\n\n* `set_content_disposition_filename` - Allows the application to\n define the representation's file name used in the\n `Content-Disposition` header. If not defined, the filename\n is derived from the source file name in Box combined with the\n extension of the representation." info: type: object description: 'An object containing the URL that can be used to fetch more info on this representation.' properties: url: type: string example: https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048 description: 'The API URL that can be used to get more info on this file representation. Make sure to make an authenticated API call to this endpoint.' properties: type: object description: An object containing the size and type of this presentation. properties: dimensions: type: string format: x example: 2048x2048 description: The width by height size of this representation in pixels. paged: type: boolean example: true description: 'Indicates if the representation is build up out of multiple pages.' thumb: type: boolean example: true description: 'Indicates if the representation can be used as a thumbnail of the file.' representation: type: string example: png description: Indicates the file type of the returned representation. status: type: object description: An object containing the status of this representation. properties: state: type: string example: success enum: - success - viewable - pending - none description: "The status of the representation.\n\n* `success` defines the representation as ready to be viewed.\n* `viewable` defines a video to be ready for viewing.\n* `pending` defines the representation as to be generated. Retry\n this endpoint to re-check the status.\n* `none` defines that the representation will be created when\n requested. Request the URL defined in the `info` object to\n trigger this generation." - description: 'A list of representations for a file that can be used to display a placeholder of the file in your application. By default this returns all representations and we recommend using the `x-rep-hints` header to further customize the desired representations.' classification: allOf: - type: object description: The classification applied to an item properties: name: type: string example: Top Secret description: The name of the classification definition: type: string example: Content that should not be shared outside the company. description: An explanation of the meaning of this classification. color: type: string example: '#FF0000' description: 'The color that is used to display the classification label in a user-interface. Colors are defined by the admin or co-admin who created the classification in the Box web app.' - description: Details about the classification applied to this file. - nullable: true uploader_display_name: allOf: - title: Uploader display name type: string example: Ellis Wiggins nullable: false description: 'The display name of the user that uploaded the file. In most cases this is the name of the user logged in at the time of the upload. If the file was uploaded using a File Request form that requires the user to provide an email address, this field is populated with that email address. If an email address was not required in the File Request form, this field is set to return a value of `File Request`. In all other anonymous cases where no email was provided this field will default to a value of `Someone`.' disposition_at: type: string format: date-time nullable: true description: The retention expiration timestamp for the given file example: '2012-12-12T10:53:43-08:00' shared_link_permission_options: type: array example: - can_preview nullable: true description: 'A list of the types of roles that user can be invited at when sharing this file.' items: type: string enum: - can_preview - can_download - can_edit WebLink--Base: title: Web link (Base) type: object x-box-resource-id: web_link--base x-box-tag: web_links x-box-variants: - base - mini - standard x-box-variant: base description: 'Web links are objects that point to URLs. These objects are also known as bookmarks within the Box web application. Web link objects are treated similarly to file objects, they will also support most actions that apply to regular files.' required: - id - type properties: id: type: string description: The unique identifier for this web link example: '11446498' type: type: string description: '`web_link`' example: web_link enum: - web_link etag: type: string example: '1' description: 'The entity tag of this web link. Used with `If-Match` headers.' 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 nullable: false description: The unique identifier that represent a file version. example: '12345' type: type: string description: '`file_version`' example: file_version enum: - file_version nullable: false Event: title: Event type: object x-box-resource-id: event x-box-tag: events description: The description of an event that happened within Box properties: type: description: '`event`' type: string example: event created_at: type: string format: date-time description: When the event object was created example: '2022-12-12T10:53:43-08:00' recorded_at: type: string format: date-time description: When the event object was recorded in database example: '2022-12-12T10:54:43-08:00' event_id: type: string example: f82c3ba03e41f7e8a7608363cc6c0390183c3f83 description: The ID of the event object. You can use this to detect duplicate events created_by: allOf: - $ref: '#/components/schemas/User--Mini' - description: 'The user that performed the action represented by the event. Some events may be performed by users not logged into Box. In that case, not all attributes of the object are populated and the event is attributed to a unknown user (`user_id = 2`)' event_type: allOf: - title: Event Type example: FILE_MARKED_MALICIOUS type: string description: An event type that can trigger an event 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 - COLLAB_ADD_COLLABORATOR - COLLAB_INVITE_COLLABORATOR - COLLAB_REMOVE_COLLABORATOR - COLLAB_ROLE_CHANGE - COMMENT_CREATE - COMMENT_DELETE - CONTENT_ACCESS - 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 - ENABLE_TWO_FACTOR_AUTH - ENTERPRISE_APP_AUTHORIZATION_UPDATE - 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_COPY - ITEM_CREATE - ITEM_DOWNLOAD - ITEM_MAKE_CURRENT_VERSION - ITEM_MODIFY - ITEM_MOVE - ITEM_OPEN - ITEM_PREVIEW - ITEM_RENAME - ITEM_SHARED - ITEM_SHARED_CREATE - ITEM_SHARED_UNSHARE - ITEM_SHARED_UPDATE - ITEM_SYNC - ITEM_TRASH - ITEM_UNDELETE_VIA_TRASH - ITEM_UNSYNC - ITEM_UPLOAD - LEGAL_HOLD_ASSIGNMENT_CREATE - LEGAL_HOLD_ASSIGNMENT_DELETE - LEGAL_HOLD_POLICY_CREATE - LEGAL_HOLD_POLICY_DELETE - LEGAL_HOLD_POLICY_UPDATE - LOCK - LOCK_CREATE - LOCK_DESTROY - LOGIN - MASTER_INVITE_ACCEPT - MASTER_INVITE_REJECT - METADATA_INSTANCE_CREATE - METADATA_INSTANCE_DELETE - METADATA_INSTANCE_UPDATE - METADATA_TEMPLATE_CREATE - METADATA_TEMPLATE_DELETE - METADATA_TEMPLATE_UPDATE - MOVE - NEW_USER - 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 - TAG_ITEM_CREATE - 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 - description: The event type that triggered this event session_id: type: string example: 70090280850c8d2a1933c1 description: 'The session of the user that performed the action. Not all events will populate this attribute.' source: allOf: - oneOf: - $ref: '#/components/schemas/User' - $ref: '#/components/schemas/EventSource' - $ref: '#/components/schemas/File' - $ref: '#/components/schemas/Folder' - $ref: '#/components/schemas/GenericSource' - description: 'The resource that triggered this event. For more information, check out the guide on event triggers.' additional_details: type: object example: key: value description: 'This object provides additional information about the event if available. This can include how a user performed an event as well as additional information to correlate an event to external KeySafe logs. Not all events have an `additional_details` object. This object is only available in the Enterprise Events.' 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 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 `total_count`. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.' example: 5000 type: integer format: int64 limit: description: 'The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.' example: 1000 type: integer format: int64 offset: description: 'The 0-based offset of the first entry in this set. This will be the same as the `offset` query parameter. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.' example: 2000 type: integer format: int64 order: description: 'The order by which items are returned. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.' type: array items: type: object description: The order in which a pagination is ordered properties: by: description: The field to order by example: type type: string direction: type: string description: The direction to order by, either ascending or descending example: ASC enum: - ASC - DESC - properties: entries: description: The items in this collection. type: array items: oneOf: - $ref: '#/components/schemas/File--Full' - $ref: '#/components/schemas/Folder--Mini' - $ref: '#/components/schemas/WebLink' 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' Folder--Base: title: Folder (Base) type: object x-box-resource-id: folder--base x-box-sanitized: true x-box-tag: folders x-box-variants: - base - mini - standard - full x-box-variant: base description: 'The bare basic representation of a folder, the minimal amount of fields returned when using the `fields` query parameter.' required: - id - type properties: id: type: string nullable: false description: 'The unique identifier that represent a folder. The ID for any folder can be determined by visiting a folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folders/123` the `folder_id` is `123`.' example: '12345' etag: type: string nullable: true example: '1' description: 'The HTTP `etag` of this folder. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the folder if (no) changes have happened.' type: type: string description: '`folder`' example: folder enum: - folder nullable: false User: title: User type: object x-box-resource-id: user x-box-variant: standard description: 'A standard representation of a user, as returned from any user API endpoints by default' allOf: - $ref: '#/components/schemas/User--Mini' - properties: created_at: type: string format: date-time description: When the user object was created example: '2012-12-12T10:53:43-08:00' modified_at: type: string format: date-time description: When the user object was last modified example: '2012-12-12T10:53:43-08:00' language: type: string description: 'The language of the user, formatted in modified version of the [ISO 639-1](/guides/api-calls/language-codes) format.' example: en timezone: type: string format: timezone description: The user's timezone example: Africa/Bujumbura space_amount: type: integer format: int64 description: The user’s total available space amount in bytes example: 11345156112 space_used: type: integer format: int64 description: The amount of space in use by the user example: 1237009912 max_upload_size: type: integer format: int64 description: The maximum individual file size in bytes the user can have example: 2147483648 status: type: string enum: - active - inactive - cannot_delete_edit - cannot_delete_edit_upload description: The user's account status example: active job_title: type: string description: The user’s job title maxLength: 100 example: CEO phone: type: string description: The user’s phone number maxLength: 100 example: '6509241374' address: type: string description: The user’s address maxLength: 255 example: 900 Jefferson Ave, Redwood City, CA 94063 avatar_url: type: string description: URL of the user’s avatar image example: https://www.box.com/api/avatar/large/181216415 notification_email: type: object description: 'An alternate notification email address to which email notifications are sent. When it''s confirmed, this will be the email address to which notifications are sent instead of to the primary email address.' nullable: true properties: email: type: string example: notifications@example.com description: The email address to send the notifications to. is_confirmed: type: boolean example: true description: Specifies if this email address has been confirmed. 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 nullable: false login: type: string format: email description: The primary email address of this user example: ceo@example.com nullable: false