3.0.0 • Published 5 years ago

@datafire/box v3.0.0

Weekly downloads
1
License
MIT
Repository
github
Last release
5 years ago

@datafire/box

Client library for Box Platform API

Installation and Usage

npm install --save @datafire/box
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

oauthCallback

Exchange the code passed to your redirect URI for an access_token

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

oauthRefresh

Exchange a refresh_token for an access_token

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

get_authorize

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

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

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

get_collaboration_whitelist_entries

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

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

post_collaboration_whitelist_entries

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

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

delete_collaboration_whitelist_entries_id

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

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

get_collaboration_whitelist_entries_id

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

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

get_collaboration_whitelist_exempt_targets

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

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

post_collaboration_whitelist_exempt_targets

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

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

delete_collaboration_whitelist_exempt_targets_id

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

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

get_collaboration_whitelist_exempt_targets_id

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

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

get_collaborations

Retrieves all pending collaboration invites for this user.

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

post_collaborations

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

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

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

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

delete_collaborations_id

Deletes a single collaboration.

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

Input

  • input object
    • collaboration_id required string: The ID of the collaboration

Output

Output schema unknown

get_collaborations_id

Retrieves a single collaboration.

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

put_collaborations_id

Updates a collaboration.

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

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

get_collections

Retrieves all collections for a given user.

Currently, only the favorites collection is supported.

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

get_collections_id_items

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

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

post_comments

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

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

delete_comments_id

Permanently deletes a comment.

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

Input

  • input object
    • comment_id required string: The ID of the comment.

Output

Output schema unknown

get_comments_id

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

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

put_comments_id

Update the message of a comment.

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

delete_device_pinners_id

Deletes an individual device pin.

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

get_device_pinners_id

Retrieves information about an individual device pin.

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

Input

  • input object
    • device_pinner_id required string: The ID of the device pin

Output

get_enterprises_id_device_pinners

Retrieves all the device pins within an enterprise.

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

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

get_events

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

By default this returns events for the authenticated user. To retrieve events for the entire enterprise, set the stream_type to admin_logs. 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.

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

options_events

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

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

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

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

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

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

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

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

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

box.options_events(null, context)

Input

This action has no parameters

Output

delete_file_requests_id

Deletes a file request permanently.

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

get_file_requests_id

Retrieves the information about a file request.

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

put_file_requests_id

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

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

post_file_requests_id_copy

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

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

get_file_version_legal_holds

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

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

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

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

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

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

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

get_file_version_legal_holds_id

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

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

get_file_version_retentions

Retrieves all file version retentions for the given enterprise.

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

get_file_version_retentions_id

Returns information about a file version retention.

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

options_files_content

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

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

post_files_content

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.

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

post_files_upload_sessions

Creates an upload session for a new file.

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

delete_files_upload_sessions_id

Abort an upload session and discard all data uploaded.

This cannot be reversed.

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

get_files_upload_sessions_id

Return information about an upload session.

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

put_files_upload_sessions_id

Updates a chunk of an upload session for a file.

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

post_files_upload_sessions_id_commit

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

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

Output

get_files_upload_sessions_id_parts

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

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

delete_files_id

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

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

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

get_files_id

Retrieves the details about a file.

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

post_files_id

Restores a file that has been moved to the trash.

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

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

put_files_id

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

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

files.file_id_add_shared_link.put

Adds a shared link to a file.

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

files.file_id_get_shared_link.get

Gets the information for a shared link on a file.

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

files.file_id_remove_shared_link.put

Removes a shared link from a file.

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

files.file_id_update_shared_link.put

Updates a shared link on a file.

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

get_files_id_collaborations

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

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

get_files_id_comments

Retrieves a list of comments for a file.

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

get_files_id_content

Returns the contents of a file in binary format.

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

post_files_id_content

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.

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

post_files_id_copy

Creates a copy of a file.

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

get_files_id_metadata

