Skip to content

Create guides for Box Archive APIs #754

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
Jul 25, 2025
Merged

Create guides for Box Archive APIs #754

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
5c2d61e
Create guides for Box Archive APIs
psatala-box Jun 23, 2025
eef2bf3
Fix linter issue
psatala-box Jun 23, 2025
8e47949
Address review comments
psatala-box Jun 24, 2025
3340e20
Update list of supported APIs
psatala-box Jun 24, 2025
6d72996
Add information about contacting customer support
psatala-box Jun 25, 2025
3aece79
Add information about not allowing edits
psatala-box Jun 26, 2025
4eb8155
Address review comments
psatala-box Jun 27, 2025
9f64ff5
Update wording
psatala-box Jun 27, 2025
d91aab4
Apply review comments
psatala-box Jun 30, 2025
117a9bd
Apply review comments
psatala-box Jul 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions content/guides/archives/add-content.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
47 changes: 47 additions & 0 deletions content/guides/archives/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

<Message type='notice'>
Box Archive is available only for Enterprise Advanced accounts.
</Message>

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.

<Message type='notice'>
The `GCM` scope is not available in the Developer Console and needs to be enabled by contacting customer support.
</Message>

[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/
33 changes: 33 additions & 0 deletions content/guides/archives/restore-content.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
73 changes: 73 additions & 0 deletions content/guides/archives/supported-apis.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

<Message type='notice'>
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.
</Message>

| 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
Loading