Box

Creates a new entry in the list of allowed domains for collaboration within your enterprise. This allows you to whitelist specific domains for external collaboration. Use 'inbound' to allow users from the specified domain to collaborate on your enterprise's files and folders. Use 'outbound' to allow your enterprise users to collaborate on content owned by the specified domain. Use 'both' for bidirectional collaboration. Note: This action requires enterprise admin privileges and the 'manage_enterprise_properties' scope.

Adds a classification to a file by specifying the label of the classification to add. **Enterprise-only feature**: This action requires a Box enterprise account with classification templates configured. Users without an enterprise account will receive an error when attempting to use this feature. This API can also be called by including the enterprise ID in the URL explicitly, for example `/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`.

Adds a classification to a folder by specifying the label of the classification to add. **Enterprise-only feature**: This action requires a Box enterprise account with classification templates configured. Users without an enterprise account will receive an error when attempting to use this feature. **Prerequisites**: - A classification template must exist in the enterprise. Use `list_all_classifications` to retrieve available classification keys. - If no classifications exist, an admin must first create the classification template using `add_initial_classifications`. **Common errors**: - 404: Classification template not found (no classifications exist in enterprise) - 409: Classification already exists on this folder (use update action instead) - 403: Insufficient permissions to add classifications This API can also be called by including the enterprise ID in the URL explicitly, for example `/folders/:id//enterprise_12345/securityClassification-6VMVochwUWo`.

Initializes the classification template for an enterprise with an initial set of classification options. IMPORTANT: This action requires admin permissions and should only be called once per enterprise when no classifications exist. If classifications already exist, use the 'add_classification' action to add more options. Common classification examples: 'Confidential', 'Internal', 'Public', 'Restricted'. Returns 400 if the classification template already exists. Returns 403 if the user lacks admin permissions.

Adds or updates a user avatar.

Adds a shared link to a file.

Adds a shared link to a folder, allowing it to be shared with others via a URL. This action creates or updates a shared link on a folder. The shared link can be configured with different access levels: - 'open': Anyone with the link can access - 'company': Only people within the company can access (paid accounts only) - 'collaborators': Only those invited to the folder can access To create a shared link with default enterprise settings, call with just folder_id and fields='shared_link'. To customize access, set shared_link_access parameter. Returns the folder object with the new shared_link information including the URL.

Adds a shared link to a web link.

Creates a group membership. Only users with admin-level permissions will be able to use this API.

Appends a new level to a metadata taxonomy structure. Use when adding hierarchical categories to organize metadata. If no levels exist, this creates the first level.

Applies or update a watermark on a file.

Applies or update a watermark on a folder.

Ask questions about Box files using Box AI. Use this action to query one or more files with natural language questions. Box AI will analyze the file contents and provide an answer based on the information found in the files. Modes: - single_item_qa: Ask about a single file (items array must have exactly 1 element) - multiple_item_qa: Ask about multiple files (up to 25 files) Limitations: - Text documents: Up to 1MB per file, max 25 files - Images: 1024x1024px resolution, max 5 images/pages - Prompts: Max 10,000 characters Requires 'manage_ai' scope in the access token.

Assign a legal hold policy to a file, file version, folder, or user. Legal hold policies preserve content for litigation or compliance purposes by preventing the deletion of specified items. When assigned to a folder, the hold applies recursively to all contents. When assigned to a user, the hold applies to all content owned by that user. Note: This feature requires Box Enterprise or higher with legal hold capabilities enabled. The authenticated user must have admin privileges with 'manage_legal_holds' scope.

Assigns a retention policy to an item in Box to enforce content retention. Use this action to apply a retention policy to: - An entire enterprise (assign_to_type='enterprise', no ID needed) - A specific folder (assign_to_type='folder', provide folder ID) - Items matching metadata criteria (assign_to_type='metadata_template', provide template ID) Prerequisites: - Box Governance license is required - Admin permissions with 'manage_data_retention' and 'enterprise_content' scopes - A retention policy must exist (use create_retention_policy first) Example usage for folder assignment: - policy_id: "173463" (from create_retention_policy or list_retention_policies) - assign_to_type: "folder" - assign_to_id: "6564564" (the folder ID)

Creates a storage policy assignment for an enterprise or user. Storage policies control where data is stored geographically (data residency). This action requires Box Zones or similar enterprise feature to be enabled. Use 'list_storage_policies' to get available policies before assignment.

Assigns a task to a user. A task can be assigned to more than one user by creating multiple assignments.

