diff --git a/content/guides/archives/add-content.md b/content/guides/archives/add-content.md new file mode 100644 index 000000000..c0723c1e9 --- /dev/null +++ b/content/guides/archives/add-content.md @@ -0,0 +1,31 @@ +--- +rank: 1 +related_endpoints: + - post-archives + - put-files-id + - put-folders-id +related_resources: + - archive +related_guides: + - archives/restore-content +required_guides: [] +alias_paths: [] +--- + +# Add content to Box Archive + +To add content to an archive, you need to create it first. If you +have not done this yet, use the [Create Archive][Create Archive] endpoint. + +## Add file or folder to archive + +Use the [`PUT /files/:id`][Update file] API endpoint to add a file to an archive, or the [`PUT /folders/:id`][Update folder] endpoint to add a folder. +The `id` parameter is the ID of the file/folder you want to add to the archive. +To specify the destination, use the `parent.id` [parameter][Update parent id of folder] in the request body. +This can be either an ID of an archive or the ID of a folder that is inside an archive. + +[Create Archive]: e://post-archives +[Update file]: e://put-files-id +[Update parent id of file]: https://developer.box.com/reference/put-files-id/#param-parent-id +[Update folder]: e://put-folders-id +[Update parent id of folder]: https://developer.box.com/reference/put-folders-id/#param-parent-id diff --git a/content/guides/archives/index.md b/content/guides/archives/index.md new file mode 100644 index 000000000..10aeb7da1 --- /dev/null +++ b/content/guides/archives/index.md @@ -0,0 +1,47 @@ +--- +rank: 1 +related_endpoints: + - post-archives + - get-archives + - delete-archives-id + - put-files-id + - put-folders-id +related_resources: + - archive +related_guides: + - archives/add-content + - archives/restore-content + - archives/supported-apis +required_guides: [] +alias_paths: [] +--- + +# Box Archive + + +Box Archive is available only for Enterprise Advanced accounts. + + +Box Archive allows you to create and manage archives. An archive is a folder dedicated to +storing content that is redundant, outdated, or trivial. Content in an archive is owned by the enterprise, +and it is not accessible to previous owner and collaborators. + +## Archives are folders + +Archives are a special type of folders. Box Archive APIs allow you to create, list and delete archives. +However, there are other APIs that also work with archives or with content within archives. +For a full list of supported APIs, see the [Supported APIs][Supported APIs] guide. + +## Required scopes + +Before using any of the Box Archive APIs, make sure you can access [Box Archive in Admin Console][Box Archive in Admin Console]. +Your Box Platform app must have the `GCM` and `Read and write all files and folders` [scopes][Scopes] enabled. +If you plan to only view archives and not modify them, use the `Read all files and folders` instead of the `Read and write all files and folders` scope. + + +The `GCM` scope is not available in the Developer Console and needs to be enabled by contacting customer support. + + +[Supported APIs]: g://archives/supported-apis +[Box Archive in Admin Console]: https://support.box.com/hc/en-us/p/Product_Page_2023?section-id=40168863437843 +[Scopes]: https://developer.box.com/guides/api-calls/permissions-and-errors/scopes/ diff --git a/content/guides/archives/restore-content.md b/content/guides/archives/restore-content.md new file mode 100644 index 000000000..725f04f84 --- /dev/null +++ b/content/guides/archives/restore-content.md @@ -0,0 +1,33 @@ +--- +rank: 2 +related_endpoints: + - put-files-id + - put-folders-id +related_resources: + - archive +related_guides: + - archives/add-content +required_guides: [] +alias_paths: [] +--- + +# Restore content from Box Archive + +This guide describes how to restore content that you archived by mistake. + +## Restore file or folder from archive + +Use the [`PUT /files/:id`][Update file] API endpoint to restore a file from an archive, or the [`PUT /folders/:id`][Update folder] endpoint to restore a folder from an archive. +The `id` parameter is the ID of the file/folder you want to restore from an archive. +To specify the destination, use the `parent.id` [parameter][Update parent id of folder] in the request body. +This is the ID of a folder (can be owned by any user) where you want to restore the file/folder. + +To restore a file/folder to user's root folder, use `0` as the `parent.id` value. Additionally, pass the ID of the user in the +`parent.user_id` [parameter][Update parent user id of file] in the request body. + +[Update file]: e://put-files-id +[Update parent id of file]: https://developer.box.com/reference/put-files-id/#param-parent-id +[Update parent user id of file]: https://developer.box.com/reference/put-files-id/#param-parent-user_id +[Update folder]: e://put-folders-id +[Update parent id of folder]: https://developer.box.com/reference/put-folders-id/#param-parent-id +[Update parent user id of folder]: https://developer.box.com/reference/put-folders-id/#param-parent-user_id diff --git a/content/guides/archives/supported-apis.md b/content/guides/archives/supported-apis.md new file mode 100644 index 000000000..5e5bace93 --- /dev/null +++ b/content/guides/archives/supported-apis.md @@ -0,0 +1,73 @@ +--- +rank: 3 +related_endpoints: [] +related_resources: + - archive +related_guides: [] +required_guides: [] +alias_paths: [] +--- + +# Supported APIs for Box Archive + +The basic Box Archive APIs allow you to create, list and delete archives, but you can use other APIs to interact with an archive or its content. +See the table below for the full list of those APIs. + + + Those APIs require the [`GCM` scope][GCM scope] to be enabled in your application. + This scope is not available in the Developer Console and needs to be enabled by contacting customer support. + + Additionally, some of the below APIs need to be enabled by contacting customer support to properly work with Box Archive. + When contacting customer support, specify the user ID you plan to use those APIs with. + + +| API Endpoint | Description | +|-------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [`POST /archives`][Create archive] | Create an archive. | +| [`GET /archives`][List archives] | List all archives. | +| [`DELETE /archives/:id`][Delete archive] | Delete an archive. | +| [`PUT /files/:id`][Update file] | Add a file to an archive, restore a file from an archive, or move file within/between archives. Other updates to the file are not allowed. Requires contacting customer support to enable. | +| [`PUT /folders/:id`][Update folder] | Add a folder to an archive, restore a folder from an archive, or move folder within/between archives. Other updates to the folder are not allowed. Requires contacting customer support to enable. | +| [`POST /files/content`][Upload file] | Upload a file to an archive or to folder within archive. Requires contacting customer support to enable. | +| [`GET /files/:id/content`][Download file] | Download a file from an archive or from folder within archive. | +| [`POST /zip_downloads`][Download zip] | Download a zip file of an archive or of a folder within archive. | +| [`POST /folders`][Create folder within archive] | Create a folder within an archive. Requires contacting customer support to enable. | +| [`GET /files/:id`][Get file details] | Get details of a file within an archive. | +| [`GET /folders/:id`][Get folder details] | Get details of archive or a folder within an archive. | +| [`GET /folders/:id/items`][List folder items] | List items within an archive or a folder within an archive. | +| [`POST /files/:id/copy`][Copy file] | Copy a file within an archive or to another archive. | +| [`POST /folders/:id/copy`][Copy folder] | Copy a folder within an archive or to another archive. | +| [`POST /files/:id/metadata/:scope/:template_key`][Create metadata on file] | Create metadata instance on a file within an archive. | +| [`GET /files/:id/metadata/:scope/:template_key`][View metadata on file] | View metadata instance on a file within an archive. | +| [`GET /files/:id/metadata`][List metadata on file] | List all metadata instances on a file within an archive. | +| [`PUT /files/:id/metadata/:scope/:template_key`][Update metadata on file] | Update metadata instance on a file within an archive. | +| [`DELETE /files/:id/metadata/:scope/:template_key`][Delete metadata on file] | Delete metadata instance on a file within an archive. | +| [`POST /files/:id/metadata/enterprise/securityClassification/6VMVochwUWo`][Create classification label on file] | Create a classification label on a file within an archive. | +| [`GET /files/:id/metadata/enterprise/securityClassification/6VMVochwUWo`][View classification label on file] | View a classification label on a file within an archive. | +| [`PUT /files/:id/metadata/enterprise/securityClassification/6VMVochwUWo`][Update classification label on file] | Update a classification label on a file within an archive. | +| [`DELETE /files/:id/metadata/enterprise/securityClassification/6VMVochwUWo`][Delete classification label on file] | Delete a classification label on a file within an archive. | + +[Create archive]: e://post-archives +[List archives]: e://get-archives +[Delete archive]: e://delete-archives-id +[Update file]: e://put-files-id +[Update folder]: e://put-folders-id +[Upload file]: e://post-files-content +[Download file]: e://get-files-id-content +[Download zip]: e://post-zip-downloads +[Create folder within archive]: e://post-folders +[Get file details]: e://get-files-id +[Get folder details]: e://get-folders-id +[List folder items]: e://get-folders-id-items +[Copy file]: e://post-files-id-copy +[Copy folder]: e://post-folders-id-copy +[Create metadata on file]: e://post-files-id-metadata-id-id +[View metadata on file]: e://get-files-id-metadata-id-id +[List metadata on file]: e://get-files-id-metadata +[Update metadata on file]: e://put-files-id-metadata-id-id +[Delete metadata on file]: e://delete-files-id-metadata-id-id +[Create classification label on file]: e://post-files-id-metadata-enterprise-securityClassification-6VMVochwUWo +[View classification label on file]: e://get-files-id-metadata-enterprise-securityClassification-6VMVochwUWo +[Update classification label on file]: e://put-files-id-metadata-enterprise-securityClassification-6VMVochwUWo +[Delete classification label on file]: e://delete-files-id-metadata-enterprise-securityClassification-6VMVochwUWo +[GCM scope]: https://developer.box.com/guides/api-calls/permissions-and-errors/scopes/#global-content-manager-gcm