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

- 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

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