Box connector

1. Install the SDK

   Node.js

   npm install @scalekit-sdk/node

   Python

   pip install scalekit

   Full SDK reference: Node.js | Python

2. Set your credentials

   Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

   .env

   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>

3. Set up the connector

   Register your Box credentials with Scalekit so it handles the token lifecycle. You do this once per environment.

   Dashboard setup steps

   Connect Box to Scalekit so your agent can manage files, folders, users, tasks, and more on behalf of your users. Box uses OAuth 2.0 — users authorize access through Box’s login flow, and Scalekit handles token storage and refresh automatically.

   You will need:

   • A Box developer account (free at developer.box.com)
   • Your Box OAuth app’s Client ID and Client Secret
   • The redirect URI from Scalekit to paste into Box

   1. Create a Box OAuth app

      • Go to the Box Developer Console and click Create New App.

      • Select Custom App as the app type.

      • Under authentication method, choose User Authentication (OAuth 2.0). This lets your agent act on behalf of each user who authorizes access.

      • Enter an app name (e.g. “My Agent App”) and click Create App.

      

   2. Copy the redirect URI from Scalekit

      • In Scalekit dashboard, go to AgentKit > Connections > Create Connection.
      • Find Box and click Create.
      • Click Use your own credentials and copy the redirect URI. It looks like: https://<env>.scalekit.cloud/sso/v1/oauth/<conn_id>/callback

      

   3. Add the redirect URI to Box

      • In the Box Developer Console, open your app and go to the Configuration tab.
      • Under OAuth 2.0 Redirect URI, paste the redirect URI from Scalekit and click Save Changes.

      

   4. Select scopes for your app

      Still on the Configuration tab in Box, scroll down to Application Scopes and enable the permissions your agent needs:

      Scope	Required for
      root_readonly	Reading files and folders
      root_readwrite	Creating, updating, and deleting files/folders
      manage_groups	Creating and managing groups
      manage_webhook	Creating and managing webhooks
      manage_managed_users	Creating and managing enterprise users
      manage_enterprise_properties	Accessing enterprise events

      Minimum required scope

      Enable at least root_readonly and root_readwrite to use the majority of Box tools. Add other scopes only for the tools you actually use.

      Click Save Changes after selecting scopes.

   5. Add credentials in Scalekit

      • In the Box Developer Console, open your app → Configuration tab.
      • Copy your Client ID and Client Secret.
      • In Scalekit dashboard, go to AgentKit > Connections, open the Box connection you created, and enter:
        • Client ID — from Box
        • Client Secret — from Box
        • Scopes — select the same scopes you enabled in Box (e.g. root_readonly, root_readwrite)

      

      • Click Save.

   6. Add a connected account for each user

      Each user who authorizes Box access becomes a connected account. During authorization, Box will show your app name and request the scopes you configured.

      Via dashboard (for testing)

      • In Scalekit dashboard, go to your Box connection → Connected Accounts → Add Account.
      • Enter a User ID (your internal identifier for this user, e.g. user_123).
      • Click Add — you will be redirected to Box’s OAuth consent screen to authorize.

      

      Via API (for production)

      In production, generate an authorization link and redirect your user to it:

      Node.js

      const { link } = await scalekit.actions.getAuthorizationLink({
        connectionName: 'box',
        identifier: 'user_123',
      });
      // Redirect your user to `link`

      Python

      link_response = scalekit_client.actions.get_authorization_link(
          connection_name="box",
          identifier="user_123",
      )
      # Redirect your user to link_response.link

      After the user authorizes, Scalekit stores their tokens. Your agent can then call Box tools on their behalf without any further redirects.

      Token refresh

      Scalekit automatically refreshes Box access tokens using the refresh token issued during authorization. If a user’s token ever expires, re-run the authorization link flow for that user.

4. Authorize and make your first call

   Node.js

   quickstart.ts

   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   
   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENV_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions
   
   const connector = 'box'
   const identifier = 'user_123'
   
   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Box:', link)
   process.stdout.write('Press Enter after authorizing...')
   await new Promise(r => process.stdin.once('data', r))
   
   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'box_collections_list',
     toolInput: {},
   })
   console.log(result)

   Python

   quickstart.py

   import os
   from scalekit.client import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()
   
   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENV_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions
   
   connection_name = "box"
   identifier = "user_123"
   
   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Box:", link_response.link)
   input("Press Enter after authorizing...")
   
   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="box_collections_list",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)

