# Dropbox
{% hint style="info" %}
The following documentation is for **Dropbox v1.0.4** *(BDK)*.
{% endhint %}
## Overview
Dropbox provides cloud storage and file synchronization services for seamless file access across devices. This integration enables automated file uploads, downloads, sharing, and folder management within your Dropbox account. Streamline file management and ensure synchronized access to important documents.
## 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:
* **Dropbox**
#### 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.
### Connect using Dropbox API key
Connects to the Dropbox API using an API key.
| Label | Description | Type |
| --------------- | ----------------------------------------------------------------- | ----------- |
| Dropbox API key | The Dropbox API key (long-lived access token) for authentication. | `sensitive` |
## Procedures
### to create a folder at a path
Creates a folder at the specified path in Dropbox.
**Input Concepts**
| Concept | Description | Type | Required | Default Value |
| ------------ | ---------------------------------------------------------------------------------------------- | --------- | -------- | ------------- |
| `path` | The absolute path for the new folder (e.g., "/New Folder Name"). | `text` | Yes | (no default) |
| `autorename` | If true, Dropbox will automatically rename the folder if a conflict occurs. Defaults to False. | `boolean` | No | False |
**Output Concepts**
| Concept | Description | Type |
| ------------------------------------ | ----------------------------------------------- | ------------------------- |
| [`answer`](#dropbox-folder-metadata) | The FolderMetadata of the newly created folder. | `dropbox folder metadata` |
**Examples**
```generic
create a folder at "/"
```
```generic
create a folder at "/my/new/folder/path/"
```
### to delete an item and get the item reference
Deletes a file or folder in Dropbox using its metadata and returns the metadata of the deleted item.
**Input Concepts**
| Concept | Description | Type | Required | Default Value |
| ------- | -------------------------------------------------------------------------- | ---------------------------------------------------- | -------- | ------------- |
| `item` | The FileMetadata or FolderMetadata object representing the item to delete. | `dropbox file metadata` or `dropbox folder metadata` | Yes | (no default) |
**Output Concepts**
| Concept | Description | Type |
| ---------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `item reference` | Metadata (FileMetadata, FolderMetadata, or DeletedMetadata) of the deleted item. | `dropbox deleted metadata` or `dropbox file metadata` or `dropbox folder metadata` |
**Examples**
```generic
...
use the above as the file reference
delete the file reference and get the item reference
```
```generic
...
use the above as the folder reference
delete the folder reference and get the item reference
```
### to download a file
Downloads a file from Dropbox using its metadata.
**Input Concepts**
| Concept | Description | Type | Required | Default Value |
| -------------------------------- | ---------------------------------------------------------- | ----------------------- | -------- | ------------- |
| [`file`](#dropbox-file-metadata) | The FileMetadata object representing the file to download. | `dropbox file metadata` | Yes | (no default) |
**Output Concepts**
| Concept | Description | Type |
| -------- | ------------------------------------------------- | ------ |
| `answer` | An IO\[bytes] object containing the file content. | `file` |
**Examples**
```generic
...
use the above as the file reference
download the file reference
```
### to upload a file and get the file reference
Uploads a file to a specific path in Dropbox and returns its metadata.
Max file size 150MB. For larger files, use upload sessions.
**Input Concepts**
| Concept | Description | Type | Required | Default Value |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------- | --------- | -------- | ------------- |
| `file` | The file content as a byte stream (IO). | `file` | Yes | (no default) |
| `file name` | The name the file should have in Dropbox (e.g., "Matrices.txt"). | `text` | Yes | (no default) |
| `dropbox path` | The destination folder path in Dropbox where the file will be uploaded (e.g., "/Homework/math" or "/Homework/math/"). | `text` | Yes | (no default) |
| `mode` | Selects what to do if a file already exists. Can be "add", "overwrite", or "update". | `text` | No | add |
| `autorename` | If there's a conflict, autorename the file. | `boolean` | No | True |
| `mute` | Whether to mute notifications for this change. | `boolean` | No | False |
| `client modified timestamp` | The client's last modification timestamp (ISO 8601 UTC). | `text` | No | (no default) |
| `strict conflict` | If true, behaves like 'overwrite' but property groups are not updated. | `boolean` | No | False |
**Output Concepts**
| Concept | Description | Type |
| ------------------------------------------ | ----------------------------------------------------- | ----------------------- |
| [`file reference`](#dropbox-file-metadata) | A FileMetadata object representing the uploaded file. | `dropbox file metadata` |
**Examples**
```generic
...
use the above as the file
upload the file and get the file reference
```
## Concepts
### Dropbox folder metadata
Metadata for a folder in Dropbox.
| Field Name | Description | Type |
| ---------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------ |
| `name` | The name of the folder. | `text` |
| `id` | The unique ID of the folder. | `text` |
| `tag` | The type of the metadata object, always ".folder". | `optional[text]` |
| `path_lower` | The lowercased path of the folder in the user's Dropbox (optional). | `optional[text]` |
| `path_display` | The display-friendly path of the folder in the user's Dropbox (optional). | `optional[text]` |
| [`property_groups`](#dropbox-property-group) | A list of property groups associated with the folder (optional). | `optional[list of dropbox property group]` |
| [`sharing_info`](#dropbox-folder-sharing-info) | Sharing information for the folder (optional). | `optional[dropbox folder sharing info]` |
### Dropbox property group
A group of properties associated with a file.
| Field Name | Description | Type |
| ----------------------------------------- | ---------------------------------------------- | -------------------------------------- |
| `template_id` | The identifier of the property group template. | `text` |
| [`fields`](#dropbox-property-group-field) | A list of property fields. | `list of dropbox property group field` |
### Dropbox folder sharing info
Sharing information for a folder.
| Field Name | Description | Type |
| ------------------------- | --------------------------------------------------------- | ------------------- |
| `read_only` | True if the folder is read-only. | `boolean` |
| `parent_shared_folder_id` | The ID of the parent shared folder (optional). | `optional[text]` |
| `shared_folder_id` | The ID of the shared folder (optional). | `optional[text]` |
| `traverse_only` | True if the user can only traverse the folder (optional). | `optional[boolean]` |
| `no_access` | True if the user has no access to the folder (optional). | `optional[boolean]` |
### Dropbox file metadata
Metadata for a file in Dropbox.
| Field Name | Description | Type |
| -------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------ |
| `name` | The name of the file. | `text` |
| `id` | The unique ID of the file. | `text` |
| `client_modified` | The client's last modification timestamp (ISO 8601 UTC). | `text` |
| `server_modified` | The server's last modification timestamp (ISO 8601 UTC). | `text` |
| `rev` | A unique revision identifier for the file. | `text` |
| `size` | The size of the file in bytes. | `number` |
| `is_downloadable` | True if the file is downloadable. | `boolean` |
| `tag` | The type of the metadata object, always ".file". | `optional[text]` |
| `path_lower` | The lowercased path of the file in the user's Dropbox (optional). | `optional[text]` |
| `path_display` | The display-friendly path of the file in the user's Dropbox (optional). | `optional[text]` |
| [`property_groups`](#dropbox-property-group) | A list of property groups associated with the file (optional). | `optional[list of dropbox property group]` |
| [`sharing_info`](#dropbox-file-sharing-info) | Sharing information for the file (optional). | `optional[dropbox file sharing info]` |
| `has_explicit_shared_members` | True if the file has explicitly shared members (optional). | `optional[boolean]` |
| `content_hash` | A hash of the file content (optional). | `optional[text]` |
| [`file_lock_info`](#dropbox-file-lock-info) | File lock information if the file is locked (optional). | `optional[dropbox file lock info]` |
### Dropbox file sharing info
Sharing information for a file.
| Field Name | Description | Type |
| ------------------------- | ------------------------------------------------------ | ---------------- |
| `read_only` | True if the file is read-only. | `boolean` |
| `parent_shared_folder_id` | The ID of the parent shared folder (optional). | `optional[text]` |
| `modified_by` | The ID of the last user to modify the file (optional). | `optional[text]` |
### Dropbox file lock info
Metadata for a file lock.
| Field Name | Description | Type |
| ----------------- | ------------------------------------------- | ---------------- |
| `is_lockholder` | True if the current user is the lockholder. | `boolean` |
| `lockholder_name` | The display name of the lockholder. | `text` |
| `created` | The time the lock was created (optional). | `optional[text]` |
### Dropbox deleted metadata
Metadata for a deleted item in Dropbox.
| Field Name | Description | Type |
| -------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------ |
| `name` | The name of the deleted item. | `text` |
| `id` | The unique ID of the deleted item. | `text` |
| `tag` | The type of the metadata object, always ".deleted". | `optional[text]` |
| `path_lower` | The lowercased path of the deleted item (optional). | `optional[text]` |
| `path_display` | The display-friendly path of the deleted item (optional). | `optional[text]` |
| [`property_groups`](#dropbox-property-group) | A list of property groups associated with the deleted item (optional). | `optional[list of dropbox property group]` |