Version 1
Connector Overview: This page documents all 266 actions for the Boxconnector v1.
AI (3)
GET Get AI agent default configuration
/ai_agent_default
Get the AI agent default config
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The mode to filter the agent config to return. |
|
|
The ISO language code to return the agent config for.
|
|
|
The model to return the default agent config for. |
|
|
N/A |
POST Send AI question request
/ai/ask
Sends an AI request to supported LLMs and returns an answer specifically focused on the user's question given the provided context.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (3)
|
Option Name |
Description |
|---|---|
|
|
The mode specifies if this request is for a single or multiple items. If you select single_item_qa the items array can have one element only. Selecting multiple_item_qa allows you to provide up to 25 items. |
|
|
The prompt provided by the client to be answered by the LLM. The prompt's length is limited to 10000 characters. |
|
|
A flag to indicate whether citations should be returned. |
POST Send AI request to generate text
/ai/text_gen
Sends an AI request to supported LLMs and returns an answer specifically focused on the creation of new text.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
The prompt provided by the client to be answered by the LLM. The prompt's length is limited to 10000 characters. |
Authorization (4)
GET Authorize user
/authorize
Authorize a user by sending them through the Box
website and request their permission to act on their behalf.
This is the first step when authenticating a user using
OAuth 2.0. To request a user's authorization to use the Box APIs
on their behalf you will need to send a user to the URL with this
format.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The type of response we'd like to receive. |
|
|
The Client ID of the application that is requesting to authenticate
|
|
|
The URI to which Box redirects the browser after the user has granted
|
|
|
A custom string of your choice. Box will pass the same string to
|
|
|
A space-separated list of application scopes you'd like to
|
|
|
N/A |
POST Refresh access token
/oauth2/token#refresh
Refresh an Access Token using its client ID, secret, and refresh token.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (4)
|
Option Name |
Description |
|---|---|
|
|
The type of request being made, in this case a refresh request. |
|
|
The client ID of the application requesting to refresh the token. |
|
|
The client secret of the application requesting to refresh the token. |
|
|
The refresh token to refresh. |
POST Request access token
/oauth2/token
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
authorize endpoint and Box will send you an
authorization code.
You will then send this code to this endpoint to exchange it for
an Access Token. The returned Access Token can then be used to to make
Box API calls.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (15)
|
Option Name |
Description |
|---|---|
|
|
The type of request being made, either using a client-side obtained
|
|
|
The Client ID of the application requesting an access token. Used in combination with authorization_code, client_credentials, or
|
|
|
The client secret of the application requesting an access token. Used in combination with authorization_code, client_credentials, or
|
|
|
The client-side authorization code passed to your application by
Used in combination with authorization_code as the grant_type. |
|
|
A refresh token used to get a new access token with. Used in combination with refresh_token as the grant_type. |
|
|
A JWT assertion for which to request a new access token. Used in combination with urn:ietf:params:oauth:grant-type:jwt-bearer
|
|
|
The token to exchange for a downscoped token. This can be a regular
Used in combination with urn:ietf:params:oauth:grant-type:token-exchange
|
|
|
The type of subject_token passed in. Used in combination with urn:ietf:params:oauth:grant-type:token-exchange
|
|
|
The token used to create an annotator token.
Used in combination with urn:ietf:params:oauth:grant-type:token-exchange
|
|
|
The type of actor_token passed in. Used in combination with urn:ietf:params:oauth:grant-type:token-exchange
|
|
|
The space-delimited list of scopes that you want apply to the
The subject_token will need to have all of these scopes or
|
|
|
Full URL for the file that the token should be generated for. |
|
|
Used in combination with client_credentials as the grant_type. |
|
|
Used in combination with client_credentials as the grant_type.
|
|
|
Full URL of the shared link on the file or folder
|
POST Revoke access token
/oauth2/revoke
Revoke an active Access Token, effectively logging a user out
that has been previously authenticated.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (3)
|
Option Name |
Description |
|---|---|
|
|
The Client ID of the application requesting to revoke the
|
|
|
The client secret of the application requesting to revoke
|
|
|
The access token to revoke. |
Classifications on files (4)
POST Add classification to file
/files/{file_id}/metadata/enterprise/securityClassification-6VMVochwUWo
Adds a classification to a file by specifying the label of the
classification to add.
This API can also be called by including the enterprise ID in the
URL explicitly, for example
/files/:id//enterprise_12345/securityClassification-6VMVochwUWo.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
The name of the classification to apply to this file. To list the available classifications in an enterprise,
|
GET Get classification on file
/files/{file_id}/metadata/enterprise/securityClassification-6VMVochwUWo
Retrieves the classification metadata instance that
has been applied to a file.
This API can also be called by including the enterprise ID in the
URL explicitly, for example
/files/:id//enterprise_12345/securityClassification-6VMVochwUWo.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
N/A |
DELETE Remove classification from file
/files/{file_id}/metadata/enterprise/securityClassification-6VMVochwUWo
Removes any classifications from a file.
This API can also be called by including the enterprise ID in the
URL explicitly, for example
/files/:id//enterprise_12345/securityClassification-6VMVochwUWo.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
N/A |
PUT Update classification on file
/files/{file_id}/metadata/enterprise/securityClassification-6VMVochwUWo
Updates a classification on a file.
The classification can only be updated if a classification has already been
applied to the file before. When editing classifications, only values are
defined for the enterprise will be accepted.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
N/A |
Options (3)
|
Option Name |
Description |
|---|---|
|
|
replace |
|
|
Defines classifications
|
|
|
The name of the classification to apply to this file. To list the available classifications in an enterprise,
|
Classifications on folders (4)
POST Add classification to folder
/folders/{folder_id}/metadata/enterprise/securityClassification-6VMVochwUWo
Adds a classification to a folder by specifying the label of the
classification to add.
This API can also be called by including the enterprise ID in the
URL explicitly, for example
/folders/:id//enterprise_12345/securityClassification-6VMVochwUWo.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent a folder. The ID for any folder can be determined
The root folder of a Box account is
|
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
The name of the classification to apply to this folder. To list the available classifications in an enterprise,
|
GET Get classification on folder
/folders/{folder_id}/metadata/enterprise/securityClassification-6VMVochwUWo
Retrieves the classification metadata instance that
has been applied to a folder.
This API can also be called by including the enterprise ID in the
URL explicitly, for example
/folders/:id//enterprise_12345/securityClassification-6VMVochwUWo.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent a folder. The ID for any folder can be determined
The root folder of a Box account is
|
|
|
N/A |
DELETE Remove classification from folder
/folders/{folder_id}/metadata/enterprise/securityClassification-6VMVochwUWo
Removes any classifications from a folder.
This API can also be called by including the enterprise ID in the
URL explicitly, for example
/folders/:id//enterprise_12345/securityClassification-6VMVochwUWo.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent a folder. The ID for any folder can be determined
The root folder of a Box account is
|
|
|
N/A |
PUT Update classification on folder
/folders/{folder_id}/metadata/enterprise/securityClassification-6VMVochwUWo
Updates a classification on a folder.
The classification can only be updated if a classification has already been
applied to the folder before. When editing classifications, only values are
defined for the enterprise will be accepted.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent a folder. The ID for any folder can be determined
The root folder of a Box account is
|
|
|
N/A |
Options (3)
|
Option Name |
Description |
|---|---|
|
|
replace |
|
|
Defines classifications
|
|
|
The name of the classification to apply to this folder. To list the available classifications in an enterprise,
|
Classifications (4)
PUT Add classification
/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema#add
Adds one or more new classifications to the list of classifications
available to the 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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (2)
|
Option Name |
Description |
|---|---|
|
|
The type of change to perform on the classification
|
|
|
Defines classifications
|
POST Add initial classifications
/metadata_templates/schema#classifications
When an enterprise does not yet have any classifications, this API call
initializes the classification template with an initial set of
classifications.
If an enterprise already has a classification, the template will already
exist and instead an API call should be made to add additional
classifications.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (5)
|
Option Name |
Description |
|---|---|
|
|
The scope in which to create the classifications. This should
|
|
|
Defines the list of metadata templates. |
|
|
The name of the
|
|
|
Determines if the classification template is
|
|
|
Determines if classifications are
|
GET List all classifications
/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
PUT Update classification
/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema#update
Updates the labels and descriptions of one or more classifications
available to the 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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (3)
|
Option Name |
Description |
|---|---|
|
|
The type of change to perform on the classification
|
|
|
Defines classifications
|
|
|
The original label of the classification to change. |
Collaborations (List) (4)
GET List file collaborations
/files/{file_id}/collaborations
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
The maximum number of items to return per page. |
|
|
Defines the position marker at which to begin returning results. This is
This requires usemarker to be set to true. |
|
|
N/A |
GET List folder collaborations
/folders/{folder_id}/collaborations
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent a folder. The ID for any folder can be determined
|
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
GET List group collaborations
/groups/{group_id}/collaborations
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the group. |
|
|
The maximum number of items to return per page. |
|
|
The offset of the item at which to begin the response. Queries with offset parameter value
|
|
|
N/A |
GET List pending collaborations
/collaborations
Retrieves all pending collaboration invites for this user.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The status of the collaborations to retrieve |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
The offset of the item at which to begin the response. Queries with offset parameter value
|
|
|
The maximum number of items to return per page. |
|
|
N/A |
Collaborations (4)
POST Create collaboration
/collaborations
Adds a collaboration for a single user or a single group to a file
or folder.
Collaborations can be created using email address, user IDs, or a
group IDs.
If a collaboration is being created with a group, access to
this endpoint is dependent on the group's ability to be invited.
If collaboration is in pending status, the following fields
are redacted:
-
loginandnameare hidden if a collaboration was created
using user_id,
-
nameis hidden if a collaboration was created usinglogin.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
Determines if users should receive email notification
|
|
|
N/A |
Options (4)
|
Option Name |
Description |
|---|---|
|
|
The level of access granted. |
|
|
If set to true, collaborators have access to
|
|
|
Determines if the invited users can see the entire parent path to
Be aware that this meaningfully increases the time required to load the
Only owner or co-owners can invite collaborators with a can_view_path of
can_view_path can only be used for folder collaborations. |
|
|
Set the expiration date for the collaboration. At this date, the
This feature will only work if the Automatically remove invited
|
GET Get collaboration
/collaborations/{collaboration_id}
Retrieves a single collaboration.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the collaboration |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
DELETE Remove collaboration
/collaborations/{collaboration_id}
Deletes a single collaboration.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the collaboration |
|
|
N/A |
PUT Update collaboration
/collaborations/{collaboration_id}
Updates a collaboration.
Can be used to change the owner of an item, or to
accept collaboration invites.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the collaboration |
|
|
N/A |
Options (4)
|
Option Name |
Description |
|---|---|
|
|
The level of access granted. |
|
|
Set the status of a pending collaboration invitation,
|
|
|
Update the expiration date for the collaboration. At this date,
This feature will only work if the Automatically remove invited
Additionally, a collaboration can only be given an
|
|
|
Determines if the invited users can see the entire parent path to
Be aware that this meaningfully increases the time required to load the
Only owner or co-owners can invite collaborators with a can_view_path of
can_view_path can only be used for folder collaborations. |
Collections (2)
GET List all collections
/collections
Retrieves all collections for a given user.
Currently, only the favorites collection
is supported.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
The offset of the item at which to begin the response. Queries with offset parameter value
|
|
|
The maximum number of items to return per page. |
|
|
N/A |
GET List collection items
/collections/{collection_id}/items
Retrieves the files and/or folders contained within
this collection.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the collection. |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
The offset of the item at which to begin the response. Queries with offset parameter value
|
|
|
The maximum number of items to return per page. |
|
|
N/A |
Comments (5)
POST Create comment
/comments
Adds a comment by the user to a specific file, or
as a reply to an other comment.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
Options (2)
|
Option Name |
Description |
|---|---|
|
|
The text of the comment. To mention a user, use the tagged_message
|
|
|
The text of the comment, including @[user_id:name]
The user_id is the target user's ID, where the name
If you are not mentioning another user, use message
|
GET Get comment
/comments/{comment_id}
Retrieves the message and metadata for a specific comment, as well
as information on the user who created the comment.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the comment. |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
GET List file comments
/files/{file_id}/comments
Retrieves a list of comments for a file.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
The maximum number of items to return per page. |
|
|
The offset of the item at which to begin the response. Queries with offset parameter value
|
|
|
N/A |
DELETE Remove comment
/comments/{comment_id}
Permanently deletes a comment.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the comment. |
|
|
N/A |
PUT Update comment
/comments/{comment_id}
Update the message of a comment.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the comment. |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
The text of the comment to update |
Device pinners (3)
GET Get device pin
/device_pinners/{device_pinner_id}
Retrieves information about an individual device pin.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the device pin |
|
|
N/A |
GET List enterprise device pins
/enterprises/{enterprise_id}/device_pinners
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the enterprise |
|
|
Defines the position marker at which to begin returning results. This is
This requires usemarker to be set to true. |
|
|
The maximum number of items to return per page. |
|
|
The direction to sort results in. This can be either in alphabetical ascending
|
|
|
N/A |
DELETE Remove device pin
/device_pinners/{device_pinner_id}
Deletes an individual device pin.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the device pin |
|
|
N/A |
Domain restrictions (User exemptions) (4)
POST Create user exemption from collaboration domain restrictions
/collaboration_whitelist_exempt_targets
Exempts a user from the restrictions set out by the allowed list of domains
for collaborations.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
GET Get user exempt from collaboration domain restrictions
/collaboration_whitelist_exempt_targets/{collaboration_whitelist_exempt_target_id}
Returns a users who has been exempt from the collaboration
domain restrictions.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the exemption to the list. |
|
|
N/A |
GET List users exempt from collaboration domain restrictions
/collaboration_whitelist_exempt_targets
Returns a list of users who have been exempt from the collaboration
domain restrictions.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
Defines the position marker at which to begin returning results. This is
This requires usemarker to be set to true. |
|
|
The maximum number of items to return per page. |
|
|
N/A |
DELETE Remove user from list of users exempt from domain restrictions
/collaboration_whitelist_exempt_targets/{collaboration_whitelist_exempt_target_id}
Removes a user's exemption from the restrictions set out by the allowed list
of domains for collaborations.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the exemption to the list. |
|
|
N/A |
Domain restrictions for collaborations (4)
POST Add domain to list of allowed collaboration domains
/collaboration_whitelist_entries
Creates a new entry in the list of allowed domains to allow
collaboration for.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (2)
|
Option Name |
Description |
|---|---|
|
|
The domain to add to the list of allowed domains. |
|
|
The direction in which to allow collaborations. |
GET Get allowed collaboration domain
/collaboration_whitelist_entries/{collaboration_whitelist_entry_id}
Returns a domain that has been deemed safe to create collaborations
for within the current enterprise.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the entry in the list. |
|
|
N/A |
GET List allowed collaboration domains
/collaboration_whitelist_entries
Returns the list domains that have been deemed safe to create collaborations
for within the current enterprise.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
Defines the position marker at which to begin returning results. This is
This requires usemarker to be set to true. |
|
|
The maximum number of items to return per page. |
|
|
N/A |
DELETE Remove domain from list of allowed collaboration domains
/collaboration_whitelist_entries/{collaboration_whitelist_entry_id}
Removes a domain from the list of domains that have been deemed safe to create
collaborations for within the current enterprise.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the entry in the list. |
|
|
N/A |
Downloads
GET Download file
/files/{file_id}/content
Returns the contents of a file in binary format.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
The byte range of the content to download. The format bytes={start_byte}-{end_byte} can be used to specify
|
|
|
The URL, and optional password, for the shared link of this item. This header can be used to access items that have not been
Use the format shared_link=[link] or if a password is required then
This header can be used on the file or folder shared, as well as on any files
|
|
|
The file version to download |
|
|
An optional access token that can be used to pre-authenticate this request, which means that a download link can be shared with a browser or a third party service without them needing to know how to handle the authentication.
|
|
|
N/A |
Email aliases (3)
POST Create email alias
/users/{user_id}/email_aliases
Adds a new email alias to a user account..
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the user. |
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
The email address to add to the account as an alias. Note: The domain of the email alias needs to be registered
|
GET List user's email aliases
/users/{user_id}/email_aliases
Retrieves all email aliases for a user. The collection
does not include the primary login for the user.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the user. |
|
|
N/A |
DELETE Remove email alias
/users/{user_id}/email_aliases/{email_alias_id}
Removes an email alias from a user.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the user. |
|
|
The ID of the email alias. |
|
|
N/A |
Events (2)
GET Get events long poll endpoint (OPTIONS)
/events
Returns a list of real-time servers that can be used for long-polling updates
to the event stream.
Long polling is the concept where a HTTP request is kept open until the
server sends a response, then repeating the process over and over to receive
updated responses.
Long polling the event stream can only be used for user events, not for
enterprise events.
To use long polling, first use this endpoint to retrieve a list of long poll
URLs. Next, make a long poll request to any of the provided URLs.
When an event occurs in monitored account a response with the value
new_change will be sent. The response contains no other details as
it only serves as a prompt to take further action such as sending a
request to the events endpoint with the last known
stream_position.
After the server sends this response it closes the connection. You must now
repeat the long poll process to begin listening for events again.
If no events occur for a while and the connection times out you will
receive a response with the value reconnect. When you receive this response
you’ll make another call to this endpoint to restart the process.
If you receive no events in retry_timeout seconds then you will need to
make another request to the real-time server (one of the URLs in the response
for this endpoint). This might be necessary due to network errors.
Finally, if you receive a max_retries error when making a request to the
real-time server, you should start over by making a call to this endpoint
first.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
GET List user and enterprise events
/events
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
Defines the type of events that are returned all returns everything for a user and is the default
requires the user making the API call to have admin permissions. This
|
|
|
The location in the event stream to start receiving events from. now will return an empty list events and
|
|
|
Limits the number of events returned Note: Sometimes, the events less than the limit requested can be returned
|
|
|
A comma-separated list of events to filter by. This can only be used when
|
|
|
The lower bound date and time to return events for. This can only be used
|
|
|
The upper bound date and time to return events for. This can only be used
|
|
|
N/A |
File requests (4)
POST Copy file request
/file_requests/{file_request_id}/copy
Copies an existing file request that is already present on one folder,
and applies it to another folder.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent a file request. The ID for any file request can be determined
|
|
|
N/A |
Options (6)
|
Option Name |
Description |
|---|---|
|
|
An optional new title for the file request. This can be
This will default to the value on the existing file request. |
|
|
An optional new description for the file request. This can be
This will default to the value on the existing file request. |
|
|
An optional new status of the file request. When the status is set to inactive, the file request
This will default to the value on the existing file request. |
|
|
Whether a file request submitter is required to provide
When this setting is set to true, the Box UI will show
This will default to the value on the existing file request. |
|
|
Whether a file request submitter is required to provide
When this setting is set to true, the Box UI will show
This will default to the value on the existing file request. |
|
|
The date after which a file request will no longer accept new
After this date, the status will automatically be set to
This will default to the value on the existing file request. |
DELETE Delete file request
/file_requests/{file_request_id}
Deletes a file request permanently.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent a file request. The ID for any file request can be determined
|
|
|
N/A |
GET Get file request
/file_requests/{file_request_id}
Retrieves the information about a file request.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent a file request. The ID for any file request can be determined
|
|
|
N/A |
PUT Update file request
/file_requests/{file_request_id}
Updates a file request. This can be used to activate or
deactivate a file request.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent a file request. The ID for any file request can be determined
|
|
|
Ensures this item hasn't recently changed before
Pass in the item's last observed etag value
|
|
|
N/A |
Options (6)
|
Option Name |
Description |
|---|---|
|
|
An optional new title for the file request. This can be
This will default to the value on the existing file request. |
|
|
An optional new description for the file request. This can be
This will default to the value on the existing file request. |
|
|
An optional new status of the file request. When the status is set to inactive, the file request
This will default to the value on the existing file request. |
|
|
Whether a file request submitter is required to provide
When this setting is set to true, the Box UI will show
This will default to the value on the existing file request. |
|
|
Whether a file request submitter is required to provide
When this setting is set to true, the Box UI will show
This will default to the value on the existing file request. |
|
|
The date after which a file request will no longer accept new
After this date, the status will automatically be set to
This will default to the value on the existing file request. |
File version legal holds (2)
GET Get file version legal hold
/file_version_legal_holds/{file_version_legal_hold_id}
Retrieves information about the legal hold policies
assigned to a file version.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the file version legal hold |
|
|
N/A |
GET List file version legal holds
/file_version_legal_holds
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the legal hold policy to get the file version legal
|
|
|
Defines the position marker at which to begin returning results. This is
This requires usemarker to be set to true. |
|
|
The maximum number of items to return per page. |
|
|
N/A |
File version retentions (2)
GET Get retention on file
/file_version_retentions/{file_version_retention_id}
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the file version retention |
|
|
N/A |
GET List file version retentions
/file_version_retentions
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
Filters results by files with this ID. |
|
|
Filters results by file versions with this ID. |
|
|
Filters results by the retention policy with this ID. |
|
|
Filters results by the retention policy with this disposition
|
|
|
Filters results by files that will have their disposition
|
|
|
Filters results by files that will have their disposition
|
|
|
The maximum number of items to return per page. |
|
|
Defines the position marker at which to begin returning results. This is
This requires usemarker to be set to true. |
|
|
N/A |
File versions (5)
GET Get file version
/files/{file_id}/versions/{file_version_id}
Retrieve a specific version of a file.
Versions are only tracked for Box users with premium accounts.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
The ID of the file version |
|
|
N/A |
GET List all file versions
/files/{file_id}/versions
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
The maximum number of items to return per page. |
|
|
The offset of the item at which to begin the response. Queries with offset parameter value
|
|
|
N/A |
POST Promote file version
/files/{file_id}/versions/current
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
Options (2)
|
Option Name |
Description |
|---|---|
|
|
The file version ID |
|
|
The type to promote |
DELETE Remove file version
/files/{file_id}/versions/{file_version_id}
Move a file version to the trash.
Versions are only tracked for Box users with premium accounts.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
The ID of the file version |
|
|
Ensures this item hasn't recently changed before
Pass in the item's last observed etag value
|
|
|
N/A |
PUT Restore file version
/files/{file_id}/versions/{file_version_id}
Restores a specific version of a file after it was deleted.
Don't use this endpoint to restore Box Notes,
as it works with file formats such as PDF, DOC,
PPTX or similar.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
The ID of the file version |
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
Set this to null to clear
|
Files (6)
POST Copy file
/files/{file_id}/copy
Creates a copy of a file.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
Options (2)
|
Option Name |
Description |
|---|---|
|
|
An optional new name for the copied file. There are some restrictions to the file name. Names containing
|
|
|
An optional ID of the specific file version to copy. |
DELETE Delete file
/files/{file_id}
Deletes a file, either permanently or by moving it to
the trash.
The the enterprise settings determine whether the item will
be permanently deleted from Box or moved to the trash.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
Ensures this item hasn't recently changed before
Pass in the item's last observed etag value
|
|
|
N/A |
GET Get file information
/files/{file_id}
Retrieves the details about a file.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
Additionally this field can be used to query any metadata
|
|
|
Ensures an item is only returned if it has changed. Pass in the item's last observed etag value
|
|
|
The URL, and optional password, for the shared link of this item. This header can be used to access items that have not been
Use the format shared_link=[link] or if a password is required then
This header can be used on the file or folder shared, as well as on any files
|
|
|
A header required to request specific representations
The general format for these representations is
For example, to request a png representation in 32x32
x-rep-hints: [jpg?dimensions=32x32][jpg?dimensions=64x64] Additionally, a text representation is available for all
x-rep-hints: [extracted_text] |
|
|
N/A |
GET Get file thumbnail
/files/{file_id}/thumbnail.{extension}
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]: https://community.box.com/t5/Migrating-and-Previewing-Content/File-Types-and-Fonts-Supported-in-Box-Content-Preview/ta-p/327
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
The file format for the thumbnail |
|
|
The minimum height of the thumbnail |
|
|
The minimum width of the thumbnail |
|
|
The maximum height of the thumbnail |
|
|
The maximum width of the thumbnail |
|
|
N/A |
POST Preflight check before upload (OPTIONS)
/files/content
Performs a check to verify that a file will be accepted by Box
before you upload the entire file.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (2)
|
Option Name |
Description |
|---|---|
|
|
The name for the file |
|
|
The size of the file in bytes |
PUT Update file
/files/{file_id}
Updates a file. This can be used to rename or move a file,
create a shared link, or lock a file.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
Ensures this item hasn't recently changed before
Pass in the item's last observed etag value
|
|
|
N/A |
Options (4)
|
Option Name |
Description |
|---|---|
|
|
An optional different name for the file. This can be used to
|
|
|
The description for a file. This can be seen in the right-hand sidebar panel
|
|
|
The retention expiration timestamp for the given file. This
|
|
|
The tags for this item. These tags are shown in
To add or remove a tag, retrieve the item's current tags,
There is a limit of 100 tags per item, and 10,000
|
Folder Locks (3)
POST Create folder lock
/folder_locks
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
DELETE Delete folder lock
/folder_locks/{folder_lock_id}
Deletes a folder lock on a given folder.
You must be authenticated as the owner or co-owner of the folder to
use this endpoint.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the folder lock. |
|
|
N/A |
GET List folder locks
/folder_locks
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent a folder. The ID for any folder can be determined
The root folder of a Box account is
|
|
|
N/A |
Folders (6)
POST Copy folder
/folders/{folder_id}/copy
Creates a copy of a folder within a destination folder.
The original folder will not be changed.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier of the folder to copy. The ID for any folder can be determined
The root folder with the ID 0 can not be copied. |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
An optional new name for the copied folder. There are some restrictions to the file name. Names containing
Additionally, the names . and .. are
|
POST Create folder
/folders
Creates a new empty folder within the specified parent folder.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
Options (2)
|
Option Name |
Description |
|---|---|
|
|
The name for the new folder. There are some restrictions to the file name. Names containing
Additionally, the names . and .. are
|
|
|
Specifies whether a folder should be synced to a
|
DELETE Delete folder
/folders/{folder_id}
Deletes a folder, either permanently or by moving it to
the trash.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent a folder. The ID for any folder can be determined
The root folder of a Box account is
|
|
|
Ensures this item hasn't recently changed before
Pass in the item's last observed etag value
|
|
|
Delete a folder that is not empty by recursively deleting the
|
|
|
N/A |
GET Get folder information
/folders/{folder_id}
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.
To fetch more items within the folder, use the
Get items in a folder endpoint.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent a folder. The ID for any folder can be determined
The root folder of a Box account is
|
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
Additionally this field can be used to query any metadata
|
|
|
Ensures an item is only returned if it has changed. Pass in the item's last observed etag value
|
|
|
The URL, and optional password, for the shared link of this item. This header can be used to access items that have not been
Use the format shared_link=[link] or if a password is required then
This header can be used on the file or folder shared, as well as on any files
|
|
|
Defines the second attribute by which items
The folder type affects the way the items
Standard folder:
Root folder:
(the folder with an id of 0).
to the associated folder visible to
|
|
|
The direction to sort results in. This can be either in alphabetical ascending
|
|
|
The offset of the item at which to begin the response. Queries with offset parameter value
|
|
|
The maximum number of items to return per page. |
|
|
N/A |
GET List items in folder
/folders/{folder_id}/items
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 Get a folder endpoint instead.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent a folder. The ID for any folder can be determined
The root folder of a Box account is
|
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
Additionally this field can be used to query any metadata
|
|
|
Specifies whether to use marker-based pagination instead of
By setting this value to true, the API will return a marker field
|
|
|
Defines the position marker at which to begin returning results. This is
This requires usemarker to be set to true. |
|
|
The offset of the item at which to begin the response. Queries with offset parameter value
|
|
|
The maximum number of items to return per page. |
|
|
The URL, and optional password, for the shared link of this item. This header can be used to access items that have not been
Use the format shared_link=[link] or if a password is required then
This header can be used on the file or folder shared, as well as on any files
|
|
|
Defines the second attribute by which items
The folder type affects the way the items
Standard folder:
Root folder:
(the folder with an id of 0).
to the associated folder visible to
|
|
|
The direction to sort results in. This can be either in alphabetical ascending
|
|
|
N/A |
PUT Update folder
/folders/{folder_id}
Updates a folder. This can be also be used to move the folder,
create shared links, update collaborations, and more.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent a folder. The ID for any folder can be determined
The root folder of a Box account is
|
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
Ensures this item hasn't recently changed before
Pass in the item's last observed etag value
|
|
|
N/A |
Options (7)
|
Option Name |
Description |
|---|---|
|
|
The optional new name for this folder. |
|
|
The optional description of this folder |
|
|
Specifies whether a folder should be synced to a
|
|
|
Specifies if users who are not the owner
|
|
|
The tags for this item. These tags are shown in
To add or remove a tag, retrieve the item's current tags,
There is a limit of 100 tags per item, and 10,000
|
|
|
Specifies if new invites to this folder are restricted to users
|
|
|
Restricts collaborators who are not the owner of
It also restricts non-owners from inviting new
When setting this field to false, it is required
|
Group memberships (6)
POST Add user to group
/group_memberships
Creates a group membership. Only users with
admin-level permissions will be able to use this API.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
The role of the user in the group. |
GET Get group membership
/group_memberships/{group_membership_id}
Retrieves a specific group membership. Only admins of this
group or users with admin-level permissions will be able to
use this API.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the group membership. |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
GET List members of group
/groups/{group_id}/memberships
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the group. |
|
|
The maximum number of items to return per page. |
|
|
The offset of the item at which to begin the response. Queries with offset parameter value
|
|
|
N/A |
GET List user's groups
/users/{user_id}/memberships
Retrieves all the groups for a user. Only members of this
group or users with admin-level permissions will be able to
use this API.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the user. |
|
|
The maximum number of items to return per page. |
|
|
The offset of the item at which to begin the response. Queries with offset parameter value
|
|
|
N/A |
DELETE Remove user from group
/group_memberships/{group_membership_id}
Deletes a specific group membership. Only admins of this
group or users with admin-level permissions will be able to
use this API.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the group membership. |
|
|
N/A |
PUT Update group membership
/group_memberships/{group_membership_id}
Updates a user's group membership. Only admins of this
group or users with admin-level permissions will be able to
use this API.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the group membership. |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
The role of the user in the group. |
Groups (5)
POST Create group
/groups
Creates a new group of users in an enterprise. Only users with admin
permissions can create new groups.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
Options (6)
|
Option Name |
Description |
|---|---|
|
|
The name of the new group to be created. This name must be unique
|
|
|
Keeps track of which external source this group is
Setting this will also prevent Box admins from editing
This is desirable for one-way syncing of groups. |
|
|
An arbitrary identifier that can be used by
Example values of this field
We recommend you use of this field in
|
|
|
A human readable description of the group. |
|
|
Specifies who can invite the group to collaborate
When set to admins_only the enterprise admin, co-admins,
When set to admins_and_members all the admins listed
When set to all_managed_users all managed users in the
|
|
|
Specifies who can see the members of the group. admins_only - the enterprise admin, co-admins, group's
enterprise |
GET Get group
/groups/{group_id}
Retrieves information about a group. Only members of this
group or users with admin-level permissions will be able to
use this API.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the group. |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
GET List groups for enterprise
/groups
Retrieves all of the groups for a given enterprise. The user
must have admin permissions to inspect enterprise's groups.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
Limits the results to only groups whose name starts
|
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
The maximum number of items to return per page. |
|
|
The offset of the item at which to begin the response. Queries with offset parameter value
|
|
|
N/A |
DELETE Remove group
/groups/{group_id}
Permanently deletes a group. Only users with
admin-level permissions will be able to use this API.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the group. |
|
|
N/A |
PUT Update group
/groups/{group_id}
Updates a specific group. Only admins of this
group or users with admin-level permissions will be able to
use this API.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the group. |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
Options (6)
|
Option Name |
Description |
|---|---|
|
|
The name of the new group to be created. Must be unique within the
|
|
|
Keeps track of which external source this group is
Setting this will also prevent Box admins from editing
This is desirable for one-way syncing of groups. |
|
|
An arbitrary identifier that can be used by
Example values of this field
We recommend you use of this field in
|
|
|
A human readable description of the group. |
|
|
Specifies who can invite the group to collaborate
When set to admins_only the enterprise admin, co-admins,
When set to admins_and_members all the admins listed
When set to all_managed_users all managed users in the
|
|
|
Specifies who can see the members of the group. admins_only - the enterprise admin, co-admins, group's
enterprise |
Integration mappings (4)
POST Create Slack integration mapping
/integration_mappings/slack
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
DELETE Delete Slack integration mapping
/integration_mappings/slack/{integration_mapping_id}
Deletes a Slack integration mapping.
You need Admin or Co-Admin role to
use this endpoint.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
An ID of an integration mapping |
|
|
N/A |
GET List Slack integration mappings
/integration_mappings/slack
Lists Slack integration mappings in a users' enterprise.
You need Admin or Co-Admin role to
use this endpoint.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
Defines the position marker at which to begin returning results. This is
This requires usemarker to be set to true. |
|
|
The maximum number of items to return per page. |
|
|
Mapped item type, for which the mapping should be returned |
|
|
ID of the mapped item, for which the mapping should be returned |
|
|
Box item ID, for which the mappings should be returned |
|
|
Box item type, for which the mappings should be returned |
|
|
Whether the mapping has been manually created |
|
|
N/A |
PUT Update Slack integration mapping
/integration_mappings/slack/{integration_mapping_id}
Updates a Slack integration mapping.
Supports updating the Box folder ID and options.
You need Admin or Co-Admin role to
use this endpoint.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
An ID of an integration mapping |
|
|
N/A |
Invites (2)
POST Create user invite
/invites
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
GET Get user invite status
/invites/{invite_id}
Returns the status of a user invite.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of an invite. |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
Legal hold policies (5)
POST Create legal hold policy
/legal_hold_policies
Create a new legal hold policy.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (5)
|
Option Name |
Description |
|---|---|
|
|
The name of the policy. |
|
|
A description for the policy. |
|
|
The filter start date. When this policy is applied using a custodian legal
Required if is_ongoing is set to false. |
|
|
The filter end date. When this policy is applied using a custodian legal
Required if is_ongoing is set to false. |
|
|
Whether new assignments under this policy should
When this policy is applied using a legal hold assignment,
For example, if a legal hold assignment is placed on a user
Required if no filter dates are set. |
GET Get legal hold policy
/legal_hold_policies/{legal_hold_policy_id}
Retrieve a legal hold policy.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the legal hold policy |
|
|
N/A |
GET List all legal hold policies
/legal_hold_policies
Retrieves a list of legal hold policies that belong to
an enterprise.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
Limits results to policies for which the names start with
|
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
Defines the position marker at which to begin returning results. This is
This requires usemarker to be set to true. |
|
|
The maximum number of items to return per page. |
|
|
N/A |
DELETE Remove legal hold policy
/legal_hold_policies/{legal_hold_policy_id}
Delete an existing legal hold policy.
This is an asynchronous process. The policy will not be
fully deleted yet when the response returns.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the legal hold policy |
|
|
N/A |
PUT Update legal hold policy
/legal_hold_policies/{legal_hold_policy_id}
Update legal hold policy.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the legal hold policy |
|
|
N/A |
Options (3)
|
Option Name |
Description |
|---|---|
|
|
The name of the policy. |
|
|
A description for the policy. |
|
|
Notes around why the policy was released. |
Legal hold policy assignments (6)
POST Assign legal hold policy
/legal_hold_policy_assignments
Assign a legal hold to a file, file version, folder, or user.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
The ID of the policy to assign. |
GET Get legal hold policy assignment
/legal_hold_policy_assignments/{legal_hold_policy_assignment_id}
Retrieve a legal hold policy assignment.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the legal hold policy assignment |
|
|
N/A |
GET List files with current file versions for legal hold policy assignment
/legal_hold_policy_assignments/{legal_hold_policy_assignment_id}/files_on_hold
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the legal hold policy assignment |
|
|
Defines the position marker at which to begin returning results. This is
This requires usemarker to be set to true. |
|
|
The maximum number of items to return per page. |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
GET List legal hold policy assignments
/legal_hold_policy_assignments
Retrieves a list of items a legal hold policy has been assigned to.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the legal hold policy |
|
|
Filters the results by the type of item the
|
|
|
Filters the results by the ID of item the
|
|
|
Defines the position marker at which to begin returning results. This is
This requires usemarker to be set to true. |
|
|
The maximum number of items to return per page. |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
GET List previous file versions for legal hold policy assignment
/legal_hold_policy_assignments/{legal_hold_policy_assignment_id}/file_versions_on_hold
Get a list of previous file versions for a legal hold
assignment.
In some cases you may only need the latest file versions instead. In these
cases, use the GET /legal_hold_policy_assignments/:id/files_on_hold API
instead to return any current (latest) versions of a file for this legal hold
policy assignment.
Due to ongoing re-architecture efforts this API might not return all files
held for this policy ID. Instead, this API will only return past file versions
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the legal hold policy assignment |
|
|
Defines the position marker at which to begin returning results. This is
This requires usemarker to be set to true. |
|
|
The maximum number of items to return per page. |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
DELETE Unassign legal hold policy
/legal_hold_policy_assignments/{legal_hold_policy_assignment_id}
Remove a legal hold from an item.
This is an asynchronous process. The policy will not be
fully removed yet when the response returns.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the legal hold policy assignment |
|
|
N/A |
Metadata cascade policies (5)
POST Create metadata cascade policy
/metadata_cascade_policies
Creates a new metadata cascade policy that applies a given
metadata template to a given folder and automatically
cascades it down to any files within that folder.
In order for the policy to be applied a metadata instance must first
be applied to the folder the policy is to be applied to.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (3)
|
Option Name |
Description |
|---|---|
|
|
The ID of the folder to apply the policy to. This folder will
|
|
|
The scope of the targeted metadata template. This template will
|
|
|
The key of the targeted metadata template. This template will
In many cases the template key is automatically derived
Please [list the templates for an enterprise][list], or
[list]: e://get-metadata-templates-enterprise
|
POST Force-apply metadata cascade policy to folder
/metadata_cascade_policies/{metadata_cascade_policy_id}/apply
Force the metadata on a folder with a metadata cascade policy to be applied to
all of its children. This can be used after creating a new cascade policy to
enforce the metadata to be cascaded down to all existing files within that
folder.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the cascade policy to force-apply. |
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
Describes the desired behavior when dealing with the conflict
none will preserve the existing value on the file
|
GET Get metadata cascade policy
/metadata_cascade_policies/{metadata_cascade_policy_id}
Retrieve a specific metadata cascade policy assigned to a folder.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the metadata cascade policy. |
|
|
N/A |
GET List metadata cascade policies
/metadata_cascade_policies
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
Specifies which folder to return policies for. This can not be used on the
|
|
|
The ID of the enterprise ID for which to find metadata
|
|
|
Defines the position marker at which to begin returning results. This is
This requires usemarker to be set to true. |
|
|
The offset of the item at which to begin the response. Queries with offset parameter value
|
|
|
N/A |
DELETE Remove metadata cascade policy
/metadata_cascade_policies/{metadata_cascade_policy_id}
Deletes a metadata cascade policy.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the metadata cascade policy. |
|
|
N/A |
Metadata instances (Files) (5)
POST Create metadata instance on file
/files/{file_id}/metadata/{scope}/{template_key}
Applies an instance of a metadata template to a file.
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
The scope of the metadata template |
|
|
The name of the metadata template |
|
|
N/A |
GET Get metadata instance on file
/files/{file_id}/metadata/{scope}/{template_key}
Retrieves the instance of a metadata template that has been applied to a
file.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
The scope of the metadata template |
|
|
The name of the metadata template |
|
|
N/A |
GET List metadata instances on file
/files/{file_id}/metadata
Retrieves all metadata for a given file.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
N/A |
DELETE Remove metadata instance from file
/files/{file_id}/metadata/{scope}/{template_key}
Deletes a piece of file metadata.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
The scope of the metadata template |
|
|
The name of the metadata template |
|
|
N/A |
PUT Update metadata instance on file
/files/{file_id}/metadata/{scope}/{template_key}
Updates a piece of metadata on a file.
The metadata instance can only be updated if the template has already been
applied to the file before. When editing metadata, only values that match
the metadata template schema will be accepted.
The update is applied atomically. If any errors occur during the
application of the operations, the metadata instance will not be changed.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
The scope of the metadata template |
|
|
The name of the metadata template |
|
|
N/A |
Options (4)
|
Option Name |
Description |
|---|---|
|
|
The type of change to perform on the template. Some
|
|
|
The location in the metadata JSON object
The path must always be prefixed with a / to represent the root
|
|
|
The value to be set or tested. Required for add, replace, and test operations. For add,
For test, the existing value at the path location must match
|
|
|
The location in the metadata JSON object to move or copy a value
|
Metadata instances (Folders) (5)
POST Create metadata instance on folder
/folders/{folder_id}/metadata/{scope}/{template_key}
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent a folder. The ID for any folder can be determined
The root folder of a Box account is
|
|
|
The scope of the metadata template |
|
|
The name of the metadata template |
|
|
N/A |
GET Get metadata instance on folder
/folders/{folder_id}/metadata/{scope}/{template_key}
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent a folder. The ID for any folder can be determined
The root folder of a Box account is
|
|
|
The scope of the metadata template |
|
|
The name of the metadata template |
|
|
N/A |
GET List metadata instances on folder
/folders/{folder_id}/metadata
Retrieves all metadata for a given folder. This can not be used on the root
folder with ID 0.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent a folder. The ID for any folder can be determined
The root folder of a Box account is
|
|
|
N/A |
DELETE Remove metadata instance from folder
/folders/{folder_id}/metadata/{scope}/{template_key}
Deletes a piece of folder metadata.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent a folder. The ID for any folder can be determined
The root folder of a Box account is
|
|
|
The scope of the metadata template |
|
|
The name of the metadata template |
|
|
N/A |
PUT Update metadata instance on folder
/folders/{folder_id}/metadata/{scope}/{template_key}
Updates a piece of metadata on a folder.
The metadata instance can only be updated if the template has already been
applied to the folder before. When editing metadata, only values that match
the metadata template schema will be accepted.
The update is applied atomically. If any errors occur during the
application of the operations, the metadata instance will not be changed.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent a folder. The ID for any folder can be determined
The root folder of a Box account is
|
|
|
The scope of the metadata template |
|
|
The name of the metadata template |
|
|
N/A |
Options (4)
|
Option Name |
Description |
|---|---|
|
|
The type of change to perform on the template. Some
|
|
|
The location in the metadata JSON object
The path must always be prefixed with a / to represent the root
|
|
|
The value to be set or tested. Required for add, replace, and test operations. For add,
For test, the existing value at the path location must match
|
|
|
The location in the metadata JSON object to move or copy a value
|
Metadata templates (8)
POST Create metadata template
/metadata_templates/schema
Creates a new metadata template that can be applied to
files and folders.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (5)
|
Option Name |
Description |
|---|---|
|
|
The scope of the metadata template to create. Applications can
This value needs to be set to enterprise, as global scopes can
|
|
|
A unique identifier for the template. This identifier needs to be
When not provided, the API will create a unique templateKey
|
|
|
The display name of the template. |
|
|
Defines if this template is visible in the Box web app UI, or if
|
|
|
Whether or not to copy any metadata attached to a file or folder
|
GET Find metadata template by instance ID
/metadata_templates
Finds a metadata template by searching for the ID of an instance of the
template.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of an instance of the metadata template to find. |
|
|
N/A |
GET Get metadata template by ID
/metadata_templates/{template_id}
Retrieves a metadata template by its ID.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the template |
|
|
N/A |
GET Get metadata template by name
/metadata_templates/{scope}/{template_key}/schema
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The scope of the metadata template |
|
|
The name of the metadata template |
|
|
N/A |
GET List all global metadata templates
/metadata_templates/global
Used to retrieve all generic, global metadata templates available to all
enterprises using Box.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
Defines the position marker at which to begin returning results. This is
This requires usemarker to be set to true. |
|
|
The maximum number of items to return per page. |
|
|
N/A |
GET List all metadata templates for enterprise
/metadata_templates/enterprise
Used to retrieve all metadata templates created to be used specifically within
the user's enterprise
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
Defines the position marker at which to begin returning results. This is
This requires usemarker to be set to true. |
|
|
The maximum number of items to return per page. |
|
|
N/A |
DELETE Remove metadata template
/metadata_templates/{scope}/{template_key}/schema
Delete a metadata template and its instances.
This deletion is permanent and can not be reversed.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The scope of the metadata template |
|
|
The name of the metadata template |
|
|
N/A |
PUT Update metadata template
/metadata_templates/{scope}/{template_key}/schema
Updates a metadata template.
The metadata template can only be updated if the template
already exists.
The update is applied atomically. If any errors occur during the
application of the operations, the metadata template will not be changed.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The scope of the metadata template |
|
|
The name of the metadata template |
|
|
N/A |
Options (7)
|
Option Name |
Description |
|---|---|
|
|
The type of change to perform on the template. Some
|
|
|
For operations that affect a single field this defines the key of
|
|
|
For operations that affect multiple fields this defines the keys
|
|
|
For operations that affect a single enum option this defines
|
|
|
For operations that affect multiple enum options this defines
|
|
|
For operations that affect a single multi select option this
|
|
|
For operations that affect multiple multi select options this
|
Recent items
GET List recently accessed items
/recent_items
Returns information about the recent items accessed
by a user, either in the last 90 days or up to the last
1000 items accessed.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
The maximum number of items to return per page. |
|
|
Defines the position marker at which to begin returning results. This is
This requires usemarker to be set to true. |
|
|
N/A |
Retention policies (5)
POST Create retention policy
/retention_policies
Creates a retention policy.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (7)
|
Option Name |
Description |
|---|---|
|
|
The name for the retention policy |
|
|
The additional text description of the retention policy. |
|
|
The type of the retention policy. A retention
|
|
|
The disposition action of the retention policy.
|
|
|
Specifies the retention type: modifiable: You can modify the retention policy. For example,
non_modifiable: You can modify the retention policy
|
|
|
Whether the owner of a file will be allowed to
|
|
|
Whether owner and co-owners of a file are notified
|
DELETE Delete retention policy
/retention_policies/{retention_policy_id}
Permanently deletes a retention policy.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the retention policy. |
|
|
N/A |
GET Get retention policy
/retention_policies/{retention_policy_id}
Retrieves a retention policy.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the retention policy. |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
GET List retention policies
/retention_policies
Retrieves all of the retention policies for an enterprise.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
Filters results by a case sensitive prefix of the name of
|
|
|
Filters results by the type of retention policy. |
|
|
Filters results by the ID of the user who created policy. |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
The maximum number of items to return per page. |
|
|
Defines the position marker at which to begin returning results. This is
|
|
|
N/A |
PUT Update retention policy
/retention_policies/{retention_policy_id}
Updates a retention policy.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the retention policy. |
|
|
N/A |
Options (6)
|
Option Name |
Description |
|---|---|
|
|
The name for the retention policy |
|
|
The additional text description of the retention policy. |
|
|
Specifies the retention type: modifiable: You can modify the retention policy. For example,
When updating a retention policy, you can use
|
|
|
Used to retire a retention policy. If not retiring a policy, do not include this parameter
|
|
|
Determines if the owner of items under the policy
|
|
|
Determines if owners and co-owners of items
|
Retention policy assignments (6)
POST Assign retention policy
/retention_policy_assignments
Assigns a retention policy to an item.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (2)
|
Option Name |
Description |
|---|---|
|
|
The ID of the retention policy to assign |
|
|
The date the retention policy assignment begins. If the assigned_to type is metadata_template,
|
GET Get file versions under retention
/retention_policy_assignments/{retention_policy_assignment_id}/file_versions_under_retention
Returns a list of file versions under retention for a retention policy
assignment.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the retention policy assignment. |
|
|
Defines the position marker at which to begin returning results. This is
This requires usemarker to be set to true. |
|
|
The maximum number of items to return per page. |
|
|
N/A |
GET Get files under retention
/retention_policy_assignments/{retention_policy_assignment_id}/files_under_retention
Returns a list of files under retention for a retention policy assignment.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the retention policy assignment. |
|
|
Defines the position marker at which to begin returning results. This is
This requires usemarker to be set to true. |
|
|
The maximum number of items to return per page. |
|
|
N/A |
GET Get retention policy assignment
/retention_policy_assignments/{retention_policy_assignment_id}
Retrieves a retention policy assignment
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the retention policy assignment. |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
GET List retention policy assignments
/retention_policies/{retention_policy_id}/assignments
Returns a list of all retention policy assignments associated with a specified
retention policy.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the retention policy. |
|
|
The type of the retention policy assignment to retrieve. |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
Defines the position marker at which to begin returning results. This is
|
|
|
The maximum number of items to return per page. |
|
|
N/A |
DELETE Remove retention policy assignment
/retention_policy_assignments/{retention_policy_assignment_id}
Removes a retention policy assignment
applied to content.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the retention policy assignment. |
|
|
N/A |
Search (2)
POST Query files/folders by metadata
/metadata_queries/execute_read
Create a search using SQL-like syntax to return items that match specific
metadata.
By default, this endpoint returns only the most basic info about the items for
which the query matches. To get additional fields for each item, including any
of the metadata, use the fields attribute in the query.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (6)
|
Option Name |
Description |
|---|---|
|
|
Specifies the template used in the query. Must be in the form
|
|
|
The query to perform. A query is a logical expression that is very similar
For example, a value of :amount would represent the amount value in
|
|
|
The ID of the folder that you are restricting the query to. A
|
|
|
A value between 0 and 100 that indicates the maximum number of results
|
|
|
Marker to use for requesting the next page. |
|
|
By default, this endpoint returns only the most basic info about the items for
This attribute takes a list of item fields, metadata template identifiers,
For example: created_by will add the details of the user who created the item to
of the metadata instance identified by the scope and templateKey plus
|
GET Search for content
/search
Searches for files, folders, web links, and shared files across the
users content or across the entire enterprise.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The string to search for. This query is matched against item names,
This parameter supports a variety of operators to further refine
"" - by wrapping a query in double quotes only exact matches are
We do not support lower case (that is,
This field is required unless the mdfilters parameter is defined. |
|
|
Limits the search results to either the files that the user has
The scope defaults to user_content, which limits the search
The enterprise_content can be requested by an admin through our
|
|
|
Limits the search results to any files that match any of the provided
|
|
|
Limits the search results to any items created within
Date ranges are defined as comma separated RFC3339
If the the start date is omitted (,2014-05-17T13:35:01-07:00)
If the end date is omitted (2014-05-15T13:35:01-07:00,) the
|
|
|
Limits the search results to any items updated within
Date ranges are defined as comma separated RFC3339
If the start date is omitted (,2014-05-17T13:35:01-07:00)
If the end date is omitted (2014-05-15T13:35:01-07:00,) the
|
|
|
Limits the search results to any items with a size within
Size ranges are defined as comma separated list of a lower
The upper and lower bound can be omitted to create open ranges. |
|
|
Limits the search results to any items that are owned
The items still need to be owned or shared with
To search across an entire enterprise, we recommend using the
|
|
|
Limits the search results to any items that have been updated
The items still need to be owned or shared with
This feature only searches back to the last 10 versions of an item. |
|
|
Limits the search results to items within the given
Search results will also include items within any subfolders
The folders still need to be owned or shared with
To search across an entire enterprise, we recommend using the
|
|
|
Limits the search results to any items that match the search query
Content types are defined as a comma separated lists
name - The name of the item, as defined by its name field.
tags field. |
|
|
Limits the search results to any items of this type. This
file - Limits the search results to files
as bookmarks |
|
|
Determines if the search should look in the trash for items. By default, this API only returns search results for items
trashed_only - Only searches for items currently in the trash
|
|
|
Limits the search results to any items for which the metadata matches the provided filter.
|
|
|
Defines the order in which search results are returned. This API
relevance (default) returns the results sorted by relevance to the
|
|
|
Defines the direction in which search results are ordered. This API
When results are sorted by relevance the ordering is locked to returning
|
|
|
Defines the maximum number of items to return as part of a page of
|
|
|
Defines whether the search results should include any items
When this parameter has been set to true,
|
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
The offset of the item at which to begin the response. Queries with offset parameter value
|
|
|
Limits the search results to items that were deleted by the given
The trash_content parameter needs to be set to trashed_only. If searching in trash is not performed, an empty result set
If the user does not have access to any files owned by
Data available from 2023-02-01 onwards. |
|
|
Limits the search results to any items deleted within a given
Date ranges are defined as comma separated RFC3339 timestamps. If the the start date is omitted (2014-05-17T13:35:01-07:00),
If the end date is omitted (2014-05-15T13:35:01-07:00),
The trash_content parameter needs to be set to trashed_only. If searching in trash is not performed, then an empty result
Data available from 2023-02-01 onwards. |
|
|
N/A |
Session termination (2)
POST Create jobs to terminate user group session
/groups/terminate_sessions
Validates the roles and permissions of the group,
and creates asynchronous jobs
to terminate the group's sessions.
Returns the status for the POST request.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
A list of group IDs |
POST Create jobs to terminate users session
/users/terminate_sessions
Validates the roles and permissions of the user,
and creates asynchronous jobs
to terminate the user's sessions.
Returns the status for the POST request.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (2)
|
Option Name |
Description |
|---|---|
|
|
A list of user IDs |
|
|
A list of user logins |
Shared links (Files) (5)
PUT Add shared link to file
/files/{file_id}#add_shared_link
Adds a shared link to a file.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
Explicitly request the shared_link fields
|
|
|
N/A |
GET Find file for shared link
/shared_items
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
Ensures an item is only returned if it has changed. Pass in the item's last observed etag value
|
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
A header containing the shared link and optional password for the
The format for this header is as follows. shared_link=[link]&shared_link_password=[password] |
|
|
N/A |
GET Get shared link for file
/files/{file_id}#get_shared_link
Gets the information for a shared link on a file.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
Explicitly request the shared_link fields
|
|
|
N/A |
PUT Remove shared link from file
/files/{file_id}#remove_shared_link
Removes a shared link from a file.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
Explicitly request the shared_link fields
|
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
By setting this value to null, the shared link
|
PUT Update shared link on file
/files/{file_id}#update_shared_link
Updates a shared link on a file.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
Explicitly request the shared_link fields
|
|
|
N/A |
Shared links (Folders) (5)
PUT Add shared link to folder
/folders/{folder_id}#add_shared_link
Adds a shared link to a folder.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent a folder. The ID for any folder can be determined
The root folder of a Box account is
|
|
|
Explicitly request the shared_link fields
|
|
|
N/A |
GET Find folder for shared link
/shared_items#folders
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
Ensures an item is only returned if it has changed. Pass in the item's last observed etag value
|
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
A header containing the shared link and optional password for the
The format for this header is as follows. shared_link=[link]&shared_link_password=[password] |
|
|
N/A |
GET Get shared link for folder
/folders/{folder_id}#get_shared_link
Gets the information for a shared link on a folder.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent a folder. The ID for any folder can be determined
The root folder of a Box account is
|
|
|
Explicitly request the shared_link fields
|
|
|
N/A |
PUT Remove shared link from folder
/folders/{folder_id}#remove_shared_link
Removes a shared link from a folder.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent a folder. The ID for any folder can be determined
The root folder of a Box account is
|
|
|
Explicitly request the shared_link fields
|
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
By setting this value to null, the shared link
|
PUT Update shared link on folder
/folders/{folder_id}#update_shared_link
Updates a shared link on a folder.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent a folder. The ID for any folder can be determined
The root folder of a Box account is
|
|
|
Explicitly request the shared_link fields
|
|
|
N/A |
Shared links (Web Links) (5)
PUT Add shared link to web link
/web_links/{web_link_id}#add_shared_link
Adds a shared link to a web link.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the web link. |
|
|
Explicitly request the shared_link fields
|
|
|
N/A |
GET Find web link for shared link
/shared_items#web_links
Returns the web link represented by a shared link.
A shared web link 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 web link when only given a shared link.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
Ensures an item is only returned if it has changed. Pass in the item's last observed etag value
|
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
A header containing the shared link and optional password for the
The format for this header is as follows. shared_link=[link]&shared_link_password=[password] |
|
|
N/A |
GET Get shared link for web link
/web_links/{web_link_id}#get_shared_link
Gets the information for a shared link on a web link.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the web link. |
|
|
Explicitly request the shared_link fields
|
|
|
N/A |
PUT Remove shared link from web link
/web_links/{web_link_id}#remove_shared_link
Removes a shared link from a web link.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the web link. |
|
|
Explicitly request the shared_link fields
|
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
By setting this value to null, the shared link
|
PUT Update shared link on web link
/web_links/{web_link_id}#update_shared_link
Updates a shared link on a web link.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the web link. |
|
|
Explicitly request the shared_link fields
|
|
|
N/A |
Shield information barrier reports (3)
POST Create shield information barrier report
/shield_information_barrier_reports
Creates a shield information barrier report for a given barrier.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
GET Get shield information barrier report by ID
/shield_information_barrier_reports/{shield_information_barrier_report_id}
Retrieves a shield information barrier report by its ID.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the shield information barrier Report. |
|
|
N/A |
GET List shield information barrier reports
/shield_information_barrier_reports
Lists shield information barrier reports.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the shield information barrier. |
|
|
Defines the position marker at which to begin returning results. This is
This requires usemarker to be set to true. |
|
|
The maximum number of items to return per page. |
|
|
N/A |
Shield information barrier segment members (4)
POST Create shield information barrier segment member
/shield_information_barrier_segment_members
Creates a new shield information barrier segment member.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
-| A type of the shield barrier segment member. |
DELETE Delete shield information barrier segment member by ID
/shield_information_barrier_segment_members/{shield_information_barrier_segment_member_id}
Deletes a shield information barrier
segment member based on provided ID.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the shield information barrier segment Member. |
|
|
N/A |
GET Get shield information barrier segment member by ID
/shield_information_barrier_segment_members/{shield_information_barrier_segment_member_id}
Retrieves a shield information barrier
segment member by its ID.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the shield information barrier segment Member. |
|
|
N/A |
GET List shield information barrier segment members
/shield_information_barrier_segment_members
Lists shield information barrier segment members
based on provided segment IDs.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the shield information barrier segment. |
|
|
Defines the position marker at which to begin returning results. This is
This requires usemarker to be set to true. |
|
|
The maximum number of items to return per page. |
|
|
N/A |
Shield information barrier segment restrictions (4)
POST Create shield information barrier segment restriction
/shield_information_barrier_segment_restrictions
Creates a shield information barrier
segment restriction object.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
The type of the shield barrier segment
|
DELETE Delete shield information barrier segment restriction by ID
/shield_information_barrier_segment_restrictions/{shield_information_barrier_segment_restriction_id}
Delete shield information barrier segment restriction
based on provided ID.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the shield information barrier segment Restriction. |
|
|
N/A |
GET Get shield information barrier segment restriction by ID
/shield_information_barrier_segment_restrictions/{shield_information_barrier_segment_restriction_id}
Retrieves a shield information barrier segment
restriction based on provided ID.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the shield information barrier segment Restriction. |
|
|
N/A |
GET List shield information barrier segment restrictions
/shield_information_barrier_segment_restrictions
Lists shield information barrier segment restrictions
based on provided segment ID.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the shield information barrier segment. |
|
|
Defines the position marker at which to begin returning results. This is
This requires usemarker to be set to true. |
|
|
The maximum number of items to return per page. |
|
|
N/A |
Shield information barrier segments (5)
POST Create shield information barrier segment
/shield_information_barrier_segments
Creates a shield information barrier segment.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (2)
|
Option Name |
Description |
|---|---|
|
|
Name of the shield information barrier segment |
|
|
Description of the shield information barrier segment |
DELETE Delete shield information barrier segment
/shield_information_barrier_segments/{shield_information_barrier_segment_id}
Deletes the shield information barrier segment
based on provided ID.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the shield information barrier segment. |
|
|
N/A |
GET Get shield information barrier segment with specified ID
/shield_information_barrier_segments/{shield_information_barrier_segment_id}
Retrieves shield information barrier segment based on provided ID..
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the shield information barrier segment. |
|
|
N/A |
GET List shield information barrier segments
/shield_information_barrier_segments
Retrieves a list of shield information barrier segment objects
for the specified Information Barrier ID.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the shield information barrier. |
|
|
Defines the position marker at which to begin returning results. This is
This requires usemarker to be set to true. |
|
|
The maximum number of items to return per page. |
|
|
N/A |
PUT Update shield information barrier segment with specified ID
/shield_information_barrier_segments/{shield_information_barrier_segment_id}
Updates the shield information barrier segment based on provided ID..
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the shield information barrier segment. |
|
|
N/A |
Options (2)
|
Option Name |
Description |
|---|---|
|
|
The updated name for the shield information barrier segment. |
|
|
The updated description for
|
Shield information barriers (4)
POST Add changed status of shield information barrier with specified ID
/shield_information_barriers/change_status
Change status of shield information barrier with the specified ID.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (2)
|
Option Name |
Description |
|---|---|
|
|
The ID of the shield information barrier. |
|
|
The desired status for the shield information barrier. |
POST Create shield information barrier
/shield_information_barriers
Creates a shield information barrier to
separate individuals/groups within the same
firm and prevents confidential information passing between them.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
GET Get shield information barrier with specified ID
/shield_information_barriers/{shield_information_barrier_id}
Get shield information barrier based on provided ID.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the shield information barrier. |
|
|
N/A |
GET List shield information barriers
/shield_information_barriers
Retrieves a list of shield information barrier objects
for the enterprise of JWT.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
Defines the position marker at which to begin returning results. This is
|
|
|
The maximum number of items to return per page. |
|
|
N/A |
Sign requests (5)
POST Cancel Box Sign request
/sign_requests/{sign_request_id}/cancel
Cancels a sign request.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the signature request |
|
|
N/A |
POST Create Box Sign request
/sign_requests
Creates a signature request. This involves preparing a document for signing and
sending the signature request to signers.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (14)
|
Option Name |
Description |
|---|---|
|
|
Indicates if the sender should receive a prepare_url in the response to complete document preparation using the UI. |
|
|
When specified, the signature request will be redirected to this url when a document is signed. |
|
|
The uri that a signer will be redirected to after declining to sign a document. |
|
|
Disables the usage of signatures generated by typing (text). |
|
|
Subject of sign request email. This is cleaned by sign request. If this field is not passed, a default subject will be used. |
|
|
Message to include in sign request email. The field is cleaned through sanitization of specific characters. However, some html tags are allowed. Links included in the message are also converted to hyperlinks in the email. The message may contain the following html tags including a, abbr, acronym, b, blockquote, code, em, i, ul, li, ol, and strong. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. If this field is not passed, a default message will be used. |
|
|
Reminds signers to sign a document on day 3, 8, 13 and 18. Reminders are only sent to outstanding signers. |
|
|
Name of the signature request. |
|
|
Set the number of days after which the created signature request will automatically expire if not completed. By default, we do not apply any expiration date on signature requests, and the signature request does not expire. |
|
|
This can be used to reference an ID in an external system that the sign request is related to. |
|
|
Forces signers to verify a text message prior to viewing the document. You must specify the phone number of signers to have this setting apply to them. |
|
|
When a signature request is created from a template this field will indicate the id of that template. |
|
|
Used as an optional system name to appear in the signature log next to the signers who have been assigned the embed_url_external_id. |
|
|
Force a specific color for the signature (blue, black, or red) |
GET Get Box Sign request by ID
/sign_requests/{sign_request_id}
Gets a sign request by ID.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the signature request |
|
|
N/A |
GET List Box Sign requests
/sign_requests
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
Defines the position marker at which to begin returning results. This is
This requires usemarker to be set to true. |
|
|
The maximum number of items to return per page. |
|
|
N/A |
POST Resend Box Sign request
/sign_requests/{sign_request_id}/resend
Resends a signature request email to all outstanding signers.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the signature request |
|
|
N/A |
Sign templates (2)
GET Get Box Sign template by ID
/sign_templates/{template_id}
Fetches details of a specific Box Sign template.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of a Box Sign template. |
|
|
N/A |
GET List Box Sign templates
/sign_templates
Gets Box Sign templates created by a user.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
Defines the position marker at which to begin returning results. This is
This requires usemarker to be set to true. |
|
|
The maximum number of items to return per page. |
|
|
N/A |
Skills (5)
POST Create Box Skill cards on file
/files/{file_id}/metadata/global/boxSkillsCards
Applies one or more Box Skills metadata cards to a file.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
A list of Box Skill cards to apply to this file. |
GET List Box Skill cards on file
/files/{file_id}/metadata/global/boxSkillsCards
List the Box Skills metadata cards that are attached to a file.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
N/A |
DELETE Remove Box Skill cards from file
/files/{file_id}/metadata/global/boxSkillsCards
Removes any Box Skills cards metadata from a file.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
N/A |
PUT Update Box Skill cards on file
/files/{file_id}/metadata/global/boxSkillsCards
Updates one or more Box Skills metadata cards to a file.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
N/A |
Options (3)
|
Option Name |
Description |
|---|---|
|
|
replace |
|
|
The JSON Path that represents the card to replace. In most cases
|
|
|
N/A |
PUT Update all Box Skill cards on file
/skill_invocations/{skill_id}
An alternative method that can be used to overwrite and update all Box Skill
metadata cards on a file.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the skill to apply this metadata for. |
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
Defines the status of this invocation. Set this to success when setting Skill cards. |
Standard and Zones Storage Policies (2)
GET Get storage policy
/storage_policies/{storage_policy_id}
Fetches a specific storage policy.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the storage policy. |
|
|
N/A |
GET List storage policies
/storage_policies
Fetches all the storage policies in the enterprise.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
Defines the position marker at which to begin returning results. This is
This requires usemarker to be set to true. |
|
|
The maximum number of items to return per page. |
|
|
N/A |
Standard and Zones Storage Policy Assignments (5)
POST Assign storage policy
/storage_policy_assignments
Creates a storage policy assignment for an enterprise or user.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
GET Get storage policy assignment
/storage_policy_assignments/{storage_policy_assignment_id}
Fetches a specific storage policy assignment.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the storage policy assignment. |
|
|
N/A |
GET List storage policy assignments
/storage_policy_assignments
Fetches all the storage policy assignment for an enterprise or user.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
Defines the position marker at which to begin returning results. This is
This requires usemarker to be set to true. |
|
|
The target type to return assignments for |
|
|
The ID of the user or enterprise to return assignments for |
|
|
N/A |
DELETE Unassign storage policy
/storage_policy_assignments/{storage_policy_assignment_id}
Delete a storage policy assignment.
Deleting a storage policy assignment on a user
will have the user inherit the enterprise's default
storage policy.
There is a rate limit for calling this endpoint of only
twice per user in a 24 hour time frame.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the storage policy assignment. |
|
|
N/A |
PUT Update storage policy assignment
/storage_policy_assignments/{storage_policy_assignment_id}
Updates a specific storage policy assignment.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the storage policy assignment. |
|
|
N/A |
Task assignments (5)
POST Assign task
/task_assignments
Assigns a task to a user.
A task can be assigned to more than one user by creating multiple
assignments.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
GET Get task assignment
/task_assignments/{task_assignment_id}
Retrieves information about a task assignment.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the task assignment. |
|
|
N/A |
GET List task assignments
/tasks/{task_id}/assignments
Lists all of the assignments for a given task.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the task. |
|
|
N/A |
DELETE Unassign task
/task_assignments/{task_assignment_id}
Deletes a specific task assignment.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the task assignment. |
|
|
N/A |
PUT Update task assignment
/task_assignments/{task_assignment_id}
Updates a task assignment. This endpoint can be
used to update the state of a task assigned to a user.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the task assignment. |
|
|
N/A |
Options (2)
|
Option Name |
Description |
|---|---|
|
|
An optional message by the assignee that can be added to the task. |
|
|
The state of the task assigned to the user. For a task with an action value of complete this can be
|
Tasks (5)
POST Create task
/tasks
Creates a single task on a file. This task is not assigned to any user and
will need to be assigned separately.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (4)
|
Option Name |
Description |
|---|---|
|
|
The action the task assignee will be prompted to do. Must be review defines an approval task that can be approved or
|
|
|
An optional message to include with the task. |
|
|
Defines when the task is due. Defaults to null if not
|
|
|
Defines which assignees need to complete this task before the task
all_assignees (default) requires all assignees to review or
|
GET Get task
/tasks/{task_id}
Retrieves information about a specific task.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the task. |
|
|
N/A |
GET List tasks on file
/files/{file_id}/tasks
Retrieves a list of all the tasks for a file. This
endpoint does not support pagination.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
N/A |
DELETE Remove task
/tasks/{task_id}
Removes a task from a file.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the task. |
|
|
N/A |
PUT Update task
/tasks/{task_id}
Updates a task. This can be used to update a task's configuration, or to
update its completion state.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the task. |
|
|
N/A |
Options (4)
|
Option Name |
Description |
|---|---|
|
|
The action the task assignee will be prompted to do. Must be review defines an approval task that can be approved or
|
|
|
The message included with the task. |
|
|
When the task is due at. |
|
|
Defines which assignees need to complete this task before the task
all_assignees (default) requires all assignees to review or
|
Terms of service user statuses (3)
POST Create terms of service status for new user
/terms_of_service_user_statuses
Sets the status for a terms of service for a user.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
Whether the user has accepted the terms. |
GET List terms of service user statuses
/terms_of_service_user_statuses
Retrieves an overview of users and their status for a
terms of service, including Whether they have accepted
the terms and when.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the terms of service. |
|
|
Limits results to the given user ID. |
|
|
N/A |
PUT Update terms of service status for existing user
/terms_of_service_user_statuses/{terms_of_service_user_status_id}
Updates the status for a terms of service for a user.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the terms of service status. |
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
Whether the user has accepted the terms. |
Terms of service (4)
POST Create terms of service
/terms_of_services
Creates a terms of service for a given enterprise
and type of user.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (3)
|
Option Name |
Description |
|---|---|
|
|
Whether this terms of service is active. |
|
|
The type of user to set the terms of
|
|
|
The terms of service text to display to users. The text can be set to empty if the status is set to disabled. |
GET Get terms of service
/terms_of_services/{terms_of_service_id}
Fetches a specific terms of service.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the terms of service. |
|
|
N/A |
GET List terms of services
/terms_of_services
Returns the current terms of service text and settings
for the enterprise.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
Limits the results to the terms of service of the given type. |
|
|
N/A |
PUT Update terms of service
/terms_of_services/{terms_of_service_id}
Updates a specific terms of service.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the terms of service. |
|
|
N/A |
Options (2)
|
Option Name |
Description |
|---|---|
|
|
Whether this terms of service is active. |
|
|
The terms of service text to display to users. The text can be set to empty if the status is set to disabled. |
Transfer folders
PUT Transfer owned folders
/users/{user_id}/folders/0
Move all of the items (files, folders and workflows) owned by a user into
another user's account
Only the root folder (0) can be transferred.
Folders can only be moved across users by users with administrative
permissions.
All existing shared links and folder-level collaborations are transferred
during the operation. Please note that while collaborations at the individual
file-level are transferred during the operation, the collaborations are
deleted when the original user is deleted.
This call will be performed synchronously which might lead to a slow response
when the source user has a large number of items in all of its folders.
If the destination path has a metadata cascade policy attached to any of
the parent folders, a metadata cascade operation will be kicked off
asynchronously.
There is currently no way to check for when this operation is finished.
The destination folder's name will be in the format `{User}'s Files and
Folders, where {User}` is the display name of the user.
To make this API call your application will need to have the "Read and write
all files and folders stored in Box" scope enabled.
Please make sure the destination user has access to Relay or Relay Lite,
and has access to the files and folders involved in the workflows being
transferred.
Admins will receive an email when the operation is completed.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the user. |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
Determines if users should receive email notification
|
|
|
N/A |
Trashed files (3)
GET Get trashed file
/files/{file_id}/trash
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
DELETE Permanently remove file
/files/{file_id}/trash
Permanently deletes a file that is in the trash.
This action cannot be undone.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
N/A |
POST Restore file
/files/{file_id}
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
An optional new name for the file. |
Trashed folders (3)
GET Get trashed folder
/folders/{folder_id}/trash
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent a folder. The ID for any folder can be determined
The root folder of a Box account is
|
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
DELETE Permanently remove folder
/folders/{folder_id}/trash
Permanently deletes a folder that is in the trash.
This action cannot be undone.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent a folder. The ID for any folder can be determined
The root folder of a Box account is
|
|
|
N/A |
POST Restore folder
/folders/{folder_id}
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent a folder. The ID for any folder can be determined
The root folder of a Box account is
|
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
An optional new name for the folder. |
Trashed items
GET List trashed items
/folders/trash/items
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
The maximum number of items to return per page. |
|
|
The offset of the item at which to begin the response. Queries with offset parameter value
|
|
|
Specifies whether to use marker-based pagination instead of
By setting this value to true, the API will return a marker field
|
|
|
Defines the position marker at which to begin returning results. This is
This requires usemarker to be set to true. |
|
|
The direction to sort results in. This can be either in alphabetical ascending
|
|
|
Defines the second attribute by which items
Items are always sorted by their type first, with
This parameter is not supported when using marker-based pagination. |
|
|
N/A |
Trashed web links (3)
GET Get trashed web link
/web_links/{web_link_id}/trash
Retrieves a web link that has been moved to the trash.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the web link. |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
DELETE Permanently remove web link
/web_links/{web_link_id}/trash
Permanently deletes a web link that is in the trash.
This action cannot be undone.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the web link. |
|
|
N/A |
POST Restore web link
/web_links/{web_link_id}
Restores a web link that has been moved to the trash.
An optional new parent ID can be provided to restore the web link to in case
the original folder has been deleted.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the web link. |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
An optional new name for the web link. |
Uploads (Chunked) (7)
POST Commit upload session
/files/upload_sessions/{upload_session_id}/commit
Close an upload session and create a file from the uploaded chunks.
The actual endpoint URL is returned by the Create upload session
and Get upload session endpoints.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the upload session. |
|
|
The [RFC3230][1] message digest of the whole file. Only SHA1 is supported. The SHA1 digest must be Base64
[1]: https://tools.ietf.org/html/rfc3230 |
|
|
Ensures this item hasn't recently changed before
Pass in the item's last observed etag value
|
|
|
Ensures an item is only returned if it has changed. Pass in the item's last observed etag value
|
|
|
N/A |
POST Create upload session
/files/upload_sessions
Creates an upload session for a new file.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (3)
|
Option Name |
Description |
|---|---|
|
|
The ID of the folder to upload the new file to. |
|
|
The total number of bytes of the file to be uploaded |
|
|
The name of new file |
POST Create upload session for existing file
/files/{file_id}/upload_sessions
Creates an upload session for an existing file.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
N/A |
Options (2)
|
Option Name |
Description |
|---|---|
|
|
The total number of bytes of the file to be uploaded |
|
|
The optional new name of new file |
GET Get upload session
/files/upload_sessions/{upload_session_id}
Return information about an upload session.
The actual endpoint URL is returned by the Create upload session endpoint.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the upload session. |
|
|
N/A |
GET List parts
/files/upload_sessions/{upload_session_id}/parts
Return a list of the chunks uploaded to the upload session so far.
The actual endpoint URL is returned by the Create upload session
and Get upload session endpoints.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the upload session. |
|
|
The offset of the item at which to begin the response. Queries with offset parameter value
|
|
|
The maximum number of items to return per page. |
|
|
N/A |
DELETE Remove upload session
/files/upload_sessions/{upload_session_id}
Abort an upload session and discard all data uploaded.
This cannot be reversed.
The actual endpoint URL is returned by the Create upload session
and Get upload session endpoints.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the upload session. |
|
|
N/A |
PUT Upload part of file
/files/upload_sessions/{upload_session_id}
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the upload session. |
|
|
The [RFC3230][1] message digest of the chunk uploaded. Only SHA1 is supported. The SHA1 digest must be base64
To get the value for the SHA digest, use the
[1]: https://tools.ietf.org/html/rfc3230 |
|
|
The byte range of the chunk. Must not overlap with the range of a part already
When providing the value for content-range, remember that: The lower bound of each part's byte range
|
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
N/A |
Uploads (2)
POST Upload file
/files/content
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
An optional header containing the SHA1 hash of the file to
|
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
The content of the file to upload to Box. The attributes part of the body must come before the
|
POST Upload file version
/files/{file_id}/content
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
Ensures this item hasn't recently changed before
Pass in the item's last observed etag value
|
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
An optional header containing the SHA1 hash of the file to
|
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
The content of the file to upload to Box. The attributes part of the body must come before the
|
User avatars (3)
POST Add or update user avatar
/users/{user_id}/avatar
Adds or updates a user avatar.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the user. |
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
The image file to be uploaded to Box.
|
DELETE Delete user avatar
/users/{user_id}/avatar
Removes an existing user avatar.
You cannot reverse this operation.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the user. |
|
|
N/A |
GET Get user avatar
/users/{user_id}/avatar
Retrieves an image of a the user's avatar.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the user. |
|
|
N/A |
Users (6)
POST Create user
/users
Creates a new managed user in an enterprise. This endpoint
is only available to users and applications with the right
admin permissions.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
Options (17)
|
Option Name |
Description |
|---|---|
|
|
The name of the user |
|
|
The email address the user uses to log in Required, unless is_platform_access_only
|
|
|
Specifies that the user is an app user. |
|
|
The user’s enterprise role |
|
|
The language of the user, formatted in modified version of the
|
|
|
Whether the user can use Box Sync |
|
|
The user’s job title |
|
|
The user’s phone number |
|
|
The user’s address |
|
|
The user’s total available space in bytes. Set this to -1 to
|
|
|
Whether the user can see other enterprise users in their
|
|
|
The user's timezone |
|
|
Whether the user is allowed to collaborate with users outside
|
|
|
Whether to exempt the user from enterprise device limits |
|
|
Whether the user must use two-factor authentication |
|
|
The user's account status |
|
|
An external identifier for an app user, which can be used to look
|
DELETE Delete user
/users/{user_id}
Deletes a user. By default this will fail if the user
still owns any content. Move their owned content first
before proceeding, or use the force field to delete
the user and their files.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the user. |
|
|
Whether the user will receive email notification of
|
|
|
Whether the user should be deleted even if this user
|
|
|
N/A |
GET Get current user
/users/me
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
GET Get user
/users/{user_id}
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the user. |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
GET List enterprise users
/users
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
Limits the results to only users who's name or
For externally managed users, the search term needs
|
|
|
Limits the results to the kind of user specified. all returns every kind of user for whom the
login matches the filter_term exactly. |
|
|
Limits the results to app users with the given
When creating an app user, an
|
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
The offset of the item at which to begin the response. Queries with offset parameter value
|
|
|
The maximum number of items to return per page. |
|
|
Specifies whether to use marker-based pagination instead of
By setting this value to true, the API will return a marker field
|
|
|
Defines the position marker at which to begin returning results. This is
This requires usemarker to be set to true. |
|
|
N/A |
PUT Update user
/users/{user_id}
Updates a managed or app user in an enterprise. This endpoint
is only available to users and applications with the right
admin permissions.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the user. |
|
|
A comma-separated list of attributes to include in the
Be aware that specifying this parameter will have the
|
|
|
N/A |
Options (19)
|
Option Name |
Description |
|---|---|
|
|
Set this to null to roll the user out of the enterprise
|
|
|
Whether the user should receive an email when they
|
|
|
The name of the user |
|
|
The email address the user uses to log in Note: If the target user's email is not confirmed, then the
|
|
|
The user’s enterprise role |
|
|
The language of the user, formatted in modified version of the
|
|
|
Whether the user can use Box Sync |
|
|
The user’s job title |
|
|
The user’s phone number |
|
|
The user’s address |
|
|
Whether the user can see other enterprise users in their
|
|
|
The user's timezone |
|
|
Whether the user is allowed to collaborate with users outside
|
|
|
Whether to exempt the user from enterprise device limits |
|
|
Whether the user must use two-factor authentication |
|
|
Whether the user is required to reset their password |
|
|
The user's account status |
|
|
The user’s total available space in bytes. Set this to -1 to
|
|
|
An external identifier for an app user, which can be used to look
Note: In order to update this field, you need to request a token
|
Watermarks (Files) (3)
PUT Apply watermark to file
/files/{file_id}/watermark
Applies or update a watermark on a file.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
N/A |
GET Get watermark on file
/files/{file_id}/watermark
Retrieve the watermark for a file.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
N/A |
DELETE Remove watermark from file
/files/{file_id}/watermark
Removes the watermark from a file.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represents a file. The ID for any file can be determined
|
|
|
N/A |
Watermarks (Folders) (3)
PUT Apply watermark to folder
/folders/{folder_id}/watermark
Applies or update a watermark on a folder.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent a folder. The ID for any folder can be determined
The root folder of a Box account is
|
|
|
N/A |
GET Get watermark for folder
/folders/{folder_id}/watermark
Retrieve the watermark for a folder.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent a folder. The ID for any folder can be determined
The root folder of a Box account is
|
|
|
N/A |
DELETE Remove watermark from folder
/folders/{folder_id}/watermark
Removes the watermark from a folder.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent a folder. The ID for any folder can be determined
The root folder of a Box account is
|
|
|
N/A |
Web links (4)
POST Create web link
/web_links
Creates a web link object within a folder.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (3)
|
Option Name |
Description |
|---|---|
|
|
The URL that this web link links to. Must start with
|
|
|
Name of the web link. Defaults to the URL if not set. |
|
|
Description of the web link. |
GET Get web link
/web_links/{web_link_id}
Retrieve information about a web link.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the web link. |
|
|
The URL, and optional password, for the shared link of this item. This header can be used to access items that have not been
Use the format shared_link=[link] or if a password is required then
This header can be used on the file or folder shared, as well as on any files
|
|
|
N/A |
DELETE Remove web link
/web_links/{web_link_id}
Deletes a web link.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the web link. |
|
|
N/A |
PUT Update web link
/web_links/{web_link_id}
Updates a web link object.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the web link. |
|
|
N/A |
Options (3)
|
Option Name |
Description |
|---|---|
|
|
The new URL that the web link links to. Must start with
|
|
|
A new name for the web link. Defaults to the URL if not set. |
|
|
A new description of the web link. |
Webhooks (5)
POST Create webhook
/webhooks
Creates a webhook.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (2)
|
Option Name |
Description |
|---|---|
|
|
The URL that is notified by this webhook |
|
|
An array of event names that this webhook is
|
GET Get webhook
/webhooks/{webhook_id}
Retrieves a specific webhook
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the webhook. |
|
|
N/A |
GET List all webhooks
/webhooks
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
Defines the position marker at which to begin returning results. This is
This requires usemarker to be set to true. |
|
|
The maximum number of items to return per page. |
|
|
N/A |
DELETE Remove webhook
/webhooks/{webhook_id}
Deletes a webhook.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the webhook. |
|
|
N/A |
PUT Update webhook
/webhooks/{webhook_id}
Updates a webhook.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the webhook. |
|
|
N/A |
Options (2)
|
Option Name |
Description |
|---|---|
|
|
The URL that is notified by this webhook |
|
|
An array of event names that this webhook is
|
Workflows (2)
GET List workflows
/workflows
Returns list of workflows that act on a given folder ID, and
have a flow with a trigger type of WORKFLOW_MANUAL_START.
You application must be authorized to use the Manage Box Relay application
scope within the developer console in to use this endpoint.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent a folder. The ID for any folder can be determined
The root folder of a Box account is
|
|
|
Type of trigger to search for. |
|
|
The maximum number of items to return per page. |
|
|
Defines the position marker at which to begin returning results. This is
This requires usemarker to be set to true. |
|
|
N/A |
POST Starts workflow based on request body
/workflows/{workflow_id}/start
Initiates a flow with a trigger type of WORKFLOW_MANUAL_START.
You application must be authorized to use the Manage Box Relay application
scope within the developer console.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID of the workflow. |
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
The type of the parameters object |
Zip Downloads (3)
POST Create zip download
/zip_downloads
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.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
The optional name of the zip archive. This name will be appended by the
|
GET Download zip archive
/zip_downloads/{zip_download_id}/content
Returns the contents of a zip archive in binary format. This URL does not
require any form of authentication and could be used in a user's browser to
download the archive to a user's device.
By default, this URL is only valid for a few seconds from the creation of
the request for this archive. Once a download has started it can not be
stopped and resumed, instead a new request for a zip archive would need to
be created.
The URL of this endpoint should not be considered as fixed. Instead, use
the Create zip download API to request to create a
zip archive, and then follow the download_url field in the response to
this endpoint.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent this zip archive. |
|
|
N/A |
GET Get zip download status
/zip_downloads/{zip_download_id}/status
Returns the download status of a zip archive, allowing an application to
inspect the progress of the download as well as the number of items that
might have been skipped.
This endpoint can only be accessed once the download has started.
Subsequently this endpoint is valid for 12 hours from the start of the
download.
The URL of this endpoint should not be considered as fixed. Instead, use
the Create zip download API to request to create a
zip archive, and then follow the status_url field in the response to
this endpoint.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The unique identifier that represent this zip archive. |
|
|
N/A |