What you can do

Connect this agent connector to let your agent:

• Get file representations, webhook, web link — Retrieves available representations for a file, such as thumbnails, PDFs, or extracted text
• List webhooks, users, user memberships — Retrieves all webhooks for the application
• Update webhook, web link, user — Updates a webhook’s address or triggers
• Delete webhook, web link, user — Removes a webhook
• Create webhook, web link, user — Creates a webhook to receive event notifications
• Restore trash folder, trash file — Restores a folder from the trash

Common workflows

Proxy API call

Node.js

// List files in the root folder
const result = await actions.request({
  connectionName: 'box',
  identifier: 'user_123',
  path: '/2.0/folders/0/items',
  method: 'GET',
});
console.log(result);

Python

# List files in the root folder
result = actions.request(
    connection_name="box",
    identifier="user_123",
    path="/2.0/folders/0/items",
    method="GET",
)
print(result)

File upload

Box file uploads use a different base URL (upload.box.com) that is not covered by the Scalekit proxy. To upload files, extract the user’s OAuth token from the connected account and call the Box upload API directly using https://upload.box.com/api/2.0/files/content.

List folder contents

Start here to discover file and folder IDs. Use "0" for the root folder.

Node.js

const result = await actions.executeTool({
  toolName: 'box_folder_items_list',
  connector: 'box',
  identifier: 'user_123',
  toolInput: {
    folder_id: '0',  // root folder
  },
});
// result.entries[] contains files and folders with their IDs

Python

result = actions.execute_tool(
    tool_name="box_folder_items_list",
    connection_name='box',
    identifier='user_123',
    tool_input={"folder_id": "0"},
)
# result["entries"] contains files and folders with their IDs

Get file details

Node.js

const file = await actions.executeTool({
  toolName: 'box_file_get',
  connector: 'box',
  identifier: 'user_123',
  toolInput: { file_id: '12345678' },
});

Python

file = actions.execute_tool(
    tool_name="box_file_get",
    connection_name='box',
    identifier='user_123',
    tool_input={"file_id": "12345678"},
)

Search Box

Node.js

const results = await actions.executeTool({
  toolName: 'box_search',
  connector: 'box',
  identifier: 'user_123',
  toolInput: {
    query: 'quarterly report',
    type: 'file',
    file_extensions: 'pdf,docx',
  },
});

Python

results = actions.execute_tool(
    tool_name="box_search",
    connection_name='box',
    identifier='user_123',
    tool_input={
        "query": "quarterly report",
        "type": "file",
        "file_extensions": "pdf,docx",
    },
)

Create a task on a file

Node.js

const task = await actions.executeTool({
  toolName: 'box_task_create',
  connector: 'box',
  identifier: 'user_123',
  toolInput: {
    file_id: '12345678',
    message: 'Please review this document',
    action: 'review',
    due_at: '2025-12-31T00:00:00Z',
  },
});
// task.id is the task ID — use it with box_task_assignment_create

Python

task = actions.execute_tool(
    tool_name="box_task_create",
    connection_name='box',
    identifier='user_123',
    tool_input={
        "file_id": "12345678",
        "message": "Please review this document",
        "action": "review",
        "due_at": "2025-12-31T00:00:00Z",
    },
)
# task["id"] is the task ID

Share a file

Node.js

const link = await actions.executeTool({
  toolName: 'box_shared_link_file_create',
  connector: 'box',
  identifier: 'user_123',
  toolInput: {
    file_id: '12345678',
    access: 'company',   // open | company | collaborators
    can_download: true,
  },
});

Python

link = actions.execute_tool(
    tool_name="box_shared_link_file_create",
    connection_name='box',
    identifier='user_123',
    tool_input={
        "file_id": "12345678",
        "access": "company",
        "can_download": True,
    },
)

Create a webhook

Webhooks require the manage_webhook scope. The triggers field is an array of event strings.

Node.js

const webhook = await actions.executeTool({
  toolName: 'box_webhook_create',
  connector: 'box',
  identifier: 'user_123',
  toolInput: {
    target_id: '0',
    target_type: 'folder',
    address: 'https://your-app.com/webhooks/box',
    triggers: ['FILE.UPLOADED', 'FILE.DELETED', 'FOLDER.CREATED'],
  },
});

