CONNECT APP
Build with Box
Platform for secure content management, workflow, and collaboration
File Storage
- OAuth
MCP
Give your agent Box tools
Every Box action is exposed as an MCP tool on Pipedream's remote server. Point a client at it with your end user's ID and Connect resolves that user's Box account for each tool call — you store no tokens.
// accessToken: mint a short-lived token with the Connect SDK — see the MCP guide
const transport = new StreamableHTTPClientTransport(
new URL("https://remote.mcp.pipedream.net/v3"),
{
requestInit: {
headers: {
Authorization: `Bearer ${accessToken}`,
"x-pd-project-id": "{project_id}",
"x-pd-environment": "production",
"x-pd-external-user-id": "{external_user_id}", // any stable ID for this user in your system
"x-pd-app-slug": "box",
},
},
},
)
const mcp = new Client({ name: "my-agent", version: "1.0.0" })
await mcp.connect(transport)
const { tools } = await mcp.listTools()
// e.g. run Add Comment:
const result = await mcp.callTool({
name: "box-add-comment",
arguments: {
folderId: "Parent Folder",
fileId: "File",
},
})# access_token: mint a short-lived token with the Connect SDK — see the MCP guide
headers = {
"Authorization": f"Bearer {access_token}",
"x-pd-project-id": "{project_id}",
"x-pd-environment": "production",
"x-pd-external-user-id": "{external_user_id}", # any stable ID for this user in your system
"x-pd-app-slug": "box",
}
async with streamablehttp_client("https://remote.mcp.pipedream.net/v3", headers=headers) as (read, write, _):
async with ClientSession(read, write) as session:
await session.initialize()
tools = await session.list_tools()
# e.g. run Add Comment:
result = await session.call_tool("box-add-comment", {
"folderId": "Parent Folder",
"fileId": "File",
})API PROXY
Call the Box API directly
For an endpoint with no pre-built tool, the Connect proxy forwards your request to the Box API with the connected user's credentials attached. You store no tokens and write no refresh logic.
const resp = await pd.proxy.get({
externalUserId: "{external_user_id}", // any stable ID for this user in your system
accountId: "apn_xxxxxxx",
url: "https://api.box.com/2.0/users/me",
})
// Any allowed Box endpoint works here. Pipedream attaches the
// connected account's credentials to the outgoing request.# The path segment is the target URL, URL-safe base64 encoded:
# https://api.box.com/2.0/users/me
curl "https://api.pipedream.com/v1/connect/{project_id}/proxy/aHR0cHM6Ly9hcGkuYm94LmNvbS8yLjAvdXNlcnMvbWU?external_user_id={external_user_id}&account_id=apn_xxxxxxx" \
-H "Authorization: Bearer {access_token}" \
-H "x-pd-environment: production"SDK
Run Box actions from your backend
Connect a user's Box account once, then run Add Comment on their behalf from your own code — TypeScript, Python, or plain HTTP.
import { PipedreamClient } from "@pipedream/sdk"
const pd = new PipedreamClient({
projectId: process.env.PIPEDREAM_PROJECT_ID!,
clientId: process.env.PIPEDREAM_CLIENT_ID!,
clientSecret: process.env.PIPEDREAM_CLIENT_SECRET!,
projectEnvironment: "production",
})
const result = await pd.actions.run({
id: "box-add-comment",
externalUserId: "{external_user_id}", // any stable ID for this user in your system
configuredProps: {
box: { authProvisionId: "apn_xxxxxxx" },
folderId: "Parent Folder",
fileId: "File",
},
})from pipedream import Pipedream
pd = Pipedream(
client_id="{oauth_client_id}",
client_secret="{oauth_client_secret}",
project_id="{project_id}",
project_environment="production",
)
result = pd.actions.run(
id="box-add-comment",
external_user_id="{external_user_id}", # any stable ID for this user in your system
configured_props={
"box": {"authProvisionId": "apn_xxxxxxx"},
"folderId": "Parent Folder",
"fileId": "File",
},
)curl -X POST https://api.pipedream.com/v1/connect/{project_id}/actions/run \
-H "Content-Type: application/json" \
-H "X-PD-Environment: production" \
-H "Authorization: Bearer {access_token}" \
-d '{
"external_user_id": "{external_user_id}",
"id": "box-add-comment",
"configured_props": {
"box": { "authProvisionId": "apn_xxxxxxx" },
"folderId": "Parent Folder",
"fileId": "File"
}
}'TOOLS
Box actions
On-demand operations your product or agent can configure and run on behalf of a connected user.
-
Add Comment
actionAdds a comment to a Box file. To mention a user, include@[user_id:name]in the message and Box will notify them by email. Use Get Comments to read existing comments on a file. See the documentation.Writev0.0.2 -
Create Box Sign Request
actionCreates a Box Sign signature request and sends it to the listed signers. Requires at least one signer, plus the document(s) to sign passed viaAdditional Options— eithersource_files(e.g.[{"id": "123456789", "type": "file"}]) or atemplate_id; Box rejects requests with no document source. The signed document and signing log are saved to theParent Folder. See the documentation.Writev0.0.9 -
Create Collaboration
actionAdds a collaboration for a user or group on a file or folder, granting them access with a role (editor, viewer, previewer, uploader, previewer uploader, viewer uploader, or co-owner). Item Type must befileorfolder. Invite users by email or user ID; groups must be invited by group ID only. Can View Path applies only to folder collaborations. Use Delete Collaboration to revoke access. See the documentation.Writev0.0.2 -
Create Folder
actionCreates a new empty folder within the specified parent folder. Parent folder ID0is the root (All Files). Folder names must be 1-255 characters, use only Unicode Basic Multilingual Plane (BMP) characters, and cannot contain non-printable characters,/or\, leading or trailing spaces, or be.or... Names must be unique within the parent (case-insensitive). Use List Folder Items to inspect contents, or Move Folder / Delete Folder to reorganize afterward. See folder name restrictions. See the documentation.Writev0.0.2 -
Create Shared Link
actionCreates or updates a shared link for a file or folder. Access levels:open,company, orcollaborators. A password can only be set when access isopen; download permission applies only when access isopenorcompany. A resource can have only one shared link at a time. See the documentation.Writev0.0.2 -
Delete Collaboration
actionRemoves a collaboration, revoking a user's or group's access to a file or folder. Use Create Collaboration to grant access first and obtain a collaboration ID from its response. See the documentation.Writev0.0.2 -
Delete Folder
actionDeletes a folder by moving it to trash (or permanently when enterprise settings require). Set Recursive totrueto delete non-empty folders and all contents; without it, deleting a non-empty folder fails. Deleting a large folder can take longer than Box's request timeout — Box then returns HTTP 503 while the deletion continues in the background, which this action reports as accepted (accepted: true). This cannot be undone from this action — use List Folder Items to verify contents first. See the documentation.Writev0.0.2 -
Download File
actionDownloads a file from Box to your workflow's/tmpdirectory and returns the saved file path. Use Get File Metadata to check the file's name and size first, or Get File Text to extract text content without downloading. See the documentationWritev0.0.12 -
Get Comments
actionFetches all comments on a Box file, paginating through every page and returning the full list. Use Add Comment to create a new comment on the file. See the documentation.Read-onlyv0.0.9 -
Get File Metadata
actionRetrieves metadata for a file (name, size, timestamps, path, and more). Optionally request specific fields. Use List File Versions for version history, or Download File for content. See the documentation.Read-onlyv0.0.2 -
Get File Text
actionExtracts the text content of a Box file using itsextracted_textrepresentation. Works for office documents, presentations, spreadsheets, PDFs, and plain-text or code files. Box does not generate this representation for images (they have no text layer) or for files larger than 500 MB, and the action fails with an error when the file has no text representation. Use Download File to fetch the raw file instead. See the documentationRead-onlyv0.0.3 -
List Collaborations
actionLists the collaborations (users and groups with access, and their roles) on a Box file or folder. Use this to find a collaboration ID before calling Delete Collaboration, or to audit who has access to an item. Item Type must befileorfolder. See the documentation.Read-onlyv0.0.2 -
List File Versions
actionLists prior versions of a file (does not include the current version). Box only tracks file versions for users with premium accounts, so this returns an empty list on free accounts. Use Get File Metadata for current file details, or Upload File Version to create a new version. See the documentation.Read-onlyv0.0.2 -
List Folder Items
actionLists files, folders, and web links in a Box folder. Use0for the root folder. Returns one page of results (default 100, max 1000). To find items by name or metadata across all folders, use Search Content instead. See the documentation.Read-onlyv0.0.3 -
List Folders
actionLists the subfolders directly inside a Box folder. Use0for the root folder. Returns one page of results (default 100, max 1000). Use List Folder Items instead to also include files and web links. See the documentation.Read-onlyv0.0.2 -
Move Folder
actionMoves a folder to a new parent folder. Optionally rename the folder while moving. Provide the source folder ID and destination parent folder ID (0for root). Cannot move a folder into itself or one of its descendants. When renaming, the new name must be 1-255 characters, use only Unicode Basic Multilingual Plane (BMP) characters, and cannot contain non-printable characters,/or\, leading or trailing spaces, or be.or... Use Create Folder to create a destination first if needed. See folder name restrictions. See the documentation.Writev0.0.2 -
Search Content
actionSearches for files, folders, and web links across the user's Box content by keyword and/or metadata filters — at least one ofQueryorMetadata Filtersis required. Matches item names, descriptions, and file text content; trashed items are excluded. Paginates through and returns all matching results. To browse a known folder instead, use List Folder Items. See the documentation.Read-onlyv0.0.12 -
Upload a File
actionUploads a file (max 50MB — Box's limit for direct uploads) to a Box folder. The file name must be unique within the parent folder (case-insensitive). Provide either a file URL or a path to a file in the/tmpdirectory. Use Upload File Version to update an existing file's content instead. See the documentation.Writev0.1.9 -
Upload File Version
actionUploads a new version of an existing Box file (max 50MB), replacing its current content; prior versions are kept in version history on premium accounts. Optionally rename the file at the same time. Use List File Versions to review version history afterward. See the documentation.Writev0.1.9
-
New Event
triggerEmit new event when any of the selected event types occurs on the target file or folder, via a Box webhook. See the documentationInstantv0.0.10 -
New File Event
triggerEmit new event when a file is uploaded to, or moved into, the target folder (FILE.UPLOADED), via a Box webhook. Box fires this trigger for both cases, so moving an existing file into the folder also emits an event. See the documentationInstantv0.1.5 -
New Folder Event
triggerEmit new event when a folder is created within the target folder (FOLDER.CREATED), via a Box webhook. See the documentationInstantv0.0.10
MULTI-APP
Use Box with other popular apps
Most products don't stop at one integration. Pair Box with the other apps your users rely on, and ship use cases that span both.
- App slug
- box
- Authentication
- OAuth
- Categories
- File Storage
- Actions
- 19
- Triggers
- 3
- API proxy
- Available