@datafire/box

Client library for Box Platform API

Installation and Usage

``bash
npm install --save @datafire/box
`
`js
let box = require('@datafire/box').create({
access_token: "",
refresh_token: "",
client_id: "",
client_secret: "",
redirect_uri: ""
});

.then(data => {
console.log(data);
});
`

Description

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.

Actions

$3

Exchange the code passed to your redirect URI for an access_token


`js
box.oauthCallback({
"code": ""
}, context)
`

#### Input
* input object
* code required string

#### Output
* output object
* access_token string
* refresh_token string
* token_type string
* scope string
* expiration string

$3

Exchange a refresh_token for an access_token


`js
box.oauthRefresh(null, context)
`

#### Input
This action has no parameters

#### Output
* output object
* access_token string
* refresh_token string
* token_type string
* scope string
* expiration string

$3

Authorize a user by sending them through the Box
website and request their permission to act on their behalf.

This is the first step when authenticating a user using
OAuth 2.0. To request a user's authorization to use the Box APIs
on their behalf you will need to send a user to the URL with this
format.


`js
box.get_authorize({
"response_type": "",
"client_id": ""
}, context)
`

#### Input
* input object
* response_type required string (values: code): The type of response we'd like to receive.
* client_id required string: The Client ID of the application that is requesting to authenticate
* redirect_uri string: The URL to which Box redirects the browser after the user has granted
* state string: A custom string of your choice. Box will pass the same string to
* scope string: A comma-separated list of application scopes you'd like to

#### Output
* output string

$3

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


`js
box.get_collaboration_whitelist_entries({}, context)
`

#### Input
* input object
* marker string: Defines the position marker at which to begin returning results. This is
* limit integer: The maximum number of items to return per page.

#### Output
* output CollaborationAllowlistEntries

$3

Creates a new entry in the list of allowed domains to allow
collaboration for.


`js
box.post_collaboration_whitelist_entries({}, context)
`

#### Input
* input object
* body object
* direction required string (values: inbound, outbound, both): The direction in which to allow collaborations.
* domain required string: The domain to add to the list of allowed domains.

#### Output
* output CollaborationAllowlistEntry

$3

Removes a domain from the list of domains that have been deemed safe to create
collaborations for within the current enterprise.


`js
box.delete_collaboration_whitelist_entries_id({
"collaboration_whitelist_entry_id": ""
}, context)
`

#### Input
* input object
* collaboration_whitelist_entry_id required string: The ID of the entry in the list.

#### Output
Output schema unknown

$3

Returns a domain that has been deemed safe to create collaborations
for within the current enterprise.


`js
box.get_collaboration_whitelist_entries_id({
"collaboration_whitelist_entry_id": ""
}, context)
`

#### Input
* input object
* collaboration_whitelist_entry_id required string: The ID of the entry in the list.

#### Output
* output CollaborationAllowlistEntry

$3

Returns a list of users who have been exempt from the collaboration
domain restrictions.


`js
box.get_collaboration_whitelist_exempt_targets({}, context)
`

#### Input
* input object
* marker string: Defines the position marker at which to begin returning results. This is
* limit integer: The maximum number of items to return per page.

#### Output
* output CollaborationAllowlistExemptTargets

$3

Exempts a user from the restrictions set out by the allowed list of domains
for collaborations.


`js
box.post_collaboration_whitelist_exempt_targets({}, context)
`

#### Input
* input object
* body object
* user required object: The user to exempt.
* id required string: The ID of the user to exempt.

#### Output
* output CollaborationAllowlistExemptTarget

$3

Removes a user's exemption from the restrictions set out by the allowed list
of domains for collaborations.


`js
box.delete_collaboration_whitelist_exempt_targets_id({
"collaboration_whitelist_exempt_target_id": ""
}, context)
`

#### Input
* input object
* collaboration_whitelist_exempt_target_id required string: The ID of the exemption to the list.

#### Output
Output schema unknown

$3

Returns a users who has been exempt from the collaboration
domain restrictions.


`js
box.get_collaboration_whitelist_exempt_targets_id({
"collaboration_whitelist_exempt_target_id": ""
}, context)
`

#### Input
* input object
* collaboration_whitelist_exempt_target_id required string: The ID of the exemption to the list.

#### Output
* output CollaborationAllowlistExemptTarget

$3

Retrieves all pending collaboration invites for this user.


`js
box.get_collaborations({
"status": ""
}, context)
`

#### Input
* input object
* status required string (values: pending): The status of the collaborations to retrieve
* fields array: A comma-separated list of attributes to include in the
* offset integer: The offset of the item at which to begin the response.
* limit integer: The maximum number of items to return per page.

#### Output
* output Collaborations

$3

Adds a collaboration for a single user or a single group to a file
or folder.

Collaborations can be created using email address, user IDs, or a
group IDs.

If a collaboration is being created with a group, access to
this endpoint is dependent on the group's ability to be invited.


`js
box.post_collaborations({}, context)
`

#### Input
* input object
* fields array: A comma-separated list of attributes to include in the
* notify boolean: Determines if users should receive email notification
* body object
* accessible_by required object: The user or group to give access to the item.
* id string: The ID of the user or group.
* login string: The email address of the user to grant access to the item.
* type required string (values: user, group): The type of collaborator to invite.
* can_view_path boolean: Determines if the invited users can see the entire parent path to
* expires_at string: Set the expiration date for the collaboration. At this date, the
* item required object: The item to attach the comment to.
* id required string: The ID of the item that will be granted access to
* type required string (values: file, folder): The type of the item that this collaboration will be
* role required string (values: editor, viewer, previewer, uploader, previewer uploader, viewer uploader, co-owner): The level of access granted.

#### Output
* output Collaboration

$3

Deletes a single collaboration.


`js
box.delete_collaborations_id({
"collaboration_id": ""
}, context)
`

#### Input
* input object
* collaboration_id required string: The ID of the collaboration

#### Output
Output schema unknown

$3

Retrieves a single collaboration.


`js
box.get_collaborations_id({
"collaboration_id": ""
}, context)
`

#### Input
* input object
* collaboration_id required string: The ID of the collaboration
* fields array: A comma-separated list of attributes to include in the

#### Output
* output Collaboration

$3

Updates a collaboration.

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


`js
box.put_collaborations_id({
"collaboration_id": ""
}, context)
`

#### Input
* input object
* collaboration_id required string: The ID of the collaboration
* body object
* can_view_path boolean: Determines if the invited users can see the entire parent path to
* expires_at string: Update the expiration date for the collaboration. At this date,
* role required string (values: editor, viewer, previewer, uploader, previewer uploader, viewer uploader, co-owner, owner): The level of access granted.
* status string (values: pending, accepted, rejected):

#### Output
* output Collaboration

$3

Retrieves all collections for a given user.

Currently, only the favorites collection
is supported.


`js
box.get_collections({}, context)
`

#### Input
* input object
* fields array: A comma-separated list of attributes to include in the
* offset integer: The offset of the item at which to begin the response.
* limit integer: The maximum number of items to return per page.

#### Output
* output Collections

$3

Retrieves the files and/or folders contained within
this collection.


`js
box.get_collections_id_items({
"collection_id": ""
}, context)
`

#### Input
* input object
* collection_id required string: The ID of the collection.
* fields array: A comma-separated list of attributes to include in the
* offset integer: The offset of the item at which to begin the response.
* limit integer: The maximum number of items to return per page.

#### Output
* output Items

$3

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


`js
box.post_comments({}, context)
`

#### Input
* input object
* fields array: A comma-separated list of attributes to include in the
* body object
* item object: The item to attach the comment to.
* id required string: The ID of the item
* type required string (values: file, comment): The type of the item that this comment will be placed on.
* message required string: The text of the comment.
* tagged_message string: The text of the comment, including @[user_id:name]

#### Output
* output Comment

$3

Permanently deletes a comment.


`js
box.delete_comments_id({
"comment_id": ""
}, context)
`

#### Input
* input object
* comment_id required string: The ID of the comment.

#### Output
Output schema unknown

$3

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


`js
box.get_comments_id({
"comment_id": ""
}, context)
`

#### Input
* input object
* comment_id required string: The ID of the comment.
* fields array: A comma-separated list of attributes to include in the

#### Output
* output Comment

$3

Update the message of a comment.


`js
box.put_comments_id({
"comment_id": ""
}, context)
`

#### Input
* input object
* comment_id required string: The ID of the comment.
* fields array: A comma-separated list of attributes to include in the
* body object
* message string: The text of the comment to update

#### Output
* output Comment

$3

Deletes an individual device pin.


`js
box.delete_device_pinners_id({
"device_pinner_id": ""
}, context)
`

#### Input
* input object
* device_pinner_id required string: The ID of the device pin

#### Output
Output schema unknown

$3

Retrieves information about an individual device pin.


`js
box.get_device_pinners_id({
"device_pinner_id": ""
}, context)
`

#### Input
* input object
* device_pinner_id required string: The ID of the device pin

#### Output
* output DevicePinner

$3

Retrieves all the device pins within an enterprise.

The user must have admin privileges, and the application
needs the "manage enterprise" scope to make this call.


`js
box.get_enterprises_id_device_pinners({
"enterprise_id": ""
}, context)
`

#### Input
* input object
* enterprise_id required string: The ID of the enterprise
* marker string: Defines the position marker at which to begin returning results. This is
* limit integer: The maximum number of items to return per page.
* direction string (values: ASC, DESC): The direction to sort results in. This can be either in alphabetical ascending

#### Output
* output DevicePinners

$3

Returns up to a year of past events for a given user
or for the entire enterprise.

By default this returns events for the authenticated user. To retrieve
events for the entire enterprise, set the stream_type to admin_logs.
The user making the API call will need to have admin privileges, and
the application will need to have the permission to access the event feed
to get the enterprise event feed.


`js
box.get_events({}, context)
`

#### Input
* input object
* stream_type string (values: all, changes, sync, admin_logs): Defines the type of events that are returned
* stream_position string: The location in the event stream to start receiving events from.
* limit integer: Limits the number of events returned
* event_type array: A comma-separated list of events to filter by. This can only be used when
* created_after string: The lower bound date and time to return events for. This can only be used
* created_before string: The upper bound date and time to return events for. This can only be used

#### Output
* output Events

$3

Returns a list of real-time servers that can be used for long-polling updates
to the event stream.

Long polling is the concept where a HTTP request is kept open until the
server sends a response, then repeating the process over and over to receive
updated responses.

Long polling the event stream can only be used for user events, not for
enterprise events.

To use long polling, first use this endpoint to retrieve a list of long poll
URLs. Next, make a long poll request to any of the provided URLs.

When an event occurs in monitored account a response with the value
new_change will be sent. The response contains no other details as
it only serves as a prompt to take further action such as sending a
request to the events endpoint with the last known
stream_position.

After the server sends this response it closes the connection. You must now
repeat the long poll process to begin listening for events again.

If no events occur for a while and the connection times out you will
receive a response with the value reconnect. When you receive this response
you’ll make another call to this endpoint to restart the process.

If you receive no events in retry_timeout seconds then you will need to
make another request to the real-time server (one of the URLs in the response
for this endpoint). This might be necessary due to network errors.

Finally, if you receive a max_retries error when making a request to the
real-time server, you should start over by making a call to this endpoint
first.


`js
box.options_events(null, context)
`

#### Input
This action has no parameters

#### Output
* output RealtimeServers

$3

Deletes a file request permanently.


`js
box.delete_file_requests_id({
"file_request_id": ""
}, context)
`

#### Input
* input object
* file_request_id required string: The unique identifier that represent a file request.

#### Output
Output schema unknown

$3

Retrieves the information about a file request.


`js
box.get_file_requests_id({
"file_request_id": ""
}, context)
`

#### Input
* input object
* file_request_id required string: The unique identifier that represent a file request.

#### Output
* output FileRequest

$3

Updates a file request. This can be used to activate or
deactivate a file request.


`js
box.put_file_requests_id({
"file_request_id": ""
}, context)
`

#### Input
* input object
* file_request_id required string: The unique identifier that represent a file request.
* if-match string: Ensures this item hasn't recently changed before
* body FileRequestUpdateRequest

#### Output
* output FileRequest

$3

Copies an existing file request that is already present on one folder,
and applies it to another folder.


`js
box.post_file_requests_id_copy({
"file_request_id": ""
}, context)
`

#### Input
* input object
* file_request_id required string: The unique identifier that represent a file request.
* body FileRequestCopyRequest

#### Output
* output FileRequest

$3

Get a list of file versions on legal hold for a legal hold
assignment.

Due to ongoing re-architecture efforts this API might not return all file
versions for this policy ID.

Instead, this API will only return file versions held in the legacy
architecture. Two new endpoints will available to request any file versions
held in the new architecture.

For file versions held in the new architecture, the GET
/legal_hold_policy_assignments/:id/file_versions_on_hold API can be used to
return all past file versions available for this policy assignment, and the
GET /legal_hold_policy_assignments/:id/files_on_hold API can be used to
return any current (latest) versions of a file under legal hold.

The GET /legal_hold_policy_assignments?policy_id={id} API can be used to
find a list of policy assignments for a given policy ID.

Once the re-architecture is completed this API will be deprecated.


`js
box.get_file_version_legal_holds({
"policy_id": ""
}, context)
`

#### Input
* input object
* policy_id required string: The ID of the legal hold policy to get the file version legal
* marker string: Defines the position marker at which to begin returning results. This is
* limit integer: The maximum number of items to return per page.

#### Output
* output FileVersionLegalHolds

$3

Retrieves information about the legal hold policies
assigned to a file version.


`js
box.get_file_version_legal_holds_id({
"file_version_legal_hold_id": ""
}, context)
`

#### Input
* input object
* file_version_legal_hold_id required string: The ID of the file version legal hold

#### Output
* output FileVersionLegalHold

$3

Retrieves all file version retentions for the given enterprise.


`js
box.get_file_version_retentions({}, context)
`

#### Input
* input object
* file_id string: Filters results by files with this ID.
* file_version_id string: Filters results by file versions with this ID.
* policy_id string: Filters results by the retention policy with this ID.
* disposition_action string (values: permanently_delete, remove_retention): Filters results by the retention policy with this disposition
* disposition_before string: Filters results by files that will have their disposition
* disposition_after string: Filters results by files that will have their disposition
* limit integer: The maximum number of items to return per page.
* marker string: Defines the position marker at which to begin returning results. This is

#### Output
* output FileVersionRetentions

$3

Returns information about a file version retention.


`js
box.get_file_version_retentions_id({
"file_version_retention_id": ""
}, context)
`

#### Input
* input object
* file_version_retention_id required string: The ID of the file version retention

#### Output
* output FileVersionRetention

$3

Performs a check to verify that a file will be accepted by Box
before you upload the entire file.


`js
box.options_files_content({}, context)
`

#### Input
* input object
* body object
* name string: The name for the file
* parent
* id string: The ID of parent item
* size integer: The size of the file in bytes

#### Output
* output UploadUrl

$3

Uploads a small file to Box. For file sizes over 50MB we recommend
using the Chunk Upload APIs.

Request body order

The attributes part of the body must come before the
file part. Requests that do not follow this format when
uploading the file will receive a HTTP 400 error with a
metadata_after_file_contents error code.


`js
box.post_files_content({
"attributes": {},
"file": ""
}, context)
`

#### Input
* input object
* fields array: A comma-separated list of attributes to include in the
* content-md5 string: An optional header containing the SHA1 hash of the file to
* attributes required object: The additional attributes of the file being uploaded. Mainly the
* file required string: The content of the file to upload to Box.

#### Output
* output Files

$3

Creates an upload session for a new file.


`js
box.post_files_upload_sessions({}, context)
`

#### Input
* input object
* body object
* file_name required string: The name of new file
* file_size required integer: The total number of bytes of the file to be uploaded
* folder_id required string: The ID of the folder to upload the new file to.

#### Output
* output UploadSession

$3

Abort an upload session and discard all data uploaded.

This cannot be reversed.


`js
box.delete_files_upload_sessions_id({
"upload_session_id": ""
}, context)
`

#### Input
* input object
* upload_session_id required string: The ID of the upload session.

#### Output
Output schema unknown

$3

Return information about an upload session.


`js
box.get_files_upload_sessions_id({
"upload_session_id": ""
}, context)
`

#### Input
* input object
* upload_session_id required string: The ID of the upload session.

#### Output
* output UploadSession

$3

Updates a chunk of an upload session for a file.


`js
box.put_files_upload_sessions_id({
"upload_session_id": "",
"digest": "",
"content-range": ""
}, context)
`

#### Input
* input object
* upload_session_id required string: The ID of the upload session.
* digest required string: The [RFC3230][1] message digest of the chunk uploaded.
* content-range required string: The byte range of the chunk.
* body string: The binary content of the file

#### Output
* output UploadedPart

$3

Close an upload session and create a file from the
uploaded chunks.


`js
box.post_files_upload_sessions_id_commit({
"upload_session_id": "",
"digest": ""
}, context)
`

#### Input
* input object
* upload_session_id required string: The ID of the upload session.
* digest required string: The [RFC3230][1] message digest of the whole file.
* if-match string: Ensures this item hasn't recently changed before
* if-none-match string: Ensures an item is only returned if it has changed.
* body object
* parts required array: The list details for the uploaded parts
* items UploadPart

#### Output
* output Files

$3

Return a list of the chunks uploaded to the upload
session so far.


`js
box.get_files_upload_sessions_id_parts({
"upload_session_id": ""
}, context)
`

#### Input
* input object
* upload_session_id required string: The ID of the upload session.
* offset integer: The offset of the item at which to begin the response.
* limit integer: The maximum number of items to return per page.

#### Output
* output UploadParts

$3

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

The the enterprise settings determine whether the item will
be permanently deleted from Box or moved to the trash.


`js
box.delete_files_id({
"file_id": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.
* if-match string: Ensures this item hasn't recently changed before

#### Output
Output schema unknown

$3

Retrieves the details about a file.


`js
box.get_files_id({
"file_id": "",
"x-rep-hints": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.
* fields array: A comma-separated list of attributes to include in the
* if-none-match string: Ensures an item is only returned if it has changed.
* boxapi string: The URL, and optional password, for the shared link of this item.
* x-rep-hints required string: A header required to request specific representations

#### Output
* output File

$3

Restores a file that has been moved to the trash.

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


`js
box.post_files_id({
"file_id": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.
* fields array: A comma-separated list of attributes to include in the
* body object
* name string: An optional new name for the file.
* parent
* id string: The ID of parent item

#### Output
* output File

$3

Updates a file. This can be used to rename or move a file,
create a shared link, or lock a file.


`js
box.put_files_id({
"file_id": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.
* fields array: A comma-separated list of attributes to include in the
* if-match string: Ensures this item hasn't recently changed before
* body object
* tags array: The tags for this item. These tags are shown in
* items string
* description string: The description for a file. This can be seen in the right-hand sidebar panel
* lock object: Defines a lock on an item. This prevents the item from being
* access string (values: lock): 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.
* name string: An optional different name for the file. This can be used to
* parent
* id string: The ID of parent item
* permissions object: Defines who can download a file.
* can_download string (values: open, company): Defines who is allowed to download this file. The possible
* shared_link
* access string (values: open, company, collaborators): The level of access for the shared link. This can be
* password string: The password required to access the shared link. Set the
* permissions object
* can_download boolean: If the shared link allows for downloading of files.
* unshared_at string: The timestamp at which this shared link will
* vanity_name string: Defines a custom vanity name to use in the shared link URL,

#### Output
* output File

$3

Adds a shared link to a file.


`js
box.files.file_id_add_shared_link.put({
"file_id": "",
"fields": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.
* fields required string: Explicitly request the shared_link fields
* body object
* shared_link object: The settings for the shared link to create on the file.
* access string (values: open, company, collaborators): The level of access for the shared link. This can be
* password string: The password required to access the shared link. Set the
* permissions object
* can_download boolean: If the shared link allows for downloading of files.
* unshared_at string: The timestamp at which this shared link will
* vanity_name string: Defines a custom vanity name to use in the shared link URL,

#### Output
* output File

$3

Gets the information for a shared link on a file.


`js
box.files.file_id_get_shared_link.get({
"file_id": "",
"fields": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.
* fields required string: Explicitly request the shared_link fields

#### Output
* output File

$3

Removes a shared link from a file.


`js
box.files.file_id_remove_shared_link.put({
"file_id": "",
"fields": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.
* fields required string: Explicitly request the shared_link fields
* body object
* shared_link object: By setting this value to null, the shared link

#### Output
* output File

$3

Updates a shared link on a file.


`js
box.files.file_id_update_shared_link.put({
"file_id": "",
"fields": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.
* fields required string: Explicitly request the shared_link fields
* body object
* shared_link object: The settings for the shared link to update.
* access string (values: open, company, collaborators): The level of access for the shared link. This can be
* password string: The password required to access the shared link. Set the
* permissions object
* can_download boolean: If the shared link allows for downloading of files.
* unshared_at string: The timestamp at which this shared link will
* vanity_name string: Defines a custom vanity name to use in the shared link URL,

#### Output
* output File

$3

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


`js
box.get_files_id_collaborations({
"file_id": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.
* fields array: A comma-separated list of attributes to include in the
* limit integer: The maximum number of items to return per page.
* marker string: Defines the position marker at which to begin returning results. This is

#### Output
* output Collaborations

$3

Retrieves a list of comments for a file.


`js
box.get_files_id_comments({
"file_id": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.
* fields array: A comma-separated list of attributes to include in the
* limit integer: The maximum number of items to return per page.
* offset integer: The offset of the item at which to begin the response.

#### Output
* output Comments

$3

Returns the contents of a file in binary format.


`js
box.get_files_id_content({
"file_id": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.
* range string: The byte range of the content to download.
* boxapi string: The URL, and optional password, for the shared link of this item.
* version string: The file version to download
* access_token string: 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.

#### Output
Output schema unknown

$3

Update a file's content. For file sizes over 50MB we recommend
using the Chunk Upload APIs.

Request body order

The attributes part of the body must come before the
file part. Requests that do not follow this format when
uploading the file will receive a HTTP 400 error with a
metadata_after_file_contents error code.


`js
box.post_files_id_content({
"file_id": "",
"attributes": {},
"file": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.
* if-match string: Ensures this item hasn't recently changed before
* fields array: A comma-separated list of attributes to include in the
* content-md5 string: An optional header containing the SHA1 hash of the file to
* attributes required object: The additional attributes of the file being uploaded. Mainly the
* file required string: The content of the file to upload to Box.

#### Output
* output Files

$3

Creates a copy of a file.


`js
box.post_files_id_copy({
"file_id": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.
* fields array: A comma-separated list of attributes to include in the
* body object
* name string: An optional new name for the copied file.
* parent required object: The destination folder to copy the file to.
* id required string: The ID of folder to copy the file to.
* version string: An optional ID of the specific file version to copy.

#### Output
* output File

$3

Retrieves all metadata for a given file.


`js
box.get_files_id_metadata({
"file_id": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.

#### Output
* output Metadatas

$3

Removes any classifications from a file.

This API can also be called by including the enterprise ID in the
URL explicitly, for example
/files/:id//enterprise_12345/securityClassification-6VMVochwUWo.


`js
box.files.file_id.metadata.enterprise.securityClassification_6VMVochwUWo.delete({
"file_id": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.

#### Output
Output schema unknown

$3

Retrieves the classification metadata instance that
has been applied to a file.

This API can also be called by including the enterprise ID in the
URL explicitly, for example
/files/:id//enterprise_12345/securityClassification-6VMVochwUWo.


`js
box.files.file_id.metadata.enterprise.securityClassification_6VMVochwUWo.get({
"file_id": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.

#### Output
* output Classification

$3

Adds a classification to a file by specifying the label of the
classification to add.

This API can also be called by including the enterprise ID in the
URL explicitly, for example
/files/:id//enterprise_12345/securityClassification-6VMVochwUWo.


`js
box.files.file_id.metadata.enterprise.securityClassification_6VMVochwUWo.post({
"file_id": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.
* body object
* Box__Security__Classification__Key string: The name of the classification to apply to this file.

#### Output
* output Classification

$3

Updates a classification on a file.

The classification can only be updated if a classification has already been
applied to the file before. When editing classifications, only values are
defined for the enterprise will be accepted.


`js
box.files.file_id.metadata.enterprise.securityClassification_6VMVochwUWo.put({
"file_id": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.
* body array: A list containing the one change to make, to
* items object: The operation to perform on the classification
* op string (values: replace): replace
* path string (values: /Box__Security__Classification__Key): /Box__Security__Classification__Key
* value string: The name of the classification to apply to this file.

#### Output
* output Classification

$3

Removes any Box Skills cards metadata from a file.


`js
box.delete_files_id_metadata_global_boxSkillsCards({
"file_id": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.

#### Output
Output schema unknown

$3

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


`js
box.get_files_id_metadata_global_boxSkillsCards({
"file_id": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.

#### Output
* output SkillCardsMetadata

$3

Applies one or more Box Skills metadata cards to a file.


`js
box.post_files_id_metadata_global_boxSkillsCards({
"file_id": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.
* body object
* cards required array: A list of Box Skill cards to apply to this file.

#### Output
* output SkillCardsMetadata

$3

Updates one or more Box Skills metadata cards to a file.


`js
box.put_files_id_metadata_global_boxSkillsCards({
"file_id": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.
* body array: A JSON-Patch
* items object: An operation that replaces an existing card.
* op string (values: replace): replace
* path string: The JSON Path that represents the card to replace. In most cases
* value

#### Output
* output SkillCardsMetadata

$3

Deletes a piece of file metadata.


`js
box.delete_files_id_metadata_id_id({
"file_id": "",
"scope": "",
"template_key": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.
* scope required string (values: global, enterprise): The scope of the metadata template
* template_key required string: The name of the metadata template

#### Output
Output schema unknown

$3

Retrieves the instance of a metadata template that has been applied to a
file.


`js
box.get_files_id_metadata_id_id({
"file_id": "",
"scope": "",
"template_key": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.
* scope required string (values: global, enterprise): The scope of the metadata template
* template_key required string: The name of the metadata template

#### Output
* output Metadata

$3

Applies an instance of a metadata template to a file.

In most cases only values that are present in the metadata template
will be accepted, except for the global.properties template which accepts
any key-value pair.


`js
box.post_files_id_metadata_id_id({
"file_id": "",
"scope": "",
"template_key": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.
* scope required string (values: global, enterprise): The scope of the metadata template
* template_key required string: The name of the metadata template
* body object

#### Output
* output Metadata

$3

Updates a piece of metadata on a file.

The metadata instance can only be updated if the template has already been
applied to the file before. When editing metadata, only values that match
the metadata template schema will be accepted.

The update is applied atomically. If any errors occur during the
application of the operations, the metadata instance will not be changed.


`js
box.put_files_id_metadata_id_id({
"file_id": "",
"scope": "",
"template_key": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.
* scope required string (values: global, enterprise): The scope of the metadata template
* template_key required string: The name of the metadata template
* body array: A JSON-Patch
* items object: A JSON-Patch operation for a
* from string: The location in the metadata JSON object to move or copy a value
* op string (values: add, replace, remove, test, move, copy): The type of change to perform on the template. Some
* path string: The location in the metadata JSON object
* value string: The value to be set or tested.

#### Output
* output Metadata

$3

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


`js
box.get_files_id_tasks({
"file_id": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.

#### Output
* output Tasks

$3

Retrieves a thumbnail, or smaller image representation, of a file.

Sizes of 32x32,64x64, 128x128, and 256x256 can be returned in
the .png format and sizes of 32x32, 94x94, 160x160, and 320x320
can be returned in the .jpg format.

Thumbnails can be generated for the image and video file formats listed
[found on our community site][1].

[1]: https://community.box.com/t5/Migrating-and-Previewing-Content/File-Types-and-Fonts-Supported-in-Box-Content-Preview/ta-p/327


`js
box.get_files_id_thumbnail_id({
"file_id": "",
"extension": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.
* extension required string (values: png, jpg): The file format for the thumbnail
* min_height integer: The minimum height of the thumbnail
* min_width integer: The minimum width of the thumbnail
* max_height integer: The maximum height of the thumbnail
* max_width integer: The maximum width of the thumbnail

#### Output
* output string: The thumbnail

$3

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


`js
box.delete_files_id_trash({
"file_id": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.

#### Output
Output schema unknown

$3

Retrieves a file that has been moved to the trash.

Please note that only if the file itself has been moved to the
trash can it be retrieved with this API call. If instead one of
its parent folders was moved to the trash, only that folder
can be inspected using the
GET /folders/:id/trash API.

To list all items that have been moved to the trash, please
use the GET /folders/trash/items
API.


`js
box.get_files_id_trash({
"file_id": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.
* fields array: A comma-separated list of attributes to include in the

#### Output
* output File

$3

Creates an upload session for an existing file.


`js
box.post_files_id_upload_sessions({
"file_id": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.
* body object
* file_name string: The optional new name of new file
* file_size required integer: The total number of bytes of the file to be uploaded

#### Output
* output UploadSession

$3

Retrieve a list of the past versions for a file.

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


`js
box.get_files_id_versions({
"file_id": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.
* fields array: A comma-separated list of attributes to include in the
* limit integer: The maximum number of items to return per page.
* offset integer: The offset of the item at which to begin the response.

#### Output
* output FileVersions

$3

Revert to a previous version of a file.

If previous versions exist, this method can be used to
promote one of the older versions to the top of the version history.

This actually creates a new copy of the old version and puts it at the
top of the versions history. The file will have the exact same contents
as the older version, with the the same hash digest, etag, and
name as the original.

Other properties such as comments do not get updated to their
former values.


`js
box.post_files_id_versions_current({
"file_id": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.
* fields array: A comma-separated list of attributes to include in the
* body object: The file version to revert to
* id string: The file version ID
* type string (values: file_version): The type to revert to

#### Output
* output FileVersion

$3

Move a file version to the trash.

Versions are only tracked for Box users with premium accounts.


`js
box.delete_files_id_versions_id({
"file_id": "",
"file_version_id": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.
* file_version_id required string: The ID of the file version
* if-match string: Ensures this item hasn't recently changed before

#### Output
Output schema unknown

$3

Retrieve a specific version of a file.

Versions are only tracked for Box users with premium accounts.


`js
box.get_files_id_versions_id({
"file_id": "",
"file_version_id": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.
* fields array: A comma-separated list of attributes to include in the
* file_version_id required string: The ID of the file version

#### Output
* output FileVersion

$3

Removes the watermark from a file.


`js
box.delete_files_id_watermark({
"file_id": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.

#### Output
Output schema unknown

$3

Retrieve the watermark for a file.


`js
box.get_files_id_watermark({
"file_id": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.

#### Output
* output Watermark

$3

Applies or update a watermark on a file.


`js
box.put_files_id_watermark({
"file_id": ""
}, context)
`

#### Input
* input object
* file_id required string: The unique identifier that represent a file.
* body object
* watermark required object: The watermark to imprint on the file
* imprint required string (values: default): The type of watermark to apply.

#### Output
* output Watermark

$3

Retrieves folder lock details for a given folder.


`js
box.get_folder_locks({
"folder_id": ""
}, context)
`

#### Input
* input object
* folder_id required string: The unique identifier that represent a folder.

#### Output
* output FolderLocks

$3

Creates a folder lock on a folder, preventing it from being moved and/or
deleted.


`js
box.post_folder_locks({}, context)
`

#### Input
* input object
* body object
* folder required object: The folder to apply the lock to.
* id required string: The ID of the folder.
* type required string: The content type the lock is being applied to. Only folder
* locked_operations object: The operations to lock for the folder. If locked_operations is
* delete required boolean: Whether deleting the folder should be locked.
* move required boolean: Whether moving the folder should be locked.

#### Output
* output FolderLock

$3

Deletes a folder lock on a given folder.


`js
box.delete_folder_locks_id({
"folder_lock_id": ""
}, context)
`

#### Input
* input object
* folder_lock_id required string: The ID of the folder lock.

#### Output
Output schema unknown

$3

Creates a new empty folder within the specified parent folder.


`js
box.post_folders({}, context)
`

#### Input
* input object
* fields array: A comma-separated list of attributes to include in the
* body object
* folder_upload_email
* access string (values: open, collaborators): When this parameter has been set, users can email files
* name required string: The name for the new folder.
* parent required object: The parent folder to create the new folder within.
* id required string: The ID of parent folder
* sync_state string (values: synced, not_synced, partially_synced): Specifies whether a folder should be synced to a

#### Output
* output Folder

$3

Retrieves the files and folders that have been moved
to the trash.

Any attribute in the full files or folders objects can be passed
in with the fields parameter to retrieve those specific
attributes that are not returned by default.

This endpoint defaults to use offset-based pagination, yet also supports
marker-based pagination using the marker parameter.


`js
box.get_folders_trash_items({}, context)
`

#### Input
* input object
* fields array: A comma-separated list of attributes to include in the
* limit integer: The maximum number of items to return per page.
* offset integer: The offset of the item at which to begin the response.
* usemarker boolean: Specifies whether to use marker-based pagination instead of
* marker string: Defines the position marker at which to begin returning results. This is
* direction string (values: ASC, DESC): The direction to sort results in. This can be either in alphabetical ascending
* sort string (values: id, name, date, size): Defines the second attribute by which items

#### Output
* output Items

$3

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


`js
box.delete_folders_id({
"folder_id": ""
}, context)
`

#### Input
* input object
* folder_id required string: The unique identifier that represent a folder.
* if-match string: Ensures this item hasn't recently changed before
* recursive boolean: Delete a folder that is not empty by recursively deleting the

#### Output
Output schema unknown

$3

Retrieves details for 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.


`js
box.get_folders_id({
"folder_id": ""
}, context)
`

#### Input
* input object
* folder_id required string: The unique identifier that represent a folder.
* fields array: A comma-separated list of attributes to include in the
* if-none-match string: Ensures an item is only returned if it has changed.
* boxapi string: The URL, and optional password, for the shared link of this item.

#### Output
* output Folder

$3

Restores a folder that has been moved to the trash.

An optional new parent ID can be provided to restore the folder to in case the
original folder has been deleted.

Folder locking

During this operation, part of the file tree will be locked, mainly
the source folder and all of its descendants, as well as the destination
folder.

For the duration of the operation, no other move, copy, delete, or restore
operation can performed on any of the locked folders.


`js
box.post_folders_id({
"folder_id": ""
}, context)
`

#### Input
* input object
* folder_id required string: The unique identifier that represent a folder.
* fields array: A comma-separated list of attributes to include in the
* body object
* name string: An optional new name for the folder.
* parent
* id string: The ID of parent item

#### Output
* output Folder

$3

Updates a folder. This can be also be used to move the folder,
create shared links, update collaborations, and more.


`js
box.put_folders_id({
"folder_id": ""
}, context)
`

#### Input
* input object
* folder_id required string: The unique identifier that represent a folder.
* fields array: A comma-separated list of attributes to include in the
* if-match string: Ensures this item hasn't recently changed before
* body object
* tags array: The tags for this item. These tags are shown in
* items string
* can_non_owners_invite boolean: Specifies if users who are not the owner
* can_non_owners_view_collaborators boolean: Restricts collaborators who are not the owner of
* collections array: An array of collections to make this folder
* items object: The bare basic reference for an object
* id string: The unique identifier for this object
* type string: The type for this object
* description string: The optional description of this folder
* folder_upload_email
* access string (values: open, collaborators): When this parameter has been set, users can email files
* is_collaboration_restricted_to_enterprise boolean: Specifies if new invites to this folder are restricted to users
* name string: The optional new name for this folder.
* parent object: The parent folder for this folder. Use this to move
* id string: The ID of the new parent folder
* shared_link
* access string (values: open, company, collaborators): The level of access for the shared link. This can be
* password string: The password required to access the shared link. Set the
* permissions object
* can_download boolean: If the shared link allows for downloading of files.
* unshared_at string: The timestamp at which this shared link will
* vanity_name string: Defines a custom vanity name to use in the shared link URL,
* sync_state string (values: synced, not_synced, partially_synced): Specifies whether a folder should be synced to a

#### Output
* output Folder

$3

Adds a shared link to a folder.


`js
box.folders.folder_id_add_shared_link.put({
"folder_id": "",
"fields": ""
}, context)
`

#### Input
* input object
* folder_id required string: The unique identifier that represent a folder.
* fields required string: Explicitly request the shared_link fields
* body object
* shared_link object: The settings for the shared link to create on the folder.
* access string (values: open, company, collaborators): The level of access for the shared link. This can be
* password string: The password required to access the shared link. Set the
* permissions object
* can_download boolean: If the shared link allows for downloading of folders.
* unshared_at string: The timestamp at which this shared link will

#### Output
* output Folder

$3

Gets the information for a shared link on a folder.


`js
box.folders.folder_id_get_shared_link.get({
"folder_id": "",
"fields": ""
}, context)
`

#### Input
* input object
* folder_id required string: The unique identifier that represent a folder.
* fields required string: Explicitly request the shared_link fields

#### Output
* output Folder

$3

Removes a shared link from a folder.


`js
box.folders.folder_id_remove_shared_link.put({
"folder_id": "",
"fields": ""
}, context)
`

#### Input
* input object
* folder_id required string: The unique identifier that represent a folder.
* fields required string: Explicitly request the shared_link fields
* body object
* shared_link object: By setting this value to null, the shared link

#### Output
* output Folder

$3

Updates a shared link on a folder.


`js
box.folders.folder_id_update_shared_link.put({
"folder_id": "",
"fields": ""
}, context)
`

#### Input
* input object
* folder_id required string: The unique identifier that represent a folder.
* fields required string: Explicitly request the shared_link fields
* body object
* shared_link object: The settings for the shared link to update.
* access string (values: open, company, collaborators): The level of access for the shared link. This can be
* password string: The password required to access the shared link. Set the
* permissions object
* can_download boolean: If the shared link allows for downloading of folders.
* unshared_at string: The timestamp at which this shared link will

#### Output
* output Folder

$3

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


`js
box.get_folders_id_collaborations({
"folder_id": ""
}, context)
`

#### Input
* input object
* folder_id required string: The unique identifier that represent a folder.
* fields array: A comma-separated list of attributes to include in the

#### Output
* output Collaborations

$3

Creates a copy of a folder within a destination folder.

The original folder will not be changed.


`js
box.post_folders_id_copy({
"folder_id": ""
}, context)
`

#### Input
* input object
* folder_id required string: The unique identifier of the folder to copy.
* fields array: A comma-separated list of attributes to include in the
* body object
* name string: An optional new name for the copied folder.
* parent required object: The destination folder to copy the folder to.
* id required string: The ID of parent folder

#### Output
* output Folder

$3

Retrieves a page of items in a folder. These items can be files,
folders, and web links.

To request more information about the folder itself, like its size,
please use the Get a folder endpoint instead.


`js
box.get_folders_id_items({
"folder_id": ""
}, context)
`

#### Input
* input object
* folder_id required string: The unique identifier that represent a folder.
* fields array: A comma-separated list of attributes to include in the
* usemarker boolean: Specifies whether to use marker-based pagination instead of
* marker string: Defines the position marker at which to begin returning results. This is
* offset integer: The offset of the item at which to begin the response.
* limit integer: The maximum number of items to return per page.
* boxapi string: The URL, and optional password, for the shared link of this item.
* sort string (values: id, name, date, size): Defines the second attribute by which items
* direction string (values: ASC, DESC): The direction to sort results in. This can be either in alphabetical ascending

#### Output
* output Items

$3


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


`js
box.get_folders_id_metadata({
"folder_id": ""
}, context)
`

#### Input
* input object
* folder_id required string: The unique identifier that represent a folder.

#### Output
* output Metadatas

$3

Removes any classifications from a folder.

This API can also be called by including the enterprise ID in the
URL explicitly, for example
/folders/:id//enterprise_12345/securityClassification-6VMVochwUWo.


`js
box.folders.folder_id.metadata.enterprise.securityClassification_6VMVochwUWo.delete({
"folder_id": ""
}, context)
`

#### Input
* input object
* folder_id required string: The unique identifier that represent a folder.

#### Output
Output schema unknown

$3

Retrieves the classification metadata instance that
has been applied to a folder.

This API can also be called by including the enterprise ID in the
URL explicitly, for example
/folders/:id//enterprise_12345/securityClassification-6VMVochwUWo.


`js
box.folders.folder_id.metadata.enterprise.securityClassification_6VMVochwUWo.get({
"folder_id": ""
}, context)
`

#### Input
* input object
* folder_id required string: The unique identifier that represent a folder.

#### Output
* output Classification

$3

Adds a classification to a folder by specifying the label of the
classification to add.

This API can also be called by including the enterprise ID in the
URL explicitly, for example
/folders/:id//enterprise_12345/securityClassification-6VMVochwUWo.


`js
box.folders.folder_id.metadata.enterprise.securityClassification_6VMVochwUWo.post({
"folder_id": ""
}, context)
`

#### Input
* input object
* folder_id required string: The unique identifier that represent a folder.
* body object
* Box__Security__Classification__Key string: The name of the classification to apply to this folder.

#### Output
* output Classification

$3

Updates a classification on a folder.

The classification can only be updated if a classification has already been
applied to the folder before. When editing classifications, only values are
defined for the enterprise will be accepted.


`js
box.folders.folder_id.metadata.enterprise.securityClassification_6VMVochwUWo.put({
"folder_id": ""
}, context)
`

#### Input
* input object
* folder_id required string: The unique identifier that represent a folder.
* body ar