Python

webhook = actions.execute_tool(
    tool_name="box_webhook_create",
    connection_name='box',
    identifier='user_123',
    tool_input={
        "target_id": "0",
        "target_type": "folder",
        "address": "https://your-app.com/webhooks/box",
        "triggers": ["FILE.UPLOADED", "FILE.DELETED", "FOLDER.CREATED"],
    },
)

Add a collaborator to a folder

Collaborations grant a user or group access to a specific file or folder. You need the user’s Box ID or email login.

Node.js

// First, get the user's Box ID using box_users_list or box_user_me_get
const collab = await actions.executeTool({
  toolName: 'box_collaboration_create',
  connector: 'box',
  identifier: 'user_123',
  toolInput: {
    item_id: 'FOLDER_ID',
    item_type: 'folder',
    accessible_by_id: 'USER_BOX_ID',
    accessible_by_type: 'user',
    role: 'editor',
  },
});
// To find the collaboration ID later, use box_folder_collaborations_list

Python

collab = actions.execute_tool(
    tool_name="box_collaboration_create",
    connection_name='box',
    identifier='user_123',
    tool_input={
        "item_id": "FOLDER_ID",
        "item_type": "folder",
        "accessible_by_id": "USER_BOX_ID",
        "accessible_by_type": "user",
        "role": "editor",
    },
)
# To find the collaboration ID later, use box_folder_collaborations_list

Collaboration ID vs User ID

The collaboration_id used by box_collaboration_get, box_collaboration_update, and box_collaboration_delete is not the same as the user’s Box user ID. Fetch the collaboration ID from box_folder_collaborations_list or box_file_collaborations_list after creating the collaboration.

Tool list

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

box_collaboration_create#Grants a user or group access to a file or folder.8 params▾

Grants a user or group access to a file or folder.

NameTypeRequiredDescription

accessible_by_idstringrequiredID of the user or group to collaborate with.

accessible_by_typestringrequiredType: user or group.

item_idstringrequiredID of the file or folder.

item_typestringrequiredType of item: file or folder.

rolestringrequiredCollaboration role: viewer, previewer, uploader, previewer_uploader, viewer_uploader, co-owner, or editor.

can_view_pathstringoptionalAllow user to see path to item (true/false).

expires_atstringoptionalExpiry date in ISO 8601 format.

notifystringoptionalNotify collaborator via email (true/false).

box_collaboration_delete#Removes a collaboration, revoking user or group access.1 param▾

Removes a collaboration, revoking user or group access.

NameTypeRequiredDescription

collaboration_idstringrequiredID of the collaboration to delete.

box_collaboration_get#Retrieves details of a specific collaboration.3 params▾

Retrieves details of a specific collaboration.

NameTypeRequiredDescription

collaboration_idstringrequiredID of the collaboration.

fieldsstringoptionalComma-separated list of fields to return.

xero_tenant_idstringoptionalXero tenant (organisation) ID.

box_collaboration_update#Updates the role or status of a collaboration.5 params▾

Updates the role or status of a collaboration.

NameTypeRequiredDescription

collaboration_idstringrequiredID of the collaboration.

can_view_pathbooleanoptionalAllow user to see path to item.

expires_atstringoptionalNew expiry date in ISO 8601 format.

rolestringoptionalNew collaboration role.

statusstringoptionalCollaboration status: accepted or rejected.

box_collection_items_list#Retrieves the items in a collection (e.g. Favorites).4 params▾

Retrieves the items in a collection (e.g. Favorites).

NameTypeRequiredDescription

collection_idstringrequiredID of the collection.

fieldsstringoptionalComma-separated list of fields to return.

limitintegeroptionalMax results.

offsetintegeroptionalPagination offset.

box_collections_list#Retrieves all collections (e.g. Favorites) for the user.3 params▾

Retrieves all collections (e.g. Favorites) for the user.

NameTypeRequiredDescription

fieldsstringoptionalComma-separated list of fields to return.

limitintegeroptionalMax results.

offsetintegeroptionalPagination offset.

box_comment_create#Adds a comment to a file.4 params▾

Adds a comment to a file.

NameTypeRequiredDescription

item_idstringrequiredID of the file to comment on.

item_typestringrequiredType of item: file or comment.

