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:

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

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

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

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

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

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

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

Creates a web link object within a folder.

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

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

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.

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

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

Deletes a file from Box by moving it to trash or permanently (based on enterprise settings). Use the if_match parameter with the file's ETag for safe concurrent operations. To permanently delete a trashed file, use the 'Permanently remove file' action instead.

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.

Deletes a file request permanently. File requests allow external users to upload files to a specific folder without needing a Box account. This action permanently deletes a file request. 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 (

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

Deletes a folder, either permanently or by moving it to the trash.

Deletes a folder lock on a given folder, removing restrictions on move and delete operations. You must be authenticated as the owner or co-owner of the folder to use this endpoint. This action removes a lock that was previously applied to prevent a folder from being moved or deleted. Once the lock is removed, the folder can be moved, transferred to another owner, or deleted normally.

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

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.

Permanently deletes a retention policy from the Box enterprise. This action removes the specified retention policy. Once deleted, the policy cannot be recovered. Only modifiable retention policies can be deleted; non-modifiable policies used for regulatory compliance cannot be deleted. The authenticated user must have admin privileges and the application must have the 'manage_data_retention' or 'enterprise_content' scope enabled. Returns an empty response (HTTP 204) on successful deletion.

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

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

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

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

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.

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:

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.

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

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.

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.

Deletes a web link.

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

Returns the contents of a file in binary format.

Downloads a zip archive containing files and/or folders from Box. Prerequisites: You must first call 'BOX_CREATE_ZIP_DOWNLOAD' to create a zip download request. The response from that action contains a 'download_url' field, from which you should extract the 'zip_download_id'. Important Notes: - The download URL is only valid for a limited time (typically a few seconds after creation, or 12 hours once the download starts). - Once a download has started, it cannot be stopped and resumed. - If the download fails or times out, create a new zip download request. Returns the zip archive in binary format as a downloadable file.

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.

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.

Returns the file represented by a shared link. A shared file 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 file when only given a shared link. The shared_link_permission_options array field can be returned by requesting it in the fields query parameter.

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.

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.

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.

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=["ask", "text_gen", "extract"]

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.

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.

Retrieves the details about a file.

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.

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 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 [found on our community site][1]. [1]:

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.

Retrieves details for a folder, including the first 100 entries in the folder. Passing sort, direction, offset, and limit parameters in query allows you to manage the list of returned folder items [blocked]. To fetch more items within the folder, use the Get items in a folder [blocked] endpoint.

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:

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 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 [blocked] or file versions under retention [blocked] 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.

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.

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

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

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 [blocked] API. To list all items that have been moved to the trash, please use the GET /folders/trash/items [blocked] 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 [blocked] API. To list all items that have been moved to the trash, please use the GET /folders/trash/items [blocked] 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 a FileDownloadable object containing the avatar image. 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 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 the watermark for a folder.

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.

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.

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.

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

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.

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

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

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.

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.

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.

Retrieves a list of comments for a file.

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.

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 [blocked] or file versions under retention [blocked] 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 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 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.

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

Retrieves a page of items in a folder. These items can be files, folders, and web links. To request more information about the folder itself, like its size, use the

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

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

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.

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.

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

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.

Lists

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

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

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.

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.

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.

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.

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.

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.

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.

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.

Request an Access Token using either a client-side obtained OAuth 2.0 authorization code or a server-side JWT assertion. An Access Token is a string that enables Box to verify that a request belongs to an authorized session. In the normal order of operations you will begin by requesting authentication from the

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

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

Searches for files, folders, web links, and shared files across the users content or across the entire enterprise.

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[].id, and any outcome IDs if needed. 3. Call this endpoint with the extracted IDs and the file IDs to process. Returns HTTP 204 No Content on success.

Terminates all active sessions for users belonging to the specified Box enterprise groups. This action validates the roles and permissions of each group, then creates asynchronous background jobs to terminate sessions for all users in those groups. The operation is processed asynchronously - check admin events to monitor job status. Requires admin privileges. Use this to enforce security policies or respond to security incidents affecting entire groups.

Creates asynchronous jobs to terminate active Box sessions for specified users. Use this when a user account may be compromised, a device is lost/stolen, or you need to force users to re-authenticate. This logs out users from all active sessions including web, desktop, and mobile apps. Both user_ids and user_logins parameters are required. Returns HTTP 202 on success with an async job created.

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.

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 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 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. This can be used to rename or move a file, create a shared link, or lock a file.

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 folder. This can be also be used to move the folder, create shared links, update collaborations, and more.

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.

Change the status of a shield information barrier. Shield information barriers are ethical walls that prevent exchanges or communication between individuals/groups within the same enterprise to avoid conflicts of interest. This action allows you to: - Set status to 'pending': Transition a barrier from 'draft' status in preparation for enablement - Set status to 'disabled': Deactivate an enabled or pending barrier Note: Barriers cannot be directly enabled via this endpoint. The 'enabled' status is set automatically by Box after all required segments and restrictions are configured on a 'pending' barrier.

Updates an existing

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:

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

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.

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.

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 [blocked] and Get upload session [blocked] 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