@lap v0.3 # Machine-readable API spec. Each @endpoint block is one API call. @api Box Platform API @base https://api.box.com/2.0 @version 2024.0 @auth OAuth2 @endpoints 296 @hint download_for_search @toc authorize(1), oauth2(3), files(48), file_requests(4), folders(28), folder_locks(3), metadata_templates(13), metadata_cascade_policies(5), metadata_queries(1), comments(4), collaborations(5), search(1), tasks(5), task_assignments(4), shared_items(1), shared_items#folders(1), web_links(11), shared_items#web_links(1), shared_items#app_items(1), users(15), invites(2), groups(8), group_memberships(4), webhooks(5), skill_invocations(1), events(2), collections(3), recent_items(1), retention_policies(6), retention_policy_assignments(5), legal_hold_policies(5), legal_hold_policy_assignments(6), file_version_retentions(2), file_version_legal_holds(2), shield_information_barriers(4), shield_information_barrier_reports(3), shield_information_barrier_segments(5), shield_information_barrier_segment_members(4), shield_information_barrier_segment_restrictions(4), device_pinners(2), enterprises(1), terms_of_services(4), terms_of_service_user_statuses(3), collaboration_whitelist_entries(4), collaboration_whitelist_exempt_targets(4), storage_policies(2), storage_policy_assignments(5), zip_downloads(3), sign_requests(5), workflows(2), sign_templates(2), integration_mappings(8), ai(4), ai_agent_default(1), ai_agents(5), metadata_taxonomies(14) @group authorize @endpoint GET /authorize @desc Authorize user @required {response_type: str(token) # The type of response we'd like to receive., client_id: str # The Client ID of the application that is requesting to authenticate the user. To get the Client ID for your application, log in to your Box developer console and click the **Edit Application** link for the application you're working with. In the OAuth 2.0 Parameters section of the configuration page, find the item labelled `client_id`. The text of that item is your application's Client ID.} @optional {redirect_uri: str(url) # The URI to which Box redirects the browser after the user has granted or denied the application permission. This URI match one of the redirect URIs in the configuration of your application. It must be a valid HTTPS URI and it needs to be able to handle the redirection to complete the next step in the OAuth 2.0 flow. Although this parameter is optional, it must be a part of the authorization URL if you configured multiple redirect URIs for the application in the developer console. A missing parameter causes a `redirect_uri_missing` error after the user grants application access., state: str # A custom string of your choice. Box will pass the same string to the redirect URL when authentication is complete. This parameter can be used to identify a user on redirect, as well as protect against hijacked sessions and other exploits., scope: str # A space-separated list of application scopes you'd like to authenticate the user for. This defaults to all the scopes configured for the application in its configuration page.} @returns(200) Does not return any data, but rather should be used in the browser. @endgroup @group oauth2 @endpoint POST /oauth2/token @desc Request access token @returns(200) {access_token: str(token), expires_in: int(int64), token_type: str, restricted_to: [map], refresh_token: str(token), issued_token_type: str(urn)} # Returns a new Access Token that can be used to make authenticated API calls by passing along the token in a authorization header as follows `Authorization: Bearer `. @errors {400: An authentication error.} @endpoint POST /oauth2/token#refresh @desc Refresh access token @returns(200) {access_token: str(token), expires_in: int(int64), token_type: str, restricted_to: [map], refresh_token: str(token), issued_token_type: str(urn)} # Returns a new Access Token that can be used to make authenticated API calls by passing along the token in a authorization header as follows `Authorization: Bearer `. @errors {400: An authentication error.} @endpoint POST /oauth2/revoke @desc Revoke access token @returns(200) Returns an empty response when the token was successfully revoked. @errors {400: An authentication error.} @endgroup @group files @endpoint GET /files/{file_id} @desc Get file information @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. Additionally this field can be used to query any metadata applied to the file by specifying the `metadata` field as well as the scope and key of the template to retrieve, for example `?fields=metadata.enterprise_12345.contractTemplate`., if-none-match: str # Ensures an item is only returned if it has changed. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `304 Not Modified` if the item has not changed since., boxapi: str # The URL, and optional password, for the shared link of this item. This header can be used to access items that have not been explicitly shared with a user. Use the format `shared_link=[link]` or if a password is required then use `shared_link=[link]&shared_link_password=[password]`. This header can be used on the file or folder shared, as well as on any files or folders nested within the item., x-rep-hints: str # A header required to request specific `representations` of a file. Use this in combination with the `fields` query parameter to request a specific file representation. The general format for these representations is `X-Rep-Hints: [...]` where `[...]` is one or many hints in the format `[fileType?query]`. For example, to request a `png` representation in `32x32` as well as `64x64` pixel dimensions provide the following hints. `x-rep-hints: [jpg?dimensions=32x32][jpg?dimensions=64x64]` Additionally, a `text` representation is available for all document file types in Box using the `[extracted_text]` representation. `x-rep-hints: [extracted_text]`.} @returns(200) Returns a file object. Not all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields. @errors {304: Returns an empty response when the `If-None-Match` header matches the current `etag` value of the folder. This indicates that the folder has not changed since it was last requested., 401: Returned when the access token provided in the `Authorization` header is not recognized or not provided., 404: Returned if the file is not found, or the user does not have access to the file., 405: Returned if the `file_id` is not in a recognized format., 415: Returns an error if an action is performed on a file with an incorrect media type. * `unsupported_media_type` when requesting an `expiring_embed_link` for a file that is not supported by Box Embed.} @endpoint POST /files/{file_id} @desc Restore file @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., name: str # An optional new name for the file., parent: any} @returns(201) {id: str, etag: str?, type: str, sequence_id: any, name: str, sha1: str(digest), file_version: any, description: str, size: int, path_collection: any, created_at: str(date-time), modified_at: str(date-time), trashed_at: str?, purged_at: str?, content_created_at: str(date-time)?, content_modified_at: str(date-time)?, created_by: any, modified_by: any, owned_by: any, shared_link: str?, parent: any, item_status: str} # Returns a file object when the file has been restored. @errors {403: Returns an error if the user does not have access to the folder the file is being restored to, or the user does not have permission to restore files from the trash., 404: Returns an error if the file is not in the trash., 409: Returns an error if there is an file with the same name in the folder the file is being restored to.} @endpoint PUT /files/{file_id} @desc Update file @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., if-match: str # Ensures this item hasn't recently changed before making changes. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `412 Precondition Failed` if it has changed since., name: str # An optional different name for the file. This can be used to rename the file. File names must be unique within their parent folder. The name check is case-insensitive, so a file named `New File` cannot be created in a parent folder that already contains a folder named `new file`., description: str # The description for a file. This can be seen in the right-hand sidebar panel when viewing a file in the Box web app. Additionally, this index is used in the search index of the file, allowing users to find the file by the content in the description., parent: any, shared_link: any, lock: map{access: str, expires_at: str(date-time), is_download_prevented: bool} # Defines a lock on an item. This prevents the item from being moved, renamed, or otherwise changed by anyone other than the user who created the lock. Set this to `null` to remove the lock., disposition_at: str(date-time) # The retention expiration timestamp for the given file. This date cannot be shortened once set on a file., permissions: map{can_download: str} # Defines who can download a file., collections: [map{id: str, type: str}] # An array of collections to make this file a member of. Currently we only support the `favorites` collection. To get the ID for a collection, use the [List all collections][1] endpoint. Passing an empty array `[]` or `null` will remove the file from all collections. [1]: https://developer.box.com/reference/get-collections, tags: [str] # The tags for this item. These tags are shown in the Box web app and mobile apps next to an item. To add or remove a tag, retrieve the item's current tags, modify them, and then update this field. There is a limit of 100 tags per item, and 10,000 unique tags per enterprise.} @returns(200) Returns a file object. Not all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields. @errors {400: Returned when the new retention time > maximum retention length., 401: Returned when the access token provided in the `Authorization` header is not recognized or not provided., 403: Returned if the user does not have all the permissions to complete the update. * `access_denied_insufficient_permissions` returned when the authenticated user does not have access to the destination folder to move the file to. * Returned when retention time is shorter or equal to current retention timestamp. * Returned when a `file_id` that is not under retention is entered. * Returned when a file that is retained but the disposition action is set to `remove_retention` * `forbidden_by_policy` is returned if copying a folder is forbidden due to information barrier restrictions., 404: Returned if the file is not found, or the user does not have access to the file., 405: Returned if the `file_id` is not in a recognized format., 412: Returns an error when the `If-Match` header does not match the current `etag` value of the file. This indicates that the file has changed since it was last requested.} @endpoint DELETE /files/{file_id} @desc Delete file @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.} @optional {if-match: str # Ensures this item hasn't recently changed before making changes. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `412 Precondition Failed` if it has changed since.} @returns(204) Returns an empty response when the file has been successfully deleted. @errors {401: Returned when the access token provided in the `Authorization` header is not recognized or not provided., 404: Returned if the file is not found or has already been deleted, or the user does not have access to the file., 405: Returned if the `file_id` is not in a recognized format., 412: Returns an error when the `If-Match` header does not match the current `etag` value of the file. This indicates that the file has changed since it was last requested.} @endpoint GET /files/{file_id}/app_item_associations @desc List file app item associations @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.} @optional {limit: int(int64) # The maximum number of items to return per page., marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`., application_type: str # If given, only return app items for this application type.} @returns(200) Returns a collection of app item objects. If there are no app items on this file, an empty collection will be returned. This list includes app items on ancestors of this File. @errors {404: Returned if the file is not found, or the user does not have access to the file.} @endpoint GET /files/{file_id}/content @desc Download file @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.} @optional {range: str # The byte range of the content to download. The format `bytes={start_byte}-{end_byte}` can be used to specify what section of the file to download., boxapi: str # The URL, and optional password, for the shared link of this item. This header can be used to access items that have not been explicitly shared with a user. Use the format `shared_link=[link]` or if a password is required then use `shared_link=[link]&shared_link_password=[password]`. This header can be used on the file or folder shared, as well as on any files or folders nested within the item., version: str # The file version to download., access_token: str # An optional access token that can be used to pre-authenticate this request, which means that a download link can be shared with a browser or a third party service without them needing to know how to handle the authentication. When using this parameter, please make sure that the access token is sufficiently scoped down to only allow read access to that file and no other files or folders.} @returns(200) Returns the requested file if the client has the **follow redirects** setting enabled to automatically follow HTTP `3xx` responses as redirects. If not, the request will return `302` instead. For details, see the [download file guide](https://developer.box.com/guides/downloads/file#download-url). @returns(202) If the file is not ready to be downloaded yet `Retry-After` header will be returned indicating the time in seconds after which the file will be available for the client to download. This response can occur when the file was uploaded immediately before the download request. @errors {302: If the file is available for download the response will include a `Location` header for the file on `dl.boxcloud.com`. The `dl.boxcloud.com` URL is not persistent and clients will need to follow the redirect to actually download the file.} @endpoint POST /files/{file_id}/content @desc Upload file version @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.} @optional {if-match: str # Ensures this item hasn't recently changed before making changes. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `412 Precondition Failed` if it has changed since., fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., content-md5: str # An optional header containing the SHA1 hash of the file to ensure that the file was not corrupted in transit.} @returns(200) {total_count: int(int64), entries: [map]} # Returns the new file object in a list. @errors {412: Returns an error when the `If-Match` header does not match the current `etag` value of the file. This indicates that the file has changed since it was last requested.} @endpoint OPTIONS /files/content @desc Preflight check before upload @optional {name: str # The name for the file., size: int(int32) # The size of the file in bytes., parent: any} @returns(200) {upload_url: str, upload_token: str} # If the check passed, the response will include a session URL that can be used to upload the file to. @errors {409: If the check did not pass, the response will include some details on why it did not pass.} @endpoint POST /files/content @desc Upload file @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., content-md5: str # An optional header containing the SHA1 hash of the file to ensure that the file was not corrupted in transit.} @returns(201) {total_count: int(int64), entries: [map]} # Returns the new file object in a list. @errors {400: Returns an error if some of the parameters are missing or not valid. * `bad_request` when a parameter is missing or incorrect. * `item_name_too_long` when the folder name is too long. * `item_name_invalid` when the folder name contains non-valid characters., 404: Returns an error if the parent folder does not exist or if the user is not authorized to access the parent folder., 409: Returns an error if the file already exists, or the account has run out of disk space.} @endpoint POST /files/upload_sessions @desc Create upload session @required {folder_id: str # The ID of the folder to upload the new file to., file_size: int(int64) # The total number of bytes of the file to be uploaded., file_name: str # The name of new file.} @returns(201) {id: str, type: str, session_expires_at: str(date-time), part_size: int(int64), total_parts: int(int32), num_parts_processed: int(int32), session_endpoints: any} # Returns a new upload session. @errors {400: Returns an error if some of the parameters are missing or not valid. * `missing_destination`: No `folder_id` was provided. * `invalid_folder_id`: `folder_id` is not valid. * `item_name_invalid`: `file_name` is not valid. * `missing_file_size`: `file_size` was not provided. * `invalid_file_size`: `file_size` was not a valid number. * `file_size_too_small`: `file_size` is below minimum file size for uploads via this API. * `missing_file_name`: `file_name` was not provided., 403: Returns an error if the operation is not allowed for some reason. * `storage_limit_exceeded`: Account storage limit reached., 404: Returns an error if the parent folder could not be found, or the authenticated user does not have access to it. * `invalid_parameter`: The `folder_id` value represents a folder that the user does not have access to, or does not exist., 409: Returns an error if the file already exists, or the account has run out of disk space.} @endpoint POST /files/{file_id}/upload_sessions @desc Create upload session for existing file @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`., file_size: int(int64) # The total number of bytes of the file to be uploaded.} @optional {file_name: str # The optional new name of new file.} @returns(201) {id: str, type: str, session_expires_at: str(date-time), part_size: int(int64), total_parts: int(int32), num_parts_processed: int(int32), session_endpoints: any} # Returns a new upload session. @errors {409: Returns an error if the file already exists, or if the account has run out of disk space.} @endpoint GET /files/upload_sessions/{upload_session_id} @desc Get upload session @required {upload_session_id: str # The ID of the upload session.} @returns(200) {id: str, type: str, session_expires_at: str(date-time), part_size: int(int64), total_parts: int(int32), num_parts_processed: int(int32), session_endpoints: any} # Returns an upload session object. @endpoint PUT /files/upload_sessions/{upload_session_id} @desc Upload part of file @required {upload_session_id: str # The ID of the upload session., digest: str # The [RFC3230][1] message digest of the chunk uploaded. Only SHA1 is supported. The SHA1 digest must be base64 encoded. The format of this header is as `sha=BASE64_ENCODED_DIGEST`. To get the value for the `SHA` digest, use the openSSL command to encode the file part: `openssl sha1 -binary | base64`. [1]: https://tools.ietf.org/html/rfc3230, content-range: str # The byte range of the chunk. Must not overlap with the range of a part already uploaded this session. Each part’s size must be exactly equal in size to the part size specified in the upload session that you created. One exception is the last part of the file, as this can be smaller. When providing the value for `content-range`, remember that: * The lower bound of each part's byte range must be a multiple of the part size. * The higher bound must be a multiple of the part size - 1.} @returns(200) {part: map} # Chunk has been uploaded successfully. @errors {409: Returns an error if the chunk conflicts with another chunk previously uploaded., 412: Returns an error if a precondition was not met., 416: Returns an error if the content range does not match a specified range for the session.} @endpoint DELETE /files/upload_sessions/{upload_session_id} @desc Remove upload session @required {upload_session_id: str # The ID of the upload session.} @returns(204) A blank response is returned if the session was successfully aborted. @endpoint GET /files/upload_sessions/{upload_session_id}/parts @desc List parts @required {upload_session_id: str # The ID of the upload session.} @optional {offset: int(int64)=0 # The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response., limit: int(int64) # The maximum number of items to return per page.} @returns(200) Returns a list of parts that have been uploaded. @endpoint POST /files/upload_sessions/{upload_session_id}/commit @desc Commit upload session @required {upload_session_id: str # The ID of the upload session., digest: str # The [RFC3230][1] message digest of the whole file. Only SHA1 is supported. The SHA1 digest must be Base64 encoded. The format of this header is as `sha=BASE64_ENCODED_DIGEST`. [1]: https://tools.ietf.org/html/rfc3230, parts: [map] # The list details for the uploaded parts.} @optional {if-match: str # Ensures this item hasn't recently changed before making changes. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `412 Precondition Failed` if it has changed since., if-none-match: str # Ensures an item is only returned if it has changed. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `304 Not Modified` if the item has not changed since.} @returns(201) {total_count: int(int64), entries: [map]} # Returns the file object in a list. @returns(202) Returns when all chunks have been uploaded but not yet processed. Inspect the upload session to get more information about the progress of processing the chunks, then retry committing the file when all chunks have processed. @errors {409: Returns an error if there is already a file with the same name in the target folder., 412: Returns an error if the `If-Match` or `If-None-Match` conditions fail.} @endpoint POST /files/{file_id}/copy @desc Copy file @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`., parent: map{id!: str} # The destination folder to copy the file to.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., name: str # An optional new name for the copied file. There are some restrictions to the file name. Names containing non-printable ASCII characters, forward and backward slashes (`/`, `\`), and protected names like `.` and `..` are automatically sanitized by removing the non-allowed characters., version: str # An optional ID of the specific file version to copy.} @returns(201) Returns a new file object representing the copied file. Not all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields. @errors {304: Returns an empty response when the `If-None-Match` header matches the current `etag` value of the file. This indicates that the file has not changed since it was last requested., 400: Returns an error if some of the parameters are missing or not valid. * `bad_request` when a parameter is missing., 403: Returns an error when the user does not have the right permissions to create the copy a file. * `forbidden_by_policy`: Returned if copying a file is forbidden due to information barrier restrictions., 404: Returns an error if either the source file or the destination folder could not be found, or the authenticated user does not have access to either. * `not_found` when the authenticated user does not have access to the source file or the destination folder., 409: `operation_blocked_temporary`: Returned if either of the destination or source folders is locked due to another move, copy, delete or restore operation in process. The operation can be retried at a later point. `item_name_in_use` when a folder with the same name already exists.} @endpoint GET /files/{file_id}/thumbnail.{extension} @desc Get file thumbnail @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`., extension: str(png/jpg) # The file format for the thumbnail.} @optional {min_height: int # The minimum height of the thumbnail., min_width: int # The minimum width of the thumbnail., max_height: int # The maximum height of the thumbnail., max_width: int # The maximum width of the thumbnail.} @returns(200) When a thumbnail can be created the thumbnail data will be returned in the body of the response. @returns(202) Sometimes generating a thumbnail can take a few seconds. In these situations the API returns a `Location`-header pointing to a placeholder graphic for this file type. The placeholder graphic can be used in a user interface until the thumbnail generation has completed. The `Retry-After`-header indicates when to the thumbnail will be ready. At that time, retry this endpoint to retrieve the thumbnail. @errors {302: Returns an error when Box is not able to create a thumbnail for this file type. Instead, a `Location`-header pointing to a placeholder graphic for this file type will be returned., 400: Returns an error if some of the parameters are missing or not valid. * `requested_preview_unavailable` - an incorrect dimension was requested. This will happen if the dimension requested is larger or smaller than the available file sizes for the thumbnail format, or when when any of the size constraints contradict each other., 403: Returned when the access token provided in the `Authorization` header is not recognized or not provided., 404: Returned if the file is not found, or the user does not have access to the file, or for additional reasons. * `preview_cannot_be_generated` - Box does not support thumbnails for this type of file.} @endpoint GET /files/{file_id}/collaborations @desc List file collaborations @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., limit: int(int64) # The maximum number of items to return per page., marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`.} @returns(200) Returns a collection of collaboration objects. If there are no collaborations on this file an empty collection will be returned. This list includes pending collaborations, for which the `status` is set to `pending`, indicating invitations that have been sent but not yet accepted. @endpoint GET /files/{file_id}/comments @desc List file comments @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., limit: int(int64) # The maximum number of items to return per page., offset: int(int64)=0 # The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response.} @returns(200) Returns a collection of comment objects. If there are no comments on this file an empty collection will be returned. @endpoint GET /files/{file_id}/tasks @desc List tasks on file @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.} @returns(200) {total_count: int(int64), entries: [map]} # Returns a list of tasks on a file. If there are no tasks on this file an empty collection is returned instead. @errors {404: Returns an error when the file could not be found or the user does not have access to the file., 405: Returns an error when the `file_id` was not provided., 500: Returns an error when an attempt was made to retrieve tasks for the file with ID `0`.} @endpoint GET /files/{file_id}/trash @desc Get trashed file @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.} @returns(200) {id: str, etag: str?, type: str, sequence_id: any, name: str, sha1: str(digest), file_version: any, description: str, size: int, path_collection: any, created_at: str(date-time), modified_at: str(date-time), trashed_at: str(date-time)?, purged_at: str(date-time)?, content_created_at: str(date-time)?, content_modified_at: str(date-time)?, created_by: any, modified_by: any, owned_by: any, shared_link: str?, parent: any, item_status: str} # Returns the file that was trashed, including information about when the it was moved to the trash. @errors {404: Returns an error if the file can not be found directly in the trash. Please note that a `HTTP 404` is also returned if any of the file's parent folders have been moved to the trash. In that case, only that parent folder can be inspected using the [`GET /folders/:id/trash`](https://developer.box.com/reference/get-folders-id-trash) API.} @endpoint DELETE /files/{file_id}/trash @desc Permanently remove file @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.} @returns(204) Returns an empty response when the file was permanently deleted. @errors {404: Returns an error if the file is not in the trash.} @endpoint GET /files/{file_id}/versions @desc List all file versions @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., limit: int(int64) # The maximum number of items to return per page., offset: int(int64)=0 # The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response.} @returns(200) Returns an array of past versions for this file. @endpoint GET /files/{file_id}/versions/{file_version_id} @desc Get file version @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`., file_version_id: str # The ID of the file version.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.} @returns(200) Returns a specific version of a file. Not all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields. @endpoint DELETE /files/{file_id}/versions/{file_version_id} @desc Remove file version @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`., file_version_id: str # The ID of the file version.} @optional {if-match: str # Ensures this item hasn't recently changed before making changes. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `412 Precondition Failed` if it has changed since.} @returns(204) Returns an empty response when the file has been successfully deleted. @endpoint PUT /files/{file_id}/versions/{file_version_id} @desc Restore file version @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`., file_version_id: str # The ID of the file version.} @optional {trashed_at: str # Set this to `null` to clear the date and restore the file.} @returns(200) Returns a restored file version object. @endpoint POST /files/{file_id}/versions/current @desc Promote file version @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., id: str # The file version ID., type: str # The type to promote.} @returns(201) Returns a newly created file version object. @endpoint GET /files/{file_id}/metadata @desc List metadata instances on file @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.} @optional {view: str # Taxonomy field values are returned in `API view` by default, meaning the value is represented with a taxonomy node identifier. To retrieve the `Hydrated view`, where taxonomy values are represented with the full taxonomy node information, set this parameter to `hydrated`. This is the only supported value for this parameter.} @returns(200) {entries: [map], limit: int} # Returns all the metadata associated with a file. This API does not support pagination and will therefore always return all of the metadata associated to the file. @errors {403: Returned when the request parameters are not valid., 404: Returned when the user does not have access to the file.} @endpoint GET /files/{file_id}/metadata/enterprise/securityClassification-6VMVochwUWo @desc Get classification on file @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.} @returns(200) {Box__Security__Classification__Key: str, $parent: str, $template: str, $scope: str, $version: int, $type: str, $typeVersion: num, $canEdit: bool} # Returns an instance of the `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. @errors {403: Returned when the request parameters are not valid., 404: Returned if the metadata template specified was not applied to this file or the user does not have access to the file. * `instance_not_found` - The metadata template was not applied to the file., 405: Returned when the method was not allowed.} @endpoint POST /files/{file_id}/metadata/enterprise/securityClassification-6VMVochwUWo @desc Add classification to file @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.} @optional {Box__Security__Classification__Key: str # The name of the classification to apply to this file. To list the available classifications in an enterprise, use the classification API to retrieve the [classification template](https://developer.box.com/reference/get-metadata-templates-enterprise-securityClassification-6VMVochwUWo-schema) which lists all available classification keys.} @returns(201) {Box__Security__Classification__Key: str, $parent: str, $template: str, $scope: str, $version: int, $type: str, $typeVersion: num, $canEdit: bool} # Returns the classification template instance that was applied to the file. @errors {400: Returns an error when the request body is not valid. * `schema_validation_failed` - The request body contains a value for a field that either does not exist, or for which the value or type does not match the expected field type. An example might be an unknown option for an `enum` or `multiSelect` field., 404: Returns an error when the file or metadata template was not found. * `not_found` - The file could not be found, or the user does not have access to the file. * `instance_tuple_not_found` - The metadata template was not found., 409: Returns an error when an instance of this metadata template is already present on the file. * `tuple_already_exists` - An instance of them metadata template already exists on the file.} @endpoint PUT /files/{file_id}/metadata/enterprise/securityClassification-6VMVochwUWo @desc Update classification on file @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.} @returns(200) {Box__Security__Classification__Key: str, $parent: str, $template: str, $scope: str, $version: int, $type: str, $typeVersion: num, $canEdit: bool} # Returns the updated classification metadata template instance. @errors {400: Returns an error when the request body is not valid. * `bad_request` - The request body format is not an array of valid JSON Patch operations., 500: Returns an error in some edge cases when the request body is not a valid array of JSON Patch items.} @endpoint DELETE /files/{file_id}/metadata/enterprise/securityClassification-6VMVochwUWo @desc Remove classification from file @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.} @returns(204) Returns an empty response when the classification is successfully deleted. @errors {400: Returned when the request parameters are not valid., 404: Returns an error when the file does not have any classification applied to it, or when the user does not have access to the file. * `instance_not_found` - An instance of the classification metadata template with the was not found on this file. * `not_found` - The file was not found, or the user does not have access to the file., 405: Returned when the method was not allowed.} @endpoint GET /files/{file_id}/metadata/{scope}/{template_key} @desc Get metadata instance on file @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`., scope: str(global/enterprise) # The scope of the metadata template., template_key: str # The name of the metadata template.} @optional {view: str # Taxonomy field values are returned in `API view` by default, meaning the value is represented with a taxonomy node identifier. To retrieve the `Hydrated view`, where taxonomy values are represented with the full taxonomy node information, set this parameter to `hydrated`. This is the only supported value for this parameter.} @returns(201) An instance of the metadata template that includes additional "key:value" pairs defined by the user or an application. @errors {400: Returned when the request parameters are not valid., 404: Returned if the metadata template specified was not applied to this file or the user does not have access to the file. * `instance_not_found` - The metadata template was not applied to the file., 405: Returned when the method was not allowed.} @endpoint POST /files/{file_id}/metadata/{scope}/{template_key} @desc Create metadata instance on file @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`., scope: str(global/enterprise) # The scope of the metadata template., template_key: str # The name of the metadata template.} @returns(201) Returns the instance of the template that was applied to the file, including the data that was applied to the template. @errors {400: Returns an error when the request body is not valid. * `schema_validation_failed` - The request body contains a value for a field that either does not exist, or for which the value or type does not match the expected field type. An example might be an unknown option for an `enum` or `multiSelect` field., 404: Returns an error when the file or metadata template was not found. * `not_found` - The file could not be found, or the user does not have access to the file. * `instance_tuple_not_found` - The metadata template was not found., 409: Returns an error when an instance of this metadata template is already present on the file. * `tuple_already_exists` - An instance of the metadata template already exists on the file.} @endpoint PUT /files/{file_id}/metadata/{scope}/{template_key} @desc Update metadata instance on file @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`., scope: str(global/enterprise) # The scope of the metadata template., template_key: str # The name of the metadata template.} @returns(200) Returns the updated metadata template instance, with the custom template data included. @errors {400: Returns an error when the request body is not valid. * `bad_request` - The request body format is not an array of valid JSON Patch objects., 500: Returns an error in some edge cases when the request body is not a valid array of JSON Patch items.} @endpoint DELETE /files/{file_id}/metadata/{scope}/{template_key} @desc Remove metadata instance from file @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`., scope: str(global/enterprise) # The scope of the metadata template., template_key: str # The name of the metadata template.} @returns(204) Returns an empty response when the metadata is successfully deleted. @errors {400: Returned when the request parameters are not valid. This may happen of the `scope` is not valid., 404: Returns an error when the file does not have an instance of the metadata template applied to it, or when the user does not have access to the file. * `instance_not_found` - An instance of the metadata template with the given `scope` and `templateKey` was not found on this file. * `not_found` - The file was not found, or the user does not have access to the file., 405: Returned when the method was not allowed.} @endpoint GET /files/{file_id}/metadata/global/boxSkillsCards @desc List Box Skill cards on file @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.} @returns(200) {$canEdit: bool, $id: str(uuid), $parent: str, $scope: str, $template: str, $type: str, $typeVersion: int, $version: int, cards: [map]} # Returns all the metadata associated with a file. This API does not support pagination and will therefore always return all of the metadata associated to the file. @endpoint POST /files/{file_id}/metadata/global/boxSkillsCards @desc Create Box Skill cards on file @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`., cards: [map] # A list of Box Skill cards to apply to this file.} @returns(201) {$canEdit: bool, $id: str(uuid), $parent: str, $scope: str, $template: str, $type: str, $typeVersion: int, $version: int, cards: [map]} # Returns the instance of the template that was applied to the file, including the data that was applied to the template. @errors {400: Returns an error when the request body is not valid. * `schema_validation_failed` - The request body contains a value for a field that either does not exist, or for which the value or type does not match the expected field type. An example might be an unknown option for an `enum` or `multiSelect` field., 404: Returns an error when the file or metadata template was not found. * `not_found` - The file could not be found, or the user does not have access to the file. * `instance_tuple_not_found` - The metadata template was not found., 409: Returns an error when an instance of this metadata template is already present on the file. * `tuple_already_exists` - An instance of them metadata template already exists on the file.} @endpoint PUT /files/{file_id}/metadata/global/boxSkillsCards @desc Update Box Skill cards on file @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.} @returns(200) {$canEdit: bool, $id: str(uuid), $parent: str, $scope: str, $template: str, $type: str, $typeVersion: int, $version: int, cards: [map]} # Returns the updated metadata template, with the custom template data included. @errors {404: The requested file could not be found.} @endpoint DELETE /files/{file_id}/metadata/global/boxSkillsCards @desc Remove Box Skill cards from file @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.} @returns(204) Returns an empty response when the cards are successfully deleted. @errors {404: Returns an error when the file does not have an instance of the Box Skill cards applied to it, or when the user does not have access to the file. * `instance_not_found` - An instance of the metadata template for Box Skill cards was not found on this file. * `not_found` - The file was not found, or the user does not have access to the file., 405: Returned when the method was not allowed.} @endpoint GET /files/{file_id}/watermark @desc Get watermark on file @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.} @returns(200) {watermark: map{created_at: str(date-time), modified_at: str(date-time)}} # Returns an object containing information about the watermark associated for to this file. @errors {404: Returns an error if the file does not have a watermark applied.} @endpoint PUT /files/{file_id}/watermark @desc Apply watermark to file @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`., watermark: map{imprint!: str} # The watermark to imprint on the file.} @returns(200) {watermark: map{created_at: str(date-time), modified_at: str(date-time)}} # Returns an updated watermark if a watermark already existed on this file. @returns(201) {watermark: map{created_at: str(date-time), modified_at: str(date-time)}} # Returns a new watermark if no watermark existed on this file yet. @endpoint DELETE /files/{file_id}/watermark @desc Remove watermark from file @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.} @returns(204) Removes the watermark and returns an empty response. @errors {404: Returns an error if the file did not have a watermark applied to it.} @endgroup @group file_requests @endpoint GET /file_requests/{file_request_id} @desc Get file request @required {file_request_id: str # The unique identifier that represent a file request. The ID for any file request can be determined by visiting a file request builder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/filerequest/123` the `file_request_id` is `123`.} @returns(200) {id: str, type: str, title: str, description: str?, status: str, is_email_required: bool, is_description_required: bool, expires_at: str(date-time), folder: any, url: str, etag: str?, created_by: any, created_at: str(date-time), updated_by: any, updated_at: str(date-time)} # Returns a file request object. @errors {401: Returned when the access token provided in the `Authorization` header is not recognized or not provided., 404: Returned if the file request is not found, or the user does not have access to the associated folder., 405: Returned if the `file_request_id` is not in a recognized format.} @endpoint PUT /file_requests/{file_request_id} @desc Update file request @required {file_request_id: str # The unique identifier that represent a file request. The ID for any file request can be determined by visiting a file request builder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/filerequest/123` the `file_request_id` is `123`.} @optional {if-match: str # Ensures this item hasn't recently changed before making changes. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `412 Precondition Failed` if it has changed since., title: str # An optional new title for the file request. This can be used to change the title of the file request. This will default to the value on the existing file request., description: str # An optional new description for the file request. This can be used to change the description of the file request. This will default to the value on the existing file request., status: str(active/inactive) # An optional new status of the file request. When the status is set to `inactive`, the file request will no longer accept new submissions, and any visitor to the file request URL will receive a `HTTP 404` status code. This will default to the value on the existing file request., is_email_required: bool # Whether a file request submitter is required to provide their email address. When this setting is set to true, the Box UI will show an email field on the file request form. This will default to the value on the existing file request., is_description_required: bool # Whether a file request submitter is required to provide a description of the files they are submitting. When this setting is set to true, the Box UI will show a description field on the file request form. This will default to the value on the existing file request., expires_at: str(date-time) # The date after which a file request will no longer accept new submissions. After this date, the `status` will automatically be set to `inactive`. This will default to the value on the existing file request.} @returns(200) {id: str, type: str, title: str, description: str?, status: str, is_email_required: bool, is_description_required: bool, expires_at: str(date-time), folder: any, url: str, etag: str?, created_by: any, created_at: str(date-time), updated_by: any, updated_at: str(date-time)} # Returns the updated file request object. @errors {401: Returned when the access token provided in the `Authorization` header is not recognized or not provided., 403: Returned if the user does not have all the permissions to complete the update. * `access_denied_insufficient_permissions` when the authenticated user does not have access to update the file request., 404: Returned if the file request is not found, or the user does not have access to the associated folder., 405: Returned if the `file_request_id` is not in a recognized format., 412: Returns an error when the `If-Match` header does not match the current `etag` value of the file request. This indicates that the file request has changed since it was last requested.} @endpoint DELETE /file_requests/{file_request_id} @desc Delete file request @required {file_request_id: str # The unique identifier that represent a file request. The ID for any file request can be determined by visiting a file request builder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/filerequest/123` the `file_request_id` is `123`.} @returns(204) Returns an empty response when the file request has been successfully deleted. @errors {401: Returned when the access token provided in the `Authorization` header is not recognized or not provided., 404: Returned if the file request is not found or has already been deleted, or the user does not have access to the associated folder., 405: Returned if the `file_request_id` is not in a recognized format.} @endpoint POST /file_requests/{file_request_id}/copy @desc Copy file request @required {file_request_id: str # The unique identifier that represent a file request. The ID for any file request can be determined by visiting a file request builder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/filerequest/123` the `file_request_id` is `123`.} @returns(200) {id: str, type: str, title: str, description: str?, status: str, is_email_required: bool, is_description_required: bool, expires_at: str(date-time), folder: any, url: str, etag: str?, created_by: any, created_at: str(date-time), updated_by: any, updated_at: str(date-time)} # Returns updated file request object. @errors {401: Returned when the access token provided in the `Authorization` header is not recognized or not provided., 403: Returned if the user does not have all the permissions to complete the update. * `access_denied_insufficient_permissions` when the authenticated user does not have access to update the file request., 404: Returned if the file request is not found, or the user does not have access to the associated folder., 405: Returned if the `file_request_id` is not in a recognized format.} @endgroup @group folders @endpoint GET /folders/{folder_id} @desc Get folder information @required {folder_id: str # The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. Additionally this field can be used to query any metadata applied to the file by specifying the `metadata` field as well as the scope and key of the template to retrieve, for example `?fields=metadata.enterprise_12345.contractTemplate`., if-none-match: str # Ensures an item is only returned if it has changed. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `304 Not Modified` if the item has not changed since., boxapi: str # The URL, and optional password, for the shared link of this item. This header can be used to access items that have not been explicitly shared with a user. Use the format `shared_link=[link]` or if a password is required then use `shared_link=[link]&shared_link_password=[password]`. This header can be used on the file or folder shared, as well as on any files or folders nested within the item., sort: str(id/name/date/size) # Defines the **second** attribute by which items are sorted. The folder type affects the way the items are sorted: * **Standard folder**: Items are always sorted by their `type` first, with folders listed before files, and files listed before web links. * **Root folder**: This parameter is not supported for marker-based pagination on the root folder (the folder with an `id` of `0`). * **Shared folder with parent path to the associated folder visible to the collaborator**: Items are always sorted by their `type` first, with folders listed before files, and files listed before web links., direction: str(ASC/DESC) # The direction to sort results in. This can be either in alphabetical ascending (`ASC`) or descending (`DESC`) order., offset: int(int64)=0 # The offset of the item at which to begin the response. Offset-based pagination is not guaranteed to work reliably for high offset values and may fail for large datasets. In those cases, reduce the number of items in the folder (for example, by restructuring the folder into smaller subfolders) before retrying the request., limit: int(int64) # The maximum number of items to return per page.} @returns(200) Returns a folder, including the first 100 entries in the folder. If you used query parameters like `sort`, `direction`, `offset`, or `limit` the *folder items list* will be affected accordingly. To fetch more items within the folder, use the [Get items in a folder](https://developer.box.com/reference/get-folders-id-items)) endpoint. Not all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields. @errors {304: Returns an empty response when the `If-None-Match` header matches the current `etag` value of the folder. This indicates that the folder has not changed since it was last requested., 403: Returned when the access token provided in the `Authorization` header is not recognized or not provided., 404: Returned if the folder is not found, or the user does not have access to the folder., 405: Returned if the `folder_id` is not in a recognized format.} @endpoint POST /folders/{folder_id} @desc Restore folder @required {folder_id: str # The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., name: str # An optional new name for the folder., parent: any} @returns(201) {id: str, etag: str?, type: str, sequence_id: any, name: str, created_at: str(date-time)?, modified_at: str(date-time)?, description: any, size: int(int64), path_collection: any, created_by: any, modified_by: any, trashed_at: str?, purged_at: str?, content_created_at: str(date-time)?, content_modified_at: str(date-time)?, owned_by: any, shared_link: str?, folder_upload_email: str?, parent: any, item_status: str} # Returns a folder object when the folder has been restored. @errors {403: Returns an error if the user does not have access to the folder the folder is being restored to, or the user does not have permission to restore folders from the trash., 404: Returns an error if the folder is not in the trash., 409: Returned an error if there is a folder with the same name in the destination folder. `operation_blocked_temporary`: Returned if either of the destination or source folders is locked due to another move, copy, delete or restore operation in process. The operation can be retried at a later point.} @endpoint PUT /folders/{folder_id} @desc Update folder @required {folder_id: str # The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., if-match: str # Ensures this item hasn't recently changed before making changes. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `412 Precondition Failed` if it has changed since., name: str # The optional new name for this folder. The following restrictions to folder names apply: names containing non-printable ASCII characters, forward and backward slashes (`/`, `\`), names with trailing spaces, and names `.` and `..` are not allowed. Folder names must be unique within their parent folder. The name check is case-insensitive, so a folder named `New Folder` cannot be created in a parent folder that already contains a folder named `new folder`., description: str # The optional description of this folder., sync_state: str(synced/not_synced/partially_synced) # Specifies whether a folder should be synced to a user's device or not. This is used by Box Sync (discontinued) and is not used by Box Drive., can_non_owners_invite: bool # Specifies if users who are not the owner of the folder can invite new collaborators to the folder., parent: any, shared_link: any, folder_upload_email: any, tags: [str] # The tags for this item. These tags are shown in the Box web app and mobile apps next to an item. To add or remove a tag, retrieve the item's current tags, modify them, and then update this field. There is a limit of 100 tags per item, and 10,000 unique tags per enterprise., is_collaboration_restricted_to_enterprise: bool # Specifies if new invites to this folder are restricted to users within the enterprise. This does not affect existing collaborations., collections: [map{id: str, type: str}] # An array of collections to make this folder a member of. Currently we only support the `favorites` collection. To get the ID for a collection, use the [List all collections][1] endpoint. Passing an empty array `[]` or `null` will remove the folder from all collections. [1]: https://developer.box.com/reference/get-collections, can_non_owners_view_collaborators: bool # Restricts collaborators who are not the owner of this folder from viewing other collaborations on this folder. It also restricts non-owners from inviting new collaborators. When setting this field to `false`, it is required to also set `can_non_owners_invite_collaborators` to `false` if it has not already been set.} @returns(200) Returns a folder object for the updated folder Not all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields. If the user is moving folders with a large number of items in all of their descendants, the call will be run asynchronously. If the operation is not completed within 10 minutes, the user will receive a 200 OK response, and the operation will continue running. @errors {400: Returns an error if some of the parameters are missing or not valid, or if a folder lock is preventing a move operation. * `bad_request` when a parameter is missing or incorrect. This error also happens when a password is set for a shared link with an access type of `open`. * `item_name_too_long` when the folder name is too long. * `item_name_invalid` when the folder name contains non-valid characters., 403: Returns an error if the user does not have the required access to perform the action. * `access_denied_insufficient_permissions`: Returned when the user does not have access to the folder or parent folder, or if the folder is being moved and a folder lock has been applied to prevent such operations. * `insufficient_scope`: Returned an error if the application does not have the right scope to update folders. Make sure your application has been configured to read and write all files and folders stored in Box. * `forbidden`: Returned when the user is not allowed to perform this action for other users. This can include trying to create a Shared Link with a `company` access level on a free account. * `forbidden_by_policy`: Returned if copying a folder is forbidden due to information barrier restrictions. Returns an error if there are too many actions in the request body. * `operation_limit_exceeded`: Returned when the user passes any parameters in addition to the `parent.id` in the request body. The calls to this endpoint have to be split up. The first call needs to include only the `parent.id`, the next call can include other parameters., 404: Returns an error if the folder or parent folder could not be found, or the authenticated user does not have access to either folder. * `not_found` when the authenticated user does not have access to the folder or parent folder., 409: `operation_blocked_temporary`: Returned if either of the destination or source folders is locked due to another move, copy, delete or restore operation in progress. The operation can be retried at a later point. `item_name_in_use`: Returned if a folder with the name already exists in the parent folder., 412: Returns an error when the `If-Match` header does not match the current `etag` value of the folder. This indicates that the folder has changed since it was last requested., 503: Returns an error when the operation takes longer than 600 seconds. The operation will continue after this response has been returned.} @endpoint DELETE /folders/{folder_id} @desc Delete folder @required {folder_id: str # The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`.} @optional {if-match: str # Ensures this item hasn't recently changed before making changes. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `412 Precondition Failed` if it has changed since., recursive: bool # Delete a folder that is not empty by recursively deleting the folder and all of its content.} @returns(204) Returns an empty response when the folder is successfully deleted or moved to the trash. @errors {400: Returns an error if the user makes a bad request. * `folder_not_empty`: Returned if the folder is not empty. Use the `recursive` query parameter to recursively delete the folder and its contents., 403: Returns an error if the user does not have the required access to perform the action. * `access_denied_insufficient_permissions`: Returned when the user does not have access to the folder, or when a folder lock has been applied to the folder to prevent deletion. * `insufficient_scope`: Returned an error if the application does not have the right scope to delete folders. Make sure your application has been configured to read and write all files and folders stored in Box., 404: Returns an error if the folder could not be found, or the authenticated user does not have access to the folder. * `not_found` when the authenticated user does not have access to the folder., 409: `operation_blocked_temporary`: Returned if the folder is locked due to another move, copy, delete or restore operation in progress. The operation can be retried at a later point., 412: Returns an error when the `If-Match` header does not match the current `etag` value of the folder. This indicates that the folder has changed since it was last requested., 503: Returns an error when the operation takes longer than 600 seconds. The operation will continue after this response has been returned.} @endpoint GET /folders/{folder_id}/app_item_associations @desc List folder app item associations @required {folder_id: str # The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`.} @optional {limit: int(int64) # The maximum number of items to return per page., marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`., application_type: str # If given, returns only app items for this application type.} @returns(200) Returns a collection of app item objects. If there are no app items on this folder an empty collection will be returned. This list includes app items on ancestors of this folder. @errors {404: Returned if the folder is not found, or the user does not have access to the folder.} @endpoint GET /folders/{folder_id}/items @desc List items in folder @required {folder_id: str # The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. Additionally this field can be used to query any metadata applied to the file by specifying the `metadata` field as well as the scope and key of the template to retrieve, for example `?fields=metadata.enterprise_12345.contractTemplate`., usemarker: bool # Specifies whether to use marker-based pagination instead of offset-based pagination. Only one pagination method can be used at a time. By setting this value to true, the API will return a `marker` field that can be passed as a parameter to this endpoint to get the next page of the response., marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`., offset: int(int64)=0 # The offset of the item at which to begin the response. Offset-based pagination is not guaranteed to work reliably for high offset values and may fail for large datasets. In those cases, use marker-based pagination by setting `usemarker` to `true`., limit: int(int64) # The maximum number of items to return per page., boxapi: str # The URL, and optional password, for the shared link of this item. This header can be used to access items that have not been explicitly shared with a user. Use the format `shared_link=[link]` or if a password is required then use `shared_link=[link]&shared_link_password=[password]`. This header can be used on the file or folder shared, as well as on any files or folders nested within the item., sort: str(id/name/date/size) # Defines the **second** attribute by which items are sorted. The folder type affects the way the items are sorted: * **Standard folder**: Items are always sorted by their `type` first, with folders listed before files, and files listed before web links. * **Root folder**: This parameter is not supported for marker-based pagination on the root folder (the folder with an `id` of `0`). * **Shared folder with parent path to the associated folder visible to the collaborator**: Items are always sorted by their `type` first, with folders listed before files, and files listed before web links., direction: str(ASC/DESC) # The direction to sort results in. This can be either in alphabetical ascending (`ASC`) or descending (`DESC`) order.} @returns(200) Returns a collection of files, folders, and web links contained in a folder. @errors {403: Returned when the access token provided in the `Authorization` header is not recognized or not provided., 404: Returned if the folder is not found, or the user does not have access to the folder., 405: Returned if the `folder_id` is not in a recognized format.} @endpoint POST /folders @desc Create folder @required {name: str # The name for the new folder. The following restrictions to folder names apply: names containing non-printable ASCII characters, forward and backward slashes (`/`, `\`), names with trailing spaces, and names `.` and `..` are not allowed. Folder names must be unique within their parent folder. The name check is case-insensitive, so a folder named `New Folder` cannot be created in a parent folder that already contains a folder named `new folder`., parent: map{id!: str} # The parent folder to create the new folder within.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., folder_upload_email: any, sync_state: str(synced/not_synced/partially_synced) # Specifies whether a folder should be synced to a user's device or not. This is used by Box Sync (discontinued) and is not used by Box Drive.} @returns(201) Returns a folder object. Not all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields. @errors {400: Returns an error if some of the parameters are missing or not valid. * `bad_request` when a parameter is missing or incorrect. * `item_name_too_long` when the folder name is too long. * `item_name_invalid` when the folder name contains non-valid characters., 403: Returns an error if the user does not have the required access to perform the action. This might be because they don't have access to the folder or parent folder, or because the application does not have permission to write files and folders., 404: Returns an error if the parent folder could not be found, or the authenticated user does not have access to the parent folder. * `not_found` when the authenticated user does not have access to the parent folder., 409: `operation_blocked_temporary`: Returned if either of the destination or source folders is locked due to another move, copy, delete or restore operation in process. The operation can be retried at a later point. `item_name_in_use`: Returned if a folder with the name already exists in the parent folder.} @endpoint POST /folders/{folder_id}/copy @desc Copy folder @required {folder_id: str # The unique identifier of the folder to copy. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder with the ID `0` can not be copied., parent: map{id!: str} # The destination folder to copy the folder to.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., name: str # An optional new name for the copied folder. There are some restrictions to the file name. Names containing non-printable ASCII characters, forward and backward slashes (`/`, `\`), as well as names with trailing spaces are prohibited. Additionally, the names `.` and `..` are not allowed either.} @returns(201) Returns a new folder object representing the copied folder. Not all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields. @errors {304: Returns an empty response when the `If-None-Match` header matches the current `etag` value of the folder. This indicates that the folder has not changed since it was last requested., 400: Returns an error if some of the parameters are missing or not valid. * `bad_request` when a parameter is missing. * `item_name_too_long` when the new folder name is too long., 403: Returns an error when the user does not have the right permissions to copy a folder. * `forbidden_by_policy`: Returned if copying a folder is forbidden due to information barrier restrictions., 404: Returns an error if either the source or destination folder could not be found, or the authenticated user does not have access to either folders. * `not_found` when the authenticated user does not have access to the parent folder., 409: Returns an error if a folder by this name already exists in the destination folder, or if the destination folder is locked. * `item_name_in_use` when a folder with the same name already exists., 500: Returns an error when trying to copy the root folder.} @endpoint GET /folders/{folder_id}/collaborations @desc List folder collaborations @required {folder_id: str # The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., limit: int(int64) # The maximum number of items to return per page., marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`.} @returns(200) Returns a collection of collaboration objects. If there are no collaborations on this folder an empty collection will be returned. This list includes pending collaborations, for which the `status` is set to `pending`, indicating invitations that have been sent but not yet accepted. @endpoint GET /folders/{folder_id}/trash @desc Get trashed folder @required {folder_id: str # The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.} @returns(200) {id: str, etag: str?, type: str, sequence_id: any, name: str, created_at: str(date-time)?, modified_at: str(date-time)?, description: any, size: int(int64), path_collection: any, created_by: any, modified_by: any, trashed_at: str(date-time)?, purged_at: str(date-time)?, content_created_at: str(date-time)?, content_modified_at: str(date-time)?, owned_by: any, shared_link: str?, folder_upload_email: str?, parent: any, item_status: str} # Returns the folder that was trashed, including information about when the it was moved to the trash. @errors {404: Returns an error if the folder can not be found directly in the trash. Please note that a `HTTP 404` is also returned if any of the folder's parent folders have been moved to the trash. In that case, only that parent folder can be inspected using the [`GET /folders/:id/trash`](https://developer.box.com/reference/get-folders-id-trash) API.} @endpoint DELETE /folders/{folder_id}/trash @desc Permanently remove folder @required {folder_id: str # The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`.} @returns(204) Returns an empty response when the folder was permanently deleted. @errors {404: Returns an error if the folder is not in the trash.} @endpoint GET /folders/{folder_id}/metadata @desc List metadata instances on folder @required {folder_id: str # The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`.} @optional {view: str # Taxonomy field values are returned in `API view` by default, meaning the value is represented with a taxonomy node identifier. To retrieve the `Hydrated view`, where taxonomy values are represented with the full taxonomy node information, set this parameter to `hydrated`. This is the only supported value for this parameter.} @returns(200) {entries: [map], limit: int} # Returns all the metadata associated with a folder. This API does not support pagination and will therefore always return all of the metadata associated to the folder. @errors {403: Returned when the request parameters are not valid. * `forbidden` - this operation is not allowed on the Root folder., 404: Returned when the user does not have access to the folder.} @endpoint GET /folders/{folder_id}/metadata/enterprise/securityClassification-6VMVochwUWo @desc Get classification on folder @required {folder_id: str # The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`.} @returns(200) {Box__Security__Classification__Key: str, $parent: str, $template: str, $scope: str, $version: int, $type: str, $typeVersion: num, $canEdit: bool} # Returns an instance of the `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. @errors {403: Returned when the request parameters are not valid., 404: Returned if the metadata template specified was not applied to this folder or the user does not have access to the folder. * `instance_not_found` - The metadata template was not applied to the folder., 405: Returned when the method was not allowed.} @endpoint POST /folders/{folder_id}/metadata/enterprise/securityClassification-6VMVochwUWo @desc Add classification to folder @required {folder_id: str # The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`.} @optional {Box__Security__Classification__Key: str # The name of the classification to apply to this folder. To list the available classifications in an enterprise, use the classification API to retrieve the [classification template](https://developer.box.com/reference/get-metadata-templates-enterprise-securityClassification-6VMVochwUWo-schema) which lists all available classification keys.} @returns(201) {Box__Security__Classification__Key: str, $parent: str, $template: str, $scope: str, $version: int, $type: str, $typeVersion: num, $canEdit: bool} # Returns the classification template instance that was applied to the folder. @errors {400: Returns an error when the request body is not valid. * `schema_validation_failed` - The request body contains a value for a field that either does not exist, or for which the value or type does not match the expected field type. An example might be an unknown option for an `enum` or `multiSelect` field., 404: Returns an error when the folder or metadata template was not found. * `not_found` - The folder could not be found, or the user does not have access to the folder. * `instance_tuple_not_found` - The metadata template was not found., 409: Returns an error when an instance of this metadata template is already present on the folder. * `tuple_already_exists` - An instance of them metadata template already exists on the folder.} @endpoint PUT /folders/{folder_id}/metadata/enterprise/securityClassification-6VMVochwUWo @desc Update classification on folder @required {folder_id: str # The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`.} @returns(200) {Box__Security__Classification__Key: str, $parent: str, $template: str, $scope: str, $version: int, $type: str, $typeVersion: num, $canEdit: bool} # Returns the updated classification metadata template instance. @errors {400: Returns an error when the request body is not valid. * `bad_request` - The request body format is not an array of valid JSON Patch operations., 500: Returns an error in some edge cases when the request body is not a valid array of JSON Patch items.} @endpoint DELETE /folders/{folder_id}/metadata/enterprise/securityClassification-6VMVochwUWo @desc Remove classification from folder @required {folder_id: str # The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`.} @returns(204) Returns an empty response when the classification is successfully deleted. @errors {400: Returned when the request parameters are not valid., 404: Returns an error when the folder does not have any classification applied to it, or when the user does not have access to the folder. * `instance_not_found` - An instance of the classification metadata template with the was not found on this folder. * `not_found` - The folder was not found, or the user does not have access to the folder., 405: Returned when the method was not allowed.} @endpoint GET /folders/{folder_id}/metadata/{scope}/{template_key} @desc Get metadata instance on folder @required {folder_id: str # The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`., scope: str(global/enterprise) # The scope of the metadata template., template_key: str # The name of the metadata template.} @returns(201) An instance of the metadata template that includes additional "key:value" pairs defined by the user or an application. @errors {403: Returned when the request parameters are not valid., 404: Returned if the metadata template specified was not applied to this folder or the user does not have access to the folder. * `instance_not_found` - The metadata template was not applied to the folder., 405: Returned when the method was not allowed. This often happens when the folder ID is not valid or the root folder with ID `0`.} @endpoint POST /folders/{folder_id}/metadata/{scope}/{template_key} @desc Create metadata instance on folder @required {folder_id: str # The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`., scope: str(global/enterprise) # The scope of the metadata template., template_key: str # The name of the metadata template.} @returns(201) Returns the instance of the template that was applied to the folder, including the data that was applied to the template. @errors {400: Returns an error when the request body is not valid. * `schema_validation_failed` - The request body contains a value for a field that either does not exist, or for which the value or type does not match the expected field type. An example might be an unknown option for an `enum` or `multiSelect` field., 404: Returns an error when the folder or metadata template was not found. * `not_found` - The folder could not be found, or the user does not have access to the folder. * `instance_tuple_not_found` - The metadata template was not found., 409: Returns an error when an instance of this metadata template is already present on the folder. * `tuple_already_exists` - An instance of the metadata template already exists on the folder.} @endpoint PUT /folders/{folder_id}/metadata/{scope}/{template_key} @desc Update metadata instance on folder @required {folder_id: str # The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`., scope: str(global/enterprise) # The scope of the metadata template., template_key: str # The name of the metadata template.} @returns(200) Returns the updated metadata template instance, with the custom template data included. @errors {400: Returns an error when the request body is not valid. * `bad_request` - The request body format is not an array of valid JSON Patch objects., 500: Returns an error in some edge cases when the request body is not a valid array of JSON Patch items.} @endpoint DELETE /folders/{folder_id}/metadata/{scope}/{template_key} @desc Remove metadata instance from folder @required {folder_id: str # The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`., scope: str(global/enterprise) # The scope of the metadata template., template_key: str # The name of the metadata template.} @returns(204) Returns an empty response when the metadata is successfully deleted. @errors {400: Returned when the request parameters are not valid. This may happen of the `scope` is not valid., 404: Returns an error when the folder does not have an instance of the metadata template applied to it, or when the user does not have access to the folder. * `instance_not_found` - An instance of the metadata template with the given `scope` and `templateKey` was not found on this folder. * `not_found` - The folder was not found, or the user does not have access to the folder., 405: Returned when the method was not allowed. This often happens when the folder ID is not valid or the root folder with ID `0`.} @endpoint GET /folders/trash/items @desc List trashed items @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., limit: int(int64) # The maximum number of items to return per page., offset: int(int64)=0 # The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response., usemarker: bool # Specifies whether to use marker-based pagination instead of offset-based pagination. Only one pagination method can be used at a time. By setting this value to true, the API will return a `marker` field that can be passed as a parameter to this endpoint to get the next page of the response., marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`., direction: str(ASC/DESC) # The direction to sort results in. This can be either in alphabetical ascending (`ASC`) or descending (`DESC`) order., sort: str(name/date/size) # Defines the **second** attribute by which items are sorted. Items are always sorted by their `type` first, with folders listed before files, and files listed before web links. This parameter is not supported when using marker-based pagination.} @returns(200) Returns a list of items that have been deleted. @errors {400: Returns an error if some of the parameters are missing or not valid. * `invalid_parameter` can appear when the `sort`, `direction` or `offset` parameter is provided when using marker based pagination, or when the `marker` parameter is provided but `usemarker` is set to `false` or `null`.} @endpoint GET /folders/{folder_id}/watermark @desc Get watermark for folder @required {folder_id: str # The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`.} @returns(200) {watermark: map{created_at: str(date-time), modified_at: str(date-time)}} # Returns an object containing information about the watermark associated for to this folder. @errors {404: Returns an error if the folder does not have a watermark applied.} @endpoint PUT /folders/{folder_id}/watermark @desc Apply watermark to folder @required {folder_id: str # The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`., watermark: map{imprint!: str} # The watermark to imprint on the folder.} @returns(200) {watermark: map{created_at: str(date-time), modified_at: str(date-time)}} # Returns an updated watermark if a watermark already existed on this folder. @returns(201) {watermark: map{created_at: str(date-time), modified_at: str(date-time)}} # Returns a new watermark if no watermark existed on this folder yet. @endpoint DELETE /folders/{folder_id}/watermark @desc Remove watermark from folder @required {folder_id: str # The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`.} @returns(204) An empty response will be returned when the watermark was successfully deleted. @errors {404: Returns an error if the folder did not have a watermark applied to it.} @endgroup @group folder_locks @endpoint GET /folder_locks @desc List folder locks @required {folder_id: str # The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`.} @returns(200) {entries: [map], limit: str, next_marker: str?} # Returns details for all folder locks applied to the folder, including the lock type and user that applied the lock. @errors {403: Returned when the access token provided in the `Authorization` header is not recognized or not provided., 404: Returned if the folder is not found, or the user does not have access to the folder., 405: Returned if the `folder_id` is not in a recognized format.} @endpoint POST /folder_locks @desc Create folder lock @required {folder: map{type!: str, id!: str} # The folder to apply the lock to.} @optional {locked_operations: map{move!: bool, delete!: bool} # The operations to lock for the folder. If `locked_operations` is included in the request, both `move` and `delete` must also be included and both set to `true`.} @returns(200) {folder: any, id: str, type: str, created_by: any, created_at: str(date-time), locked_operations: map{move: bool, delete: bool}, lock_type: str} # Returns the instance of the folder lock that was applied to the folder, including the user that applied the lock and the operations set. @errors {400: Returns an error when the request body is not valid. * `schema_validation_failed` - The request body contains a value for a field that either does not exist, or for which the value or type does not match the expected field type. An example might be an unknown option for an `enum` or `multiSelect` field., 404: Returns an error when the folder was not found. * `not_found` - The folder could not be found, the user does not have access to the folder, or the user making call is not an owner or co-owner of folder.} @endpoint DELETE /folder_locks/{folder_lock_id} @desc Delete folder lock @required {folder_lock_id: str # The ID of the folder lock.} @returns(204) Returns an empty response when the folder lock is successfully deleted. @errors {403: Returns an error if the user does not have the required access to perform the action. * `access_denied_insufficient_permissions`: Returned when the user does not have access to the folder. * `insufficient_scope`: Returned an error if the application does not have the right scope to delete folders. Make sure your application has been configured to read and write all files and folders stored in Box., 404: Returns an error if the folder could not be found, or the authenticated user does not have access to the folder. * `not_found` when the authenticated user does not have access to the folder.} @endgroup @group metadata_templates @endpoint GET /metadata_templates @desc Find metadata template by instance ID @required {metadata_instance_id: str(uuid) # The ID of an instance of the metadata template to find.} @optional {marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`., limit: int(int64) # The maximum number of items to return per page.} @returns(200) Returns a list containing the 1 metadata template that matches the instance ID. @errors {400: Returned when the request parameters are not valid.} @endpoint GET /metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema @desc List all classifications @returns(200) {id: str, type: str, scope: str, templateKey: str, displayName: str, hidden: bool, copyInstanceOnItemCopy: bool, fields: [map]} # Returns the `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. @errors {400: Returned if any of the request parameters are not valid., 404: Returned when a template name is not correct. Please make sure the URL for the request is correct.} @endpoint PUT /metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema#add @desc Add classification @returns(200) {id: str, type: str, scope: str, templateKey: str, displayName: str, hidden: bool, copyInstanceOnItemCopy: bool, fields: [map]} # Returns the updated `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. @errors {400: Returned if any of the request parameters are not valid., 404: Returned when a template name is not correct. Please make sure the URL for the request is correct.} @endpoint PUT /metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema#update @desc Update classification @returns(200) {id: str, type: str, scope: str, templateKey: str, displayName: str, hidden: bool, copyInstanceOnItemCopy: bool, fields: [map]} # Returns the updated `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. @errors {400: Returned if any of the request parameters are not valid., 404: Returned when a template name is not correct. Please make sure the URL for the request is correct.} @endpoint GET /metadata_templates/{scope}/{template_key}/schema @desc Get metadata template by name @required {scope: str(global/enterprise) # The scope of the metadata template., template_key: str # The name of the metadata template.} @returns(200) {id: str, type: str, scope: str, templateKey: str, displayName: str, hidden: bool, fields: [map], copyInstanceOnItemCopy: bool} # Returns the metadata template matching the `scope` and `template` name. @errors {400: Returned if any of the request parameters are not valid. * `bad_request`: Often returned when the scope of the template is not recognised. Please make sure to use either `enterprise` or `global` as the `scope` value., 404: Returned when a template with the given `scope` and `template_key` can not be found.} @endpoint PUT /metadata_templates/{scope}/{template_key}/schema @desc Update metadata template @required {scope: str(global/enterprise) # The scope of the metadata template., template_key: str # The name of the metadata template.} @returns(200) {id: str, type: str, scope: str, templateKey: str, displayName: str, hidden: bool, fields: [map], copyInstanceOnItemCopy: bool} # Returns the updated metadata template, with the custom template data included. @errors {400: The request body does not contain a valid metadata schema., 403: The request body contains a scope that the user is not allowed to create templates for., 404: The requested template could not be found.} @endpoint DELETE /metadata_templates/{scope}/{template_key}/schema @desc Remove metadata template @required {scope: str(global/enterprise) # The scope of the metadata template., template_key: str # The name of the metadata template.} @returns(204) Returns an empty response when the metadata template is successfully deleted. @errors {400: Request body does not contain a valid metadata schema., 403: Request body contains a scope that the user is not allowed to create a template for.} @endpoint GET /metadata_templates/{template_id} @desc Get metadata template by ID @required {template_id: str # The ID of the template.} @returns(200) {id: str, type: str, scope: str, templateKey: str, displayName: str, hidden: bool, fields: [map], copyInstanceOnItemCopy: bool} # Returns the metadata template that matches the ID. @errors {400: Returned if any of the request parameters are not valid. * `bad_request`: Often returned with a message when the ID of the template is not recognised.} @endpoint GET /metadata_templates/global @desc List all global metadata templates @optional {marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`., limit: int(int64) # The maximum number of items to return per page.} @returns(200) Returns all of the metadata templates available to all enterprises and their corresponding schema. @errors {400: Returned when the request parameters are not valid.} @endpoint GET /metadata_templates/enterprise @desc List all metadata templates for enterprise @optional {marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`., limit: int(int64) # The maximum number of items to return per page.} @returns(200) Returns all of the metadata templates within an enterprise and their corresponding schema. @errors {400: Returned when the request parameters are not valid.} @endpoint POST /metadata_templates/schema @desc Create metadata template @required {scope: str # The scope of the metadata template to create. Applications can only create templates for use within the authenticated user's enterprise. This value needs to be set to `enterprise`, as `global` scopes can not be created by applications., displayName: str # The display name of the template.} @optional {templateKey: str # A unique identifier for the template. This identifier needs to be unique across the enterprise for which the metadata template is being created. When not provided, the API will create a unique `templateKey` based on the value of the `displayName`., hidden: bool=false # Defines if this template is visible in the Box web app UI, or if it is purely intended for usage through the API., fields: [map{type!: str, key!: str, displayName!: str, description: str, hidden: bool, options: [map], taxonomyKey: str, namespace: str, optionsRules: map}] # An ordered list of template fields which are part of the template. Each field can be a regular text field, date field, number field, as well as a single or multi-select list., copyInstanceOnItemCopy: bool=false # Whether or not to copy any metadata attached to a file or folder when it is copied. By default, metadata is not copied along with a file or folder when it is copied.} @returns(201) {id: str, type: str, scope: str, templateKey: str, displayName: str, hidden: bool, fields: [map], copyInstanceOnItemCopy: bool} # The schema representing the metadata template created. @errors {400: Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. In many cases this response will include extra details on what fields are missing., 403: Returned when the user does not have the permission to create the metadata template. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the application tries to create a template with the `global` scope.} @endpoint POST /metadata_templates/schema#classifications @desc Add initial classifications @required {scope: str # The scope in which to create the classifications. This should be `enterprise` or `enterprise_{id}` where `id` is the unique ID of the enterprise., templateKey: str # Defines the list of metadata templates., displayName: str # The name of the template as shown in web and mobile interfaces., fields: [map{type!: str, key!: str, displayName!: str, hidden: bool, options!: [map]}] # The classification template requires exactly one field, which holds all the valid classification values.} @optional {hidden: bool # Determines if the classification template is hidden or available on web and mobile devices., copyInstanceOnItemCopy: bool # Determines if classifications are copied along when the file or folder is copied.} @returns(200) {id: str, type: str, scope: str, templateKey: str, displayName: str, hidden: bool, copyInstanceOnItemCopy: bool, fields: [map]} # Returns a new `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. @errors {400: Returned if any of the request parameters are not valid., 404: Returned when a template name is not correct. Please make sure the URL for the request is correct.} @endgroup @group metadata_cascade_policies @endpoint GET /metadata_cascade_policies @desc List metadata cascade policies @required {folder_id: str # Specifies which folder to return policies for. This can not be used on the root folder with ID `0`.} @optional {owner_enterprise_id: str # The ID of the enterprise ID for which to find metadata cascade policies. If not specified, it defaults to the current enterprise., marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`., offset: int(int64)=0 # The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response.} @returns(200) Returns a list of metadata cascade policies. @errors {400: Returns an error when any of the parameters are not in a valid format., 403: Returns an error when the folder can not be accessed. This error often happens when accessing the root folder with ID `0`., 404: Returns an error when the folder can not be found or the user does not have access to the folder. * `not_found` - The folder could not be found or the user does not have access to the folder.} @endpoint POST /metadata_cascade_policies @desc Create metadata cascade policy @required {folder_id: str # The ID of the folder to apply the policy to. This folder will need to already have an instance of the targeted metadata template applied to it., scope: str(global/enterprise) # The scope of the targeted metadata template. This template will need to already have an instance applied to the targeted folder., templateKey: str # The key of the targeted metadata template. This template will need to already have an instance applied to the targeted folder. In many cases the template key is automatically derived of its display name, for example `Contract Template` would become `contractTemplate`. In some cases the creator of the template will have provided its own template key. Please [list the templates for an enterprise][list], or get all instances on a [file][file] or [folder][folder] to inspect a template's key. [list]: https://developer.box.com/reference/get-metadata-templates-enterprise [file]: https://developer.box.com/reference/get-files-id-metadata [folder]: https://developer.box.com/reference/get-folders-id-metadata} @returns(201) {id: str, type: str, owner_enterprise: map{type: str, id: str}, parent: map{type: str, id: str}, scope: str, templateKey: str} # Returns a new of metadata cascade policy. @errors {400: Returns an error when any of the parameters are not in a valid format. * `bad_request` - Either the `scope`, `templateKey`, or `folder_id` are not in a valid format., 403: Returns an error when trying to apply a policy to a restricted folder, for example the root folder with ID `0`. * `forbidden` - Although the folder ID was valid and the user has access to the folder, the policy could not be applied to this folder., 404: Returns an error when the template or folder can not be found, or when the user does not have access to the folder or template. * `instance_tuple_not_found` - The template could not be found or the user does not have access to the template. * `not_found` - The folder could not be found or the user does not have access to the folder., 409: Returns an error when a policy for this folder and template is already in place. * `tuple_already_exists` - A cascade policy for this combination of `folder_id`, `scope` and `templateKey` already exists.} @endpoint GET /metadata_cascade_policies/{metadata_cascade_policy_id} @desc Get metadata cascade policy @required {metadata_cascade_policy_id: str # The ID of the metadata cascade policy.} @returns(200) {id: str, type: str, owner_enterprise: map{type: str, id: str}, parent: map{type: str, id: str}, scope: str, templateKey: str} # Returns a metadata cascade policy. @errors {404: Returns an error when the policy can not be found or the user does not have access to the folder. * `instance_not_found` - The policy could not be found * `not_found` - The folder could not be found or the user does not have access to the folder.} @endpoint DELETE /metadata_cascade_policies/{metadata_cascade_policy_id} @desc Remove metadata cascade policy @required {metadata_cascade_policy_id: str # The ID of the metadata cascade policy.} @returns(204) Returns an empty response when the policy is successfully deleted. @errors {404: Returns an error when the policy can not be found or the user does not have access to the folder. * `instance_not_found` - The policy could not be found * `not_found` - The folder could not be found or the user does not have access to the folder.} @endpoint POST /metadata_cascade_policies/{metadata_cascade_policy_id}/apply @desc Force-apply metadata cascade policy to folder @required {metadata_cascade_policy_id: str # The ID of the cascade policy to force-apply., conflict_resolution: str(none/overwrite) # Describes the desired behavior when dealing with the conflict where a metadata template already has an instance applied to a child. * `none` will preserve the existing value on the file * `overwrite` will force-apply the templates values over any existing values.} @returns(202) Returns an empty response when the API call was successful. The metadata cascade operation will be performed asynchronously. The API call will return directly, before the cascade operation is complete. There is currently no API to check for the status of this operation. @errors {404: Returns an error when the policy can not be found or the user does not have access to the folder. * `instance_not_found` - The policy could not be found * `not_found` - The folder could not be found or the user does not have access to the folder.} @endgroup @group metadata_queries @endpoint POST /metadata_queries/execute_read @desc Query files/folders by metadata @required {from: str # Specifies the template used in the query. Must be in the form `scope.templateKey`. Not all templates can be used in this field, most notably the built-in, Box-provided classification templates can not be used in a query., ancestor_folder_id: str # The ID of the folder that you are restricting the query to. A value of zero will return results from all folders you have access to. A non-zero value will only return results found in the folder corresponding to the ID or in any of its subfolders.} @optional {query: str # The query to perform. A query is a logical expression that is very similar to a SQL `SELECT` statement. Values in the search query can be turned into parameters specified in the `query_param` arguments list to prevent having to manually insert search values into the query string. For example, a value of `:amount` would represent the `amount` value in `query_params` object., query_params: map # Set of arguments corresponding to the parameters specified in the `query`. The type of each parameter used in the `query_params` must match the type of the corresponding metadata template field., order_by: [map{field_key: str, direction: str}] # A list of template fields and directions to sort the metadata query results by. The ordering `direction` must be the same for each item in the array., limit: int=100 # A value between 0 and 100 that indicates the maximum number of results to return for a single request. This only specifies a maximum boundary and will not guarantee the minimum number of results returned., marker: str # Marker to use for requesting the next page., fields: [str] # By default, this endpoint returns only the most basic info about the items for which the query matches. This attribute can be used to specify a list of additional attributes to return for any item, including its metadata. This attribute takes a list of item fields, metadata template identifiers, or metadata template field identifiers. For example: * `created_by` will add the details of the user who created the item to the response. * `metadata..` will return the mini-representation of the metadata instance identified by the `scope` and `templateKey`. * `metadata...` will return all the mini-representation of the metadata instance identified by the `scope` and `templateKey` plus the field specified by the `field` name. Multiple fields for the same `scope` and `templateKey` can be defined.} @returns(200) {entries: [map], limit: int(int64), next_marker: str} # Returns a list of files and folders that match this metadata query. @errors {400: Returns an error when the request body is not valid. * `invalid_query` - Any of the provided body parameters might be incorrect. This can mean the `query` is incorrect, as well as some cases where the `from` value does not represent a valid template. * `unexpected_json_type` - An argument from the `query` string is not present in `query_param`. For example, `query` of `name = :name` requires the `query_param` to include a value for the `name` argument, for example `{ "name": "Box, Inc" }`., 404: Returns an error when a metadata template with the given `scope` and `templateKey` can not be found. The error response will include extra details. * `instance_not_found` - The template was not found. Please make sure to use the full template scope including the enterprise ID, like `enterprise_12345`.} @endgroup @group comments @endpoint GET /comments/{comment_id} @desc Get comment @required {comment_id: str # The ID of the comment.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.} @returns(200) Returns a full comment object. @endpoint PUT /comments/{comment_id} @desc Update comment @required {comment_id: str # The ID of the comment.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., message: str # The text of the comment to update.} @returns(200) Returns the updated comment object. @endpoint DELETE /comments/{comment_id} @desc Remove comment @required {comment_id: str # The ID of the comment.} @returns(204) Returns an empty response when the comment has been deleted. @endpoint POST /comments @desc Create comment @required {message: str # The text of the comment. To mention a user, use the `tagged_message` parameter instead., item: map{id!: str, type!: str} # The item to attach the comment to.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., tagged_message: str # The text of the comment, including `@[user_id:name]` somewhere in the message to mention another user, which will send them an email notification, letting them know they have been mentioned. The `user_id` is the target user's ID, where the `name` can be any custom phrase. In the Box UI this name will link to the user's profile. If you are not mentioning another user, use `message` instead.} @returns(201) Returns the newly created comment object. Not all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields. @endgroup @group collaborations @endpoint GET /collaborations/{collaboration_id} @desc Get collaboration @required {collaboration_id: str # The ID of the collaboration.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.} @returns(200) {id: str, type: str, item: any?, app_item: any?, accessible_by: map, invite_email: str?, role: str, expires_at: str(date-time)?, is_access_only: bool, status: str, acknowledged_at: str(date-time), created_by: any, created_at: str(date-time), modified_at: str(date-time), acceptance_requirements_status: map{terms_of_service_requirement: map{is_accepted: bool?, terms_of_service: any}, strong_password_requirement: map{enterprise_has_strong_password_required_for_external_users: bool, user_has_strong_password: bool?}, two_factor_authentication_requirement: map{enterprise_has_two_factor_auth_enabled: bool, user_has_two_factor_authentication_enabled: bool?}}} # Returns a collaboration object. @endpoint PUT /collaborations/{collaboration_id} @desc Update collaboration @required {collaboration_id: str # The ID of the collaboration.} @optional {role: str(editor/viewer/previewer/uploader/previewer uploader/viewer uploader/co-owner/owner) # The level of access granted., status: str(pending/accepted/rejected) # Set the status of a `pending` collaboration invitation, effectively accepting, or rejecting the invite., expires_at: str(date-time) # Update the expiration date for the collaboration. At this date, the collaboration will be automatically removed from the item. This feature will only work if the **Automatically remove invited collaborators: Allow folder owners to extend the expiry date** setting has been enabled in the **Enterprise Settings** of the **Admin Console**. When the setting is not enabled, collaborations can not have an expiry date and a value for this field will be result in an error. Additionally, a collaboration can only be given an expiration if it was created after the **Automatically remove invited collaborator** setting was enabled., can_view_path: bool # Determines if the invited users can see the entire parent path to the associated folder. The user will not gain privileges in any parent folder and therefore can not see content the user is not collaborated on. Be aware that this meaningfully increases the time required to load the invitee's **All Files** page. We recommend you limit the number of collaborations with `can_view_path` enabled to 1,000 per user. Only an owner or co-owners can invite collaborators with a `can_view_path` of `true`. Only an owner can update `can_view_path` on existing collaborations. `can_view_path` can only be used for folder collaborations. When you delete a folder with `can_view_path=true`, collaborators may still see the parent path. For instructions on how to remove this, see [Even though a folder invited via can_view_path is deleted, the path remains displayed](https://support.box.com/hc/en-us/articles/37472814319891-Even-though-a-folder-invited-via-can-view-path-is-deleted-the-path-remains-displayed).} @returns(200) {id: str, type: str, item: any?, app_item: any?, accessible_by: map, invite_email: str?, role: str, expires_at: str(date-time)?, is_access_only: bool, status: str, acknowledged_at: str(date-time), created_by: any, created_at: str(date-time), modified_at: str(date-time), acceptance_requirements_status: map{terms_of_service_requirement: map{is_accepted: bool?, terms_of_service: any}, strong_password_requirement: map{enterprise_has_strong_password_required_for_external_users: bool, user_has_strong_password: bool?}, two_factor_authentication_requirement: map{enterprise_has_two_factor_auth_enabled: bool, user_has_two_factor_authentication_enabled: bool?}}} # Returns an updated collaboration object unless the owner has changed. @returns(204) If the role is changed to `owner`, the collaboration is deleted and a new collaboration is created. The previous `owner` of the old collaboration will be a `co-owner` on the new collaboration. @errors {403: Returns an error if the authenticated user does not have the right permissions to update the collaboration. Additionally, this error may occur when attempting to update the `expires_at` field for the collaboration without the **Automatically remove invited collaborators: Allow folder owners to extend the expiry date** setting enabled in the admin dashboard of the enterprise.} @endpoint DELETE /collaborations/{collaboration_id} @desc Remove collaboration @required {collaboration_id: str # The ID of the collaboration.} @returns(204) A blank response is returned if the collaboration was successfully deleted. @endpoint GET /collaborations @desc List pending collaborations @required {status: str # The status of the collaborations to retrieve.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., offset: int(int64)=0 # The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response., limit: int(int64) # The maximum number of items to return per page.} @returns(200) Returns a collection of pending collaboration objects. If the user has no pending collaborations, the collection will be empty. @endpoint POST /collaborations @desc Create collaboration @required {item: map{type: str, id: str} # The item to attach the comment to., accessible_by: map{type!: str, id: str, login: str} # The user or group to give access to the item., role: str(editor/viewer/previewer/uploader/previewer uploader/viewer uploader/co-owner) # The level of access granted.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., notify: bool # Determines if users should receive email notification for the action performed., is_access_only: bool # If set to `true`, collaborators have access to shared items, but such items won't be visible in the All Files list. Additionally, collaborators won't see the path to the root folder for the shared item., can_view_path: bool # Determines if the invited users can see the entire parent path to the associated folder. The user will not gain privileges in any parent folder and therefore can not see content the user is not collaborated on. Be aware that this meaningfully increases the time required to load the invitee's **All Files** page. We recommend you limit the number of collaborations with `can_view_path` enabled to 1,000 per user. Only an owner or co-owners can invite collaborators with a `can_view_path` of `true`. Only an owner can update `can_view_path` on existing collaborations. `can_view_path` can only be used for folder collaborations. When you delete a folder with `can_view_path=true`, collaborators may still see the parent path. For instructions on how to remove this, see [Even though a folder invited via can_view_path is deleted, the path remains displayed](https://support.box.com/hc/en-us/articles/37472814319891-Even-though-a-folder-invited-via-can-view-path-is-deleted-the-path-remains-displayed)., expires_at: str(date-time) # Set the expiration date for the collaboration. At this date, the collaboration will be automatically removed from the item. This feature will only work if the **Automatically remove invited collaborators: Allow folder owners to extend the expiry date** setting has been enabled in the **Enterprise Settings** of the **Admin Console**. When the setting is not enabled, collaborations can not have an expiry date and a value for this field will be result in an error.} @returns(201) {id: str, type: str, item: any?, app_item: any?, accessible_by: map, invite_email: str?, role: str, expires_at: str(date-time)?, is_access_only: bool, status: str, acknowledged_at: str(date-time), created_by: any, created_at: str(date-time), modified_at: str(date-time), acceptance_requirements_status: map{terms_of_service_requirement: map{is_accepted: bool?, terms_of_service: any}, strong_password_requirement: map{enterprise_has_strong_password_required_for_external_users: bool, user_has_strong_password: bool?}, two_factor_authentication_requirement: map{enterprise_has_two_factor_auth_enabled: bool, user_has_two_factor_authentication_enabled: bool?}}} # Returns a new collaboration object. @errors {403: Returns an error when the user does not have the right permissions to create the collaboration. * `forbidden_by_policy`: Creating a collaboration is forbidden due to information barrier restrictions.} @endgroup @group search @endpoint GET /search @desc Search for content @optional {query: str # The string to search for. This query is matched against item names, descriptions, text content of files, and various other fields of the different item types. This parameter supports a variety of operators to further refine the results returns. * `""` - by wrapping a query in double quotes only exact matches are returned by the API. Exact searches do not return search matches based on specific character sequences. Instead, they return matches based on phrases, that is, word sequences. For example: A search for `"Blue-Box"` may return search results including the sequence `"blue.box"`, `"Blue Box"`, and `"Blue-Box"`; any item containing the words `Blue` and `Box` consecutively, in the order specified. * `AND` - returns items that contain both the search terms. For example, a search for `marketing AND BoxWorks` returns items that have both `marketing` and `BoxWorks` within its text in any order. It does not return a result that only has `BoxWorks` in its text. * `OR` - returns items that contain either of the search terms. For example, a search for `marketing OR BoxWorks` returns a result that has either `marketing` or `BoxWorks` within its text. Using this operator is not necessary as we implicitly interpret multi-word queries as `OR` unless another supported boolean term is used. * `NOT` - returns items that do not contain the search term provided. For example, a search for `marketing AND NOT BoxWorks` returns a result that has only `marketing` within its text. Results containing `BoxWorks` are omitted. We do not support lower case (that is, `and`, `or`, and `not`) or mixed case (that is, `And`, `Or`, and `Not`) operators. This field is required unless the `mdfilters` parameter is defined., scope: str(user_content/enterprise_content)=user_content # Limits the search results to either the files that the user has access to, or to files available to the entire enterprise. The scope defaults to `user_content`, which limits the search results to content that is available to the currently authenticated user. The `enterprise_content` can be requested by an admin through our support channels. Once this scope has been enabled for a user, it will allow that use to query for content across the entire enterprise and not only the content that they have access to., file_extensions: [str] # Limits the search results to any files that match any of the provided file extensions. This list is a comma-separated list of file extensions without the dots., created_at_range: [str] # Limits the search results to any items created within a given date range. Date ranges are defined as comma separated RFC3339 timestamps. If the start date is omitted (`,2014-05-17T13:35:01-07:00`) anything created before the end date will be returned. If the end date is omitted (`2014-05-15T13:35:01-07:00,`) the current date will be used as the end date instead., updated_at_range: [str] # Limits the search results to any items updated within a given date range. Date ranges are defined as comma separated RFC3339 timestamps. If the start date is omitted (`,2014-05-17T13:35:01-07:00`) anything updated before the end date will be returned. If the end date is omitted (`2014-05-15T13:35:01-07:00,`) the current date will be used as the end date instead., size_range: [int] # Limits the search results to any items with a size within a given file size range. This applied to files and folders. Size ranges are defined as comma separated list of a lower and upper byte size limit (inclusive). The upper and lower bound can be omitted to create open ranges., owner_user_ids: [str] # Limits the search results to any items that are owned by the given list of owners, defined as a list of comma separated user IDs. The items still need to be owned or shared with the currently authenticated user for them to show up in the search results. If the user does not have access to any files owned by any of the users an empty result set will be returned. To search across an entire enterprise, we recommend using the `enterprise_content` scope parameter which can be requested with our support team., recent_updater_user_ids: [str] # Limits the search results to any items that have been updated by the given list of users, defined as a list of comma separated user IDs. The items still need to be owned or shared with the currently authenticated user for them to show up in the search results. If the user does not have access to any files owned by any of the users an empty result set will be returned. This feature only searches back to the last 10 versions of an item., ancestor_folder_ids: [str] # Limits the search results to items within the given list of folders, defined as a comma separated lists of folder IDs. Search results will also include items within any subfolders of those ancestor folders. The folders still need to be owned or shared with the currently authenticated user. If the folder is not accessible by this user, or it does not exist, a `HTTP 404` error code will be returned instead. To search across an entire enterprise, we recommend using the `enterprise_content` scope parameter which can be requested with our support team., content_types: [str] # Limits the search results to any items that match the search query for a specific part of the file, for example the file description. Content types are defined as a comma separated lists of Box recognized content types. The allowed content types are as follows. * `name` - The name of the item, as defined by its `name` field. * `description` - The description of the item, as defined by its `description` field. * `file_content` - The actual content of the file. * `comments` - The content of any of the comments on a file or folder. * `tags` - Any tags that are applied to an item, as defined by its `tags` field., type: str(file/folder/web_link) # Limits the search results to any items of this type. This parameter only takes one value. By default the API returns items that match any of these types. * `file` - Limits the search results to files, * `folder` - Limits the search results to folders, * `web_link` - Limits the search results to web links, also known as bookmarks., trash_content: str(non_trashed_only/trashed_only/all_items)=non_trashed_only # Determines if the search should look in the trash for items. By default, this API only returns search results for items not currently in the trash (`non_trashed_only`). * `trashed_only` - Only searches for items currently in the trash * `non_trashed_only` - Only searches for items currently not in the trash * `all_items` - Searches for both trashed and non-trashed items., mdfilters: [map] # Limits the search results to any items for which the metadata matches the provided filter. This parameter is a list that specifies exactly **one** metadata template used to filter the search results. The parameter is required unless the `query` parameter is provided., sort: str(modified_at/relevance)=relevance # Defines the order in which search results are returned. This API defaults to returning items by relevance unless this parameter is explicitly specified. * `relevance` (default) returns the results sorted by relevance to the query search term. The relevance is based on the occurrence of the search term in the items name, description, content, and additional properties. * `modified_at` returns the results ordered in descending order by date at which the item was last modified., direction: str(DESC/ASC)=DESC # Defines the direction in which search results are ordered. This API defaults to returning items in descending (`DESC`) order unless this parameter is explicitly specified. When results are sorted by `relevance` the ordering is locked to returning items in descending order of relevance, and this parameter is ignored., limit: int(int64)=30 # Defines the maximum number of items to return as part of a page of results., include_recent_shared_links: bool=false # Defines whether the search results should include any items that the user recently accessed through a shared link. When this parameter has been set to true, the format of the response of this API changes to return a list of [Search Results with Shared Links](https://developer.box.com/reference/resources/search-results-with-shared-links)., fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., offset: int(int64)=0 # The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response., deleted_user_ids: [str] # Limits the search results to items that were deleted by the given list of users, defined as a list of comma separated user IDs. The `trash_content` parameter needs to be set to `trashed_only`. If searching in trash is not performed, an empty result set is returned. The items need to be owned or shared with the currently authenticated user for them to show up in the search results. If the user does not have access to any files owned by any of the users, an empty result set is returned. Data available from 2023-02-01 onwards., deleted_at_range: [str] # Limits the search results to any items deleted within a given date range. Date ranges are defined as comma separated RFC3339 timestamps. If the start date is omitted (`2014-05-17T13:35:01-07:00`), anything deleted before the end date will be returned. If the end date is omitted (`2014-05-15T13:35:01-07:00`), the current date will be used as the end date instead. The `trash_content` parameter needs to be set to `trashed_only`. If searching in trash is not performed, then an empty result is returned. Data available from 2023-02-01 onwards.} @returns(200) Returns a collection of search results. If there are no matching search results, the `entries` array will be empty. @errors {400: Returns an error when the request was not valid. This can have multiple reasons and the `context_info` object will provide you with more details. * `missing_parameter` - Please provide at least the `query` or `mdfilters` query parameter in a search. * `invalid_parameter` - Any of the fields might not be in the right format. This could for example mean that one of the RFC3339 dates is incorrect, or a string is provided where an integer is expected., 403: Returns an error when the user does not have the permission to make this API call. * The developer provided a `scope` of `enterprise_content` but did not request this scope to be enabled for the user through our support channels., 404: Returns an error when the user does not have access to an item mentioned in the request. * The developer provided a folder ID in `ancestor_folder_ids` that either does not exist or the user does not have access to.} @endgroup @group tasks @endpoint POST /tasks @desc Create task @required {item: map{id: str, type: str} # The file to attach the task to.} @optional {action: str(review/complete)=review # The action the task assignee will be prompted to do. Must be * `review` defines an approval task that can be approved or, rejected * `complete` defines a general task which can be completed., message: str= # An optional message to include with the task., due_at: str(date-time) # Defines when the task is due. Defaults to `null` if not provided., completion_rule: str(all_assignees/any_assignee)=all_assignees # Defines which assignees need to complete this task before the task is considered completed. * `all_assignees` (default) requires all assignees to review or approve the task in order for it to be considered completed. * `any_assignee` accepts any one assignee to review or approve the task in order for it to be considered completed.} @returns(201) {id: str, type: str, item: any, due_at: str(date-time), action: str, message: str, task_assignment_collection: any, is_completed: bool, created_by: any, created_at: str(date-time), completion_rule: str} # Returns the newly created task. @errors {400: Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. This may be because the `action` or `completion_rule` are not one of the allowed values., 403: Returns an error when the user does not have the permission to create a task on the file., 404: Returns an error when the file could not be found or the user does not have access to the file.} @endpoint GET /tasks/{task_id} @desc Get task @required {task_id: str # The ID of the task.} @returns(200) {id: str, type: str, item: any, due_at: str(date-time), action: str, message: str, task_assignment_collection: any, is_completed: bool, created_by: any, created_at: str(date-time), completion_rule: str} # Returns a task object. @errors {404: Returns an error when the task could not be found or the user does not have access to the file the task is assigned to.} @endpoint PUT /tasks/{task_id} @desc Update task @required {task_id: str # The ID of the task.} @optional {action: str(review/complete) # The action the task assignee will be prompted to do. Must be * `review` defines an approval task that can be approved or rejected, * `complete` defines a general task which can be completed., message: str # The message included with the task., due_at: str(date-time) # When the task is due at., completion_rule: str(all_assignees/any_assignee) # Defines which assignees need to complete this task before the task is considered completed. * `all_assignees` (default) requires all assignees to review or approve the task in order for it to be considered completed. * `any_assignee` accepts any one assignee to review or approve the task in order for it to be considered completed.} @returns(200) {id: str, type: str, item: any, due_at: str(date-time), action: str, message: str, task_assignment_collection: any, is_completed: bool, created_by: any, created_at: str(date-time), completion_rule: str} # Returns the updated task object. @errors {400: Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. This may be because the `action` or `completion_rule` are not one of the allowed values., 403: Returns an error when the user does not have the permission to update a task on the file., 404: Returns an error when the file could not be found or the user does not have access to the file.} @endpoint DELETE /tasks/{task_id} @desc Remove task @required {task_id: str # The ID of the task.} @returns(204) Returns an empty response when the task was successfully deleted. @errors {404: Returns an error when the task could not be found or the user does not have access to the file the task is assigned to.} @endpoint GET /tasks/{task_id}/assignments @desc List task assignments @required {task_id: str # The ID of the task.} @returns(200) {total_count: int(int64), entries: [map]} # Returns a collection of task assignment defining what task on a file has been assigned to which users and by who. @errors {404: Returns an error when the task could not be found or the user does not have access to the file the task is assigned to., 500: Returns an error if the task assignment ID was omitted in the request.} @endgroup @group task_assignments @endpoint POST /task_assignments @desc Assign task @required {task: map{id!: str, type!: str} # The task to assign to a user., assign_to: map{id: str, login: str} # The user to assign the task to.} @returns(201) {id: str, type: str, item: any, assigned_to: any, message: str, completed_at: str(date-time), assigned_at: str(date-time), reminded_at: str(date-time), resolution_state: str, assigned_by: any} # Returns a new task assignment object. @errors {403: Returns an error if a change is attempted for a completed task or the user does not have access to the item linked to the task for the given task assignment., 404: Returns an error when the task cannot be found., 500: Returns an error if any of the IDs for this request were not valid, or if the targeted user does not have access to the file.} @endpoint GET /task_assignments/{task_assignment_id} @desc Get task assignment @required {task_assignment_id: str # The ID of the task assignment.} @returns(200) {id: str, type: str, item: any, assigned_to: any, message: str, completed_at: str(date-time), assigned_at: str(date-time), reminded_at: str(date-time), resolution_state: str, assigned_by: any} # Returns a task assignment, specifying who the task has been assigned to and by whom. @errors {404: Returns an error when the task assignment could not be found or the user does not have access to the file the task is assigned to.} @endpoint PUT /task_assignments/{task_assignment_id} @desc Update task assignment @required {task_assignment_id: str # The ID of the task assignment.} @optional {message: str # An optional message by the assignee that can be added to the task., resolution_state: str(completed/incomplete/approved/rejected) # The state of the task assigned to the user. * For a task with an `action` value of `complete` this can be `incomplete` or `completed`. * For a task with an `action` of `review` this can be `incomplete`, `approved`, or `rejected`.} @returns(200) {id: str, type: str, item: any, assigned_to: any, message: str, completed_at: str(date-time), assigned_at: str(date-time), reminded_at: str(date-time), resolution_state: str, assigned_by: any} # Returns the updated task assignment object. @errors {400: Returns an error if a resolution state is incompatible with the action type of the task., 404: Returns an error when the task assignment could not be found or the user does not have access to the file the task is assigned to.} @endpoint DELETE /task_assignments/{task_assignment_id} @desc Unassign task @required {task_assignment_id: str # The ID of the task assignment.} @returns(204) Returns an empty response when the task assignment was successfully deleted. @errors {404: Returns an error if the task assignment for the given ID does not exist or is inaccessible to your account.} @endgroup @group shared_items @endpoint GET /shared_items @desc Find file for shared link @required {boxapi: str # A header containing the shared link and optional password for the shared link. The format for this header is as follows: `shared_link=[link]&shared_link_password=[password]`.} @optional {if-none-match: str # Ensures an item is only returned if it has changed. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `304 Not Modified` if the item has not changed since., fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.} @returns(200) Returns a full file resource if the shared link is valid and the user has access to it. @errors {304: Returns an empty response when the `If-None-Match` header matches the current `etag` value of the file. This indicates that the file has not changed since it was last requested.} @endgroup @group files @endpoint GET /files/{file_id}#get_shared_link @desc Get shared link for file @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`., fields: str # Explicitly request the `shared_link` fields to be returned for this item.} @returns(200) Returns the base representation of a file with the additional shared link information. @errors {401: Returned when the access token provided in the `Authorization` header is not recognized or not provided., 404: Returned if the file is not found, or the user does not have access to the file., 405: Returned if the `file_id` is not in a recognized format.} @endpoint PUT /files/{file_id}#add_shared_link @desc Add shared link to file @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`., fields: str # Explicitly request the `shared_link` fields to be returned for this item.} @optional {shared_link: map{access: str, password: str, vanity_name: str, unshared_at: str(date-time), permissions: map} # The settings for the shared link to create on the file. Use an empty object (`{}`) to use the default settings for shared links.} @returns(200) Returns the base representation of a file with a new shared link attached. @errors {400: Returned when there is an incorrect permission combination., 401: Returned when the access token provided in the `Authorization` header is not recognized or not provided., 403: Returned if the user does not have all the permissions to complete the update., 404: Returned if the file is not found, or the user does not have access to the file., 405: Returned if the `file_id` is not in a recognized format., 412: Returns an error when the `If-Match` header does not match the current `etag` value of the file. This indicates that the file has changed since it was last requested.} @endpoint PUT /files/{file_id}#update_shared_link @desc Update shared link on file @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`., fields: str # Explicitly request the `shared_link` fields to be returned for this item.} @optional {shared_link: map{access: str, password: str, vanity_name: str, unshared_at: str(date-time), permissions: map} # The settings for the shared link to update.} @returns(200) Returns a basic representation of the file, with the updated shared link attached. @errors {400: Returned when there is an incorrect permission combination., 401: Returned when the access token provided in the `Authorization` header is not recognized or not provided., 403: Returned if the user does not have all the permissions to complete the update., 404: Returned if the file is not found, or the user does not have access to the file., 405: Returned if the `file_id` is not in a recognized format., 412: Returns an error when the `If-Match` header does not match the current `etag` value of the file. This indicates that the file has changed since it was last requested.} @endpoint PUT /files/{file_id}#remove_shared_link @desc Remove shared link from file @required {file_id: str # The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`., fields: str # Explicitly request the `shared_link` fields to be returned for this item.} @optional {shared_link: map # By setting this value to `null`, the shared link is removed from the file.} @returns(200) Returns a basic representation of a file, with the shared link removed. @errors {401: Returned when the access token provided in the `Authorization` header is not recognized or not provided., 403: Returned if the user does not have all the permissions to complete the update., 404: Returned if the file is not found, or the user does not have access to the file., 405: Returned if the `file_id` is not in a recognized format., 412: Returns an error when the `If-Match` header does not match the current `etag` value of the file. This indicates that the file has changed since it was last requested.} @endgroup @group shared_items#folders @endpoint GET /shared_items#folders @desc Find folder for shared link @required {boxapi: str # A header containing the shared link and optional password for the shared link. The format for this header is as follows: `shared_link=[link]&shared_link_password=[password]`.} @optional {if-none-match: str # Ensures an item is only returned if it has changed. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `304 Not Modified` if the item has not changed since., fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.} @returns(200) Returns a full folder resource if the shared link is valid and the user has access to it. @errors {304: Returns an empty response when the `If-None-Match` header matches the current `etag` value of the folder. This indicates that the folder has not changed since it was last requested.} @endgroup @group folders @endpoint GET /folders/{folder_id}#get_shared_link @desc Get shared link for folder @required {folder_id: str # The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`., fields: str # Explicitly request the `shared_link` fields to be returned for this item.} @returns(200) Returns the base representation of a folder with the additional shared link information. @errors {401: Returned when the access token provided in the `Authorization` header is not recognized or not provided., 404: Returned if the folder is not found, or the user does not have access to the folder., 405: Returned if the `folder_id` is not in a recognized format.} @endpoint PUT /folders/{folder_id}#add_shared_link @desc Add shared link to folder @required {folder_id: str # The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`., fields: str # Explicitly request the `shared_link` fields to be returned for this item.} @optional {shared_link: map{access: str, password: str, vanity_name: str, unshared_at: str(date-time), permissions: map} # The settings for the shared link to create on the folder. Use an empty object (`{}`) to use the default settings for shared links.} @returns(200) Returns the base representation of a folder with a new shared link attached. @errors {400: Returned when there is an incorrect permission combination., 401: Returned when the access token provided in the `Authorization` header is not recognized or not provided., 403: Returned if the user does not have all the permissions to complete the update., 404: Returned if the folder is not found, or the user does not have access to the folder., 405: Returned if the `folder_id` is not in a recognized format., 412: Returns an error when the `If-Match` header does not match the current `etag` value of the folder. This indicates that the folder has changed since it was last requested.} @endpoint PUT /folders/{folder_id}#update_shared_link @desc Update shared link on folder @required {folder_id: str # The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`., fields: str # Explicitly request the `shared_link` fields to be returned for this item.} @optional {shared_link: map{access: str, password: str, vanity_name: str, unshared_at: str(date-time), permissions: map} # The settings for the shared link to update.} @returns(200) Returns a basic representation of the folder, with the updated shared link attached. @errors {400: Returned when there is an incorrect permission combination., 401: Returned when the access token provided in the `Authorization` header is not recognized or not provided., 403: Returned if the user does not have all the permissions to complete the update., 404: Returned if the folder is not found, or the user does not have access to the folder., 405: Returned if the `folder_id` is not in a recognized format., 412: Returns an error when the `If-Match` header does not match the current `etag` value of the folder. This indicates that the folder has changed since it was last requested.} @endpoint PUT /folders/{folder_id}#remove_shared_link @desc Remove shared link from folder @required {folder_id: str # The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`., fields: str # Explicitly request the `shared_link` fields to be returned for this item.} @optional {shared_link: map # By setting this value to `null`, the shared link is removed from the folder.} @returns(200) Returns a basic representation of a folder, with the shared link removed. @errors {401: Returned when the access token provided in the `Authorization` header is not recognized or not provided., 403: Returned if the user does not have all the permissions to complete the update., 404: Returned if the folder is not found, or the user does not have access to the folder., 405: Returned if the `folder_id` is not in a recognized format., 412: Returns an error when the `If-Match` header does not match the current `etag` value of the folder. This indicates that the folder has changed since it was last requested.} @endgroup @group web_links @endpoint POST /web_links @desc Create web link @required {url: str # The URL that this web link links to. Must start with `"http://"` or `"https://"`., parent: map{id!: str} # The parent folder to create the web link within.} @optional {name: str # Name of the web link. Defaults to the URL if not set., description: str # Description of the web link.} @returns(200) Returns the newly created web link object. @endpoint GET /web_links/{web_link_id} @desc Get web link @required {web_link_id: str # The ID of the web link.} @optional {boxapi: str # The URL, and optional password, for the shared link of this item. This header can be used to access items that have not been explicitly shared with a user. Use the format `shared_link=[link]` or if a password is required then use `shared_link=[link]&shared_link_password=[password]`. This header can be used on the file or folder shared, as well as on any files or folders nested within the item.} @returns(200) Returns the web link object. @endpoint POST /web_links/{web_link_id} @desc Restore web link @required {web_link_id: str # The ID of the web link.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., name: str # An optional new name for the web link., parent: any} @returns(201) {type: str, id: str, sequence_id: any, etag: str, name: str, url: str, parent: any, description: str, path_collection: any, created_at: str(date-time), modified_at: str(date-time), trashed_at: str?, purged_at: str?, created_by: any, modified_by: any, owned_by: any, shared_link: str?, item_status: str} # Returns a web link object when it has been restored. @errors {403: Returns an error if the user does not have access to the folder the web link is being restored to, or the user does not have permission to restore web link from the trash., 404: Returns an error if the web link is not in the trash., 409: Returns an error if there is an web link with the same name in the folder the web link is being restored to.} @endpoint PUT /web_links/{web_link_id} @desc Update web link @required {web_link_id: str # The ID of the web link.} @optional {url: str # The new URL that the web link links to. Must start with `"http://"` or `"https://"`., parent: any, name: str # A new name for the web link. Defaults to the URL if not set., description: str # A new description of the web link., shared_link: map{access: str, password: str, vanity_name: str, unshared_at: str(date-time)} # The settings for the shared link to update.} @returns(200) Returns the updated web link object. @endpoint DELETE /web_links/{web_link_id} @desc Remove web link @required {web_link_id: str # The ID of the web link.} @returns(204) An empty response will be returned when the web link was successfully deleted. @endpoint GET /web_links/{web_link_id}/trash @desc Get trashed web link @required {web_link_id: str # The ID of the web link.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.} @returns(200) {type: str, id: str, sequence_id: any, etag: str, name: str, url: str, parent: any, description: str, path_collection: any, created_at: str(date-time), modified_at: str(date-time), trashed_at: str(date-time)?, purged_at: str(date-time)?, created_by: any, modified_by: any, owned_by: any, shared_link: str?, item_status: str} # Returns the web link that was trashed, including information about when the it was moved to the trash. @errors {404: Returns an error if the web link is not in the trash.} @endpoint DELETE /web_links/{web_link_id}/trash @desc Permanently remove web link @required {web_link_id: str # The ID of the web link.} @returns(204) Returns an empty response when the web link was permanently deleted. @errors {404: Returns an error if the web link is not in the trash.} @endgroup @group shared_items#web_links @endpoint GET /shared_items#web_links @desc Find web link for shared link @required {boxapi: str # A header containing the shared link and optional password for the shared link. The format for this header is as follows: `shared_link=[link]&shared_link_password=[password]`.} @optional {if-none-match: str # Ensures an item is only returned if it has changed. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `304 Not Modified` if the item has not changed since., fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.} @returns(200) Returns a full web link resource if the shared link is valid and the user has access to it. @errors {304: Returns an empty response when the `If-None-Match` header matches the current `etag` value of the web link. This indicates that the web link has not changed since it was last requested.} @endgroup @group web_links @endpoint GET /web_links/{web_link_id}#get_shared_link @desc Get shared link for web link @required {web_link_id: str # The ID of the web link., fields: str # Explicitly request the `shared_link` fields to be returned for this item.} @returns(200) Returns the base representation of a web link with the additional shared link information. @errors {401: Returned when the access token provided in the `Authorization` header is not recognized or not provided., 404: Returned if the file is not found, or the user does not have access to the file., 405: Returned if the `file_id` is not in a recognized format.} @endpoint PUT /web_links/{web_link_id}#add_shared_link @desc Add shared link to web link @required {web_link_id: str # The ID of the web link., fields: str # Explicitly request the `shared_link` fields to be returned for this item.} @optional {shared_link: map{access: str, password: str, vanity_name: str, unshared_at: str(date-time), permissions: map} # The settings for the shared link to create on the web link. Use an empty object (`{}`) to use the default settings for shared links.} @returns(200) Returns the base representation of a web link with a new shared link attached. @errors {400: Returned when there is an incorrect permission combination., 401: Returned when the access token provided in the `Authorization` header is not recognized or not provided., 403: Returned if the user does not have all the permissions to complete the update., 404: Returned if the file is not found, or the user does not have access to the file., 405: Returned if the `file_id` is not in a recognized format., 412: Returns an error when the `If-Match` header does not match the current `etag` value of the file. This indicates that the file has changed since it was last requested.} @endpoint PUT /web_links/{web_link_id}#update_shared_link @desc Update shared link on web link @required {web_link_id: str # The ID of the web link., fields: str # Explicitly request the `shared_link` fields to be returned for this item.} @optional {shared_link: map{access: str, password: str, vanity_name: str, unshared_at: str(date-time), permissions: map} # The settings for the shared link to update.} @returns(200) Returns a basic representation of the web link, with the updated shared link attached. @errors {400: Returned when there is an incorrect permission combination., 401: Returned when the access token provided in the `Authorization` header is not recognized or not provided., 403: Returned if the user does not have all the permissions to complete the update., 404: Returned if the file is not found, or the user does not have access to the file., 405: Returned if the `file_id` is not in a recognized format., 412: Returns an error when the `If-Match` header does not match the current `etag` value of the file. This indicates that the file has changed since it was last requested.} @endpoint PUT /web_links/{web_link_id}#remove_shared_link @desc Remove shared link from web link @required {web_link_id: str # The ID of the web link., fields: str # Explicitly request the `shared_link` fields to be returned for this item.} @optional {shared_link: map # By setting this value to `null`, the shared link is removed from the web link.} @returns(200) Returns a basic representation of a web link, with the shared link removed. @errors {401: Returned when the access token provided in the `Authorization` header is not recognized or not provided., 403: Returned if the user does not have all the permissions to complete the update., 404: Returned if the file is not found, or the user does not have access to the file., 405: Returned if the `file_id` is not in a recognized format., 412: Returns an error when the `If-Match` header does not match the current `etag` value of the file. This indicates that the file has changed since it was last requested.} @endgroup @group shared_items#app_items @endpoint GET /shared_items#app_items @desc Find app item for shared link @required {boxapi: str # A header containing the shared link and optional password for the shared link. The format for this header is `shared_link=[link]&shared_link_password=[password]`.} @returns(200) {id: str, type: str, application_type: str} # Returns a full app item resource if the shared link is valid and the user has access to it. @endgroup @group users @endpoint GET /users @desc List enterprise users @optional {filter_term: str # Limits the results to only users who's `name` or `login` start with the search term. For externally managed users, the search term needs to completely match the in order to find the user, and it will only return one user at a time., user_type: str(all/managed/external) # Limits the results to the kind of user specified. * `all` returns every kind of user for whom the `login` or `name` partially matches the `filter_term`. It will only return an external user if the login matches the `filter_term` completely, and in that case it will only return that user. * `managed` returns all managed and app users for whom the `login` or `name` partially matches the `filter_term`. * `external` returns all external users for whom the `login` matches the `filter_term` exactly., external_app_user_id: str # Limits the results to app users with the given `external_app_user_id` value. When creating an app user, an `external_app_user_id` value can be set. This value can then be used in this endpoint to find any users that match that `external_app_user_id` value., fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., offset: int(int64)=0 # The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response., limit: int(int64) # The maximum number of items to return per page., usemarker: bool # Specifies whether to use marker-based pagination instead of offset-based pagination. Only one pagination method can be used at a time. By setting this value to true, the API will return a `marker` field that can be passed as a parameter to this endpoint to get the next page of the response., marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`.} @returns(200) Returns all of the users in the enterprise. @endpoint POST /users @desc Create user @required {name: str # The name of the user.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., login: str # The email address the user uses to log in Required, unless `is_platform_access_only` is set to `true`., is_platform_access_only: bool # Specifies that the user is an app user., role: str(coadmin/user) # The user’s enterprise role., language: str # The language of the user, formatted in modified version of the [ISO 639-1](https://developer.box.com/guides/api-calls/language-codes) format., is_sync_enabled: bool # Whether the user can use Box Sync., job_title: str # The user’s job title., phone: str # The user’s phone number., address: str # The user’s address., space_amount: int(int64) # The user’s total available space in bytes. Set this to `-1` to indicate unlimited storage., tracking_codes: [map{type: str, name: str, value: str}] # Tracking codes allow an admin to generate reports from the admin console and assign an attribute to a specific group of users. This setting must be enabled for an enterprise before it can be used., can_see_managed_users: bool # Whether the user can see other enterprise users in their contact list., timezone: str(timezone) # The user's timezone., is_external_collab_restricted: bool # Whether the user is allowed to collaborate with users outside their enterprise., is_exempt_from_device_limits: bool # Whether to exempt the user from enterprise device limits., is_exempt_from_login_verification: bool # Whether the user must use two-factor authentication., status: str(active/inactive/cannot_delete_edit/cannot_delete_edit_upload) # The user's account status., external_app_user_id: str # An external identifier for an app user, which can be used to look up the user. This can be used to tie user IDs from external identity providers to Box users.} @returns(201) Returns a user object for the newly created user. @endpoint GET /users/me @desc Get current user @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.} @returns(200) Returns a single user object. @endpoint POST /users/terminate_sessions @desc Create jobs to terminate users session @required {user_ids: [str] # A list of user IDs., user_logins: [str] # A list of user logins.} @returns(202) {message: str} # Returns a message about the request status. @errors {400: Returns an error if some of the parameters are not valid. * `Users can not be NULL or EMPTY` when no value is provided. * `User id format is string` when the provided user id format is incorrect. * `Supported payload format is JSON` when the provided payload format is incorrect., 403: Returns an error if there are insufficient permissions., 404: Returns an error if the resource could not be found., 429: Returns an error if the rate limit is exceeded., 500: Returns an error if there is an internal server issue., 503: Returns an error if the request timed out.} @endpoint GET /users/{user_id} @desc Get user @required {user_id: str # The ID of the user.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.} @returns(200) Returns a single user object. Not all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields using the [fields](#parameter-fields) parameter. @endpoint PUT /users/{user_id} @desc Update user @required {user_id: str # The ID of the user.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., enterprise: str # Set this to `null` to roll the user out of the enterprise and make them a free user., notify: bool # Whether the user should receive an email when they are rolled out of an enterprise., name: str # The name of the user., login: str # The email address the user uses to log in Note: If the target user's email is not confirmed, then the primary login address cannot be changed., role: str(coadmin/user) # The user’s enterprise role., language: str # The language of the user, formatted in modified version of the [ISO 639-1](https://developer.box.com/guides/api-calls/language-codes) format., is_sync_enabled: bool # Whether the user can use Box Sync., job_title: str # The user’s job title., phone: str # The user’s phone number., address: str # The user’s address., tracking_codes: [map{type: str, name: str, value: str}] # Tracking codes allow an admin to generate reports from the admin console and assign an attribute to a specific group of users. This setting must be enabled for an enterprise before it can be used., can_see_managed_users: bool # Whether the user can see other enterprise users in their contact list., timezone: str(timezone) # The user's timezone., is_external_collab_restricted: bool # Whether the user is allowed to collaborate with users outside their enterprise., is_exempt_from_device_limits: bool # Whether to exempt the user from enterprise device limits., is_exempt_from_login_verification: bool # Whether the user must use two-factor authentication., is_password_reset_required: bool # Whether the user is required to reset their password., status: str(active/inactive/cannot_delete_edit/cannot_delete_edit_upload) # The user's account status., space_amount: int(int64) # The user’s total available space in bytes. Set this to `-1` to indicate unlimited storage., notification_email: map{email: str} # An alternate notification email address to which email notifications are sent. When it's confirmed, this will be the email address to which notifications are sent instead of to the primary email address. Set this value to `null` to remove the notification email., external_app_user_id: str # An external identifier for an app user, which can be used to look up the user. This can be used to tie user IDs from external identity providers to Box users. Note: In order to update this field, you need to request a token using the application that created the app user.} @returns(200) Returns the updated user object. @errors {400: Returns an error if some of the parameters are missing or not valid. * `invalid_parameter` when a parameter is formatted incorrectly, for example when the `notification_email` has an incorrectly formatted email address., 403: Returns an error if the user is not allowed to make the changes. * `access_denied_insufficient_permissions` when the user does not have the right permissions, for example when updating the notification email is turned off for the enterprise. * `denied_by_policy` when the user does not have the right permissions due to the information barrier restrictions.} @endpoint DELETE /users/{user_id} @desc Delete user @required {user_id: str # The ID of the user.} @optional {notify: bool # Whether the user will receive email notification of the deletion., force: bool # Specifies whether to delete the user even if they still own files, were recently active, or recently joined the enterprise from a free account.} @returns(204) Removes the user and returns an empty response. @endpoint GET /users/{user_id}/avatar @desc Get user avatar @required {user_id: str # The ID of the user.} @returns(200) When an avatar can be found for the user the image data will be returned in the body of the response. @endpoint POST /users/{user_id}/avatar @desc Add or update user avatar @required {user_id: str # The ID of the user.} @returns(200) {pic_urls: map{small: str, large: str, preview: str}} # `ok`: Returns the `pic_urls` object with URLs to existing user avatars that were updated. @returns(201) {pic_urls: map{small: str, large: str, preview: str}} # `created`: Returns the `pic_urls` object with URLS to user avatars uploaded to Box with the request. @errors {400: `bad_request`: Returns an error when: * An image is not included in the request * The uploaded file is empty * The image size exceeds 1024 * 1024 pixels or 1MB * The file extension is other than `.jpg` or `.png`., 403: `forbidden`: Returns an error if the user does not have permissions necessary to upload an avatar or is not activated., 404: `not_found`: Returns an error if the user does not exist or cannot be found.} @endpoint DELETE /users/{user_id}/avatar @desc Delete user avatar @required {user_id: str # The ID of the user.} @returns(204) `no_content`: Removes the avatar and returns an empty response. @errors {403: `forbidden`: Returned if the user does not have necessary permissions or is not activated., 404: `not_found`: Returned if the user or user avatar does not exist or cannot be found.} @endpoint PUT /users/{user_id}/folders/0 @desc Transfer owned folders @required {user_id: str # The ID of the user., owned_by: map{id!: str} # The user who the folder will be transferred to.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., notify: bool # Determines if users should receive email notification for the action performed.} @returns(200) Returns the information for the newly created destination folder. @errors {403: Returns an error when folder ownership cannot be transferred to another user. * `forbidden_by_policy`: Returned if ownership transfer is forbidden due to information barrier restrictions. * `Cannot transfer files from/to higher privileged accounts`: You can only transfer content to or from managed users or your own account, not other co-admins or admins. Admins can transfer content between any users, including co-admins and managed users.} @endpoint GET /users/{user_id}/email_aliases @desc List user's email aliases @required {user_id: str # The ID of the user.} @returns(200) {total_count: int(int64), entries: [map]} # Returns a collection of email aliases. @endpoint POST /users/{user_id}/email_aliases @desc Create email alias @required {user_id: str # The ID of the user., email: str # The email address to add to the account as an alias. Note: The domain of the email alias needs to be registered to your enterprise. See the [domain verification guide]( https://support.box.com/hc/en-us/articles/4408619650579-Domain-Verification ) for steps to add a new domain.} @returns(201) {id: str, type: str, email: str, is_confirmed: bool} # Returns the newly created email alias object. @endpoint DELETE /users/{user_id}/email_aliases/{email_alias_id} @desc Remove email alias @required {user_id: str # The ID of the user., email_alias_id: str # The ID of the email alias.} @returns(204) Removes the alias and returns an empty response. @endpoint GET /users/{user_id}/memberships @desc List user's groups @required {user_id: str # The ID of the user.} @optional {limit: int(int64) # The maximum number of items to return per page., offset: int(int64)=0 # The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response.} @returns(200) Returns a collection of membership objects. If there are no memberships, an empty collection will be returned. @endgroup @group invites @endpoint POST /invites @desc Create user invite @required {enterprise: map{id!: str} # The enterprise to invite the user to., actionable_by: map{login: str} # The user to invite.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.} @returns(200) {id: str, type: str, invited_to: map{id: str, type: str, name: str}, actionable_by: map, invited_by: map, status: str, created_at: str(date-time), modified_at: str(date-time)} # Returns a new invite object. @errors {404: Returns `not_found` when user was not found.} @endpoint GET /invites/{invite_id} @desc Get user invite status @required {invite_id: str # The ID of an invite.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.} @returns(200) {id: str, type: str, invited_to: map{id: str, type: str, name: str}, actionable_by: map, invited_by: map, status: str, created_at: str(date-time), modified_at: str(date-time)} # Returns an invite object. @endgroup @group groups @endpoint GET /groups @desc List groups for enterprise @optional {filter_term: str # Limits the results to only groups whose `name` starts with the search term., fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., limit: int(int64) # The maximum number of items to return per page., offset: int(int64)=0 # The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response.} @returns(200) Returns a collection of group objects. If there are no groups, an empty collection will be returned. @endpoint POST /groups @desc Create group @required {name: str # The name of the new group to be created. This name must be unique within the enterprise.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., provenance: str # Keeps track of which external source this group is coming, for example `Active Directory`, or `Okta`. Setting this will also prevent Box admins from editing the group name and its members directly via the Box web application. This is desirable for one-way syncing of groups., external_sync_identifier: str # An arbitrary identifier that can be used by external group sync tools to link this Box Group to an external group. Example values of this field could be an **Active Directory Object ID** or a **Google Group ID**. We recommend you use of this field in order to avoid issues when group names are updated in either Box or external systems., description: str # A human readable description of the group., invitability_level: str(admins_only/admins_and_members/all_managed_users) # Specifies who can invite the group to collaborate on folders. When set to `admins_only` the enterprise admin, co-admins, and the group's admin can invite the group. When set to `admins_and_members` all the admins listed above and group members can invite the group. When set to `all_managed_users` all managed users in the enterprise can invite the group., member_viewability_level: str(admins_only/admins_and_members/all_managed_users) # Specifies who can see the members of the group. * `admins_only` - the enterprise admin, co-admins, group's group admin. * `admins_and_members` - all admins and group members. * `all_managed_users` - all managed users in the enterprise.} @returns(201) Returns the new group object. @errors {409: Returns an error a conflict is stopping the group from being created. * `invalid_parameter`: Often returned if the group name is not unique in the enterprise.} @endpoint POST /groups/terminate_sessions @desc Create jobs to terminate user group session @required {group_ids: [str] # A list of group IDs.} @returns(202) {message: str} # Returns a message about the request status. @errors {400: Returns an error if some of the parameters are not valid. * `Groups can not be NULL or EMPTY` when no value is provided. * `group id format is string` when the provided group id format is incorrect. * `Supported payload format is JSON` when the provided payload format is incorrect., 403: Returns an error if there are insufficient permissions., 404: Returns an error if the resource could not be found., 429: Returns an error if the request limit is exceeded., 500: Returns an error if there is an internal server issue., 503: Returns an error if the request timed out.} @endpoint GET /groups/{group_id} @desc Get group @required {group_id: str # The ID of the group.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.} @returns(200) Returns the group object. @endpoint PUT /groups/{group_id} @desc Update group @required {group_id: str # The ID of the group.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., name: str # The name of the new group to be created. Must be unique within the enterprise., provenance: str # Keeps track of which external source this group is coming, for example `Active Directory`, or `Okta`. Setting this will also prevent Box admins from editing the group name and its members directly via the Box web application. This is desirable for one-way syncing of groups., external_sync_identifier: str # An arbitrary identifier that can be used by external group sync tools to link this Box Group to an external group. Example values of this field could be an **Active Directory Object ID** or a **Google Group ID**. We recommend you use of this field in order to avoid issues when group names are updated in either Box or external systems., description: str # A human readable description of the group., invitability_level: str(admins_only/admins_and_members/all_managed_users) # Specifies who can invite the group to collaborate on folders. When set to `admins_only` the enterprise admin, co-admins, and the group's admin can invite the group. When set to `admins_and_members` all the admins listed above and group members can invite the group. When set to `all_managed_users` all managed users in the enterprise can invite the group., member_viewability_level: str(admins_only/admins_and_members/all_managed_users) # Specifies who can see the members of the group. * `admins_only` - the enterprise admin, co-admins, group's group admin. * `admins_and_members` - all admins and group members. * `all_managed_users` - all managed users in the enterprise.} @returns(200) Returns the updated group object. @errors {409: Returns an error a conflict is stopping the group from being created. * `invalid_parameter`: Often returned if the group name is not unique in the enterprise.} @endpoint DELETE /groups/{group_id} @desc Remove group @required {group_id: str # The ID of the group.} @returns(204) A blank response is returned if the group was successfully deleted. @endpoint GET /groups/{group_id}/memberships @desc List members of group @required {group_id: str # The ID of the group.} @optional {limit: int(int64) # The maximum number of items to return per page., offset: int(int64)=0 # The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response.} @returns(200) Returns a collection of membership objects. If there are no memberships, an empty collection will be returned. @endpoint GET /groups/{group_id}/collaborations @desc List group collaborations @required {group_id: str # The ID of the group.} @optional {limit: int(int64) # The maximum number of items to return per page., offset: int(int64)=0 # The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response.} @returns(200) Returns a collection of collaboration objects. If there are no collaborations, an empty collection will be returned. @endgroup @group group_memberships @endpoint POST /group_memberships @desc Add user to group @required {user: map{id!: str} # The user to add to the group., group: map{id!: str} # The group to add the user to.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., role: str(member/admin) # The role of the user in the group., configurable_permissions: map # Custom configuration for the permissions an admin if a group will receive. This option has no effect on members with a role of `member`. Setting these permissions overwrites the default access levels of an admin. Specifying a value of `null` for this object will disable all configurable permissions. Specifying permissions will set them accordingly, omitted permissions will be enabled by default.} @returns(201) {id: str, type: str, user: any, group: any, role: str, created_at: str(date-time), modified_at: str(date-time)} # Returns a new group membership object. @errors {403: Returns an error when the user cannot be added to a group. * `forbidden_by_policy`: Adding a user to a group is forbidden due to information barrier restrictions.} @endpoint GET /group_memberships/{group_membership_id} @desc Get group membership @required {group_membership_id: str # The ID of the group membership.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.} @returns(200) {id: str, type: str, user: any, group: any, role: str, created_at: str(date-time), modified_at: str(date-time)} # Returns the group membership object. @endpoint PUT /group_memberships/{group_membership_id} @desc Update group membership @required {group_membership_id: str # The ID of the group membership.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., role: str(member/admin) # The role of the user in the group., configurable_permissions: map # Custom configuration for the permissions an admin if a group will receive. This option has no effect on members with a role of `member`. Setting these permissions overwrites the default access levels of an admin. Specifying a value of `null` for this object will disable all configurable permissions. Specifying permissions will set them accordingly, omitted permissions will be enabled by default.} @returns(200) {id: str, type: str, user: any, group: any, role: str, created_at: str(date-time), modified_at: str(date-time)} # Returns a new group membership object. @endpoint DELETE /group_memberships/{group_membership_id} @desc Remove user from group @required {group_membership_id: str # The ID of the group membership.} @returns(204) A blank response is returned if the membership was successfully deleted. @endgroup @group webhooks @endpoint GET /webhooks @desc List all webhooks @optional {marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`., limit: int(int64) # The maximum number of items to return per page.} @returns(200) Returns a list of webhooks. @errors {403: Returns an error if the application does not have the permission to manage webhooks.} @endpoint POST /webhooks @desc Create webhook @required {target: map{id: str, type: str} # The item that will trigger the webhook., address: str # The URL that is notified by this webhook., triggers: [str] # An array of event names that this webhook is to be triggered for.} @returns(201) Returns the new webhook object. @errors {400: Returns an error if the parameters were incorrect., 403: Returns an error if the application does not have the permission to manage webhooks., 404: Returns an error if the target item could not be found., 409: Returns an error if the a webhook for this combination of target, application, and user already exists.} @endpoint GET /webhooks/{webhook_id} @desc Get webhook @required {webhook_id: str # The ID of the webhook.} @returns(200) Returns a webhook object. @errors {403: Returns an error if the application does not have the permission to manage webhooks., 404: Returns an error if the webhook could not be found.} @endpoint PUT /webhooks/{webhook_id} @desc Update webhook @required {webhook_id: str # The ID of the webhook.} @optional {target: map{id: str, type: str} # The item that will trigger the webhook., address: str # The URL that is notified by this webhook., triggers: [str] # An array of event names that this webhook is to be triggered for.} @returns(200) Returns the new webhook object. @errors {400: Returns an error if the parameters were incorrect., 403: Returns an error if the application does not have the permission to manage webhooks., 404: Returns an error if the target item or webhook could not be found., 409: Returns an error if the a webhook for this combination of target, application, and user already exists.} @endpoint DELETE /webhooks/{webhook_id} @desc Remove webhook @required {webhook_id: str # The ID of the webhook.} @returns(204) An empty response will be returned when the webhook was successfully deleted. @errors {403: Returns an error if the application does not have the permission to manage webhooks., 404: Returns an error if the webhook could not be found.} @endgroup @group skill_invocations @endpoint PUT /skill_invocations/{skill_id} @desc Update all Box Skill cards on file @required {skill_id: str # The ID of the skill to apply this metadata for., status: str(invoked/processing/success/transient_failure/permanent_failure) # Defines the status of this invocation. Set this to `success` when setting Skill cards., metadata: map{cards: [map]} # The metadata to set for this skill. This is a list of Box Skills cards. These cards will overwrite any existing Box skill cards on the file., file: map{type: str, id: str} # The file to assign the cards to.} @optional {file_version: map{type: str, id: str} # The optional file version to assign the cards to., usage: map{unit: str, value: num} # A descriptor that defines what items are affected by this call. Set this to the default values when setting a card to a `success` state, and leave it out in most other situations.} @returns(200) Returns an empty response when the card has been successfully updated. @errors {400: Returns an error when the request body is not valid. * `schema_validation_failed` - The request body contains a value for a field that either does not exist, or for which the value or type does not match the expected field type. An example might be an unknown option for an `enum` or `multiSelect` field., 404: Returns an error when the file could not be found or the user does not have access. * `not_found` - The file could not be found, or the user does not have access to the file.} @endgroup @group events @endpoint OPTIONS /events @desc Get events long poll endpoint @returns(200) {chunk_size: int(int64), entries: [map]} # Returns a paginated array of servers that can be used instead of the regular endpoints for long-polling events. @endpoint GET /events @desc List user and enterprise events @optional {stream_type: str(all/changes/sync/admin_logs/admin_logs_streaming)=all # Defines the type of events that are returned * `all` returns everything for a user and is the default * `changes` returns events that may cause file tree changes such as file updates or collaborations. * `sync` is similar to `changes` but only applies to synced folders * `admin_logs` returns all events for an entire enterprise and requires the user making the API call to have admin permissions. This stream type is for programmatically pulling from a 1 year history of events across all users within the enterprise and within a `created_after` and `created_before` time frame. The complete history of events will be returned in chronological order based on the event time, but latency will be much higher than `admin_logs_streaming`. * `admin_logs_streaming` returns all events for an entire enterprise and requires the user making the API call to have admin permissions. This stream type is for polling for recent events across all users within the enterprise. Latency will be much lower than `admin_logs`, but events will not be returned in chronological order and may contain duplicates., stream_position: str # The location in the event stream to start receiving events from. * `now` will return an empty list events and the latest stream position for initialization. * `0` or `null` will return all events., limit: int(int64)=100 # Limits the number of events returned. Note: Sometimes, the events less than the limit requested can be returned even when there may be more events remaining. This is primarily done in the case where a number of events have already been retrieved and these retrieved events are returned rather than delaying for an unknown amount of time to see if there are any more results., event_type: [str] # A comma-separated list of events to filter by. This can only be used when requesting the events with a `stream_type` of `admin_logs` or `adming_logs_streaming`. For any other `stream_type` this value will be ignored., created_after: str(date-time) # The lower bound date and time to return events for. This can only be used when requesting the events with a `stream_type` of `admin_logs`. For any other `stream_type` this value will be ignored., created_before: str(date-time) # The upper bound date and time to return events for. This can only be used when requesting the events with a `stream_type` of `admin_logs`. For any other `stream_type` this value will be ignored.} @returns(200) {chunk_size: int(int64), next_stream_position: any, entries: [map]} # Returns a list of event objects. Events objects are returned in pages, with each page (chunk) including a list of event objects. The response includes a `chunk_size` parameter indicating how many events were returned in this chunk, as well as the next `stream_position` that can be queried. @endgroup @group collections @endpoint GET /collections @desc List all collections @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., offset: int(int64)=0 # The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response., limit: int(int64) # The maximum number of items to return per page.} @returns(200) Returns all collections for the given user. @endpoint GET /collections/{collection_id}/items @desc List collection items @required {collection_id: str # The ID of the collection.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., offset: int(int64)=0 # The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response., limit: int(int64) # The maximum number of items to return per page.} @returns(200) Returns an array of items in the collection. @endpoint GET /collections/{collection_id} @desc Get collection by ID @required {collection_id: str # The ID of the collection.} @returns(200) {id: str, type: str, name: str, collection_type: str} # Returns an array of items in the collection. @endgroup @group recent_items @endpoint GET /recent_items @desc List recently accessed items @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., limit: int(int64) # The maximum number of items to return per page., marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`.} @returns(200) Returns a list recent items access by a user. @endgroup @group retention_policies @endpoint GET /retention_policies @desc List retention policies @optional {policy_name: str # Filters results by a case sensitive prefix of the name of retention policies., policy_type: str(finite/indefinite) # Filters results by the type of retention policy., created_by_user_id: str # Filters results by the ID of the user who created policy., fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., limit: int(int64) # The maximum number of items to return per page., marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.} @returns(200) Returns a list retention policies in the enterprise. @errors {400: Returns a `bad_request` if a non existent `policy_type` was specified., 404: Returns a `not_found` error if the user specified in `created_by_user_id` does not exist.} @endpoint POST /retention_policies @desc Create retention policy @required {policy_name: str # The name for the retention policy., policy_type: str(finite/indefinite) # The type of the retention policy. A retention policy type can either be `finite`, where a specific amount of time to retain the content is known upfront, or `indefinite`, where the amount of time to retain the content is still unknown., disposition_action: str(permanently_delete/remove_retention) # The disposition action of the retention policy. `permanently_delete` deletes the content retained by the policy permanently. `remove_retention` lifts retention policy from the content, allowing it to be deleted by users once the retention policy has expired.} @optional {description: str # The additional text description of the retention policy., retention_length: any # The length of the retention policy. This value specifies the duration in days that the retention policy will be active for after being assigned to content. If the policy has a `policy_type` of `indefinite`, the `retention_length` will also be `indefinite`., retention_type: str(modifiable/non_modifiable) # Specifies the retention type: * `modifiable`: You can modify the retention policy. For example, you can add or remove folders, shorten or lengthen the policy duration, or delete the assignment. Use this type if your retention policy is not related to any regulatory purposes. * `non_modifiable`: You can modify the retention policy only in a limited way: add a folder, lengthen the duration, retire the policy, change the disposition action or notification settings. You cannot perform other actions, such as deleting the assignment or shortening the policy duration. Use this type to ensure compliance with regulatory retention policies., can_owner_extend_retention: bool # Whether the owner of a file will be allowed to extend the retention., are_owners_notified: bool # Whether owner and co-owners of a file are notified when the policy nears expiration., custom_notification_recipients: [map] # A list of users notified when the retention policy duration is about to end.} @returns(201) Returns a new retention policy object. @errors {400: Returns a `bad_request` error with the `retention_length` was specified for a `infinite` retention policy, an incorrect `disposition_action` was set, or description exceeds maximum length of 500 characters., 409: Returns an error if a retention policy with the given name already exists.} @endpoint GET /retention_policies/{retention_policy_id} @desc Get retention policy @required {retention_policy_id: str # The ID of the retention policy.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.} @returns(200) Returns the retention policy object. @endpoint PUT /retention_policies/{retention_policy_id} @desc Update retention policy @required {retention_policy_id: str # The ID of the retention policy.} @optional {policy_name: str # The name for the retention policy., description: str # The additional text description of the retention policy., disposition_action: any # The disposition action of the retention policy. This action can be `permanently_delete`, which will cause the content retained by the policy to be permanently deleted, or `remove_retention`, which will lift the retention policy from the content, allowing it to be deleted by users, once the retention policy has expired. You can use `null` if you don't want to change `disposition_action`., retention_type: str # Specifies the retention type: * `modifiable`: You can modify the retention policy. For example, you can add or remove folders, shorten or lengthen the policy duration, or delete the assignment. Use this type if your retention policy is not related to any regulatory purposes. * `non-modifiable`: You can modify the retention policy only in a limited way: add a folder, lengthen the duration, retire the policy, change the disposition action or notification settings. You cannot perform other actions, such as deleting the assignment or shortening the policy duration. Use this type to ensure compliance with regulatory retention policies. When updating a retention policy, you can use `non-modifiable` type only. You can convert a `modifiable` policy to `non-modifiable`, but not the other way around., retention_length: any # The length of the retention policy. This value specifies the duration in days that the retention policy will be active for after being assigned to content. If the policy has a `policy_type` of `indefinite`, the `retention_length` will also be `indefinite`., status: str # Used to retire a retention policy. If not retiring a policy, do not include this parameter or set it to `null`., can_owner_extend_retention: bool # Determines if the owner of items under the policy can extend the retention when the original retention duration is about to end., are_owners_notified: bool # Determines if owners and co-owners of items under the policy are notified when the retention duration is about to end., custom_notification_recipients: [map{id!: str, type!: str}] # A list of users notified when the retention duration is about to end.} @returns(200) Returns the updated retention policy object. @errors {400: Returns a `bad_request` if an incorrect `disposition_action` was set or description exceeds maximum length of 500 characters., 403: Returns an error when a user wants to shorten the duration of a non-modifiable policy, or to convert a non-modifiable policy to a modifiable one. Note: Lengthening policy duration is allowed., 409: Returns an error if a retention policy with the given name already exists.} @endpoint DELETE /retention_policies/{retention_policy_id} @desc Delete retention policy @required {retention_policy_id: str # The ID of the retention policy.} @returns(204) Returns an empty response when the policy has been deleted. @errors {403: Returns an error if the policy is non-modifiable or the user does not have the required access to perform the action., 404: Returns an error if the policy is not found.} @endpoint GET /retention_policies/{retention_policy_id}/assignments @desc List retention policy assignments @required {retention_policy_id: str # The ID of the retention policy.} @optional {type: str(folder/enterprise/metadata_template) # The type of the retention policy assignment to retrieve., fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination., limit: int(int64) # The maximum number of items to return per page.} @returns(200) Returns a list of the retention policy assignments associated with the specified retention policy. @errors {400: Returns an error if an unknown `type` is specified.} @endgroup @group retention_policy_assignments @endpoint POST /retention_policy_assignments @desc Assign retention policy @required {policy_id: str # The ID of the retention policy to assign., assign_to: map{type!: str, id: str} # The item to assign the policy to.} @optional {filter_fields: [map{field: str, value: str}] # If the `assign_to` type is `metadata_template`, then optionally add the `filter_fields` parameter which will require an array of objects with a field entry and a value entry. Currently only one object of `field` and `value` is supported., start_date_field: str # The date the retention policy assignment begins. If the `assigned_to` type is `metadata_template`, this field can be a date field's metadata attribute key id.} @returns(201) {id: str, type: str, retention_policy: any, assigned_to: map{id: str?, type: str}, filter_fields: [map]?, assigned_by: any, assigned_at: str(date-time), start_date_field: str} # Returns a new retention policy assignment object. @errors {400: Returns an error if an `id` is specified while assigning the retention policy to an enterprise. Returns an error if `start_date_field` is present but `assign_to.type` is not `metadata_template` Returns an error if `start_date_field` is present, but belongs to a different metadata template than the one specified in `assign_to.id` Returns an error if `start_date_field` is present, but the `retention_policy` has a `retention_length` of "indefinite" Returns an error if `start_date_field` is present, but cannot be resolved to a valid metadata date field., 404: Returns an error if no retention policy with the given `policy_id` exists., 409: Returns an error if a retention policy of equal or greater length has already been assigned to this item.} @endpoint GET /retention_policy_assignments/{retention_policy_assignment_id} @desc Get retention policy assignment @required {retention_policy_assignment_id: str # The ID of the retention policy assignment.} @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.} @returns(200) {id: str, type: str, retention_policy: any, assigned_to: map{id: str?, type: str}, filter_fields: [map]?, assigned_by: any, assigned_at: str(date-time), start_date_field: str} # Returns the retention policy assignment object. @endpoint DELETE /retention_policy_assignments/{retention_policy_assignment_id} @desc Remove retention policy assignment @required {retention_policy_assignment_id: str # The ID of the retention policy assignment.} @returns(204) Returns an empty response when the policy assignment is successfully deleted. @errors {403: Returns an error when the assignment relates to a retention policy that cannot be modified., 404: Returns an error when the retention policy assignment does not exist.} @endpoint GET /retention_policy_assignments/{retention_policy_assignment_id}/files_under_retention @desc Get files under retention @required {retention_policy_assignment_id: str # The ID of the retention policy assignment.} @optional {marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`., limit: int(int64) # The maximum number of items to return per page.} @returns(200) Returns a list of files under retention that are associated with the specified retention policy assignment. @errors {400: Returns an error if `retention_policy_assignment_id` is not specified.} @endpoint GET /retention_policy_assignments/{retention_policy_assignment_id}/file_versions_under_retention @desc Get file versions under retention @required {retention_policy_assignment_id: str # The ID of the retention policy assignment.} @optional {marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`., limit: int(int64) # The maximum number of items to return per page.} @returns(200) Returns a list of file versions under retention that are associated with the specified retention policy assignment. @errors {400: Returns an error if `retention_policy_assignment_id` is not specified.} @endgroup @group legal_hold_policies @endpoint GET /legal_hold_policies @desc List all legal hold policies @optional {policy_name: str # Limits results to policies for which the names start with this search term. This is a case-insensitive prefix., fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`., limit: int(int64) # The maximum number of items to return per page.} @returns(200) Returns a list of legal hold policies. @endpoint POST /legal_hold_policies @desc Create legal hold policy @required {policy_name: str # The name of the policy.} @optional {description: str # A description for the policy., filter_started_at: str(date-time) # The filter start date. When this policy is applied using a `custodian` legal hold assignments, it will only apply to file versions created or uploaded inside of the date range. Other assignment types, such as folders and files, will ignore the date filter. Required if `is_ongoing` is set to `false`., filter_ended_at: str(date-time) # The filter end date. When this policy is applied using a `custodian` legal hold assignments, it will only apply to file versions created or uploaded inside of the date range. Other assignment types, such as folders and files, will ignore the date filter. Required if `is_ongoing` is set to `false`., is_ongoing: bool # Whether new assignments under this policy should continue applying to files even after initialization. When this policy is applied using a legal hold assignment, it will continue applying the policy to any new file versions even after it has been applied. For example, if a legal hold assignment is placed on a user today, and that user uploads a file tomorrow, that file will get held. This will continue until the policy is retired. Required if no filter dates are set.} @returns(201) Returns a new legal hold policy object. @errors {400: Returns an error if required parameters are missing, or neither `is_ongoing` or filter dates are specified., 409: Returns an error if a policy with this name already exists.} @endpoint GET /legal_hold_policies/{legal_hold_policy_id} @desc Get legal hold policy @required {legal_hold_policy_id: str # The ID of the legal hold policy.} @returns(200) Returns a legal hold policy object. @endpoint PUT /legal_hold_policies/{legal_hold_policy_id} @desc Update legal hold policy @required {legal_hold_policy_id: str # The ID of the legal hold policy.} @optional {policy_name: str # The name of the policy., description: str # A description for the policy., release_notes: str # Notes around why the policy was released.} @returns(200) Returns a new legal hold policy object. @errors {409: Returns an error if a policy with this name already exists.} @endpoint DELETE /legal_hold_policies/{legal_hold_policy_id} @desc Remove legal hold policy @required {legal_hold_policy_id: str # The ID of the legal hold policy.} @returns(202) A blank response is returned if the policy was successfully deleted. @endgroup @group legal_hold_policy_assignments @endpoint GET /legal_hold_policy_assignments @desc List legal hold policy assignments @required {policy_id: str # The ID of the legal hold policy.} @optional {assign_to_type: str(file/file_version/folder/user/ownership/interactions) # Filters the results by the type of item the policy was applied to., assign_to_id: str # Filters the results by the ID of item the policy was applied to., marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`., limit: int(int64) # The maximum number of items to return per page., fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.} @returns(200) Returns a list of legal hold policy assignments. @endpoint POST /legal_hold_policy_assignments @desc Assign legal hold policy @required {policy_id: str # The ID of the policy to assign., assign_to: map{type!: str, id!: str} # The item to assign the policy to.} @returns(201) Returns a new legal hold policy assignment. @endpoint GET /legal_hold_policy_assignments/{legal_hold_policy_assignment_id} @desc Get legal hold policy assignment @required {legal_hold_policy_assignment_id: str # The ID of the legal hold policy assignment.} @returns(200) Returns a legal hold policy object. @endpoint DELETE /legal_hold_policy_assignments/{legal_hold_policy_assignment_id} @desc Unassign legal hold policy @required {legal_hold_policy_assignment_id: str # The ID of the legal hold policy assignment.} @returns(202) A blank response is returned if the assignment was successfully deleted. @endpoint GET /legal_hold_policy_assignments/{legal_hold_policy_assignment_id}/files_on_hold @desc List files with current file versions for legal hold policy assignment @required {legal_hold_policy_assignment_id: str # The ID of the legal hold policy assignment.} @optional {marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`., limit: int(int64) # The maximum number of items to return per page., fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.} @returns(200) Returns the list of current file versions held under legal hold for a specific legal hold policy assignment. @endgroup @group file_version_retentions @endpoint GET /file_version_retentions @desc List file version retentions @optional {file_id: str # Filters results by files with this ID., file_version_id: str # Filters results by file versions with this ID., policy_id: str # Filters results by the retention policy with this ID., disposition_action: str(permanently_delete/remove_retention) # Filters results by the retention policy with this disposition action., disposition_before: str # Filters results by files that will have their disposition come into effect before this date., disposition_after: str # Filters results by files that will have their disposition come into effect after this date., limit: int(int64) # The maximum number of items to return per page., marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`.} @returns(200) Returns a list of all file version retentions for the enterprise. @endgroup @group legal_hold_policy_assignments @endpoint GET /legal_hold_policy_assignments/{legal_hold_policy_assignment_id}/file_versions_on_hold @desc List previous file versions for legal hold policy assignment @required {legal_hold_policy_assignment_id: str # The ID of the legal hold policy assignment.} @optional {marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`., limit: int(int64) # The maximum number of items to return per page., fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.} @returns(200) Returns the list of previous file versions held under legal hold for a specific legal hold policy assignment. @endgroup @group file_version_retentions @endpoint GET /file_version_retentions/{file_version_retention_id} @desc Get retention on file @required {file_version_retention_id: str # The ID of the file version retention.} @returns(200) {id: str, type: str, file_version: any, file: any, applied_at: str(date-time), disposition_at: str(date-time), winning_retention_policy: any} # Returns a file version retention object. @endgroup @group file_version_legal_holds @endpoint GET /file_version_legal_holds/{file_version_legal_hold_id} @desc Get file version legal hold @required {file_version_legal_hold_id: str # The ID of the file version legal hold.} @returns(200) {id: str, type: str, file_version: any, file: any, legal_hold_policy_assignments: [map], deleted_at: str(date-time)} # Returns the legal hold policy assignments for the file version. @endpoint GET /file_version_legal_holds @desc List file version legal holds @required {policy_id: str # The ID of the legal hold policy to get the file version legal holds for.} @optional {marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`., limit: int(int64) # The maximum number of items to return per page.} @returns(200) Returns the list of file version legal holds for a specific legal hold policy. @endgroup @group shield_information_barriers @endpoint GET /shield_information_barriers/{shield_information_barrier_id} @desc Get shield information barrier with specified ID @required {shield_information_barrier_id: str # The ID of the shield information barrier.} @returns(200) {id: str, type: str, enterprise: any, status: str, created_at: str(date-time), created_by: any, updated_at: str(date-time), updated_by: any, enabled_at: str(date-time), enabled_by: any} # Returns the shield information barrier object. @errors {404: Returns a `not_found` error if the shield information barrier was not found.} @endpoint POST /shield_information_barriers/change_status @desc Add changed status of shield information barrier with specified ID @required {id: str # The ID of the shield information barrier., status: str(pending/disabled) # The desired status for the shield information barrier.} @returns(200) {id: str, type: str, enterprise: any, status: str, created_at: str(date-time), created_by: any, updated_at: str(date-time), updated_by: any, enabled_at: str(date-time), enabled_by: any} # Returns the updated shield information barrier object. @errors {404: Returns a `not_found` error if the shield information barrier was not found., 409: Returns an error if there exists Conflicts with existing information barriers.} @endpoint GET /shield_information_barriers @desc List shield information barriers @optional {marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination., limit: int(int64) # The maximum number of items to return per page.} @returns(200) Returns a paginated list of shield information barrier objects, empty list if currently no barrier. @errors {404: Returns a `not_found` error if could not find an enterprise using JWT.} @endpoint POST /shield_information_barriers @desc Create shield information barrier @required {enterprise: any # The `type` and `id` of enterprise this barrier is under.} @returns(201) {id: str, type: str, enterprise: any, status: str, created_at: str(date-time), created_by: any, updated_at: str(date-time), updated_by: any, enabled_at: str(date-time), enabled_by: any} # Returns a new shield information barrier object. @errors {400: Returns an error if the enterprise is missing from the request., 404: Returns an error when an incorrect or null enterprise is present in the request body.} @endgroup @group shield_information_barrier_reports @endpoint GET /shield_information_barrier_reports @desc List shield information barrier reports @required {shield_information_barrier_id: str # The ID of the shield information barrier.} @optional {marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`., limit: int(int64) # The maximum number of items to return per page.} @returns(200) Returns a paginated list of shield information barrier report objects. @errors {404: Returns a `not_found` error if the Shield Information Barrier could not be found.} @endpoint POST /shield_information_barrier_reports @desc Create shield information barrier report @optional {shield_information_barrier: map{id: str, type: str} # A base representation of a shield information barrier object.} @returns(201) Returns the shield information barrier report information object. @errors {404: Returns a `not_found` error if the shield information barrier report was not found., 409: Returns a `conflict` error if a shield information barrier report is currently being created.} @endpoint GET /shield_information_barrier_reports/{shield_information_barrier_report_id} @desc Get shield information barrier report by ID @required {shield_information_barrier_report_id: str # The ID of the shield information barrier Report.} @returns(200) Returns the shield information barrier report object. @errors {404: Returns a `not_found` error if the shield information barrier Report was not found.} @endgroup @group shield_information_barrier_segments @endpoint GET /shield_information_barrier_segments/{shield_information_barrier_segment_id} @desc Get shield information barrier segment with specified ID @required {shield_information_barrier_segment_id: str # The ID of the shield information barrier segment.} @returns(200) {id: str, type: str, shield_information_barrier: map{id: str, type: str}, name: str, description: str, created_at: str(date-time), created_by: any, updated_at: str(date-time), updated_by: any} # Returns the shield information barrier segment object. @errors {404: Returns a `not_found` error if the shield information barrier segment was not found.} @endpoint DELETE /shield_information_barrier_segments/{shield_information_barrier_segment_id} @desc Delete shield information barrier segment @required {shield_information_barrier_segment_id: str # The ID of the shield information barrier segment.} @returns(204) Empty body in response. @errors {404: Returns a `not_found` error if the shield information barrier segment with specified ID was not found.} @endpoint PUT /shield_information_barrier_segments/{shield_information_barrier_segment_id} @desc Update shield information barrier segment with specified ID @required {shield_information_barrier_segment_id: str # The ID of the shield information barrier segment.} @optional {name: str # The updated name for the shield information barrier segment., description: str # The updated description for the shield information barrier segment.} @returns(200) {id: str, type: str, shield_information_barrier: map{id: str, type: str}, name: str, description: str, created_at: str(date-time), created_by: any, updated_at: str(date-time), updated_by: any} # Returns the updated shield information barrier segment object. @errors {404: Returns a `not_found` error if the shield information Barrier Segment was not found., 409: Returns an error if there exists a shield information Barrier Segment with the same name.} @endpoint GET /shield_information_barrier_segments @desc List shield information barrier segments @required {shield_information_barrier_id: str # The ID of the shield information barrier.} @optional {marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`., limit: int(int64) # The maximum number of items to return per page.} @returns(200) Returns a paginated list of shield information barrier segment objects. @errors {404: Returns a `not_found` error if the shield information Barrier of given ID was not found.} @endpoint POST /shield_information_barrier_segments @desc Create shield information barrier segment @required {shield_information_barrier: map{id: str, type: str} # A base representation of a shield information barrier object., name: str # Name of the shield information barrier segment.} @optional {description: str # Description of the shield information barrier segment.} @returns(201) {id: str, type: str, shield_information_barrier: map{id: str, type: str}, name: str, description: str, created_at: str(date-time), created_by: any, updated_at: str(date-time), updated_by: any} # Returns a new shield information barrier segment object. @errors {404: Returns an error if the shield information barrier was not found., 409: Returns an error if there exists an shield information barrier segment with same name.} @endgroup @group shield_information_barrier_segment_members @endpoint GET /shield_information_barrier_segment_members/{shield_information_barrier_segment_member_id} @desc Get shield information barrier segment member by ID @required {shield_information_barrier_segment_member_id: str # The ID of the shield information barrier segment Member.} @returns(200) Returns the shield information barrier segment member object. @errors {404: Returns a `not_found` error if the shield information barrier segment member was not found.} @endpoint DELETE /shield_information_barrier_segment_members/{shield_information_barrier_segment_member_id} @desc Delete shield information barrier segment member by ID @required {shield_information_barrier_segment_member_id: str # The ID of the shield information barrier segment Member.} @returns(204) Returns an empty response if the segment member was deleted successfully. @errors {404: Returns a `not_found` error if the shield information barrier segment member was not found.} @endpoint GET /shield_information_barrier_segment_members @desc List shield information barrier segment members @required {shield_information_barrier_segment_id: str # The ID of the shield information barrier segment.} @optional {marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`., limit: int(int64) # The maximum number of items to return per page.} @returns(200) Returns a paginated list of shield information barrier segment member objects. @endpoint POST /shield_information_barrier_segment_members @desc Create shield information barrier segment member @required {shield_information_barrier_segment: map{id: str, type: str} # The `type` and `id` of the requested shield information barrier segment., user: any # User to which restriction will be applied.} @optional {type: str # A type of the shield barrier segment member., shield_information_barrier: map{id: str, type: str} # A base representation of a shield information barrier object.} @returns(201) Returns a new shield information barrier segment member object. @errors {404: Returns an error if the shield information barrier or segment was not found.} @endgroup @group shield_information_barrier_segment_restrictions @endpoint GET /shield_information_barrier_segment_restrictions/{shield_information_barrier_segment_restriction_id} @desc Get shield information barrier segment restriction by ID @required {shield_information_barrier_segment_restriction_id: str # The ID of the shield information barrier segment Restriction.} @returns(200) Returns the shield information barrier segment restriction object. @errors {404: Returns a `not_found` error if the shield information barrier segment restriction was not found.} @endpoint DELETE /shield_information_barrier_segment_restrictions/{shield_information_barrier_segment_restriction_id} @desc Delete shield information barrier segment restriction by ID @required {shield_information_barrier_segment_restriction_id: str # The ID of the shield information barrier segment Restriction.} @returns(204) Empty body in response. @errors {404: Returns a `not_found` error if the shield information barrier segment restriction was not found.} @endpoint GET /shield_information_barrier_segment_restrictions @desc List shield information barrier segment restrictions @required {shield_information_barrier_segment_id: str # The ID of the shield information barrier segment.} @optional {marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`., limit: int(int64) # The maximum number of items to return per page.} @returns(200) Returns a paginated list of shield information barrier segment restriction objects. @endpoint POST /shield_information_barrier_segment_restrictions @desc Create shield information barrier segment restriction @required {type: str # The type of the shield barrier segment restriction for this member., shield_information_barrier_segment: map{id: str, type: str} # The `type` and `id` of the requested shield information barrier segment., restricted_segment: map{id: str, type: str} # The `type` and `id` of the restricted shield information barrier segment.} @optional {shield_information_barrier: map{id: str, type: str} # A base representation of a shield information barrier object.} @returns(201) Returns the newly created Shield Information Barrier Segment Restriction object. @errors {404: Returns a `not_found` error if the shield information barrier or segment was not found.} @endgroup @group device_pinners @endpoint GET /device_pinners/{device_pinner_id} @desc Get device pin @required {device_pinner_id: str # The ID of the device pin.} @returns(200) {id: str, type: str, owned_by: any, product_name: str} # Returns information about a single device pin. @endpoint DELETE /device_pinners/{device_pinner_id} @desc Remove device pin @required {device_pinner_id: str # The ID of the device pin.} @returns(204) Returns an empty response when the pin has been deleted. @endgroup @group enterprises @endpoint GET /enterprises/{enterprise_id}/device_pinners @desc List enterprise device pins @required {enterprise_id: str # The ID of the enterprise.} @optional {marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`., limit: int(int64) # The maximum number of items to return per page., direction: str(ASC/DESC) # The direction to sort results in. This can be either in alphabetical ascending (`ASC`) or descending (`DESC`) order.} @returns(200) {entries: [map], limit: int(int64), next_marker: int(int64), order: [map]} # Returns a list of device pins for a given enterprise. @endgroup @group terms_of_services @endpoint GET /terms_of_services @desc List terms of services @optional {tos_type: str(external/managed) # Limits the results to the terms of service of the given type.} @returns(200) {total_count: int(int64), entries: [map]} # Returns a collection of terms of service text and settings for the enterprise. @endpoint POST /terms_of_services @desc Create terms of service @required {status: str(enabled/disabled) # Whether this terms of service is active., text: str # The terms of service text to display to users. The text can be set to empty if the `status` is set to `disabled`.} @optional {tos_type: str(external/managed) # The type of user to set the terms of service for.} @returns(200) Returns a new task object. @endpoint GET /terms_of_services/{terms_of_service_id} @desc Get terms of service @required {terms_of_service_id: str # The ID of the terms of service.} @returns(200) Returns a terms of service object. @endpoint PUT /terms_of_services/{terms_of_service_id} @desc Update terms of service @required {terms_of_service_id: str # The ID of the terms of service., status: str(enabled/disabled) # Whether this terms of service is active., text: str # The terms of service text to display to users. The text can be set to empty if the `status` is set to `disabled`.} @returns(200) Returns an updated terms of service object. @endgroup @group terms_of_service_user_statuses @endpoint GET /terms_of_service_user_statuses @desc List terms of service user statuses @required {tos_id: str # The ID of the terms of service.} @optional {user_id: str # Limits results to the given user ID.} @returns(200) {total_count: int(int64), entries: [map]} # Returns a list of terms of service statuses. @endpoint POST /terms_of_service_user_statuses @desc Create terms of service status for new user @required {tos: map{type!: str, id!: str} # The terms of service to set the status for., user: map{type!: str, id!: str} # The user to set the status for., is_accepted: bool # Whether the user has accepted the terms.} @returns(201) {id: str, type: str, tos: any, user: any, is_accepted: bool, created_at: str(date-time), modified_at: str(date-time)} # Returns a terms of service status object. @endpoint PUT /terms_of_service_user_statuses/{terms_of_service_user_status_id} @desc Update terms of service status for existing user @required {terms_of_service_user_status_id: str # The ID of the terms of service status., is_accepted: bool # Whether the user has accepted the terms.} @returns(200) {id: str, type: str, tos: any, user: any, is_accepted: bool, created_at: str(date-time), modified_at: str(date-time)} # Returns the updated terms of service status object. @endgroup @group collaboration_whitelist_entries @endpoint GET /collaboration_whitelist_entries @desc List allowed collaboration domains @optional {marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`., limit: int(int64) # The maximum number of items to return per page.} @returns(200) Returns a collection of domains that are allowed for collaboration. @endpoint POST /collaboration_whitelist_entries @desc Add domain to list of allowed collaboration domains @required {domain: str # The domain to add to the list of allowed domains., direction: str(inbound/outbound/both) # The direction in which to allow collaborations.} @returns(200) {id: str, type: str, domain: str, direction: str, enterprise: any, created_at: str(date-time)} # Returns a new entry on the list of allowed domains. @endpoint GET /collaboration_whitelist_entries/{collaboration_whitelist_entry_id} @desc Get allowed collaboration domain @required {collaboration_whitelist_entry_id: str # The ID of the entry in the list.} @returns(200) {id: str, type: str, domain: str, direction: str, enterprise: any, created_at: str(date-time)} # Returns an entry on the list of allowed domains. @endpoint DELETE /collaboration_whitelist_entries/{collaboration_whitelist_entry_id} @desc Remove domain from list of allowed collaboration domains @required {collaboration_whitelist_entry_id: str # The ID of the entry in the list.} @returns(204) A blank response is returned if the entry was successfully deleted. @endgroup @group collaboration_whitelist_exempt_targets @endpoint GET /collaboration_whitelist_exempt_targets @desc List users exempt from collaboration domain restrictions @optional {marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`., limit: int(int64) # The maximum number of items to return per page.} @returns(200) Returns a collection of user exemptions. @endpoint POST /collaboration_whitelist_exempt_targets @desc Create user exemption from collaboration domain restrictions @required {user: map{id!: str} # The user to exempt.} @returns(200) {id: str, type: str, enterprise: any, user: any, created_at: str(date-time), modified_at: str(date-time)} # Returns a new exemption entry. @endpoint GET /collaboration_whitelist_exempt_targets/{collaboration_whitelist_exempt_target_id} @desc Get user exempt from collaboration domain restrictions @required {collaboration_whitelist_exempt_target_id: str # The ID of the exemption to the list.} @returns(200) {id: str, type: str, enterprise: any, user: any, created_at: str(date-time), modified_at: str(date-time)} # Returns the user's exempted from the list of collaboration domains. @endpoint DELETE /collaboration_whitelist_exempt_targets/{collaboration_whitelist_exempt_target_id} @desc Remove user from list of users exempt from domain restrictions @required {collaboration_whitelist_exempt_target_id: str # The ID of the exemption to the list.} @returns(204) A blank response is returned if the exemption was successfully deleted. @endgroup @group storage_policies @endpoint GET /storage_policies @desc List storage policies @optional {fields: [str] # A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested., marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`., limit: int(int64) # The maximum number of items to return per page.} @returns(200) Returns a collection of storage policies. @endpoint GET /storage_policies/{storage_policy_id} @desc Get storage policy @required {storage_policy_id: str # The ID of the storage policy.} @returns(200) Returns a storage policy object. @endgroup @group storage_policy_assignments @endpoint GET /storage_policy_assignments @desc List storage policy assignments @required {resolved_for_type: str(user/enterprise) # The target type to return assignments for., resolved_for_id: str # The ID of the user or enterprise to return assignments for.} @optional {marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`.} @returns(200) Returns a collection of storage policies for the enterprise or user. @endpoint POST /storage_policy_assignments @desc Assign storage policy @required {storage_policy: map{type!: str, id!: str} # The storage policy to assign to the user or enterprise., assigned_to: map{type!: str, id!: str} # The user or enterprise to assign the storage policy to.} @returns(200) {id: str, type: str, storage_policy: any, assigned_to: any} # Returns the new storage policy assignment created. @endpoint GET /storage_policy_assignments/{storage_policy_assignment_id} @desc Get storage policy assignment @required {storage_policy_assignment_id: str # The ID of the storage policy assignment.} @returns(200) {id: str, type: str, storage_policy: any, assigned_to: any} # Returns a storage policy assignment object. @endpoint PUT /storage_policy_assignments/{storage_policy_assignment_id} @desc Update storage policy assignment @required {storage_policy_assignment_id: str # The ID of the storage policy assignment., storage_policy: map{type!: str, id!: str} # The storage policy to assign to the user or enterprise.} @returns(200) {id: str, type: str, storage_policy: any, assigned_to: any} # Returns an updated storage policy assignment object. @endpoint DELETE /storage_policy_assignments/{storage_policy_assignment_id} @desc Unassign storage policy @required {storage_policy_assignment_id: str # The ID of the storage policy assignment.} @returns(204) Returns an empty response when the storage policy assignment is successfully deleted. @endgroup @group zip_downloads @endpoint POST /zip_downloads @desc Create zip download @required {items: [map{type!: str, id!: str}] # A list of items to add to the `zip` archive. These can be folders or files.} @optional {download_file_name: str # The optional name of the `zip` archive. This name will be appended by the `.zip` file extension, for example `January Financials.zip`.} @returns(202) {download_url: str, status_url: str, expires_at: str(date-time), name_conflicts: [[map]]} # If the `zip` archive is ready to be downloaded, the API will return a response that will include a `download_url`, a `status_url`, as well as any conflicts that might have occurred when creating the request. @errors {400: Returns an error if some of the parameters are missing or not valid. In most cases, this error might happen because the JSON request body is not valid JSON, any of the items has an incorrect or missing ID, any of the items is not a file or folder, or the root folder with ID `0` has been added to the list of folders to add to the archive. The following is a list of common error codes for this response. * `bad_request` - the request body is missing, invalid, or both the list of files and folders are empty. Additionally, it this error might be returned when attempting to add the root folder with ID `0` to an archive. * `zip_download_file_count_exceeded_limit` - the requested files and folders would result in an archive with more than 10,000 files. The request will have to be split into multiple requests to reduce the number of files per archive. * `zip_download_pre_compressed_bytes_exceeded_limit` - the requested files and folders would result in an archive with more than the allowed download limit. The request will have to be split into multiple requests to reduce the size of the archive., 401: Returned when the access token provided in the `Authorization` header is not recognized or not provided., 403: Returned when an authorization header is provided but the user does not have access to the items.} @endpoint GET /zip_downloads/{zip_download_id}/content @desc Download zip archive @required {zip_download_id: str # The unique identifier that represent this `zip` archive.} @returns(200) Returns the content of the items requested for this download, formatted as a stream of files and folders in a `zip` archive. @errors {404: Returns an error if the ID of this download request is not valid. This error can also be returned if this URL has been called before. To re-download this archive, please create a new request for a zip download., 429: Returns an error if the number of concurrent zip downloads has been reached for either the user or the enterprise. * `user_too_many_concurrent_downloads` - the maximum of 5 parallel downloads of zip archives per user has been met. * `enterprise_too_many_concurrent_downloads` - the maximum of 10 parallel downloads of zip archives per enterprise has been met.} @endpoint GET /zip_downloads/{zip_download_id}/status @desc Get zip download status @required {zip_download_id: str # The unique identifier that represent this `zip` archive.} @returns(200) {total_file_count: int, downloaded_file_count: int, skipped_file_count: int, skipped_folder_count: int, state: str} # Returns the status of the `zip` archive that is being downloaded. @errors {401: Returned when the access token provided in the `Authorization` header is not recognized or not provided., 403: Returned when an authorization header is provided but the user does not have access to the items., 404: Returns an error if the ID of this download request is not valid, or if the status of a download is requested before the download has been started.} @endgroup @group sign_requests @endpoint POST /sign_requests/{sign_request_id}/cancel @desc Cancel Box Sign request @required {sign_request_id: str # The ID of the signature request.} @optional {reason: str # An optional reason for cancelling the sign request.} @returns(200) Returns a Sign Request object. @errors {404: Returns an error when the sign request cannot be found or the user does not have access to the sign request.} @endpoint POST /sign_requests/{sign_request_id}/resend @desc Resend Box Sign request @required {sign_request_id: str # The ID of the signature request.} @returns(202) Returns an empty response when the API call was successful. The email notifications will be sent asynchronously. @errors {404: Returns an error when the signature request cannot be found or the user does not have access to the signature request.} @endpoint GET /sign_requests/{sign_request_id} @desc Get Box Sign request by ID @required {sign_request_id: str # The ID of the signature request.} @returns(200) Returns a signature request. @errors {404: Returns an error when the signature request cannot be found, the user does not have access to the signature request, or `sign_files` and/or `parent_folder` is deleted.} @endpoint GET /sign_requests @desc List Box Sign requests @optional {marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`., limit: int(int64) # The maximum number of items to return per page., senders: [str] # A list of sender emails to filter the signature requests by sender. If provided, `shared_requests` must be set to `true`., shared_requests: bool=false # If set to `true`, only includes requests that user is not an owner, but user is a collaborator. Collaborator access is determined by the user access level of the sign files of the request. Default is `false`. Must be set to `true` if `senders` are provided.} @returns(200) Returns a collection of sign requests. @endpoint POST /sign_requests @desc Create Box Sign request @returns(201) Returns a Box Sign request object. @endgroup @group workflows @endpoint GET /workflows @desc List workflows @required {folder_id: str # The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`.} @optional {trigger_type: str # Type of trigger to search for., limit: int(int64) # The maximum number of items to return per page., marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`.} @returns(200) Returns the workflow. @errors {400: Returned if the trigger type is not `WORKFLOW_MANUAL_START`., 404: Returned if the folder is not found, or the user does not have access to the folder.} @endpoint POST /workflows/{workflow_id}/start @desc Starts workflow based on request body @required {workflow_id: str # The ID of the workflow., flow: map{type: str, id: str} # The flow that will be triggered., files: [map{type: str, id: str}] # The array of files for which the workflow should start. All files must be in the workflow's configured folder., folder: map{type: str, id: str} # The folder object for which the workflow is configured.} @optional {type: str # The type of the parameters object., outcomes: [map{id!: str, collaborators: any, completion_rule: any, file_collaborator_role: any, task_collaborators: any, role: any}] # A configurable outcome the workflow should complete.} @returns(204) Starts the workflow. @errors {400: Returns an error if some of the parameters are missing or not valid. * `workflow_is_not_enabled` when the workflow is not enabled. * `workflow_not_active_on_provided_folder` when the workflow is not enabled for the specified folder id. * `parameters_provided_do_not_match_target_outcome` when the provided parameters do not match the expected parameters., 403: Returns an error if there are insufficient permissions. * `insufficient_access` when the user does not have access rights to file or folder. * `missing_relay_full_access` when the user does not have access to Relay Full., 404: Returns an error if the workflow could not be found, or the authenticated user does not have access to the workflow. * `workflow_not_found` when the workflow is not found. * `flow_missing_or_inaccessible` when the flow is not a manual start flow.} @endgroup @group sign_templates @endpoint GET /sign_templates @desc List Box Sign templates @optional {marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`., limit: int(int64) # The maximum number of items to return per page.} @returns(200) Returns a collection of templates. @errors {401: Returned when the access token provided in the `Authorization` header is not recognized or not provided.} @endpoint GET /sign_templates/{template_id} @desc Get Box Sign template by ID @required {template_id: str # The ID of a Box Sign template.} @returns(200) Returns details of a template. @errors {401: Returned when the access token provided in the `Authorization` header is not recognized or not provided., 404: Returned if the template is not found or the user does not have access to the associated template.} @endgroup @group integration_mappings @endpoint GET /integration_mappings/slack @desc List Slack integration mappings @optional {marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`., limit: int(int64) # The maximum number of items to return per page., partner_item_type: str # Mapped item type, for which the mapping should be returned., partner_item_id: str # ID of the mapped item, for which the mapping should be returned., box_item_id: str # Box item ID, for which the mappings should be returned., box_item_type: str # Box item type, for which the mappings should be returned., is_manually_created: bool # Whether the mapping has been manually created.} @returns(200) Returns a collection of integration mappings. @errors {400: The server cannot or will not process the request due to an apparent client error., 404: Returns a `not_found` error if the integration mapping could not be found.} @endpoint POST /integration_mappings/slack @desc Create Slack integration mapping @required {partner_item: any, box_item: any} @optional {options: any} @returns(201) Returns the created integration mapping. @errors {400: Returns a `bad_request` if an incorrect `options` was supplied or the Box folder cannot be mapped to this `partner_item_id`. Error codes: * `SERVICE_ACCOUNT_IS_NOT_A_COOWNER_OR_OWNER` - service account doesn't have co-owner collaboration or is not an owner of the `box_item_id`, * `CHANNEL_ALREADY_MAPPED` - channel is already mapped to another `box_item_id`, * `CHANNEL_NOT_FOUND` - channel was not found, * `CHANNEL_NOT_SUITABLE_FOR_CFS` - connect channel, not suitable for Box as Content layer for Slack, * `BOX_ENTERPRISE_MISMATCH` - Box folder must be owned by the enterprise, which is configured to use Box as Content layer for Slack, * `CFS_DISABLED` - Box as Content layer for Slack must be enabled for a provided Slack workspace or organization * `BOX_FOLDER_EXTERNALLY_OWNED` - Box folder must be internally owned to the admin's enterprise, * `JWT_APP_NOT_AUTHORIZED` - JWT authorization error., 404: Returns a `not_found` error if the integration mapping could not be found.} @endpoint PUT /integration_mappings/slack/{integration_mapping_id} @desc Update Slack integration mapping @required {integration_mapping_id: str # An ID of an integration mapping.} @optional {box_item: any, options: any} @returns(200) Returns the updated integration mapping object. @errors {400: Returns a `bad_request` if an incorrect `options` was supplied or the Box folder cannot be mapped to this `partner_item`. Error codes: * `SERVICE_ACCOUNT_IS_NOT_A_COOWNER_OR_OWNER` - service account doesn't have co-owner collaboration or is not an owner of the `box_item_id`, * `BOX_FOLDER_EXTERNALLY_OWNED` - Box folder must be internally owned to the admin's enterprise, * `JWT_APP_NOT_AUTHORIZED` - JWT authorization error., 404: Returns `not_found` if integration mapping object was not found.} @endpoint DELETE /integration_mappings/slack/{integration_mapping_id} @desc Delete Slack integration mapping @required {integration_mapping_id: str # An ID of an integration mapping.} @returns(204) Empty body in response. @errors {404: Returns a `not_found` error if the integration mapping could not be found.} @endpoint GET /integration_mappings/teams @desc List Teams integration mappings @optional {partner_item_type: str(channel/team) # Mapped item type, for which the mapping should be returned., partner_item_id: str # ID of the mapped item, for which the mapping should be returned., box_item_id: str # Box item ID, for which the mappings should be returned., box_item_type: str # Box item type, for which the mappings should be returned.} @returns(200) Returns a collection of integration mappings. @errors {400: The server cannot or will not process the request due to an apparent client error., 404: Returns a `not_found` error if the integration mapping could not be found.} @endpoint POST /integration_mappings/teams @desc Create Teams integration mapping @required {partner_item: any, box_item: any} @returns(201) Returns the created integration mapping. @errors {400: Returns a `bad_request` if an incorrect `options` was supplied or the Box folder cannot be mapped to this `partner_item_id`. Error codes: * `SERVICE_ACCOUNT_IS_NOT_A_COOWNER_OR_OWNER` - service account doesn't have co-owner collaboration or is not an owner of the `box_item_id`, * `CHANNEL_ALREADY_MAPPED` - channel is already mapped to another `box_item_id`, * `TEAM_ALREADY_MAPPED` - team is already mapped to another `box_item_id`, * `BOX_ENTERPRISE_MISMATCH` - Box folder must be owned by the enterprise, which is configured to use Box as Content layer for Teams, * `BOX_FOLDER_EXTERNALLY_OWNED` - Box folder must be internally owned to the admin's enterprise * `FOLDER_ALREADY_MAPPED` - Box folder must not be mapped to another integration mapping., 404: Returns a `not_found` error if the integration mapping, record or folder could not be found.} @endpoint PUT /integration_mappings/teams/{integration_mapping_id} @desc Update Teams integration mapping @required {integration_mapping_id: str # An ID of an integration mapping.} @optional {box_item: any} @returns(200) Returns the updated integration mapping object. @errors {400: Returns a `bad_request` if an incorrect `options` was supplied or the Box folder cannot be mapped to this `partner_item`. Error codes: * `SERVICE_ACCOUNT_IS_NOT_A_COOWNER_OR_OWNER` - service account doesn't have co-owner collaboration or is not an owner of the `box_item_id`, * `BOX_FOLDER_EXTERNALLY_OWNED` - Box folder must be internally owned to the admin's enterprise, * `FOLDER_ALREADY_MAPPED` - Box folder must not be mapped to another integration mapping., 404: Returns `not_found` if integration mapping object was not found.} @endpoint DELETE /integration_mappings/teams/{integration_mapping_id} @desc Delete Teams integration mapping @required {integration_mapping_id: str # An ID of an integration mapping.} @returns(204) Empty body in response. @errors {404: Returns a `not_found` error if the integration mapping could not be found.} @endgroup @group ai @endpoint POST /ai/ask @desc Ask question @required {mode: str(multiple_item_qa/single_item_qa) # Box AI handles text documents with text representations up to 1MB in size, or a maximum of 25 files, whichever comes first. If the text file size exceeds 1MB, the first 1MB of text representation will be processed. Box AI handles image documents with a resolution of 1024 x 1024 pixels, with a maximum of 5 images or 5 pages for multi-page images. If the number of image or image pages exceeds 5, the first 5 images or pages will be processed. If you set mode parameter to `single_item_qa`, the items array can have one element only. Currently Box AI does not support multi-modal requests. If both images and text are sent Box AI will only process the text., prompt: str # The prompt provided by the client to be answered by the LLM. The prompt's length is limited to 10000 characters., items: [map{id!: str, type!: str, content: str}] # The items to be processed by the LLM, often files.} @optional {dialogue_history: [map{prompt: str, answer: str, created_at: str(date-time)}] # The history of prompts and answers previously passed to the LLM. This provides additional context to the LLM in generating the response., include_citations: bool # A flag to indicate whether citations should be returned., ai_agent: any} @returns(200) A successful response including the answer from the LLM. @returns(204) No content is available to answer the question. This is returned when the request item is a hub, but content in the hubs is not indexed. To ensure content in the hub is indexed, make sure Box AI for Hubs in the Admin Console was enabled before hub creation. @errors {500: An unexpected server error.} @endpoint POST /ai/text_gen @desc Generate text @required {prompt: str # The prompt provided by the client to be answered by the LLM. The prompt's length is limited to 10000 characters., items: [map{id!: str, type!: str, content: str}] # The items to be processed by the LLM, often files. The array can include **exactly one** element. **Note**: Box AI handles documents with text representations up to 1MB in size. If the file size exceeds 1MB, the first 1MB of text representation will be processed.} @optional {dialogue_history: [map{prompt: str, answer: str, created_at: str(date-time)}] # The history of prompts and answers previously passed to the LLM. This parameter provides the additional context to the LLM when generating the response., ai_agent: any} @returns(200) {answer: str, created_at: str(date-time), completion_reason: str, ai_agent_info: map{models: [map], processor: str}} # A successful response including the answer from the LLM. @errors {500: An unexpected server error.} @endgroup @group ai_agent_default @endpoint GET /ai_agent_default @desc Get AI agent default configuration @required {mode: str(ask/text_gen/extract/extract_structured) # The mode to filter the agent config to return.} @optional {language: str # The ISO language code to return the agent config for. If the language is not supported the default agent config is returned., model: str # The model to return the default agent config for.} @returns(200) A successful response including the default agent configuration. This response can be one of the following four objects: * AI agent for questions * AI agent for text generation * AI agent for freeform metadata extraction * AI agent for structured metadata extraction. The response depends on the agent configuration requested in this endpoint. @errors {500: An unexpected server error.} @endgroup @group ai @endpoint POST /ai/extract @desc Extract metadata (freeform) @required {prompt: str # The prompt provided to a Large Language Model (LLM) in the request. The prompt can be up to 10000 characters long and it can be an XML or a JSON schema., items: [map{id!: str, type!: str, content: str}] # The items that LLM will process. Currently, you can use files only.} @optional {ai_agent: any} @returns(200) {answer: str, created_at: str(date-time), completion_reason: str, ai_agent_info: map{models: [map], processor: str}} # A response including the answer from the LLM. @errors {500: An unexpected server error.} @endpoint POST /ai/extract_structured @desc Extract metadata (structured) @required {items: [map{id!: str, type!: str, content: str}] # The items to be processed by the LLM. Currently you can use files only.} @optional {metadata_template: map{template_key: str, type: str, scope: str} # The metadata template containing the fields to extract. For your request to work, you must provide either `metadata_template` or `fields`, but not both., fields: [map{key!: str, description: str, displayName: str, prompt: str, type: str, options: [map]}] # The fields to be extracted from the provided items. For your request to work, you must provide either `metadata_template` or `fields`, but not both., include_confidence_score: bool # A flag to indicate whether confidence scores for every extracted field should be returned., include_reference: bool # A flag to indicate whether references for every extracted field should be returned., ai_agent: any} @returns(200) {answer: map, created_at: str(date-time), completion_reason: str, confidence_score: map, reference: map, ai_agent_info: map{models: [map], processor: str}} # A successful response including the answer from the LLM. @errors {500: An unexpected server error.} @endgroup @group ai_agents @endpoint GET /ai_agents @desc List AI agents @optional {mode: [str] # The mode to filter the agent config to return. Possible values are: `ask`, `text_gen`, and `extract`., fields: [str] # The fields to return in the response., agent_state: [str] # The state of the agents to return. Possible values are: `enabled`, `disabled` and `enabled_for_selected_users`., include_box_default: bool=false # Whether to include the Box default agents in the response., marker: str # Defines the position marker at which to begin returning results., limit: int(int64) # The maximum number of items to return per page.} @returns(200) A successful response including the agents list. @errors {400: An unexpected client error., 500: An unexpected server error.} @endpoint POST /ai_agents @desc Create AI agent @required {type: str # The type of agent used to handle queries., name: str # The name of the AI Agent., access_state: str # The state of the AI Agent. Possible values are: `enabled`, `disabled`, and `enabled_for_selected_users`.} @optional {icon_reference: str # The icon reference of the AI Agent. It should have format of the URL `https://cdn01.boxcdn.net/app-assets/aistudio/avatars/` where possible values of `file_name` are: `logo_boxAi.png`,`logo_stamp.png`,`logo_legal.png`,`logo_finance.png`,`logo_config.png`,`logo_handshake.png`,`logo_analytics.png`,`logo_classification.png`., allowed_entities: [map] # List of allowed users or groups., ask: map{type!: str, access_state!: str, description!: str, custom_instructions: str, suggested_questions: [str], long_text: map, basic_text: map, basic_image: map, spreadsheet: map, long_text_multi: map, basic_text_multi: map, basic_image_multi: map} # The AI agent to be used to handle queries., text_gen: map{type!: str, access_state!: str, description!: str, custom_instructions: str, suggested_questions: [str], basic_gen: map} # The AI agent to be used to generate text., extract: map{type!: str, access_state!: str, description!: str, custom_instructions: str, long_text: map, basic_text: map, basic_image: map} # The AI agent to be used for metadata extraction.} @returns(200) Definition of created AI agent. @errors {400: An unexpected client error., 500: An unexpected server error.} @endpoint PUT /ai_agents/{agent_id} @desc Update AI agent @required {agent_id: str # The ID of the agent to update., type: str # The type of agent used to handle queries., name: str # The name of the AI Agent., access_state: str # The state of the AI Agent. Possible values are: `enabled`, `disabled`, and `enabled_for_selected_users`.} @optional {icon_reference: str # The icon reference of the AI Agent. It should have format of the URL `https://cdn01.boxcdn.net/app-assets/aistudio/avatars/` where possible values of `file_name` are: `logo_boxAi.png`,`logo_stamp.png`,`logo_legal.png`,`logo_finance.png`,`logo_config.png`,`logo_handshake.png`,`logo_analytics.png`,`logo_classification.png`., allowed_entities: [map] # List of allowed users or groups., ask: map{type!: str, access_state!: str, description!: str, custom_instructions: str, suggested_questions: [str], long_text: map, basic_text: map, basic_image: map, spreadsheet: map, long_text_multi: map, basic_text_multi: map, basic_image_multi: map} # The AI agent to be used to handle queries., text_gen: map{type!: str, access_state!: str, description!: str, custom_instructions: str, suggested_questions: [str], basic_gen: map} # The AI agent to be used to generate text., extract: map{type!: str, access_state!: str, description!: str, custom_instructions: str, long_text: map, basic_text: map, basic_image: map} # The AI agent to be used for metadata extraction.} @returns(200) Definition of created AI agent. @errors {400: An unexpected client error., 500: An unexpected server error.} @endpoint GET /ai_agents/{agent_id} @desc Get AI agent by agent ID @required {agent_id: str # The agent id to get.} @optional {fields: [str] # The fields to return in the response.} @returns(200) A successful response including the agent. @errors {400: An unexpected client error., 500: An unexpected server error.} @endpoint DELETE /ai_agents/{agent_id} @desc Delete AI agent @required {agent_id: str # The ID of the agent to delete.} @returns(204) A successful response with no content. @errors {400: An unexpected client error., 404: Returned if the AI agent is not found., 500: An unexpected server error.} @endgroup @group metadata_taxonomies @endpoint POST /metadata_taxonomies @desc Create metadata taxonomy @required {displayName: str # The display name of the taxonomy., namespace: str # The namespace of the metadata taxonomy to create.} @optional {key: str # The taxonomy key. If it is not provided in the request body, it will be generated from the `displayName`. The `displayName` would be converted to lower case, and all spaces and non-alphanumeric characters replaced with underscores.} @returns(201) {id: str, key: str, displayName: str, namespace: str, levels: [map]} # The schema representing the metadata taxonomy created. @errors {400: Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. In many cases this response will include extra details on what fields are missing., 403: Returned when the user does not have the permission to create the metadata taxonomy. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace.} @endpoint GET /metadata_taxonomies/{namespace} @desc Get metadata taxonomies for namespace @required {namespace: str # The namespace of the metadata taxonomy.} @optional {marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`., limit: int(int64) # The maximum number of items to return per page.} @returns(200) Returns all of the metadata taxonomies within a namespace and their corresponding schema. @errors {400: Returned when the request parameters are not valid.} @endpoint GET /metadata_taxonomies/{namespace}/{taxonomy_key} @desc Get metadata taxonomy by taxonomy key @required {namespace: str # The namespace of the metadata taxonomy., taxonomy_key: str # The key of the metadata taxonomy.} @returns(200) {id: str, key: str, displayName: str, namespace: str, levels: [map]} # Returns the metadata taxonomy identified by the taxonomy key. @errors {400: Returned when the request parameters are not valid., 404: Returned when a taxonomy with the given `namespace` and `taxonomy_key` cannot be found.} @endpoint PATCH /metadata_taxonomies/{namespace}/{taxonomy_key} @desc Update metadata taxonomy @required {namespace: str # The namespace of the metadata taxonomy., taxonomy_key: str # The key of the metadata taxonomy., displayName: str # The display name of the taxonomy.} @returns(200) {id: str, key: str, displayName: str, namespace: str, levels: [map]} # The schema representing the updated metadata taxonomy. @errors {400: Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. In many cases this response will include extra details on what fields are missing., 403: Returned when the user does not have the permission to modify the metadata taxonomy. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace.} @endpoint DELETE /metadata_taxonomies/{namespace}/{taxonomy_key} @desc Remove metadata taxonomy @required {namespace: str # The namespace of the metadata taxonomy., taxonomy_key: str # The key of the metadata taxonomy.} @returns(204) Returns an empty response when the metadata taxonomy is successfully deleted. @errors {400: Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. In many cases this response will include extra details on what fields are missing., 403: Returned when the user does not have the permission to delete the metadata taxonomy. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace., 404: Returned if the metadata taxonomy does not exist.} @endpoint POST /metadata_taxonomies/{namespace}/{taxonomy_key}/levels @desc Create metadata taxonomy levels @required {namespace: str # The namespace of the metadata taxonomy., taxonomy_key: str # The key of the metadata taxonomy.} @returns(201) Returns an array of all taxonomy levels. @errors {400: Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. In many cases this response will include extra details on what fields are missing., 403: Returned when the user does not have the permission to modify the metadata taxonomy. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace.} @endpoint PATCH /metadata_taxonomies/{namespace}/{taxonomy_key}/levels/{level_index} @desc Update metadata taxonomy level @required {namespace: str # The namespace of the metadata taxonomy., taxonomy_key: str # The key of the metadata taxonomy., level_index: int # The index of the metadata taxonomy level., displayName: str # The display name of the taxonomy level.} @optional {description: str # The description of the taxonomy level.} @returns(200) {displayName: str, description: str, level: int(int32)} # The updated taxonomy level. @errors {400: Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. In many cases this response will include extra details on what fields are missing., 403: Returned when the user does not have the permission to modify the metadata taxonomy. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace.} @endpoint POST /metadata_taxonomies/{namespace}/{taxonomy_key}/levels:append @desc Add metadata taxonomy level @required {namespace: str # The namespace of the metadata taxonomy., taxonomy_key: str # The key of the metadata taxonomy., displayName: str # The display name of the taxonomy level.} @optional {description: str # The description of the taxonomy level.} @returns(201) Returns an array of all taxonomy levels. @errors {400: Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. In many cases this response will include extra details on what fields are missing., 403: Returned when the user does not have the permission to modify the metadata taxonomy. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace.} @endpoint POST /metadata_taxonomies/{namespace}/{taxonomy_key}/levels:trim @desc Delete metadata taxonomy level @required {namespace: str # The namespace of the metadata taxonomy., taxonomy_key: str # The key of the metadata taxonomy.} @returns(200) Returns an array of all taxonomy levels. @errors {400: Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. In many cases this response will include extra details on what fields are missing., 403: Returned when the user does not have the permission to modify the metadata taxonomy. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace.} @endpoint GET /metadata_taxonomies/{namespace}/{taxonomy_key}/nodes @desc List metadata taxonomy nodes @required {namespace: str # The namespace of the metadata taxonomy., taxonomy_key: str # The key of the metadata taxonomy.} @optional {level: [int] # Filters results by taxonomy level. Multiple values can be provided. Results include nodes that match any of the specified values., parent: [str] # Node identifier of a direct parent node. Multiple values can be provided. Results include nodes that match any of the specified values., ancestor: [str] # Node identifier of any ancestor node. Multiple values can be provided. Results include nodes that match any of the specified values., query: str # Query text to search for the taxonomy nodes., include-total-result-count: bool # When set to `true` this provides the total number of nodes that matched the query. The response will compute counts of up to 10,000 elements. Defaults to `false`., marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`., limit: int(int64) # The maximum number of items to return per page.} @returns(200) Returns a list of the taxonomy nodes that match the specified parameters. @errors {400: Returned when the request parameters are not valid.} @endpoint POST /metadata_taxonomies/{namespace}/{taxonomy_key}/nodes @desc Create metadata taxonomy node @required {namespace: str # The namespace of the metadata taxonomy., taxonomy_key: str # The key of the metadata taxonomy., displayName: str # The display name of the taxonomy node., level: int # The level of the taxonomy node.} @optional {parentId: str # The identifier of the parent taxonomy node. Omit this field for root-level nodes.} @returns(201) {id: str, displayName: str, level: int, parentId: str, nodePath: [str], ancestors: [map]} # The schema representing the taxonomy node created. @errors {400: Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. In many cases this response will include extra details on what fields are missing., 403: Returned when the user does not have the permission to modify the metadata taxonomy. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace.} @endpoint GET /metadata_taxonomies/{namespace}/{taxonomy_key}/nodes/{node_id} @desc Get metadata taxonomy node by ID @required {namespace: str # The namespace of the metadata taxonomy., taxonomy_key: str # The key of the metadata taxonomy., node_id: str # The identifier of the metadata taxonomy node.} @returns(200) {id: str, displayName: str, level: int, parentId: str, nodePath: [str], ancestors: [map]} # Returns the metadata taxonomy node that matches the identifier. @errors {400: Returned if any of the request parameters are not valid., 404: Returned if the taxonomy node with the given `node_id` cannot be found.} @endpoint PATCH /metadata_taxonomies/{namespace}/{taxonomy_key}/nodes/{node_id} @desc Update metadata taxonomy node @required {namespace: str # The namespace of the metadata taxonomy., taxonomy_key: str # The key of the metadata taxonomy., node_id: str # The identifier of the metadata taxonomy node.} @optional {displayName: str # The display name of the taxonomy node.} @returns(200) {id: str, displayName: str, level: int, parentId: str, nodePath: [str], ancestors: [map]} # The schema representing the updated taxonomy node. @errors {400: Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. In many cases this response will include extra details on what fields are missing., 403: Returned when the user does not have the permission to modify the metadata taxonomy. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace.} @endpoint DELETE /metadata_taxonomies/{namespace}/{taxonomy_key}/nodes/{node_id} @desc Remove metadata taxonomy node @required {namespace: str # The namespace of the metadata taxonomy., taxonomy_key: str # The key of the metadata taxonomy., node_id: str # The identifier of the metadata taxonomy node.} @returns(204) Returns an empty response when the metadata taxonomy node is successfully deleted. @errors {400: Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. In many cases this response will include extra details on what fields are missing., 403: Returned when the user does not have the permission to delete the metadata taxonomy node. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace., 404: Returned if the metadata taxonomy node does not exist.} @endgroup @group metadata_templates @endpoint GET /metadata_templates/{namespace}/{template_key}/fields/{field_key}/options @desc List metadata template's options for taxonomy field @required {namespace: str # The namespace of the metadata taxonomy., template_key: str # The name of the metadata template., field_key: str # The key of the metadata taxonomy field in the template.} @optional {level: [int] # Filters results by taxonomy level. Multiple values can be provided. Results include nodes that match any of the specified values., parent: [str] # Node identifier of a direct parent node. Multiple values can be provided. Results include nodes that match any of the specified values., ancestor: [str] # Node identifier of any ancestor node. Multiple values can be provided. Results include nodes that match any of the specified values., query: str # Query text to search for the taxonomy nodes., include-total-result-count: bool # When set to `true` this provides the total number of nodes that matched the query. The response will compute counts of up to 10,000 elements. Defaults to `false`., only-selectable-options: bool # When set to `true`, this only returns valid selectable options for this template taxonomy field. Otherwise, it returns all taxonomy nodes, whether or not they are selectable. Defaults to `true`., marker: str # Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`., limit: int(int64) # The maximum number of items to return per page.} @returns(200) Returns a list of the taxonomy nodes that match the specified parameters. @errors {400: Returned when the request parameters are not valid.} @endgroup @end