Authorize a user by sending them through the [Box](https://box.com) website and request their permission to act on their behalf. This is the first step when authenticating a user using OAuth 2.0. To request a user's authorization to use the Box APIs on their behalf you will need to send a user to the URL with this format.

Cancels a pending Box Sign request that has not yet been fully signed or declined. After cancellation, any outstanding signers will no longer be able to sign the document. Only the user who created the request (the requester) is able to cancel it. Note: A request cannot be cancelled if it was already declined, fully signed, or if the document is still in the converting state. Returns the cancelled sign request object with updated status set to 'cancelled'.

Commits an upload session and creates a file from the uploaded chunks. This is the final step in a chunked upload workflow: 1. Create an upload session using 'create_upload_session' 2. Upload file parts using 'upload_part_of_file' 3. Commit the session using this action to finalize the file Requirements: - All parts must be uploaded before committing - The digest header must contain the SHA1 hash of the entire file (Base64 encoded) - Parts array must include part_id, offset, and size for each uploaded chunk Note: The API may return 202 if processing is not complete. In this case, check the retry_after field and retry after the specified number of seconds.

Creates a copy of a file.

Copies an existing file request to a new folder. File requests allow external users to upload files to a specific folder without needing a Box account. This action creates a copy of an existing file request and associates it with a different destination folder. IMPORTANT LIMITATION: File request IDs cannot be discovered via API - they can only be obtained from the Box web application. To find a file_request_id: 1. Navigate to Box web UI (https://app.box.com) 2. Go to the folder containing the file request 3. Open the file request settings 4. Copy the ID from the URL (e.g., https://*.app.box.com/filerequest/123 → ID is "123") Common use cases: - Creating file request templates that can be copied to multiple project folders - Automating file request creation for new cases/customers/projects - Duplicating file requests with different settings (title, description, etc.) When copying, you can optionally override settings from the source file request including title, description, status, and form requirements.

Creates a copy of a folder within a destination folder. The original folder will not be changed.

Creates a custom AI agent in Box AI Studio. At least one capability required: ask (Q&A), text_gen (content generation), or extract (metadata extraction). Requirements: Box Enterprise Advanced account, Box AI Studio enabled, "Manage AI" scope in Developer Console. Access options: 'enabled' (all users), 'disabled' (none), 'enabled_for_selected_users' (specified in allowed_entities). Example: Set name + ask__type='ai_agent_ask' + ask__access__state='enabled' + ask__description to create Q&A agent.

Creates a Box Sign request to send documents for electronic signing. Prepares documents and sends signature requests to signers via email. Signers do not need Box accounts. Supports up to 10 files, 35 signers, sequential signing order, templates, and custom redirect URLs. Requires Box Sign feature enabled and sign_requests.readwrite scope.

Applies one or more Box Skills metadata cards to a file. NOTE: This action creates NEW Box Skill cards on a file. If Box Skill cards already exist on the file, this action will fail with a 409 Conflict error. In that case: - Use 'remove_box_skill_cards_from_file' to delete existing cards first, then create new ones, OR - Use 'update_all_box_skill_cards_on_file' to overwrite all existing cards

Exempts a specific user from the enterprise's collaboration domain restrictions. This allows the specified user to collaborate with external parties from any domain, bypassing the enterprise's allowed collaboration domain list. PREREQUISITES: - The enterprise MUST have at least one allowed collaboration domain configured. Use 'Add domain to list of allowed collaboration domains' first if needed. - The user must not already have an exemption (returns 409 Conflict if exists). - Requires enterprise admin privileges with 'manage_users' scope. COMMON ERRORS: - 409 Conflict: User already exempt OR no whitelisted domains exist for enterprise. - 403 Forbidden: Insufficient permissions to manage user exemptions. - 404 Not Found: The specified user ID does not exist.

Adds a collaboration for a single user or a single group to a file or folder. Collaborations can be created using email address, user IDs, or a group IDs. If a collaboration is being created with a group, access to this endpoint is dependent on the group's ability to be invited. If collaboration is in `pending` status, the following fields are redacted: - `login` and `name` are hidden if a collaboration was created using `user_id`, - `name` is hidden if a collaboration was created using `login`.

Adds a comment by the user to a specific file, or as a reply to an other comment.

Adds a new email alias to a user account. The email domain must be registered to your enterprise. Returns the newly created email alias object with id, type, email, and is_confirmed fields.

Creates a new empty folder within the specified parent folder.

Creates a folder lock on a folder, preventing it from being moved and/or deleted. You must be authenticated as the owner or co-owner of the folder to use this endpoint.

Creates a new group of users in an enterprise. Only users with admin permissions can create new groups.

Create a new legal hold policy in Box. Legal hold policies are used to prevent permanent deletion of content during ongoing litigation. Once created, the policy can be assigned to specific users, folders, or files. IMPORTANT: Either `is_ongoing` must be set to true, OR both `filter_started_at` and `filter_ended_at` must be provided. The policy name must be unique within the enterprise. Requires Box Governance add-on (Enterprise plan with legal hold feature enabled).

Creates a new metadata cascade policy that automatically applies a metadata template to all files and subfolders within a specified folder. Prerequisites: - A metadata instance must already be applied to the target folder before creating the cascade policy. - The target folder cannot be the root folder (ID '0'). - Enterprise admin must have enabled 'Cascading Folder Level Metadata' in Admin Console > Enterprise Settings > Content & Sharing. Common use case: After applying metadata to a folder, create a cascade policy to ensure all new items added to that folder automatically inherit the metadata. Returns: A MetadataCascadePolicy object with id, type, owner_enterprise, parent, scope, and templateKey fields. Error codes: - 400: Invalid format for scope, templateKey, or folder_id - 403: Policy cannot apply to restricted folders (e.g., root folder) - 404: Folder or template not found/inaccessible - 409: Duplicate policy already exists for this folder/template combination

Applies an instance of a metadata template to a file. The metadata_fields parameter contains key-value pairs that match the fields defined in the template. In most cases only field keys present in the metadata template will be accepted, except for the `global.properties` template which accepts any key-value pair. Common error codes: - 409 (tuple_already_exists): A metadata instance of this template already exists on the file. - 404 (not_found): The file was not found or the user does not have access. - 404 (instance_tuple_not_found): The metadata template was not found. - 400 (schema_validation_failed): Invalid field key or value type for the template.

Applies an instance of a metadata template to a folder. In most cases only values that are present in the metadata template will be accepted, except for the `global.properties` template which accepts any key-value pair. To display the metadata template in the Box web app the enterprise needs to be configured to enable **Cascading Folder Level Metadata** for the user in the admin console.

Tool to create a new metadata taxonomy in Box. Use when you need to set up a hierarchical classification system for organizing and categorizing metadata templates.

Creates new hierarchical levels for a metadata taxonomy in Box. Use this to define the structure of your taxonomy by specifying levels like Continent -> Country -> City. Each level must have a unique level number starting from 1, with higher numbers representing deeper levels in the hierarchy.

Tool to create a new metadata taxonomy node within a specified taxonomy. Use when you need to add a new classification or category to an existing metadata taxonomy hierarchy.

Creates a new metadata template that can be applied to files and folders.

Creates a retention policy for managing content lifecycle in Box. Retention policies prevent permanent deletion of content for a specified duration. Once created, policies can be assigned to folders or the entire enterprise. Note: This endpoint requires the Box Governance add-on feature and the 'manage retention policies' scope enabled in your application.

Creates a shield information barrier to establish an "ethical wall" that separates individuals/groups within an enterprise and prevents confidential information sharing. Prerequisites: Box Shield add-on must be licensed and enabled. Admin-level permissions required. Only one barrier allowed per enterprise. NOT available in Shield trials. Workflow: 1) Get enterprise ID from /users/me, 2) Create barrier (starts in 'draft'), 3) Create segments and add users, 4) Define segment restrictions, 5) Enable barrier. Common errors: 400 (missing enterprise), 404 (Shield not enabled/invalid ID), 409 (barrier already exists).

