openapi: 3.1.0 info: title: Box Authorize Authorization Transfer Folders API description: Needs a description. tags: - name: Transfer Folders description: 'API designed to move all of the items (files, folders and workflows) owned by a user into another user''s account.' x-box-tag: transfer paths: /users/{user_id}/folders/0: put: operationId: put_users_id_folders_0 x-box-tag: transfer summary: Box Transfer owned folders tags: - Transfer Folders description: 'Move all of the items (files, folders and workflows) owned by a user into another user''s account Only the root folder (`0`) can be transferred. Folders can only be moved across users by users with administrative permissions. All existing shared links and folder-level collaborations are transferred during the operation. Please note that while collaborations at the individual file-level are transferred during the operation, the collaborations are deleted when the original user is deleted. This call will be performed synchronously which might lead to a slow response when the source user has a large number of items in all of its folders. If the destination path has a metadata cascade policy attached to any of the parent folders, a metadata cascade operation will be kicked off asynchronously. There is currently no way to check for when this operation is finished. The destination folder''s name will be in the format `{User}''s Files and Folders`, where `{User}` is the display name of the user. To make this API call your application will need to have the "Read and write all files and folders stored in Box" scope enabled. Please make sure the destination user has access to `Relay` or `Relay Lite`, and has access to the files and folders involved in the workflows being transferred. Admins will receive an email when the operation is completed.' parameters: - name: user_id description: The ID of the user. example: '12345' in: path required: true schema: type: string - name: fields description: 'A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.' in: query example: - id - type - name required: false explode: false schema: type: array items: type: string - name: notify description: 'Determines if users should receive email notification for the action performed.' in: query required: false example: true schema: type: boolean requestBody: content: application/json: schema: type: object required: - owned_by properties: owned_by: type: object description: The user who the folder will be transferred to required: - id properties: id: type: string example: '1232234' description: 'The ID of the user who the folder will be transferred to' responses: '200': description: 'Returns the information for the newly created destination folder.' content: application/json: schema: $ref: '#/components/schemas/Folder--Full' '403': description: "Returns an error when folder ownership cannot be\ntransferred to another user.\n\n* `forbidden_by_policy`: Returned if ownership transfer\n is forbidden due to information barrier restrictions." content: application/json: schema: $ref: '#/components/schemas/ClientError' 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 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' 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' Folder--Full: title: Folder (Full) type: object x-box-resource-id: folder--full x-box-variant: full description: 'A full representation of a folder, as can be returned from any folder API endpoints by default' allOf: - $ref: '#/components/schemas/Folder' - properties: sync_state: allOf: - type: string example: synced nullable: false description: 'Specifies whether a folder should be synced to a user''s device or not. This is used by Box Sync (discontinued) and is not used by Box Drive.' enum: - synced - not_synced - partially_synced has_collaborations: type: boolean example: true nullable: false description: Specifies if this folder has any other collaborators. permissions: allOf: - type: object description: The permissions that the authenticated user has for a folder. required: - can_upload 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_upload: type: boolean description: Specifies if the user can upload into this folder. example: true nullable: false - description: 'Describes the permissions that the current user has for this folder' - 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 can_non_owners_invite: allOf: - type: boolean example: true description: 'Specifies if users who are not the owner of the folder can invite new collaborators to the folder.' - nullable: false is_externally_owned: type: boolean example: true nullable: false description: 'Specifies if this folder is owned by a user outside of the authenticated enterprise.' 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 folder. Each metadata instance is uniquely identified by its `scope` and `templateKey`. There can only be one instance of any metadata template attached to each folder. 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.' is_collaboration_restricted_to_enterprise: allOf: - type: boolean example: true description: 'Specifies if new invites to this folder are restricted to users within the enterprise. This does not affect existing collaborations.' - nullable: false allowed_shared_link_access_levels: type: array example: - open items: type: string enum: - open - company - collaborators nullable: false description: 'A list of access levels that are available for this folder. For some folders, like the root folder, this will always be an empty list as sharing is not allowed at that level.' 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 folder.' items: type: string enum: - editor - viewer - previewer - uploader - previewer uploader - viewer uploader - co-owner 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 folder - nullable: false is_accessible_via_shared_link: type: boolean description: 'Specifies if the folder can be accessed with the direct shared link or a shared link to a parent folder.' example: true enum: - true - false can_non_owners_view_collaborators: type: boolean example: true description: 'Specifies if collaborators who are not owners of this folder are restricted from viewing other collaborations on this folder. It also restricts non-owners from inviting new collaborators.' 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 folder. - nullable: true 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 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' 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--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