> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jinba.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Box

> Manage files and folders in Box cloud storage

## Overview

The Box tools let you work with Box cloud storage from your flows: browse and search files, upload and download content, create and copy folders, share items via shared links or collaborators, and delete items.

## Key Features

* `BOX_LIST_FILES`
  * List files and folders in a Box folder with a compact response (id, name, type, size, modified date).
  * Inputs: `folder_id` (defaults to the root folder `"0"`), `limit` (1–1000, default 100).
* `BOX_LIST_FOLDER_ITEMS`
  * List files and folders in a Box folder including pagination metadata (`total_count`, `offset`, `next_marker`).
  * Inputs: `folder_id`, `limit`, `offset` (offset-based paging), `marker` and `use_marker_based_paging` (marker-based paging), `fields` (comma-separated Box fields to request).
* `BOX_SEARCH`
  * Search files and folders in Box by keyword.
  * Inputs: `query`, optional `file_extensions` (e.g. `"pdf,docx"`), optional `ancestor_folder_ids` to limit the search scope, `limit` (1–200, default 30).
* `BOX_GET_FILE_INFO`
  * Get metadata for a Box file or folder, including shared link information when requested.
  * Inputs: `item_id`, `item_type` (`file` or `folder`, default `file`), `fields`.
* `BOX_DOWNLOAD_FILE`
  * Download a file from Box and return its content as base64, along with the file name and size.
  * Inputs: `file_id`. Files up to 50MB are supported.
* `BOX_UPLOAD_FILE`
  * Upload a file to Box. Accepts base64 content, a data URL (`data:<mime>;base64,...`), or an HTTPS URL.
  * Inputs: `file`, optional `filename` (extracted from the file URL if omitted), `folder_id` (default root `"0"`). Returns the new `file_id` and `name`.
* `BOX_CREATE_FOLDER`
  * Create a new folder in Box.
  * Inputs: `name`, `parent_folder_id` (default root `"0"`).
* `BOX_COPY_FOLDER`
  * Copy a folder to another location, optionally renaming it. Handles Box's asynchronous copy by polling until completion.
  * Inputs: `source_folder_id`, `parent_folder_id` (default `"0"`), optional `name`, `wait_for_completion` (default `true`), `max_poll_attempts` (0–30, default 10), `poll_interval_ms` (0–30000, default 1000).
* `BOX_ADD_COLLABORATOR`
  * Invite a user or group as a collaborator on a Box file or folder.
  * Inputs: `item_id`, `item_type` (default `folder`), `login` (email to invite) or `accessible_by_id` (existing Box user/group ID), `accessible_by_type` (`user` or `group`), `role` (`editor` (default), `viewer`, `previewer`, `uploader`, `previewer uploader`, `viewer uploader`, `co-owner`), `notify` (default `true`).
* `BOX_CREATE_SHARED_LINK`
  * Create a shared link for a Box file or folder.
  * Inputs: `item_id`, `item_type` (default `file`), optional `access` (`open`, `company`, or `collaborators`), optional `password`, optional `unshared_at` (ISO date-time expiration), optional `can_download`.
* `BOX_DELETE_ITEM`
  * Delete one or more Box files or folders.
  * Inputs: a single `item_id` with `item_type`, or multiple `ids` with `types`, or an `items` array of `{ "id": "...", "type": "file|folder" }`; `recursive` (default `false`) to delete non-empty folders. Returns `deleted_items` and `failed_items`.

## Authentication

All Box tools require a Box OAuth access token (`token` in the tool config, secret type `BOX_OAUTH`).

Go to the [Jinba secrets dashboard](https://flow.jinba.io/workspace/secrets) and connect your Box account. This creates a `BOX_OAUTH` secret, and the platform refreshes the access token automatically when it expires. Reference the token in the tool config as shown below.

**Note**: Treat credentials as sensitive information and never commit them to public repositories.

## Usage Examples

### Example: Search for PDFs and download the first match

```yaml theme={null}
- id: search_reports
  name: search_reports
  tool: BOX_SEARCH
  config:
    - name: token
      value: "{{secrets.BOX_OAUTH.access_token}}"
  input:
    - name: query
      value: "monthly report"
    - name: file_extensions
      value: "pdf"
    - name: limit
      value: 10

- id: download_report
  name: download_report
  tool: BOX_DOWNLOAD_FILE
  config:
    - name: token
      value: "{{secrets.BOX_OAUTH.access_token}}"
  input:
    - name: file_id
      value: "{{steps.search_reports.result.entries[0].id}}"
```

### Example: Create a project folder, upload a file, and share it

```yaml theme={null}
- id: create_folder
  name: create_folder
  tool: BOX_CREATE_FOLDER
  config:
    - name: token
      value: "{{secrets.BOX_OAUTH.access_token}}"
  input:
    - name: parent_folder_id
      value: "0"
    - name: name
      value: "Project Alpha Deliverables"

- id: upload_file
  name: upload_file
  tool: BOX_UPLOAD_FILE
  config:
    - name: token
      value: "{{secrets.BOX_OAUTH.access_token}}"
  input:
    - name: file
      value: "{{steps.generate_report.result.url}}"
    - name: filename
      value: "deliverable.pdf"
    - name: folder_id
      value: "{{steps.create_folder.result.folder.id}}"

- id: share_file
  name: share_file
  tool: BOX_CREATE_SHARED_LINK
  config:
    - name: token
      value: "{{secrets.BOX_OAUTH.access_token}}"
  input:
    - name: item_id
      value: "{{steps.upload_file.result.file_id}}"
    - name: item_type
      value: "file"
    - name: access
      value: "company"
```

## Notes

* **File size limits**: `BOX_DOWNLOAD_FILE` and `BOX_UPLOAD_FILE` support files up to 50MB. Larger files fail with an error (Box's chunked upload API is not supported).
* **Root folder**: The Box root folder always has ID `"0"`; folder-related inputs default to it.
* **Pagination**: `BOX_LIST_FILES` returns a compact list without pagination metadata (max 1000 items). Use `BOX_LIST_FOLDER_ITEMS` when you need `total_count`, offset-based paging, or marker-based paging via `next_marker`.
* **Search limits**: `BOX_SEARCH` returns at most 200 results per call.
* **Asynchronous folder copies**: Box may process large folder copies asynchronously. `BOX_COPY_FOLDER` polls until completion (up to `max_poll_attempts`); if the copy is still in progress, the result has `pending: true`.
* **Deleting folders**: Non-empty folders are only deleted when `recursive` is set to `true` in `BOX_DELETE_ITEM`.
* **Collaborator roles**: The `owner` role cannot be assigned via `BOX_ADD_COLLABORATOR` — Box only accepts the roles listed above when creating a collaboration.