Creates a shield information barrier report for a given barrier. Shield information barrier reports track the configuration status of information barriers in Box Shield. When created, reports start with status 'pending' and transition to 'done', 'error', or 'cancelled'. Note: Requires Box Shield enterprise add-on license. Returns 404 if Shield is not enabled for the enterprise. Returns 409 if a report is already being created.

Creates a new shield information barrier segment for compliance and information isolation. Segments represent organizational divisions (e.g., Investment Banking, Research, Trading) that need to be isolated from each other for regulatory compliance. Each segment can have users assigned to it, and restrictions can be created to prevent collaboration between specific segments. Prerequisites: Box Shield license, existing barrier (create_shield_information_barrier), barrier in 'draft'/'pending' status. Returns 404 if Shield not enabled or barrier doesn't exist. Returns 409 if segment name already exists. Related: create_shield_information_barrier_segment_member, create_shield_information_barrier_segment_restriction, list_shield_information_barrier_segments

Adds a Box user to a shield information barrier segment for compliance and information security. This assigns users to segments that restrict collaboration between departments (e.g., Investment Banking vs Research in financial institutions). Users can only belong to ONE segment at a time. Prerequisites: Box Shield license, existing barrier and segment, valid user ID. Returns 404 if Shield not enabled or resources don't exist. Related: create_shield_information_barrier_segment, list_shield_information_barrier_segment_members

