Box

Extract metadata from Box files using AI with freeform prompts. Use this action to extract custom metadata from files without needing a predefined metadata template. Box AI will analyze the file contents and extract information based on your prompt instructions. Features: - Freeform prompts: Specify exactly what metadata to extract using natural language - Flexible output: Response format adapts to your prompt (can be JSON, key-value pairs, etc.) - No template required: Unlike structured extraction, no metadata template setup needed Limitations: - Text documents: Up to 1MB per file - Maximum 25 files per request - Prompts: Maximum 10,000 characters Requires 'ai.readwrite' or 'manage_ai' scope in the access token.

Extract structured metadata from files using Box AI. Uses Large Language Models (LLMs) to extract metadata as key-value pairs from files. Requires Box AI access (ai.readwrite scope). Supports two extraction approaches: 1. Using fields: Define custom fields with 'key', optional 'description', 'type', 'prompt', and 'options'. 2. Using metadata_template: Reference an existing Box metadata template by its template_key, type, and scope. You must use EITHER 'fields' OR 'metadata_template', but NOT both. Supports OCR for images (TIFF, PNG, JPEG) and scanned documents automatically.

Return the folder represented by a shared link. A shared folder can be represented by a shared link, which can originate within the current enterprise or within another. This endpoint allows an application to retrieve information about a shared folder when only given a shared link. Conditional parameter requirements: - To retrieve the folder, you must supply a valid shared link via either the `shared_link` field (recommended) or the `boxapi` header string. If the shared link is password-protected, also provide `shared_link_password`.

Returns the file, folder, web link, or app item represented by a shared link. This endpoint allows you to retrieve information about any Box item (file, folder, web link, or app item) using its shared link URL. The shared link can originate from the current enterprise or another. While the action name references "app items", it works with all types of shared links in Box. The endpoint requires a valid shared link to be provided via the `boxapi` header or through the `shared_link` field. If the link is password-protected, provide the password via `shared_link_password`.

Finds a metadata template by searching for the ID of an instance of the template. This action is useful when you have a metadata instance ID (the '$id' field from a metadata instance on a file or folder) and need to retrieve the full template definition including all field configurations. Common use case: After listing metadata instances on a file/folder, use this action to get the complete template schema to understand what fields are available.

Generate text using Box AI based on a prompt and file context. This action sends a request to Box AI's text generation endpoint, which uses Large Language Models (LLMs) to generate text based on your prompt and the content of a specified file. Use cases include: - Summarizing document content - Generating responses based on file content - Creating content drafts using file context - Answering questions about document content Note: Requires Box AI access (Business, Business Plus, Enterprise, or higher plans). Files up to 1MB of text content are supported.

Retrieves detailed information about a specific AI Agent by its unique identifier. Use Cases: - Get the current configuration and capabilities of an AI agent - Check the access state and allowed users/groups for an agent - Retrieve capability settings (ask, text_gen, extract) for an agent Requirements: - Box Enterprise Advanced account with Box AI Studio enabled - "Manage AI" scope must be enabled in the Box Developer Console Example: To get an agent with all capability details, use: agent_id="1234567890", fields=

Retrieve the default AI agent configuration for a specific mode. Returns the default AI agent settings used by Box AI features. The configuration includes model settings, token limits, LLM endpoint parameters, and tool configurations for text processing, image handling, and spreadsheet operations. Use this to understand or customize the AI agent behavior for ask, text generation, or metadata extraction operations.

Retrieves details of a specific allowed collaboration domain entry within your enterprise. This endpoint returns information about a domain that has been whitelisted for collaboration, including the domain name, the direction of allowed collaborations (inbound, outbound, or both), and the enterprise that owns the entry. Use 'list_allowed_collaboration_domains' to get a list of all whitelist entry IDs, or use the ID returned when adding a new domain via 'add_domain_to_list_of_allowed_collaboration_domains'. Note: This endpoint requires enterprise admin privileges and the 'manage_enterprise_properties' scope.

Retrieves the details of a specific Box Sign request by its unique ID. Returns comprehensive information about the signature request including: - Request status (e.g., 'converting', 'created', 'sent', 'viewed', 'signed', 'declined', 'cancelled', 'expired', 'error_converting', 'error_sending') - Signers information with their email, role, decision status, and embed URLs - Source files included in the request - Signed document copies available for download (when completed) - Signing log reference - Request timestamps and sender information Note: Requires Box Sign to be enabled for the enterprise account.

Retrieves details of a specific Box Sign template by its unique ID. Returns template configuration including name, email subject/message, signers, source files, destination folder, and various lock settings that control what can be modified when creating signature requests. Note: Templates can only be created and edited via the Box web application. This API is read-only for template data. Required scope: sign_requests.readwrite

Retrieves details of a single collaboration by its ID. A collaboration represents shared access between a user/group and a file or folder in Box. This action returns information about who has access, what role they have, and which item the collaboration grants access to.

Retrieves details of a specific collection by its unique identifier. Collections in Box are used to organize items (files and folders). Currently, Box only supports the 'favorites' collection, which contains items that the user has marked as favorites. Use 'list_all_collections' to discover available collection IDs. Returns the collection's id, type, name, and collection_type.

Retrieves the message and metadata for a specific comment, as well as information on the user who created the comment.

Retrieves information about the user who is currently authenticated. In the case of a client-side authenticated OAuth 2.0 application this will be the user who authorized the app. In the case of a JWT, server-side authenticated application this will be the service account that belongs to the application by default. Use the `As-User` header to change who this API call is made on behalf of.

Retrieves information about an individual device pin in the enterprise. Device pins are created when users access Box from mobile or desktop devices that support device pinning. This endpoint returns details about a specific device pin including the device type and the user who owns it. The user must have admin privileges and the application needs the 'manage_enterprise_properties' scope to make this call.

Retrieves detailed information about a file request in Box. File requests are forms that allow external users to upload files to a specific folder without needing a Box account. This action returns the file request's configuration including its title, description, status, associated folder, and the shareable URL. Note: File request IDs can only be obtained from the Box web application URL (e.g., https://*.app.box.com/filerequest/123). There is no API endpoint to list all file requests.

Retrieves a thumbnail, or smaller image representation, of a file. Sizes of `32x32`,`64x64`, `128x128`, and `256x256` can be returned in the `.png` format and sizes of `32x32`, `160x160`, and `320x320` can be returned in the `.jpg` format. Thumbnails can be generated for the image and video file formats listed

Retrieve detailed information about a specific version of a file. This action returns metadata about a file version including its SHA1 hash, size, creation date, and who modified it. Versions are only tracked for Box users with premium accounts. Use BOX_LIST_ALL_FILE_VERSIONS to get a list of all available versions for a file.

Retrieves detailed information about a specific file version legal hold by its ID. A file version legal hold represents the preservation of a specific file version due to legal hold policies. This action returns the hold details including which file and file version are held, and which legal hold policy assignments created the hold. Use this action when you need to inspect the legal hold status and details for a specific file version legal hold record.

Returns a list of file versions under retention for a specified retention policy assignment. A retention policy assignment links a retention policy to content (enterprise, folder, or metadata template). This endpoint retrieves all file versions that are currently being retained under the specified assignment. Use cases: - Audit which file versions are being retained under a specific policy assignment - Monitor retention compliance for specific folders or metadata templates - Track file versions before their disposition date Prerequisites: - Requires a valid retention_policy_assignment_id (obtain from 'List retention policy assignments' endpoint) - Requires the 'manage_data_retention' scope enabled for the application Note: Retention policies are an enterprise feature and require Box Governance or similar Box product.