messagestringrequiredText of the comment.

tagged_messagestringoptionalComment text with @mentions using @[user_id:user_name] syntax.

box_comment_delete#Removes a comment.1 param▾

Removes a comment.

NameTypeRequiredDescription

comment_idstringrequiredID of the comment to delete.

box_comment_get#Retrieves a comment.2 params▾

Retrieves a comment.

NameTypeRequiredDescription

comment_idstringrequiredID of the comment.

fieldsstringoptionalComma-separated list of fields to return.

box_comment_update#Updates the text of a comment.2 params▾

Updates the text of a comment.

NameTypeRequiredDescription

comment_idstringrequiredID of the comment to update.

messagestringrequiredNew text for the comment.

box_events_list#Retrieves events from the event stream.6 params▾

Retrieves events from the event stream.

NameTypeRequiredDescription

created_afterstringoptionalReturn events after this date (ISO 8601).

created_beforestringoptionalReturn events before this date (ISO 8601).

event_typestringoptionalComma-separated list of event types to filter.

limitintegeroptionalMax events to return.

stream_positionstringoptionalPagination position from a previous response.

stream_typestringoptionalEvent stream type: all, changes, sync, or admin_logs.

box_file_collaborations_list#Retrieves all collaborations on a file.2 params▾

Retrieves all collaborations on a file.

NameTypeRequiredDescription

file_idstringrequiredID of the file.

fieldsstringoptionalComma-separated list of fields to return.

box_file_comments_list#Retrieves all comments on a file.2 params▾

Retrieves all comments on a file.

NameTypeRequiredDescription

file_idstringrequiredID of the file.

fieldsstringoptionalComma-separated list of fields to return.

box_file_copy#Creates a copy of a file in a specified folder.3 params▾

Creates a copy of a file in a specified folder.

NameTypeRequiredDescription

file_idstringrequiredID of the file to copy.

parent_idstringrequiredID of the destination folder.

namestringoptionalNew name for the copied file (optional).

box_file_delete#Moves a file to the trash.1 param▾

Moves a file to the trash.

NameTypeRequiredDescription

file_idstringrequiredID of the file to delete.

box_file_get#Retrieves detailed information about a file.2 params▾

Retrieves detailed information about a file.

NameTypeRequiredDescription

file_idstringrequiredID of the file.

fieldsstringoptionalComma-separated list of fields to return.

box_file_metadata_create#Applies metadata to a file.4 params▾

Applies metadata to a file.

NameTypeRequiredDescription

data_jsonstringrequiredJSON object of metadata fields and values.

file_idstringrequiredID of the file.

scopestringrequiredScope: global or enterprise.

template_keystringrequiredMetadata template key.

box_file_metadata_delete#Removes a metadata instance from a file.3 params▾

Removes a metadata instance from a file.

NameTypeRequiredDescription

file_idstringrequiredID of the file.

scopestringrequiredScope: global or enterprise.

template_keystringrequiredMetadata template key.

box_file_metadata_get#Retrieves a specific metadata instance on a file.3 params▾

Retrieves a specific metadata instance on a file.

NameTypeRequiredDescription

file_idstringrequiredID of the file.

scopestringrequiredScope: global or enterprise.

template_keystringrequiredMetadata template key.

box_file_metadata_list#Retrieves all metadata instances attached to a file.1 param▾

Retrieves all metadata instances attached to a file.

NameTypeRequiredDescription

file_idstringrequiredID of the file.

box_file_representations_get#Retrieves available representations for a file, such as thumbnails, PDFs, or extracted text. Use the x_rep_hints parameter to request specific formats.2 params▾

Retrieves available representations for a file, such as thumbnails, PDFs, or extracted text. Use the x_rep_hints parameter to request specific formats.

NameTypeRequiredDescription

file_idstringrequiredID of the file.

x_rep_hintsstringrequiredHints for which representations to generate, e.g. [pdf][extracted_text][jpg?dimensions=320x320].

box_file_tasks_list#Retrieves all tasks associated with a file.1 param▾

Retrieves all tasks associated with a file.

NameTypeRequiredDescription

file_idstringrequiredID of the file.

box_file_thumbnail_get#Retrieves a thumbnail image for a file.4 params▾

Retrieves a thumbnail image for a file.

NameTypeRequiredDescription