Creates a ONE-WAY shield information barrier segment restriction preventing collaboration between members of two segments (e.g., Investment Banking cannot collaborate with Research). Prerequisites: - Box Shield add-on enabled (returns 404 if not available) - Admin privileges required - Both segments must exist in the same barrier Key details: - Creates ONE-WAY restriction. For bidirectional, call twice with swapped segment IDs - shield_information_barrier parameter is optional (inferred from segments) - Use create_shield_information_barrier_segment to create segments first - Common for regulatory compliance and ethical walls Workflow: 1) Create barrier 2) Create segments 3) Create restrictions 4) Add members to segments

Creates a [Slack integration mapping](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack) by mapping a Slack channel to a Box item. You need Admin or Co-Admin role to use this endpoint.

Creates a single task on a file. This task is not assigned to any user and will need to be assigned separately.

Creates a Microsoft Teams integration mapping that links a Teams channel or team to a Box folder. Once mapped, files shared in the Teams channel are automatically stored in the linked Box folder. Requires Admin/Co-Admin role and the `manage_enterprise_properties` scope. **Prerequisites:** - Box for Teams must be installed in the Microsoft Teams workspace - The Box folder must be owned by the enterprise and not already mapped See: https://support.box.com/hc/en-us/articles/360044681474-Using-Box-for-Teams

Creates a terms of service for a given enterprise and type of user. This action requires enterprise admin permissions with 'Edit settings for your company' enabled. The Terms of Service feature must also be enabled for the enterprise in the Box Admin Console. Box supports two types of Terms of Service: - 'managed': Applied to the enterprise's own users - 'external': Applied to external collaborators from other enterprises

Creates a terms of service status record for a user who has not previously accepted or rejected the terms. This action records whether a user has accepted or rejected a specific terms of service. Use this for users who are encountering the terms of service for the first time. For users who have previously accepted or rejected terms, use update_terms_of_service_status_for_existing_user instead. Prerequisites: - The Terms of Service feature must be enabled for the enterprise in the Box Admin Console - A terms of service must exist (created via create_terms_of_service) - The user must not already have a status record for this terms of service Note: If a status already exists for the user and terms of service combination, the API will return an error.

Creates an upload session for chunked upload of large files (20MB+). This is the first step in Box's chunked upload process. After creating the session, you must: (1) upload file chunks using the upload_part endpoint, (2) commit the session using the commit endpoint to finalize the file. The session expires after 7 days. Use this for files 20MB or larger. For smaller files, use the regular upload endpoint instead.

Creates an upload session for uploading a new version of an existing file using chunked upload. Use this for files larger than 20MB. The session provides endpoints for uploading file parts, committing the upload, and checking status. Returns session info including part_size, total_parts, and session_endpoints for managing the chunked upload process.

Creates a new managed user in an enterprise. This endpoint is only available to users and applications with the right admin permissions.

Invites an existing external user to join an enterprise. The existing user can not be part of another enterprise and must already have a Box account. Once invited, the user will receive an email and are prompted to accept the invitation within the Box web application. This method requires the "Manage An Enterprise" scope enabled for the application, which can be enabled within the developer console.

Creates a webhook to monitor a file or folder for specific events. Webhooks allow you to receive notifications at a specified URL when events occur on Box content. When an event triggers, Box sends an HTTP POST request to your specified address with details about the event. Requirements: - The notification URL must use HTTPS on port 443 - The URL must respond with HTTP 200-299 within 30 seconds - Requires 'Manage Webhooks' scope enabled for the application Note: Folder webhooks cascade to sub-folders automatically.

Creates a web link object within a folder.

Creates a request to download multiple files and folders as a single `zip` archive file. This API does not return the archive but instead performs all the checks to ensure that the user has access to all the items, and then returns a `download_url` and a `status_url` that can be used to download the archive. The limit for an archive is either the Account's upload limit or 10,000 files, whichever is met first. **Note**: Downloading a large file can be affected by various factors such as distance, network latency, bandwidth, and congestion, as well as packet loss ratio and current server load. For these reasons we recommend that a maximum ZIP archive total size does not exceed 25GB.

Permanently deletes a custom AI agent from Box AI Studio. This action removes the specified AI agent and all its configuration, including any custom instructions and capability settings. This operation cannot be undone. Note: This action requires the 'Manage AI' scope to be enabled for the Box application. The authenticated user must have appropriate permissions to delete AI agents. Common error responses: - 403 Forbidden: Insufficient permissions or 'Manage AI' scope not enabled - 404 Not Found: The specified agent_id does not exist