Returns a paginated list of files under retention for a specific retention policy assignment. This endpoint is part of Box Governance and requires: - 'manage_retention_policies' scope enabled for the application - Global Content Manager (GCM) permissions, which must be enabled by Box support The response includes file metadata (id, name, sha1, etag) and file version information. Results are paginated using marker-based pagination.

Retrieves information about a group. Only members of this group or users with admin-level permissions will be able to use this API.

Retrieves a specific group membership. Only admins of this group or users with admin-level permissions will be able to use this API.

Retrieve detailed information about a specific legal hold policy by its ID. Legal hold policies preserve content for litigation or compliance purposes by preventing deletion or modification. This action returns the policy's name, description, status (active/applying/releasing/released), assignment counts by type (user/folder/file/ file_version/ownership/interactions), creator info, and timestamps. Prerequisites: - Box Governance add-on must be enabled for the enterprise - Requires 'manage_legal_holds' or 'enterprise_content' OAuth scope - Admin or co-admin role required To enable Legal Hold: https://www.box.com/business/governance-and-compliance

Retrieves detailed information about a specific legal hold policy assignment by its ID. Legal hold policy assignments link a legal hold policy to specific items (files, folders, file versions, users, ownership-based content, or user interactions). When a policy is assigned, it places a legal hold on the relevant file versions, preventing them from being deleted or modified until the hold is released. The response includes the assignment ID, the associated legal hold policy, the assigned item details, the user who created the assignment, creation timestamp, and deletion timestamp (if applicable). Prerequisites: - Requires Box Governance add-on (Box Enterprise Plus or higher) - Requires 'manage_legal_holds' or 'enterprise_content' OAuth scope - Admin or co-admin role required Use cases: - Verify legal hold coverage on specific items - Audit legal hold assignments for compliance - Check assignment status and metadata

Retrieve a specific metadata cascade policy assigned to a folder.

Retrieves a specific metadata template instance that has been applied to a file. This action returns the metadata key-value pairs for a particular template on a file. Use BOX_LIST_METADATA_INSTANCES_ON_FILE first to discover which templates are applied to a file if you don't know the scope and template_key. Common error codes: - 404 (instance_not_found): The metadata template has not been applied to this file. - 404 (not_found): The file was not found or the user does not have access. - 403 (forbidden): The user does not have permission to view this metadata. Example usage: - Get global properties: scope='global', template_key='properties' - Get enterprise classification: scope='enterprise', template_key='classification' - Get custom template: scope='enterprise', template_key='yourCustomTemplate'

Retrieves the instance of a metadata template that has been applied to a folder. This can not be used on the root folder with ID `0`.

Retrieves all metadata taxonomies within a specific namespace. Use this when you need to list all taxonomy templates available in an enterprise namespace.

Retrieves a metadata taxonomy by its namespace and taxonomy key. Use when you need to fetch detailed information about a specific taxonomy structure.

Retrieves a specific node from a metadata taxonomy by its identifier. Use when you need to get details about a particular taxonomy node including its display name, level, and ancestor information.

Retrieves a metadata template by its ID.

Retrieves a metadata template by its `scope` and `templateKey` values. To find the `scope` and `templateKey` for a template, list all templates for an enterprise or globally, or list all templates applied to a file or folder.

Returns a list of real-time servers that can be used for long-polling user events. Long-polling allows applications to listen for events in real-time without repeatedly polling the /events endpoint. After calling this endpoint, make a GET request to the returned `url` to start listening for events. When events occur, the server responds with 'new_change' to signal that you should fetch events from GET /events. If no events occur within `retry_timeout` seconds, you'll receive 'reconnect' and should call this endpoint again to get a fresh URL. Note: Long-polling is only available for user events, not enterprise events.

Returns information about a file version retention. Note: File retention API is now deprecated. To get information about files and file versions under retention, see files under retention or file versions under retention endpoints.

Retrieves a retention policy by its unique ID. Retention policies define how long content is retained before being automatically deleted or having the retention removed. This is an enterprise-level feature that requires the 'manage_data_retention' OAuth scope to be enabled. Returns details including policy name, retention length, disposition action, status, and assignment counts.

Retrieves a retention policy assignment by its unique ID. A retention policy assignment represents a link between a retention policy and its target (a folder, the enterprise, or a metadata template). This action returns details about where and how the retention policy is applied. Requires Box Governance license and scopes: manage_data_retention, enterprise_content.

Tool to retrieve web link information for a shared link. Use when you have a Box shared link URL and need to get details about the web link object it points to.

Retrieves the shared link information for a file. This action fetches details about an existing shared link, including the URL, access level, permissions, and usage statistics. If the file does not have a shared link, the shared_link field in the response will be null.

Retrieves shared link information for a folder. This action fetches the shared link details for a specified folder, including the public URL, access level, permissions, and usage statistics. If the folder does not have a shared link, the 'shared_link' field in the response will be null. Use the 'fields' parameter to request additional folder information beyond just the shared link. This is useful for getting context about the folder (name, path, owner) in the same request. Note: This action only retrieves existing shared link information. To create a shared link, use the 'add_shared_link_to_folder' action.

Retrieves a shield information barrier report by its ID. Shield information barrier reports provide information about users and groups that are affected by shield information barriers in the enterprise. Reports include details about which users are in which segments and any policy violations. Note: This endpoint requires Box Shield, an enterprise add-on feature. The report must exist and belong to a barrier in your enterprise.

Retrieves a shield information barrier segment member by its unique ID. Shield Information Barriers enforce compliance by restricting collaboration between departments (e.g., Investment Banking vs Research in financial institutions). Returns details about a user's segment assignment including when added, by whom, and which barrier/segment. Prerequisites: Box Shield license, valid member ID from create/list operations. Returns 200 on success, 404 if not found or feature disabled. Related: create_shield_information_barrier_segment_member, list_shield_information_barrier_segment_members

Retrieves a shield information barrier segment restriction by its unique ID. Shield information barrier segment restrictions define which segments cannot communicate or collaborate with each other. This action fetches the details of a specific restriction including the requesting segment, restricted segment, and the parent barrier information. Note: This feature requires Box Shield subscription and enterprise-level access.

Retrieves a shield information barrier segment by its unique identifier. Shield information barriers are used to prevent conflicts of interest by restricting communication between specific groups of users. Segments define groups of users within a barrier. Note: This feature requires Box Shield, which is an enterprise-level add-on. The API will return 404 if Shield is not enabled for the enterprise.

Retrieves a shield information barrier by its unique ID. Shield information barriers are used to separate individuals/groups within the same enterprise and prevent confidential information from passing between them. Note: This feature requires Box Shield enterprise licensing. Returns 404 if the barrier ID doesn't exist or if Shield is not enabled for the enterprise.

Fetches a specific storage policy by its ID. Storage policies define the geographic location where content is stored (data residency). This is an enterprise feature that requires Box Zones or similar subscription. Use this action to get details about a storage policy, including its name and the geographic region(s) it covers. To find available storage policy IDs, first use the 'list_storage_policies' action.

