Skip to main content
This document covers export_to_box (display name Box Export), which downloads a platform or HTTP file URL and uploads its bytes to the connected Box account. Box is a native REST integration, not an MCP or Composio tool.

​
Authentication and enablement

The tool uses the Box OAuth connector. The access token is injected through x-variable-service: "box" and is not shown as a per-run input. Box API and upload calls use the audited HTTP transport. Off by default. Enable the tool explicitly for each agent that needs Box export. The connector is registered only when BOX_CLIENT_ID / BOX_CLIENT_SECRET are configured, so on a deployment without a Box app the tool and the connector card are both absent rather than present-but-broken. Uploads are performed by the connected Box account, which is the workspace’s Box connection — not the individual user who ran the task. Files therefore appear in Box as owned by that account.

​
Inputs

Required:
  • file_url: source file URL, such as a platform storage URL or output from another file-producing tool.
  • file_name: destination file name in Box, such as report.md.
Optional:
  • folder_path: slash-separated destination folder, such as Clients/Acme. Missing folders are created segment by segment. Uploads to the Box root when omitted.
  • folder_id: Box folder id to upload into. Takes precedence over folder_path and skips path resolution. Box’s root folder id is 0.
  • conflict_behavior:
    • fail (default): return an error and leave the existing file untouched. Overwriting a file in the user’s own Box is not done implicitly.
    • replace: upload a new version of the existing file, keeping its Box file id and version history. Note this transfers the file twice (the initial upload gets a 409, then the new-version upload), so a repeated refresh-in-place of a large file is ~2x its size in egress each run.
    • rename: keep both, saving the new file as name_1.ext. The result reports renamed and the requested_file_name that was taken.
  • mime_type: output MIME type; inferred from file_name when omitted.

​
Upload behavior

  • Exports are limited to 50 MB, Box’s ceiling for the single-request upload endpoint. Larger files are rejected with an explicit error; chunked upload sessions are not implemented yet.
  • Empty source files are rejected explicitly.
  • Folder resolution reuses an existing folder when one matches, and returns a clear error when a file already occupies a path segment.
  • A folder created concurrently by another run is re-resolved rather than failing the upload.
  • rename tries name_1, name_2, … up to ten times before giving up, so a folder full of same-named files cannot spin. Underscore rather than a space: the names are generated, and spaces are worse in URLs and scripts.
  • Read requests may be retried; uploads are not blindly replayed after an ambiguous response.

​
Output

The structured result contains file_id, file_name, file_url, mime_type, file_size, folder_id, folder_path, conflict_behavior, replaced, renamed, requested_file_name (only when renamed), and completed_at. file_url is the https://app.box.com/file/<id> link — Box’s upload response carries no web URL, so it is derived from the returned file id. replaced distinguishes a new version of an existing file from a newly created one, and renamed flags that the stored name is not the one that was requested.

​
Errors

  • Missing source URL, missing file name, or an unknown conflict_behavior fails validation before upload.
  • A missing access token fails the run rather than calling Box unauthenticated.
  • 401 / 403 responses return an error naming scopes and folder permissions as the things to check — the usual cause is a Box app without root_readwrite or a folder the connected account cannot write.
  • A 409 on upload is surfaced as a name conflict and handled per conflict_behavior; with fail it is returned as an error.
  • Tokens, response bodies, and file content are never written to logs.