Module box
API
Definitions
![](https://bcentral-packageicons.azureedge.net/images/ballerinax_box_1.1.0.png)
ballerinax/box Ballerina library
Overview
This is a generated connector for Box Platform API v2.0.0 OpenAPI specification.
Box Platform provides functionality to provide access to content stored within Box. It provides endpoints for basic manipulation of files and folders, management of users within an enterprise, as well as more complex topics such as legal holds and retention policies.
Prerequisites
Before using this connector in your Ballerina application, complete the following:
- Create Box Platform Account by selecting the pricing plan
- Obtaining tokens
- Go to Box Platform Account and log into the account
- Navigate to developer console, create new app and get needed credentials
- Create and obtain bearer token credentials and store somewhere securely
Quickstart
Step 1: Import connector
Import the ballerinax/box module into the Ballerina project.
import ballerinax/box;
Step 2: Create a new connector instance
configurable http:BearerTokenConfig & readonly auth = ?; box:ClientConfig clientConfig = { auth : auth }; box:Client baseClient = check new Client(clientConfig, serviceUrl = "https://api.box.com/2.0");
Step 3: Invoke connector operation
- You can get a existing file by using
getFilesId
method.box:File file = check baseClient->getFilesId("833080141230", "bal");
- Use
bal run
command to compile and run the Ballerina program.
Clients![](/images/permalink.svg)
box: Client![](/images/permalink.svg)
This is a generated connector for Box Platform API v2.0.0 OpenAPI specification. Box Platform provides functionality to provide access to content stored within Box. It provides endpoints for basic manipulation of files and folders, management of users within an enterprise, as well as more complex topics such as legal holds and retention policies.
Constructor![](/images/permalink.svg)
Gets invoked to initialize the connector
.
The connector initialization requires setting the API credentials.
Create a Box Developer Account and obtain tokens following this guide.
init (ClientConfig clientConfig, string serviceUrl)
- clientConfig ClientConfig - The configurations to be used when initializing the
connector
- serviceUrl string "https://api.box.com/2.0" - URL of the target service
getAuthorize![](/images/permalink.svg)
function getAuthorize(string responseType, string clientId, string? redirectUri, string? state, string? scope) returns string|error
Authorize user
Parameters
- responseType string - The type of response we'd like to receive.
- clientId string - The Client ID of the application that is requesting to authenticate the user. To get the Client ID for your application, log in to your Box developer console and click the Edit Application link for the application you're working with. In the OAuth 2.0 Parameters section of the configuration page, find the item labelled
client_id
. The text of that item is your application's Client ID.
- redirectUri string? (default ()) - The URL to which Box redirects the browser after the user has granted or denied the application permission. This URL must match the redirect URL in the configuration of your application. It must be a valid HTTPS URL and it needs to be able to handle the redirection to complete the next step in the OAuth 2.0 flow.
- state string? (default ()) - A custom string of your choice. Box will pass the same string to the redirect URL when authentication is complete. This parameter can be used to identify a user on redirect, as well as protect against hijacked sessions and other exploits.
- scope string? (default ()) - A comma-separated list of application scopes you'd like to authenticate the user for. This defaults to all the scopes configured for the application in its configuration page.
postOauth2Token![](/images/permalink.svg)
function postOauth2Token(PostOAuth2Token payload) returns AccessToken|error
Request access token
Parameters
- payload PostOAuth2Token -
Return Type
- AccessToken|error - Returns a new Access Token that can be used to make authenticated API calls by passing along the token in a authorization header as follows
Authorization: Bearer <Token>
.
postOauth2TokenRefresh![](/images/permalink.svg)
function postOauth2TokenRefresh(Postoauth2tokenRefreshaccesstoken payload) returns AccessToken|error
Refresh access token
Parameters
- payload Postoauth2tokenRefreshaccesstoken -
Return Type
- AccessToken|error - Returns a new Access Token that can be used to make authenticated API calls by passing along the token in a authorization header as follows
Authorization: Bearer <Token>
.
postOauth2Revoke![](/images/permalink.svg)
function postOauth2Revoke(PostOAuth2Revoke payload) returns Response|error
Revoke access token
Parameters
- payload PostOAuth2Revoke -
getFilesId![](/images/permalink.svg)
function getFilesId(string fileId, string xRepHints, string[]? fields, string? ifNoneMatch, string? boxapi) returns File|error
Get file information
Parameters
- fileId string - The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/files/123
thefile_id
is123
.
- xRepHints string - A header required to request specific
representations
of a file. Use this in combination with thefields
query parameter to request a specific file representation. The general format for these representations isX-Rep-Hints: [...]
where[...]
is one or many hints in the format[fileType?query]
. For example, to request apng
representation in32x32
as well as94x94
pixel dimensions provide the following hints.X-Rep-Hints: [jpg?dimensions=32x32][jpg?dimensions=94x94]
Additionally, atext
representation is available for all document file types in Box using the[extracted_text]
representation.X-Rep-Hints: [extracted_text]
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. Additionally this field can be used to query any metadata applied to the file by specifying the
metadata
field as well as the scope and key of the template to retrieve, for example?field=metadata.enterprise_12345.contractTemplate
.
- ifNoneMatch string? (default ()) - Ensures an item is only returned if it has changed. Pass in the item's last observed
etag
value into this header and the endpoint will fail with a304 Not Modified
if the item has not changed since.
- boxapi string? (default ()) - The URL, and optional password, for the shared link of this item. This header can be used to access items that have not been explicitly shared with a user. Use the format
shared_link=[link]
or if a password is required then useshared_link=[link]&shared_link_password=[password]
. This header can be used on the file or folder shared, as well as on any files or folders nested within the item.
Return Type
putFilesId![](/images/permalink.svg)
function putFilesId(string fileId, FilesFileIdBody payload, string[]? fields, string? ifMatch) returns File|error
Update file
Parameters
- fileId string - The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/files/123
thefile_id
is123
.
- payload FilesFileIdBody -
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
- ifMatch string? (default ()) - Ensures this item hasn't recently changed before making changes. Pass in the item's last observed
etag
value into this header and the endpoint will fail with a412 Precondition Failed
if it has changed since.
Return Type
postFilesId![](/images/permalink.svg)
function postFilesId(string fileId, FilesFileIdBody1 payload, string[]? fields) returns File|error
Restore file
Parameters
- fileId string - The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/files/123
thefile_id
is123
.
- payload FilesFileIdBody1 -
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
deleteFilesId![](/images/permalink.svg)
Delete file
Parameters
- fileId string - The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/files/123
thefile_id
is123
.
- ifMatch string? (default ()) - Ensures this item hasn't recently changed before making changes. Pass in the item's last observed
etag
value into this header and the endpoint will fail with a412 Precondition Failed
if it has changed since.
getFilesIdContent![](/images/permalink.svg)
function getFilesIdContent(string fileId, string? range, string? boxapi, string? 'version, string? accessToken) returns Response|error
Download file
Parameters
- fileId string - The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/files/123
thefile_id
is123
.
- range string? (default ()) - The byte range of the content to download. The format
{start_byte}-{end_byte}
can be used to specify what section of the file to download.
- boxapi string? (default ()) - The URL, and optional password, for the shared link of this item. This header can be used to access items that have not been explicitly shared with a user. Use the format
shared_link=[link]
or if a password is required then useshared_link=[link]&shared_link_password=[password]
. This header can be used on the file or folder shared, as well as on any files or folders nested within the item.
- 'version string? (default ()) - The file version to download
- accessToken string? (default ()) - 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. When using this parameter, please make sure that the access token is sufficiently scoped down to only allow read access to that file and no other files or folders.
Return Type
postFilesIdContent![](/images/permalink.svg)
function postFilesIdContent(string fileId, FileIdContentBody payload, string? ifMatch, string[]? fields, string? contentMd5) returns Files|error
Upload file version
Parameters
- fileId string - The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/files/123
thefile_id
is123
.
- payload FileIdContentBody -
- ifMatch string? (default ()) - Ensures this item hasn't recently changed before making changes. Pass in the item's last observed
etag
value into this header and the endpoint will fail with a412 Precondition Failed
if it has changed since.
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
- contentMd5 string? (default ()) - An optional header containing the SHA1 hash of the file to ensure that the file was not corrupted in transit.
postFilesContent![](/images/permalink.svg)
function postFilesContent(FilesContentBody payload, string[]? fields, string? contentMd5) returns Files|error
Upload file
Parameters
- payload FilesContentBody -
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
- contentMd5 string? (default ()) - An optional header containing the SHA1 hash of the file to ensure that the file was not corrupted in transit.
postFilesUploadSessions![](/images/permalink.svg)
function postFilesUploadSessions(FilesUploadSessionsBody payload) returns UploadSession|error
Create upload session
Parameters
- payload FilesUploadSessionsBody -
Return Type
- UploadSession|error - Returns a new upload session.
postFilesIdUploadSessions![](/images/permalink.svg)
function postFilesIdUploadSessions(string fileId, FileIdUploadSessionsBody payload) returns UploadSession|error
Create upload session for existing file
Parameters
- fileId string - The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/files/123
thefile_id
is123
.
- payload FileIdUploadSessionsBody -
Return Type
- UploadSession|error - Returns a new upload session.
getFilesUploadSessionsId![](/images/permalink.svg)
function getFilesUploadSessionsId(string uploadSessionId) returns UploadSession|error
Get upload session
Parameters
- uploadSessionId string - The ID of the upload session.
Return Type
- UploadSession|error - Returns an upload session object.
putFilesUploadSessionsId![](/images/permalink.svg)
function putFilesUploadSessionsId(string uploadSessionId, string digest, string contentRange, byte[] payload) returns UploadedPart|error
Upload part of file
Parameters
- uploadSessionId string - The ID of the upload session.
- digest string - The [RFC3230][1] message digest of the chunk uploaded. Only SHA1 is supported. The SHA1 digest must be Base64 encoded. The format of this header is as
sha=BASE64_ENCODED_DIGEST
. [1]: https://tools.ietf.org/html/rfc3230
- contentRange string - The byte range of the chunk. Must not overlap with the range of a part already uploaded this session.
- payload byte[] -
Return Type
- UploadedPart|error - Chunk has been uploaded successfully.
deleteFilesUploadSessionsId![](/images/permalink.svg)
Remove upload session
Parameters
- uploadSessionId string - The ID of the upload session.
getFilesUploadSessionsIdParts![](/images/permalink.svg)
function getFilesUploadSessionsIdParts(string uploadSessionId, int offset, int? 'limit) returns UploadParts|error
List parts
Parameters
- uploadSessionId string - The ID of the upload session.
- offset int (default 0) - The offset of the item at which to begin the response.
- 'limit int? (default ()) - The maximum number of items to return per page.
Return Type
- UploadParts|error - Returns a list of parts that have been uploaded.
postFilesUploadSessionsIdCommit![](/images/permalink.svg)
function postFilesUploadSessionsIdCommit(string uploadSessionId, string digest, UploadSessionIdCommitBody payload, string? ifMatch, string? ifNoneMatch) returns Files|error?
Commit upload session
Parameters
- uploadSessionId string - The ID of the upload session.
- digest string - The [RFC3230][1] message digest of the whole file. Only SHA1 is supported. The SHA1 digest must be Base64 encoded. The format of this header is as
sha=BASE64_ENCODED_DIGEST
. [1]: https://tools.ietf.org/html/rfc3230
- payload UploadSessionIdCommitBody -
- ifMatch string? (default ()) - Ensures this item hasn't recently changed before making changes. Pass in the item's last observed
etag
value into this header and the endpoint will fail with a412 Precondition Failed
if it has changed since.
- ifNoneMatch string? (default ()) - Ensures an item is only returned if it has changed. Pass in the item's last observed
etag
value into this header and the endpoint will fail with a304 Not Modified
if the item has not changed since.
postFilesIdCopy![](/images/permalink.svg)
function postFilesIdCopy(string fileId, FileIdCopyBody payload, string[]? fields) returns File|error
Copy file
Parameters
- fileId string - The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/files/123
thefile_id
is123
.
- payload FileIdCopyBody -
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
Return Type
getFilesIdThumbnailId![](/images/permalink.svg)
function getFilesIdThumbnailId(string fileId, string extension, int? minHeight, int? minWidth, int? maxHeight, int? maxWidth) returns string|error?
Get file thumbnail
Parameters
- fileId string - The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/files/123
thefile_id
is123
.
- extension string - The file format for the thumbnail
- minHeight int? (default ()) - The minimum height of the thumbnail
- minWidth int? (default ()) - The minimum width of the thumbnail
- maxHeight int? (default ()) - The maximum height of the thumbnail
- maxWidth int? (default ()) - The maximum width of the thumbnail
Return Type
getFilesIdCollaborations![](/images/permalink.svg)
function getFilesIdCollaborations(string fileId, string[]? fields, int? 'limit, string? marker) returns Collaborations|error
List file collaborations
Parameters
- fileId string - The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/files/123
thefile_id
is123
.
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
- 'limit int? (default ()) - The maximum number of items to return per page.
- marker string? (default ()) - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires
usemarker
to be set totrue
.
Return Type
- Collaborations|error - Returns a collection of collaboration objects. If there are no collaborations on this file an empty collection will be returned. This list includes pending collaborations, for which the
status
is set topending
, indicating invitations that have been sent but not yet accepted.
getFilesIdComments![](/images/permalink.svg)
function getFilesIdComments(string fileId, string[]? fields, int? 'limit, int offset) returns Comments|error
List file comments
Parameters
- fileId string - The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/files/123
thefile_id
is123
.
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
- 'limit int? (default ()) - The maximum number of items to return per page.
- offset int (default 0) - The offset of the item at which to begin the response.
Return Type
getFilesIdTasks![](/images/permalink.svg)
List tasks on file
Parameters
- fileId string - The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/files/123
thefile_id
is123
.
Return Type
getFilesIdTrash![](/images/permalink.svg)
Get trashed file
Parameters
- fileId string - The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/files/123
thefile_id
is123
.
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
Return Type
deleteFilesIdTrash![](/images/permalink.svg)
Permanently remove file
Parameters
- fileId string - The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/files/123
thefile_id
is123
.
getFilesIdVersions![](/images/permalink.svg)
function getFilesIdVersions(string fileId, string[]? fields, int? 'limit, int offset) returns FileVersions|error
List all file versions
Parameters
- fileId string - The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/files/123
thefile_id
is123
.
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
- 'limit int? (default ()) - The maximum number of items to return per page.
- offset int (default 0) - The offset of the item at which to begin the response.
Return Type
- FileVersions|error - Returns an array of past versions for this file.
getFilesIdVersionsId![](/images/permalink.svg)
function getFilesIdVersionsId(string fileId, string fileVersionId, string[]? fields) returns FileVersion|error
Get file version
Parameters
- fileId string - The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/files/123
thefile_id
is123
.
- fileVersionId string - The ID of the file version
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
Return Type
- FileVersion|error - Returns a specific version of a file. Not all available fields are returned by default. Use the fields query parameter to explicitly request any specific fields.
deleteFilesIdVersionsId![](/images/permalink.svg)
function deleteFilesIdVersionsId(string fileId, string fileVersionId, string? ifMatch) returns Response|error
Remove file version
Parameters
- fileId string - The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/files/123
thefile_id
is123
.
- fileVersionId string - The ID of the file version
- ifMatch string? (default ()) - Ensures this item hasn't recently changed before making changes. Pass in the item's last observed
etag
value into this header and the endpoint will fail with a412 Precondition Failed
if it has changed since.
postFilesIdVersionsCurrent![](/images/permalink.svg)
function postFilesIdVersionsCurrent(string fileId, VersionsCurrentBody payload, string[]? fields) returns FileVersion|error
Revert file version
Parameters
- fileId string - The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/files/123
thefile_id
is123
.
- payload VersionsCurrentBody -
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
Return Type
- FileVersion|error - Returns a newly created file version object.
getFilesIdWatermark![](/images/permalink.svg)
Get watermark on file
Parameters
- fileId string - The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/files/123
thefile_id
is123
.
Return Type
putFilesIdWatermark![](/images/permalink.svg)
function putFilesIdWatermark(string fileId, FileIdWatermarkBody payload) returns Watermark|error
Apply watermark to file
Parameters
- fileId string - The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/files/123
thefile_id
is123
.
- payload FileIdWatermarkBody -
Return Type
deleteFilesIdWatermark![](/images/permalink.svg)
Remove watermark from file
Parameters
- fileId string - The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/files/123
thefile_id
is123
.
Return Type
getFileRequestsId![](/images/permalink.svg)
function getFileRequestsId(string fileRequestId) returns FileRequest|error
Get file request
Parameters
- fileRequestId string - The unique identifier that represent a file request. The ID for any file request can be determined by visiting a file request builder in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/filerequest/123
thefile_request_id
is123
.
Return Type
- FileRequest|error - Returns a file request object.
putFileRequestsId![](/images/permalink.svg)
function putFileRequestsId(string fileRequestId, FileRequestUpdateRequest payload, string? ifMatch) returns FileRequest|error
Update file request
Parameters
- fileRequestId string - The unique identifier that represent a file request. The ID for any file request can be determined by visiting a file request builder in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/filerequest/123
thefile_request_id
is123
.
- payload FileRequestUpdateRequest -
- ifMatch string? (default ()) - Ensures this item hasn't recently changed before making changes. Pass in the item's last observed
etag
value into this header and the endpoint will fail with a412 Precondition Failed
if it has changed since.
Return Type
- FileRequest|error - Returns the updated file request object.
deleteFileRequestsId![](/images/permalink.svg)
Delete file request
Parameters
- fileRequestId string - The unique identifier that represent a file request. The ID for any file request can be determined by visiting a file request builder in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/filerequest/123
thefile_request_id
is123
.
Return Type
postFileRequestsIdCopy![](/images/permalink.svg)
function postFileRequestsIdCopy(string fileRequestId, FileRequestCopyRequest payload) returns FileRequest|error
Copy file request
Parameters
- fileRequestId string - The unique identifier that represent a file request. The ID for any file request can be determined by visiting a file request builder in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/filerequest/123
thefile_request_id
is123
.
- payload FileRequestCopyRequest -
Return Type
- FileRequest|error - Returns updated file request object.
getFoldersId![](/images/permalink.svg)
function getFoldersId(string folderId, string[]? fields, string? ifNoneMatch, string? boxapi) returns Folder|error
Get folder information
Parameters
- folderId string - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/folder/123
thefolder_id
is123
. The root folder of a Box account is always represented by the ID0
.
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. Additionally this field can be used to query any metadata applied to the file by specifying the
metadata
field as well as the scope and key of the template to retrieve, for example?field=metadata.enterprise_12345.contractTemplate
.
- ifNoneMatch string? (default ()) - Ensures an item is only returned if it has changed. Pass in the item's last observed
etag
value into this header and the endpoint will fail with a304 Not Modified
if the item has not changed since.
- boxapi string? (default ()) - The URL, and optional password, for the shared link of this item. This header can be used to access items that have not been explicitly shared with a user. Use the format
shared_link=[link]
or if a password is required then useshared_link=[link]&shared_link_password=[password]
. This header can be used on the file or folder shared, as well as on any files or folders nested within the item.
Return Type
- Folder|error - Returns a folder, including the first 100 entries in the folder. To fetch more items within the folder, please use the Get items in a folder endpoint. Not all available fields are returned by default. Use the fields query parameter to explicitly request any specific fields.
putFoldersId![](/images/permalink.svg)
function putFoldersId(string folderId, FoldersFolderIdBody payload, string[]? fields, string? ifMatch) returns Folder|error
Update folder
Parameters
- folderId string - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/folder/123
thefolder_id
is123
. The root folder of a Box account is always represented by the ID0
.
- payload FoldersFolderIdBody -
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
- ifMatch string? (default ()) - Ensures this item hasn't recently changed before making changes. Pass in the item's last observed
etag
value into this header and the endpoint will fail with a412 Precondition Failed
if it has changed since.
Return Type
- Folder|error - Returns a folder object for the updated folder Not all available fields are returned by default. Use the fields query parameter to explicitly request any specific fields. This call will return synchronously. This holds true even when moving folders with a large a large number of items in all of its descendants. For very large folders, this means the call could take minutes or hours to return.
postFoldersId![](/images/permalink.svg)
function postFoldersId(string folderId, FoldersFolderIdBody1 payload, string[]? fields) returns Folder|error
Restore folder
Parameters
- folderId string - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/folder/123
thefolder_id
is123
. The root folder of a Box account is always represented by the ID0
.
- payload FoldersFolderIdBody1 -
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
deleteFoldersId![](/images/permalink.svg)
function deleteFoldersId(string folderId, string? ifMatch, boolean? recursive) returns Response|error
Delete folder
Parameters
- folderId string - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/folder/123
thefolder_id
is123
. The root folder of a Box account is always represented by the ID0
.
- ifMatch string? (default ()) - Ensures this item hasn't recently changed before making changes. Pass in the item's last observed
etag
value into this header and the endpoint will fail with a412 Precondition Failed
if it has changed since.
- recursive boolean? (default ()) - Delete a folder that is not empty by recursively deleting the folder and all of its content.
Return Type
getFoldersIdItems![](/images/permalink.svg)
function getFoldersIdItems(string folderId, string[]? fields, boolean? usemarker, string? marker, int offset, int? 'limit, string? boxapi, string? sort, string? direction) returns Items|error
List items in folder
Parameters
- folderId string - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/folder/123
thefolder_id
is123
. The root folder of a Box account is always represented by the ID0
.
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. Additionally this field can be used to query any metadata applied to the file by specifying the
metadata
field as well as the scope and key of the template to retrieve, for example?field=metadata.enterprise_12345.contractTemplate
.
- usemarker boolean? (default ()) - Specifies whether to use marker-based pagination instead of offset-based pagination. Only one pagination method can be used at a time. By setting this value to true, the API will return a
marker
field that can be passed as a parameter to this endpoint to get the next page of the response.
- marker string? (default ()) - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires
usemarker
to be set totrue
.
- offset int (default 0) - The offset of the item at which to begin the response.
- 'limit int? (default ()) - The maximum number of items to return per page.
- boxapi string? (default ()) - The URL, and optional password, for the shared link of this item. This header can be used to access items that have not been explicitly shared with a user. Use the format
shared_link=[link]
or if a password is required then useshared_link=[link]&shared_link_password=[password]
. This header can be used on the file or folder shared, as well as on any files or folders nested within the item.
- sort string? (default ()) - Defines the second attribute by which items are sorted. Items are always sorted by their
type
first, with folders listed before files, and files listed before web links. This parameter is not supported for marker-based pagination on the root folder (the folder with an ID of0
).
- direction string? (default ()) - The direction to sort results in. This can be either in alphabetical ascending (
ASC
) or descending (DESC
) order.
Return Type
postFolders![](/images/permalink.svg)
function postFolders(FoldersBody payload, string[]? fields) returns Folder|error
Create folder
Parameters
- payload FoldersBody -
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
Return Type
postFoldersIdCopy![](/images/permalink.svg)
function postFoldersIdCopy(string folderId, FolderIdCopyBody payload, string[]? fields) returns Folder|error
Copy folder
Parameters
- folderId string - The unique identifier of the folder to copy. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/folder/123
thefolder_id
is123
. The root folder with the ID0
can not be copied.
- payload FolderIdCopyBody -
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
Return Type
getFoldersIdCollaborations![](/images/permalink.svg)
function getFoldersIdCollaborations(string folderId, string[]? fields) returns Collaborations|error
List folder collaborations
Parameters
- folderId string - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/folder/123
thefolder_id
is123
.
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
Return Type
- Collaborations|error - Returns a collection of collaboration objects. If there are no collaborations on this folder an empty collection will be returned. This list includes pending collaborations, for which the
status
is set topending
, indicating invitations that have been sent but not yet accepted.
getFoldersIdTrash![](/images/permalink.svg)
Get trashed folder
Parameters
- folderId string - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/folder/123
thefolder_id
is123
. The root folder of a Box account is always represented by the ID0
.
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
Return Type
deleteFoldersIdTrash![](/images/permalink.svg)
Permanently remove folder
Parameters
- folderId string - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/folder/123
thefolder_id
is123
. The root folder of a Box account is always represented by the ID0
.
getFoldersTrashItems![](/images/permalink.svg)
function getFoldersTrashItems(string[]? fields, int? 'limit, int offset, boolean? usemarker, string? marker, string? direction, string? sort) returns Items|error
List trashed items
Parameters
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
- 'limit int? (default ()) - The maximum number of items to return per page.
- offset int (default 0) - The offset of the item at which to begin the response.
- usemarker boolean? (default ()) - Specifies whether to use marker-based pagination instead of offset-based pagination. Only one pagination method can be used at a time. By setting this value to true, the API will return a
marker
field that can be passed as a parameter to this endpoint to get the next page of the response.
- marker string? (default ()) - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires
usemarker
to be set totrue
.
- direction string? (default ()) - The direction to sort results in. This can be either in alphabetical ascending (
ASC
) or descending (DESC
) order.
- sort string? (default ()) - Defines the second attribute by which items are sorted. Items are always sorted by their
type
first, with folders listed before files, and files listed before web links. This parameter is not supported when using marker-based pagination.
getFoldersIdWatermark![](/images/permalink.svg)
Get watermark for folder
Parameters
- folderId string - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/folder/123
thefolder_id
is123
. The root folder of a Box account is always represented by the ID0
.
Return Type
putFoldersIdWatermark![](/images/permalink.svg)
function putFoldersIdWatermark(string folderId, FolderIdWatermarkBody payload) returns Watermark|error
Apply watermark to folder
Parameters
- folderId string - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/folder/123
thefolder_id
is123
. The root folder of a Box account is always represented by the ID0
.
- payload FolderIdWatermarkBody -
Return Type
deleteFoldersIdWatermark![](/images/permalink.svg)
Remove watermark from folder
Parameters
- folderId string - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/folder/123
thefolder_id
is123
. The root folder of a Box account is always represented by the ID0
.
Return Type
getFolderLocks![](/images/permalink.svg)
function getFolderLocks(string folderId) returns FolderLocks|error
List folder locks
Parameters
- folderId string - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/folder/123
thefolder_id
is123
. The root folder of a Box account is always represented by the ID0
.
Return Type
- FolderLocks|error - Returns details for all folder locks applied to the folder, including the lock type and user that applied the lock.
postFolderLocks![](/images/permalink.svg)
function postFolderLocks(FolderLocksBody payload) returns FolderLock|error
Create folder lock
Parameters
- payload FolderLocksBody -
Return Type
- FolderLock|error - Returns the instance of the folder lock that was applied to the folder, including the user that applied the lock and the operations set.
deleteFolderLocksId![](/images/permalink.svg)
Delete folder lock
Parameters
- folderLockId string - The ID of the folder lock.
getCommentsId![](/images/permalink.svg)
Get comment
Parameters
- commentId string - The ID of the comment.
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
putCommentsId![](/images/permalink.svg)
function putCommentsId(string commentId, CommentsCommentIdBody payload, string[]? fields) returns Comment|error
Update comment
Parameters
- commentId string - The ID of the comment.
- payload CommentsCommentIdBody -
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
deleteCommentsId![](/images/permalink.svg)
Remove comment
Parameters
- commentId string - The ID of the comment.
postComments![](/images/permalink.svg)
function postComments(CommentsBody payload, string[]? fields) returns Comment|error
Create comment
Parameters
- payload CommentsBody -
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
Return Type
getCollaborationsId![](/images/permalink.svg)
function getCollaborationsId(string collaborationId, string[]? fields) returns Collaboration|error
Get collaboration
Parameters
- collaborationId string - The ID of the collaboration
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
Return Type
- Collaboration|error - Returns a collaboration object.
putCollaborationsId![](/images/permalink.svg)
function putCollaborationsId(string collaborationId, CollaborationsCollaborationIdBody payload) returns Collaboration|error
Update collaboration
Parameters
- collaborationId string - The ID of the collaboration
- payload CollaborationsCollaborationIdBody -
Return Type
- Collaboration|error - Returns an updated collaboration object unless the owner has changed.
deleteCollaborationsId![](/images/permalink.svg)
Remove collaboration
Parameters
- collaborationId string - The ID of the collaboration
Return Type
getCollaborations![](/images/permalink.svg)
function getCollaborations(string status, string[]? fields, int offset, int? 'limit) returns Collaborations|error
List pending collaborations
Parameters
- status string - The status of the collaborations to retrieve
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
- offset int (default 0) - The offset of the item at which to begin the response.
- 'limit int? (default ()) - The maximum number of items to return per page.
Return Type
- Collaborations|error - Returns a collection of pending collaboration objects. If the user has no pending collaborations, the collection will be empty.
postCollaborations![](/images/permalink.svg)
function postCollaborations(CollaborationsBody payload, string[]? fields, boolean? notify) returns Collaboration|error
Create collaboration
Parameters
- payload CollaborationsBody -
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
- notify boolean? (default ()) - Determines if users should receive email notification for the action performed.
Return Type
- Collaboration|error - Returns a new collaboration object.
postTasks![](/images/permalink.svg)
Create task
Parameters
- payload TasksBody -
getTasksId![](/images/permalink.svg)
Get task
Parameters
- taskId string - The ID of the task.
putTasksId![](/images/permalink.svg)
function putTasksId(string taskId, TasksTaskIdBody payload) returns Task|error
Update task
deleteTasksId![](/images/permalink.svg)
Remove task
Parameters
- taskId string - The ID of the task.
getTasksIdAssignments![](/images/permalink.svg)
function getTasksIdAssignments(string taskId) returns TaskAssignments|error
List task assignments
Parameters
- taskId string - The ID of the task.
Return Type
- TaskAssignments|error - Returns a collection of task assignment defining what task on a file has been assigned to which users and by who.
postTaskAssignments![](/images/permalink.svg)
function postTaskAssignments(TaskAssignmentsBody payload) returns TaskAssignment|error
Assign task
Parameters
- payload TaskAssignmentsBody -
Return Type
- TaskAssignment|error - Returns a new task assignment object.
getTaskAssignmentsId![](/images/permalink.svg)
function getTaskAssignmentsId(string taskAssignmentId) returns TaskAssignment|error
Get task assignment
Parameters
- taskAssignmentId string - The ID of the task assignment.
Return Type
- TaskAssignment|error - Returns a task assignment, specifying who the task has been assigned to and by whom.
putTaskAssignmentsId![](/images/permalink.svg)
function putTaskAssignmentsId(string taskAssignmentId, TaskAssignmentsTaskAssignmentIdBody payload) returns TaskAssignment|error
Update task assignment
Parameters
- taskAssignmentId string - The ID of the task assignment.
- payload TaskAssignmentsTaskAssignmentIdBody -
Return Type
- TaskAssignment|error - Returns the updated task assignment object.
deleteTaskAssignmentsId![](/images/permalink.svg)
Unassign task
Parameters
- taskAssignmentId string - The ID of the task assignment.
Return Type
getSharedItems![](/images/permalink.svg)
Find file for shared link
Parameters
- boxapi string - A header containing the shared link and optional password for the shared link. The format for this header is as follows.
shared_link=[link]&shared_link_password=[password]
- ifNoneMatch string? (default ()) - Ensures an item is only returned if it has changed. Pass in the item's last observed
etag
value into this header and the endpoint will fail with a304 Not Modified
if the item has not changed since.
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
Return Type
getFilesIdGetSharedLink![](/images/permalink.svg)
Get shared link for file
Parameters
- fileId string - The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/files/123
thefile_id
is123
.
- fields string - Explicitly request the
shared_link
fields to be returned for this item.
Return Type
putFilesIdAddSharedLink![](/images/permalink.svg)
function putFilesIdAddSharedLink(string fileId, string fields, FilesFileIdaddSharedLinkBody payload) returns File|error
Add shared link to file
Parameters
- fileId string - The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/files/123
thefile_id
is123
.
- fields string - Explicitly request the
shared_link
fields to be returned for this item.
- payload FilesFileIdaddSharedLinkBody -
putFilesIdUpdateSharedLink![](/images/permalink.svg)
function putFilesIdUpdateSharedLink(string fileId, string fields, FilesFileIdupdateSharedLinkBody payload) returns File|error
Update shared link on file
Parameters
- fileId string - The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/files/123
thefile_id
is123
.
- fields string - Explicitly request the
shared_link
fields to be returned for this item.
- payload FilesFileIdupdateSharedLinkBody -
Return Type
putFilesIdRemoveSharedLink![](/images/permalink.svg)
function putFilesIdRemoveSharedLink(string fileId, string fields, FilesFileIdremoveSharedLinkBody payload) returns File|error
Remove shared link from file
Parameters
- fileId string - The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/files/123
thefile_id
is123
.
- fields string - Explicitly request the
shared_link
fields to be returned for this item.
- payload FilesFileIdremoveSharedLinkBody -
getSharedItemsFolders![](/images/permalink.svg)
function getSharedItemsFolders(string boxapi, string? ifNoneMatch, string[]? fields) returns Folder|error
Find folder for shared link
Parameters
- boxapi string - A header containing the shared link and optional password for the shared link. The format for this header is as follows.
shared_link=[link]&shared_link_password=[password]
- ifNoneMatch string? (default ()) - Ensures an item is only returned if it has changed. Pass in the item's last observed
etag
value into this header and the endpoint will fail with a304 Not Modified
if the item has not changed since.
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
Return Type
getFoldersIdGetSharedLink![](/images/permalink.svg)
Get shared link for folder
Parameters
- folderId string - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/folder/123
thefolder_id
is123
. The root folder of a Box account is always represented by the ID0
.
- fields string - Explicitly request the
shared_link
fields to be returned for this item.
Return Type
putFoldersIdAddSharedLink![](/images/permalink.svg)
function putFoldersIdAddSharedLink(string folderId, string fields, FoldersFolderIdaddSharedLinkBody payload) returns Folder|error
Add shared link to folder
Parameters
- folderId string - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/folder/123
thefolder_id
is123
. The root folder of a Box account is always represented by the ID0
.
- fields string - Explicitly request the
shared_link
fields to be returned for this item.
- payload FoldersFolderIdaddSharedLinkBody -
Return Type
putFoldersIdUpdateSharedLink![](/images/permalink.svg)
function putFoldersIdUpdateSharedLink(string folderId, string fields, FoldersFolderIdupdateSharedLinkBody payload) returns Folder|error
Update shared link on folder
Parameters
- folderId string - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/folder/123
thefolder_id
is123
. The root folder of a Box account is always represented by the ID0
.
- fields string - Explicitly request the
shared_link
fields to be returned for this item.
- payload FoldersFolderIdupdateSharedLinkBody -
Return Type
putFoldersIdRemoveSharedLink![](/images/permalink.svg)
function putFoldersIdRemoveSharedLink(string folderId, string fields, FoldersFolderIdremoveSharedLinkBody payload) returns Folder|error
Remove shared link from folder
Parameters
- folderId string - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/folder/123
thefolder_id
is123
. The root folder of a Box account is always represented by the ID0
.
- fields string - Explicitly request the
shared_link
fields to be returned for this item.
- payload FoldersFolderIdremoveSharedLinkBody -
postWebLinks![](/images/permalink.svg)
function postWebLinks(WebLinksBody payload) returns WebLink|error
Create web link
Parameters
- payload WebLinksBody -
getWebLinksId![](/images/permalink.svg)
Get web link
Parameters
- webLinkId string - The ID of the web link.
- boxapi string? (default ()) - The URL, and optional password, for the shared link of this item. This header can be used to access items that have not been explicitly shared with a user. Use the format
shared_link=[link]
or if a password is required then useshared_link=[link]&shared_link_password=[password]
. This header can be used on the file or folder shared, as well as on any files or folders nested within the item.
putWebLinksId![](/images/permalink.svg)
function putWebLinksId(string webLinkId, WebLinksWebLinkIdBody payload) returns WebLink|error
Update web link
postWebLinksId![](/images/permalink.svg)
function postWebLinksId(string webLinkId, WebLinksWebLinkIdBody1 payload, string[]? fields) returns WebLink|error
Restore web link
Parameters
- webLinkId string - The ID of the web link.
- payload WebLinksWebLinkIdBody1 -
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
deleteWebLinksId![](/images/permalink.svg)
Remove web link
Parameters
- webLinkId string - The ID of the web link.
Return Type
getWebLinksIdTrash![](/images/permalink.svg)
Get trashed web link
Parameters
- webLinkId string - The ID of the web link.
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
Return Type
deleteWebLinksIdTrash![](/images/permalink.svg)
Permanently remove web link
Parameters
- webLinkId string - The ID of the web link.
getUsers![](/images/permalink.svg)
function getUsers(string? filterTerm, string? userType, string? externalAppUserId, string[]? fields, int offset, int? 'limit, boolean? usemarker, string? marker) returns Users|error
List enterprise users
Parameters
- filterTerm string? (default ()) - Limits the results to only users who's
name
orlogin
start with the search term. For externally managed users, the search term needs to completely match the in order to find the user, and it will only return one user at a time.
- userType string? (default ()) - Limits the results to the kind of user specified. *
all
returns every kind of user for whom thelogin
orname
partially matches thefilter_term
. It will only return an external user if the login matches thefilter_term
completely, and in that case it will only return that user. *managed
returns all managed and app users for whom thelogin
orname
partially matches thefilter_term
. *external
returns all external users for whom thelogin
matches thefilter_term
exactly.
- externalAppUserId string? (default ()) - Limits the results to app users with the given
external_app_user_id
value. When creating an app user, anexternal_app_user_id
value can be set. This value can then be used in this endpoint to find any users that match thatexternal_app_user_id
value.
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
- offset int (default 0) - The offset of the item at which to begin the response.
- 'limit int? (default ()) - The maximum number of items to return per page.
- usemarker boolean? (default ()) - Specifies whether to use marker-based pagination instead of offset-based pagination. Only one pagination method can be used at a time. By setting this value to true, the API will return a
marker
field that can be passed as a parameter to this endpoint to get the next page of the response.
- marker string? (default ()) - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires
usemarker
to be set totrue
.
postUsers![](/images/permalink.svg)
Create user
Parameters
- payload UsersBody -
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
getUsersMe![](/images/permalink.svg)
Get current user
Parameters
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
getUsersId![](/images/permalink.svg)
Get user
Parameters
- userId string - The ID of the user.
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
Return Type
putUsersId![](/images/permalink.svg)
function putUsersId(string userId, UsersUserIdBody payload, string[]? fields) returns User|error
Update user
Parameters
- userId string - The ID of the user.
- payload UsersUserIdBody -
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
deleteUsersId![](/images/permalink.svg)
Delete user
Parameters
- userId string - The ID of the user.
- notify boolean? (default ()) - Whether the user will receive email notification of the deletion
- force boolean? (default ()) - Whether the user should be deleted even if this user still own files
getUsersIdAvatar![](/images/permalink.svg)
Get user avatar
Parameters
- userId string - The ID of the user.
Return Type
putUsersIdFolders0![](/images/permalink.svg)
function putUsersIdFolders0(string userId, Folders0Body payload, string[]? fields, boolean? notify) returns Folder|error
Transfer owned folders
Parameters
- userId string - The ID of the user.
- payload Folders0Body -
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
- notify boolean? (default ()) - Determines if users should receive email notification for the action performed.
getUsersIdEmailAliases![](/images/permalink.svg)
function getUsersIdEmailAliases(string userId) returns EmailAliases|error
List user's email aliases
Parameters
- userId string - The ID of the user.
Return Type
- EmailAliases|error - Returns a collection of email aliases.
postUsersIdEmailAliases![](/images/permalink.svg)
function postUsersIdEmailAliases(string userId, UserIdEmailAliasesBody payload) returns EmailAlias|error
Create email alias
Return Type
- EmailAlias|error - Returns the newly created email alias object.
deleteUsersIdEmailAliasesId![](/images/permalink.svg)
Remove email alias
getUsersIdMemberships![](/images/permalink.svg)
function getUsersIdMemberships(string userId, int? 'limit, int offset) returns GroupMemberships|error
List user's groups
Parameters
- userId string - The ID of the user.
- 'limit int? (default ()) - The maximum number of items to return per page.
- offset int (default 0) - The offset of the item at which to begin the response.
Return Type
- GroupMemberships|error - Returns a collection of membership objects. If there are no memberships, an empty collection will be returned.
postInvites![](/images/permalink.svg)
function postInvites(InvitesBody payload, string[]? fields) returns Invite|error
Create user invite
Parameters
- payload InvitesBody -
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
getInvitesId![](/images/permalink.svg)
Get user invite status
Parameters
- inviteId string - The ID of an invite.
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
getGroups![](/images/permalink.svg)
function getGroups(string? filterTerm, string[]? fields, int? 'limit, int offset) returns Groups|error
List groups for enterprise
Parameters
- filterTerm string? (default ()) - Limits the results to only groups whose
name
starts with the search term.
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
- 'limit int? (default ()) - The maximum number of items to return per page.
- offset int (default 0) - The offset of the item at which to begin the response.
Return Type
postGroups![](/images/permalink.svg)
function postGroups(GroupsBody payload, string[]? fields) returns Group|error
Create group
Parameters
- payload GroupsBody -
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
getGroupsId![](/images/permalink.svg)
Get group
Parameters
- groupId string - The ID of the group.
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
putGroupsId![](/images/permalink.svg)
function putGroupsId(string groupId, GroupsGroupIdBody payload, string[]? fields) returns Group|error
Update group
Parameters
- groupId string - The ID of the group.
- payload GroupsGroupIdBody -
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
deleteGroupsId![](/images/permalink.svg)
Remove group
Parameters
- groupId string - The ID of the group.
getGroupsIdMemberships![](/images/permalink.svg)
function getGroupsIdMemberships(string groupId, int? 'limit, int offset) returns GroupMemberships|error
List members of group
Parameters
- groupId string - The ID of the group.
- 'limit int? (default ()) - The maximum number of items to return per page.
- offset int (default 0) - The offset of the item at which to begin the response.
Return Type
- GroupMemberships|error - Returns a collection of membership objects. If there are no memberships, an empty collection will be returned.
getGroupsIdCollaborations![](/images/permalink.svg)
function getGroupsIdCollaborations(string groupId, int? 'limit, int offset) returns Collaborations|error
List group collaborations
Parameters
- groupId string - The ID of the group.
- 'limit int? (default ()) - The maximum number of items to return per page.
- offset int (default 0) - The offset of the item at which to begin the response.
Return Type
- Collaborations|error - Returns a collection of collaboration objects. If there are no collaborations, an empty collection will be returned.
postGroupMemberships![](/images/permalink.svg)
function postGroupMemberships(GroupMembershipsBody payload, string[]? fields) returns GroupMembership|error
Add user to group
Parameters
- payload GroupMembershipsBody -
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
Return Type
- GroupMembership|error - Returns a new group membership object.
getGroupMembershipsId![](/images/permalink.svg)
function getGroupMembershipsId(string groupMembershipId, string[]? fields) returns GroupMembership|error
Get group membership
Parameters
- groupMembershipId string - The ID of the group membership.
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
Return Type
- GroupMembership|error - Returns the group membership object.
putGroupMembershipsId![](/images/permalink.svg)
function putGroupMembershipsId(string groupMembershipId, GroupMembershipsGroupMembershipIdBody payload, string[]? fields) returns GroupMembership|error
Update group membership
Parameters
- groupMembershipId string - The ID of the group membership.
- payload GroupMembershipsGroupMembershipIdBody -
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
Return Type
- GroupMembership|error - Returns a new group membership object.
deleteGroupMembershipsId![](/images/permalink.svg)
Remove user from group
Parameters
- groupMembershipId string - The ID of the group membership.
Return Type
getWebhooks![](/images/permalink.svg)
List all webhooks
Parameters
- marker string? (default ()) - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires
usemarker
to be set totrue
.
- 'limit int? (default ()) - The maximum number of items to return per page.
postWebhooks![](/images/permalink.svg)
function postWebhooks(WebhooksBody payload) returns Webhook|error
Create webhook
Parameters
- payload WebhooksBody -
getWebhooksId![](/images/permalink.svg)
Get webhook
Parameters
- webhookId string - The ID of the webhook.
putWebhooksId![](/images/permalink.svg)
function putWebhooksId(string webhookId, WebhooksWebhookIdBody payload) returns Webhook|error
Update webhook
deleteWebhooksId![](/images/permalink.svg)
Remove webhook
Parameters
- webhookId string - The ID of the webhook.
Return Type
putSkillInvocationsId![](/images/permalink.svg)
function putSkillInvocationsId(string skillId, SkillInvocationsSkillIdBody payload) returns Response|error
Update all Box Skill cards on file
Parameters
- skillId string - The ID of the skill to apply this metadata for.
- payload SkillInvocationsSkillIdBody -
getEvents![](/images/permalink.svg)
function getEvents(string streamType, string? streamPosition, int 'limit, string[]? eventType, string? createdAfter, string? createdBefore) returns Events|error
List user and enterprise events
Parameters
- streamType string (default "all") - Defines the type of events that are returned *
all
returns everything for a user and is the default *changes
returns events that may cause file tree changes such as file updates or collaborations. *sync
is similar tochanges
but only applies to synced folders *admin_logs
returns all events for an entire enterprise and requires the user making the API call to have admin permissions.
- streamPosition string? (default ()) - The location in the event stream to start receiving events from. *
now
will return an empty list events and the latest stream position for initialization. *0
ornull
will return all events.
- 'limit int (default 100) - Limits the number of events returned
- eventType string[]? (default ()) - A comma-separated list of events to filter by. This can only be used when requesting the events with a
stream_type
ofadmin_logs
. For any otherstream_type
this value will be ignored.
- createdAfter string? (default ()) - The lower bound date and time to return events for. This can only be used when requesting the events with a
stream_type
ofadmin_logs
. For any otherstream_type
this value will be ignored.
- createdBefore string? (default ()) - The upper bound date and time to return events for. This can only be used when requesting the events with a
stream_type
ofadmin_logs
. For any otherstream_type
this value will be ignored.
Return Type
- Events|error - Returns a list of event objects. Events objects are returned in pages, with each page (chunk) including a list of event objects. The response includes a
chunk_size
parameter indicating how many events were returned in this chunk, as well as the nextstream_position
that can be queried.
optionsEvents![](/images/permalink.svg)
function optionsEvents() returns RealtimeServers|error
Get events long poll endpoint
Return Type
- RealtimeServers|error - Returns a paginated array of servers that can be used instead of the regular endpoints for long-polling events.
getCollections![](/images/permalink.svg)
function getCollections(string[]? fields, int offset, int? 'limit) returns Collections|error
List all collections
Parameters
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
- offset int (default 0) - The offset of the item at which to begin the response.
- 'limit int? (default ()) - The maximum number of items to return per page.
Return Type
- Collections|error - Returns all collections for the given user
getCollectionsIdItems![](/images/permalink.svg)
function getCollectionsIdItems(string collectionId, string[]? fields, int offset, int? 'limit) returns Items|error
List collection items
Parameters
- collectionId string - The ID of the collection.
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
- offset int (default 0) - The offset of the item at which to begin the response.
- 'limit int? (default ()) - The maximum number of items to return per page.
getRecentItems![](/images/permalink.svg)
function getRecentItems(string[]? fields, int? 'limit, string? marker) returns RecentItems|error
List recently accessed items
Parameters
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
- 'limit int? (default ()) - The maximum number of items to return per page.
- marker string? (default ()) - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires
usemarker
to be set totrue
.
Return Type
- RecentItems|error - Returns a list recent items access by a user.
getRetentionPolicies![](/images/permalink.svg)
function getRetentionPolicies(string? policyName, string? policyType, string? createdByUserId) returns RetentionPolicies|error
List retention policies
Parameters
- policyName string? (default ()) - Filters results by a case sensitive prefix of the name of retention policies.
- policyType string? (default ()) - Filters results by the type of retention policy.
- createdByUserId string? (default ()) - Filters results by the ID of the user who created policy.
Return Type
- RetentionPolicies|error - Returns a list retention policies in the enterprise.
postRetentionPolicies![](/images/permalink.svg)
function postRetentionPolicies(RetentionPoliciesBody payload) returns RetentionPolicy|error
Create retention policy
Parameters
- payload RetentionPoliciesBody -
Return Type
- RetentionPolicy|error - Returns a new retention policy object.
getRetentionPoliciesId![](/images/permalink.svg)
function getRetentionPoliciesId(string retentionPolicyId) returns RetentionPolicy|error
Get retention policy
Parameters
- retentionPolicyId string - The ID of the retention policy.
Return Type
- RetentionPolicy|error - Returns the retention policy object.
putRetentionPoliciesId![](/images/permalink.svg)
function putRetentionPoliciesId(string retentionPolicyId, RetentionPoliciesRetentionPolicyIdBody payload) returns RetentionPolicy|error
Update retention policy
Parameters
- retentionPolicyId string - The ID of the retention policy.
- payload RetentionPoliciesRetentionPolicyIdBody -
Return Type
- RetentionPolicy|error - Returns the updated retention policy object.
getRetentionPoliciesIdAssignments![](/images/permalink.svg)
function getRetentionPoliciesIdAssignments(string retentionPolicyId, string? 'type, string? marker, int? 'limit) returns RetentionPolicyAssignments|error
List retention policy assignments
Parameters
- retentionPolicyId string - The ID of the retention policy.
- 'type string? (default ()) - The type of the retention policy assignment to retrieve.
- marker string? (default ()) - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires
usemarker
to be set totrue
.
- 'limit int? (default ()) - The maximum number of items to return per page.
Return Type
- RetentionPolicyAssignments|error - Returns a list of the retention policy assignments associated with the specified retention policy.
postRetentionPolicyAssignments![](/images/permalink.svg)
function postRetentionPolicyAssignments(RetentionPolicyAssignmentsBody payload) returns RetentionPolicyAssignment|error
Assign retention policy
Parameters
- payload RetentionPolicyAssignmentsBody -
Return Type
- RetentionPolicyAssignment|error - Returns a new retention policy assignment object.
getRetentionPolicyAssignmentsId![](/images/permalink.svg)
function getRetentionPolicyAssignmentsId(string retentionPolicyAssignmentId) returns RetentionPolicyAssignment|error
Get retention policy assignment
Parameters
- retentionPolicyAssignmentId string - The ID of the retention policy assignment.
Return Type
- RetentionPolicyAssignment|error - Returns the retention policy assignment object.
getLegalHoldPolicies![](/images/permalink.svg)
function getLegalHoldPolicies(string? policyName, string[]? fields, string? marker, int? 'limit) returns LegalHoldPolicies|error
List all legal hold policies
Parameters
- policyName string? (default ()) - Limits results to policies for which the names start with this search term. This is a case-insensitive prefix.
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
- marker string? (default ()) - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires
usemarker
to be set totrue
.
- 'limit int? (default ()) - The maximum number of items to return per page.
Return Type
- LegalHoldPolicies|error - Returns a list of legal hold policies.
postLegalHoldPolicies![](/images/permalink.svg)
function postLegalHoldPolicies(LegalHoldPoliciesBody payload) returns LegalHoldPolicy|error
Create legal hold policy
Parameters
- payload LegalHoldPoliciesBody -
Return Type
- LegalHoldPolicy|error - Returns a new legal hold policy object.
getLegalHoldPoliciesId![](/images/permalink.svg)
function getLegalHoldPoliciesId(string legalHoldPolicyId) returns LegalHoldPolicy|error
Get legal hold policy
Parameters
- legalHoldPolicyId string - The ID of the legal hold policy
Return Type
- LegalHoldPolicy|error - Returns a legal hold policy object.
putLegalHoldPoliciesId![](/images/permalink.svg)
function putLegalHoldPoliciesId(string legalHoldPolicyId, LegalHoldPoliciesLegalHoldPolicyIdBody payload) returns LegalHoldPolicy|error
Update legal hold policy
Parameters
- legalHoldPolicyId string - The ID of the legal hold policy
- payload LegalHoldPoliciesLegalHoldPolicyIdBody -
Return Type
- LegalHoldPolicy|error - Returns a new legal hold policy object.
deleteLegalHoldPoliciesId![](/images/permalink.svg)
Remove legal hold policy
Parameters
- legalHoldPolicyId string - The ID of the legal hold policy
getLegalHoldPolicyAssignments![](/images/permalink.svg)
function getLegalHoldPolicyAssignments(string policyId, string? assignToType, string? assignToId, string? marker, int? 'limit, string[]? fields) returns LegalHoldPolicyAssignments|error
List legal hold policy assignments
Parameters
- policyId string - The ID of the legal hold policy
- assignToType string? (default ()) - Filters the results by the type of item the policy was applied to.
- assignToId string? (default ()) - Filters the results by the ID of item the policy was applied to.
- marker string? (default ()) - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires
usemarker
to be set totrue
.
- 'limit int? (default ()) - The maximum number of items to return per page.
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
Return Type
- LegalHoldPolicyAssignments|error - Returns a list of legal hold policy assignments.
postLegalHoldPolicyAssignments![](/images/permalink.svg)
function postLegalHoldPolicyAssignments(LegalHoldPolicyAssignmentsBody payload) returns LegalHoldPolicyAssignment|error
Assign legal hold policy
Parameters
- payload LegalHoldPolicyAssignmentsBody -
Return Type
- LegalHoldPolicyAssignment|error - Returns a new legal hold policy assignment.
getLegalHoldPolicyAssignmentsId![](/images/permalink.svg)
function getLegalHoldPolicyAssignmentsId(string legalHoldPolicyAssignmentId) returns LegalHoldPolicyAssignment|error
Get legal hold policy assignment
Parameters
- legalHoldPolicyAssignmentId string - The ID of the legal hold policy assignment
Return Type
- LegalHoldPolicyAssignment|error - Returns a legal hold policy object.
deleteLegalHoldPolicyAssignmentsId![](/images/permalink.svg)
function deleteLegalHoldPolicyAssignmentsId(string legalHoldPolicyAssignmentId) returns Response|error
Unassign legal hold policy
Parameters
- legalHoldPolicyAssignmentId string - The ID of the legal hold policy assignment
Return Type
getLegalHoldPolicyAssignmentsIdFilesOnHold![](/images/permalink.svg)
function getLegalHoldPolicyAssignmentsIdFilesOnHold(string legalHoldPolicyAssignmentId, string? marker, int? 'limit, string[]? fields) returns FileVersionLegalHolds|error
List current file versions for legal hold policy assignment
Parameters
- legalHoldPolicyAssignmentId string - The ID of the legal hold policy assignment
- marker string? (default ()) - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires
usemarker
to be set totrue
.
- 'limit int? (default ()) - The maximum number of items to return per page.
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
Return Type
- FileVersionLegalHolds|error - Returns the list of current file versions held under legal hold for a specific legal hold policy assignment.
getLegalHoldPolicyAssignmentsIdFileVersionsOnHold![](/images/permalink.svg)
function getLegalHoldPolicyAssignmentsIdFileVersionsOnHold(string legalHoldPolicyAssignmentId, string? marker, int? 'limit, string[]? fields) returns FileVersionLegalHolds|error
List previous file versions for legal hold policy assignment
Parameters
- legalHoldPolicyAssignmentId string - The ID of the legal hold policy assignment
- marker string? (default ()) - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires
usemarker
to be set totrue
.
- 'limit int? (default ()) - The maximum number of items to return per page.
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
Return Type
- FileVersionLegalHolds|error - Returns the list of previous file versions held under legal hold for a specific legal hold policy assignment.
getFileVersionRetentionsId![](/images/permalink.svg)
function getFileVersionRetentionsId(string fileVersionRetentionId) returns FileVersionRetention|error
Get retention on file
Parameters
- fileVersionRetentionId string - The ID of the file version retention
Return Type
- FileVersionRetention|error - Returns a file version retention object.
getFileVersionRetentions![](/images/permalink.svg)
function getFileVersionRetentions(string? fileId, string? fileVersionId, string? policyId, string? dispositionAction, string? dispositionBefore, string? dispositionAfter, int? 'limit, string? marker) returns FileVersionRetentions|error
List file version retentions
Parameters
- fileId string? (default ()) - Filters results by files with this ID.
- fileVersionId string? (default ()) - Filters results by file versions with this ID.
- policyId string? (default ()) - Filters results by the retention policy with this ID.
- dispositionAction string? (default ()) - Filters results by the retention policy with this disposition action.
- dispositionBefore string? (default ()) - Filters results by files that will have their disposition come into effect before this date.
- dispositionAfter string? (default ()) - Filters results by files that will have their disposition come into effect after this date.
- 'limit int? (default ()) - The maximum number of items to return per page.
- marker string? (default ()) - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires
usemarker
to be set totrue
.
Return Type
- FileVersionRetentions|error - Returns a list of all file version retentions for the enterprise.
getFileVersionLegalHoldsId![](/images/permalink.svg)
function getFileVersionLegalHoldsId(string fileVersionLegalHoldId) returns FileVersionLegalHold|error
Get file version legal hold
Parameters
- fileVersionLegalHoldId string - The ID of the file version legal hold
Return Type
- FileVersionLegalHold|error - Returns the legal hold policy assignments for the file version.
getFileVersionLegalHolds![](/images/permalink.svg)
function getFileVersionLegalHolds(string policyId, string? marker, int? 'limit) returns FileVersionLegalHolds|error
List file version legal holds
Parameters
- policyId string - The ID of the legal hold policy to get the file version legal holds for.
- marker string? (default ()) - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires
usemarker
to be set totrue
.
- 'limit int? (default ()) - The maximum number of items to return per page.
Return Type
- FileVersionLegalHolds|error - Returns the list of file version legal holds for a specific legal hold policy.
getDevicePinnersId![](/images/permalink.svg)
function getDevicePinnersId(string devicePinnerId) returns DevicePinner|error
Get device pin
Parameters
- devicePinnerId string - The ID of the device pin
Return Type
- DevicePinner|error - Returns information about a single device pin.
deleteDevicePinnersId![](/images/permalink.svg)
Remove device pin
Parameters
- devicePinnerId string - The ID of the device pin
getEnterprisesIdDevicePinners![](/images/permalink.svg)
function getEnterprisesIdDevicePinners(string enterpriseId, string? marker, int? 'limit, string? direction) returns DevicePinners|error
List enterprise device pins
Parameters
- enterpriseId string - The ID of the enterprise
- marker string? (default ()) - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires
usemarker
to be set totrue
.
- 'limit int? (default ()) - The maximum number of items to return per page.
- direction string? (default ()) - The direction to sort results in. This can be either in alphabetical ascending (
ASC
) or descending (DESC
) order.
Return Type
- DevicePinners|error - Returns a list of device pins for a given enterprise.
getTermsOfServices![](/images/permalink.svg)
function getTermsOfServices(string? tosType) returns TermsOfServices|error
List terms of services
Parameters
- tosType string? (default ()) - Limits the results to the terms of service of the given type.
Return Type
- TermsOfServices|error - Returns a collection of terms of service text and settings for the enterprise.
postTermsOfServices![](/images/permalink.svg)
function postTermsOfServices(TermsOfServicesBody payload) returns Task|error
Create terms of service
Parameters
- payload TermsOfServicesBody -
getTermsOfServicesId![](/images/permalink.svg)
function getTermsOfServicesId(string termsOfServiceId) returns TermsOfService|error
Get terms of service
Parameters
- termsOfServiceId string - The ID of the terms of service.
Return Type
- TermsOfService|error - Returns a terms of service object.
putTermsOfServicesId![](/images/permalink.svg)
function putTermsOfServicesId(string termsOfServiceId, TermsOfServicesTermsOfServiceIdBody payload) returns TermsOfService|error
Update terms of service
Parameters
- termsOfServiceId string - The ID of the terms of service.
- payload TermsOfServicesTermsOfServiceIdBody -
Return Type
- TermsOfService|error - Returns an updated terms of service object.
getTermsOfServiceUserStatuses![](/images/permalink.svg)
function getTermsOfServiceUserStatuses(string tosId, string? userId) returns TermsOfServiceUserStatuses|error
List terms of service user statuses
Parameters
- tosId string - The ID of the terms of service.
- userId string? (default ()) - Limits results to the given user ID.
Return Type
- TermsOfServiceUserStatuses|error - Returns a list of terms of service statuses.
postTermsOfServiceUserStatuses![](/images/permalink.svg)
function postTermsOfServiceUserStatuses(TermsOfServiceUserStatusesBody payload) returns TermsOfServiceUserStatus|error
Create terms of service status for new user
Parameters
- payload TermsOfServiceUserStatusesBody -
Return Type
- TermsOfServiceUserStatus|error - Returns a terms of service status object.
putTermsOfServiceUserStatusesId![](/images/permalink.svg)
function putTermsOfServiceUserStatusesId(string termsOfServiceUserStatusId, TermsOfServiceUserStatusesTermsOfServiceUserStatusIdBody payload) returns TermsOfServiceUserStatus|error
Update terms of service status for existing user
Parameters
- termsOfServiceUserStatusId string - The ID of the terms of service status.
Return Type
- TermsOfServiceUserStatus|error - Returns the updated terms of service status object.
getCollaborationWhitelistEntries![](/images/permalink.svg)
function getCollaborationWhitelistEntries(string? marker, int? 'limit) returns CollaborationAllowlistEntries|error
List allowed collaboration domains
Parameters
- marker string? (default ()) - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires
usemarker
to be set totrue
.
- 'limit int? (default ()) - The maximum number of items to return per page.
Return Type
- CollaborationAllowlistEntries|error - Returns a collection of domains that are allowed for collaboration.
postCollaborationWhitelistEntries![](/images/permalink.svg)
function postCollaborationWhitelistEntries(CollaborationWhitelistEntriesBody payload) returns CollaborationAllowlistEntry|error
Add domain to list of allowed collaboration domains
Parameters
- payload CollaborationWhitelistEntriesBody -
Return Type
- CollaborationAllowlistEntry|error - Returns a new entry on the list of allowed domains.
getCollaborationWhitelistEntriesId![](/images/permalink.svg)
function getCollaborationWhitelistEntriesId(string collaborationWhitelistEntryId) returns CollaborationAllowlistEntry|error
Get allowed collaboration domain
Parameters
- collaborationWhitelistEntryId string - The ID of the entry in the list.
Return Type
- CollaborationAllowlistEntry|error - Returns an entry on the list of allowed domains.
deleteCollaborationWhitelistEntriesId![](/images/permalink.svg)
function deleteCollaborationWhitelistEntriesId(string collaborationWhitelistEntryId) returns Response|error
Remove domain from list of allowed collaboration domains
Parameters
- collaborationWhitelistEntryId string - The ID of the entry in the list.
getCollaborationWhitelistExemptTargets![](/images/permalink.svg)
function getCollaborationWhitelistExemptTargets(string? marker, int? 'limit) returns CollaborationAllowlistExemptTargets|error
List users exempt from collaboration domain restrictions
Parameters
- marker string? (default ()) - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires
usemarker
to be set totrue
.
- 'limit int? (default ()) - The maximum number of items to return per page.
Return Type
- CollaborationAllowlistExemptTargets|error - Returns a collection of user exemptions.
postCollaborationWhitelistExemptTargets![](/images/permalink.svg)
function postCollaborationWhitelistExemptTargets(CollaborationWhitelistExemptTargetsBody payload) returns CollaborationAllowlistExemptTarget|error
Create user exemption from collaboration domain restrictions
Parameters
- payload CollaborationWhitelistExemptTargetsBody -
Return Type
- CollaborationAllowlistExemptTarget|error - Returns a new exemption entry.
getCollaborationWhitelistExemptTargetsId![](/images/permalink.svg)
function getCollaborationWhitelistExemptTargetsId(string collaborationWhitelistExemptTargetId) returns CollaborationAllowlistExemptTarget|error
Get user exempt from collaboration domain restrictions
Parameters
- collaborationWhitelistExemptTargetId string - The ID of the exemption to the list.
Return Type
- CollaborationAllowlistExemptTarget|error - Returns the user's exempted from the list of collaboration domains.
deleteCollaborationWhitelistExemptTargetsId![](/images/permalink.svg)
function deleteCollaborationWhitelistExemptTargetsId(string collaborationWhitelistExemptTargetId) returns Response|error
Remove user from list of users exempt from domain restrictions
Parameters
- collaborationWhitelistExemptTargetId string - The ID of the exemption to the list.
getStoragePolicies![](/images/permalink.svg)
function getStoragePolicies(string[]? fields, string? marker, int? 'limit) returns StoragePolicies|error
List storage policies
Parameters
- fields string[]? (default ()) - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
- marker string? (default ()) - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires
usemarker
to be set totrue
.
- 'limit int? (default ()) - The maximum number of items to return per page.
Return Type
- StoragePolicies|error - Returns a collection of storage policies.
getStoragePoliciesId![](/images/permalink.svg)
function getStoragePoliciesId(string storagePolicyId) returns StoragePolicy|error
Get storage policy
Parameters
- storagePolicyId string - The ID of the storage policy.
Return Type
- StoragePolicy|error - Returns a storage policy object.
getStoragePolicyAssignments![](/images/permalink.svg)
function getStoragePolicyAssignments(string resolvedForType, string resolvedForId, string? marker) returns StoragePolicyAssignments|error
List storage policy assignments
Parameters
- resolvedForType string - The target type to return assignments for
- resolvedForId string - The ID of the user or enterprise to return assignments for
- marker string? (default ()) - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires
usemarker
to be set totrue
.
Return Type
- StoragePolicyAssignments|error - Returns a collection of storage policies for the enterprise or user.
postStoragePolicyAssignments![](/images/permalink.svg)
function postStoragePolicyAssignments(StoragePolicyAssignmentsBody payload) returns StoragePolicyAssignment|error
Assign storage policy
Parameters
- payload StoragePolicyAssignmentsBody -
Return Type
- StoragePolicyAssignment|error - Returns the new storage policy assignment created.
getStoragePolicyAssignmentsId![](/images/permalink.svg)
function getStoragePolicyAssignmentsId(string storagePolicyAssignmentId) returns StoragePolicyAssignment|error
Get storage policy assignment
Parameters
- storagePolicyAssignmentId string - The ID of the storage policy assignment.
Return Type
- StoragePolicyAssignment|error - Returns a storage policy assignment object.
putStoragePolicyAssignmentsId![](/images/permalink.svg)
function putStoragePolicyAssignmentsId(string storagePolicyAssignmentId, StoragePolicyAssignmentsStoragePolicyAssignmentIdBody payload) returns StoragePolicyAssignment|error
Update storage policy assignment
Parameters
- storagePolicyAssignmentId string - The ID of the storage policy assignment.
Return Type
- StoragePolicyAssignment|error - Returns an updated storage policy assignment object.
deleteStoragePolicyAssignmentsId![](/images/permalink.svg)
Unassign storage policy
Parameters
- storagePolicyAssignmentId string - The ID of the storage policy assignment.
Return Type
postZipDownloads![](/images/permalink.svg)
function postZipDownloads(ZipDownloadRequest payload) returns ZipDownload|error
Create zip download
Parameters
- payload ZipDownloadRequest -
Return Type
- ZipDownload|error - If the
zip
archive is ready to be downloaded, the API will return a response that will include adownload_url
, astatus_url
, as well as any conflicts that might have occurred when creating the request.
getZipDownloadsIdContent![](/images/permalink.svg)
Download zip archive
Parameters
- zipDownloadId string - The unique identifier that represent this
zip
archive.
Return Type
getZipDownloadsIdStatus![](/images/permalink.svg)
function getZipDownloadsIdStatus(string zipDownloadId) returns ZipDownloadStatus|error
Get zip download status
Parameters
- zipDownloadId string - The unique identifier that represent this
zip
archive.
Return Type
- ZipDownloadStatus|error - Returns the status of the
zip
archive that is being downloaded.
Records![](/images/permalink.svg)
box: AccessToken![](/images/permalink.svg)
A token that can be used to make authenticated API calls.
Fields
- access_token string? - The requested access token.
- expires_in int? - The time in seconds in seconds by which this token will expire.
- token_type string? - The type of access token returned.
- restricted_to FileScope[]? - The permissions that this access token permits, providing a list of resources (files, folders, etc) and the scopes permitted for each of those resources.
- refresh_token string? - The refresh token for this access token, which can be used to request a new access token when the current one expires.
- issued_token_type string? - The type of downscoped access token returned. This is only returned if an access token has been downscoped.
box: AssignedTo![](/images/permalink.svg)
The bare basic reference for an object
Fields
- id string? - The unique identifier for this object
- 'type string? - The type for this object
box: ClassificationTemplate![](/images/permalink.svg)
A metadata template that holds the security classifications defined by an enterprise.
Fields
- id string? - The ID of the classification template.
- 'type string? -
metadata_template
- scope string? - The scope of the classification template. This is in the format
enterprise_{id}
where theid
is the enterprise ID.
- templateKey string? -
securityClassification-6VMVochwUWo
- displayName string? - The name of this template as shown in web and mobile interfaces.
- hidden boolean? - This template is always available in web and mobile interfaces.
- copyInstanceOnItemCopy boolean? - Classifications are always copied along when the file or folder is copied.
- fields ClassificationtemplateFields[]? - A list of fields for this classification template. This includes only one field, the
Box__Security__Classification__Key
, which defines the different classifications available in this enterprise.
box: ClassificationtemplateFields![](/images/permalink.svg)
The metadata template field that represents the available classifications.
Fields
- id string? - The unique ID of the field.
- 'type string? -
enum
- 'key string? -
Box__Security__Classification__Key
- displayName string? -
Classification
- hidden boolean? - Classifications are always visible to web and mobile users.
- options ClassificationtemplateOptions[]? - A list of classifications available in this enterprise.
box: ClassificationtemplateOptions![](/images/permalink.svg)
A single classification available in this enterprise.
Fields
- id string? - The unique ID of this classification.
- 'key string? - The display name and key for this classification.
- staticConfig ClassificationtemplateStaticconfig? - Additional information about the classification.
box: ClassificationtemplateStaticconfig![](/images/permalink.svg)
Additional information about the classification.
Fields
- classification ClassificationtemplateStaticconfigClassification? - Additional information about the classification. This is not an exclusive list of properties, and more object fields might be returned. These fields are used for internal Box Shield and Box Governance purposes and no additional value must be derived from these fields.
box: ClassificationtemplateStaticconfigClassification![](/images/permalink.svg)
Additional information about the classification. This is not an exclusive list of properties, and more object fields might be returned. These fields are used for internal Box Shield and Box Governance purposes and no additional value must be derived from these fields.
Fields
- classificationDefinition string? - A longer description of the classification.
- colorID decimal? - An internal Box identifier used to assign a color to a classification label. Mapping between a
colorID
and a color may change without notice. Currently, the color mappings are as follows. *0
: Yellow *1
: Orange *2
: Watermelon red *3
: Purple rain *4
: Light blue *5
: Dark blue *6
: Light green *7
: Gray
box: ClientConfig![](/images/permalink.svg)
Provides a set of configurations for controlling the behaviours when communicating with a remote HTTP endpoint.
Fields
- auth BearerTokenConfig|OAuth2RefreshTokenGrantConfig - Configurations related to client authentication
- httpVersion string(default "1.1") - The HTTP version understood by the client
- http1Settings ClientHttp1Settings(default {}) - Configurations related to HTTP/1.x protocol
- http2Settings ClientHttp2Settings(default {}) - Configurations related to HTTP/2 protocol
- timeout decimal(default 60) - The maximum time to wait (in seconds) for a response before closing the connection
- forwarded string(default "disable") - The choice of setting
forwarded
/x-forwarded
header
- followRedirects FollowRedirects?(default ()) - Configurations associated with Redirection
- poolConfig PoolConfiguration?(default ()) - Configurations associated with request pooling
- cache CacheConfig(default {}) - HTTP caching related configurations
- compression Compression(default http:COMPRESSION_AUTO) - Specifies the way of handling compression (
accept-encoding
) header
- circuitBreaker CircuitBreakerConfig?(default ()) - Configurations associated with the behaviour of the Circuit Breaker
- retryConfig RetryConfig?(default ()) - Configurations associated with retrying
- cookieConfig CookieConfig?(default ()) - Configurations associated with cookies
- responseLimits ResponseLimitConfigs(default {}) - Configurations associated with inbound response size limits
- secureSocket ClientSecureSocket?(default ()) - SSL/TLS-related options
box: ClientError![](/images/permalink.svg)
A generic error
Fields
- 'type string? -
error
- status int? - The HTTP status of the response.
- code string? - A Box-specific error code
- message string? - A short message describing the error.
- context_info ClienterrorContextInfo? - A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis.
- help_url string? - A URL that links to more information about why this error occurred.
- request_id string? - A unique identifier for this response, which can be used when contacting Box support.
box: ClienterrorContextInfo![](/images/permalink.svg)
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis.
Fields
- conflicts FileConflict[]? - A list of the file conflicts that caused this error.
box: Collaboration![](/images/permalink.svg)
Collaborations define access permissions for users and groups to files and folders, similar to access control lists. A collaboration object grants a user or group access to a file or folder with permissions defined by a specific role.
Fields
- id string? - The unique identifier for this collaboration.
- 'type string? -
collaboration
- accessible_by UserMini? - A mini representation of a user, as can be returned when nested within other resources.
- invite_email string? - The email address used to invite an unregistered collaborator, if they are not a registered user.
- role string? - The level of access granted.
- expires_at string? - When the collaboration will expire, or
null
if no expiration date is set.
- status string? - The status of the collaboration invitation.
- acknowledged_at string? - When the
status
of the collaboration object changed toaccepted
orrejected
- created_by UserMini? - A mini representation of a user, as can be returned when nested within other resources.
- created_at string? - When the collaboration object was created
- modified_at string? - When the collaboration object was last modified
- acceptance_requirements_status CollaborationAcceptanceRequirementsStatus? - The terms of service that must be accepted before the collaboration can be accepted.
box: CollaborationAcceptanceRequirementsStatus![](/images/permalink.svg)
The terms of service that must be accepted before the collaboration can be accepted.
Fields
- terms_of_service_requirement CollaborationAcceptanceRequirementsStatusTermsOfServiceRequirement? -
- strong_password_requirement CollaborationAcceptanceRequirementsStatusStrongPasswordRequirement? -
- two_factor_authentication_requirement CollaborationAcceptanceRequirementsStatusTwoFactorAuthenticationRequirement? -
box: CollaborationAcceptanceRequirementsStatusStrongPasswordRequirement![](/images/permalink.svg)
Fields
- enterprise_has_strong_password_required_for_external_users boolean? - Whether or not the enterprise that owns the content requires a strong password to collaborate on the content.
- user_has_strong_password boolean? - Whether or not the user has a strong password set for their account. The field is
null
when a strong password is not required.
box: CollaborationAcceptanceRequirementsStatusTermsOfServiceRequirement![](/images/permalink.svg)
Fields
- is_accepted boolean? - Whether or not the terms of service have been accepted. The field is
null
when there is no terms of service required.
- terms_of_service record {}? -
box: CollaborationAcceptanceRequirementsStatusTwoFactorAuthenticationRequirement![](/images/permalink.svg)
Fields
- enterprise_has_two_factor_auth_enabled boolean? - Whether or not the enterprise that owns the content requires two-factor authentication to be enabled in order to collaborate on the content.
- user_has_two_factor_authentication_enabled boolean? - Whether or not the user has two-factor authentication enabled. The field is
null
when two-factor authentication is not required.
box: CollaborationAllowlistEnterprise![](/images/permalink.svg)
A representation of a Box enterprise
Fields
- id string? - The unique identifier for this enterprise.
- 'type string? -
enterprise
- name string? - The name of the enterprise
box: CollaborationAllowlistEntries![](/images/permalink.svg)
A list of allowed domains for collaboration.
Fields
- 'limit int? - The limit that was used for these entries. This will be the same as the
limit
query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.
- next_marker int? - The marker for the start of the next page of results.
- prev_marker int? - The marker for the start of the previous page of results.
- entries CollaborationAllowlistEntry[]? -
box: CollaborationAllowlistEntry![](/images/permalink.svg)
An entry that describes an approved domain for which users can collaborate with files and folders in your enterprise or vice versa.
Fields
- id string? - The unique identifier for this entry
- 'type string? -
collaboration_whitelist_entry
- domain string? - The whitelisted domain
- direction string? - The direction of the collaborations to allow.
- enterprise CollaborationAllowlistEnterprise? - A representation of a Box enterprise
- created_at string? - The time the entry was created at
box: CollaborationAllowlistExemptTarget![](/images/permalink.svg)
The user that is exempt from any of the restrictions imposed by the list of allowed collaboration domains for this enterprise.
Fields
- id string? - The unique identifier for this exemption
- 'type string? -
collaboration_whitelist
- enterprise CollaborationAllowlistEnterprise? - A representation of a Box enterprise
- user CollaborationAllowlistUser? - A representation of a Box enterprise
- created_at string? - The time the entry was created
- modified_at string? - The time the entry was modified
box: CollaborationAllowlistExemptTargets![](/images/permalink.svg)
A list of users that is exempt from any of the restrictions imposed by the list of allowed collaboration domains for this enterprise.
Fields
- 'limit int? - The limit that was used for these entries. This will be the same as the
limit
query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.
- next_marker int? - The marker for the start of the next page of results.
- prev_marker int? - The marker for the start of the previous page of results.
- entries CollaborationAllowlistExemptTarget[]? -
box: CollaborationAllowlistUser![](/images/permalink.svg)
A representation of a Box enterprise
Fields
- id string? - The unique identifier for this enterprise.
- 'type string? -
enterprise
- name string? - The name of the enterprise
box: Collaborations![](/images/permalink.svg)
A list of collaborations
Fields
- total_count int? - One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than
total_count
. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.
- 'limit int? - The limit that was used for these entries. This will be the same as the
limit
query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.
- offset int? - The 0-based offset of the first entry in this set. This will be the same as the
offset
query parameter. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.
- 'order CollaborationsOrder[]? - The order by which items are returned. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.
- entries Collaboration[]? -
box: CollaborationsAccessibleBy![](/images/permalink.svg)
The user or group to give access to the item.
Fields
- 'type string - The type of collaborator to invite.
- id string? - The ID of the user or group. Alternatively, use
login
to specify a user by email address.
- login string? - The email address of the user to grant access to the item. Alternatively, use
id
to specify a user by user ID.
box: CollaborationsBody![](/images/permalink.svg)
Fields
- item CollaborationsItem - The item to attach the comment to.
- accessible_by CollaborationsAccessibleBy - The user or group to give access to the item.
- role string - The level of access granted.
- can_view_path boolean? - Determines if the invited users can see the entire parent path to the associated folder. The user will not gain privileges in any parent folder and therefore can not see content the user is not collaborated on. Be aware that this meaningfully increases the time required to load the invitee's All Files page. We recommend you limit the number of collaborations with
can_view_path
enabled to 1,000 per user.
- expires_at string? - Set the expiration date for the collaboration. At this date, the collaboration will be automatically removed from the item. This feature will only work if the Automatically remove invited collaborators: Allow folder owners to extend the expiry date setting has been enabled in the Enterprise Settings of the Admin Console. When the setting is not enabled, collaborations can not have an expiry date and a value for this field will be result in an error.
box: CollaborationsCollaborationIdBody![](/images/permalink.svg)
Fields
- role string - The level of access granted.
- status string? - <!--alex ignore reject--> Set the status of a `pending` collaboration invitation, effectively accepting, or rejecting the invite.
- expires_at string? - Update the expiration date for the collaboration. At this date, the collaboration will be automatically removed from the item. This feature will only work if the Automatically remove invited collaborators: Allow folder owners to extend the expiry date setting has been enabled in the Enterprise Settings of the Admin Console. When the setting is not enabled, collaborations can not have an expiry date and a value for this field will be result in an error. Additionally, a collaboration can only be given an expiration if it was created after the Automatically remove invited collaborator setting was enabled.
- can_view_path boolean? - Determines if the invited users can see the entire parent path to the associated folder. The user will not gain privileges in any parent folder and therefore can not see content the user is not collaborated on. Be aware that this meaningfully increases the time required to load the invitee's All Files page. We recommend you limit the number of collaborations with
can_view_path
enabled to 1,000 per user.
box: CollaborationsItem![](/images/permalink.svg)
The item to attach the comment to.
Fields
- 'type string - The type of the item that this collaboration will be granted access to
- id string - The ID of the item that will be granted access to
box: CollaborationsOrder![](/images/permalink.svg)
The order in which a pagination is ordered
Fields
- 'by string? - The field to order by
- direction string? - The direction to order by, either ascending or descending
box: CollaborationWhitelistEntriesBody![](/images/permalink.svg)
Fields
- domain string - The domain to add to the list of allowed domains.
- direction string - The direction in which to allow collaborations.
box: CollaborationWhitelistExemptTargetsBody![](/images/permalink.svg)
Fields
- user CollaborationWhitelistExemptTargetsUser - The user to exempt.
box: CollaborationWhitelistExemptTargetsUser![](/images/permalink.svg)
The user to exempt.
Fields
- id string - The ID of the user to exempt.
box: Collection![](/images/permalink.svg)
A collection of items, including files and folders. Currently, the only collection available is the favorites
collection. The contents of a collection can be explored in a similar way to which the contents of a folder is explored.
Fields
- id string? - The unique identifier for this collection.
- 'type string? -
collection
- name string? - The name of the collection.
- collection_type string? - The type of the collection. This is used to determine the proper visual treatment for collections.
box: Collections![](/images/permalink.svg)
A list of collections
Fields
- total_count int? - One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than
total_count
. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.
- 'limit int? - The limit that was used for these entries. This will be the same as the
limit
query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.
- offset int? - The 0-based offset of the first entry in this set. This will be the same as the
offset
query parameter. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.
- 'order CollaborationsOrder[]? - The order by which items are returned. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.
- entries Collection[]? -
box: Comment![](/images/permalink.svg)
Standard representation of a comment.
Fields
- Fields Included from *CommentBase
- is_reply_comment boolean? - Whether or not this comment is a reply to another comment
- message string? - The text of the comment, as provided by the user
- created_by record {}? -
- created_at string? - The time this comment was created
- modified_at string? - The time this comment was last modified
box: CommentBase![](/images/permalink.svg)
Base representation of a comment.
Fields
- id string? - The unique identifier for this comment.
- 'type string? -
comment
box: CommentFull![](/images/permalink.svg)
Comments are messages created on files. Comments can be made independently or created as responses to other comments
Fields
- Fields Included from *Comment
- tagged_message string? - The string representing the comment text with @mentions included. @mention format is @[id:username] where
id
is user's Box ID andusername
is their display name.
box: Comments![](/images/permalink.svg)
A list of comments
Fields
- total_count int? - One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than
total_count
. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.
- 'limit int? - The limit that was used for these entries. This will be the same as the
limit
query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.
- offset int? - The 0-based offset of the first entry in this set. This will be the same as the
offset
query parameter. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.
- 'order CollaborationsOrder[]? - The order by which items are returned. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.
- entries Comment[]? -
box: CommentsBody![](/images/permalink.svg)
Fields
- message string - The text of the comment. To mention a user, use the
tagged_message
parameter instead.
- tagged_message string? - The text of the comment, including
@[user_id:name]
somewhere in the message to mention another user, which will send them an email notification, letting them know they have been mentioned. Theuser_id
is the target user's ID, where thename
can be any custom phrase. In the Box UI this name will link to the user's profile. If you are not mentioning another user, usemessage
instead.
- item CommentsItem? - The item to attach the comment to.
box: CommentsCommentIdBody![](/images/permalink.svg)
Fields
- message string? - The text of the comment to update
box: CommentsItem![](/images/permalink.svg)
The item to attach the comment to.
Fields
- id string - The ID of the item
- 'type string - The type of the item that this comment will be placed on.
box: ConflictError![](/images/permalink.svg)
The error that occurs when a file can not be created due to a conflict.
Fields
- Fields Included from *ClientError
- context_info ConflicterrorContextInfo? -
box: ConflicterrorContextInfo![](/images/permalink.svg)
Fields
- conflicts FileConflict[]? - A list of the file conflicts that caused this error.
box: DevicePinner![](/images/permalink.svg)
Device pins allow enterprises to control what devices can use native Box applications.
Fields
- id string? - The unique identifier for this device pin.
- 'type string? -
device_pinner
- owned_by UserMini? - A mini representation of a user, as can be returned when nested within other resources.
- product_name string? - The type of device being pinned
- created_at string? - The time the device pin was created
- modified_at string? - The time the device pin was modified
box: DevicePinners![](/images/permalink.svg)
A list of device pins
Fields
- entries DevicePinner[]? - A entries of device pins
- 'limit int? - The limit that was used for these entries. This will be the same as the
limit
query parameter unless that value exceeded the maximum value allowed.
- next_marker int? - The marker for the start of the next page of results.
- 'order DevicepinnersOrder[]? - The order by which items are returned.
box: DevicepinnersOrder![](/images/permalink.svg)
The order in which a pagination is ordered
Fields
- 'by string? - The field that is ordered by
- direction string? - The direction to order by, either ascending or descending
box: EmailAlias![](/images/permalink.svg)
An email alias for a user.
Fields
- id string? - The unique identifier for this object
- 'type string? - Email alias type
- email string? - The email address
- is_confirmed boolean? - Whether the email address has been confirmed
box: EmailAliases![](/images/permalink.svg)
A list of email aliases
Fields
- total_count int? - The number of email aliases.
- entries EmailAlias[]? - The entries of email alias.
box: Enterprise![](/images/permalink.svg)
A representation of a Box enterprise
Fields
- id string? - The unique identifier for this enterprise.
- 'type string? -
enterprise
- name string? - The name of the enterprise
box: Event![](/images/permalink.svg)
The description of an event that happened within Box
Fields
- 'type string? -
event
- event_id string? - The ID of the event object. You can use this to detect duplicate events
- created_by UserMini? - A mini representation of a user, as can be returned when nested within other resources.
- event_type string? - An event type that can trigger an event
- session_id string? - The session of the user that performed the action. Not all events will populate this attribute.
- 'source User|EventSource? -
- additional_details record {}? - This object provides additional information about the event if available. This can include how a user performed an event as well as additional information to correlate an event to external KeySafe logs. Not all events have an
additional_details
object. This object is only available in the Enterprise Events.
box: Events![](/images/permalink.svg)
A list of event objects
Fields
- chunk_size int? - The number of events returned in this response.
- next_stream_position string? - The stream position of the start of the next page (chunk) of events.
- entries Event[]? - The description of an events that happened within Box.
box: EventSource![](/images/permalink.svg)
The source file or folder that triggered an event in the event stream.
Fields
- item_type string? - The type of the item that the event represents. Can be
file
orfolder
.
- item_id string? - The unique identifier that represents the item.
- item_name string? - The name of the item.
- parent FolderMini? - A mini representation of a file version, used when nested under another resource.
- owned_by UserMini? - A mini representation of a user, as can be returned when nested within other resources.
box: File![](/images/permalink.svg)
A standard representation of a file, as returned from any file API endpoints by default
Fields
- Fields Included from *FileMini
- description string? - The optional description of this file
- size int? - The file size in bytes. Be careful parsing this integer as it can get very large and cause an integer overflow.
- path_collection record { total_count int, entries FolderMini[] }? -
- created_at string? - The date and time when the file was created on Box.
- modified_at string? - The date and time when the file was last updated on Box.
- trashed_at string? - The time at which this file was put in the trash.
- purged_at string? - The time at which this file is expected to be purged from the trash.
- content_created_at string? - The date and time at which this file was originally created, which might be before it was uploaded to Box.
- content_modified_at string? - The date and time at which this file was last updated, which might be before it was uploaded to Box.
- created_by record {}? -
- modified_by record {}? -
- owned_by record {}? -
- shared_link record { url string, download_url string?, vanity_url string?, vanity_name string?, access string, effective_access string, effective_permission string, unshared_at string?, is_password_enabled boolean, permissions record { can_download boolean, can_preview boolean }, download_count int, preview_count int }? -
- parent record {}? -
- item_status string? - Defines if this item has been deleted or not. *
active
when the item has is not in the trash *trashed
when the item has been moved to the trash but not deleted *deleted
when the item has been permanently deleted.
box: FileBase![](/images/permalink.svg)
The bare basic representation of a file, the minimal amount of fields returned when using the fields
query parameter.
Fields
- id string? - The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/files/123
thefile_id
is123
.
- etag string? - The HTTP
etag
of this file. This can be used within some API endpoints in theIf-Match
andIf-None-Match
headers to only perform changes on the file if (no) changes have happened.
- 'type string? -
file
box: FileConflict![](/images/permalink.svg)
A representation of a file that is used to show
Fields
- Fields Included from *FileMini
- sha1 string? - The SHA1 hash of the file.
- file_version FileversionMini? - A mini representation of a file version, used when nested within another resource.
box: FileFull![](/images/permalink.svg)
A full representation of a file, as can be returned from any file API endpoints by default
Fields
- Fields Included from *File
- description string
- size int
- path_collection record { total_count int, entries FolderMini[], anydata... }
- created_at string
- modified_at string
- trashed_at string|()
- purged_at string|()
- content_created_at string|()
- content_modified_at string|()
- created_by record { name string, login string, id string, type string, anydata... }
- modified_by record { name string, login string, id string, type string, anydata... }
- owned_by record { name string, login string, id string, type string, anydata... }
- shared_link record { url string, download_url string|(), vanity_url string|(), vanity_name string|(), access string, effective_access string, effective_permission string, unshared_at string|(), is_password_enabled boolean, permissions record { can_download boolean, can_preview boolean, anydata... }, download_count int, preview_count int, anydata... }
- parent record { sequence_id record { anydata... }, name string, id string, etag string|(), type string, anydata... }
- item_status string
- sequence_id record { anydata... }
- name string
- sha1 string
- file_version record { sha1 string, id string, type string, anydata... }
- id string
- etag string|()
- type string
- anydata...
- version_number string? - The version number of this file
- comment_count int? - The number of comments on this file
- permissions record { can_delete boolean, can_download boolean, can_invite_collaborator boolean, can_rename boolean, can_set_share_access boolean, can_share boolean, can_annotate boolean, can_comment boolean, can_preview boolean, can_upload boolean, can_view_annotations_all boolean, can_view_annotations_self boolean }? -
- tags record {}? -
- extension string? - Indicates the (optional) file extension for this file. By default, this is set to an empty string.
- is_package boolean? - Indicates if the file is a package. Packages are commonly used by Mac Applications and can include iWork files.
- watermark_info record { is_watermarked boolean }? -
- allowed_invitee_roles string[]? - A list of the types of roles that user can be invited at when sharing this file.
- is_externally_owned boolean? - Specifies if this file is owned by a user outside of the authenticated enterprise.
- has_collaborations boolean? - Specifies if this file has any other collaborators.
- metadata record {}? -
- expires_at string? - When the file will automatically be deleted
- uploader_display_name record {}? -
box: FileIdContentBody![](/images/permalink.svg)
Fields
- attributes FilesfileIdcontentAttributes - The additional attributes of the file being uploaded. Mainly the name and the parent folder. These attributes are part of the multi part request body and are in JSON format. <Message warning> The
attributes
part of the body must come before thefile
part. Requests that do not follow this format when uploading the file will receive a HTTP400
error with ametadata_after_file_contents
error code. </Message>
- file string - The content of the file to upload to Box. <Message warning> The
attributes
part of the body must come before thefile
part. Requests that do not follow this format when uploading the file will receive a HTTP400
error with ametadata_after_file_contents
error code. </Message>
box: FileIdCopyBody![](/images/permalink.svg)
Fields
- name string? - An optional new name for the copied file. There are some restrictions to the file name. Names containing non-printable ASCII characters, forward and backward slashes (
/
,\
), and protected names like.
and..
are automatically sanitized by removing the non-allowed characters. MISSING[`]
- 'version string? - An optional ID of the specific file version to copy.
- parent FilesfileIdcopyParent - The destination folder to copy the file to.
box: FileIdUploadSessionsBody![](/images/permalink.svg)
Fields
- file_size int - The total number of bytes of the file to be uploaded
- file_name string? - The optional new name of new file
box: FileIdWatermarkBody![](/images/permalink.svg)
Fields
- watermark FilesfileIdwatermarkWatermark - The watermark to imprint on the file
box: FileMini![](/images/permalink.svg)
A mini representation of a file, used when nested under another resource.
Fields
- Fields Included from *FileBase
- sequence_id record {}? -
- name string? - The name of the file
- sha1 string? - The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file.
- file_version record {}? -
box: FileRequest![](/images/permalink.svg)
A standard representation of a file request, as returned from any file request API endpoints by default.
Fields
- id string? - The unique identifier for this file request.
- 'type string? -
file-request
- title string? - The title of file request. This is shown in the Box UI to users uploading files. This defaults to title of the file request that was copied to create this file request.
- description string? - The optional description of this file request. This is shown in the Box UI to users uploading files. This defaults to description of the file request that was copied to create this file request.
- status string? - The status of the file request. This defaults to
active
. When the status is set toinactive
, the file request will no longer accept new submissions, and any visitor to the file request URL will receive aHTTP 404
status code. This defaults to status of file request that was copied to create this file request.
- is_email_required boolean? - Whether a file request submitter is required to provide their email address. When this setting is set to true, the Box UI will show an email field on the file request form. This defaults to setting of file request that was copied to create this file request.
- is_description_required boolean? - Whether a file request submitter is required to provide a description of the files they are submitting. When this setting is set to true, the Box UI will show a description field on the file request form. This defaults to setting of file request that was copied to create this file request.
- expires_at string? - The date after which a file request will no longer accept new submissions. After this date, the
status
will automatically be set toinactive
.
- folder FolderMini? - A mini representation of a file version, used when nested under another resource.
- url string? - The generated URL for this file request. This URL can be shared with users to let them upload files to the associated folder.
- etag string? - The HTTP
etag
of this file. This can be used in combination with theIf-Match
header when updating a file request. By providing that header, a change will only be performed on the file request if theetag
on the file request still matches theetag
provided in theIf-Match
header.
- created_by UserMini? - A mini representation of a user, as can be returned when nested within other resources.
- created_at string? - The date and time when the file request was created.
- updated_by UserMini? - A mini representation of a user, as can be returned when nested within other resources.
- updated_at string? - The date and time when the file request was last updated.
box: FileRequestCopyRequest![](/images/permalink.svg)
The request body to copy a file request.
Fields
- Fields Included from *FileRequestUpdateRequest
- folder FilerequestcopyrequestFolder? - The folder to associate the new file request to.
box: FilerequestcopyrequestFolder![](/images/permalink.svg)
The folder to associate the new file request to.
Fields
- 'type string? -
folder
- id string - The ID of the folder to associate the new file request to.
box: FileRequestUpdateRequest![](/images/permalink.svg)
The request body to update a file request.
Fields
- title string? - An optional new title for the file request. This can be used to change the title of the file request. This will default to the value on the existing file request.
- description string? - An optional new description for the file request. This can be used to change the description of the file request. This will default to the value on the existing file request.
- status string? - An optional new status of the file request. When the status is set to
inactive
, the file request will no longer accept new submissions, and any visitor to the file request URL will receive aHTTP 404
status code. This will default to the value on the existing file request.
- is_email_required boolean? - Whether a file request submitter is required to provide their email address. When this setting is set to true, the Box UI will show an email field on the file request form. This will default to the value on the existing file request.
- is_description_required boolean? - Whether a file request submitter is required to provide a description of the files they are submitting. When this setting is set to true, the Box UI will show a description field on the file request form. This will default to the value on the existing file request.
- expires_at string? - The date after which a file request will no longer accept new submissions. After this date, the
status
will automatically be set toinactive
. This will default to the value on the existing file request.
box: Files![](/images/permalink.svg)
A list of files
Fields
- total_count int? - The number of files.
- entries File[]? - A list of files
box: FilescontentAttributes![](/images/permalink.svg)
The additional attributes of the file being uploaded. Mainly the name and the parent folder. These attributes are part of the multi part request body and are in JSON format. 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.
Fields
- name string - The name of the file
- parent FilescontentAttributesParent - The parent folder to upload the file to
- content_created_at string? - Defines the time the file was originally created at. If not set, the upload time will be used.
- content_modified_at string? - Defines the time the file was last modified at. If not set, the upload time will be used.
box: FilescontentAttributesParent![](/images/permalink.svg)
The parent folder to upload the file to
Fields
- id string - The id of the parent folder. Use
0
for the user's root folder.
box: FilesContentBody![](/images/permalink.svg)
Fields
- attributes FilescontentAttributes - The additional attributes of the file being uploaded. Mainly the name and the parent folder. These attributes are part of the multi part request body and are in JSON format. <Message warning> The
attributes
part of the body must come before thefile
part. Requests that do not follow this format when uploading the file will receive a HTTP400
error with ametadata_after_file_contents
error code. </Message>
- file string - The content of the file to upload to Box. <Message warning> The
attributes
part of the body must come before thefile
part. Requests that do not follow this format when uploading the file will receive a HTTP400
error with ametadata_after_file_contents
error code. </Message>
box: FileScope![](/images/permalink.svg)
A relation between a file and the scopes for which the file can be accessed
Fields
- scope string? - The file scopes for the file access
- 'object FileMini? - A mini representation of a file, used when nested under another resource.
box: FilesFileIdaddSharedLinkBody![](/images/permalink.svg)
Fields
- shared_link FilesfileIdaddSharedLinkSharedLink? - The settings for the shared link to create on the file. Use an empty object (
{}
) to use the default settings for shared links.
box: FilesfileIdaddSharedLinkSharedLink![](/images/permalink.svg)
The settings for the shared link to create on the file. Use an empty object ({}
) to use the default settings for shared links.
Fields
- access string? - The level of access for the shared link. This can be restricted to anyone with the link (
open
), only people within the company (company
) and only those who have been invited to the file (collaborators
). If not set, this field defaults to the access level specified by the enterprise admin. To create a shared link with this default setting pass theshared_link
object with noaccess
field, for example{ "shared_link": {} }
. Thecompany
access level is only available to paid accounts.
- password string? - The password required to access the shared link. Set the password to
null
to remove it. A password can only be set whenaccess
is set toopen
.
- vanity_name string? - Defines a custom vanity name to use in the shared link URL, for example
https://app.box.com/v/my-shared-link
. Custom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links.
- unshared_at string? - The timestamp at which this shared link will expire. This field can only be set by users with paid accounts. The value must be greater than the current date and time.
- permissions FilesfileIdaddSharedLinkSharedLinkPermissions? - The permissions on shared link.
box: FilesfileIdaddSharedLinkSharedLinkPermissions![](/images/permalink.svg)
The permissions on shared link.
Fields
- can_download boolean? - If the shared link allows for downloading of files. This can only be set when
access
is set toopen
orcompany
.
box: FilesFileIdBody![](/images/permalink.svg)
Fields
- name string? - An optional different name for the file. This can be used to rename the file.
- description string? - The description for a file. This can be seen in the right-hand sidebar panel when viewing a file in the Box web app. Additionally, this index is used in the search index of the file, allowing users to find the file by the content in the description.
- parent FilesfileIdParent? - The parent for this item
- shared_link FilesfileIdSharedLink? - Defines a shared link for an item. Set this to
null
to remove the shared link.
- 'lock FilesfileIdLock? - Defines a lock on an item. This prevents the item from being moved, renamed, or otherwise changed by anyone other than the user who created the lock. Set this to
null
to remove the lock.
- permissions FilesfileIdPermissions? - Defines who can download a file.
- tags string[]? - The tags for this item. These tags are shown in the Box web app and mobile apps next to an item. To add or remove a tag, retrieve the item's current tags, modify them, and then update this field. There is a limit of 100 tags per item, and 10,000 unique tags per enterprise.
box: FilesFileIdBody1![](/images/permalink.svg)
Fields
- name string? - An optional new name for the file.
- parent FilesfileIdParent? - The parent for this item
box: FilesfileIdcontentAttributes![](/images/permalink.svg)
The additional attributes of the file being uploaded. Mainly the name and the parent folder. These attributes are part of the multi part request body and are in JSON format. 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.
Fields
- name string - An optional new name for the file. If specified, the file will be renamed when the new version is uploaded.
- content_modified_at string? - Defines the time the file was last modified at. If not set, the upload time will be used.
box: FilesfileIdcopyParent![](/images/permalink.svg)
The destination folder to copy the file to.
Fields
- id string - The ID of folder to copy the file to.
box: FilesfileIdLock![](/images/permalink.svg)
Defines a lock on an item. This prevents the item from being moved, renamed, or otherwise changed by anyone other than the user who created the lock. Set this to null
to remove the lock.
Fields
- access string? - The type of this object.
- expires_at string? - Defines the time at which the lock expires.
- is_download_prevented boolean? - Defines if the file can be downloaded while it is locked.
box: FilesfileIdParent![](/images/permalink.svg)
The parent for this item
Fields
- id string? - The ID of parent item
box: FilesfileIdPermissions![](/images/permalink.svg)
Defines who can download a file.
Fields
- can_download string? - Defines who is allowed to download this file. The possible values are either
open
for everyone orcompany
for the other members of the user's enterprise. This setting overrides the download permissions that are normally part of therole
of a collaboration. When set tocompany
, this essentially removes the download option for external users withviewer
oreditor
a roles.
box: FilesFileIdremoveSharedLinkBody![](/images/permalink.svg)
Fields
- shared_link record {}? - By setting this value to
null
, the shared link is removed from the file.
box: FilesfileIdSharedLink![](/images/permalink.svg)
Defines a shared link for an item. Set this to null
to remove the shared link.
Fields
- access string? - The level of access for the shared link. This can be restricted to anyone with the link (
open
), only people within the company (company
) and only those who have been invited to the folder (collaborators
). If not set, this field defaults to the access level specified by the enterprise admin. To create a shared link with this default setting pass theshared_link
object with noaccess
field, for example{ "shared_link": {} }
. Thecompany
access level is only available to paid accounts.
- password string? - The password required to access the shared link. Set the password to
null
to remove it. A password can only be set whenaccess
is set toopen
.
- vanity_name string? - Defines a custom vanity name to use in the shared link URL, for example
https://app.box.com/v/my-shared-link
. Custom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links.
- unshared_at string? - The timestamp at which this shared link will expire. This field can only be set by users with paid accounts.
- permissions FilesfileIdSharedLinkPermissions? - The permissions for the shared link.
box: FilesfileIdSharedLinkPermissions![](/images/permalink.svg)
The permissions for the shared link.
Fields
- can_download boolean? - If the shared link allows for downloading of files. This can only be set when
access
is set toopen
orcompany
.
box: FilesFileIdupdateSharedLinkBody![](/images/permalink.svg)
Fields
- shared_link FilesfileIdupdateSharedLinkSharedLink? - The settings for the shared link to update.
box: FilesfileIdupdateSharedLinkSharedLink![](/images/permalink.svg)
The settings for the shared link to update.
Fields
- access string? - The level of access for the shared link. This can be restricted to anyone with the link (
open
), only people within the company (company
) and only those who have been invited to the folder (collaborators
). If not set, this field defaults to the access level specified by the enterprise admin. To create a shared link with this default setting pass theshared_link
object with noaccess
field, for example{ "shared_link": {} }
. Thecompany
access level is only available to paid accounts.
- password string? - The password required to access the shared link. Set the password to
null
to remove it. A password can only be set whenaccess
is set toopen
.
- vanity_name string? - Defines a custom vanity name to use in the shared link URL, for example
https://app.box.com/v/my-shared-link
. Custom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links.
- unshared_at string? - The timestamp at which this shared link will expire. This field can only be set by users with paid accounts. The value must be greater than the current date and time.
- permissions FilesfileIdaddSharedLinkSharedLinkPermissions? - The permissions on shared link.
box: FilesfileIdwatermarkWatermark![](/images/permalink.svg)
The watermark to imprint on the file
Fields
- imprint string - The type of watermark to apply. Currently only supports one option.
box: FilesUploadSessionsBody![](/images/permalink.svg)
Fields
- folder_id string - The ID of the folder to upload the new file to.
- file_size int - The total number of bytes of the file to be uploaded
- file_name string - The name of new file
box: FileVersion![](/images/permalink.svg)
A standard representation of a file version
Fields
- Fields Included from *FileversionMini
- name string? - The name of the file version
- size int? - Size of the file version in bytes
- created_at string? - When the file version object was created
- modified_at string? - When the file version object was last updated
- modified_by record {}? -
- trashed_at string? - When the file version object was trashed.
- trashed_by record {}? -
- restored_at string? - When the file version was restored from the trash.
- restored_by record {}? -
- purged_at string? - When the file version object will be permanently deleted.
- uploader_display_name record {}? -
box: FileversionBase![](/images/permalink.svg)
The bare basic representation of a file version, the minimal amount of fields returned when using the fields
query parameter.
Fields
- id string? - The unique identifier that represent a file version.
- 'type string? -
file_version
box: FileVersionLegalHold![](/images/permalink.svg)
File-Version-Legal-Hold is an entity representing all holds on a File Version.
Fields
- id string? - The unique identifier for this file version legal hold
- 'type string? -
file_version_legal_hold
- file_version FileversionMini? - A mini representation of a file version, used when nested within another resource.
- file FileMini? - A mini representation of a file, used when nested under another resource.
- legal_hold_policy_assignments LegalHoldPolicyAssignment[]? - List of assignments contributing to this Hold.
- deleted_at string? - Time that this File-Version-Legal-Hold was deleted.
box: FileVersionLegalHolds![](/images/permalink.svg)
A list of file version legal holds.
Fields
- 'limit int? - The limit that was used for these entries. This will be the same as the
limit
query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.
- next_marker int? - The marker for the start of the next page of results.
- prev_marker int? - The marker for the start of the previous page of results.
- entries FileVersionLegalHold[]? -
box: FileversionMini![](/images/permalink.svg)
A mini representation of a file version, used when nested within another resource.
Fields
- Fields Included from *FileversionBase
- sha1 string? - The SHA1 hash of this version of the file.
box: FileVersionRetention![](/images/permalink.svg)
A retention policy blocks permanent deletion of content for a specified amount of time. Admins can apply policies to specified folders, or an entire enterprise. A file version retention is a record for a retained file version. To use this feature, you must have the manage retention policies scope enabled for your API key via your application management console. For more information about retention policies, please visit our help documentation
Fields
- id string? - The unique identifier for this file version retention.
- 'type string? -
file_version_retention
- file_version FileversionMini? - A mini representation of a file version, used when nested within another resource.
- file FileMini? - A mini representation of a file, used when nested under another resource.
- applied_at string? - When this file version retention object was created
- disposition_at string? - When the retention expires on this file version retention
- winning_retention_policy RetentionpolicyMini? - A mini representation of a retention policy, used when nested within another resource.
box: FileVersionRetentions![](/images/permalink.svg)
A list of file version retentions.
Fields
- 'limit int? - The limit that was used for these entries. This will be the same as the
limit
query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.
- next_marker int? - The marker for the start of the next page of results.
- prev_marker int? - The marker for the start of the previous page of results.
- entries FileVersionRetention[]? -
box: FileVersions![](/images/permalink.svg)
A list of file versions
Fields
- total_count int? - One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than
total_count
. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.
- 'limit int? - The limit that was used for these entries. This will be the same as the
limit
query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.
- offset int? - The 0-based offset of the first entry in this set. This will be the same as the
offset
query parameter. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.
- 'order CollaborationsOrder[]? - The order by which items are returned. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.
- entries FileVersion[]? -
box: Folder![](/images/permalink.svg)
A standard representation of a folder, as returned from any folder API endpoints by default
Fields
- Fields Included from *FolderMini
- created_at string? - The date and time when the folder was created. This value may be
null
for some folders such as the root folder or the trash folder.
- modified_at string? - The date and time when the folder was last updated. This value may be
null
for some folders such as the root folder or the trash folder.
- description record {}? -
- size int? - The folder size in bytes. Be careful parsing this integer as its value can get very large.
- path_collection record { total_count int, entries FolderMini[] }? -
- created_by record {}? -
- modified_by record {}? -
- trashed_at string? - The time at which this folder was put in the trash.
- purged_at string? - The time at which this folder is expected to be purged from the trash.
- content_created_at string? - The date and time at which this folder was originally created.
- content_modified_at string? - The date and time at which this folder was last updated.
- expires_at string? - The time and which the folder will be automatically be deleted.
- owned_by record {}? -
- shared_link record { url string, download_url string?, vanity_url string?, vanity_name string?, access string, effective_access string, effective_permission string, unshared_at string?, is_password_enabled boolean, permissions record { can_download boolean, can_preview boolean }, download_count int, preview_count int }? -
- folder_upload_email FolderFolderUploadEmail? -
- parent record {}? -
- item_status string? - Defines if this item has been deleted or not. *
active
when the item has is not in the trash *trashed
when the item has been moved to the trash but not deleted *deleted
when the item has been permanently deleted.
- item_collection record {}? -
box: FolderBase![](/images/permalink.svg)
The bare basic representation of a folder, the minimal amount of fields returned when using the fields
query parameter.
Fields
- id string? - The unique identifier that represent a folder. The ID for any folder can be determined by visiting a folder in the web application and copying the ID from the URL. For example, for the URL
https://*.app.box.com/folders/123
thefolder_id
is123
.
- etag string? - The HTTP
etag
of this folder. This can be used within some API endpoints in theIf-Match
andIf-None-Match
headers to only perform changes on the folder if (no) changes have happened.
- 'type string? -
folder
box: FolderFolderUploadEmail![](/images/permalink.svg)
Fields
- access string? - When this parameter has been set, users can email files to the email address that has been automatically created for this folder. To create an email address, set this property either when creating or updating the folder. When set to
collaborators
, only emails from registered email addresses for collaborators will be accepted. This includes any email aliases a user might have registered. When set toopen
it will accept emails from any email address.
- email string? - The optional upload email address for this folder.
box: FolderFull![](/images/permalink.svg)
A full representation of a folder, as can be returned from any folder API endpoints by default
Fields
- Fields Included from *Folder
- created_at string|()
- modified_at string|()
- description record { anydata... }
- size int
- path_collection record { total_count int, entries FolderMini[], anydata... }
- created_by record { name string, login string, id string, type string, anydata... }
- modified_by record { name string, login string, id string, type string, anydata... }
- trashed_at string|()
- purged_at string|()
- content_created_at string|()
- content_modified_at string|()
- expires_at string|()
- owned_by record { name string, login string, id string, type string, anydata... }
- shared_link record { url string, download_url string|(), vanity_url string|(), vanity_name string|(), access string, effective_access string, effective_permission string, unshared_at string|(), is_password_enabled boolean, permissions record { can_download boolean, can_preview boolean, anydata... }, download_count int, preview_count int, anydata... }
- folder_upload_email FolderFolderUploadEmail|()
- parent record { sequence_id record { anydata... }, name string, id string, etag string|(), type string, anydata... }
- item_status string
- item_collection record { total_count int, limit int, offset int, order CollaborationsOrder[], entries FileMini|FolderMini|WeblinkMini[], anydata... }
- sequence_id record { anydata... }
- name string
- id string
- etag string|()
- type string
- anydata...
- sync_state record {}? -
- has_collaborations boolean? - Specifies if this folder has any other collaborators.
- tags record {}? -
- can_non_owners_invite record {}? -
- is_externally_owned boolean? - Specifies if this folder is owned by a user outside of the authenticated enterprise.
- metadata record {}? -
- is_collaboration_restricted_to_enterprise record {}? -
- allowed_shared_link_access_levels string[]? - A list of access levels that are available for this folder. For some folders, like the root folder, this will always be an empty list as sharing is not allowed at that level.
- allowed_invitee_roles string[]? - A list of the types of roles that user can be invited at when sharing this folder.
- watermark_info record { is_watermarked boolean }? -
- can_non_owners_view_collaborators boolean? - Specifies if collaborators who are not owners of this folder are restricted from viewing other collaborations on this folder. It also restricts non-owners from inviting new collaborators.
box: FolderIdCopyBody![](/images/permalink.svg)
Fields
- name string? - An optional new name for the copied folder. There are some restrictions to the file name. Names containing non-printable ASCII characters, forward and backward slashes (
/
,\
), as well as names with trailing spaces are prohibited. Additionally, the names.
and..
are not allowed either. MISSING[`]
- parent FoldersfolderIdcopyParent - The destination folder to copy the folder to.
box: FolderIdWatermarkBody![](/images/permalink.svg)
Fields
- watermark FoldersfolderIdwatermarkWatermark - The watermark to imprint on the folder
box: FolderLock![](/images/permalink.svg)
Folder locks define access restrictions placed by folder owners to prevent specific folders from being moved or deleted.
Fields
- folder FolderMini? - A mini representation of a file version, used when nested under another resource.
- id string? - The unique identifier for this folder lock.
- 'type string? - The object type, always
folder_lock
.
- created_by UserBase? - A mini representation of a user, used when nested within another resource.
- created_at string? - When the folder lock object was created.
- locked_operations FolderlockLockedOperations? - The operations that have been locked. Currently the
move
anddelete
operations cannot be locked separately, and both need to be set totrue
.
- lock_type string? - The lock type, always
freeze
.
box: FolderlockLockedOperations![](/images/permalink.svg)
The operations that have been locked. Currently the move
and delete
operations cannot be locked separately, and both need to be set to true
.
Fields
- move boolean? - Whether moving the folder is restricted.
- delete boolean? - Whether deleting the folder is restricted.
box: FolderLocks![](/images/permalink.svg)
A list of folder locks
Fields
- 'limit int? - The limit that was used for these entries. This will be the same as the
limit
query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.
- next_marker int? - The marker for the start of the next page of results.
- prev_marker int? - The marker for the start of the previous page of results.
- entries FolderLock[]? -
box: FolderLocksBody![](/images/permalink.svg)
Fields
- locked_operations FolderLocksLockedOperations? - The operations to lock for the folder. If
locked_operations
is included in the request, bothmove
anddelete
must also be included and both set totrue
.
- folder FolderLocksFolder - The folder to apply the lock to.
box: FolderLocksFolder![](/images/permalink.svg)
The folder to apply the lock to.
Fields
- 'type string - The content type the lock is being applied to. Only
folder
is supported.
- id string - The ID of the folder.
box: FolderLocksLockedOperations![](/images/permalink.svg)
The operations to lock for the folder. If locked_operations
is included in the request, both move
and delete
must also be included and both set to true
.
Fields
- move boolean - Whether moving the folder should be locked.
- delete boolean - Whether deleting the folder should be locked.
box: FolderMini![](/images/permalink.svg)
A mini representation of a file version, used when nested under another resource.
Fields
- Fields Included from *FolderBase
- sequence_id record {}? -
- name string? - The name of the folder.
box: Folders0Body![](/images/permalink.svg)
Fields
- owned_by UsersuserIdfolders0OwnedBy - The user who the folder will be transferred to
box: FoldersBody![](/images/permalink.svg)
Fields
- name string - The name for the new folder. There are some restrictions to the file name. Names containing non-printable ASCII characters, forward and backward slashes (
/
,\
), as well as names with trailing spaces are prohibited. Additionally, the names.
and..
are not allowed either. MISSING[`]
- parent FoldersParent - The parent folder to create the new folder within.
- folder_upload_email record { access string }? -
- sync_state string? - Specifies whether a folder should be synced to a user's device or not. This is used by Box Sync (discontinued) and is not used by Box Drive.
box: FoldersFolderIdaddSharedLinkBody![](/images/permalink.svg)
Fields
- shared_link FoldersfolderIdaddSharedLinkSharedLink? - The settings for the shared link to create on the folder. Use an empty object (
{}
) to use the default settings for shared links.
box: FoldersfolderIdaddSharedLinkSharedLink![](/images/permalink.svg)
The settings for the shared link to create on the folder. Use an empty object ({}
) to use the default settings for shared links.
Fields
- access string? - The level of access for the shared link. This can be restricted to anyone with the link (
open
), only people within the company (company
) and only those who have been invited to the folder (collaborators
). If not set, this field defaults to the access level specified by the enterprise admin. To create a shared link with this default setting pass theshared_link
object with noaccess
field, for example{ "shared_link": {} }
. Thecompany
access level is only available to paid accounts.
- password string? - The password required to access the shared link. Set the password to
null
to remove it. A password can only be set whenaccess
is set toopen
.
- unshared_at string? - The timestamp at which this shared link will expire. This field can only be set by users with paid accounts. The value must be greater than the current date and time.
- permissions FoldersfolderIdaddSharedLinkSharedLinkPermissions? - The permissions on shared link.
box: FoldersfolderIdaddSharedLinkSharedLinkPermissions![](/images/permalink.svg)
The permissions on shared link.
Fields
- can_download boolean? - If the shared link allows for downloading of folders. This can only be set when
access
is set toopen
orcompany
.
box: FoldersFolderIdBody![](/images/permalink.svg)
Fields
- name string? - The optional new name for this folder.
- description string? - The optional description of this folder
- sync_state string? - Specifies whether a folder should be synced to a user's device or not. This is used by Box Sync (discontinued) and is not used by Box Drive.
- can_non_owners_invite boolean? - Specifies if users who are not the owner of the folder can invite new collaborators to the folder.
- parent FoldersfolderIdParent? - The parent folder for this folder. Use this to move the folder or to restore it out of the trash.
- folder_upload_email record { access string }? -
- tags string[]? - The tags for this item. These tags are shown in the Box web app and mobile apps next to an item. To add or remove a tag, retrieve the item's current tags, modify them, and then update this field. There is a limit of 100 tags per item, and 10,000 unique tags per enterprise.
- is_collaboration_restricted_to_enterprise boolean? - Specifies if new invites to this folder are restricted to users within the enterprise. This does not affect existing collaborations.
- collections Reference[]? - An array of collections to make this folder a member of. Currently we only support the
favorites
collection. To get the ID for a collection, use the [List all collections][1] endpoint. Passing an empty array[]
ornull
will remove the folder from all collections. [1]: ../advanced-files-and-folders/#get-collections
- can_non_owners_view_collaborators boolean? - Restricts collaborators who are not the owner of this folder from viewing other collaborations on this folder. It also restricts non-owners from inviting new collaborators. When setting this field to
false
, it is required to also setcan_non_owners_invite_collaborators
tofalse
if it has not already been set.
box: FoldersFolderIdBody1![](/images/permalink.svg)
Fields
- name string? - An optional new name for the folder.
- parent record { id string }? -
box: FoldersfolderIdcopyParent![](/images/permalink.svg)
The destination folder to copy the folder to.
Fields
- id string - The ID of parent folder
box: FoldersfolderIdParent![](/images/permalink.svg)
The parent folder for this folder. Use this to move the folder or to restore it out of the trash.
Fields
- id string? - The ID of the new parent folder
box: FoldersFolderIdremoveSharedLinkBody![](/images/permalink.svg)
Fields
- shared_link record {}? - By setting this value to
null
, the shared link is removed from the folder.
box: FoldersFolderIdupdateSharedLinkBody![](/images/permalink.svg)
Fields
- shared_link FoldersfolderIdupdateSharedLinkSharedLink? - The settings for the shared link to update.
box: FoldersfolderIdupdateSharedLinkSharedLink![](/images/permalink.svg)
The settings for the shared link to update.
Fields
- access string? - The level of access for the shared link. This can be restricted to anyone with the link (
open
), only people within the company (company
) and only those who have been invited to the folder (collaborators
). If not set, this field defaults to the access level specified by the enterprise admin. To create a shared link with this default setting pass theshared_link
object with noaccess
field, for example{ "shared_link": {} }
. Thecompany
access level is only available to paid accounts.
- password string? - The password required to access the shared link. Set the password to
null
to remove it. A password can only be set whenaccess
is set toopen
.
- unshared_at string? - The timestamp at which this shared link will expire. This field can only be set by users with paid accounts. The value must be greater than the current date and time.
- permissions FoldersfolderIdaddSharedLinkSharedLinkPermissions? - The permissions on shared link.
box: FoldersfolderIdwatermarkWatermark![](/images/permalink.svg)
The watermark to imprint on the folder
Fields
- imprint string - The type of watermark to apply. Currently only supports one option.
box: FoldersParent![](/images/permalink.svg)
The parent folder to create the new folder within.
Fields
- id string - The ID of parent folder
box: Group![](/images/permalink.svg)
A standard representation of a group, as returned from any group API endpoints by default
Fields
- Fields Included from *GroupMini
- created_at string? - When the group object was created
- modified_at string? - When the group object was last modified
box: GroupBase![](/images/permalink.svg)
A base representation of a group.
Fields
- id string? - The unique identifier for this object
- 'type string? -
group
box: GroupFull![](/images/permalink.svg)
Groups contain a set of users, and can be used in place of users in some operations, such as collaborations.
Fields
- Fields Included from *Group
- provenance string? - Keeps track of which external source this group is coming from (e.g. "Active Directory", "Google Groups", "Facebook Groups"). Setting this will also prevent Box users from editing the group name and its members directly via the Box web application. This is desirable for one-way syncing of groups.
- external_sync_identifier string? - An arbitrary identifier that can be used by external group sync tools to link this Box Group to an external group. Example values of this field could be an Active Directory Object ID or a Google Group ID. We recommend you use of this field in order to avoid issues when group names are updated in either Box or external systems.
- description string? - Human readable description of the group.
- invitability_level string? - Specifies who can invite the group to collaborate on items. When set to
admins_only
the enterprise admin, co-admins, and the group's admin can invite the group. When set toadmins_and_members
all the admins listed above and group members can invite the group. When set toall_managed_users
all managed users in the enterprise can invite the group.
- member_viewability_level string? - Specifies who can view the members of the group (Get Memberships for Group). *
admins_only
- the enterprise admin, co-admins, group's group admin *admins_and_members
- all admins and group members *all_managed_users
- all managed users in the enterprise
- permissions record { can_invite_as_collaborator boolean }? -
box: GroupMembership![](/images/permalink.svg)
Membership is used to signify that a user is part of a group.
Fields
- id string? - The unique identifier for this group membership
- 'type string? -
group_membership
- user UserMini? - A mini representation of a user, as can be returned when nested within other resources.
- 'group GroupMini? - Mini representation of a group, including id and name of group.
- role string? - The role of the user in the group.
- created_at string? - The time this membership was created.
- modified_at string? - The time this membership was last modified.
box: GroupMemberships![](/images/permalink.svg)
A list of group memberships.
Fields
- total_count int? - One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than
total_count
. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.
- 'limit int? - The limit that was used for these entries. This will be the same as the
limit
query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.
- offset int? - The 0-based offset of the first entry in this set. This will be the same as the
offset
query parameter. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.
- 'order CollaborationsOrder[]? - The order by which items are returned. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.
- entries GroupMembership[]? -
box: GroupMembershipsBody![](/images/permalink.svg)
Fields
- user GroupMembershipsUser - The user to add to the group.
- 'group GroupMembershipsGroup - The group to add the user to.
- role string? - The role of the user in the group.
- configurable_permissions record {}? - Custom configuration for the permissions an admin if a group will receive. This option has no effect on members with a role of
member
. Setting these permissions overwrites the default access levels of an admin. Specifying a value of "null" for this object will disable all configurable permissions. Specifying permissions will set them accordingly, omitted permissions will be enabled by default.
box: GroupMembershipsGroup![](/images/permalink.svg)
The group to add the user to.
Fields
- id string - The ID of the group to add the user to
box: GroupMembershipsGroupMembershipIdBody![](/images/permalink.svg)
Fields
- role string? - The role of the user in the group.
- configurable_permissions record {}? - Custom configuration for the permissions an admin if a group will receive. This option has no effect on members with a role of
member
. Setting these permissions overwrites the default access levels of an admin. Specifying a value of "null" for this object will disable all configurable permissions. Specifying permissions will set them accordingly, omitted permissions will be enabled by default.
box: GroupMembershipsUser![](/images/permalink.svg)
The user to add to the group.
Fields
- id string - The ID of the user to add to the group
box: GroupMini![](/images/permalink.svg)
Mini representation of a group, including id and name of group.
Fields
- Fields Included from *GroupBase
- name string? - The name of the group
- group_type string? - The type of the group.
box: Groups![](/images/permalink.svg)
A list of groups.
Fields
- total_count int? - One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than
total_count
. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.
- 'limit int? - The limit that was used for these entries. This will be the same as the
limit
query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.
- offset int? - The 0-based offset of the first entry in this set. This will be the same as the
offset
query parameter. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.
- 'order CollaborationsOrder[]? - The order by which items are returned. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.
- entries GroupMini[]? -
box: GroupsBody![](/images/permalink.svg)
Fields
- name string - The name of the new group to be created. This name must be unique within the enterprise.
- provenance string? - Keeps track of which external source this group is coming, for example
Active Directory
, orOkta
. Setting this will also prevent Box admins from editing the group name and its members directly via the Box web application. This is desirable for one-way syncing of groups.
- external_sync_identifier string? - An arbitrary identifier that can be used by external group sync tools to link this Box Group to an external group. Example values of this field could be an Active Directory Object ID or a Google Group ID. We recommend you use of this field in order to avoid issues when group names are updated in either Box or external systems.
- description string? - A human readable description of the group.
- invitability_level string? - Specifies who can invite the group to collaborate on folders. When set to
admins_only
the enterprise admin, co-admins, and the group's admin can invite the group. When set toadmins_and_members
all the admins listed above and group members can invite the group. When set toall_managed_users
all managed users in the enterprise can invite the group.
- member_viewability_level string? - Specifies who can see the members of the group. *
admins_only
- the enterprise admin, co-admins, group's group admin *admins_and_members
- all admins and group members *all_managed_users
- all managed users in the enterprise
box: GroupsGroupIdBody![](/images/permalink.svg)
Fields
- name string? - The name of the new group to be created. Must be unique within the enterprise.
- provenance string? - Keeps track of which external source this group is coming, for example
Active Directory
, orOkta
. Setting this will also prevent Box admins from editing the group name and its members directly via the Box web application. This is desirable for one-way syncing of groups.
- external_sync_identifier string? - An arbitrary identifier that can be used by external group sync tools to link this Box Group to an external group. Example values of this field could be an Active Directory Object ID or a Google Group ID. We recommend you use of this field in order to avoid issues when group names are updated in either Box or external systems.
- description string? - A human readable description of the group.
- invitability_level string? - Specifies who can invite the group to collaborate on folders. When set to
admins_only
the enterprise admin, co-admins, and the group's admin can invite the group. When set toadmins_and_members
all the admins listed above and group members can invite the group. When set toall_managed_users
all managed users in the enterprise can invite the group.
- member_viewability_level string? - Specifies who can see the members of the group. *
admins_only
- the enterprise admin, co-admins, group's group admin *admins_and_members
- all admins and group members *all_managed_users
- all managed users in the enterprise
box: Invite![](/images/permalink.svg)
An invite for a user to an enterprise.
Fields
- id string? - The unique identifier for this invite
- 'type string? -
invite
- invited_to Enterprise? - A representation of a Box enterprise
- actionable_by UserMini? - A mini representation of a user, as can be returned when nested within other resources.
- invited_by UserMini? - A mini representation of a user, as can be returned when nested within other resources.
- status string? - The status of the invite
- created_at string? - When the invite was created
- modified_at string? - When the invite was modified.
box: InvitesActionableBy![](/images/permalink.svg)
The user to invite
Fields
- login string? - The login of the invited user
box: InvitesBody![](/images/permalink.svg)
Fields
- enterprise InvitesEnterprise - The enterprise to invite the user to
- actionable_by InvitesActionableBy - The user to invite
box: InvitesEnterprise![](/images/permalink.svg)
The enterprise to invite the user to
Fields
- id string - The ID of the enterprise
box: Items![](/images/permalink.svg)
A list of files, folders, and web links in their mini representation.
Fields
- total_count int? - One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than
total_count
. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.
- 'limit int? - The limit that was used for these entries. This will be the same as the
limit
query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.
- offset int? - The 0-based offset of the first entry in this set. This will be the same as the
offset
query parameter. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.
- 'order CollaborationsOrder[]? - The order by which items are returned. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.
- entries (FileMini|FolderMini|WeblinkMini)[]? - The items in this collection.
box: KeywordSkillCard![](/images/permalink.svg)
A skill card that contains a set of keywords
Fields
- created_at string? - The optional date and time this card was created at.
- 'type string -
skill_card
- skill_card_type string -
keyword
- skill_card_title KeywordskillcardSkillCardTitle? - The title of the card.
- skill SkillcardSkill - The service that applied this metadata.
- invocation SkillcardInvocation - The invocation of this service, used to track which instance of a service applied the metadata.
- entries KeywordskillcardEntries[] - An list of entries in the metadata card.
box: KeywordskillcardEntries![](/images/permalink.svg)
An entry in the entries
attribute of a metadata card
Fields
- text string? - The text of the keyword.
box: KeywordskillcardSkillCardTitle![](/images/permalink.svg)
The title of the card.
Fields
- code string? - An optional identifier for the title.
- message string - The actual title to show in the UI.
box: LegalHoldPolicies![](/images/permalink.svg)
A list of legal hold policies.
Fields
- 'limit int? - The limit that was used for these entries. This will be the same as the
limit
query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.
- next_marker int? - The marker for the start of the next page of results.
- prev_marker int? - The marker for the start of the previous page of results.
- entries LegalHoldPolicy[]? -
box: LegalHoldPoliciesBody![](/images/permalink.svg)
Fields
- policy_name string - The name of the policy.
- description string? - A description for the policy.
- filter_started_at string? - The filter start date. When this policy is applied using a
custodian
legal hold assignments, it will only apply to file versions created or uploaded inside of the date range. Other assignment types, such as folders and files, will ignore the date filter. Required ifis_ongoing
is set tofalse
.
- filter_ended_at string? - The filter end date. When this policy is applied using a
custodian
legal hold assignments, it will only apply to file versions created or uploaded inside of the date range. Other assignment types, such as folders and files, will ignore the date filter. Required ifis_ongoing
is set tofalse
.
- is_ongoing boolean? - Whether new assignments under this policy should continue applying to files even after initialization. When this policy is applied using a legal hold assignment, it will continue applying the policy to any new file versions even after it has been applied. For example, if a legal hold assignment is placed on a user today, and that user uploads a file tomorrow, that file will get held. This will continue until the policy is retired. Required if no filter dates are set.
box: LegalHoldPoliciesLegalHoldPolicyIdBody![](/images/permalink.svg)
Fields
- policy_name string? - The name of the policy.
- description string? - A description for the policy.
- release_notes string? - Notes around why the policy was released.
box: LegalHoldPolicy![](/images/permalink.svg)
Legal Hold Policy information describes the basic characteristics of the Policy, such as name, description, and filter dates.
Fields
- Fields Included from *LegalholdpolicyMini
- policy_name string? - Name of the legal hold policy.
- description string? - Description of the legal hold policy. Optional property with a 500 character limit.
- status string? -
- 'active' - the policy is not in a transition state * 'applying' - that the policy is in the process of being applied * 'releasing' - that the process is in the process of being released * 'released' - the policy is no longer active
- assignment_counts LegalholdpolicyAssignmentCounts? - Counts of assignments within this a legal hold policy by item type
- created_by record {}? -
- created_at string? - When the legal hold policy object was created
- modified_at string? - When the legal hold policy object was modified. Does not update when assignments are added or removed.
- deleted_at string? - When the policy release request was sent. (Because it can take time for a policy to fully delete, this isn't quite the same time that the policy is fully deleted). If
null
, the policy was not deleted.
- filter_started_at string? - User-specified, optional date filter applies to Custodian assignments only
- filter_ended_at string? - User-specified, optional date filter applies to Custodian assignments only
- release_notes string? - Optional notes about why the policy was created.
box: LegalHoldPolicyAssignment![](/images/permalink.svg)
Legal Hold Assignments are used to assign Legal Hold Policies to Users, Folders, Files, or File Versions. Creating a Legal Hold Assignment puts a hold on the File-Versions that belong to the Assignment's 'apply-to' entity.
Fields
- Fields Included from *LegalholdpolicyassignmentBase
- legal_hold_policy record {}? -
- assigned_by record {}? -
- assigned_at string? - When the legal hold policy assignment object was created
- deleted_at string? - When the assignment release request was sent. (Because it can take time for an assignment to fully delete, this isn't quite the same time that the assignment is fully deleted). If null, Assignment was not deleted.
box: LegalholdpolicyassignmentBase![](/images/permalink.svg)
Legal Hold Assignments are used to assign Legal Hold Policies to Users, Folders, Files, or File Versions. Creating a Legal Hold Assignment puts a hold on the File-Versions that belong to the Assignment's 'apply-to' entity.
Fields
- id string? - The unique identifier for this legal hold assignment
- 'type string? -
legal_hold_policy_assignment
box: LegalholdpolicyAssignmentCounts![](/images/permalink.svg)
Counts of assignments within this a legal hold policy by item type
Fields
- user int? - The number of users this policy is applied to
- folder int? - The number of folders this policy is applied to
- file int? - The number of files this policy is applied to
- file_version int? - The number of file versions this policy is applied to
box: LegalHoldPolicyAssignments![](/images/permalink.svg)
A list of legal hold policies assignments.
Fields
- 'limit int? - The limit that was used for these entries. This will be the same as the
limit
query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.
- next_marker int? - The marker for the start of the next page of results.
- prev_marker int? - The marker for the start of the previous page of results.
- entries LegalholdpolicyassignmentBase[]? -
box: LegalHoldPolicyAssignmentsAssignTo![](/images/permalink.svg)
The item to assign the policy to
Fields
- 'type string - The type of item to assign the policy to
- id string - The ID of item to assign the policy to
box: LegalHoldPolicyAssignmentsBody![](/images/permalink.svg)
Fields
- policy_id string - The ID of the policy to assign.
- assign_to LegalHoldPolicyAssignmentsAssignTo - The item to assign the policy to
box: LegalholdpolicyMini![](/images/permalink.svg)
A mini legal hold policy
Fields
- id string? - The unique identifier for this legal hold policy
- 'type string? -
legal_hold_policy
box: NameconflictInner![](/images/permalink.svg)
A file or folder for which a conflict was encountered, This object provides the type and identifier of the original item, as well as a mapping between its original name and it's new name as it will appear in the archive.
Fields
- id string? - The identifier of the item
- 'type string? - The type of this item
- original_name string? - The original name of this item
- download_name string? - The new name of this item as it will appear in the downloaded
zip
archive.
box: OAuth2Error![](/images/permalink.svg)
An OAuth 2.0 error
Fields
- _error string? - The type of the error returned.
- error_description string? - The type of the error returned.
box: PostOAuth2Revoke![](/images/permalink.svg)
A request to revoke an OAuth 2.0 token
Fields
- client_id string? - The Client ID of the application requesting to revoke the access token.
- client_secret string? - The client secret of the application requesting to revoke an access token.
- token string? - The access token to revoke.
box: PostOAuth2Token![](/images/permalink.svg)
A request for a new OAuth 2.0 token
Fields
- grant_type string - The type of request being made, either using a client-side obtained authorization code, a refresh token, a JWT assertion, client credentials grant or another access token for the purpose of downscoping a token.
- client_id string? - The Client ID of the application requesting an access token. Used in combination with
authorization_code
,client_credentials
, orurn:ietf:params:oauth:grant-type:jwt-bearer
as thegrant_type
.
- client_secret string? - The client secret of the application requesting an access token. Used in combination with
authorization_code
,client_credentials
, orurn:ietf:params:oauth:grant-type:jwt-bearer
as thegrant_type
.
- code string? - The client-side authorization code passed to your application by Box in the browser redirect after the user has successfully granted your application permission to make API calls on their behalf. Used in combination with
authorization_code
as thegrant_type
.
- refresh_token string? - A refresh token used to get a new access token with. Used in combination with
refresh_token
as thegrant_type
.
- assertion string? - A JWT assertion for which to request a new access token. Used in combination with
urn:ietf:params:oauth:grant-type:jwt-bearer
as thegrant_type
.
- subject_token string? - The token to exchange for a downscoped token. This can be a regular access token, a JWT assertion, or an app token. Used in combination with
urn:ietf:params:oauth:grant-type:token-exchange
as thegrant_type
.
- subject_token_type string? - The type of
subject_token
passed in. Used in combination withurn:ietf:params:oauth:grant-type:token-exchange
as thegrant_type
.
- actor_token string? - The token used to create an annotator token. This is a JWT assertion. Used in combination with
urn:ietf:params:oauth:grant-type:token-exchange
as thegrant_type
.
- actor_token_type string? - The type of
actor_token
passed in. Used in combination withurn:ietf:params:oauth:grant-type:token-exchange
as thegrant_type
.
- scope string? - The space-delimited list of scopes that you want apply to the new access token. The
subject_token
will need to have all of these scopes or the call will error with 401 Unauthorized.
- 'resource string? - Full URL for the file that the token should be generated for.
- box_subject_type string? - Used in combination with
client_credentials
as thegrant_type
.
- box_subject_id string? - Used in combination with
client_credentials
as thegrant_type
. Value is determined bybox_subject_type
. Ifuser
use user ID and ifenterprise
use enterprise ID.
- box_shared_link string? - Full URL of the shared link on the file or folder that the token should be generated for.
box: Postoauth2tokenRefreshaccesstoken![](/images/permalink.svg)
A request to refresh an Access Token. Use this API to refresh an expired Access Token using a valid Refresh Token.
Fields
- grant_type string - The type of request being made, in this case a refresh request.
- client_id string - The client ID of the application requesting to refresh the token.
- client_secret string - The client secret of the application requesting to refresh the token.
- refresh_token string - The refresh token to refresh.
box: RealtimeServer![](/images/permalink.svg)
A real-time server that can be used for long polling user events
Fields
- 'type string? -
realtime_server
- url string? - The URL for the server.
- ttl int? - The time in minutes for which this server is available
- max_retries int? - The maximum number of retries this server will allow before a new long poll should be started by getting a new list of server.
- retry_timeout int? - The maximum number of seconds without a response after which you should retry the long poll connection. This helps to overcome network issues where the long poll looks to be working but no packages are coming through.
box: RealtimeServers![](/images/permalink.svg)
A list of real-time servers that can be used for long-polling.
Fields
- chunk_size int? - The number of items in this response.
- entries RealtimeServer[]? - The entries of realtime servers.
box: RecentItem![](/images/permalink.svg)
A recent item accessed by a user.
Fields
- 'type string? -
recent_item
- interaction_type string? - The most recent type of access the user performed on the item.
- interacted_at string? - The time of the most recent interaction.
- interaction_shared_link string? - If the item was accessed through a shared link it will appear here, otherwise this will be null.
box: RecentItems![](/images/permalink.svg)
A list of recent items.
Fields
- 'limit int? - The limit that was used for these entries. This will be the same as the
limit
query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.
- next_marker int? - The marker for the start of the next page of results.
- prev_marker int? - The marker for the start of the previous page of results.
- entries RecentItem[]? -
box: Reference![](/images/permalink.svg)
The bare basic reference for an object
Fields
- id string? - The unique identifier for this object
- 'type string? - The type for this object
box: RetentionPolicies![](/images/permalink.svg)
A list of retention policies
Fields
- total_count int? - The number of retention policies.
- entries RetentionPolicy[]? - The entries of retention policies.
box: RetentionPoliciesBody![](/images/permalink.svg)
Fields
- policy_name string - The name for the retention policy
- policy_type string - The type of the retention policy. A retention policy type can either be
finite
, where a specific amount of time to retain the content is known upfront, orindefinite
, where the amount of time to retain the content is still unknown.
- disposition_action string - The disposition action of the retention policy. This action can be
permanently_delete
, which will cause the content retained by the policy to be permanently deleted, orremove_retention
, which will lift the retention policy from the content, allowing it to be deleted by users, once the retention policy has expired.
- retention_length string? - The length of the retention policy. This length specifies the duration in days that the retention policy will be active for after being assigned to content. If the policy has A
policy_type
ofindefinite
, theretention_length
will also beindefinite
.
- can_owner_extend_retention boolean? - Whether the owner of a file will be allowed to extend the retention.
- are_owners_notified boolean? - Whether owner and co-owners of a file are notified when the policy nears expiration.
- custom_notification_recipients RetentionPoliciesCustomNotificationRecipients[]? -
box: RetentionPoliciesCustomNotificationRecipients![](/images/permalink.svg)
A user that is notified of an event.
Fields
- 'type string? - The type of item to notify
- id string? - The id of the user to notify
- name string? - The name of the user to notify
- login string? - The email address the user uses to notify
box: RetentionPoliciesRetentionPolicyIdBody![](/images/permalink.svg)
Fields
- policy_name string? - The name for the retention policy
- disposition_action string? - The disposition action of the retention policy. This action can be
permanently_delete
, which will cause the content retained by the policy to be permanently deleted, orremove_retention
, which will lift the retention policy from the content, allowing it to be deleted by users, once the retention policy has expired.
- status string? - Used to retire a retention policy. If not retiring a policy, do not include this parameter or set it to
null
.
box: RetentionPolicy![](/images/permalink.svg)
A retention policy blocks permanent deletion of content for a specified amount of time. Admins can create retention policies and then later assign them to specific folders or their entire enterprise. To use this feature, you must have the manage retention policies scope enabled for your API key via your application management console.
Fields
- Fields Included from *RetentionpolicyMini
- policy_type string? - The type of the retention policy. A retention policy type can either be
finite
, where a specific amount of time to retain the content is known upfront, orindefinite
, where the amount of time to retain the content is still unknown.
- status string? - The status of the retention policy. The status of a policy will be
active
, unless explicitly retired by an administrator, in which case the status will beretired
. Once a policy has been retired, it cannot become active again.
- created_by record {}? -
- created_at string? - When the retention policy object was created
- modified_at string? - When the retention policy object was last modified
box: RetentionPolicyAssignment![](/images/permalink.svg)
The retention policy assignment endpoint provides a way for admins to apply a retention policy on a per-folder basis, or place a blanket policy over the entire enterprise.
Fields
- id string? - The unique identifier for this retention policy assignment
- 'type string? -
retention_policy_assignment
- retention_policy RetentionpolicyMini? - A mini representation of a retention policy, used when nested within another resource.
- assigned_to Reference? - The bare basic reference for an object
- assigned_by UserMini? - A mini representation of a user, as can be returned when nested within other resources.
- assigned_at string? - When the retention policy assignment object was created
box: RetentionPolicyAssignments![](/images/permalink.svg)
A list of retention policy assignments
Fields
- 'limit int? - The limit that was used for these entries. This will be the same as the
limit
query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.
- next_marker int? - The marker for the start of the next page of results.
- prev_marker int? - The marker for the start of the previous page of results.
- entries RetentionPolicyAssignment[]? -
box: RetentionPolicyAssignmentsAssignTo![](/images/permalink.svg)
The item to assign the policy to
Fields
- 'type string - The type of item to assign the policy to.
- id string - The ID of item to assign the policy to. Set to
null
or omit whentype
is set toenterprise
.
box: RetentionPolicyAssignmentsBody![](/images/permalink.svg)
Fields
- policy_id string - The ID of the retention policy to assign
- assign_to RetentionPolicyAssignmentsAssignTo - The item to assign the policy to
box: RetentionpolicyBase![](/images/permalink.svg)
The bare basic representation of a file version, the minimal amount of fields returned when using the fields
query parameter.
Fields
- id string? - The unique identifier that represent a file version.
- 'type string? -
retention_policy
box: RetentionpolicyMini![](/images/permalink.svg)
A mini representation of a retention policy, used when nested within another resource.
Fields
- Fields Included from *RetentionpolicyBase
- policy_name string? - The name given to the retention policy
- retention_length string? - The length of the retention policy. This length specifies the duration in days that the retention policy will be active for after being assigned to content. If the policy has A
policy_type
ofindefinite
, theretention_length
will also beindefinite
.
- disposition_action string? - The disposition action of the retention policy. This action can be
permanently_delete
, which will cause the content retained by the policy to be permanently deleted, orremove_retention
, which will lift the retention policy from the content, allowing it to be deleted by users, once the retention policy has expired.
box: SearchResults![](/images/permalink.svg)
A list of files, folders and web links that matched the search query.
Fields
- total_count int? - One greater than the offset of the last entry in the search results. The total number of entries in the collection may be less than
total_count
.
- 'limit int? - The limit that was used for this search. This will be the same as the
limit
query parameter unless that value exceeded the maximum value allowed.
- offset int? - The 0-based offset of the first entry in this set. This will be the same as the
offset
query parameter used.
box: SearchResultsWithSharedLinks![](/images/permalink.svg)
A list of files, folders and web links that matched the search query, including the additional information about any shared links through which the item has been shared with the user. This response format is only returned when the include_recent_shared_links
query parameter has been set to true
.
Fields
- total_count int? - One greater than the offset of the last entry in the search results. The total number of entries in the collection may be less than
total_count
.
- 'limit int? - The limit that was used for this search. This will be the same as the
limit
query parameter unless that value exceeded the maximum value allowed.
- offset int? - The 0-based offset of the first entry in this set. This will be the same as the
offset
query parameter used.
- entries SearchResultWithSharedLink[]? - The search results for the query provided, including the additional information about any shared links through which the item has been shared with the user.
box: SearchResultWithSharedLink![](/images/permalink.svg)
A single of files, folder or web link that matched the search query, including the additional information about the shared link through which the item has been shared with the user. This response format is only returned when the include_recent_shared_links
query parameter has been set to true
.
Fields
- accessible_via_shared_link string? - The optional shared link through which the user has access to this item. This value is only returned for items for which the user has recently accessed the file through a shared link. For all other items this value will return
null
.
- 'type string? - The result type. The value is always
search_result
.
box: SessionEndpoint![](/images/permalink.svg)
Session endpoints.
Fields
- upload_part string? - The URL to upload parts to
- 'commit string? - The URL used to commit the file
- 'abort string? - The URL for used to abort the session.
- list_parts string? - The URL users to list all parts.
- status string? - The URL used to get the status of the upload.
- log_event string? - The URL used to get the upload log from.
box: Skill![](/images/permalink.svg)
An object representing a skill
Fields
- id string? - The unique identifier for this skill
- 'type string? -
skill
- name string? - The name of the skill
- api_key string? - The client ID of the application
box: SkillCard![](/images/permalink.svg)
A generic Box Skill metadata card.
Fields
- created_at string? - The optional date and time this card was created at.
- 'type string -
skill_card
- skill_card_type string - The type of card to add to the file.
- skill_card_title SkillcardSkillCardTitle? - The title of the card.
- status SkillcardStatus? - Used with a card of type
status
to set the status of the skill. This can be used to show a message to the user while the Skill is processing the data.
- skill SkillcardSkill - The service that applied this metadata.
- invocation SkillcardInvocation - The invocation of this service, used to track which instance of a service applied the metadata.
- duration int? - An optional total duration in seconds. Used with a
skill_card_type
oftranscript
ortimeline
.
- entries SkillcardEntries[]? - An optional list of entries in the metadata card. This field is used with a
skill_card_type
oftranscript
,keyword
ortimeline
.
box: SkillcardAppears![](/images/permalink.svg)
The timestamp for an entry.
Fields
- 'start int? - The time in seconds when an entry should start appearing on a timeline.
- end int? - The time in seconds when an entry should stop appearing on a timeline. For a
skill_card_type
oftranscript
this value is ignored.
box: SkillcardEntries![](/images/permalink.svg)
An entry in the entries
attribute of a metadata card
Fields
- text string? - The text of the entry. This would be the actual keyword in a
keyword
card, the line of a transcript in atranscript
card, or the display name for an item when using thetimeline
entry.
- appears SkillcardAppears[]? - Defines a list of timestamps for an entry. This is used with a
skill_card_type
oftranscript
as well astimeline
to place items on a timeline. For askill_card_type
oftranscript
there can only be one entry in this list for each item, and only thestart
time is used to place the transcript on the timeline.
- image_url string? - The image to show on a for an entry that appears on a timeline. This image URL is required for any
timeline
cards. The image will be shown in a list of items (for example faces), and clicking the image will show the user where that entry appears during the duration of this entry.
box: SkillcardInvocation![](/images/permalink.svg)
The invocation of this service, used to track which instance of a service applied the metadata.
Fields
- 'type string -
skill_invocation
- id string - A custom identifier that represent the instance of the service that applied this metadata. For example, if your
image-recognition-service
runs on multiple nodes, this field can be used to identify the ID of the node that was used to apply the metadata.
box: SkillcardSkill![](/images/permalink.svg)
The service that applied this metadata.
Fields
- 'type string -
service
- id string - A custom identifier that represent the service that applied this metadata.
box: SkillcardSkillCardTitle![](/images/permalink.svg)
The title of the card.
Fields
- code string? - An optional identifier for the title.
- message string - The actual title to show in the UI.
box: SkillcardStatus![](/images/permalink.svg)
Used with a card of type status
to set the status of the skill. This can be used to show a message to the user while the Skill is processing the data.
Fields
- code string - A code for the status of this Skill invocation. By default each of these will have their own accompanied messages. These can be adjusted by setting the
message
value on this object.
- message string? - A custom message that can be provided with this status. This will be shown in the web app to the end user.
box: SkillInvocation![](/images/permalink.svg)
The payload of a Box skill as sent to a skill's invocation_url
.
Fields
- 'type string? -
skill_invocation
- id string? - Unique identifier for the invocation request.
- skill Skill? - An object representing a skill
- token SkillinvocationToken? - The read-only and read-write access tokens for this item
- status SkillinvocationStatus? - The details status of this event.
- created_at string? - The time this invocation was created.
- trigger string? - Action that triggered the invocation
- enterprise Enterprise? - A representation of a Box enterprise
- event Event? - The description of an event that happened within Box
box: SkillInvocationsSkillIdBody![](/images/permalink.svg)
Fields
- status string - Defines the status of this invocation. Set this to
success
when setting Skill cards.
- metadata SkillInvocationsskillIdMetadata - The metadata to set for this skill. This is a list of Box Skills cards. These cards will overwrite any existing Box skill cards on the file.
- file SkillInvocationsskillIdFile - The file to assign the cards to.
- file_version SkillInvocationsskillIdFileVersion? - The optional file version to assign the cards to.
- usage SkillInvocationsskillIdUsage? - A descriptor that defines what items are affected by this call. Set this to the default values when setting a card to a
success
state, and leave it out in most other situations.
box: SkillInvocationsskillIdFile![](/images/permalink.svg)
The file to assign the cards to.
Fields
- 'type string? -
file
- id string? - The ID of the file
box: SkillInvocationsskillIdFileVersion![](/images/permalink.svg)
The optional file version to assign the cards to.
Fields
- 'type string? -
file_version
- id string? - The ID of the file version
box: SkillInvocationsskillIdMetadata![](/images/permalink.svg)
The metadata to set for this skill. This is a list of Box Skills cards. These cards will overwrite any existing Box skill cards on the file.
Fields
- cards (SkillCard|KeywordSkillCard|TimelineSkillCard|TranscriptSkillCard|StatusSkillCard)[]? - A list of Box Skill cards to apply to this file.
box: SkillInvocationsskillIdUsage![](/images/permalink.svg)
A descriptor that defines what items are affected by this call. Set this to the default values when setting a card to a success
state, and leave it out in most other situations.
Fields
- unit string? -
file
- value decimal? -
1
box: SkillinvocationStatus![](/images/permalink.svg)
The details status of this event.
Fields
- state string? - The state of this event. *
invoked
- Triggered the skill with event details to start applying skill on the file. *processing
- Currently processing. *success
- Completed processing with a success. *transient_failure
- Encountered an issue which can be retried. *permanent_failure
- Encountered a permanent issue and retry would not help.
- message string? - Status information
- error_code string? - Error code information, if error occurred.
- additional_info string? - Additional status information.
box: SkillinvocationToken![](/images/permalink.svg)
The read-only and read-write access tokens for this item
Fields
- read SkillinvocationTokenRead? - The basics of an access token
- write SkillinvocationTokenRead? - The basics of an access token
box: SkillinvocationTokenRead![](/images/permalink.svg)
The basics of an access token
Fields
- access_token string? - The requested access token.
- expires_in int? - The time in seconds in seconds by which this token will expire.
- token_type string? - The type of access token returned.
- restricted_to FileScope[]? - The permissions that this access token permits, providing a list of resources (files, folders, etc) and the scopes permitted for each of those resources.
box: StatusSkillCard![](/images/permalink.svg)
A Box Skill metadata card that puts a status message in the metadata sidebar.
Fields
- created_at string? - The optional date and time this card was created at.
- 'type string -
skill_card
- skill_card_type string -
status
- skill_card_title StatusskillcardSkillCardTitle? - The title of the card.
- status StatusskillcardStatus - Sets the status of the skill. This can be used to show a message to the user while the Skill is processing the data, or if it was not able to process the file.
- skill SkillcardSkill - The service that applied this metadata.
- invocation SkillcardInvocation - The invocation of this service, used to track which instance of a service applied the metadata.
box: StatusskillcardSkillCardTitle![](/images/permalink.svg)
The title of the card.
Fields
- code string? - An optional identifier for the title.
- message string - The actual title to show in the UI.
box: StatusskillcardStatus![](/images/permalink.svg)
Sets the status of the skill. This can be used to show a message to the user while the Skill is processing the data, or if it was not able to process the file.
Fields
- code string - A code for the status of this Skill invocation. By default each of these will have their own accompanied messages. These can be adjusted by setting the
message
value on this object.
- message string? - A custom message that can be provided with this status. This will be shown in the web app to the end user.
box: StoragePolicies![](/images/permalink.svg)
A list of storage policies.
Fields
- 'limit int? - The limit that was used for these entries. This will be the same as the
limit
query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.
- next_marker int? - The marker for the start of the next page of results.
- prev_marker int? - The marker for the start of the previous page of results.
- entries StoragePolicy[]? -
box: StoragePolicy![](/images/permalink.svg)
The Storage Policy object describes the storage zone.
Fields
- Fields Included from *StoragepolicyMini
- name string? - A descriptive name of the region
box: StoragePolicyAssignment![](/images/permalink.svg)
The assignment of a storage policy to a user or enterprise
Fields
- storage_policy StoragepolicyMini? - A mini description of a Storage Policy object
- assigned_to AssignedTo? - The bare basic reference for an object
box: StoragePolicyAssignments![](/images/permalink.svg)
A list of storage policy assignments.
Fields
- 'limit int? - The limit that was used for these entries. This will be the same as the
limit
query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.
- next_marker int? - The marker for the start of the next page of results.
- prev_marker int? - The marker for the start of the previous page of results.
- entries StoragePolicyAssignment[]? -
box: StoragePolicyAssignmentsAssignedTo![](/images/permalink.svg)
The user or enterprise to assign the storage policy to.
Fields
- 'type string - The type to assign the policy to.
- id string - The ID of the user or enterprise
box: StoragePolicyAssignmentsBody![](/images/permalink.svg)
Fields
- storage_policy StoragePolicyAssignmentsStoragePolicy - The storage policy to assign to the user or enterprise
- assigned_to StoragePolicyAssignmentsAssignedTo - The user or enterprise to assign the storage policy to.
box: StoragePolicyAssignmentsStoragePolicy![](/images/permalink.svg)
The storage policy to assign to the user or enterprise
Fields
- 'type string - The type to assign.
- id string - The ID of the storage policy to assign.
box: StoragePolicyAssignmentsStoragePolicyAssignmentIdBody![](/images/permalink.svg)
Fields
- storage_policy StoragePolicyAssignmentsStoragePolicy - The storage policy to assign to the user or enterprise
box: StoragepolicyMini![](/images/permalink.svg)
A mini description of a Storage Policy object
Fields
- id string? - The unique identifier for this storage policy
- 'type string? -
storage_policy
box: Task![](/images/permalink.svg)
A task allows for file-centric workflows within Box. Users can create tasks on files and assign them to other users for them to complete the tasks.
Fields
- id string? - The unique identifier for this task
- 'type string? -
task
- item FileMini? - A mini representation of a file, used when nested under another resource.
- due_at string? - When the task is due
- action string? - The type of task the task assignee will be prompted to perform.
- message string? - A message that will be included with the task
- task_assignment_collection TaskAssignments? - A list of task assignments
- is_completed boolean? - Whether the task has been completed
- created_by UserMini? - A mini representation of a user, as can be returned when nested within other resources.
- created_at string? - When the task object was created
- completion_rule string? - Defines which assignees need to complete this task before the task is considered completed. *
all_assignees
requires all assignees to review or approve the the task in order for it to be considered completed. *any_assignee
accepts any one assignee to review or approve the the task in order for it to be considered completed.
box: TaskAssignment![](/images/permalink.svg)
A task assignment defines which task is assigned to which user to complete.
Fields
- id string? - The unique identifier for this task assignment
- 'type string? -
task_assignment
- item FileMini? - A mini representation of a file, used when nested under another resource.
- assigned_to UserMini? - A mini representation of a user, as can be returned when nested within other resources.
- message string? - A message that will is included with the task assignment. This is visible to the assigned user in the web and mobile UI.
- completed_at string? - The date at which this task assignment was completed. This will be
null
if the task is not completed yet.
- assigned_at string? - The date at which this task was assigned to the user.
- reminded_at string? - The date at which the assigned user was reminded of this task assignment.
- resolution_state string? - The current state of the assignment. The available states depend on the
action
value of the task object.
- assigned_by UserMini? - A mini representation of a user, as can be returned when nested within other resources.
box: TaskAssignments![](/images/permalink.svg)
A list of task assignments
Fields
- total_count int? - The total number of items in this collection.
- entries TaskAssignment[]? - The entries of task assignments.
box: TaskAssignmentsAssignTo![](/images/permalink.svg)
The user to assign the task to.
Fields
- id string? - The ID of the user to assign to the task. To specify a user by their email address use the
login
parameter.
- login string? - The email address of the user to assign to the task. To specify a user by their user ID please use the
id
parameter.
box: TaskAssignmentsBody![](/images/permalink.svg)
Fields
- task TaskAssignmentsTask - The task to assign to a user.
- assign_to TaskAssignmentsAssignTo - The user to assign the task to.
box: TaskAssignmentsTask![](/images/permalink.svg)
The task to assign to a user.
Fields
- id string - The ID of the task
- 'type string - The type of the item to assign.
box: TaskAssignmentsTaskAssignmentIdBody![](/images/permalink.svg)
Fields
- message string? - An optional message by the assignee that can be added to the task.
- resolution_state string? - The state of the task assigned to the user. * For a task with an
action
value ofcomplete
this can beincomplete
orcompleted
. * For a task with anaction
ofreview
this can beincomplete
,approved
, orrejected
.
box: Tasks![](/images/permalink.svg)
A list of tasks
Fields
- total_count int? - One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than
total_count
.
- entries Task[]? - Tasks on files which other users can to complete for a user.
box: TasksBody![](/images/permalink.svg)
Fields
- item TasksItem - The file to attach the task to.
- action string? - The action the task assignee will be prompted to do. Must be *
review
defines an approval task that can be approved or rejected *complete
defines a general task which can be completed
- message string? - An optional message to include with the task.
- due_at string? - Defines when the task is due. Defaults to
null
if not provided.
- completion_rule string? - Defines which assignees need to complete this task before the task is considered completed. *
all_assignees
(default) requires all assignees to review or approve the the task in order for it to be considered completed. *any_assignee
accepts any one assignee to review or approve the the task in order for it to be considered completed.
box: TasksItem![](/images/permalink.svg)
The file to attach the task to.
Fields
- id string - The ID of the file
- 'type string -
file
box: TasksTaskIdBody![](/images/permalink.svg)
Fields
- action string? - The action the task assignee will be prompted to do. Must be *
review
defines an approval task that can be approved or rejected *complete
defines a general task which can be completed
- message string? - The message included with the task.
- due_at string? - When the task is due at.
- completion_rule string? - Defines which assignees need to complete this task before the task is considered completed. *
all_assignees
(default) requires all assignees to review or approve the the task in order for it to be considered completed. *any_assignee
accepts any one assignee to review or approve the the task in order for it to be considered completed.
box: TermsOfService![](/images/permalink.svg)
The root-level record that is supposed to represent a single Terms of Service.
Fields
- Fields Included from *TermsofserviceMini
- status string? - Whether these terms are enabled or not
- tos_type string? - Whether to apply these terms to managed users or external users
- text string? - The text for your terms and conditions. This text could be empty if the
status
is set todisabled
.
- created_at string? - When the legal item was created
- modified_at string? - When the legal item was modified.
box: TermsofserviceMini![](/images/permalink.svg)
The root-level record that is supposed to represent a single Terms of Service.
Fields
- id string? - The unique identifier for this terms of service.
- 'type string? -
terms_of_service
box: TermsOfServices![](/images/permalink.svg)
A list of terms of services
Fields
- total_count int? - The total number of objects.
- entries TermsOfService[]? - The entries of terms of service.
box: TermsOfServicesBody![](/images/permalink.svg)
Fields
- status string - Whether this terms of service is active.
- tos_type string? - The type of user to set the terms of service for.
- text string - The terms of service text to display to users. The text can be set to empty if the
status
is set todisabled
.
box: TermsOfServicesTermsOfServiceIdBody![](/images/permalink.svg)
Fields
- status string - Whether this terms of service is active.
- text string - The terms of service text to display to users. The text can be set to empty if the
status
is set todisabled
.
box: TermsOfServiceUserStatus![](/images/permalink.svg)
The association between a Terms of Service and a user
Fields
- id string? - The unique identifier for this terms of service user status
- 'type string? -
terms_of_service_user_status
- tos TermsofserviceMini? - The root-level record that is supposed to represent a single Terms of Service.
- user UserMini? - A mini representation of a user, as can be returned when nested within other resources.
- is_accepted boolean? - If the user has accepted the terms of services
- created_at string? - When the legal item was created
- modified_at string? - When the legal item was modified.
box: TermsOfServiceUserStatuses![](/images/permalink.svg)
A list of terms of service user statuses
Fields
- total_count int? - The total number of objects.
- entries TermsOfServiceUserStatus[]? - The associations between a Terms of Service and a user.
box: TermsOfServiceUserStatusesBody![](/images/permalink.svg)
Fields
- tos TermsOfServiceUserStatusesTos - The terms of service to set the status for.
- user TermsOfServiceUserStatusesUser - The user to set the status for.
- is_accepted boolean - Whether the user has accepted the terms.
box: TermsOfServiceUserStatusesTermsOfServiceUserStatusIdBody![](/images/permalink.svg)
Fields
- is_accepted boolean - Whether the user has accepted the terms.
box: TermsOfServiceUserStatusesTos![](/images/permalink.svg)
The terms of service to set the status for.
Fields
- 'type string - The type of object.
- id string - The ID of terms of service
box: TermsOfServiceUserStatusesUser![](/images/permalink.svg)
The user to set the status for.
Fields
- 'type string - The type of object.
- id string - The ID of user
box: TimelineSkillCard![](/images/permalink.svg)
A Box Skill metadata card that places a list of images on a timeline.
Fields
- created_at string? - The optional date and time this card was created at.
- 'type string -
skill_card
- skill_card_type string -
timeline
- skill_card_title TimelineskillcardSkillCardTitle? - The title of the card.
- skill SkillcardSkill - The service that applied this metadata.
- invocation SkillcardInvocation - The invocation of this service, used to track which instance of a service applied the metadata.
- duration int? - An total duration in seconds of the timeline.
- entries TimelineskillcardEntries[] - A list of entries on the timeline.
box: TimelineskillcardAppears![](/images/permalink.svg)
The timestamp for an entry.
Fields
- 'start int? - The time in seconds when an entry should start appearing on a timeline.
- end int? - The time in seconds when an entry should stop appearing on a timeline.
box: TimelineskillcardEntries![](/images/permalink.svg)
An single item that's placed on multiple items on the timeline.
Fields
- text string? - The text of the entry. This would be the display name for an item being placed on the timeline, for example the name of the person who was detected in a video.
- appears TimelineskillcardAppears[]? - Defines a list of timestamps for when this item should appear on the timeline.
- image_url string? - The image to show on a for an entry that appears on a timeline. This image URL is required for every entry. The image will be shown in a list of items (for example faces), and clicking the image will show the user where that entry appears during the duration of this entry.
box: TimelineskillcardSkillCardTitle![](/images/permalink.svg)
The title of the card.
Fields
- code string? - An optional identifier for the title.
- message string - The actual title to show in the UI.
box: TranscriptSkillCard![](/images/permalink.svg)
A Box Skill metadata card that adds a transcript to a file.
Fields
- created_at string? - The optional date and time this card was created at.
- 'type string -
skill_card
- skill_card_type string -
transcript
- skill_card_title SkillcardSkillCardTitle? - The title of the card.
- skill TranscriptskillcardSkill - The service that applied this metadata.
- invocation TranscriptskillcardInvocation - The invocation of this service, used to track which instance of a service applied the metadata.
- duration int? - An optional total duration in seconds. Used with a
skill_card_type
oftranscript
ortimeline
.
- entries TranscriptskillcardEntries[] - An list of entries for the card. This represents the individual entries of the transcription.
box: TranscriptskillcardAppears![](/images/permalink.svg)
The timestamp for an entry.
Fields
- 'start int? - The time in seconds when an entry should start appearing on a timeline.
box: TranscriptskillcardEntries![](/images/permalink.svg)
An entry in the entries
attribute of a metadata card
Fields
- text string? - The text of the entry. This would be the transcribed text assigned to the entry on the timeline.
- appears TranscriptskillcardAppears[]? - Defines when a transcribed bit of text appears. This only includes a start time and no end time.
box: TranscriptskillcardInvocation![](/images/permalink.svg)
The invocation of this service, used to track which instance of a service applied the metadata.
Fields
- 'type string -
skill_invocation
- id string - A custom identifier that represent the instance of the service that applied this metadata. For example, if your
image-recognition-service
runs on multiple nodes, this field can be used to identify the ID of the node that was used to apply the metadata.
box: TranscriptskillcardSkill![](/images/permalink.svg)
The service that applied this metadata.
Fields
- 'type string -
service
- id string - A custom identifier that represent the service that applied this metadata.
box: UploadedPart![](/images/permalink.svg)
A chunk of a file uploaded as part of an upload session, as returned by some endpoints.
Fields
- part UploadPart? - The representation of an upload session chunk.
box: UploadPart![](/images/permalink.svg)
The representation of an upload session chunk.
Fields
- Fields Included from *UploadpartMini
- sha1 string? - The SHA1 hash of the chunk.
box: UploadpartMini![](/images/permalink.svg)
The basic representation of an upload session chunk.
Fields
- part_id string? - The unique ID of the chunk.
- offset int? - The offset of the chunk within the file in bytes. The lower bound of the position of the chunk within the file.
- size int? - The size of the chunk in bytes.
box: UploadParts![](/images/permalink.svg)
A list of uploaded chunks for an upload session.
Fields
- total_count int? - One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than
total_count
. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.
- 'limit int? - The limit that was used for these entries. This will be the same as the
limit
query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.
- offset int? - The 0-based offset of the first entry in this set. This will be the same as the
offset
query parameter. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.
- 'order CollaborationsOrder[]? - The order by which items are returned. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.
- entries UploadPart[]? -
box: UploadSession![](/images/permalink.svg)
An upload session for chunk uploading a file.
Fields
- id string? - The unique identifier for this session
- 'type string? -
upload_session
- session_expires_at string? - The date and time when this session expires.
- part_size int? - The size in bytes that must be used for all parts of of the upload. Only the last part is allowed to be of a smaller size.
- total_parts int? - The total number of parts expected in this upload session, as determined by the file size and part size.
- num_parts_processed int? - The number of parts that have been uploaded and processed by the server. This starts at
0
. When committing a file files, inspecting this property can provide insight if all parts have been uploaded correctly.
- session_endpoints SessionEndpoint? - Session endpoints.
box: UploadSessionIdCommitBody![](/images/permalink.svg)
Fields
- parts UploadPart[] - The list details for the uploaded parts
box: UploadUrl![](/images/permalink.svg)
The details for the upload session for the file.
Fields
- upload_url string? - A URL for an upload session that can be used to upload the file.
- upload_token string? - An optional access token to use to upload the file
box: User![](/images/permalink.svg)
A standard representation of a user, as returned from any user API endpoints by default
Fields
- Fields Included from *UserMini
- created_at string? - When the user object was created
- modified_at string? - When the user object was last modified
- timezone string? - The user's timezone
- space_amount int? - The user’s total available space amount in bytes
- space_used int? - The amount of space in use by the user
- max_upload_size int? - The maximum individual file size in bytes the user can have
- status string? - The user's account status
- job_title string? - The user’s job title
- phone string? - The user’s phone number
- address string? - The user’s address
- avatar_url string? - URL of the user’s avatar image
- notification_email UserNotificationEmail? - An alternate notification email address to which email notifications are sent. When it's confirmed, this will be the email address to which notifications are sent instead of to the primary email address.
box: UserBase![](/images/permalink.svg)
A mini representation of a user, used when nested within another resource.
Fields
- id string? - The unique identifier for this user
- 'type string? -
user
box: UserFull![](/images/permalink.svg)
A full representation of a user, as can be returned from any user API endpoint.
Fields
- Fields Included from *User
- role string? - The user’s enterprise role
- tracking_codes UserfullTrackingCodes[]? - Tracking codes allow an admin to generate reports from the admin console and assign an attribute to a specific group of users. This setting must be enabled for an enterprise before it can be used.
- can_see_managed_users boolean? - Whether the user can see other enterprise users in their contact list
- is_sync_enabled boolean? - Whether the user can use Box Sync
- is_external_collab_restricted boolean? - Whether the user is allowed to collaborate with users outside their enterprise
- is_exempt_from_device_limits boolean? - Whether to exempt the user from Enterprise device limits
- is_exempt_from_login_verification boolean? - Whether the user must use two-factor authentication
- my_tags string[]? - Tags for all files and folders owned by the user. Values returned will only contain tags that were set by the requester.
- hostname string? - The root (protocol, subdomain, domain) of any links that need to be generated for the user
- is_platform_access_only boolean? - Whether the user is an App User
- external_app_user_id string? - An external identifier for an app user, which can be used to look up the user. This can be used to tie user IDs from external identity providers to Box users.
box: UserfullTrackingCodes![](/images/permalink.svg)
Custom tracking code for a user.
Fields
- 'type string? -
tracking_code
- name string? - The name of the tracking code, which must be preconfigured in the Admin Console
- value string? - The value of the tracking code
box: UserIdEmailAliasesBody![](/images/permalink.svg)
Fields
- email string - The email address to add to the account as an alias.
box: UserMini![](/images/permalink.svg)
A mini representation of a user, as can be returned when nested within other resources.
Fields
- Fields Included from *UserBase
- name string? - The display name of this user
- login string? - The primary email address of this user
box: UserNotificationEmail![](/images/permalink.svg)
An alternate notification email address to which email notifications are sent. When it's confirmed, this will be the email address to which notifications are sent instead of to the primary email address.
Fields
- email string? - The email address to send the notifications to.
- is_confirmed boolean? - Specifies if this email address has been confirmed.
box: Users![](/images/permalink.svg)
A list of users.
Fields
- total_count int? - One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than
total_count
. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.
- 'limit int? - The limit that was used for these entries. This will be the same as the
limit
query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.
- offset int? - The 0-based offset of the first entry in this set. This will be the same as the
offset
query parameter. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.
- 'order CollaborationsOrder[]? - The order by which items are returned. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.
- entries User[]? -
box: UsersBody![](/images/permalink.svg)
Fields
- name string - The name of the user
- login string? - The email address the user uses to log in Required, unless
is_platform_access_only
is set totrue
.
- is_platform_access_only boolean? - Specifies that the user is an app user.
- role string? - The user’s enterprise role
- is_sync_enabled boolean? - Whether the user can use Box Sync
- job_title string? - The user’s job title
- phone string? - The user’s phone number
- address string? - The user’s address
- space_amount int? - The user’s total available space in bytes. Set this to
-1
to indicate unlimited storage.
- tracking_codes string[]? - Tracking codes allow an admin to generate reports from the admin console and assign an attribute to a specific group of users. This setting must be enabled for an enterprise before it can be used.
- can_see_managed_users boolean? - Whether the user can see other enterprise users in their contact list
- timezone string? - The user's timezone
- is_external_collab_restricted boolean? - Whether the user is allowed to collaborate with users outside their enterprise
- is_exempt_from_device_limits boolean? - Whether to exempt the user from enterprise device limits
- is_exempt_from_login_verification boolean? - Whether the user must use two-factor authentication
- status string? - The user's account status
- external_app_user_id string? - An external identifier for an app user, which can be used to look up the user. This can be used to tie user IDs from external identity providers to Box users.
box: UsersUserIdBody![](/images/permalink.svg)
Fields
- enterprise string? - Set this to
null
to roll the user out of the enterprise and make them a free user
- notify boolean? - Whether the user should receive an email when they are rolled out of an enterprise
- name string? - The name of the user
- login string? - The email address the user uses to log in
- role string? - The user’s enterprise role
- is_sync_enabled boolean? - Whether the user can use Box Sync
- job_title string? - The user’s job title
- phone string? - The user’s phone number
- address string? - The user’s address
- tracking_codes string[]? - Tracking codes allow an admin to generate reports from the admin console and assign an attribute to a specific group of users. This setting must be enabled for an enterprise before it can be used.
- can_see_managed_users boolean? - Whether the user can see other enterprise users in their contact list
- timezone string? - The user's timezone
- is_external_collab_restricted boolean? - Whether the user is allowed to collaborate with users outside their enterprise
- is_exempt_from_device_limits boolean? - Whether to exempt the user from enterprise device limits
- is_exempt_from_login_verification boolean? - Whether the user must use two-factor authentication
- is_password_reset_required boolean? - Whether the user is required to reset their password
- status string? - The user's account status
- space_amount int? - The user’s total available space in bytes. Set this to
-1
to indicate unlimited storage.
- notification_email UsersuserIdNotificationEmail? - An alternate notification email address to which email notifications are sent. When it's confirmed, this will be the email address to which notifications are sent instead of to the primary email address. Set this value to
null
to remove the notification email.
box: UsersuserIdfolders0OwnedBy![](/images/permalink.svg)
The user who the folder will be transferred to
Fields
- id string - The ID of the user who the folder will be transferred to
box: UsersuserIdNotificationEmail![](/images/permalink.svg)
An alternate notification email address to which email notifications are sent. When it's confirmed, this will be the email address to which notifications are sent instead of to the primary email address. Set this value to null
to remove the notification email.
Fields
- email string? - The email address to send the notifications to.
box: VersionsCurrentBody![](/images/permalink.svg)
The file version to revert to
Fields
- id string? - The file version ID
- 'type string? - The type to revert to
box: Watermark![](/images/permalink.svg)
A watermark is a semi-transparent overlay on an embedded file preview that displays a viewer's email address or user ID and the time of access over a file's content
Fields
- watermark WatermarkWatermark? - Watermark details
box: WatermarkWatermark![](/images/permalink.svg)
Watermark details
Fields
- created_at string? - When this watermark was created
- modified_at string? - When this task was modified
box: Webhook![](/images/permalink.svg)
Represents a configured webhook.
Fields
- id string? - The unique identifier for this webhook.
- 'type string? -
webhook
- target WebhooksTarget? - The item that will trigger the webhook
- created_by UserMini? - A mini representation of a user, as can be returned when nested within other resources.
- created_at string? - A timestamp identifying the time that the webhook was created.
- address string? - The URL that is notified by this webhook
- triggers string[]? - An array of event names that this webhook is to be triggered for
box: WebhookInvocation![](/images/permalink.svg)
The event that is sent to a webhook address when an event happens.
Fields
- id string? - The unique identifier for this webhook invocation
- 'type string? -
webhook_event
- webhook Webhook? - Represents a configured webhook.
- created_by UserMini? - A mini representation of a user, as can be returned when nested within other resources.
- created_at string? - A timestamp identifying the time that the webhook event was triggered.
- trigger string? - The event name that triggered this webhook
box: Webhooks![](/images/permalink.svg)
A list of webhooks.
Fields
- 'limit int? - The limit that was used for these entries. This will be the same as the
limit
query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.
- next_marker int? - The marker for the start of the next page of results.
- prev_marker int? - The marker for the start of the previous page of results.
- entries Webhook[]? -
box: WebhooksBody![](/images/permalink.svg)
Fields
- target WebhooksTarget - The item that will trigger the webhook
- address string - The URL that is notified by this webhook
- triggers string[] - An array of event names that this webhook is to be triggered for
box: WebhooksTarget![](/images/permalink.svg)
The item that will trigger the webhook
Fields
- id string? - The ID of the item to trigger a webhook
- 'type string? - The type of item to trigger a webhook
box: WebhooksWebhookIdBody![](/images/permalink.svg)
Fields
- target WebhooksTarget? - The item that will trigger the webhook
- address string? - The URL that is notified by this webhook
- triggers string[]? - An array of event names that this webhook is to be triggered for
box: WebLink![](/images/permalink.svg)
Web links are objects that point to URLs. These objects are also known as bookmarks within the Box web application. Web link objects are treated similarly to file objects, they will also support most actions that apply to regular files.
Fields
- Fields Included from *WeblinkMini
- parent record {}? -
- description string? - The description accompanying the web link. This is visible within the Box web application.
- path_collection record { total_count int, entries FolderMini[] }? -
- created_at string? - When this file was created on Box’s servers.
- modified_at string? - When this file was last updated on the Box servers.
- trashed_at string? - When this file was last moved to the trash.
- purged_at string? - When this file will be permanently deleted.
- created_by record {}? -
- modified_by record {}? -
- owned_by record {}? -
- shared_link record { url string, download_url string?, vanity_url string?, vanity_name string?, access string, effective_access string, effective_permission string, unshared_at string?, is_password_enabled boolean, permissions record { can_download boolean, can_preview boolean }, download_count int, preview_count int }? -
- item_status string? - Whether this item is deleted or not. Values include
active
,trashed
if the file has been moved to the trash, anddeleted
if the file has been permanently deleted
box: WeblinkBase![](/images/permalink.svg)
Web links are objects that point to URLs. These objects are also known as bookmarks within the Box web application. Web link objects are treated similarly to file objects, they will also support most actions that apply to regular files.
Fields
- id string? - The unique identifier for this web link
- 'type string? -
web_link
- etag string? - The entity tag of this web link. Used with
If-Match
headers.
box: WeblinkMini![](/images/permalink.svg)
Web links are objects that point to URLs. These objects are also known as bookmarks within the Box web application. Web link objects are treated similarly to file objects, they will also support most actions that apply to regular files.
Fields
- Fields Included from *WeblinkBase
- url string? - The URL this web link points to
- sequence_id record {}? -
- name string? - The name of the web link
box: WebLinksBody![](/images/permalink.svg)
Fields
- url string - The URL that this web link links to. Must start with
"http://"
or"https://"
.
- parent WebLinksParent - The parent folder to create the web link within.
- name string? - Name of the web link. Defaults to the URL if not set.
- description string? - Description of the web link.
box: WebLinksParent![](/images/permalink.svg)
The parent folder to create the web link within.
Fields
- id string - The ID of parent folder
box: WebLinksWebLinkIdBody![](/images/permalink.svg)
Fields
- url string? - The new URL that the web link links to. Must start with
"http://"
or"https://"
.
- parent record { id string }? -
- name string? - A new name for the web link. Defaults to the URL if not set.
- description string? - A new description of the web link.
box: WebLinksWebLinkIdBody1![](/images/permalink.svg)
Fields
- name string? - An optional new name for the web link.
- parent record { id string }? -
box: ZipDownload![](/images/permalink.svg)
Represents a successful request to create a zip
archive of a list of files and folders.
Fields
- download_url string? - The URL that can be used to download the
zip
archive. AGet
request to this URL will start streaming the items requested. By default, this URL is only valid for a few seconds, until theexires_at
time, unless a download is started after which it is valid for the duration of the download. It is important to note that the domain and path of this URL might change between API calls, and therefore it's important to use this URL as-is.
- status_url string? - The URL that can be used to get the status of the
zip
archive being downloaded. AGet
request to this URL will return the number of files in the archive as well as the number of items already downloaded or skipped. By default, this URL is only valid for a few seconds, until theexires_at
time, unless a download is started after which the URL is valid for 12 hours from the start of the download. It is important to note that the domain and path of this URL might change between API calls, and therefore it's important to use this URL as-is.
- expires_at string? - The time and date when this archive will expire. After this time the
status_url
anddownload_url
will return an error. By default, these URLs are only valid for a few seconds, unless a download is started after which thedownload_url
is valid for the duration of the download, and thestatus_url
is valid for 12 hours from the start of the download.
- name_conflicts NameConflict[]? - A list of conflicts that occurred when trying to create the archive. This would occur when multiple items have been requested with the same name. To solve these conflicts, the API will automatically rename an item and return a mapping between the original item's name and its new name. For every conflict, both files will be renamed and therefore this list will always be a multiple of 2.
box: ZipDownloadRequest![](/images/permalink.svg)
A request to create a zip
archive to download
Fields
- items ZipdownloadrequestItems[] - A list of items to add to the
zip
archive. These can be folders or files.
- download_file_name string? - The optional name of the
zip
archive. This name will be appended by the.zip
file extension, for exampleJanuary Financials.zip
.
box: ZipdownloadrequestItems![](/images/permalink.svg)
An item to add to the zip
archive. This can be a file or a folder.
Fields
- 'type string - The type of the item to add to the archive.
- id string - The identifier of the item to add to the archive. When this item is a folder then this can not be the root folder with ID
0
.
box: ZipDownloadStatus![](/images/permalink.svg)
The status of a zip
archive being downloaded.
Fields
- total_file_count int? - The total number of files in the archive.
- downloaded_file_count int? - The number of files that have already been downloaded.
- skipped_file_count int? - The number of files that have been skipped as they could not be downloaded. In many cases this is due to permission issues that have surfaced between the creation of the request for the archive and the archive being downloaded.
- skipped_folder_count int? - The number of folders that have been skipped as they could not be downloaded. In many cases this is due to permission issues that have surfaced between the creation of the request for the archive and the archive being downloaded.
- state string? - The state of the archive being downloaded.
Import
import ballerinax/box;
Metadata
Released date: over 2 years ago
Version: 1.1.0
License: Apache-2.0
Compatibility
Platform: any
Ballerina version: slbeta6
GraalVM compatible: Yes
Pull count
Total: 0
Current verison: 0
Weekly downloads
Keywords
Content & Files/File Management & Storage
Cost/Freemium
Contributors