Retrieves information about a specific storage policy assignment. Storage policies control where data is physically stored (data residency). This action requires the Box Zones add-on or equivalent enterprise feature. Use 'list_storage_policy_assignments' to find assignment IDs for users or the enterprise.

Retrieves detailed information about a specific task in Box. A task is a to-do item that can be assigned to users for a specific file. Tasks can be of type 'review' (approval workflow) or 'complete' (general task). Use this action to get task details including the associated file, assignees, due date, message, and completion status.

Retrieves detailed information about a specific task assignment in Box. A task assignment represents a task that has been assigned to a specific user. This endpoint returns information including: - The file associated with the task - The user the task is assigned to - The user who created the assignment - The assignment status (incomplete, completed, approved, or rejected) - Timestamps for assignment, completion, and reminders

Retrieves a specific terms of service by its unique identifier. Returns the full terms of service object including: - Status (enabled/disabled) - Terms text content - Type (managed users or external collaborators) - Associated enterprise information - Creation and modification timestamps Note: This endpoint requires the Terms of Service feature to be enabled for the enterprise. Admin permissions may be required to access this data.

Retrieves a file that has been moved to the trash. Please note that only if the file itself has been moved to the trash can it be retrieved with this API call. If instead one of its parent folders was moved to the trash, only that folder can be inspected using the `GET /folders/:id/trash` API. To list all items that have been moved to the trash, please use the `GET /folders/trash/items` API.

Retrieves a folder that has been moved to the trash. Please note that only if the folder itself has been moved to the trash can it be retrieved with this API call. If instead one of its parent folders was moved to the trash, only that folder can be inspected using the `GET /folders/:id/trash` API. To list all items that have been moved to the trash, please use the `GET /folders/trash/items` API.

Retrieves a web link that has been moved to the trash. Returns detailed information about a trashed web link including its original URL, name, description, creator, when it was trashed, and when it will be permanently purged. The web link must exist in the trash (not permanently deleted) for this action to succeed.

Retrieves detailed information about an existing chunked upload session. Returns the session status including: - Total number of parts expected for the file upload - Size of each part in bytes - Number of parts already processed/uploaded - Session expiration timestamp - Available endpoints for uploading parts, committing, aborting, and checking status Use this action to monitor upload progress or retrieve session endpoints needed to continue a chunked file upload. The upload_session_id is obtained from the 'Create upload session' action.

Retrieves information about a user in the enterprise. The application and the authenticated user need to have the permission to look up users in the entire enterprise. This endpoint also returns a limited set of information for external users who are collaborated on content owned by the enterprise for authenticated users with the right scopes. In this case, disallowed fields will return null instead.

Retrieves the avatar image of a Box user. Returns 404 if the user has no avatar set.

Retrieves details of a specific user exemption from collaboration domain restrictions. This endpoint returns information about a user who has been granted an exemption from the enterprise's collaboration domain allowlist, allowing them to collaborate with external parties from any domain. PREREQUISITES: - The enterprise MUST have collaboration domain restrictions enabled. - The authenticated user must have admin privileges. - The exemption ID must exist (obtained from creating an exemption or listing exempt users). COMMON ERRORS: - 403 Forbidden: Enterprise doesn't have collaboration domain restrictions enabled, or the authenticated user lacks admin permissions. - 404 Not Found: The specified exemption ID does not exist. USE CASE: Use this to verify a specific user's exemption status or retrieve exemption metadata after creating or discovering an exemption ID.

Returns the status of a user invite. This endpoint retrieves detailed information about a specific invite, including: - The invited user's details (email, name, ID) - The enterprise they were invited to - The user who created the invite - The invite status (e.g., 'pending', 'accepted') - Creation and modification timestamps Note: The invite_id must be obtained from creating an invite using the BOX_CREATE_USER_INVITE action. This endpoint requires the 'manage_enterprise' scope.

Retrieve the watermark for a folder.

Retrieve the watermark for a file. Returns the watermark information (created_at and modified_at timestamps) for a file that has a watermark applied. If the file does not have a watermark, a 404 Not Found error is returned. Prerequisites: - The file must exist in Box - A watermark must have been applied to the file using BOX_APPLY_WATERMARK_TO_FILE Use BOX_APPLY_WATERMARK_TO_FILE to apply a watermark to a file first if needed.

Retrieve detailed information about a web link (bookmark) in Box. Returns the full web link object including its URL, name, description, parent folder, path collection, creation and modification timestamps, and ownership details. Web links are bookmarks to external URLs stored in Box folders.

Retrieves detailed information about a specific webhook by its ID. Use this action to get the configuration of an existing webhook, including the target item being monitored (file or folder), the notification URL, the event triggers, and who created the webhook. Note: This action requires the 'Manage Webhooks' scope to be enabled for the application. The webhook must exist and be accessible to the authenticated user.

Get the download status of a zip archive, including progress, skipped items, and current state. Prerequisites: Call 'BOX_CREATE_ZIP_DOWNLOAD' first to get a zip_download_id, then initiate the download via 'BOX_DOWNLOAD_ZIP_ARCHIVE'. The status endpoint is only accessible after the download starts and remains valid for 12 hours. Skipped files/folders indicate permission issues.

Lists AI agents based on the provided parameters.

Retrieves the classification metadata template and lists all the classifications available to this enterprise. This API can also be called by including the enterprise ID in the URL explicitly, for example `/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`. Note: Returns a 404 if no classifications have been added to the enterprise yet. In this case, the action returns an empty classifications list.

Retrieves all collections for a given user. Currently, only the `favorites` collection is supported.

Retrieve a list of the past versions for a file. Versions are only tracked by Box users with premium accounts. To fetch the ID of the current version of a file, use the `GET /file/:id` API.

Used to retrieve all generic, global metadata templates available to all enterprises using Box.

Retrieves a list of legal hold policies that belong to an enterprise.

Used to retrieve all metadata templates created to be used specifically within the user's enterprise

Returns all defined webhooks for the requesting application. This API only returns webhooks that are applied to files or folders that are owned by the authenticated user. This means that an admin can not see webhooks created by a service account unless the admin has access to those folders, and vice versa.

Returns the list domains that have been deemed safe to create collaborations for within the current enterprise.

Tool to list all Box Hubs for the authenticated user or enterprise. Use when you need to retrieve, search, or filter Box Hubs.

Gets signature requests created by a user. If the `sign_files` and/or `parent_folder` are deleted, the signature request will not return in the list.

Gets Box Sign templates created by a user.

List the Box Skills metadata cards that are attached to a file.

Retrieves the files and/or folders contained within a Box collection. Collections in Box are used to organize content. Currently, Box supports one type of collection: 'Favorites', which allows users to mark files and folders for quick access. Use this action to: - List all files and folders in a user's Favorites collection - Paginate through large collections using offset and limit parameters - Request specific fields to reduce response size Note: To get the collection_id, first use the 'List all collections' action (BOX_LIST_ALL_COLLECTIONS).

Retrieves all the device pins within an enterprise. The user must have admin privileges, and the application needs the "manage enterprise" scope to make this call.

Returns a list of all users for the Enterprise along with their `user_id`, `public_name`, and `login`. The application and the authenticated user need to have the permission to look up users in the entire enterprise.

This is a beta feature, which means that its availability might be limited. Returns all app items the file is associated with. This includes app items associated with ancestors of the file. Assuming the context user has access to the file, the type/ids are revealed even if the context user does not have View permission on the app item.

