VX Agents

OpenAPI Marketplace · Documents & E-signature

Box Files

v1.0.0 · 12 endpoints · 0 connections · shared by vx.ai

Lets an agent find and organise content in Box: search files and folders, browse folder contents, read file details and comments, get download and shared links, rename or move files, comment, and see who has access. Curated from Box's official OpenAPI specification.

Connect this API to an AI agent Browse all specs

What you can do with Box Files via MCP

Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.

MethodPathOperationDescription
GET /users/me getCurrentUser Get the Box user the token acts as
GET /search searchContent Search files and folders by name, content or metadata
GET /folders/{folder_id} getFolder Get folder details (use `0` for the root folder)
GET /folders/{folder_id}/items listFolderItems List the files and folders inside a folder
GET /files/{file_id} getFile Get file details, including its shared link when requested
PUT /files/{file_id} updateFile Rename, move or describe a file, or create/change its shared link
GET /files/{file_id}/content downloadFile Download a file (redirects to a short-lived download URL)
GET /files/{file_id}/comments listFileComments List the comments on a file
GET /shared_items findItemBySharedLink Open the file behind a Box shared link
GET /files/{file_id}/collaborations listFileCollaborations List who a file is shared with
GET /folders/{folder_id}/collaborations listFolderCollaborations List who a folder is shared with
POST /comments createComment Add a comment to a file

Authentication

boxBearer

Bearer token — sent as Authorization: Bearer <token>

Send a Box access token as Authorization: Bearer <token>: a developer token for testing, or an OAuth 2.0 / Client Credentials Grant token for production.

How to get a credential

  1. Open the Box Developer Console: https://app.box.com/developers/console and click Create Platform App > Custom App.
  2. For a quick test choose User Authentication (OAuth 2.0), open the Configuration tab and click Generate Developer Token (valid for 60 minutes).
  3. For long-running use choose Server Authentication (Client Credentials Grant), have a Box admin authorize the app (Admin Console > Integrations > Platform Apps Manager), then exchange the client id/secret at https://api.box.com/oauth2/token for an access token.
  4. Under Application Scopes, enable Read all files and folders and, for renames/comments/shared links, Write all files and folders.
  5. A service account (CCG) only sees content shared with it: add it as a collaborator on the folders the agent should use.

Permissions used

Scope Operations
root_readonly (Read all files and folders) getCurrentUser, searchContent, getFolder, listFolderItems, getFile, downloadFile, listFileComments, findItemBySharedLink, listFileCollaborations, listFolderCollaborations
root_readwrite (Write all files and folders) updateFile, createComment

Common errors

  • 401 Unauthorized: token expired (developer tokens last 60 minutes, OAuth tokens about 60 minutes) or revoked. Refresh or regenerate it.
  • 403 Forbidden (access_denied_insufficient_permissions): the app lacks the write scope or the user/service account is not a collaborator with enough rights.
  • 404 Not Found: wrong id, or the item is not shared with the authenticated user.
  • 400 Bad Request: invalid fields, a bad search query, or an invalid shared link access value for the enterprise.
  • 429 Too Many Requests: Box rate limit; wait for Retry-After and retry.

Store the access token as a VX Agents credential (Bearer token) for this spec; never paste it into chat.

Usage guide

Setup

  • Credential: a Box access token as a Bearer token (developer token for testing, OAuth 2.0 or Client Credentials Grant token for real use). The agent sees only what that user or service account can.
  • Worth pinning: the folder_id of the folder the agent should work in (the number at the end of app.box.com/folder/<id>); 0 is the root.

Find and share files

  1. searchContent with query, optional type=file|folder, file_extensions=pdf,docx, ancestor_folder_ids, updated_at_range (2026-10-01T00:00:00Z, for "since"), limit (max 200).
  2. Or browse: getFolder / listFolderItems (fields=name,modified_at,size,shared_link, limit up to 1000, page with offset).
  3. getFile with fields=name,size,modified_at,owned_by,shared_link,description for details; listFileComments to read discussion.
  4. Download link: downloadFile answers with a redirect to a short-lived URL; share that URL or the shared link, not the token.
  5. Share: updateFile with {"shared_link": {"access": "company"}} (or open, collaborators), then getFile with fields=shared_link for the URL. null removes the link.
  6. Rename or move: updateFile with {"name": "..."} or {"parent": {"id": "<folder_id>"}}.
  7. createComment with {"message": "...", "item": {"type": "file", "id": "<file_id>"}}.
  8. findItemBySharedLink opens a pasted link: send header boxapi: shared_link=<url> (add &shared_link_password=... if protected).
  9. listFileCollaborations / listFolderCollaborations show who has access.

Confirm before writing: show the user the change and wait for approval before updateFile (renames, moves, shared links: open links make a file public) or createComment.

Good to know

  • Ids are numeric strings. Uploads, deletes and new collaborations are not part of this spec.
  • Search finds new files only after indexing (a few minutes); browse the folder for just-added items.
  • Most responses only include basic fields unless you ask for more with fields.
  • 429 means rate limited: wait Retry-After seconds.

How to use this spec

  1. Create a free VX Agents account (sandbox tools included).
  2. Open the marketplace and connect “Box Files” to an agent.
  3. Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.