extensionstringrequiredThumbnail format: jpg or png.

file_idstringrequiredID of the file.

min_heightintegeroptionalMinimum height of the thumbnail in pixels.

min_widthintegeroptionalMinimum width of the thumbnail in pixels.

box_file_update#Updates a file's name, description, tags, or moves it to another folder.5 params▾

Updates a file's name, description, tags, or moves it to another folder.

NameTypeRequiredDescription

file_idstringrequiredID of the file to update.

descriptionstringoptionalNew description for the file.

namestringoptionalNew name for the file.

parent_idstringoptionalID of the folder to move the file into.

tagsstringoptionalComma-separated list of tags. Pass as JSON string.

box_file_versions_list#Retrieves all previous versions of a file.1 param▾

Retrieves all previous versions of a file.

NameTypeRequiredDescription

file_idstringrequiredID of the file.

box_folder_collaborations_list#Retrieves all collaborations on a folder.2 params▾

Retrieves all collaborations on a folder.

NameTypeRequiredDescription

folder_idstringrequiredID of the folder.

fieldsstringoptionalComma-separated list of fields to return.

box_folder_copy#Creates a copy of a folder and its contents.3 params▾

Creates a copy of a folder and its contents.

NameTypeRequiredDescription

folder_idstringrequiredID of the folder to copy.

parent_idstringrequiredID of the destination folder.

namestringoptionalNew name for the copied folder (optional).

box_folder_create#Creates a new folder inside a parent folder.3 params▾

Creates a new folder inside a parent folder.

NameTypeRequiredDescription

namestringrequiredName of the new folder.

parent_idstringrequiredID of the parent folder. Use '0' for root.

fieldsstringoptionalComma-separated list of fields to return.

box_folder_delete#Moves a folder to the trash.2 params▾

Moves a folder to the trash.

NameTypeRequiredDescription

folder_idstringrequiredID of the folder to delete.

recursivestringoptionalDelete non-empty folders recursively (true/false).

box_folder_get#Retrieves a folder's details and its items.6 params▾

Retrieves a folder's details and its items.

NameTypeRequiredDescription

folder_idstringrequiredID of the folder. Use '0' for root.

directionstringoptionalSort direction: ASC or DESC.

fieldsstringoptionalComma-separated list of fields to return.

limitintegeroptionalMax items to return (max 1000).

offsetintegeroptionalPagination offset.

sortstringoptionalSort order: id, name, date, or size.

box_folder_items_list#Retrieves a paginated list of items in a folder.6 params▾

Retrieves a paginated list of items in a folder.

NameTypeRequiredDescription

folder_idstringrequiredID of the folder. Use '0' for root.

directionstringoptionalASC or DESC.

fieldsstringoptionalComma-separated list of fields to return.

limitintegeroptionalMax items to return (max 1000).

offsetintegeroptionalPagination offset.

sortstringoptionalSort field: id, name, date, or size.

box_folder_metadata_list#Retrieves all metadata instances on a folder.1 param▾

Retrieves all metadata instances on a folder.

NameTypeRequiredDescription

folder_idstringrequiredID of the folder.

box_folder_update#Updates a folder's name, description, or moves it.4 params▾

Updates a folder's name, description, or moves it.

NameTypeRequiredDescription

folder_idstringrequiredID of the folder to update.

descriptionstringoptionalNew description for the folder.

namestringoptionalNew name for the folder.

parent_idstringoptionalID of the new parent folder to move into.

box_group_create#Creates a new group in the enterprise.5 params▾

Creates a new group in the enterprise.

NameTypeRequiredDescription

namestringrequiredName of the group.

descriptionstringoptionalDescription of the group.

invitability_levelstringoptionalWho can invite to group: admins_only, admins_and_members, all_managed_users.

member_viewability_levelstringoptionalWho can view group members: admins_only, admins_and_members, all_managed_users.

provenancestringoptionalIdentifier to distinguish manually vs synced groups.

box_group_delete#Permanently deletes a group.1 param▾

Permanently deletes a group.

NameTypeRequiredDescription

group_idstringrequiredID of the group to delete.

box_group_get#Retrieves information about a group.2 params▾

Retrieves information about a group.

NameTypeRequiredDescription

group_idstringrequiredID of the group.

fieldsstringoptionalComma-separated list of fields to return.

