<!-- BusyBot node reference — https://busybot.net/tools/box/ -->

> Node: Box (`box`) · Action (binary) · v1
> Category: Data & Storage · Credentials: Box OAuth2 (`boxOAuth2`)
> Updated: 2026-08-16

# Box

> Manage files and folders in Box cloud content management

## Overview

The Box tool provides comprehensive file and folder management for Box cloud content management. It supports file operations (copy, delete, download, get metadata, search, share via collaboration, upload) and folder operations (create, delete, get metadata, search, share via collaboration, update properties). File download fetches binary content from Box and stores it in the binary store. File upload reads binary data from the item and uploads it to Box via multipart form data. Sharing creates Box collaborations with granular permission roles. Search supports both file and folder types with extensive filtering options. Uses OAuth2 authentication with automatic token refresh.

**Category:** Data & Storage  
**Tool Name:** `box`  
**Version:** 1

**Appearance:** Icon: `si-box` | Color: `#0061D5`

## Node Type

**Action (Binary)** — handles file/binary data operations

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool requires **Box OAuth2** credentials.
See the [Credentials Guide](https://busybot.net/credentials/box-oauth2/) for setup instructions.

### Resources

| Resource | Value |
|----------|-------|
| File | `file` |
| Folder | `folder` |

### Operations

Operations for the `file` resource:

| Operation | Value | Description |
|-----------|-------|-------------|
| Copy | `copy` | Copy a file |
| Delete | `delete` | Delete a file |
| Download | `download` | Download a file |
| Get | `get` | Get file metadata |
| Search | `search` | Search files |
| Share | `share` | Share a file via collaboration |
| Upload | `upload` | Upload a file |

Operations for the `folder` resource:

| Operation | Value | Description |
|-----------|-------|-------------|
| Create | `create` | Create a folder |
| Delete | `delete` | Delete a folder |
| Get | `get` | Get folder metadata |
| Search | `search` | Search folders |
| Share | `share` | Share a folder via collaboration |
| Update | `update` | Update folder properties |

### Parameters

#### File: Copy

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| File ID | `string` | Yes | — | The ID of the file to copy. |
| Parent ID | `string` | No | — | ID of the destination folder. If not defined, the file is copied to the root folder (0). |
| Additional Fields | `collection` | No | `{}` | Optional settings for the copy. |
| — Fields | `string` | No | — | Comma-separated list of attributes to include in the response. |
| — Name | `string` | No | — | An optional new name for the copied file. |
| — Version | `string` | No | — | An optional ID of the specific file version to copy. |

#### File: Delete

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| File ID | `string` | No | — | The ID of the file to delete. |

#### File: Download

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| File ID | `string` | No | — | The ID of the file to download. |
| Binary Property | `string` | Yes | `data` | Name of the binary property to write the downloaded file to. Names are case-sensitive — see the upstream node's Binary Data panel for the exact names to use. |

#### File: Get

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| File ID | `string` | No | — | The ID of the file to retrieve metadata for. |
| Additional Fields | `collection` | No | `{}` | Optional settings for the lookup. |
| — Fields | `string` | No | — | Comma-separated list of attributes to include in the response. |

#### File: Search

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Query | `string` | No | — | The search query. Matched against item names, descriptions, text content, and other fields. |
| Return All | `boolean` | No | `false` | Whether to return all results or only up to a given limit. |
| Limit | `number` | No | `100` | Max number of results to return. Accepts 1–500. _(shown when Return All is `false`)_ |
| Additional Fields | `collection` | No | `{}` | Filters and sorting for the search. |
| — Content Types | `string` | No | — | Comma-separated list of Box recognized content types. |
| — Created At Range | `fixedCollection` | No | `{}` | Restrict results to items created between two dates. Both ends must be set. |
| — — From | `string` | No | — | ISO 8601 date string for range start. |
| — — To | `string` | No | — | ISO 8601 date string for range end. |
| — Direction | `options` | No | — | Sort direction. |
| | | | | Options: `ASC`, `DESC` |
| — Fields | `string` | No | — | Comma-separated list of response attributes. |
| — File Extensions | `string` | No | — | Comma-separated list of file extensions (e.g., pdf,png,gif). |
| — Folder IDs | `string` | No | — | Comma-separated folder IDs to limit search scope. |
| — Scope | `options` | No | — | Limits search results to a scope. |
| | | | | Options: `user_content`, `enterprise_content` |
| — Size Range | `string` | No | — | Comma-separated byte size range (e.g., 1000000,5000000). |
| — Sort | `options` | No | `relevance` | Sort order for results. |
| | | | | Options: `relevance`, `modified_at` |
| — Trash Content | `options` | No | `non_trashed_only` | Controls if search results include trashed items. |
| | | | | Options: `non_trashed_only`, `trashed_only` |
| — Updated At Range | `fixedCollection` | No | `{}` | Restrict results to items updated between two dates. Both ends must be set. |
| — — From | `string` | No | — | ISO 8601 date string for range start. |
| — — To | `string` | No | — | ISO 8601 date string for range end. |
| — User IDs | `string` | No | — | Comma-separated owner user IDs to filter results. |

#### File: Share

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| File ID | `string` | No | — | The ID of the file to share. |
| Accessible By | `options` | No | — | The type of entity the file will be shared with. |
| | | | | Options: `group`, `user` |
| Use Email | `boolean` | No | `true` | Whether to identify the user by email or ID. _(shown when Accessible By is `user`)_ |
| Email | `string` | No | — | The email address of the user to share the file with. _(shown when Accessible By is `user` and Use Email is `true`)_ |
| User ID | `string` | No | — | The ID of the user to share the file with. _(shown when Accessible By is `user` and Use Email is `false`)_ |
| Group ID | `string` | No | — | The ID of the group to share the file with. _(shown when Accessible By is `group`)_ |
| Role | `options` | No | `editor` | The level of access granted. |
| | | | | Options: `coOwner` (all functional read/write access an editor has), `editor` (full read/write access), `previewer` (limited read access), `previewerUploader`, `uploader` (limited write access), `viewer` (read access), `viewerUploader` |
| Options | `collection` | No | `{}` | Optional settings for the collaboration. |
| — Can View Path | `boolean` | No | `false` | Whether invited users can see the entire parent path to the associated folder. |
| — Expires At | `string` | No | — | Expiration date for the collaboration (ISO 8601). |
| — Fields | `string` | No | — | Comma-separated list of response attributes. |
| — Notify | `boolean` | No | `false` | Whether to send email notification for the action. |

#### File: Upload

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| File Name | `string` | No | — | The name the file should be saved as in Box. |
| Binary File | `boolean` | Yes | `false` | Whether the data to upload should be taken from the binary field. |
| Binary Property | `string` | Yes | `data` | Name of the binary property containing the file to upload. Names are case-sensitive — see the upstream node's Binary Data panel for the exact names to use. _(shown when Binary File is `true`)_ |
| File Content | `string` | No | — | The text content of the file to upload. _(shown when Binary File is `false`)_ |
| Parent ID | `string` | No | — | ID of the parent folder to upload the file to. If not defined, it will be uploaded to the root folder. |

#### Folder: Create

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Name | `string` | Yes | — | Name for the new folder. |
| Parent ID | `string` | No | — | ID of the parent folder. If not defined, the folder is created in the root folder (0). |
| Options | `collection` | No | `{}` | Optional settings applied when the folder is created. |
| — Access | `options` | No | — | Email upload access level for the folder. |
| | | | | Options: `collaborators` (only emails from registered collaborator addresses are accepted), `open` (accepts emails from any address) |
| — Fields | `string` | No | — | Comma-separated list of response attributes. |

#### Folder: Delete

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Folder ID | `string` | No | — | The ID of the folder to delete. |
| Recursive | `boolean` | No | `false` | Whether to recursively delete a non-empty folder and all of its content. |

#### Folder: Get

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Folder ID | `string` | No | — | The ID of the folder to retrieve. |

#### Folder: Search

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Query | `string` | No | — | The search query. Matched against item names, descriptions, text content, and other fields. |
| Return All | `boolean` | No | `false` | Whether to return all results or only up to a given limit. |
| Limit | `number` | No | `100` | Max number of results to return. Accepts 1–500. _(shown when Return All is `false`)_ |
| Additional Fields | `collection` | No | `{}` | Filters and sorting for the search. |
| — Content Types | `string` | No | — | Comma-separated list of Box recognized content types. |
| — Created At Range | `fixedCollection` | No | `{}` | Restrict results to items created between two dates. Both ends must be set. |
| — — From | `string` | No | — | ISO 8601 date string. |
| — — To | `string` | No | — | ISO 8601 date string. |
| — Direction | `options` | No | — | Sort direction. |
| | | | | Options: `ASC`, `DESC` |
| — Fields | `string` | No | — | Comma-separated list of response attributes. |
| — File Extensions | `string` | No | — | Comma-separated list of file extensions. |
| — Folder IDs | `string` | No | — | Comma-separated folder IDs to limit search scope. |
| — Scope | `options` | No | — | Limits search results to a scope. |
| | | | | Options: `user_content`, `enterprise_content` |
| — Size Range | `string` | No | — | Comma-separated byte size range. |
| — Sort | `options` | No | `relevance` | Sort order. |
| | | | | Options: `relevance`, `modified_at` |
| — Trash Content | `options` | No | `non_trashed_only` | Controls if search results include trashed items. |
| | | | | Options: `non_trashed_only`, `trashed_only` |
| — Updated At Range | `fixedCollection` | No | `{}` | Restrict results to items updated between two dates. Both ends must be set. |
| — — From | `string` | No | — | ISO 8601 date string. |
| — — To | `string` | No | — | ISO 8601 date string. |
| — User IDs | `string` | No | — | Comma-separated owner user IDs. |

#### Folder: Share

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Folder ID | `string` | No | — | The ID of the folder to share. |
| Accessible By | `options` | No | `user` | The type of entity the folder will be shared with. |
| | | | | Options: `user`, `group` |
| Use Email | `boolean` | No | `true` | Whether to identify the user by email or ID. _(shown when Accessible By is `user`)_ |
| Email | `string` | No | — | The email address of the user to share the folder with. _(shown when Accessible By is `user` and Use Email is `true`)_ |
| User ID | `string` | No | — | The ID of the user to share the folder with. _(shown when Accessible By is `user` and Use Email is `false`)_ |
| Group ID | `string` | No | — | The ID of the group to share the folder with. _(shown when Accessible By is `group`)_ |
| Role | `options` | No | `editor` | The level of access granted. |
| | | | | Options: `coOwner` (all functional read/write access an editor has), `editor` (full read/write access), `previewer` (limited read access), `previewerUploader`, `uploader` (limited write access), `viewer` (read access), `viewerUploader` |
| Options | `collection` | No | `{}` | Optional settings for the collaboration. |
| — Can View Path | `boolean` | No | `false` | Whether invited users can see the entire parent path. |
| — Expires At | `string` | No | — | Expiration date for the collaboration (ISO 8601). |
| — Fields | `string` | No | — | Comma-separated list of response attributes. |
| — Notify | `boolean` | No | `false` | Whether to send email notification. |

#### Folder: Update

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Folder ID | `string` | Yes | — | The ID of the folder to update. |
| Update Fields | `collection` | No | `{}` | Properties to change on the folder. |
| — Can Non-Owners Invite | `boolean` | No | `false` | Whether users who are not the owner can invite new collaborators. |
| — Can Non-Owners View Collaborators | `boolean` | No | `false` | Whether non-owners can view other collaborations. |
| — Description | `string` | No | — | The description of this folder. |
| — Fields | `string` | No | — | Comma-separated list of response attributes. |
| — Is Collaboration Restricted To Enterprise | `boolean` | No | `false` | Whether new invites are restricted to enterprise users. |
| — Name | `string` | No | — | The new name for this folder. |
| — Parent ID | `string` | No | — | Move the folder to a new parent folder by providing its ID. |
| — Shared Link | `collection` | No | `{}` | Shared link configuration. |
| — — Access | `options` | No | `open` | Who can open the shared link. |
| | | | | Options: `collaborators` (only those invited to the folder), `company` (only people within the company), `open` (anyone with the link) |
| — — Password | `string` | No | — | Password required to access the shared link. |
| — — Permissions | `collection` | No | `{}` | What the shared link allows. |
| — — — Can Download | `boolean` | No | `false` | Whether the shared link allows downloading. |
| — — — Unshared At | `string` | No | — | Timestamp at which the shared link expires (ISO 8601). |
| — — — Vanity Name | `string` | No | — | Custom vanity name for the shared link URL. |
| — — Tags | `string` | No | — | Comma-separated tags for the folder. |

#### All Operations

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Box Account | `credential` | No | — | Connect your Box account via OAuth2. |
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. Accepts 1–100. |

## Output Data

Every operation produces exactly one output item per input item — nothing fans out, including the two search operations. The Box API response is merged onto the input item's JSON, so the properties you started with remain available. Binary data on the input item is forwarded.

| Resource / Operation | Output |
|----------------------|--------|
| File `copy`, File `get`, File `upload` | The Box file object — `id`, `name`, `size`, `parent`, and the rest of the fields Box returns. |
| File `download` | The item JSON unchanged, with the file attached as binary under the property named in **Binary Property**. |
| File `share`, Folder `share` | The Box collaboration object created for the invitation. |
| File `delete`, Folder `delete` | `success: true`. |
| File `search`, Folder `search` | An array of matching Box objects under `results` on a single item. |
| Folder `create`, Folder `get`, Folder `update` | The Box folder object. |

**Search results arrive as one array, not one item per hit.** Add a Split Out node on `results` when you want to process each match separately:

```json
{
  "results": [
    { "id": "12345", "type": "file", "name": "report.pdf" }
  ]
}
```

**Downloads.** The node reads the file's metadata first so the binary property carries Box's own file name, and takes the MIME type from the download response. Because the JSON is untouched, address the file through the binary property rather than the item JSON.

**Uploads.** With **Binary File** on, the bytes come from the named binary property; with it off, the text in **File Content** is uploaded instead. **File Name** sets the name in Box, and **Parent ID** the destination folder — leave it empty for the root folder.

Reference results downstream by expression, e.g. `{{ $json.id }}` or `{{ $json.results[0].name }}`.

## Usage Examples

- Download a file from Box by ID
- Upload a binary file to a Box folder
- Copy a file to another Box folder
- Search for files matching a query
- Share a folder with a user by email
- Create a new folder in Box
- Update folder properties including shared links

## Example Configuration

Download a file into the `data` binary property:

```json
{
  "type": "box",
  "parameters": {
    "resource": "file",
    "operation": "download",
    "fileId": "{{ $json.fileId }}",
    "binaryPropertyName": "data"
  }
}
```

Upload a binary file into a folder:

```json
{
  "type": "box",
  "parameters": {
    "resource": "file",
    "operation": "upload",
    "fileName": "{{ $json.title }}.pdf",
    "binaryData": true,
    "binaryPropertyName": "data",
    "parentId": "0"
  }
}
```

Upload plain text without any binary input:

```json
{
  "type": "box",
  "parameters": {
    "resource": "file",
    "operation": "upload",
    "fileName": "summary.txt",
    "binaryData": false,
    "fileContent": "{{ $json.summary }}",
    "parentId": "{{ $json.folderId }}"
  }
}
```

Search for recent PDFs inside a folder tree:

```json
{
  "type": "box",
  "parameters": {
    "resource": "file",
    "operation": "search",
    "query": "{{ $json.term }}",
    "returnAll": false,
    "limit": 50,
    "additionalFields": {
      "file_extensions": "pdf",
      "ancestor_folder_ids": "12345",
      "sort": "modified_at",
      "direction": "DESC",
      "trash_content": "non_trashed_only",
      "updatedRangeUi": {
        "updatedRangeValuesUi": {
          "from": "2026-01-01T00:00:00Z",
          "to": "2026-01-31T23:59:59Z"
        }
      }
    }
  }
}
```

Copy a file into another folder under a new name:

```json
{
  "type": "box",
  "parameters": {
    "resource": "file",
    "operation": "copy",
    "fileId": "{{ $json.id }}",
    "parentId": "67890",
    "additionalFields": {
      "name": "{{ $json.name }} (archive)"
    }
  }
}
```

Share a file with a user by email as a viewer:

```json
{
  "type": "box",
  "parameters": {
    "resource": "file",
    "operation": "share",
    "fileId": "{{ $json.id }}",
    "accessibleBy": "user",
    "useEmail": true,
    "email": "{{ $json.email }}",
    "role": "viewer",
    "options": {
      "notify": true,
      "expires_at": "2026-12-31T00:00:00Z"
    }
  }
}
```

Create a folder, then publish a password-protected shared link on it:

```json
{
  "type": "box",
  "parameters": {
    "resource": "folder",
    "operation": "create",
    "name": "{{ $json.projectName }}",
    "parentId": "0",
    "options": {
      "access": "collaborators"
    }
  }
}
```

```json
{
  "type": "box",
  "parameters": {
    "resource": "folder",
    "operation": "update",
    "folderId": "{{ $json.id }}",
    "updateFields": {
      "description": "Deliverables for {{ $json.projectName }}",
      "shared_link": {
        "access": "company",
        "password": "{{ $json.linkPassword }}",
        "permissions": {
          "can_download": true,
          "unshared_at": "2026-12-31T00:00:00Z"
        }
      }
    }
  }
}
```

Delete a folder and everything inside it:

```json
{
  "type": "box",
  "parameters": {
    "resource": "folder",
    "operation": "delete",
    "folderId": "{{ $json.id }}",
    "recursive": true
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Manage Box files and folders — download, upload, copy, delete, search, share, and update via the Box API.