Retrieves a list of pending and active collaborations for a file. This returns all the users that have access to the file or have been invited to the file.

Get a list of file versions on legal hold for a legal hold assignment. Due to ongoing re-architecture efforts this API might not return all file versions for this policy ID. Instead, this API will only return file versions held in the legacy architecture. Two new endpoints will available to request any file versions held in the new architecture. For file versions held in the new architecture, the `GET /legal_hold_policy_assignments/:id/file_versions_on_hold` API can be used to return all past file versions available for this policy assignment, and the `GET /legal_hold_policy_assignments/:id/files_on_hold` API can be used to return any current (latest) versions of a file under legal hold. The `GET /legal_hold_policy_assignments?policy_id={id}` API can be used to find a list of policy assignments for a given policy ID. Once the re-architecture is completed this API will be deprecated.

Retrieves all file version retentions for the given enterprise. Note: File retention API is now deprecated. To get information about files and file versions under retention, see files under retention or file versions under retention endpoints.

This is a beta feature, which means that its availability might be limited. Returns all app items the folder is associated with. This includes app items associated with ancestors of the folder. Assuming the context user has access to the folder, the type/ids are revealed even if the context user does not have View permission on the app item.

Retrieves a list of pending and active collaborations for a folder. This returns all the users that have access to the folder or have been invited to the folder.

Retrieves folder lock details for a given folder. You must be authenticated as the owner or co-owner of the folder to use this endpoint.

Retrieves all the collaborations for a group. The user must have admin permissions to inspect enterprise's groups. Each collaboration object has details on which files or folders the group has access to and with what role.

Retrieves all of the groups for a given enterprise. The user must have admin permissions to inspect enterprise's groups.

Retrieves a list of items a legal hold policy has been assigned to.

Retrieves all the members for a group. Only members of this group or users with admin-level permissions will be able to use this API.

Retrieves a list of all the metadata cascade policies that are applied to a given folder. This can not be used on the root folder with ID `0`.

Retrieves all metadata instances applied to a file. Returns all metadata template instances that have been applied to the specified file, including both enterprise and global templates. The API does not support pagination and will return all metadata instances in a single response.

Retrieves all metadata for a given folder. This can not be used on the root folder with ID `0`.

Retrieves metadata taxonomy nodes based on the specified parameters. Use when you need to browse or search hierarchical metadata classifications in Box. Results are sorted in lexicographic order unless a query parameter is passed, in which case results are sorted by relevance.

Retrieves all pending collaboration invites for this user.

Retrieves a list of previous (non-current) file versions that are on legal hold for a specific legal hold policy assignment. This endpoint returns file versions held under the new Box architecture. For current (latest) file versions, use BOX_REVIEW_FILES_ON_LEGAL_HOLD_POLICY_ASSIGNMENT instead. For file versions in the legacy architecture, use BOX_LIST_FILE_VERSION_LEGAL_HOLDS. Note: Due to ongoing re-architecture efforts, this API might not return all file versions held for this policy ID. This endpoint does not support returning content that is on hold due to a Custodian collaborating on a Hub. Requires the 'manage_legal_holds' scope and Legal Hold feature enabled for the enterprise.

Returns information about the recent items accessed by a user, either in the last 90 days or up to the last 1000 items accessed.

Retrieves all of the retention policies for an enterprise.

Retrieves all retention policy assignments for a specified retention policy. Retention policies can be assigned to: - 'enterprise': Apply to all content in the enterprise - 'folder': Apply to a specific folder - 'metadata_template': Apply based on metadata template values Requires the 'manage_retention_policies' scope.

Lists shield information barrier reports for a specified barrier. Shield information barrier reports contain details about barrier violations and compliance status. This feature requires Box Shield enterprise license. Returns a paginated list of report objects with status (pending/completed), creation timestamps, and details about the barrier scope.

Lists shield information barrier segment members based on provided segment IDs.

Lists all shield information barrier segment restrictions for a specific segment. Shield information barrier segment restrictions define which segments are prevented from collaborating with each other. This endpoint retrieves all restrictions where the specified segment is the requesting segment (the segment whose members are restricted from collaborating with other segments). Note: This feature requires Box Shield add-on and enterprise admin privileges. Returns 404 if Shield is not enabled for your enterprise or if the segment ID does not exist. Use Cases: - View all collaboration restrictions for a specific segment - Audit compliance boundaries between organizational divisions - Paginate through large sets of restrictions using marker-based pagination

Retrieves a list of shield information barrier segment objects for the specified Information Barrier ID. Shield Information Barriers are used to separate individuals/groups within the same enterprise to prevent confidential information from passing between them. Segments define the groups of users that are separated by the barrier. Note: This is an enterprise-level feature that requires Box Shield to be enabled. Returns a 404 error if Shield Information Barriers is not available for the enterprise.

Retrieves a list of shield information barrier objects for the enterprise of JWT.

Lists Slack integration mappings in a users' enterprise. You need Admin or Co-Admin role to use this endpoint.

Fetches all the storage policies in the enterprise.

Fetches all the storage policy assignment for an enterprise or user.

Lists all of the assignments for a given task. Returns a collection of task assignment objects showing who has been assigned to complete or review a task. Each assignment includes the assigned user's details, the assignment status, and the associated file information. This endpoint does not support pagination as tasks typically have a limited number of assignees.

Retrieves a list of all the tasks for a file. This endpoint does not support pagination.

Lists Teams integration mappings in a users' enterprise. You need Admin or Co-Admin role to use this endpoint.

Retrieves a list of users and their acceptance status for a specific terms of service. Returns information about whether each user has accepted the terms, including: - User details (ID, name, email) - Acceptance status (accepted or not) - Creation and modification timestamps Note: This endpoint requires the Terms of Service feature to be enabled for the enterprise and appropriate admin permissions (manage enterprise properties or manage users). Use 'list_terms_of_services' first to get valid terms of service IDs.

Returns the current terms of service text and settings for the enterprise.

Retrieves the files and folders that have been moved to the trash. Any attribute in the full files or folders objects can be passed in with the `fields` parameter to retrieve those specific attributes that are not returned by default. This endpoint defaults to use offset-based pagination, yet also supports marker-based pagination using the `marker` parameter.

List the parts (chunks) that have been uploaded to a chunked upload session. This is useful for tracking upload progress, verifying which parts have been successfully uploaded, and determining which parts still need to be uploaded. The upload_session_id is obtained from the 'Create upload session' action. Note: Chunked uploads are only for files larger than 20MB.

Returns up to a year of past events for a given user or for the entire enterprise. By default this returns events for the authenticated user. To retrieve events for the entire enterprise, set the `stream_type` to `admin_logs_streaming` for live monitoring of new events, or `admin_logs` for querying across historical events. The user making the API call will need to have admin privileges, and the application will need to have the scope `manage enterprise properties` checked.

Retrieves all email aliases for a user. The collection does not include the primary login for the user.

Retrieves all group memberships for a user, including the groups they belong to and their role in each group (member or admin). Only members of this group or users with admin-level permissions will be able to use this API.

Returns a list of users who have been exempt from the collaboration domain restrictions. Note: This endpoint requires an enterprise account with collaboration domain restrictions enabled. A 403 Forbidden error will be returned if the feature is not available for the enterprise.