box_group_members_list#Retrieves all members of a group.3 params▾

Retrieves all members of a group.

NameTypeRequiredDescription

group_idstringrequiredID of the group.

limitintegeroptionalMax results.

offsetintegeroptionalPagination offset.

box_group_membership_add#Adds a user to a group.3 params▾

Adds a user to a group.

NameTypeRequiredDescription

group_idstringrequiredID of the group.

user_idstringrequiredID of the user to add.

rolestringoptionalRole in the group: member or admin.

box_group_membership_get#Retrieves a specific group membership.2 params▾

Retrieves a specific group membership.

NameTypeRequiredDescription

group_membership_idstringrequiredID of the group membership.

fieldsstringoptionalComma-separated list of fields to return.

box_group_membership_remove#Removes a user from a group.1 param▾

Removes a user from a group.

NameTypeRequiredDescription

group_membership_idstringrequiredID of the group membership to remove.

box_group_membership_update#Updates a user's role in a group.2 params▾

Updates a user's role in a group.

NameTypeRequiredDescription

group_membership_idstringrequiredID of the membership to update.

rolestringoptionalNew role: member or admin.

box_group_update#Updates a group's properties.5 params▾

Updates a group's properties.

NameTypeRequiredDescription

group_idstringrequiredID of the group to update.

descriptionstringoptionalNew description.

invitability_levelstringoptionalWho can invite: admins_only, admins_and_members, all_managed_users.

member_viewability_levelstringoptionalWho can view members.

namestringoptionalNew name for the group.

box_groups_list#Retrieves all groups in the enterprise.4 params▾

Retrieves all groups in the enterprise.

NameTypeRequiredDescription

fieldsstringoptionalComma-separated list of fields to return.

filter_termstringoptionalFilter groups by name.

limitintegeroptionalMax results.

offsetintegeroptionalPagination offset.

box_metadata_template_get#Retrieves a metadata template schema.2 params▾

Retrieves a metadata template schema.

NameTypeRequiredDescription

scopestringrequiredScope of the template: global or enterprise.

template_keystringrequiredKey of the metadata template.

box_metadata_templates_list#Retrieves all metadata templates for the enterprise.2 params▾

Retrieves all metadata templates for the enterprise.

NameTypeRequiredDescription

limitintegeroptionalMax results.

markerstringoptionalPagination marker.

box_recent_items_list#Retrieves files and folders accessed recently.3 params▾

Retrieves files and folders accessed recently.

NameTypeRequiredDescription

fieldsstringoptionalComma-separated list of fields to return.

limitintegeroptionalMax results.

markerstringoptionalPagination marker.

box_search#Searches files, folders, and web links in Box.12 params▾

Searches files, folders, and web links in Box.

NameTypeRequiredDescription

querystringrequiredSearch query string.

ancestor_folder_idsstringoptionalComma-separated folder IDs to search within.

content_typesstringoptionalComma-separated content types: name, description, tag, comments, file_content.

created_at_rangestringoptionalDate range in ISO 8601: 2024-01-01T00:00:00Z,2024-12-31T23:59:59Z

fieldsstringoptionalComma-separated list of fields to return.

file_extensionsstringoptionalComma-separated file extensions to filter.

limitintegeroptionalMax results (max 200).

offsetintegeroptionalPagination offset.

owner_user_idsstringoptionalComma-separated user IDs.

scopestringoptionalSearch scope: user_content or enterprise_content.

typestringoptionalFilter by type: file, folder, or web_link.

updated_at_rangestringoptionalDate range for last updated.

box_shared_link_file_create#Creates or updates a shared link for a file.6 params▾

Creates or updates a shared link for a file.

NameTypeRequiredDescription

file_idstringrequiredID of the file.

accessstringoptionalShared link access: open, company, or collaborators.

can_downloadbooleanoptionalAllow download (true/false).

can_previewbooleanoptionalAllow preview (true/false).

passwordstringoptionalPassword to protect the shared link.

unshared_atstringoptionalExpiry date in ISO 8601 format.

box_shared_link_folder_create#Creates or updates a shared link for a folder.5 params▾

Creates or updates a shared link for a folder.

NameTypeRequiredDescription

folder_idstringrequiredID of the folder.

accessstringoptionalShared link access: open, company, or collaborators.

can_downloadbooleanoptionalAllow download (true/false).

