# Box
{% hint style="info" %}
The following documentation is for **Box v1.0.5** *(BDK)*.
{% endhint %}
## Overview
Box is a cloud content management and file sharing platform designed for secure business collaboration. This integration enables automated file uploads, downloads, folder management, and permission controls within your workflows. Enhance document workflows and maintain secure file sharing across your organization.
## Prerequisites
### 1. Required Books
The following Book(s) need to be added to your agent so it can learn and understand the automation procedures defined within them:
* **Box**
#### How to Add the Book(s)
1. Go to **Books** → **All Books**.
2. Search for the name of the book and click on it.
3. Click on **Install** or **Add Connection** to add the book to your agent.
4. If adding a connection, you'll be prompted for [**connectivity**](#connectivity) details.
## Connectivity
This section outlines the available methods for connecting to the Book, along with the required configuration details for each.
## Procedures
### to create a (folder) in another folder
Creates a new empty folder within the specified parent folder.
**Input Concepts**
| Concept | Description | Type | Required | Default Value |
| ----------------------------------------- | ------------------------------------------------ | ----------------------------------------- | -------- | ------------- |
| `folder name` | The name for the new folder. | `text` | Yes | (no default) |
| [`another folder`](#box-folder-reference) | A FolderReference for the parent folder. | `box folder reference` or `box item base` | Yes | (no default) |
| `fields` | A list of attributes to include in the response. | `text` | No | (no default) |
**Output Concepts**
| Concept | Description | Type |
| --------------------------------- | ------------------------------------------------------ | ----------------------------------------- |
| [`folder`](#box-folder-reference) | A FolderReference object for the newly created folder. | `box folder reference` or `box item base` |
**Examples**
```generic
retrieve the root folder reference
use the above as the parent folder
create a folder in the parent folder
```
### to delete an item and get an item reference
Deletes a file or folder by moving it to the trash. For folders, this is recursive.
**Input Concepts**
| Concept | Description | Type | Required | Default Value |
| ------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------ | -------- | ------------- |
| `item` | A FileReference or FolderReference object for the item to delete. | `box file reference` or `box folder reference` or `box item base` or `box item base` | Yes | (no default) |
**Output Concepts**
| Concept | Description | Type |
| ---------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------ |
| `item reference` | The reference of the item targeted for deletion. | `box file reference` or `box folder reference` or `box item base` or `box item base` |
**Examples**
```generic
retrieve the root folder reference
list the items in the folder
use the above as the item
delete the item
```
```generic
retrieve the root folder reference
list the items in the folder
get the first item
use the above as the item
delete the item
```
### to download a file
Downloads the content of a file.
**Input Concepts**
| Concept | Description | Type | Required | Default Value |
| ----------------------------- | ----------------------------------------------------------- | --------------------------------------- | -------- | ------------- |
| [`file`](#box-file-reference) | A FileReference for the file to download. | `box file reference` or `box item base` | Yes | (no default) |
| `version` | The specific version ID of the file to download (optional). | `text` | No | (no default) |
**Output Concepts**
| Concept | Description | Type |
| -------- | ------------------------------------------------- | ------ |
| `answer` | An IO\[bytes] object containing the file content. | `file` |
**Examples**
```generic
retrieve the root folder reference
list the items in the folder
use the above as the file
download the file
```
### to list (items) in a folder
Retrieves a page of item references from the specified folder.
**Input Concepts**
| Concept | Description | Type | Required | Default Value |
| --------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------- | -------- | ------------- |
| [`folder`](#box-folder-reference) | A FolderReference object for the folder whose items are to be listed. | `box folder reference` or `box item base` | Yes | (no default) |
| `fields` | A comma-separated list of attributes to include in the response for each item. | `text` | No | (no default) |
| `use marker` | Specifies whether to use marker-based pagination. | `boolean` | No | (no default) |
| `marker` | Defines the position marker at which to begin returning results (for marker-based pagination). | `text` | No | (no default) |
**Output Concepts**
| Concept | Description | Type |
| ------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `items` | A list of item references (FileReference, FolderReference, WebLinkMini). | `box file reference` or `box folder reference` or `box item base` or `box item base` or `box item base` or `box web link mini` |
**Examples**
```generic
retrieve the root folder reference
use the above as the folder
list the items in the folder
```
### to retrieve the (root folder reference)
Retrieves a reference to the root folder.
**Input Concepts**
| Concept | Description | Type | Required | Default Value |
| -------- | ------------------------------------------------------------------------------ | ------ | -------- | ------------- |
| `fields` | A list of attributes to include in the response for the root folder reference. | `text` | No | (no default) |
**Output Concepts**
| Concept | Description | Type |
| ------------------------------------------------ | ------------------------------------------------------ | ----------------------------------------- |
| [`root folder reference`](#box-folder-reference) | A FolderReference object representing the root folder. | `box folder reference` or `box item base` |
**Examples**
```generic
retrieve the root folder reference
```
```generic
retrieve the root folder reference
... the fields are name, id
```
### to upload a file and get a file reference
Uploads a file to Box. For files over 50MB, consider chunked upload APIs.
**Input Concepts**
| Concept | Description | Type | Required | Default Value |
| ---------------------------------------- | ------------------------------------------------------------ | ----------------------------------------- | -------- | ------------- |
| `file` | The content of the file as a byte stream. | `file` | Yes | (no default) |
| `file name` | The name the file should have in Box. | `text` | Yes | (no default) |
| [`parent folder`](#box-folder-reference) | A FolderReference for the parent folder. | `box folder reference` or `box item base` | Yes | (no default) |
| `content created at` | The RFC3339 timestamp of when the content was created. | `text` | No | (no default) |
| `content modified at` | The RFC3339 timestamp of when the content was last modified. | `text` | No | (no default) |
**Output Concepts**
| Concept | Description | Type |
| --------------------------------------- | --------------------------------------------- | --------------------------------------- |
| [`file reference`](#box-file-reference) | A FileReference object for the uploaded file. | `box file reference` or `box item base` |
**Examples**
```generic
...
use the above as the file
retrieve the root folder reference
use the above as the parent folder
upload the file to the parent folder
```
## Concepts
### Box folder reference
Represents a folder, often used in lists or as a parent reference (Folder--Mini like).
ALSO : `box item base`
| Field Name | Description | Type |
| ------------- | --------------------------------------------------------------------- | ---------------- |
| `id` | The unique identifier for this folder. | `text` |
| `type` | The type of this resource, typically "folder". (Set by this class) | `optional[text]` |
| `name` | The name of this folder. | `optional[text]` |
| `etag` | The HTTP ETag of this folder. | `optional[text]` |
| `sequence_id` | A numeric identifier of the most recent event applied to this folder. | `optional[text]` |
### Box file reference
Reference to a file, containing key identifying information from list views (File--Mini like).
ALSO : `box item base`
| Field Name | Description | Type |
| ------------------------------------------------------ | ----------------------------------------------- | --------------------------------------------------- |
| `id` | The unique identifier for this file. | `text` |
| `type` | The type, typically "file". (Set by this class) | `optional[text]` |
| `name` | The name of this file. | `optional[text]` |
| `etag` | The ETag of this file. | `optional[text]` |
| `sequence_id` | The sequence ID of this file. | `optional[text]` |
| `sha1` | The SHA1 hash of the file. | `optional[text]` |
| [`file_version`](#box-file-version-mini) | Mini representation of the file version. | `optional[box file version mini]` |
| [`parent`](#`box-folder-reference`-or-`box-item-base`) | The parent folder of this file. | `box item base]` or `optional[box folder reference` |
### Box file version mini
Minimal representation of a file version.
| Field Name | Description | Type |
| ---------- | ----------------------------------------------------- | ---------------- |
| `id` | The unique identifier for this file version. | `text` |
| `type` | The type of this resource, typically "file\_version". | `text` |
| `sha1` | The SHA1 hash of this version of the file. | `optional[text]` |
### Box item base
Mini representation of a web link.
ALSO : `box web link mini`
| Field Name | Description | Type |
| ------------- | ----------------------------------------------------------------------- | ---------------- |
| `id` | The unique identifier for this web link. | `text` |
| `type` | The type of this resource, typically "web\_link". (Set by this class) | `optional[text]` |
| `name` | The name of this web link. | `optional[text]` |
| `etag` | The HTTP ETag of this web link. | `optional[text]` |
| `sequence_id` | A numeric identifier of the most recent event applied to this web link. | `optional[text]` |
| `url` | The URL this web link points to. | `optional[text]` |