openapi: 3.1.0 info: title: Box Folders API description: Needs a description. paths: /folders/{folder_id}: get: operationId: get_folders_id summary: Box Get folder information tags: - Folders x-box-tag: folders x-box-enable-explorer: true x-box-sanitized: true description: |- Retrieves details for a folder, including the first 100 entries in the folder. Passing `sort`, `direction`, `offset`, and `limit` parameters in query allows you to manage the list of returned [folder items](r://folder--full#param-item-collection). To fetch more items within the folder, use the [Get items in a folder](e://get-folders-id-items) endpoint. parameters: - name: folder_id description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: '12345' in: path required: true schema: type: string nullable: false - 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. Additionally this field can be used to query any metadata applied to the file by specifying the `metadata` field as well as the scope and key of the template to retrieve, for example `?field=metadata.enterprise_12345.contractTemplate`. in: query example: - id - type - name required: false explode: false schema: type: array items: type: string - name: if-none-match description: |- Ensures an item is only returned if it has changed. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `304 Not Modified` if the item has not changed since. in: header required: false example: '1' schema: type: string - name: boxapi description: >- The URL, and optional password, for the shared link of this item. This header can be used to access items that have not been explicitly shared with a user. Use the format `shared_link=[link]` or if a password is required then use `shared_link=[link]&shared_link_password=[password]`. This header can be used on the file or folder shared, as well as on any files or folders nested within the item. example: shared_link=[link]&shared_link_password=[password] in: header required: false schema: type: string - name: sort description: |- Defines the **second** attribute by which items are sorted. The folder type affects the way the items are sorted: * **Standard folder**: Items are always sorted by their `type` first, with folders listed before files, and files listed before web links. * **Root folder**: This parameter is not supported for marker-based pagination on the root folder (the folder with an `id` of `0`). * **Shared folder with parent path to the associated folder visible to the collaborator**: Items are always sorted by their `type` first, with folders listed before files, and files listed before web links. in: query required: false example: id schema: type: string enum: - id - name - date - size - name: direction description: >- The direction to sort results in. This can be either in alphabetical ascending (`ASC`) or descending (`DESC`) order. in: query required: false example: ASC schema: type: string enum: - ASC - DESC - name: offset description: |- The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. in: query required: false example: 1000 schema: type: integer format: int64 default: 0 - name: limit description: The maximum number of items to return per page. in: query required: false example: 1000 schema: type: integer format: int64 maximum: 1000 responses: '200': description: |- Returns a folder, including the first 100 entries in the folder. If you used query parameters like `sort`, `direction`, `offset`, or `limit` the *folder items list* will be affected accordingly. To fetch more items within the folder, use the [Get items in a folder](e://get-folders-id-items)) endpoint. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. content: application/json: schema: $ref: '#/components/schemas/Folder--Full' '304': description: >- Returns an empty response when the `If-None-Match` header matches the current `etag` value of the folder. This indicates that the folder has not changed since it was last requested. '403': description: >- Returned when the access token provided in the `Authorization` header is not recognized or not provided. content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: |- Returned if the folder is not found, or the user does not have access to the folder. content: application/json: schema: $ref: '#/components/schemas/ClientError' '405': description: Returned if the `folder_id` is not in a recognized format. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' post: operationId: post_folders_id summary: Box Restore folder tags: - Folders x-box-tag: trashed_folders description: >- Restores a folder that has been moved to the trash. An optional new parent ID can be provided to restore the folder to in case the original folder has been deleted. # Folder locking During this operation, part of the file tree will be locked, mainly the source folder and all of its descendants, as well as the destination folder. For the duration of the operation, no other move, copy, delete, or restore operation can performed on any of the locked folders. parameters: - name: folder_id description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: '12345' in: path required: true schema: type: string nullable: false - 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 requestBody: content: application/json: schema: type: object properties: name: description: An optional new name for the folder. example: Restored Photos type: string parent: allOf: - type: object description: The parent for this item properties: id: type: string description: The ID of parent item example: '123' - description: >- Specifies an optional ID of a folder to restore the folder to when the original folder no longer exists. Please be aware that this ID will only be used if the original folder no longer exists. Use this ID to provide a fallback location to restore the folder to if the original location has been deleted. responses: '201': description: Returns a folder object when the folder has been restored. content: application/json: schema: $ref: '#/components/schemas/TrashFolderRestored' '403': description: >- Returns an error if the user does not have access to the folder the folder is being restored to, or the user does not have permission to restore folders from the trash. content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: Returns an error if the folder is not in the trash. content: application/json: schema: $ref: '#/components/schemas/ClientError' '409': description: >- * Returned an error if there is a folder with the same name in the destination folder. * `operation_blocked_temporary`: Returned if either of the destination or source folders is locked due to another move, copy, delete or restore operation in process. The operation can be retried at a later point. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' put: operationId: put_folders_id summary: Box Update folder description: |- Updates a folder. This can be also be used to move the folder, create shared links, update collaborations, and more. tags: - Folders x-box-tag: folders x-box-sanitized: true x-box-enable-explorer: true parameters: - name: folder_id description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: '12345' in: path required: true schema: type: string nullable: false - 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: if-match description: |- Ensures this item hasn't recently changed before making changes. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `412 Precondition Failed` if it has changed since. in: header required: false example: '1' schema: type: string requestBody: content: application/json: schema: type: object properties: name: type: string description: The optional new name for this folder. example: New Folder description: type: string description: The optional description of this folder maxLength: 256 example: Legal contracts for the new ACME deal nullable: false sync_state: 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 can_non_owners_invite: type: boolean example: true description: |- Specifies if users who are not the owner of the folder can invite new collaborators to the folder. parent: type: object description: |- The parent folder for this folder. Use this to move the folder or to restore it out of the trash. properties: id: type: string description: The ID of the new parent folder example: '0' shared_link: allOf: - description: >- Defines a shared link for an item. Set this to `null` to remove the shared link. type: object properties: access: type: string description: >- The level of access for the shared link. This can be restricted to anyone with the link (`open`), only people within the company (`company`) and only those who have been invited to the folder (`collaborators`). If not set, this field defaults to the access level specified by the enterprise admin. To create a shared link with this default setting pass the `shared_link` object with no `access` field, for example `{ "shared_link": {} }`. The `company` access level is only available to paid accounts. enum: - open - company - collaborators example: open password: type: string description: >- The password required to access the shared link. Set the password to `null` to remove it. Passwords must now be at least eight characters long and include a number, upper case letter, or a non-numeric or non-alphabetic character. A password can only be set when `access` is set to `open`. example: do-n8t-use-this-Password vanity_name: type: string description: >- Defines a custom vanity name to use in the shared link URL, for example `https://app.box.com/v/my-shared-link`. Custom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links. example: my-shared-link unshared_at: type: string format: date-time example: '2012-12-12T10:53:43-08:00' description: |- The timestamp at which this shared link will expire. This field can only be set by users with paid accounts. permissions: type: object properties: can_download: type: boolean example: true description: >- If the shared link allows for downloading of files. This can only be set when `access` is set to `open` or `company`. - description: Enables the creation of a shared link for a folder. folder_upload_email: allOf: - title: Folder upload email type: object description: The Write Folder Upload Email object 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. - description: >- Setting this object enables the upload email address. This email address can be used by users to directly upload files directly to the folder via email. Setting the value to `null` will disable the email address. tags: 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. is_collaboration_restricted_to_enterprise: 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. collections: type: array description: |- An array of collections to make this folder a member of. Currently we only support the `favorites` collection. To get the ID for a collection, use the [List all collections][1] endpoint. Passing an empty array `[]` or `null` will remove the folder from all collections. [1]: e://get-collections items: title: Reference description: The bare basic reference for an object type: object properties: id: type: string description: The unique identifier for this object example: '11446498' type: type: string description: The type for this object example: file can_non_owners_view_collaborators: type: boolean example: true description: |- Restricts collaborators who are not the owner of this folder from viewing other collaborations on this folder. It also restricts non-owners from inviting new collaborators. When setting this field to `false`, it is required to also set `can_non_owners_invite_collaborators` to `false` if it has not already been set. responses: '200': description: |- Returns a folder object for the updated folder Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. This call will return synchronously. This holds true even when moving folders with a large a large number of items in all of its descendants. For very large folders, this means the call could take minutes or hours to return. content: application/json: schema: $ref: '#/components/schemas/Folder--Full' '400': description: >- Returns an error if some of the parameters are missing or not valid, or if a folder lock is preventing a move operation. * `bad_request` when a parameter is missing or incorrect. This error also happens when a password is set for a shared link with an access type of `open`. * `item_name_too_long` when the folder name is too long. * `item_name_invalid` when the folder name contains non-valid characters. content: application/json: schema: $ref: '#/components/schemas/ClientError' '403': description: |- Returns an error if the user does not have the required access to perform the action. * `access_denied_insufficient_permissions`: Returned when the user does not have access to the folder or parent folder, or if the folder is being moved and a folder lock has been applied to prevent such operations. * `insufficient_scope`: Returned an error if the application does not have the right scope to update folders. Make sure your application has been configured to read and write all files and folders stored in Box. * `forbidden`: Returned when the user is not allowed to perform this action for other users. This can include trying to create a Shared Link with a `company` access level on a free account. * `forbidden_by_policy`: Returned if copying a folder is forbidden due to information barrier restrictions. Returns an error if there are too many actions in the request body. * `operation_limit_exceeded`: Returned when the user passes any parameters in addition to the `parent.id` in the request body. The calls to this endpoint have to be split up. The first call needs to include only the `parent.id`, the next call can include other parameters. content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: |- Returns an error if the folder or parent folder could not be found, or the authenticated user does not have access to either folder. * `not_found` when the authenticated user does not have access to the folder or parent folder. content: application/json: schema: $ref: '#/components/schemas/ClientError' '409': description: >- * `operation_blocked_temporary`: Returned if either of the destination or source folders is locked due to another move, copy, delete or restore operation in progress. The operation can be retried at a later point. * `item_name_in_use`: Returned if a folder with the name already exists in the parent folder. content: application/json: schema: $ref: '#/components/schemas/ClientError' '412': description: |- Returns an error when the `If-Match` header does not match the current `etag` value of the folder. This indicates that the folder has changed since it was last requested. content: application/json: schema: $ref: '#/components/schemas/ClientError' '503': description: |- Returns an error when the operation takes longer than 60 seconds. The operation will continue after this response has been returned. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' delete: operationId: delete_folders_id summary: Box Delete folder description: |- Deletes a folder, either permanently or by moving it to the trash. tags: - Folders x-box-tag: folders x-box-sanitized: true parameters: - name: folder_id description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: '12345' in: path required: true schema: type: string nullable: false - name: if-match description: |- Ensures this item hasn't recently changed before making changes. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `412 Precondition Failed` if it has changed since. in: header required: false example: '1' schema: type: string - name: recursive description: |- Delete a folder that is not empty by recursively deleting the folder and all of its content. in: query required: false example: true schema: type: boolean responses: '204': description: |- Returns an empty response when the folder is successfully deleted or moved to the trash. '400': description: |- Returns an error if the user makes a bad request. * `folder_not_empty`: Returned if the folder is not empty. Use the `recursive` query parameter to recursively delete the folder and its contents. content: application/json: schema: $ref: '#/components/schemas/ClientError' '403': description: |- Returns an error if the user does not have the required access to perform the action. * `access_denied_insufficient_permissions`: Returned when the user does not have access to the folder, or when a folder lock has been applied to the folder to prevent deletion. * `insufficient_scope`: Returned an error if the application does not have the right scope to delete folders. Make sure your application has been configured to read and write all files and folders stored in Box. content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: |- Returns an error if the folder could not be found, or the authenticated user does not have access to the folder. * `not_found` when the authenticated user does not have access to the folder. content: application/json: schema: $ref: '#/components/schemas/ClientError' '409': description: |- * `operation_blocked_temporary`: Returned if the folder is locked due to another move, copy, delete or restore operation in progress. The operation can be retried at a later point. content: application/json: schema: $ref: '#/components/schemas/ClientError' '412': description: |- Returns an error when the `If-Match` header does not match the current `etag` value of the folder. This indicates that the folder has changed since it was last requested. content: application/json: schema: $ref: '#/components/schemas/ClientError' '503': description: |- Returns an error when the operation takes longer than 60 seconds. The operation will continue after this response has been returned. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' /folders/{folder_id}/items: get: operationId: get_folders_id_items summary: Box List items in folder tags: - Folders x-box-tag: folders x-box-sanitized: true x-box-enable-explorer: true description: |- Retrieves a page of items in a folder. These items can be files, folders, and web links. To request more information about the folder itself, like its size, use the [Get a folder](#get-folders-id) endpoint instead. parameters: - name: folder_id description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: '12345' in: path required: true schema: type: string nullable: false - 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. Additionally this field can be used to query any metadata applied to the file by specifying the `metadata` field as well as the scope and key of the template to retrieve, for example `?field=metadata.enterprise_12345.contractTemplate`. in: query example: - id - type - name required: false explode: false schema: type: array items: type: string - name: usemarker description: |- Specifies whether to use marker-based pagination instead of offset-based pagination. Only one pagination method can be used at a time. By setting this value to true, the API will return a `marker` field that can be passed as a parameter to this endpoint to get the next page of the response. in: query required: false example: true schema: type: boolean - name: marker description: >- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. in: query required: false example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii schema: type: string - name: offset description: |- The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. in: query required: false example: 1000 schema: type: integer format: int64 default: 0 - name: limit description: The maximum number of items to return per page. in: query required: false example: 1000 schema: type: integer format: int64 maximum: 1000 - name: boxapi description: >- The URL, and optional password, for the shared link of this item. This header can be used to access items that have not been explicitly shared with a user. Use the format `shared_link=[link]` or if a password is required then use `shared_link=[link]&shared_link_password=[password]`. This header can be used on the file or folder shared, as well as on any files or folders nested within the item. example: shared_link=[link]&shared_link_password=[password] in: header required: false schema: type: string - name: sort description: |- Defines the **second** attribute by which items are sorted. The folder type affects the way the items are sorted: * **Standard folder**: Items are always sorted by their `type` first, with folders listed before files, and files listed before web links. * **Root folder**: This parameter is not supported for marker-based pagination on the root folder (the folder with an `id` of `0`). * **Shared folder with parent path to the associated folder visible to the collaborator**: Items are always sorted by their `type` first, with folders listed before files, and files listed before web links. in: query required: false example: id schema: type: string enum: - id - name - date - size - name: direction description: >- The direction to sort results in. This can be either in alphabetical ascending (`ASC`) or descending (`DESC`) order. in: query required: false example: ASC schema: type: string enum: - ASC - DESC responses: '200': description: >- Returns a collection of files, folders, and web links contained in a folder. content: application/json: schema: $ref: '#/components/schemas/Items' '403': description: >- Returned when the access token provided in the `Authorization` header is not recognized or not provided. content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: |- Returned if the folder is not found, or the user does not have access to the folder. content: application/json: schema: $ref: '#/components/schemas/ClientError' '405': description: Returned if the `folder_id` is not in a recognized format. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' /folders: post: operationId: post_folders summary: Box Create folder tags: - Folders x-box-tag: folders x-box-enable-explorer: true description: Creates a new empty folder within the specified parent folder. parameters: - 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 requestBody: content: application/json: schema: type: object required: - name - parent properties: name: type: string description: >- The name for the new folder. There are some restrictions to the file name. Names containing non-printable ASCII characters, forward and backward slashes (`/`, `\`), as well as names with trailing spaces are prohibited. Additionally, the names `.` and `..` are not allowed either. example: New Folder maxLength: 255 minLength: 1 parent: type: object description: The parent folder to create the new folder within. required: - id properties: id: type: string description: The ID of parent folder example: '0' folder_upload_email: allOf: - title: Folder upload email type: object description: The Write Folder Upload Email object 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. - description: |- Setting this object enables the upload email address. This email address can be used by users to directly upload files directly to the folder via email. sync_state: 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 responses: '201': description: |- Returns a folder object. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. content: application/json: schema: $ref: '#/components/schemas/Folder--Full' '400': description: |- Returns an error if some of the parameters are missing or not valid. * `bad_request` when a parameter is missing or incorrect. * `item_name_too_long` when the folder name is too long. * `item_name_invalid` when the folder name contains non-valid characters. content: application/json: schema: $ref: '#/components/schemas/ClientError' '403': description: |- Returns an error if the user does not have the required access to perform the action. This might be because they don't have access to the folder or parent folder, or because the application does not have permission to write files and folders. content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: |- Returns an error if the parent folder could not be found, or the authenticated user does not have access to the parent folder. * `not_found` when the authenticated user does not have access to the parent folder content: application/json: schema: $ref: '#/components/schemas/ClientError' '409': description: >- * `operation_blocked_temporary`: Returned if either of the destination or source folders is locked due to another move, copy, delete or restore operation in process. The operation can be retried at a later point. * `item_name_in_use`: Returned if a folder with the name already exists in the parent folder. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' /folders/{folder_id}/copy: post: operationId: post_folders_id_copy summary: Box Copy folder x-box-enable-explorer: true x-box-tag: folders description: |- Creates a copy of a folder within a destination folder. The original folder will not be changed. tags: - Folders parameters: - name: folder_id description: |- The unique identifier of the folder to copy. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder with the ID `0` can not be copied. example: '0' in: path required: true schema: type: string nullable: false - 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 requestBody: content: application/json: schema: type: object required: - parent nullable: false properties: name: type: string description: >- An optional new name for the copied folder. There are some restrictions to the file name. Names containing non-printable ASCII characters, forward and backward slashes (`/`, `\`), as well as names with trailing spaces are prohibited. Additionally, the names `.` and `..` are not allowed either. example: New Folder maxLength: 255 minLength: 1 parent: type: object description: The destination folder to copy the folder to. required: - id properties: id: type: string description: The ID of parent folder example: '0' responses: '201': description: |- Returns a new folder object representing the copied folder. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. content: application/json: schema: $ref: '#/components/schemas/Folder--Full' '304': description: >- Returns an empty response when the `If-None-Match` header matches the current `etag` value of the folder. This indicates that the folder has not changed since it was last requested. '400': description: |- Returns an error if some of the parameters are missing or not valid. * `bad_request` when a parameter is missing. * `item_name_too_long` when the new folder name is too long. content: application/json: schema: $ref: '#/components/schemas/ClientError' '403': description: |- Returns an error when the user does not have the right permissions to copy a folder. * `forbidden_by_policy`: Returned if copying a folder is forbidden due to information barrier restrictions. content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: |- Returns an error if either the source or destination folder could not be found, or the authenticated user does not have access to either folders. * `not_found` when the authenticated user does not have access to the parent folder content: application/json: schema: $ref: '#/components/schemas/ClientError' '409': description: |- Returns an error if a folder by this name already exists in the destination folder, or if the destination folder is locked. * `item_name_in_use` when a folder with the same name already exists. content: application/json: schema: $ref: '#/components/schemas/ClientError' '500': description: Returns an error when trying to copy the root folder. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' /folders/{folder_id}/collaborations: get: operationId: get_folders_id_collaborations summary: Box List folder collaborations description: |- Retrieves a list of pending and active collaborations for a folder. This returns all the users that have access to the folder or have been invited to the folder. tags: - Folders x-box-tag: list_collaborations parameters: - name: folder_id description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. example: '12345' in: path required: true schema: type: string nullable: false - 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 responses: '200': description: >- Returns a collection of collaboration objects. If there are no collaborations on this folder an empty collection will be returned. This list includes pending collaborations, for which the `status` is set to `pending`, indicating invitations that have been sent but not yet accepted. content: application/json: schema: $ref: '#/components/schemas/Collaborations' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' /folders/{folder_id}/trash: get: operationId: get_folders_id_trash summary: Box Get trashed folder tags: - Folders x-box-tag: trashed_folders description: |- Retrieves a folder that has been moved to the trash. Please note that only if the folder itself has been moved to the trash can it be retrieved with this API call. If instead one of its parent folders was moved to the trash, only that folder can be inspected using the [`GET /folders/:id/trash`](e://get_folders_id_trash) API. To list all items that have been moved to the trash, please use the [`GET /folders/trash/items`](e://get-folders-trash-items/) API. parameters: - name: folder_id description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: '12345' in: path required: true schema: type: string nullable: false - 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 responses: '200': description: |- Returns the folder that was trashed, including information about when the it was moved to the trash. content: application/json: schema: $ref: '#/components/schemas/TrashFolder' '404': description: |- Returns an error if the folder can not be found directly in the trash. Please note that a `HTTP 404` is also returned if any of the folder's parent folders have been moved to the trash. In that case, only that parent folder can be inspected using the [`GET /folders/:id/trash`](e://get_folders_id_trash) API. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' delete: operationId: delete_folders_id_trash summary: Box Permanently remove folder tags: - Folders x-box-tag: trashed_folders description: |- Permanently deletes a folder that is in the trash. This action cannot be undone. parameters: - name: folder_id description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: '12345' in: path required: true schema: type: string nullable: false responses: '204': description: |- Returns an empty response when the folder was permanently deleted. '404': description: Returns an error if the folder is not in the trash. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' /folders/{folder_id}/metadata: get: operationId: get_folders_id_metadata summary: Box List metadata instances on folder tags: - Folders x-box-tag: folder_metadata x-box-sanitized: true description: >- Retrieves all metadata for a given folder. This can not be used on the root folder with ID `0`. parameters: - name: folder_id description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: '12345' in: path required: true schema: type: string nullable: false responses: '200': description: >- Returns all the metadata associated with a folder. This API does not support pagination and will therefore always return all of the metadata associated to the folder. content: application/json: schema: $ref: '#/components/schemas/Metadatas' '403': description: |- Returned when the request parameters are not valid. * `forbidden` - this operation is not allowed on the Root folder. content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: Returned when the user does not have access to the folder. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' /folders/{folder_id}/metadata/enterprise/securityClassification-6VMVochwUWo: get: operationId: get_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo summary: Box Get classification on folder tags: - Folders x-box-tag: folder_classifications x-box-sanitized: true description: |- Retrieves the classification metadata instance that has been applied to a folder. This API can also be called by including the enterprise ID in the URL explicitly, for example `/folders/:id//enterprise_12345/securityClassification-6VMVochwUWo`. parameters: - name: folder_id description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: '12345' in: path required: true schema: type: string nullable: false responses: '201': description: |- Returns an instance of the `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. content: application/json: schema: $ref: '#/components/schemas/Classification' '403': description: Returned when the request parameters are not valid. content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: >- Returned if the metadata template specified was not applied to this folder or the user does not have access to the folder. * `instance_not_found` - The metadata template was not applied to the folder. content: application/json: schema: $ref: '#/components/schemas/ClientError' '405': description: Returned when the method was not allowed. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' post: operationId: post_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo summary: Box Add classification to folder tags: - Folders x-box-tag: folder_classifications x-box-sanitized: true description: |- Adds a classification to a folder by specifying the label of the classification to add. This API can also be called by including the enterprise ID in the URL explicitly, for example `/folders/:id//enterprise_12345/securityClassification-6VMVochwUWo`. parameters: - name: folder_id description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: '12345' in: path required: true schema: type: string nullable: false requestBody: content: application/json: schema: type: object properties: Box__Security__Classification__Key: type: string description: >- The name of the classification to apply to this folder. To list the available classifications in an enterprise, use the classification API to retrieve the [classification template](e://get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema) which lists all available classification keys. example: Sensitive responses: '201': description: |- Returns the classification template instance that was applied to the folder. content: application/json: schema: $ref: '#/components/schemas/Classification' '400': description: >- Returns an error when the request body is not valid. * `schema_validation_failed` - The request body contains a value for a for a field that either does not exist, or for which the value or type does not match the expected field type. An example might be an unknown option for an `enum` or `multiSelect` field. content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: >- Returns an error when the folder or metadata template was not found. * `not_found` - The folder could not be found, or the user does not have access to the folder. * `instance_tuple_not_found` - The metadata template was not found. content: application/json: schema: $ref: '#/components/schemas/ClientError' '409': description: >- Returns an error when an instance of this metadata template is already present on the folder. * `tuple_already_exists` - An instance of them metadata template already exists on the folder. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' put: operationId: put_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo summary: Box Update classification on folder tags: - Folders x-box-tag: folder_classifications x-box-sanitized: true description: >- Updates a classification on a folder. The classification can only be updated if a classification has already been applied to the folder before. When editing classifications, only values are defined for the enterprise will be accepted. parameters: - name: folder_id description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: '12345' in: path required: true schema: type: string nullable: false requestBody: content: application/json-patch+json: schema: required: - items description: |- A list containing the one change to make, to update the classification label. type: array items: type: object description: |- The operation to perform on the classification metadata template instance. In this case, it use used to replace the value stored for the `Box__Security__Classification__Key` field with a new value. required: - op - path - value properties: op: type: string example: replace description: '`replace`' enum: - replace path: type: string example: /Box__Security__Classification__Key description: |- Defines classifications available in the enterprise. enum: - /Box__Security__Classification__Key value: type: string description: >- The name of the classification to apply to this folder. To list the available classifications in an enterprise, use the classification API to retrieve the [classification template](e://get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema) which lists all available classification keys. example: Sensitive responses: '200': description: Returns the updated classification metadata template instance. content: application/json: schema: $ref: '#/components/schemas/Classification' '400': description: >- Returns an error when the request body is not valid. * `bad_request` - The request body format is not an array of valid JSON Patch operations. content: application/json: schema: $ref: '#/components/schemas/ClientError' '500': description: >- Returns an error in some edge cases when the request body is not a valid array of JSON Patch items. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' delete: operationId: delete_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo summary: Box Remove classification from folder tags: - Folders x-box-tag: folder_classifications x-box-sanitized: true description: |- Removes any classifications from a folder. This API can also be called by including the enterprise ID in the URL explicitly, for example `/folders/:id//enterprise_12345/securityClassification-6VMVochwUWo`. parameters: - name: folder_id description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: '12345' in: path required: true schema: type: string nullable: false responses: '204': description: |- Returns an empty response when the classification is successfully deleted. '400': description: Returned when the request parameters are not valid. content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: >- Returns an error when the folder does not have any classification applied to it, or when the user does not have access to the folder. * `instance_not_found` - An instance of the classification metadata template with the was not found on this folder. * `not_found` - The folder was not found, or the user does not have access to the folder. content: application/json: schema: $ref: '#/components/schemas/ClientError' '405': description: Returned when the method was not allowed. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' /folders/{folder_id}/metadata/{scope}/{template_key}: get: operationId: get_folders_id_metadata_id_id summary: Box Get metadata instance on folder tags: - Folders x-box-tag: folder_metadata x-box-sanitized: true description: |- Retrieves the instance of a metadata template that has been applied to a folder. This can not be used on the root folder with ID `0`. parameters: - name: folder_id description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: '12345' in: path required: true schema: type: string nullable: false - name: scope description: The scope of the metadata template example: global in: path required: true schema: type: string enum: - global - enterprise - name: template_key description: The name of the metadata template example: properties in: path required: true schema: type: string responses: '201': description: |- An instance of the metadata template that includes additional "key:value" pairs defined by the user or an application. content: application/json: schema: $ref: '#/components/schemas/Metadata--Full' '403': description: Returned when the request parameters are not valid. content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: >- Returned if the metadata template specified was not applied to this folder or the user does not have access to the folder. * `instance_not_found` - The metadata template was not applied to the folder. content: application/json: schema: $ref: '#/components/schemas/ClientError' '405': description: >- Returned when the method was not allowed. This often happens when the folder ID is not valid or the root folder with ID `0`. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' post: operationId: post_folders_id_metadata_id_id summary: Box Create metadata instance on folder tags: - Folders x-box-tag: folder_metadata x-box-sanitized: true x-box-enable-explorer: false description: >- Applies an instance of a metadata template to a folder. In most cases only values that are present in the metadata template will be accepted, except for the `global.properties` template which accepts any key-value pair. To display the metadata template in the Box web app the enterprise needs to be configured to enable **Cascading Folder Level Metadata** for the user in the admin console. parameters: - name: folder_id description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: '12345' in: path required: true schema: type: string nullable: false - name: scope description: The scope of the metadata template example: global in: path required: true schema: type: string enum: - global - enterprise - name: template_key description: The name of the metadata template example: properties in: path required: true schema: type: string requestBody: content: application/json: schema: type: object example: name: Aaron Levie additionalProperties: allOf: - {} - example: Aaron Levie - description: >- A value for each of the fields that are present on the metadata template. For the `global.properties` template this can be a list of zero or more fields, as this template allows for any generic key-value pairs to be stored in the template. x-box-example-key: name responses: '201': description: |- Returns the instance of the template that was applied to the folder, including the data that was applied to the template. content: application/json: schema: $ref: '#/components/schemas/Metadata--Full' '400': description: >- Returns an error when the request body is not valid. * `schema_validation_failed` - The request body contains a value for a field that either does not exist, or for which the value or type does not match the expected field type. An example might be an unknown option for an `enum` or `multiSelect` field. content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: >- Returns an error when the folder or metadata template was not found. * `not_found` - The folder could not be found, or the user does not have access to the folder. * `instance_tuple_not_found` - The metadata template was not found. content: application/json: schema: $ref: '#/components/schemas/ClientError' '409': description: >- Returns an error when an instance of this metadata template is already present on the folder. * `tuple_already_exists` - An instance of them metadata template already exists on the file. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' put: operationId: put_folders_id_metadata_id_id summary: Box Update metadata instance on folder tags: - Folders x-box-tag: folder_metadata x-box-sanitized: true description: >- Updates a piece of metadata on a folder. The metadata instance can only be updated if the template has already been applied to the folder before. When editing metadata, only values that match the metadata template schema will be accepted. The update is applied atomically. If any errors occur during the application of the operations, the metadata instance will not be changed. parameters: - name: folder_id description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: '12345' in: path required: true schema: type: string nullable: false - name: scope description: The scope of the metadata template example: global in: path required: true schema: type: string enum: - global - enterprise - name: template_key description: The name of the metadata template example: properties in: path required: true schema: type: string requestBody: content: application/json-patch+json: schema: description: |- A [JSON-Patch](https://tools.ietf.org/html/rfc6902) specification for the changes to make to the metadata instance. The changes are represented as a JSON array of operation objects. type: array items: title: A metadata instance update operation description: >- A [JSON-Patch](https://tools.ietf.org/html/rfc6902) operation for a change to make to the metadata instance. type: object properties: op: type: string example: add enum: - add - replace - remove - test - move - copy description: >- The type of change to perform on the template. Some of these are hazardous as they will change existing templates. path: type: string example: /currentState description: >- The location in the metadata JSON object to apply the changes to, in the format of a [JSON-Pointer](https://tools.ietf.org/html/rfc6901). The path must always be prefixed with a `/` to represent the root of the template. The characters `~` and `/` are reserved characters and must be escaped in the key. value: type: string example: reviewed description: >- The value to be set or tested. Required for `add`, `replace`, and `test` operations. For `add`, if the value exists already the previous value will be overwritten by the new value. For `replace`, the value must exist before replacing. For `test`, the existing value at the `path` location must match the specified value. from: type: string example: /nextState description: >- The location in the metadata JSON object to move or copy a value from. Required for `move` or `copy` operations and must be in the format of a [JSON-Pointer](https://tools.ietf.org/html/rfc6901). responses: '200': description: |- Returns the updated metadata template instance, with the custom template data included. content: application/json: schema: $ref: '#/components/schemas/Metadata--Full' '400': description: >- Returns an error when the request body is not valid. * `bad_request` - The request body format is not an array of valid JSON Patch objects. content: application/json: schema: $ref: '#/components/schemas/ClientError' '500': description: >- Returns an error in some edge cases when the request body is not a valid array of JSON Patch items. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' delete: operationId: delete_folders_id_metadata_id_id summary: Box Remove metadata instance from folder tags: - Folders x-box-tag: folder_metadata x-box-sanitized: true description: Deletes a piece of folder metadata. parameters: - name: folder_id description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: '12345' in: path required: true schema: type: string nullable: false - name: scope description: The scope of the metadata template example: global in: path required: true schema: type: string enum: - global - enterprise - name: template_key description: The name of the metadata template example: properties in: path required: true schema: type: string responses: '204': description: |- Returns an empty response when the metadata is successfully deleted. '400': description: >- Returned when the request parameters are not valid. This may happen of the `scope` is not valid. content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: >- Returns an error when the folder does not have an instance of the metadata template applied to it, or when the user does not have access to the folder. * `instance_not_found` - An instance of the metadata template with the given `scope` and `templateKey` was not found on this folder. * `not_found` - The folder was not found, or the user does not have access to the folder. content: application/json: schema: $ref: '#/components/schemas/ClientError' '405': description: >- Returned when the method was not allowed. This often happens when the folder ID is not valid or the root folder with ID `0`. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' /folders/trash/items: get: operationId: get_folders_trash_items summary: Box List trashed items tags: - Folders x-box-tag: trashed_items description: |- Retrieves the files and folders that have been moved to the trash. Any attribute in the full files or folders objects can be passed in with the `fields` parameter to retrieve those specific attributes that are not returned by default. This endpoint defaults to use offset-based pagination, yet also supports marker-based pagination using the `marker` parameter. parameters: - 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: limit description: The maximum number of items to return per page. in: query required: false example: 1000 schema: type: integer format: int64 maximum: 1000 - name: offset description: |- The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. in: query required: false example: 1000 schema: type: integer format: int64 default: 0 - name: usemarker description: |- Specifies whether to use marker-based pagination instead of offset-based pagination. Only one pagination method can be used at a time. By setting this value to true, the API will return a `marker` field that can be passed as a parameter to this endpoint to get the next page of the response. in: query required: false example: true schema: type: boolean - name: marker description: >- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. in: query required: false example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii schema: type: string - name: direction description: >- The direction to sort results in. This can be either in alphabetical ascending (`ASC`) or descending (`DESC`) order. in: query required: false example: ASC schema: type: string enum: - ASC - DESC - name: sort description: |- Defines the **second** attribute by which items are sorted. Items are always sorted by their `type` first, with folders listed before files, and files listed before web links. This parameter is not supported when using marker-based pagination. in: query required: false example: name schema: type: string enum: - name - date - size responses: '200': description: Returns a list of items that have been deleted content: application/json: schema: $ref: '#/components/schemas/Items' '400': description: >- Returns an error if some of the parameters are missing or not valid. * `invalid_parameter` can appear when the `sort`, `direction` or `offset` parameter is provided when using marker based pagination, or when the `marker` parameter is provided but `usemarker` is set to `false` or `null`. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' /folders/{folder_id}/watermark: get: operationId: get_folders_id_watermark summary: Box Get watermark for folder tags: - Folders x-box-tag: folder_watermarks description: Retrieve the watermark for a folder. parameters: - name: folder_id description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: '12345' in: path required: true schema: type: string nullable: false responses: '200': description: |- Returns an object containing information about the watermark associated for to this folder. content: application/json: schema: $ref: '#/components/schemas/Watermark' '404': description: Returns an error if the folder does not have a watermark applied. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' put: operationId: put_folders_id_watermark summary: Box Apply watermark to folder tags: - Folders x-box-tag: folder_watermarks description: Applies or update a watermark on a folder. parameters: - name: folder_id description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: '12345' in: path required: true schema: type: string nullable: false requestBody: content: application/json: schema: type: object required: - watermark properties: watermark: type: object description: The watermark to imprint on the folder required: - imprint properties: imprint: type: string example: default description: |- The type of watermark to apply. Currently only supports one option. enum: - default responses: '200': description: |- Returns an updated watermark if a watermark already existed on this folder. content: application/json: schema: $ref: '#/components/schemas/Watermark' '201': description: |- Returns a new watermark if no watermark existed on this folder yet. content: application/json: schema: $ref: '#/components/schemas/Watermark' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' delete: operationId: delete_folders_id_watermark summary: Box Remove watermark from folder tags: - Folders x-box-tag: folder_watermarks description: Removes the watermark from a folder. parameters: - name: folder_id description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: '12345' in: path required: true schema: type: string nullable: false responses: '204': description: |- An empty response will be returned when the watermark was successfully deleted. '404': description: |- Returns an error if the folder did not have a watermark applied to it content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' /folders/{folder_id}#get_shared_link: get: operationId: get_folders_id#get_shared_link summary: Box Get shared link for folder tags: - Folders x-box-tag: shared_links_folders x-box-enable-explorer: true x-box-sanitized: true description: Gets the information for a shared link on a folder. parameters: - name: folder_id description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: '12345' in: path required: true schema: type: string nullable: false - name: fields description: |- Explicitly request the `shared_link` fields to be returned for this item. example: shared_link in: query required: true schema: type: string responses: '200': description: |- Returns the base representation of a folder with the additional shared link information. content: application/json: schema: $ref: '#/components/schemas/Folder--Full' examples: default: value: id: '12345' type: folder etag: '1' shared_link: url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1 download_url: >- https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf vanity_url: vanity_name: effective_access: open effective_permission: can_download is_password_enabled: false unshared_at: '2020-09-21T10:34:41-07:00' download_count: 0 preview_count: 0 access: open permissions: can_preview: true can_download: true can_edit: false '401': description: >- Returned when the access token provided in the `Authorization` header is not recognized or not provided. content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: |- Returned if the folder is not found, or the user does not have access to the folder. content: application/json: schema: $ref: '#/components/schemas/ClientError' '405': description: Returned if the `folder_id` is not in a recognized format. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' /folders/{folder_id}#add_shared_link: put: operationId: put_folders_id#add_shared_link summary: Box Add shared link to folder tags: - Folders x-box-tag: shared_links_folders x-box-enable-explorer: true x-box-sanitized: true description: Adds a shared link to a folder. parameters: - name: folder_id description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: '12345' in: path required: true schema: type: string nullable: false - name: fields description: |- Explicitly request the `shared_link` fields to be returned for this item. example: shared_link in: query required: true schema: type: string requestBody: content: application/json: schema: type: object properties: shared_link: description: >- The settings for the shared link to create on the folder. Use an empty object (`{}`) to use the default settings for shared links. type: object properties: access: type: string description: >- The level of access for the shared link. This can be restricted to anyone with the link (`open`), only people within the company (`company`) and only those who have been invited to the folder (`collaborators`). If not set, this field defaults to the access level specified by the enterprise admin. To create a shared link with this default setting pass the `shared_link` object with no `access` field, for example `{ "shared_link": {} }`. The `company` access level is only available to paid accounts. enum: - open - company - collaborators example: open password: type: string description: >- The password required to access the shared link. Set the password to `null` to remove it. Passwords must now be at least eight characters long and include a number, upper case letter, or a non-numeric or non-alphabetic character. A password can only be set when `access` is set to `open`. example: do-n8t-use-this-Password vanity_name: type: string description: >- Defines a custom vanity name to use in the shared link URL, for example `https://app.box.com/v/my-shared-link`. Custom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links. minLength: 12 example: my-shared-link unshared_at: type: string format: date-time example: '2012-12-12T10:53:43-08:00' description: >- The timestamp at which this shared link will expire. This field can only be set by users with paid accounts. The value must be greater than the current date and time. permissions: type: object properties: can_download: type: boolean example: true description: |- If the shared link allows for downloading of files. This can only be set when `access` is set to `open` or `company`. can_preview: type: boolean example: true description: >- If the shared link allows for previewing of files. This value is always `true`. For shared links on folders this also applies to any items in the folder. can_edit: type: boolean example: false description: |- This value can only be `false` for items with a `type` of `folder`. responses: '200': description: |- Returns the base representation of a folder with a new shared link attached. content: application/json: schema: $ref: '#/components/schemas/Folder--Full' examples: default: value: id: '12345' type: folder etag: '1' shared_link: url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1 download_url: >- https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf vanity_url: vanity_name: effective_access: open effective_permission: can_download is_password_enabled: false unshared_at: '2020-09-21T10:34:41-07:00' download_count: 0 preview_count: 0 access: open permissions: can_preview: true can_download: true can_edit: false '400': description: Returned when there is an incorrect permission combination content: application/json: schema: $ref: '#/components/schemas/ClientError' '401': description: >- Returned when the access token provided in the `Authorization` header is not recognized or not provided. content: application/json: schema: $ref: '#/components/schemas/ClientError' '403': description: >- Returned if the user does not have all the permissions to complete the update. content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: |- Returned if the folder is not found, or the user does not have access to the folder. content: application/json: schema: $ref: '#/components/schemas/ClientError' '405': description: Returned if the `folder_id` is not in a recognized format. content: application/json: schema: $ref: '#/components/schemas/ClientError' '412': description: >- Returns an error when the `If-Match` header does not match the current `etag` value of the folder. This indicates that the folder has changed since it was last requested. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' /folders/{folder_id}#update_shared_link: put: operationId: put_folders_id#update_shared_link summary: Box Update shared link on folder tags: - Folders x-box-tag: shared_links_folders x-box-enable-explorer: true x-box-sanitized: true description: Updates a shared link on a folder. parameters: - name: folder_id description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: '12345' in: path required: true schema: type: string nullable: false - name: fields description: |- Explicitly request the `shared_link` fields to be returned for this item. example: shared_link in: query required: true schema: type: string requestBody: content: application/json: schema: type: object properties: shared_link: description: The settings for the shared link to update. type: object properties: access: type: string description: >- The level of access for the shared link. This can be restricted to anyone with the link (`open`), only people within the company (`company`) and only those who have been invited to the folder (`collaborators`). If not set, this field defaults to the access level specified by the enterprise admin. To create a shared link with this default setting pass the `shared_link` object with no `access` field, for example `{ "shared_link": {} }`. The `company` access level is only available to paid accounts. enum: - open - company - collaborators example: open password: type: string description: >- The password required to access the shared link. Set the password to `null` to remove it. Passwords must now be at least eight characters long and include a number, upper case letter, or a non-numeric or non-alphabetic character. A password can only be set when `access` is set to `open`. example: do-n8t-use-this-Password vanity_name: type: string description: >- Defines a custom vanity name to use in the shared link URL, for example `https://app.box.com/v/my-shared-link`. Custom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links. minLength: 12 example: my-shared-link unshared_at: type: string format: date-time example: '2012-12-12T10:53:43-08:00' description: >- The timestamp at which this shared link will expire. This field can only be set by users with paid accounts. The value must be greater than the current date and time. permissions: type: object properties: can_download: type: boolean example: true description: |- If the shared link allows for downloading of files. This can only be set when `access` is set to `open` or `company`. can_preview: type: boolean example: true description: >- If the shared link allows for previewing of files. This value is always `true`. For shared links on folders this also applies to any items in the folder. can_edit: type: boolean example: false description: |- This value can only be `false` for items with a `type` of `folder`. responses: '200': description: >- Returns a basic representation of the folder, with the updated shared link attached. content: application/json: schema: $ref: '#/components/schemas/Folder--Full' examples: default: value: id: '12345' type: folder etag: '1' shared_link: url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1 download_url: >- https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf vanity_url: vanity_name: effective_access: open effective_permission: can_download is_password_enabled: false unshared_at: '2020-09-21T10:34:41-07:00' download_count: 0 preview_count: 0 access: open permissions: can_preview: true can_download: true can_edit: false '400': description: Returned when there is an incorrect permission combination content: application/json: schema: $ref: '#/components/schemas/ClientError' '401': description: >- Returned when the access token provided in the `Authorization` header is not recognized or not provided. content: application/json: schema: $ref: '#/components/schemas/ClientError' '403': description: >- Returned if the user does not have all the permissions to complete the update. content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: |- Returned if the folder is not found, or the user does not have access to the folder. content: application/json: schema: $ref: '#/components/schemas/ClientError' '405': description: Returned if the `folder_id` is not in a recognized format. content: application/json: schema: $ref: '#/components/schemas/ClientError' '412': description: >- Returns an error when the `If-Match` header does not match the current `etag` value of the folder. This indicates that the folder has changed since it was last requested. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' /folders/{folder_id}#remove_shared_link: put: operationId: put_folders_id#remove_shared_link summary: Box Remove shared link from folder tags: - Folders x-box-tag: shared_links_folders x-box-enable-explorer: true x-box-sanitized: true description: Removes a shared link from a folder. parameters: - name: folder_id description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: '12345' in: path required: true schema: type: string nullable: false - name: fields description: |- Explicitly request the `shared_link` fields to be returned for this item. example: shared_link in: query required: true schema: type: string requestBody: content: application/json: schema: type: object properties: shared_link: description: |- By setting this value to `null`, the shared link is removed from the folder. type: object example: nullable: true responses: '200': description: >- Returns a basic representation of a folder, with the shared link removed. content: application/json: schema: $ref: '#/components/schemas/Folder--Full' examples: default: value: id: '12345' type: folder etag: '1' shared_link: '401': description: >- Returned when the access token provided in the `Authorization` header is not recognized or not provided. content: application/json: schema: $ref: '#/components/schemas/ClientError' '403': description: >- Returned if the user does not have all the permissions to complete the update. content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: |- Returned if the folder is not found, or the user does not have access to the folder. content: application/json: schema: $ref: '#/components/schemas/ClientError' '405': description: Returned if the `folder_id` is not in a recognized format. content: application/json: schema: $ref: '#/components/schemas/ClientError' '412': description: >- Returns an error when the `If-Match` header does not match the current `etag` value of the folder. This indicates that the folder has changed since it was last requested. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' /users/{user_id}/folders/0: put: operationId: put_users_id_folders_0 x-box-tag: transfer summary: Box Transfer owned folders tags: - Users 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 transferred to another user. * `forbidden_by_policy`: Returned if ownership transfer 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--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 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' Collaborations: title: Collaborations type: object x-box-resource-id: collaborations x-box-tag: user_collaborations description: A list of collaborations 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: type: array description: A list of collaborations items: $ref: '#/components/schemas/Collaboration' TrashFolder: title: Trashed Folder type: object x-box-resource-id: trash_folder x-box-tag: trashed_folders description: Represents a trashed folder. required: - id - type - name - description - size - path_collection - created_by - modified_by - owned_by - item_status 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: '123456789' 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 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 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 (Trash) description: A list of parent folders for an item in the trash. 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: description: Array of folders for this item's path collection type: array items: type: object description: The parent folder for this item properties: type: type: string description: '`folder`' enum: - folder example: folder id: type: string description: The unique identifier that represent a folder. example: '123456789' sequence_id: type: string nullable: true example: description: This field is null for the Trash folder etag: type: string nullable: true example: description: This field is null for the Trash folder name: type: string description: The name of the Trash folder. example: Trash nullable: false - description: |- The tree of folders that this file 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: type: string description: >- The shared link for this folder. This will be `null` if a folder has been trashed, since the link will no longer be active. example: nullable: true folder_upload_email: type: string description: >- The folder upload email for this folder. This will be `null` if a folder has been trashed, since the upload will no longer work. example: nullable: true 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: trashed Metadatas: title: Metadata instances type: object x-box-resource-id: metadatas x-box-tag: file_metadata description: A list of metadata instances that have been applied to a file or folder. properties: entries: type: array description: A list of metadata instances, as applied to this file or folder. items: $ref: '#/components/schemas/Metadata' limit: description: The limit that was used for this page of results. example: 100 type: integer Classification: title: Classification type: object x-box-resource-id: classification x-box-tag: classifications description: |- An instance of the classification metadata template, containing the classification applied to the file or folder. To get more details about the classification applied to an item, request the classification metadata template. properties: Box__Security__Classification__Key: type: string example: Sensitive description: The name of the classification applied to the item. $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: securityClassification-6VMVochwUWo description: '`securityClassification-6VMVochwUWo`' enum: - securityClassification-6VMVochwUWo $scope: type: string example: enterprise_27335 description: |- The scope of the enterprise that this classification has been applied for. This will be in the format `enterprise_{enterprise_id}`. $version: type: integer example: 1 description: |- The version of the metadata instance. This version starts at 0 and increases every time a classification is updated. $type: type: string example: >- securityClassification-6VMVochwUWo-fd31537a-0f95-4d86-9f2b-5974a29978f8 description: |- The unique ID of this classification instance. This will be include the name of the classification template and a unique ID. $typeVersion: type: number example: 5 description: >- The version of the metadata template. This version starts at 0 and increases every time the template is updated. This is mostly for internal use. $canEdit: type: boolean example: true description: Whether an end user can change the classification. Metadata--Full: title: Metadata instance (Full) type: object x-box-resource-id: metadata--full x-box-variant: full description: |- An instance of a metadata template, which has been applied to a file or folder. allOf: - $ref: '#/components/schemas/Metadata' - properties: $canEdit: type: boolean example: true description: Whether the user can edit this metadata instance. $id: type: string format: uuid example: 01234500-12f1-1234-aa12-b1d234cb567e maxLength: 36 description: A UUID to identify the metadata instance. $type: type: string example: properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0 description: |- A unique identifier for the "type" of this instance. This is an internal system property and should not be used by a client application. $typeVersion: type: integer example: 2 description: |- The last-known version of the template of the object. This is an internal system property and should not be used by a client application. - additionalProperties: allOf: - {} - example: Aaron Levie - description: |- A value for each of the fields that are present on the metadata template. For the `global.properties` template this can be a list of zero or more fields, as this template allows for any generic key-value pairs to be stored stored in the template. x-box-example-key: name Watermark: title: Watermark type: object x-box-resource-id: watermark x-box-tag: file_watermarks description: |- A watermark is a semi-transparent overlay on an embedded file preview that displays a viewer's email address or user ID and the time of access over a file's content properties: watermark: type: object properties: created_at: type: string format: date-time description: When this watermark was created example: '2012-12-12T10:53:43-08:00' modified_at: type: string format: date-time description: When this task was modified example: '2012-12-12T10:53:43-08:00' tags: - name: Folders - name: Users