passwordstringoptionalPassword to protect the shared link.

unshared_atstringoptionalExpiry date in ISO 8601 format.

box_task_assignment_create#Assigns a task to a user.3 params▾

Assigns a task to a user.

NameTypeRequiredDescription

task_idstringrequiredID of the task to assign.

user_idstringoptionalID of the user to assign the task to.

user_loginstringoptionalEmail login of the user (alternative to user_id).

box_task_assignment_delete#Removes a task assignment from a user.1 param▾

Removes a task assignment from a user.

NameTypeRequiredDescription

task_assignment_idstringrequiredID of the task assignment to remove.

box_task_assignment_get#Retrieves a specific task assignment.1 param▾

Retrieves a specific task assignment.

NameTypeRequiredDescription

task_assignment_idstringrequiredID of the task assignment.

box_task_assignment_update#Updates a task assignment (complete, approve, or reject).3 params▾

Updates a task assignment (complete, approve, or reject).

NameTypeRequiredDescription

task_assignment_idstringrequiredID of the task assignment.

messagestringoptionalOptional message/comment for the resolution.

resolution_statestringoptionalResolution state: completed, incomplete, approved, or rejected.

box_task_assignments_list#Retrieves all assignments for a task.1 param▾

Retrieves all assignments for a task.

NameTypeRequiredDescription

task_idstringrequiredID of the task.

box_task_create#Creates a task on a file.5 params▾

Creates a task on a file.

NameTypeRequiredDescription

file_idstringrequiredID of the file to attach the task to.

actionstringoptionalAction: review or complete.

completion_rulestringoptionalCompletion rule: all_assignees or any_assignee.

due_atstringoptionalDue date in ISO 8601 format.

messagestringoptionalTask message/description.

box_task_delete#Removes a task from a file.1 param▾

Removes a task from a file.

NameTypeRequiredDescription

task_idstringrequiredID of the task to delete.

box_task_get#Retrieves a task's details.1 param▾

Retrieves a task's details.

NameTypeRequiredDescription

task_idstringrequiredID of the task.

box_task_update#Updates a task's message, due date, or completion rule.5 params▾

Updates a task's message, due date, or completion rule.

NameTypeRequiredDescription

task_idstringrequiredID of the task to update.

actionstringoptionalNew action: review or complete.

completion_rulestringoptionalNew completion rule: all_assignees or any_assignee.

due_atstringoptionalNew due date in ISO 8601 format.

messagestringoptionalNew message for the task.

box_trash_file_permanently_delete#Permanently deletes a trashed file.1 param▾

Permanently deletes a trashed file.

NameTypeRequiredDescription

file_idstringrequiredID of the trashed file.

box_trash_file_restore#Restores a file from the trash.3 params▾

Restores a file from the trash.

NameTypeRequiredDescription

file_idstringrequiredID of the trashed file.

namestringoptionalNew name if original name is taken.

parent_idstringoptionalParent folder ID if original is unavailable.

box_trash_folder_permanently_delete#Permanently deletes a trashed folder.1 param▾

Permanently deletes a trashed folder.

NameTypeRequiredDescription

folder_idstringrequiredID of the trashed folder.

box_trash_folder_restore#Restores a folder from the trash.3 params▾

Restores a folder from the trash.

NameTypeRequiredDescription

folder_idstringrequiredID of the trashed folder.

namestringoptionalNew name if original is taken.

parent_idstringoptionalNew parent folder ID if original is unavailable.

box_trash_list#Retrieves items in the user's trash.5 params▾

Retrieves items in the user's trash.

NameTypeRequiredDescription

directionstringoptionalSort direction: ASC or DESC.

fieldsstringoptionalComma-separated list of fields to return.

limitintegeroptionalMax results.

offsetintegeroptionalPagination offset.

sortstringoptionalSort field: name, date, or size.

box_user_create#Creates a new user in the enterprise.5 params▾

Creates a new user in the enterprise.

NameTypeRequiredDescription

namestringrequiredFull name of the user.

is_platform_access_onlybooleanoptionalSet true for app users (no login).

loginstringoptionalEmail address (login) for managed users.

rolestringoptionalUser role: user or coadmin.

space_amountintegeroptionalStorage quota in bytes (-1 for unlimited).

box_user_delete#Removes a user from the enterprise.3 params▾