Lists Box Relay workflows configured for a specific folder. Use the 'trigger_type' parameter to filter workflows by trigger type (e.g., 'WORKFLOW_MANUAL_START' for workflows that can be manually started via API). Your application must be authorized to use the 'Manage Box Relay' application scope within the Box developer console. Returns a paginated list of workflow objects with their flows and outcomes.

Performs a preflight check to verify that a file will be accepted by Box before uploading the entire file. This helps verify permissions, quota, and filename conflicts before starting the actual upload. A successful response (HTTP 200) indicates the upload can proceed. A 409 Conflict response indicates a file with the same name already exists.

Query files and folders by metadata using SQL-like syntax. Returns items that have metadata instances matching the specified template and optional query conditions. Use this action when you need to find files/folders based on their metadata values rather than searching by file name or content. This is useful for locating documents based on custom attributes like status, category, department, dates, etc. Examples: - Find all files with a specific metadata template: set `from_` to "enterprise_XXXXX.templateKey" - Find files in a specific folder: set `ancestor_folder_id` to the folder ID (use "0" for all folders) - Filter by metadata values: use `query` and `query_params` (e.g., query="status = :val", query_params={"val": "approved"}) Note: Classification templates cannot be queried with this endpoint.

Get a list of files with current file versions for a legal hold assignment. In some cases you may want to get previous file versions instead. In these cases, use the `GET /legal_hold_policy_assignments/:id/file_versions_on_hold` API instead to return any previous versions of a file for this legal hold policy assignment. Due to ongoing re-architecture efforts this API might not return all file versions held for this policy ID. Instead, this API will only return the latest file version held in the newly developed architecture. The `GET /file_version_legal_holds` API can be used to fetch current and past versions of files held within the legacy architecture. This endpoint does not support returning any content that is on hold due to a Custodian collaborating on a Hub. The `GET /legal_hold_policy_assignments?policy_id={id}` API can be used to find a list of policy assignments for a given policy ID.

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.

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.

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

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 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 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 a new managed user in an enterprise. This endpoint is only available to users and applications with the right admin permissions.

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.

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 web link object within a folder.

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 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.

Promote a specific version of a file. If previous versions exist, this method can be used to promote one of the older versions to the top of the version history. This creates a new copy of the old version and puts it at the top of the versions history. The file will have the exact same contents as the older version, with the the same hash digest, `etag`, and name as the original. Other properties such as comments do not get updated to their former values. Don't use this endpoint to restore Box Notes, as it works with file formats such as PDF, DOC, PPTX or similar.

Uploads a small file to Box. For file sizes over 50MB we recommend using the Chunk Upload APIs. The `attributes` part of the body must come before the `file` part. Requests that do not follow this format when uploading the file will receive a HTTP `400` error with a `metadata_after_file_contents` error code.

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.

Forces a metadata cascade policy to immediately apply the folder's metadata template to all existing child files and subfolders. This operation is asynchronous and returns immediately with HTTP 202 Accepted. Use cases: - After creating a new cascade policy to back-fill metadata on existing content - To retroactively apply metadata changes to all items in a folder hierarchy - When you need to enforce consistent metadata across all folder contents Important notes: - The cascade operation runs asynchronously in the background after the API returns - There is currently no API to check the status of this operation - Use the conflict_resolution parameter carefully to avoid unintended data overwrites - Only works with enterprise-scoped metadata templates (not global templates) - Newly added files/folders will automatically inherit metadata via the existing cascade policy Returns: HTTP 202 Accepted with an empty response body when the cascade operation is queued successfully.

Refresh an Access Token using its client ID, secret, and refresh token. This endpoint exchanges a refresh token for a new access token. The refresh token must be valid (they expire after 60 days). Each time a refresh token is used, it is invalidated and a new one is returned along with the new access token. Access tokens expire after 1 hour and need to be refreshed periodically. Note: This action requires valid OAuth2 credentials (client_id, client_secret, and a valid refresh_token) that cannot be automatically generated.

Removes a shared link from a file in Box. This action disables the shared link for the specified file, making it no longer accessible via the previously shared URL. The file itself is not deleted - only the shared link is removed. After successful execution, the shared_link field in the response will be null. This is an idempotent operation - calling it on a file that already has no shared link will succeed without error.

Removes a shared link from a folder in Box. This action disables the shared link for the specified folder, making it no longer accessible via the previously shared URL. The folder itself is not deleted - only the shared link is removed. After successful execution, the shared_link field in the response will be null. This is an idempotent operation - calling it on a folder that already has no shared link will succeed without error.

Resends signature request emails to all outstanding signers. Use this when a signer did not receive the original email, the email was lost, or the signer accidentally deleted it. The email is sent asynchronously after the API call returns. Rate limit: Can only be called once every 10 minutes per sign request. Note: For automated reminders, consider setting 'are_reminders_enabled' to true when creating the sign request, which sends automatic reminder emails after 3, 8, 13, and 18 days. Requires Box Sign feature to be enabled and sign_requests.readwrite scope.

Restores a file that has been moved to the trash. An optional new parent ID can be provided to restore the file to in case the original folder has been deleted.

Restores a specific version of a file after it was deleted (trashed). This action restores a file version that was previously moved to the trash by setting its trashed_at field back to null. Do not use this endpoint to restore Box Notes - it only works with standard file formats such as PDF, DOC, PPTX, or similar. To restore a file version: 1. First use 'List all file versions' to find versions with trashed_at set 2. Then call this action with the file_id and file_version_id The restored version will have trashed_at=null and restored_at/restored_by fields populated.

Restores a folder that has been moved to the trash. An optional new parent ID can be provided to restore the folder to in case the original folder has been deleted. During this operation, part of the file tree will be locked, mainly the source folder and all of its descendants, as well as the destination folder. For the duration of the operation, no other move, copy, delete, or restore operation can performed on any of the locked folders.

Restores a web link that has been moved to the trash. This action recovers a trashed web link and restores it to its original parent folder. If the original folder has been deleted, you can optionally specify an alternative parent folder using the parent_id parameter. You can also rename the web link during restoration using the name parameter. The web link must exist in the trash (not permanently deleted) for this action to succeed. Returns the restored web link with item_status changed from 'trashed' to 'active'.

Starts a Box Relay workflow with trigger type `WORKFLOW_MANUAL_START`. Prerequisites: - Your application must have the 'Manage Box Relay' scope enabled in the Box Developer Console. - Use the 'List Workflows' endpoint to get the workflow_id, flow.id, and folder.id. - All files specified must exist in the workflow's configured folder. Workflow: 1. Call 'List Workflows' with the folder_id to get available workflows. 2. From the response, extract: workflow.id, flows

Updates an existing custom AI agent in Box AI Studio. You can modify the agent's name, access settings, icon, and capability configurations (ask, text_gen, extract). Requirements: - Box Enterprise Advanced account with Box AI Studio enabled - "Manage AI" scope must be enabled in the Box Developer Console Usage Notes: - The `type` field must always be set to 'ai_agent' - Only custom agents (origin='CUSTOM') can be updated; Box default agents cannot be modified - When updating capabilities, provide all required fields (type, access_state, description) - Use `enabled_for_selected_users` access_state with `allowed_entities` to restrict access Example: To update an agent's name and enable the ask capability: agent_id="1234567890", name="Updated Agent", access_state="enabled", ask_type="ai_agent_ask", ask_access_state="enabled", ask_description="Ask questions about documents"