Retrieves all metadata for a given file.

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

Input

  • input object
    • file_id required string: The unique identifier that represent a file.

Output

files.file_id.metadata.enterprise.securityClassification_6VMVochwUWo.delete

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.

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

files.file_id.metadata.enterprise.securityClassification_6VMVochwUWo.get

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.

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

files.file_id.metadata.enterprise.securityClassification_6VMVochwUWo.post

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.

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
      • BoxSecurityClassification__Key string: The name of the classification to apply to this file.

Output

files.file_id.metadata.enterprise.securityClassification_6VMVochwUWo.put

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.

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: /BoxSecurityClassificationKey): `/BoxSecurityClassificationKey`
        • value string: The name of the classification to apply to this file.

Output

delete_files_id_metadata_global_boxSkillsCards

Removes any Box Skills cards metadata from a file.

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

get_files_id_metadata_global_boxSkillsCards

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

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

post_files_id_metadata_global_boxSkillsCards

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

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

put_files_id_metadata_global_boxSkillsCards

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

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

delete_files_id_metadata_id_id

Deletes a piece of file metadata.

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

get_files_id_metadata_id_id

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

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

post_files_id_metadata_id_id

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.

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

put_files_id_metadata_id_id

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.

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

get_files_id_tasks

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

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

Input

  • input object
    • file_id required string: The unique identifier that represent a file.

Output

get_files_id_thumbnail_id

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.

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

delete_files_id_trash

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

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

get_files_id_trash

Retrieves a file that has been moved to the trash.

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

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

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

post_files_id_upload_sessions

Creates an upload session for an existing file.

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

get_files_id_versions

Retrieve a list of the past versions for a file.

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

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

post_files_id_versions_current

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.

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

delete_files_id_versions_id

Move a file version to the trash.

Versions are only tracked for Box users with premium accounts.

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

get_files_id_versions_id

Retrieve a specific version of a file.

Versions are only tracked for Box users with premium accounts.

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

delete_files_id_watermark

Removes the watermark from a file.

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

get_files_id_watermark

Retrieve the watermark for a file.

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

Input

  • input object
    • file_id required string: The unique identifier that represent a file.

Output

put_files_id_watermark

Applies or update a watermark on a file.

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

get_folder_locks

Retrieves folder lock details for a given folder.

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

Input

  • input object
    • folder_id required string: The unique identifier that represent a folder.

Output

post_folder_locks

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

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

delete_folder_locks_id

Deletes a folder lock on a given folder.

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

post_folders

Creates a new empty folder within the specified parent folder.

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

get_folders_trash_items

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

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

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

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

delete_folders_id

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

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

get_folders_id

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.

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

post_folders_id

Restores a folder that has been moved to the trash.

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

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.

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

put_folders_id

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

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

folders.folder_id_add_shared_link.put

Adds a shared link to a folder.

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

folders.folder_id_get_shared_link.get

Gets the information for a shared link on a folder.

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

folders.folder_id_remove_shared_link.put

Removes a shared link from a folder.

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

folders.folder_id_update_shared_link.put

Updates a shared link on a folder.

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

get_folders_id_collaborations

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

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

post_folders_id_copy

Creates a copy of a folder within a destination folder.

The original folder will not be changed.

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

get_folders_id_items

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

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

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

get_folders_id_metadata

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

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

Input

  • input object
    • folder_id required string: The unique identifier that represent a folder.

Output

folders.folder_id.metadata.enterprise.securityClassification_6VMVochwUWo.delete

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.

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

folders.folder_id.metadata.enterprise.securityClassification_6VMVochwUWo.get

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.

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

folders.folder_id.metadata.enterprise.securityClassification_6VMVochwUWo.post

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.

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
      • BoxSecurityClassification__Key string: The name of the classification to apply to this folder.

Output

folders.folder_id.metadata.enterprise.securityClassification_6VMVochwUWo.put

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.

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