Removes a user from the enterprise.

NameTypeRequiredDescription

user_idstringrequiredID of the user to delete.

forcestringoptionalForce deletion even if user owns content (true/false).

notifystringoptionalNotify user via email (true/false).

box_user_get#Retrieves information about a specific user.2 params▾

Retrieves information about a specific user.

NameTypeRequiredDescription

user_idstringrequiredID of the user.

fieldsstringoptionalComma-separated list of fields to return.

box_user_me_get#Retrieves information about the currently authenticated user.1 param▾

Retrieves information about the currently authenticated user.

NameTypeRequiredDescription

fieldsstringoptionalComma-separated list of fields to return.

box_user_memberships_list#Retrieves all group memberships for a user.3 params▾

Retrieves all group memberships for a user.

NameTypeRequiredDescription

user_idstringrequiredID of the user.

limitintegeroptionalMax results.

offsetintegeroptionalPagination offset.

box_user_update#Updates a user's properties in the enterprise.6 params▾

Updates a user's properties in the enterprise.

NameTypeRequiredDescription

user_idstringrequiredID of the user to update.

namestringoptionalNew full name.

rolestringoptionalNew role: user or coadmin.

space_amountintegeroptionalStorage quota in bytes.

statusstringoptionalNew status: active, inactive, or cannot_delete_edit.

tracking_codesstringoptionalTracking codes as JSON array string.

box_users_list#Retrieves all users in the enterprise.5 params▾

Retrieves all users in the enterprise.

NameTypeRequiredDescription

fieldsstringoptionalComma-separated list of fields to return.

filter_termstringoptionalFilter users by name or login.

limitintegeroptionalMax users to return.

offsetintegeroptionalPagination offset.

user_typestringoptionalFilter by type: all, managed, or external.

box_web_link_create#Creates a web link (bookmark) inside a folder.4 params▾

Creates a web link (bookmark) inside a folder.

NameTypeRequiredDescription

parent_idstringrequiredID of the parent folder.

urlstringrequiredURL of the web link.

descriptionstringoptionalDescription of the web link.

namestringoptionalName for the web link.

box_web_link_delete#Removes a web link.1 param▾

Removes a web link.

NameTypeRequiredDescription

web_link_idstringrequiredID of the web link to delete.

box_web_link_get#Retrieves a web link's details.2 params▾

Retrieves a web link's details.

NameTypeRequiredDescription

web_link_idstringrequiredID of the web link.

fieldsstringoptionalComma-separated list of fields to return.

box_web_link_update#Updates a web link's URL, name, or description.5 params▾

Updates a web link's URL, name, or description.

NameTypeRequiredDescription

web_link_idstringrequiredID of the web link to update.

descriptionstringoptionalNew description.

namestringoptionalNew name.

parent_idstringoptionalNew parent folder ID.

urlstringoptionalNew URL.

box_webhook_create#Creates a webhook to receive event notifications.4 params▾

Creates a webhook to receive event notifications.

NameTypeRequiredDescription

addressstringrequiredHTTPS URL to receive webhook notifications.

target_idstringrequiredID of the file or folder to watch.

target_typestringrequiredType of target: file or folder.

triggersarrayrequiredArray of trigger events, e.g. ["FILE.UPLOADED","FILE.DELETED"].

box_webhook_delete#Removes a webhook.1 param▾

Removes a webhook.

NameTypeRequiredDescription

webhook_idstringrequiredID of the webhook to delete.

box_webhook_get#Retrieves a webhook's details.1 param▾

Retrieves a webhook's details.

NameTypeRequiredDescription

webhook_idstringrequiredID of the webhook.

box_webhook_update#Updates a webhook's address or triggers.5 params▾

Updates a webhook's address or triggers.

NameTypeRequiredDescription

webhook_idstringrequiredID of the webhook to update.

addressstringoptionalNew HTTPS URL for notifications.

target_idstringoptionalNew target ID.

target_typestringoptionalNew target type: file or folder.

triggersarrayoptionalNew array of trigger events, e.g. ["FILE.UPLOADED","FILE.DELETED"].

box_webhooks_list#Retrieves all webhooks for the application.2 params▾

Retrieves all webhooks for the application.

NameTypeRequiredDescription

limitintegeroptionalMax results.

markerstringoptionalPagination marker.