An alternative method to overwrite and update all Box Skill metadata cards on a file. IMPORTANT: This endpoint is designed for Box Skills applications. The skill_id parameter must be a valid Box-assigned skill invocation ID that is received in the webhook payload when Box triggers a skill on a file. This ID is NOT a user-created identifier. Use Cases: - Update skill card metadata after processing a file with a custom Box Skill - Report processing status (success, failure, in-progress) back to Box - Overwrite existing skill cards with new results from ML/AI processing For creating skill cards on files without a skill invocation ID, use: - 'create_box_skill_cards_on_file' to add new skill cards - 'list_box_skill_cards_on_file' to view existing skill cards - 'remove_box_skill_cards_from_file' to delete skill cards

Updates one or more Box Skills metadata cards on a file using JSON-Patch format. This action allows you to selectively update specific skill cards by their index position without affecting other cards. Use the 'replace' operation to modify existing cards at specified positions (e.g., /cards/0 for the first card). NOTE: This updates existing cards in place. To view existing cards first, use 'list_box_skill_cards_on_file'. To add new cards, use 'create_box_skill_cards_on_file'. To remove all cards, use 'remove_box_skill_cards_from_file'.

Updates a collaboration. Can be used to change the owner of an item, or to accept collaboration invites.

Update the message of a comment.

Updates a file request in Box. File requests allow external users to upload files to a specific folder without needing a Box account. Use this action to modify file request settings such as title, description, status, and form requirements. Common use cases: - Activate or deactivate a file request by changing its status - Update the title or description shown to uploaders - Set or change form requirements (email, description) - Set an expiration date for the file request Note: File request IDs can only be obtained from the Box web application URL. There is no API endpoint to list all file requests. To find a file_request_id, navigate to the file request in Box web UI and copy the ID from the URL (e.g., https://*.app.box.com/filerequest/123).

Updates a specific group. Only admins of this group or users with admin-level permissions will be able to use this API.

Updates a user's group membership. Only admins of this group or users with admin-level permissions will be able to use this API.

Update an existing legal hold policy in Box. This action allows you to modify the name, description, and release notes of an existing legal hold policy. Legal hold policies are used to preserve content for litigation or compliance purposes. At least one of the optional parameters (policy_name, description, or release_notes) should be provided. Note: This is a Box Governance feature that requires an enterprise account with legal hold capabilities enabled. The authenticated user must have admin-level permissions with the 'manage_legal_holds' scope.

Updates a metadata instance on a file using JSON-Patch operations. The metadata template must already be applied to the file before it can be updated. Only values that match the template schema are accepted. The update is atomic - if any operation fails, no changes are applied.

Updates metadata on a folder using JSON-Patch operations (RFC 6902). The metadata template must already be applied to the folder. Only values matching the template schema are accepted (except global.properties which accepts any key-value pairs). All operations are applied atomically - if any fail, no changes are made.

Tool to update an existing metadata taxonomy's display name. Use when you need to rename a taxonomy while keeping its structure and key intact.

Tool to update an existing metadata taxonomy node's display name. Use when you need to rename a taxonomy node in the Box metadata taxonomy hierarchy.

Updates a metadata template by applying JSON-Patch operations. The template must already exist. The update is applied atomically - if any error occurs during the application of operations, the metadata template will not be changed. Use this to modify template properties, add/edit/remove fields, or manage enum/multiSelect options.

Updates an existing Box retention policy. Use this action to modify retention policy settings such as name, description, retention duration, disposition action, and notification settings. Requires Box Governance add-on and 'manage retention policies' scope. Note: Non-modifiable policies have limited update options (can only extend duration, add folders, retire policy, or change notification settings).

Updates a shared link on a file.

Updates a shared link on a folder.

Updates a shared link on a web link.

Updates a shield information barrier segment's name and/or description. Shield Information Barrier segments represent organizational divisions (e.g., 'Investment Banking', 'Research', 'Trading') that need to be isolated from each other for regulatory compliance or information security purposes. Use this action to modify a segment's identifying information after creation. At least one of 'name' or 'description' should be provided. Requirements: - Box Shield license is required to use this feature - The segment must exist (obtained from list_shield_information_barrier_segments) - Admin permissions are required to update segments Returns 404 if segment not found, 409 if name conflicts with an existing segment.

Updates an existing Slack integration mapping. Use this to change which Box folder is mapped to a Slack channel, or to update configuration options like automatic access management. Requires Admin or Co-Admin role and the 'manage_enterprise_properties' scope. At least one of 'box_item' or 'options' must be provided.

Updates a storage policy assignment for an enterprise or user. Storage policies control where data is stored geographically (data residency). Use this action to change which storage policy is assigned to a user or enterprise. This action requires Box Zones or similar enterprise feature to be enabled and admin-level permissions with 'manage_enterprise_properties' scope. Use 'list_storage_policies' to get available policies and 'list_storage_policy_assignments' to find existing assignment IDs.

Updates a task. This can be used to update a task's configuration, or to update its completion state.

Updates a task assignment to change its resolution state or add a message. This endpoint allows updating the state of a task assigned to a user. Use this to mark tasks as completed, approved, rejected, or incomplete, and optionally add a message explaining the decision. Important notes: - Only the assignee can typically update their own task assignment - For 'complete' action tasks: use 'completed' or 'incomplete' - For 'review' action tasks: use 'approved', 'rejected', or 'incomplete' - At least one of 'message' or 'resolution_state' should be provided

Updates a Microsoft Teams integration mapping that links a Box folder to a Teams channel. This endpoint allows you to change which Box folder is associated with a Microsoft Teams channel through the Box for Teams integration. After updating, any new files shared in the Teams channel will be stored in the newly mapped Box folder. Requirements: - Admin or Co-Admin role in the Box enterprise - The 'manage_enterprise_properties' scope - Box for Teams must be installed in the relevant Microsoft Teams workspace Use Cases: - Reorganize where Teams channel files are stored in Box - Move team collaboration content to a different department folder - Update mappings after folder restructuring For more information, see: https://support.box.com/hc/en-us/articles/360044681474-Using-Box-for-Teams

Updates an existing terms of service for the enterprise. This action allows you to modify the status (enabled/disabled) and text content of an existing terms of service. When enabled, users will be prompted to accept the terms before accessing Box content. Note: This endpoint 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. Use 'list_terms_of_services' to find the terms_of_service_id to update.

Updates the acceptance status of a terms of service for a user who has previously accepted or rejected it. This action allows you to change whether a user has accepted or rejected a specific terms of service. Use this for users who already have a status record. For users who are encountering the terms of service for the first time, use create_terms_of_service_status_for_new_user instead. Prerequisites: - The Terms of Service feature must be enabled for the enterprise in the Box Admin Console - A terms of service user status record must already exist for the user (created via create_terms_of_service_status_for_new_user) - Requires admin permissions with 'manage enterprise properties' or 'manage users' scope Use list_terms_of_service_user_statuses to find existing status IDs for users.

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

Updates a web link object. This action allows you to modify an existing web link's properties including: - Changing the URL destination - Updating the name and description - Moving it to a different folder - Configuring shared link settings (access level, password, vanity URL, expiration) All fields except web_link_id are optional - only provide the fields you want to update.

Updates an existing webhook's configuration. Use this action to modify a webhook's target item (file or folder), notification URL, or event triggers. Only the fields provided in the request will be updated; omitted fields remain unchanged. 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: When changing the target, both target_id and target_type must be provided together.

Update a file's content. For file sizes over 50MB we recommend using the Chunk Upload APIs. The `attributes` part of the body must come before the `file` part. Requests that do not follow this format when uploading the file will receive a HTTP `400` error with a `metadata_after_file_contents` error code.

Uploads a chunk of a file for an upload session. The actual endpoint URL is returned by the `Create upload session` and `Get upload session` endpoints. Requirements: - Chunked uploads require files with a minimum size of 20MB - Each part's size must match the part_size from the upload session (except the last part) - The offset must be a multiple of the part_size - Parts cannot overlap with previously uploaded parts

Permanently deletes a shield information barrier segment by its ID. Shield information barriers help prevent conflicts of interest by restricting collaboration between user segments within an organization. This action removes a specific segment from the barrier configuration. Requirements: - Box Shield add-on must be enabled for the enterprise - Admin privileges are required to delete segments - The segment must not have any active restrictions referencing it Returns HTTP 204 No Content on successful deletion. Returns HTTP 404 Not Found if the segment ID does not exist.

Removes a user from a shield information barrier segment by deleting their membership. Shield information barriers are used to prevent conflicts of interest by restricting communication and collaboration between specific groups of users within an enterprise. This action removes a user's membership from a specific barrier segment. Note: This feature requires Box Shield and is only available for enterprise accounts with the appropriate licensing. Returns 204 No Content on successful deletion.

Deletes a shield information barrier segment restriction by its unique ID. Shield information barrier segment restrictions define which segments cannot communicate with each other. When a restriction is deleted, users in the previously restricted segments will be able to collaborate again. Important Notes: - This operation is destructive and cannot be undone - Returns HTTP 204 (No Content) with empty response body on success - Requires Box Shield add-on with information barriers enabled - Idempotent: Deleting a non-existent restriction returns 404 (not an error state) - Requires admin privileges Prerequisites: - Box Shield add-on enabled (returns 404 if not available) - Valid segment restriction ID from create or list operations

Deletes a Slack integration mapping that links a Box folder to a Slack channel. This endpoint removes an existing mapping between a Slack channel and a Box folder created through the Box for Slack integration. After deletion, any new files shared in the Slack channel will be stored in the default location rather than the previously mapped Box folder. Requirements: - Admin or Co-Admin role in the Box enterprise - Box for Slack must be installed in the relevant Slack workspace - Box as the Content Layer for Slack must be enabled Note: This action is irreversible. Once deleted, a new mapping must be created to restore the integration between the Slack channel and Box folder. For more information, see: https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack

Deletes a Microsoft Teams integration mapping that links a Box folder to a Teams channel. This endpoint removes an existing mapping between a Microsoft Teams channel or team and a Box folder created through the Box for Teams integration. After deletion, any new files shared in the Teams channel will be stored in the default location rather than the previously mapped Box folder. Requirements: - Admin or Co-Admin role in the Box enterprise - Box for Teams must be installed in the relevant Microsoft Teams workspace Note: This action is irreversible. Once deleted, a new mapping must be created to restore the integration between the Teams channel and Box folder. For more information, see: https://support.box.com/hc/en-us/articles/360044681474-Using-Box-for-Teams

Permanently deletes a user from the enterprise. By default, deletion fails if the user still owns content, was recently active, or recently joined from a free account. Use the `force` parameter to bypass these restrictions and delete the user along with all their content. Returns an empty response (HTTP 204) on success.

Deletes a user's custom avatar image from Box. This operation is irreversible. After deletion, the user will revert to the default Box avatar. If the user does not have a custom avatar set (only the default avatar), the operation will still succeed but indicate that no custom avatar was found. Note: This only removes custom uploaded avatars. Users always retain a default Box-generated avatar. Required scopes: root_readwrite or manage_managed_users

Permanently deletes a file from the trash. This action is irreversible and cannot be undone. The file must already be in the trash before it can be permanently removed. To move a file to trash first, use the 'Delete file' action.

Permanently deletes a folder that is in the trash. This action cannot be undone.

Permanently deletes a web link that is in the trash. This action cannot be undone.

Removes any Box Skills cards metadata from a file.

Removes a collaboration from a file or folder, revoking the collaborator's access. A collaboration in Box represents shared access granted to a user or group on a file or folder. Removing a collaboration will: - Revoke the collaborator's access to the item immediately - Remove the item from the collaborator's "Shared with Me" view - Cancel any pending invitations if the collaboration was not yet accepted This action is permanent and cannot be undone. To restore access, you would need to create a new collaboration. Returns HTTP 204 (No Content) on successful deletion.

Permanently deletes a comment from a file or folder in Box. This action removes a comment that was previously added to a Box item. Once deleted, the comment cannot be recovered. The operation returns HTTP 204 (No Content) on success. If the comment does not exist or has already been deleted, a 404 error is returned. Note: Only the user who created the comment or an admin can delete it.

Deletes an individual device pin from the enterprise. Device pins are created when users access Box from mobile or desktop devices that support device pinning. Removing a device pin will require the user to re-authenticate on that device. This endpoint requires admin privileges and the 'manage_enterprise_properties' scope. On successful deletion, returns HTTP 204 No Content.

Removes a domain from the list of allowed collaboration domains (whitelist) within your enterprise. This action deletes a specific collaboration whitelist entry, preventing users from that domain from collaborating on your enterprise's content (or vice versa, depending on the original direction). Requirements: - Enterprise admin privileges - The 'manage_enterprise_properties' scope - External collaboration allowlisting must be enabled for your enterprise (part of the Governance package) Usage: Provide the collaboration_whitelist_entry_id of the domain entry you want to remove. You can obtain this ID from the 'Add domain' or 'List allowed collaboration domains' actions. Response: Returns 204 No Content on successful deletion. This operation is idempotent - deleting an already deleted entry will still return success.

Removes an email alias from a user. This endpoint permanently deletes an email alias associated with a user account. Note: You cannot remove a user's primary email address. To change the primary email, you must first create a new alias, set it as primary, then remove the old one. Returns HTTP 204 (No Content) on success with an empty response body. Returns HTTP 404 if the user or email alias is not found.

Move a file version to the trash. Versions are only tracked for Box users with premium accounts.

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

Permanently delete an existing legal hold policy from Box. This is an asynchronous operation - the policy deletion is initiated but may not complete immediately. A successful response (HTTP 202) indicates the deletion has started. The policy cannot be recovered after deletion. Note: Legal Hold is an enterprise feature that must be enabled for your Box account. Requires 'manage_legal_holds' scope.

Permanently deletes a metadata cascade policy from a folder. When deleted, existing metadata on files/subfolders remains, but new items will no longer automatically inherit the template. Prerequisites: Requires 'manage_managed_metadata' scope and admin permissions. Returns: HTTP 204 No Content on success (empty response body). Operation is idempotent. Error codes: - 400: Invalid policy ID format - 404: Policy not found or folder inaccessible - 403: Insufficient permissions Related: BOX_CREATE_METADATA_CASCADE_POLICY, BOX_LIST_METADATA_CASCADE_POLICIES

Removes a metadata instance from a file. Deletes all metadata associated with a specific template from a file. This operation cannot be undone. The metadata template itself is not deleted, only the instance of metadata applied to this specific file. Returns a 204 No Content response on success. Returns 404 if the metadata instance doesn't exist on the file or if the file is not found.

Remove a metadata instance from a folder. Deletes a specific metadata template instance that has been applied to a folder. This operation is idempotent and will return a 404 error if the metadata instance doesn't exist. Returns HTTP 204 No Content on successful deletion. Note: This only removes the metadata instance, not the folder itself. To remove a folder, use the delete folder action instead.

Permanently deletes a metadata taxonomy from the enterprise. This deletion is permanent and cannot be reverted. Once deleted, the taxonomy and all associated metadata will be removed from files and folders. Use with caution.

Permanently deletes a metadata taxonomy node from Box. Metadata taxonomies in Box allow you to organize and classify content using hierarchical structures. This action removes a specific node from a taxonomy. Important constraints: - Only nodes without any children can be deleted - This deletion is permanent and cannot be reverted - Requires admin or co-admin permissions - The user must have access to the metadata taxonomies feature Returns HTTP 204 No Content on successful deletion. Returns HTTP 400 Bad Request if the node has children or request is invalid. Returns HTTP 403 Forbidden if the user lacks necessary permissions. Returns HTTP 404 Not Found if the taxonomy or node does not exist.

Permanently delete a metadata template and all its instances from files and folders. WARNING: This operation is destructive and cannot be undone. Once deleted: - The template definition is permanently removed - All metadata instances using this template on files/folders are also deleted - Any cascade policies using this template will stop working Scope: Use 'enterprise' for custom templates created within your organization. Global templates (scope='global') cannot be deleted. Required Permission: Requires 'manage enterprise properties' scope. Only enterprise admins can delete metadata templates.

Removes a retention policy assignment from content in Box. This action permanently removes the link between a retention policy and its assigned target (folder, enterprise, or metadata template). Once removed, the retention policy will no longer apply to the previously associated content. Important restrictions: - Only assignments for modifiable retention policies can be deleted. - Assignments for non-modifiable (regulatory) retention policies cannot be removed to ensure compliance with retention requirements. - Requires Box Governance license and admin permissions. Required scopes: manage_data_retention, enterprise_content Returns: HTTP 204 No Content on success (empty response body).

Removes a shared link from a web link in Box. This action disables the shared link for the specified web link, making it no longer accessible via the previously shared URL. The web link itself is not deleted - only the shared link is removed. After successful execution, the shared_link field in the response will be null. This is an idempotent operation - calling it on a web link that already has no shared link will succeed without error.

Permanently deletes a task from Box. Tasks are work assignments on files that can be assigned to collaborators for review or completion. Once deleted, the task and its assignments are permanently removed and cannot be recovered. Returns HTTP 204 (No Content) on successful deletion. Returns HTTP 404 if the task does not exist or has already been deleted. Use cases: - Remove completed tasks to clean up a file's task list - Cancel tasks that are no longer needed - Delete tasks created in error

Abort and permanently remove a chunked upload session, discarding all uploaded data. This action is irreversible - once removed, all uploaded file parts are permanently deleted and the upload session cannot be recovered. Use this to cancel an in-progress chunked upload or clean up abandoned upload sessions. Returns HTTP 204 (No Content) on success. The upload_session_id can be obtained from the response of the 'Create upload session' or 'Get upload session' endpoints.

Removes a user's exemption from the enterprise's collaboration domain restrictions. After removal, the user will be subject to the allowed collaboration domain list configured for the enterprise and can no longer collaborate with users from domains outside of that list. PREREQUISITES: - The exemption must exist (obtain ID from 'List users exempt from collaboration domain restrictions' or when creating an exemption). - Requires enterprise admin privileges. - The enterprise must have collaboration domain restrictions enabled. COMMON ERRORS: - 204 No Content: Successful deletion (empty response body). - 403 Forbidden: Insufficient permissions or collaboration domain restrictions feature not enabled for the enterprise. - 404 Not Found: The specified exemption ID does not exist. NOTE: This is a destructive action. Once removed, the exemption cannot be recovered and the user will immediately be subject to domain restrictions.

Deletes a specific group membership. Only admins of this group or users with admin-level permissions will be able to use this API.

Removes the watermark from a file. This action deletes the watermark that was previously applied to the specified file. After removal, the file will no longer display watermark overlays when viewed or downloaded. Returns: - 204 No Content: Watermark successfully removed (empty response body) - 404 Not Found: File does not exist or has no watermark applied Note: This operation is idempotent. If the file doesn't have a watermark, the API will return a 404 error.

Removes the watermark from a folder. This action deletes the watermark applied to a specified folder. The folder must have a watermark applied to it, otherwise the API will return a 404 error. Only users with Owner, Co-owner, or Editor permissions on the folder can remove watermarks. This feature is available for Box Enterprise plans and above.

Deletes a web link.

Permanently deletes a webhook from the Box account. Webhooks are used to receive notifications at a specified URL when events occur on Box content. Once deleted, the webhook will no longer send notifications for its configured triggers. This operation cannot be undone. To restore webhook functionality, you would need to create a new webhook with the same configuration. Returns an empty response (HTTP 204) on success. Returns 404 if the webhook ID does not exist or the user doesn't have access to it. Returns 403 if the application doesn't have the 'Manage Webhooks' permission scope.

Revoke an active Access Token, effectively logging a user out that has been previously authenticated.

Transfers all files and folders owned by one user to another user's account in Box. This creates a new folder in the destination user's root directory containing all the source user's content. The operation is commonly used for employee offboarding, role transitions, or account consolidation. Important: This operation is irreversible and requires enterprise admin permissions. All existing shared links and folder-level collaborations are preserved during transfer.

Deletes the last level from a metadata taxonomy by trimming it. Use when you need to remove the deepest hierarchical level from a taxonomy structure.

Remove a legal hold policy assignment from an item (user, folder, file, or file version). This endpoint unassigns a legal hold policy by deleting the assignment record. When successful, the API returns a 202 Accepted response with an empty body. IMPORTANT: This is an asynchronous operation - the legal hold is not fully removed when the response returns. The removal process continues in the background. To get the assignment ID: - Use 'assign_legal_hold_policy' and capture the returned 'id' field - Or use 'list_legal_hold_policy_assignments' to find existing assignment IDs Prerequisites: - Box Enterprise account with Box Governance add-on - OAuth scope: 'manage_legal_hold' - Admin-level permissions on the Box account Use case: Remove legal holds when litigation is resolved or content no longer needs to be preserved for compliance purposes.

Deletes a storage policy assignment, causing the assigned user to inherit the enterprise's default storage policy (Box Zone). Use this action when you want to reset a user's storage policy back to the enterprise default. This is useful when: - A user moves to a different region and should use the default zone - Cleaning up custom storage assignments - Reverting a user's data residency settings Prerequisites: Requires Box Zones feature to be enabled for the enterprise. Rate Limit: Only twice per user in a 24-hour period. Response: Returns 204 No Content on success (empty data object).

Deletes a specific task assignment, removing the task from the assigned user. This action unassigns a user from a task without deleting the task itself. The task remains on the file and can be reassigned to other users. To delete the task entirely, use the 'remove_task' action instead. The authenticated user must have permission to modify task assignments on the file. Typically, this means being the user who created the assignment, the assigned user themselves, or having appropriate file access permissions.