{ "openapi": "3.0.2", "info": { "title": "Box Platform API", "description": "[Box Platform](https://box.dev) provides functionality to provide access to content stored within [Box](https://box.com). It provides endpoints for basic manipulation of files and folders, management of users within an enterprise, as well as more complex topics such as legal holds and retention policies.", "termsOfService": "https://cloud.app.box.com/s/rmwxu64h1ipr41u49w3bbuvbsa29wku9", "contact": { "name": "Box, Inc", "url": "https://box.dev", "email": "devrel@box.com" }, "license": { "name": "Apache-2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0" }, "version": "2.0.0" }, "servers": [ { "url": "https://api.box.com/2.0", "description": "Box Platform API server" } ], "paths": { "/authorize": { "get": { "operationId": "get_authorize", "summary": "Authorize user", "description": "Authorize a user by sending them through the [Box](https://box.com)\nwebsite and request their permission to act on their behalf.\n\nThis is the first step when authenticating a user using\nOAuth 2.0. To request a user's authorization to use the Box APIs\non their behalf you will need to send a user to the URL with this\nformat.", "tags": [ "Authorization" ], "x-box-tag": "authorization", "security": [], "servers": [ { "url": "https://account.box.com/api/oauth2", "description": "Server for client-side authentication" } ], "parameters": [ { "name": "response_type", "description": "The type of response we'd like to receive.", "in": "query", "example": "code", "required": true, "schema": { "type": "string", "format": "token", "enum": [ "code" ] } }, { "name": "client_id", "description": "The Client ID of the application that is requesting to authenticate\nthe user. To get the Client ID for your application, log in to your\nBox developer console and click the **Edit Application** link for\nthe application you're working with. In the OAuth 2.0 Parameters section\nof the configuration page, find the item labelled `client_id`. The\ntext of that item is your application's Client ID.", "in": "query", "example": "ly1nj6n11vionaie65emwzk575hnnmrk", "required": true, "schema": { "type": "string" } }, { "name": "redirect_uri", "description": "The URI to which Box redirects the browser after the user has granted\nor denied the application permission. This URI match one of the redirect\nURIs in the configuration of your application. It must be a\nvalid HTTPS URI and it needs to be able to handle the redirection to\ncomplete the next step in the OAuth 2.0 flow.\nAlthough this parameter is optional, it must be a part of the\nauthorization URL if you configured multiple redirect URIs\nfor the application in the developer console. A missing parameter causes\na `redirect_uri_missing` error after the user grants application access.", "in": "query", "example": "http://example.com/auth/callback", "required": false, "schema": { "type": "string", "format": "url" } }, { "name": "state", "description": "A custom string of your choice. Box will pass the same string to\nthe redirect URL when authentication is complete. This parameter\ncan be used to identify a user on redirect, as well as protect\nagainst hijacked sessions and other exploits.", "in": "query", "example": "my_state", "required": false, "schema": { "type": "string" } }, { "name": "scope", "description": "A comma-separated list of application scopes you'd like to\nauthenticate the user for. This defaults to all the scopes configured\nfor the application in its configuration page.", "in": "query", "example": "admin_readwrite", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Does not return any data, but rather should be used in the browser.", "content": { "text/html": { "schema": { "type": "string", "format": "html" } } } }, "default": { "description": "Does not return any data, but rather should be used in the browser.", "content": { "text/html": { "schema": { "type": "string", "format": "html" } } } } } } }, "/oauth2/token": { "post": { "operationId": "post_oauth2_token", "summary": "Request access token", "description": "Request an Access Token using either a client-side obtained OAuth 2.0\nauthorization code or a server-side JWT assertion.\n\nAn Access Token is a string that enables Box to verify that a\nrequest belongs to an authorized session. In the normal order of\noperations you will begin by requesting authentication from the\n[authorize](#get-authorize) endpoint and Box will send you an\nauthorization code.\n\nYou will then send this code to this endpoint to exchange it for\nan Access Token. The returned Access Token can then be used to to make\nBox API calls.", "tags": [ "Authorization" ], "servers": [ { "url": "https://api.box.com", "description": "Server for server-side authentication" } ], "x-box-tag": "authorization", "security": [], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PostOAuth2Token" } } } }, "responses": { "200": { "description": "Returns a new Access Token that can be used to make authenticated\nAPI calls by passing along the token in a authorization header as\nfollows `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessToken" } } } }, "400": { "description": "An authentication error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2Error" } } } }, "default": { "description": "An authentication error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2Error" } } } } } } }, "/oauth2/token#refresh": { "post": { "operationId": "post_oauth2_token#refresh", "summary": "Refresh access token", "description": "Refresh an Access Token using its client ID, secret, and refresh token.", "tags": [ "Authorization" ], "servers": [ { "url": "https://api.box.com", "description": "Server for server-side authentication" } ], "x-box-tag": "authorization", "x-box-is-variation": true, "security": [], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PostOAuth2Token--RefreshAccessToken" } } } }, "responses": { "200": { "description": "Returns a new Access Token that can be used to make authenticated\nAPI calls by passing along the token in a authorization header as\nfollows `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessToken" } } } }, "400": { "description": "An authentication error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2Error" } } } }, "default": { "description": "An authentication error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2Error" } } } } } } }, "/oauth2/revoke": { "post": { "operationId": "post_oauth2_revoke", "summary": "Revoke access token", "description": "Revoke an active Access Token, effectively logging a user out\nthat has been previously authenticated.", "tags": [ "Authorization" ], "servers": [ { "url": "https://api.box.com", "description": "Server for server-side authentication" } ], "x-box-tag": "authorization", "security": [], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PostOAuth2Revoke" } } } }, "responses": { "200": { "description": "Returns an empty response when the token was successfully revoked." }, "400": { "description": "An authentication error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2Error" } } } }, "default": { "description": "An authentication error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2Error" } } } } } } }, "/files/{file_id}": { "get": { "operationId": "get_files_id", "summary": "Get file information", "tags": [ "Files" ], "x-box-tag": "files", "x-box-enable-explorer": true, "description": "Retrieves the details about a file.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.\n\nAdditionally this field can be used to query any metadata\napplied to the file by specifying the `metadata` field as well\nas the scope and key of the template to retrieve, for example\n`?field=metadata.enterprise_12345.contractTemplate`.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "if-none-match", "description": "Ensures an item is only returned if it has changed.\n\nPass in the item's last observed `etag` value\ninto this header and the endpoint will fail\nwith a `304 Not Modified` if the item has not\nchanged since.", "in": "header", "required": false, "example": "1", "schema": { "type": "string" } }, { "name": "boxapi", "description": "The URL, and optional password, for the shared link of this item.\n\nThis header can be used to access items that have not been\nexplicitly shared with a user.\n\nUse the format `shared_link=[link]` or if a password is required then\nuse `shared_link=[link]&shared_link_password=[password]`.\n\nThis header can be used on the file or folder shared, as well as on any files\nor folders nested within the item.", "example": "shared_link=[link]&shared_link_password=[password]", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "x-rep-hints", "description": "A header required to request specific `representations`\nof a file. Use this in combination with the `fields` query\nparameter to request a specific file representation.\n\nThe general format for these representations is\n`X-Rep-Hints: [...]` where `[...]` is one or many\nhints in the format `[fileType?query]`.\n\nFor example, to request a `png` representation in `32x32`\nas well as `64x64` pixel dimensions provide the following\nhints.\n\n`x-rep-hints: [jpg?dimensions=32x32][jpg?dimensions=64x64]`\n\nAdditionally, a `text` representation is available for all\ndocument file types in Box using the `[extracted_text]`\nrepresentation.\n\n`x-rep-hints: [extracted_text]`", "example": "[pdf]", "in": "header", "required": false, "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Returns a file object.\n\nNot all available fields are returned by default. Use the\n[fields](#param-fields) query parameter to explicitly request\nany specific fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File--Full" } } } }, "304": { "description": "Returns an empty response when the `If-None-Match` header matches\nthe current `etag` value of the folder. This indicates that the folder\nhas not changed since it was last requested." }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file is not found, or the user does not\nhave access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `file_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "415": { "description": "Returns an error if an action is performed on a file with an\nincorrect media type.\n\n* `unsupported_media_type` when requesting an `expiring_embed_link`\n for a file that is not supported by Box Embed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_files_id", "summary": "Restore file", "tags": [ "Trashed files" ], "x-box-tag": "trashed_files", "description": "Restores a file that has been moved to the trash.\n\nAn optional new parent ID can be provided to restore the file to in case the\noriginal folder has been deleted.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "An optional new name for the file.", "example": "Restored.docx", "type": "string" }, "parent": { "allOf": [ { "type": "object", "description": "The parent for this item", "properties": { "id": { "type": "string", "description": "The ID of parent item", "example": "123" } } }, { "description": "Specifies an optional ID of a folder to restore the file to\nwhen the original folder no longer exists.\n\nPlease be aware that this ID will only be used if the original\nfolder no longer exists. Use this ID to provide a fallback\nlocation to restore the file to if the original location\nhas been deleted." } ] } } } } } }, "responses": { "201": { "description": "Returns a file object when the file has been restored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrashFileRestored" } } } }, "403": { "description": "Returns an error if the user does not have access to the folder\nthe file is being restored to, or the user does not have permission\nto restore files from the trash.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the file is not in the trash.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error if there is an file with the same name\nin the folder the file is being restored to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "put": { "operationId": "put_files_id", "summary": "Update file", "tags": [ "Files" ], "x-box-tag": "files", "x-box-enable-explorer": true, "x-box-sanitized": true, "description": "Updates a file. This can be used to rename or move a file,\ncreate a shared link, or lock a file.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "if-match", "description": "Ensures this item hasn't recently changed before\nmaking changes.\n\nPass in the item's last observed `etag` value\ninto this header and the endpoint will fail\nwith a `412 Precondition Failed` if it\nhas changed since.", "in": "header", "required": false, "example": "1", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "An optional different name for the file. This can be used to\nrename the file.", "example": "NewFile.txt" }, "description": { "type": "string", "description": "The description for a file. This can be seen in the right-hand sidebar panel\nwhen viewing a file in the Box web app. Additionally, this index is used in\nthe search index of the file, allowing users to find the file by the content\nin the description.", "maxLength": 256, "example": "The latest reports. Automatically updated" }, "parent": { "allOf": [ { "type": "object", "description": "The parent for this item", "properties": { "id": { "type": "string", "description": "The ID of parent item", "example": "123" } } }, { "description": "An optional new parent folder for the file. This can be used\nto move the file to a new folder." } ] }, "shared_link": { "allOf": [ { "description": "Defines a shared link for an item. Set this to `null` to remove\nthe shared link.", "type": "object", "properties": { "access": { "type": "string", "description": "The level of access for the shared link. This can be\nrestricted to anyone with the link (`open`), only people\nwithin the company (`company`) and only those who\nhave been invited to the folder (`collaborators`).\n\nIf not set, this field defaults to the access level specified\nby the enterprise admin. To create a shared link with this\ndefault setting pass the `shared_link` object with\nno `access` field, for example `{ \"shared_link\": {} }`.\n\nThe `company` access level is only available to paid\naccounts.", "enum": [ "open", "company", "collaborators" ], "example": "open" }, "password": { "type": "string", "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\n\nA password can only be set when `access` is set to `open`.", "example": "do-not-use-this-password" }, "vanity_name": { "type": "string", "description": "Defines a custom vanity name to use in the shared link URL,\nfor example `https://app.box.com/v/my-shared-link`.\n\nCustom URLs should not be used when sharing sensitive content\nas vanity URLs are a lot easier to guess than regular shared links.", "example": "my-shared-link" }, "unshared_at": { "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "description": "The timestamp at which this shared link will\nexpire. This field can only be set by\nusers with paid accounts." }, "permissions": { "type": "object", "properties": { "can_download": { "type": "boolean", "example": true, "description": "If the shared link allows for downloading of files.\nThis can only be set when `access` is set to\n`open` or `company`." } } } } }, { "description": "Defines a shared link for a file. Set this to `null` to remove\nthe shared link." } ] }, "lock": { "type": "object", "description": "Defines a lock on an item. This prevents the item from being\nmoved, renamed, or otherwise changed by anyone other than the user\nwho created the lock.\n\nSet this to `null` to remove the lock.", "required": [ "type" ], "properties": { "access": { "type": "string", "description": "The type of this object.", "enum": [ "lock" ], "example": "lock" }, "expires_at": { "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "description": "Defines the time at which the lock expires." }, "is_download_prevented": { "type": "boolean", "example": true, "description": "Defines if the file can be downloaded while it is locked." } } }, "disposition_at": { "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "description": "The retention expiration timestamp for the given file. This\ndate cannot be shortened once set on a file." }, "permissions": { "description": "Defines who can download a file.", "type": "object", "properties": { "can_download": { "description": "Defines who is allowed to download this file. The possible\nvalues are either `open` for everyone or `company` for\nthe other members of the user's enterprise.\n\nThis setting overrides the download permissions that are\nnormally part of the `role` of a collaboration. When set to\n`company`, this essentially removes the download option for\nexternal users with `viewer` or `editor` a roles.", "type": "string", "example": "open", "enum": [ "open", "company" ] } } }, "tags": { "type": "array", "example": [ "approved" ], "items": { "type": "string" }, "minItems": 1, "maxItems": 100, "description": "The tags for this item. These tags are shown in\nthe Box web app and mobile apps next to an item.\n\nTo add or remove a tag, retrieve the item's current tags,\nmodify them, and then update this field.\n\nThere is a limit of 100 tags per item, and 10,000\nunique tags per enterprise." } } } } } }, "responses": { "200": { "description": "Returns a file object.\n\nNot all available fields are returned by default. Use the\n[fields](#param-fields) query parameter to explicitly request\nany specific fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File--Full" } } } }, "400": { "description": "Returned when the new retention time > maximum retention length.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned if the user does not have all the permissions to complete the\nupdate.\n\n* `access_denied_insufficient_permissions` returned\nwhen the authenticated user does not have access\nto the destination folder to move the file to.\n* Returned when retention time is shorter or equal to current retention\ntimestamp.\n* Returned when a `file_id` that is not under retention is entered.\n* Returned when a file that is retained but the disposition action is set\nto `remove_retention`\n* `forbidden_by_policy` is returned if copying a folder is\nforbidden due to information barrier restrictions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file is not found, or the user does not\nhave access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `file_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the file. This indicates that the file\nhas changed since it was last requested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_files_id", "summary": "Delete file", "tags": [ "Files" ], "x-box-tag": "files", "x-box-sanitized": true, "description": "Deletes a file, either permanently or by moving it to\nthe trash.\n\nThe the enterprise settings determine whether the item will\nbe permanently deleted from Box or moved to the trash.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "if-match", "description": "Ensures this item hasn't recently changed before\nmaking changes.\n\nPass in the item's last observed `etag` value\ninto this header and the endpoint will fail\nwith a `412 Precondition Failed` if it\nhas changed since.", "in": "header", "required": false, "example": "1", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Returns an empty response when the file has been successfully\ndeleted." }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file is not found or has already been deleted, or the user\ndoes not have access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `file_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the file. This indicates that the file\nhas changed since it was last requested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/files/{file_id}/content": { "get": { "operationId": "get_files_id_content", "summary": "Download file", "tags": [ "Downloads" ], "x-box-tag": "downloads", "description": "Returns the contents of a file in binary format.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "range", "description": "The byte range of the content to download.\n\nThe format `bytes={start_byte}-{end_byte}` can be used to specify\nwhat section of the file to download.", "example": "bytes=0-1024", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "boxapi", "description": "The URL, and optional password, for the shared link of this item.\n\nThis header can be used to access items that have not been\nexplicitly shared with a user.\n\nUse the format `shared_link=[link]` or if a password is required then\nuse `shared_link=[link]&shared_link_password=[password]`.\n\nThis header can be used on the file or folder shared, as well as on any files\nor folders nested within the item.", "example": "shared_link=[link]&shared_link_password=[password]", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "version", "description": "The file version to download", "example": "4", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "access_token", "description": "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.\nWhen 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.", "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "202": { "description": "If the file is not ready to be downloaded yet `Retry-After` header will\nbe returned indicating the time in seconds after which the file will\nbe available for the client to download.\n\nThis response can occur when the file was uploaded immediately before the\ndownload request.", "headers": { "Retry-After": { "description": "The time in seconds after which to retry the download", "schema": { "type": "integer" } } } }, "302": { "description": "If the file is available to be downloaded the response will include a\n`Location` header for the file on `dl.boxcloud.com`.\n\nThe `dl.boxcloud.com` URL is not persistent and clients will need\nto follow the redirect in order to actually download the file.", "headers": { "Location": { "description": "A pointer to the download URL", "schema": { "type": "string", "format": "url" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_files_id_content", "tags": [ "Uploads" ], "x-box-tag": "uploads", "summary": "Upload file version", "description": "Update a file's content. For file sizes over 50MB we recommend\nusing the Chunk Upload APIs.\n\n# Request body order\n\nThe `attributes` part of the body must come **before** the\n`file` part. Requests that do not follow this format when\nuploading the file will receive a HTTP `400` error with a\n`metadata_after_file_contents` error code.", "servers": [ { "url": "https://upload.box.com/api/2.0", "description": "Server for file uploads" } ], "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "if-match", "description": "Ensures this item hasn't recently changed before\nmaking changes.\n\nPass in the item's last observed `etag` value\ninto this header and the endpoint will fail\nwith a `412 Precondition Failed` if it\nhas changed since.", "in": "header", "required": false, "example": "1", "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "content-md5", "required": false, "schema": { "type": "string" }, "example": "134b65991ed521fcfe4724b7d814ab8ded5185dc", "in": "header", "description": "An optional header containing the SHA1 hash of the file to\nensure that the file was not corrupted in transit." } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "attributes", "file" ], "properties": { "attributes": { "description": "The additional attributes of the file being uploaded. Mainly the\nname and the parent folder. These attributes are part of the multi\npart request body and are in JSON format.\n\n\n\n The `attributes` part of the body must come **before** the\n `file` part. Requests that do not follow this format when\n uploading the file will receive a HTTP `400` error with a\n `metadata_after_file_contents` error code.\n\n", "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "An optional new name for the file. If specified, the file\nwill be renamed when the new version is uploaded.", "example": "Photo 2.0.png" }, "content_modified_at": { "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "description": "Defines the time the file was last modified at.\n\nIf not set, the upload time will be used." } } }, "file": { "type": "string", "format": "binary", "description": "The content of the file to upload to Box.\n\n\n\n The `attributes` part of the body must come **before** the\n `file` part. Requests that do not follow this format when\n uploading the file will receive a HTTP `400` error with a\n `metadata_after_file_contents` error code.\n\n" } } } } } }, "responses": { "200": { "description": "Returns the new file object in a list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Files" } } } }, "412": { "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the file. This indicates that the file\nhas changed since it was last requested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/files/content": { "options": { "operationId": "options_files_content", "summary": "Preflight check before upload", "tags": [ "Files" ], "x-box-tag": "uploads", "description": "Performs a check to verify that a file will be accepted by Box\nbefore you upload the entire file.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name for the file", "example": "File.mp4" }, "size": { "type": "integer", "format": "int32", "description": "The size of the file in bytes", "example": 1024 }, "parent": { "allOf": [ { "type": "object", "description": "The parent for this item", "properties": { "id": { "type": "string", "description": "The ID of parent item", "example": "123" } } }, { "description": "The parent folder to upload the file to" } ] } } } } } }, "responses": { "200": { "description": "If the check passed, the response will include a session URL that\ncan be used to upload the file to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadUrl" } } } }, "409": { "description": "If the check did not pass, the response will include some details on\nwhy it did not pass.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_files_content", "tags": [ "Uploads" ], "x-box-tag": "uploads", "summary": "Upload file", "description": "Uploads a small file to Box. For file sizes over 50MB we recommend\nusing the Chunk Upload APIs.\n\n# Request body order\n\nThe `attributes` part of the body must come **before** the\n`file` part. Requests that do not follow this format when\nuploading the file will receive a HTTP `400` error with a\n`metadata_after_file_contents` error code.", "servers": [ { "url": "https://upload.box.com/api/2.0", "description": "Server for file uploads" } ], "parameters": [ { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "content-md5", "required": false, "schema": { "type": "string" }, "example": "134b65991ed521fcfe4724b7d814ab8ded5185dc", "in": "header", "description": "An optional header containing the SHA1 hash of the file to\nensure that the file was not corrupted in transit." } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "attributes", "file" ], "properties": { "attributes": { "description": "The additional attributes of the file being uploaded. Mainly the\nname and the parent folder. These attributes are part of the multi\npart request body and are in JSON format.\n\n\n\n The `attributes` part of the body must come **before** the\n `file` part. Requests that do not follow this format when\n uploading the file will receive a HTTP `400` error with a\n `metadata_after_file_contents` error code.\n\n", "type": "object", "required": [ "name", "parent" ], "properties": { "name": { "type": "string", "description": "The name of the file", "example": "Photo.png" }, "parent": { "type": "object", "description": "The parent folder to upload the file to", "required": [ "id" ], "properties": { "id": { "type": "string", "example": "124132", "description": "The id of the parent folder. Use\n`0` for the user's root folder." } } }, "content_created_at": { "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "description": "Defines the time the file was originally created at.\n\nIf not set, the upload time will be used." }, "content_modified_at": { "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "description": "Defines the time the file was last modified at.\n\nIf not set, the upload time will be used." } } }, "file": { "type": "string", "format": "binary", "description": "The content of the file to upload to Box.\n\n\n\n The `attributes` part of the body must come **before** the\n `file` part. Requests that do not follow this format when\n uploading the file will receive a HTTP `400` error with a\n `metadata_after_file_contents` error code.\n\n" } } } } } }, "responses": { "201": { "description": "Returns the new file object in a list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Files" } } } }, "400": { "description": "Returns an error if some of the parameters are missing or\nnot valid.\n* `bad_request` when a parameter is missing or incorrect.\n* `item_name_too_long` when the folder name is too long.\n* `item_name_invalid` when the folder name contains\n non-valid characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the parent folder\ndoes not exist or if the user\nis not authorized to access the parent folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error if the file already exists,\nor the account has run out of disk space.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/files/upload_sessions": { "post": { "operationId": "post_files_upload_sessions", "summary": "Create upload session", "tags": [ "Uploads (Chunked)" ], "x-box-tag": "chunked_uploads", "description": "Creates an upload session for a new file.", "servers": [ { "url": "https://upload.box.com/api/2.0", "description": "Server for file uploads" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "folder_id", "file_size", "file_name" ], "properties": { "folder_id": { "description": "The ID of the folder to upload the new file to.", "type": "string", "example": "0" }, "file_size": { "description": "The total number of bytes of the file to be uploaded", "example": 104857600, "type": "integer", "format": "int64" }, "file_name": { "description": "The name of new file", "example": "Project.mov", "type": "string" } } } } } }, "responses": { "201": { "description": "Returns a new upload session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSession" } } } }, "400": { "description": "Returns an error if some of the parameters are missing or\nnot valid.\n\n* `missing_destination`: No `folder_id` was provided\n* `invalid_folder_id`: `folder_id` is not valid\n* `item_name_invalid`: `file_name` is not valid\n* `missing_file_size`: `file_size` was not provided\n* `invalid_file_size`: `file_size` was not a valid number\n* `file_size_too_small`: `file_size` is below minimum file size for\n uploads via this API\n* `missing_file_name`: `file_name` was not provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error if the operation is not allowed for some reason.\n\n* `storage_limit_exceeded`: Account storage limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the parent folder could not be found, or\nthe authenticated user does not have access to it.\n\n* `invalid_parameter`: The `folder_id` value represents a\n folder that the user does not have access to, or does not\n exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error if the file already exists,\nor the account has run out of disk space.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/files/{file_id}/upload_sessions": { "post": { "operationId": "post_files_id_upload_sessions", "summary": "Create upload session for existing file", "tags": [ "Uploads (Chunked)" ], "x-box-tag": "chunked_uploads", "description": "Creates an upload session for an existing file.", "servers": [ { "url": "https://upload.box.com/api/2.0", "description": "Server for file uploads" } ], "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "file_size" ], "properties": { "file_size": { "description": "The total number of bytes of the file to be uploaded", "example": 104857600, "type": "integer", "format": "int64" }, "file_name": { "description": "The optional new name of new file", "example": "Project.mov", "type": "string" } } } } } }, "responses": { "201": { "description": "Returns a new upload session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSession" } } } }, "409": { "description": "Returns an error if the file already exists,\nor if the account has run out of disk space.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/files/upload_sessions/{upload_session_id}": { "get": { "operationId": "get_files_upload_sessions_id", "summary": "Get upload session", "tags": [ "Uploads (Chunked)" ], "description": "Return information about an upload session.", "x-box-tag": "chunked_uploads", "servers": [ { "url": "https://upload.box.com/api/2.0", "description": "Server for file uploads" } ], "parameters": [ { "name": "upload_session_id", "description": "The ID of the upload session.", "example": "D5E3F7A", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns an upload session object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSession" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "put": { "operationId": "put_files_upload_sessions_id", "summary": "Upload part of file", "tags": [ "Uploads (Chunked)" ], "x-box-tag": "chunked_uploads", "description": "Updates a chunk of an upload session for a file.", "servers": [ { "url": "https://upload.box.com/api/2.0", "description": "Server for file uploads" } ], "parameters": [ { "name": "upload_session_id", "description": "The ID of the upload session.", "example": "D5E3F7A", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "digest", "description": "The [RFC3230][1] message digest of the chunk uploaded.\n\nOnly SHA1 is supported. The SHA1 digest must be base64\nencoded. The format of this header is as\n`sha=BASE64_ENCODED_DIGEST`.\n\nTo get the value for the `SHA` digest, use the\nopenSSL command to encode the file part:\n`openssl sha1 -binary | base64`\n\n[1]: https://tools.ietf.org/html/rfc3230", "example": "sha=fpRyg5eVQletdZqEKaFlqwBXJzM=", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "content-range", "description": "The byte range of the chunk.\n\nMust not overlap with the range of a part already\nuploaded this session. Each part’s size must be\nexactly equal in size to the part size specified\nin the upload session that you created.\nOne exception is the last part of the file, as this can be smaller.\n\nWhen providing the value for `content-range`, remember that:\n\n* The lower bound of each part's byte range\n must be a multiple of the part size.\n* The higher bound must be a multiple of the part size - 1.", "example": "bytes 8388608-16777215/445856194", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "description": "The binary content of the file" } } } }, "responses": { "200": { "description": "Chunk has been uploaded successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadedPart" } } } }, "409": { "description": "Returns an error if the chunk conflicts with another\nchunk previously uploaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "description": "Returns an error if a precondition was not met.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "416": { "description": "Returns an error if the content range does not match a specified range\nfor the session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_files_upload_sessions_id", "summary": "Remove upload session", "tags": [ "Uploads (Chunked)" ], "description": "Abort an upload session and discard all data uploaded.\n\nThis cannot be reversed.", "servers": [ { "url": "https://upload.box.com/api/2.0", "description": "Server for file uploads" } ], "x-box-tag": "chunked_uploads", "parameters": [ { "name": "upload_session_id", "description": "The ID of the upload session.", "example": "D5E3F7A", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "A blank response is returned if the session was\nsuccessfully aborted." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/files/upload_sessions/{upload_session_id}/parts": { "get": { "operationId": "get_files_upload_sessions_id_parts", "summary": "List parts", "tags": [ "Uploads (Chunked)" ], "x-box-tag": "chunked_uploads", "servers": [ { "url": "https://upload.box.com/api/2.0", "description": "Server for file uploads" } ], "description": "Return a list of the chunks uploaded to the upload\nsession so far.", "parameters": [ { "name": "upload_session_id", "description": "The ID of the upload session.", "example": "D5E3F7A", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "offset", "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } } ], "responses": { "200": { "description": "Returns a list of parts that have been uploaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadParts" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/files/upload_sessions/{upload_session_id}/commit": { "post": { "operationId": "post_files_upload_sessions_id_commit", "summary": "Commit upload session", "tags": [ "Uploads (Chunked)" ], "x-box-tag": "chunked_uploads", "servers": [ { "url": "https://upload.box.com/api/2.0", "description": "Server for file uploads" } ], "description": "Close an upload session and create a file from the\nuploaded chunks.", "parameters": [ { "name": "upload_session_id", "description": "The ID of the upload session.", "example": "D5E3F7A", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "digest", "description": "The [RFC3230][1] message digest of the whole file.\n\nOnly SHA1 is supported. The SHA1 digest must be Base64\nencoded. The format of this header is as\n`sha=BASE64_ENCODED_DIGEST`.\n\n[1]: https://tools.ietf.org/html/rfc3230", "in": "header", "example": "sha=fpRyg5eVQletdZqEKaFlqwBXJzM=", "required": true, "schema": { "type": "string" } }, { "name": "if-match", "description": "Ensures this item hasn't recently changed before\nmaking changes.\n\nPass in the item's last observed `etag` value\ninto this header and the endpoint will fail\nwith a `412 Precondition Failed` if it\nhas changed since.", "in": "header", "required": false, "example": "1", "schema": { "type": "string" } }, { "name": "if-none-match", "description": "Ensures an item is only returned if it has changed.\n\nPass in the item's last observed `etag` value\ninto this header and the endpoint will fail\nwith a `304 Not Modified` if the item has not\nchanged since.", "in": "header", "required": false, "example": "1", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "parts" ], "properties": { "parts": { "type": "array", "description": "The list details for the uploaded parts", "items": { "$ref": "#/components/schemas/UploadPart" } } } } } } }, "responses": { "201": { "description": "Returns the file object in a list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Files" } } } }, "202": { "description": "Returns when all chunks have been uploaded but not yet processed.\n\nInspect the upload session to get more information about the\nprogress of processing the chunks, then retry committing the file\nwhen all chunks have processed.", "headers": { "Retry-After": { "description": "Indicates the number of seconds the client should wait before\nattempting their commit request again.", "schema": { "type": "integer" } } } }, "409": { "description": "Returns an error if there is already a file with the same name\nin the target folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "description": "Returns an error if the `If-Match` or `If-None-Match` conditions fail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/files/{file_id}/copy": { "post": { "operationId": "post_files_id_copy", "summary": "Copy file", "description": "Creates a copy of a file.", "tags": [ "Files" ], "x-box-tag": "files", "x-box-enable-explorer": true, "x-box-sanitized": true, "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "parent" ], "nullable": false, "properties": { "name": { "type": "string", "description": "An optional new name for the copied file.\n\nThere are some restrictions to the file name. Names containing\nnon-printable ASCII characters, forward and backward slashes\n(`/`, `\\`), and protected names like `.` and `..` are\nautomatically sanitized by removing the non-allowed\ncharacters.", "example": "FileCopy.txt", "maxLength": 255 }, "version": { "type": "string", "description": "An optional ID of the specific file version to copy.", "example": "0" }, "parent": { "type": "object", "description": "The destination folder to copy the file to.", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The ID of folder to copy the file to.", "example": "0" } } } } } } } }, "responses": { "201": { "description": "Returns a new file object representing the copied file.\n\nNot all available fields are returned by default. Use the\n[fields](#param-fields) query parameter to explicitly request\nany specific fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File--Full" } } } }, "304": { "description": "Returns an empty response when the `If-None-Match` header matches\nthe current `etag` value of the file. This indicates that the file\nhas not changed since it was last requested." }, "400": { "description": "Returns an error if some of the parameters are missing or\nnot valid.\n\n* `bad_request` when a parameter is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error when the user does not have the\nright permissions to create the copy a file.\n\n* `forbidden_by_policy`: Returned if copying a file is\nforbidden due to information barrier restrictions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if either the source file or the destination\nfolder could not be found, or the authenticated user does not\nhave access to either.\n\n* `not_found` when the authenticated user does not have access\n to the source file or the destination folder", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "* `operation_blocked_temporary`: Returned if either of the destination\n or source folders is locked due to another move, copy, delete or\n restore operation in process.\n\n The operation can be retried at a later point.\n\n* `item_name_in_use` when a folder with the same name already\n exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/files/{file_id}/thumbnail.{extension}": { "get": { "operationId": "get_files_id_thumbnail_id", "summary": "Get file thumbnail", "description": "Retrieves a thumbnail, or smaller image representation, of a file.\n\nSizes of `32x32`,`64x64`, `128x128`, and `256x256` can be returned in\nthe `.png` format and sizes of `32x32`, `160x160`, and `320x320`\ncan be returned in the `.jpg` format.\n\nThumbnails can be generated for the image and video file formats listed\n[found on our community site][1].\n\n[1]: https://community.box.com/t5/Migrating-and-Previewing-Content/File-Types-and-Fonts-Supported-in-Box-Content-Preview/ta-p/327", "tags": [ "Files" ], "x-box-tag": "files", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "extension", "description": "The file format for the thumbnail", "in": "path", "required": true, "example": "png", "schema": { "type": "string", "enum": [ "png", "jpg" ] } }, { "name": "min_height", "description": "The minimum height of the thumbnail", "in": "query", "example": 32, "schema": { "type": "integer", "minimum": 32, "maximum": 320 } }, { "name": "min_width", "description": "The minimum width of the thumbnail", "in": "query", "example": 32, "schema": { "type": "integer", "minimum": 32, "maximum": 320 } }, { "name": "max_height", "description": "The maximum height of the thumbnail", "in": "query", "required": false, "example": 320, "schema": { "type": "integer", "minimum": 32, "maximum": 320 } }, { "name": "max_width", "description": "The maximum width of the thumbnail", "in": "query", "required": false, "example": 320, "schema": { "type": "integer", "minimum": 32, "maximum": 320 } } ], "responses": { "200": { "description": "When a thumbnail can be created the thumbnail data will be\nreturned in the body of the response.", "content": { "image/png": { "schema": { "type": "string", "format": "binary", "description": "The thumbnail" } }, "image/jpg": { "schema": { "type": "string", "format": "binary", "description": "The thumbnail" } } } }, "202": { "description": "Sometimes generating a thumbnail can take a few seconds. In these\nsituations the API returns a `Location`-header pointing to a\nplaceholder graphic for this file type.\n\nThe placeholder graphic can be used in a user interface until the\nthumbnail generation has completed. The `Retry-After`-header indicates\nwhen to the thumbnail will be ready. At that time, retry this endpoint\nto retrieve the thumbnail.", "headers": { "Retry-After": { "description": "The time in seconds after which the thumbnail will be available.\n\nYour application only attempt to get the thumbnail again after\nthis time.", "schema": { "type": "integer", "format": "int64" } }, "Location": { "description": "A pointer to a placeholder graphic that can be used until the\nthumbnail has been generated.", "schema": { "type": "string", "format": "url" } } } }, "302": { "description": "Returns an error when Box is not able to create a thumbnail for this\nfile type.\n\nInstead, a `Location`-header pointing to a placeholder graphic for\nthis file type will be returned.", "headers": { "Location": { "description": "A pointer to a placeholder graphic that can be used for this\nfile type.", "schema": { "type": "string", "format": "url" } } } }, "400": { "description": "Returns an error if some of the parameters are missing or\nnot valid.\n\n* `requested_preview_unavailable` - an incorrect dimension was\n requested. This will happen if the dimension requested is\n larger or smaller than the available file sizes for the thumbnail\n format, or when when any of the size constraints contradict\n each other.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file is not found, or the user does not\nhave access to the file, or for additional reasons.\n\n* `preview_cannot_be_generated` - Box does not support thumbnails\n for this type of file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/files/{file_id}/collaborations": { "get": { "operationId": "get_files_id_collaborations", "summary": "List file collaborations", "description": "Retrieves a list of pending and active collaborations for a\nfile. This returns all the users that have access to the file\nor have been invited to the file.", "tags": [ "Collaborations (List)" ], "x-box-tag": "list_collaborations", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a collection of collaboration objects. If there are no\ncollaborations on this file an empty collection will be returned.\n\nThis list includes pending collaborations, for which the `status`\nis set to `pending`, indicating invitations that have been sent but not\nyet accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collaborations" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/files/{file_id}/comments": { "get": { "operationId": "get_files_id_comments", "summary": "List file comments", "description": "Retrieves a list of comments for a file.", "tags": [ "Comments" ], "x-box-tag": "comments", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } }, { "name": "offset", "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 } } ], "responses": { "200": { "description": "Returns a collection of comment objects. If there are no\ncomments on this file an empty collection will be returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comments" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/files/{file_id}/tasks": { "get": { "operationId": "get_files_id_tasks", "summary": "List tasks on file", "description": "Retrieves a list of all the tasks for a file. This\nendpoint does not support pagination.", "tags": [ "Tasks" ], "x-box-tag": "tasks", "x-box-sanitized": true, "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a list of tasks on a file.\n\nIf there are no tasks on this file an empty collection is returned\ninstead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tasks" } } } }, "404": { "description": "Returns an error when the file could not be found or the user does not\nhave access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returns an error when the `file_id` was not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "500": { "description": "Returns an error when an attempt was made to retrieve tasks for the file\nwith ID `0`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/files/{file_id}/trash": { "get": { "operationId": "get_files_id_trash", "summary": "Get trashed file", "tags": [ "Trashed files" ], "x-box-tag": "trashed_files", "description": "Retrieves a file that has been moved to the trash.\n\nPlease note that only if the file itself has been moved to the\ntrash can it be retrieved with this API call. If instead one of\nits parent folders was moved to the trash, only that folder\ncan be inspected using the\n[`GET /folders/:id/trash`](e://get_folders_id_trash) API.\n\nTo list all items that have been moved to the trash, please\nuse the [`GET /folders/trash/items`](e://get-folders-trash-items/)\nAPI.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Returns the file that was trashed,\nincluding information about when the it\nwas moved to the trash.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrashFile" } } } }, "404": { "description": "Returns an error if the file can not be found directly\nin the trash.\n\nPlease note that a `HTTP 404` is also returned if any of\nthe file's parent folders have been moved to the trash.\n\nIn that case, only that parent folder can be inspected using\nthe [`GET /folders/:id/trash`](e://get_folders_id_trash) API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_files_id_trash", "summary": "Permanently remove file", "tags": [ "Trashed files" ], "x-box-tag": "trashed_files", "description": "Permanently deletes a file that is in the trash.\nThis action cannot be undone.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Returns an empty response when the file was\npermanently deleted." }, "404": { "description": "Returns an error if the file is not in the trash.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/files/{file_id}/versions": { "get": { "operationId": "get_files_id_versions", "summary": "List all file versions", "tags": [ "File versions" ], "x-box-tag": "file_versions", "description": "Retrieve a list of the past versions for a file.\n\nVersions are only tracked by Box users with premium accounts. To fetch the ID\nof the current version of a file, use the `GET /file/:id` API.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } }, { "name": "offset", "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 } } ], "responses": { "200": { "description": "Returns an array of past versions for this file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileVersions" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/files/{file_id}/versions/{file_version_id}": { "get": { "operationId": "get_files_id_versions_id", "summary": "Get file version", "tags": [ "File versions" ], "x-box-tag": "file_versions", "description": "Retrieve a specific version of a file.\n\nVersions are only tracked for Box users with premium accounts.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "file_version_id", "description": "The ID of the file version", "in": "path", "required": true, "example": "1234", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a specific version of a file.\n\nNot all available fields are returned by default. Use the\n[fields](#param-fields) query parameter to explicitly request\nany specific fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileVersion--Full" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_files_id_versions_id", "summary": "Remove file version", "tags": [ "File versions" ], "x-box-tag": "file_versions", "description": "Move a file version to the trash.\n\nVersions are only tracked for Box users with premium accounts.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "file_version_id", "description": "The ID of the file version", "in": "path", "required": true, "example": "1234", "schema": { "type": "string" } }, { "name": "if-match", "description": "Ensures this item hasn't recently changed before\nmaking changes.\n\nPass in the item's last observed `etag` value\ninto this header and the endpoint will fail\nwith a `412 Precondition Failed` if it\nhas changed since.", "in": "header", "required": false, "example": "1", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Returns an empty response when the file has been successfully\ndeleted." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "put": { "operationId": "put_files_id_versions_id", "summary": "Restore file version", "tags": [ "File versions" ], "x-box-tag": "file_versions", "description": "Restores a specific version of a file after it was deleted.\nDon't use this endpoint to restore Box Notes,\nas it works with file formats such as PDF, DOC,\nPPTX or similar.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "file_version_id", "description": "The ID of the file version", "in": "path", "required": true, "example": "1234", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "The file version to be\nrestored", "properties": { "trashed_at": { "type": "string", "description": "Set this to `null` to clear\nthe date and restore the file.", "example": "null" } } } } } }, "responses": { "200": { "description": "Returns a restored file version object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileVersion--Full" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/files/{file_id}/versions/current": { "post": { "operationId": "post_files_id_versions_current", "summary": "Promote file version", "tags": [ "File versions" ], "x-box-tag": "file_versions", "description": "Promote a specific version of a file.\n\nIf previous versions exist, this method can be used to\npromote one of the older versions to the top of the version history.\n\nThis creates a new copy of the old version and puts it at the\ntop of the versions history. The file will have the exact same contents\nas the older version, with the the same hash digest, `etag`, and\nname as the original.\n\nOther properties such as comments do not get updated to their\nformer values.\n\nDon't use this endpoint to restore Box Notes,\nas it works with file formats such as PDF, DOC,\nPPTX or similar.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "The file version to promote", "properties": { "id": { "type": "string", "description": "The file version ID", "example": "11446498" }, "type": { "type": "string", "description": "The type to promote", "example": "file_version", "enum": [ "file_version" ] } } } } } }, "responses": { "201": { "description": "Returns a newly created file version object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileVersion--Full" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/files/{file_id}/metadata": { "get": { "operationId": "get_files_id_metadata", "summary": "List metadata instances on file", "tags": [ "Metadata instances (Files)" ], "x-box-tag": "file_metadata", "x-box-sanitized": true, "description": "Retrieves all metadata for a given file.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns all the metadata associated with a file.\n\nThis API does not support pagination and will therefore always return\nall of the metadata associated to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metadatas" } } } }, "403": { "description": "Returned when the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the user does not have access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/files/{file_id}/metadata/enterprise/securityClassification-6VMVochwUWo": { "get": { "operationId": "get_files_id_metadata_enterprise_securityClassification-6VMVochwUWo", "summary": "Get classification on file", "tags": [ "Classifications on files" ], "x-box-tag": "file_classifications", "x-box-sanitized": true, "description": "Retrieves the classification metadata instance that\nhas been applied to a file.\n\nThis API can also be called by including the enterprise ID in the\nURL explicitly, for example\n`/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Returns an instance of the `securityClassification` metadata\ntemplate, which contains a `Box__Security__Classification__Key`\nfield that lists all the classifications available to this\nenterprise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Classification" } } } }, "403": { "description": "Returned when the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the metadata template specified\nwas not applied to this file or the user does not have access to the\nfile.\n\n* `instance_not_found` - The metadata template was not applied to the\nfile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned when the method was not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_files_id_metadata_enterprise_securityClassification-6VMVochwUWo", "summary": "Add classification to file", "tags": [ "Classifications on files" ], "x-box-tag": "file_classifications", "x-box-sanitized": true, "description": "Adds a classification to a file by specifying the label of the\nclassification to add.\n\nThis API can also be called by including the enterprise ID in the\nURL explicitly, for example\n`/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Box__Security__Classification__Key": { "type": "string", "description": "The name of the classification to apply to this file.\n\nTo list the available classifications in an enterprise,\nuse the classification API to retrieve the\n[classification template](e://get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema)\nwhich lists all available classification keys.", "example": "Sensitive" } } } } } }, "responses": { "201": { "description": "Returns the classification template instance\nthat was applied to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Classification" } } } }, "400": { "description": "Returns an error when the request body is not valid.\n\n* `schema_validation_failed` - The request body contains a value for a for\na field that either does not exist, or for which the value or type does\nnot match the expected field type. An example might be an unknown option\nfor an `enum` or `multiSelect` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the file or metadata template was not found.\n\n* `not_found` - The file could not be found, or the user does not have\naccess to the file.\n* `instance_tuple_not_found` - The metadata template was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error when an instance of this metadata template is already\npresent on the file.\n\n* `tuple_already_exists` - An instance of them metadata template already\nexists on the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "put": { "operationId": "put_files_id_metadata_enterprise_securityClassification-6VMVochwUWo", "summary": "Update classification on file", "tags": [ "Classifications on files" ], "x-box-tag": "file_classifications", "x-box-sanitized": true, "description": "Updates a classification on a file.\n\nThe classification can only be updated if a classification has already been\napplied to the file before. When editing classifications, only values are\ndefined for the enterprise will be accepted.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json-patch+json": { "schema": { "description": "A list containing the one change to make, to\nupdate the classification label.", "type": "array", "items": { "type": "object", "description": "The operation to perform on the classification\nmetadata template instance. In this case, it use\nused to replace the value stored for the\n`Box__Security__Classification__Key` field with a new\nvalue.", "properties": { "op": { "type": "string", "example": "replace", "description": "`replace`", "enum": [ "replace" ] }, "path": { "type": "string", "example": "/Box__Security__Classification__Key", "description": "`/Box__Security__Classification__Key`", "enum": [ "/Box__Security__Classification__Key" ] }, "value": { "type": "string", "description": "The name of the classification to apply to this file.\n\nTo list the available classifications in an enterprise,\nuse the classification API to retrieve the\n[classification template](e://get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema)\nwhich lists all available classification keys.", "example": "Sensitive" } } } } } } }, "responses": { "200": { "description": "Returns the updated classification metadata template instance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Classification" } } } }, "400": { "description": "Returns an error when the request body is not valid.\n\n* `bad_request` - The request body format is not an array of valid JSON\nPatch operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "500": { "description": "Returns an error in some edge cases when the request body is not a valid\narray of JSON Patch items.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_files_id_metadata_enterprise_securityClassification-6VMVochwUWo", "summary": "Remove classification from file", "tags": [ "Classifications on files" ], "x-box-tag": "file_classifications", "x-box-sanitized": true, "description": "Removes any classifications from a file.\n\nThis API can also be called by including the enterprise ID in the\nURL explicitly, for example\n`/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Returns an empty response when the classification is\nsuccessfully deleted." }, "400": { "description": "Returned when the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the file does not have any classification applied\nto it, or when the user does not have access to the\nfile.\n\n* `instance_not_found` - An instance of the classification metadata\ntemplate with the was not found on this file.\n* `not_found` - The file was not found, or the user does not have access\nto the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned when the method was not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/files/{file_id}/metadata/{scope}/{template_key}": { "get": { "operationId": "get_files_id_metadata_id_id", "summary": "Get metadata instance on file", "tags": [ "Metadata instances (Files)" ], "x-box-tag": "file_metadata", "x-box-sanitized": true, "description": "Retrieves the instance of a metadata template that has been applied to a\nfile.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "scope", "description": "The scope of the metadata template", "example": "global", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "global", "enterprise" ] } }, { "name": "template_key", "description": "The name of the metadata template", "example": "properties", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "An instance of the metadata template that includes\nadditional \"key:value\" pairs defined by the user or\nan application.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metadata" } } } }, "403": { "description": "Returned when the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the metadata template specified\nwas not applied to this file or the user does not have access to the\nfile.\n\n* `instance_not_found` - The metadata template was not applied to the\nfile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned when the method was not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_files_id_metadata_id_id", "summary": "Create metadata instance on file", "tags": [ "Metadata instances (Files)" ], "x-box-tag": "file_metadata", "x-box-sanitized": true, "description": "Applies an instance of a metadata template to a file.\n\nIn most cases only values that are present in the metadata template\nwill be accepted, except for the `global.properties` template which accepts\nany key-value pair.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "scope", "description": "The scope of the metadata template", "example": "global", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "global", "enterprise" ] } }, { "name": "template_key", "description": "The name of the metadata template", "example": "properties", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "name": "Aaron Levie" }, "additionalProperties": { "type": "string", "description": "A value for each of the fields that are present on the metadata\ntemplate.\n\nFor the `global.properties` template this can be an a list of zero\nor more fields, as this template allows for any generic key-value\npairs to be stored on the template.", "example": "Aaron Levie", "x-box-example-key": "name" } } } } }, "responses": { "201": { "description": "Returns the instance of the template that was applied to the file,\nincluding the data that was applied to the template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metadata" } } } }, "400": { "description": "Returns an error when the request body is not valid.\n\n* `schema_validation_failed` - The request body contains a value for a for\na field that either does not exist, or for which the value or type does\nnot match the expected field type. An example might be an unknown option\nfor an `enum` or `multiSelect` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the file or metadata template was not found.\n\n* `not_found` - The file could not be found, or the user does not have\naccess to the file.\n* `instance_tuple_not_found` - The metadata template was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error when an instance of this metadata template is already\npresent on the file.\n\n* `tuple_already_exists` - An instance of them metadata template already\nexists on the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "put": { "operationId": "put_files_id_metadata_id_id", "summary": "Update metadata instance on file", "tags": [ "Metadata instances (Files)" ], "x-box-tag": "file_metadata", "x-box-sanitized": true, "description": "Updates a piece of metadata on a file.\n\nThe metadata instance can only be updated if the template has already been\napplied to the file before. When editing metadata, only values that match\nthe metadata template schema will be accepted.\n\nThe update is applied atomically. If any errors occur during the\napplication of the operations, the metadata instance will not be changed.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "scope", "description": "The scope of the metadata template", "example": "global", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "global", "enterprise" ] } }, { "name": "template_key", "description": "The name of the metadata template", "example": "properties", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json-patch+json": { "schema": { "description": "A [JSON-Patch](https://tools.ietf.org/html/rfc6902)\nspecification for the changes to make to the metadata\ninstance.\n\nThe changes are represented as a JSON array of\noperation objects.", "type": "array", "items": { "title": "A metadata instance update operation", "description": "A [JSON-Patch](https://tools.ietf.org/html/rfc6902) operation for a\nchange to make to the metadata instance.", "type": "object", "properties": { "op": { "type": "string", "example": "add", "enum": [ "add", "replace", "remove", "test", "move", "copy" ], "description": "The type of change to perform on the template. Some\nof these are hazardous as they will change existing templates." }, "path": { "type": "string", "example": "/currentState", "description": "The location in the metadata JSON object\nto apply the changes to, in the format of a\n[JSON-Pointer](https://tools.ietf.org/html/rfc6901).\n\nThe path must always be prefixed with a `/` to represent the root\nof the template. The characters `~` and `/` are reserved\ncharacters and must be escaped in the key." }, "value": { "type": "string", "example": "reviewed", "description": "The value to be set or tested.\n\nRequired for `add`, `replace`, and `test` operations. For `add`,\nif the value exists already the previous value will be overwritten\nby the new value. For `replace`, the value must exist before\nreplacing.\n\nFor `test`, the existing value at the `path` location must match\nthe specified value." }, "from": { "type": "string", "example": "/nextState", "description": "The location in the metadata JSON object to move or copy a value\nfrom. Required for `move` or `copy` operations and must be in the\nformat of a [JSON-Pointer](https://tools.ietf.org/html/rfc6901)." } } } } } } }, "responses": { "200": { "description": "Returns the updated metadata template instance, with the\ncustom template data included.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metadata" } } } }, "400": { "description": "Returns an error when the request body is not valid.\n\n* `bad_request` - The request body format is not an array of valid JSON\nPatch objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "500": { "description": "Returns an error in some edge cases when the request body is not a valid\narray of JSON Patch items.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_files_id_metadata_id_id", "summary": "Remove metadata instance from file", "tags": [ "Metadata instances (Files)" ], "x-box-tag": "file_metadata", "x-box-sanitized": true, "description": "Deletes a piece of file metadata.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "scope", "description": "The scope of the metadata template", "example": "global", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "global", "enterprise" ] } }, { "name": "template_key", "description": "The name of the metadata template", "example": "properties", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Returns an empty response when the metadata is\nsuccessfully deleted." }, "400": { "description": "Returned when the request parameters are not valid. This may happen of the\n`scope` is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the file does not have an instance of the metadata\ntemplate applied to it, or when the user does not have access to the\nfile.\n\n* `instance_not_found` - An instance of the metadata template with the\ngiven `scope` and `templateKey` was not found on this file.\n* `not_found` - The file was not found, or the user does not have access\nto the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned when the method was not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/files/{file_id}/metadata/global/boxSkillsCards": { "get": { "operationId": "get_files_id_metadata_global_boxSkillsCards", "summary": "List Box Skill cards on file", "tags": [ "Skills" ], "x-box-tag": "skills", "description": "List the Box Skills metadata cards that are attached to a file.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns all the metadata associated with a file.\n\nThis API does not support pagination and will therefore always return\nall of the metadata associated to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCardsMetadata" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_files_id_metadata_global_boxSkillsCards", "summary": "Create Box Skill cards on file", "tags": [ "Skills" ], "x-box-tag": "skills", "description": "Applies one or more Box Skills metadata cards to a file.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "cards" ], "properties": { "cards": { "type": "array", "description": "A list of Box Skill cards to apply to this file.", "items": { "oneOf": [ { "$ref": "#/components/schemas/KeywordSkillCard" }, { "$ref": "#/components/schemas/TimelineSkillCard" }, { "$ref": "#/components/schemas/TranscriptSkillCard" }, { "$ref": "#/components/schemas/StatusSkillCard" } ] } } } } } } }, "responses": { "201": { "description": "Returns the instance of the template that was applied to the file,\nincluding the data that was applied to the template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCardsMetadata" } } } }, "400": { "description": "Returns an error when the request body is not valid.\n\n* `schema_validation_failed` - The request body contains a value for a for\na field that either does not exist, or for which the value or type does\nnot match the expected field type. An example might be an unknown option\nfor an `enum` or `multiSelect` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the file or metadata template was not found.\n\n* `not_found` - The file could not be found, or the user does not have\naccess to the file.\n* `instance_tuple_not_found` - The metadata template was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error when an instance of this metadata template is already\npresent on the file.\n\n* `tuple_already_exists` - An instance of them metadata template already\nexists on the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "put": { "operationId": "put_files_id_metadata_global_boxSkillsCards", "summary": "Update Box Skill cards on file", "tags": [ "Skills" ], "x-box-tag": "skills", "description": "Updates one or more Box Skills metadata cards to a file.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json-patch+json": { "schema": { "description": "A [JSON-Patch](https://tools.ietf.org/html/rfc6902)\nspecification for the changes to make to the metadata\ntemplate.\n\nThe changes are represented as a JSON array of\noperation objects.", "type": "array", "items": { "type": "object", "description": "An operation that replaces an existing card.", "properties": { "op": { "type": "string", "description": "`replace`", "example": "replace", "enum": [ "replace" ] }, "path": { "type": "string", "description": "The JSON Path that represents the card to replace. In most cases\nthis will be in the format `/cards/{index}` where `index` is the\nzero-indexed position of the card in the list of cards.", "example": "/cards/0" }, "value": { "allOf": [ { "oneOf": [ { "$ref": "#/components/schemas/KeywordSkillCard" }, { "$ref": "#/components/schemas/TimelineSkillCard" }, { "$ref": "#/components/schemas/TranscriptSkillCard" }, { "$ref": "#/components/schemas/StatusSkillCard" } ] }, { "description": "The card to insert into the list of cards at the\nposition defined by `path`." } ] } } } } } } }, "responses": { "200": { "description": "Returns the updated metadata template, with the\ncustom template data included.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCardsMetadata" } } } }, "404": { "description": "The requested file could not be found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_files_id_metadata_global_boxSkillsCards", "summary": "Remove Box Skill cards from file", "tags": [ "Skills" ], "x-box-tag": "skills", "x-box-sanitized": true, "description": "Removes any Box Skills cards metadata from a file.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Returns an empty response when the cards are\nsuccessfully deleted." }, "404": { "description": "Returns an error when the file does not have an instance of the Box Skill\ncards applied to it, or when the user does not have access to the file.\n\n* `instance_not_found` - An instance of the metadata template for Box\nSkill cards was not found on this file.\n* `not_found` - The file was not found, or the user does not have access\nto the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned when the method was not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/files/{file_id}/watermark": { "get": { "operationId": "get_files_id_watermark", "summary": "Get watermark on file", "tags": [ "Watermarks (Files)" ], "x-box-tag": "file_watermarks", "description": "Retrieve the watermark for a file.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns an object containing information about the\nwatermark associated for to this file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Watermark" } } } }, "404": { "description": "Returns an error if the file does not have a watermark applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "put": { "operationId": "put_files_id_watermark", "summary": "Apply watermark to file", "tags": [ "Watermarks (Files)" ], "x-box-tag": "file_watermarks", "description": "Applies or update a watermark on a file.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "watermark" ], "properties": { "watermark": { "type": "object", "description": "The watermark to imprint on the file", "required": [ "imprint" ], "properties": { "imprint": { "type": "string", "example": "default", "description": "The type of watermark to apply.\n\nCurrently only supports one option.", "enum": [ "default" ] } } } } } } } }, "responses": { "200": { "description": "Returns an updated watermark if a watermark already\nexisted on this file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Watermark" } } } }, "201": { "description": "Returns a new watermark if no watermark existed on\nthis file yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Watermark" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_files_id_watermark", "summary": "Remove watermark from file", "tags": [ "Watermarks (Files)" ], "x-box-tag": "file_watermarks", "description": "Removes the watermark from a file.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Removes the watermark and returns an empty response." }, "404": { "description": "Returns an error if the file did not have\na watermark applied to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/file_requests/{file_request_id}": { "get": { "operationId": "get_file_requests_id", "summary": "Get file request", "tags": [ "File requests" ], "x-box-tag": "file_requests", "x-box-enable-explorer": true, "description": "Retrieves the information about a file request.", "parameters": [ { "name": "file_request_id", "description": "The unique identifier that represent a file request.\n\nThe ID for any file request can be determined\nby visiting a file request builder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/filerequest/123`\nthe `file_request_id` is `123`.", "example": "123", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a file request object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileRequest" } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file request is not found, or the user does not\nhave access to the associated folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `file_request_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "put": { "operationId": "put_file_requests_id", "summary": "Update file request", "tags": [ "File requests" ], "x-box-tag": "file_requests", "x-box-enable-explorer": true, "x-box-sanitized": true, "description": "Updates a file request. This can be used to activate or\ndeactivate a file request.", "parameters": [ { "name": "file_request_id", "description": "The unique identifier that represent a file request.\n\nThe ID for any file request can be determined\nby visiting a file request builder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/filerequest/123`\nthe `file_request_id` is `123`.", "example": "123", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "if-match", "description": "Ensures this item hasn't recently changed before\nmaking changes.\n\nPass in the item's last observed `etag` value\ninto this header and the endpoint will fail\nwith a `412 Precondition Failed` if it\nhas changed since.", "in": "header", "required": false, "example": "1", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileRequestUpdateRequest" } } } }, "responses": { "200": { "description": "Returns the updated file request object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileRequest" } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned if the user does not have all the permissions to complete the\nupdate.\n\n* `access_denied_insufficient_permissions` when the authenticated user\ndoes not have access to update the file request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file request is not found, or the user does not\nhave access to the associated folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `file_request_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the file request. This indicates that the\nfile request has changed since it was last requested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_file_requests_id", "summary": "Delete file request", "tags": [ "File requests" ], "x-box-tag": "file_requests", "x-box-sanitized": true, "description": "Deletes a file request permanently.", "parameters": [ { "name": "file_request_id", "description": "The unique identifier that represent a file request.\n\nThe ID for any file request can be determined\nby visiting a file request builder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/filerequest/123`\nthe `file_request_id` is `123`.", "example": "123", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Returns an empty response when the file request has been successfully\ndeleted." }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file request is not found or has already been deleted,\nor the user does not have access to the associated folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `file_request_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/file_requests/{file_request_id}/copy": { "post": { "operationId": "post_file_requests_id_copy", "summary": "Copy file request", "tags": [ "File requests" ], "x-box-tag": "file_requests", "x-box-enable-explorer": true, "x-box-sanitized": true, "description": "Copies an existing file request that is already present on one folder,\nand applies it to another folder.", "parameters": [ { "name": "file_request_id", "description": "The unique identifier that represent a file request.\n\nThe ID for any file request can be determined\nby visiting a file request builder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/filerequest/123`\nthe `file_request_id` is `123`.", "example": "123", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileRequestCopyRequest" } } } }, "responses": { "200": { "description": "Returns updated file request object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileRequest" } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned if the user does not have all the permissions to complete the\nupdate.\n\n* `access_denied_insufficient_permissions` when the authenticated user\ndoes not have access to update the file request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file request is not found, or the user does not\nhave access to the associated folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `file_request_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/folders/{folder_id}": { "get": { "operationId": "get_folders_id", "summary": "Get folder information", "tags": [ "Folders" ], "x-box-tag": "folders", "x-box-enable-explorer": true, "x-box-sanitized": true, "description": "Retrieves details for a folder, including the first 100 entries\nin the folder.\n\nTo fetch more items within the folder, please use the\n[Get items in a folder](#get-folders-id-items) endpoint.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string", "nullable": false } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.\n\nAdditionally this field can be used to query any metadata\napplied to the file by specifying the `metadata` field as well\nas the scope and key of the template to retrieve, for example\n`?field=metadata.enterprise_12345.contractTemplate`.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "if-none-match", "description": "Ensures an item is only returned if it has changed.\n\nPass in the item's last observed `etag` value\ninto this header and the endpoint will fail\nwith a `304 Not Modified` if the item has not\nchanged since.", "in": "header", "required": false, "example": "1", "schema": { "type": "string" } }, { "name": "boxapi", "description": "The URL, and optional password, for the shared link of this item.\n\nThis header can be used to access items that have not been\nexplicitly shared with a user.\n\nUse the format `shared_link=[link]` or if a password is required then\nuse `shared_link=[link]&shared_link_password=[password]`.\n\nThis header can be used on the file or folder shared, as well as on any files\nor folders nested within the item.", "example": "shared_link=[link]&shared_link_password=[password]", "in": "header", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a folder, including the first 100 entries in the folder.\n\nTo fetch more items within the folder, please use the\n[Get items in a folder](#get-folders-id-items) endpoint.\n\nNot all available fields are returned by default. Use the\n[fields](#param-fields) query parameter to explicitly request\nany specific fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder--Full" } } } }, "304": { "description": "Returns an empty response when the `If-None-Match` header matches\nthe current `etag` value of the folder. This indicates that the folder\nhas not changed since it was last requested." }, "403": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the folder is not found, or the user does not\nhave access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `folder_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_folders_id", "summary": "Restore folder", "tags": [ "Trashed folders" ], "x-box-tag": "trashed_folders", "description": "Restores a folder that has been moved to the trash.\n\nAn optional new parent ID can be provided to restore the folder to in case the\noriginal folder has been deleted.\n\n# Folder locking\n\nDuring this operation, part of the file tree will be locked, mainly\nthe source folder and all of its descendants, as well as the destination\nfolder.\n\nFor the duration of the operation, no other move, copy, delete, or restore\noperation can performed on any of the locked folders.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string", "nullable": false } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "An optional new name for the folder.", "example": "Restored Photos", "type": "string" }, "parent": { "allOf": [ { "type": "object", "description": "The parent for this item", "properties": { "id": { "type": "string", "description": "The ID of parent item", "example": "123" } } }, { "description": "Specifies an optional ID of a folder to restore the folder\nto when the original folder no longer exists.\n\nPlease be aware that this ID will only be used if the original\nfolder no longer exists. Use this ID to provide a fallback\nlocation to restore the folder to if the original location\nhas been deleted." } ] } } } } } }, "responses": { "201": { "description": "Returns a folder object when the folder has been restored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrashFolderRestored" } } } }, "403": { "description": "Returns an error if the user does not have access to the folder\nthe folder is being restored to, or the user does not have permission\nto restore folders from the trash.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the folder is not in the trash.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "* Returned an error if there is a folder with the same name\n in the destination folder.\n\n* `operation_blocked_temporary`: Returned if either of the destination\n or source folders is locked due to another move, copy, delete or\n restore operation in process.\n\n The operation can be retried at a later point.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "put": { "operationId": "put_folders_id", "summary": "Update folder", "description": "Updates a folder. This can be also be used to move the folder,\ncreate shared links, update collaborations, and more.", "tags": [ "Folders" ], "x-box-tag": "folders", "x-box-sanitized": true, "x-box-enable-explorer": true, "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string", "nullable": false } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "if-match", "description": "Ensures this item hasn't recently changed before\nmaking changes.\n\nPass in the item's last observed `etag` value\ninto this header and the endpoint will fail\nwith a `412 Precondition Failed` if it\nhas changed since.", "in": "header", "required": false, "example": "1", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The optional new name for this folder.", "example": "New Folder" }, "description": { "type": "string", "description": "The optional description of this folder", "maxLength": 256, "example": "Legal contracts for the new ACME deal", "nullable": false }, "sync_state": { "type": "string", "example": "synced", "nullable": false, "description": "Specifies whether a folder should be synced to a\nuser's device or not. This is used by Box Sync\n(discontinued) and is not used by Box Drive.", "enum": [ "synced", "not_synced", "partially_synced" ] }, "can_non_owners_invite": { "type": "boolean", "example": true, "description": "Specifies if users who are not the owner\nof the folder can invite new collaborators to the folder." }, "parent": { "type": "object", "description": "The parent folder for this folder. Use this to move\nthe folder or to restore it out of the trash.", "properties": { "id": { "type": "string", "description": "The ID of the new parent folder", "example": "0" } } }, "shared_link": { "allOf": [ { "description": "Defines a shared link for an item. Set this to `null` to remove\nthe shared link.", "type": "object", "properties": { "access": { "type": "string", "description": "The level of access for the shared link. This can be\nrestricted to anyone with the link (`open`), only people\nwithin the company (`company`) and only those who\nhave been invited to the folder (`collaborators`).\n\nIf not set, this field defaults to the access level specified\nby the enterprise admin. To create a shared link with this\ndefault setting pass the `shared_link` object with\nno `access` field, for example `{ \"shared_link\": {} }`.\n\nThe `company` access level is only available to paid\naccounts.", "enum": [ "open", "company", "collaborators" ], "example": "open" }, "password": { "type": "string", "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\n\nA password can only be set when `access` is set to `open`.", "example": "do-not-use-this-password" }, "vanity_name": { "type": "string", "description": "Defines a custom vanity name to use in the shared link URL,\nfor example `https://app.box.com/v/my-shared-link`.\n\nCustom URLs should not be used when sharing sensitive content\nas vanity URLs are a lot easier to guess than regular shared links.", "example": "my-shared-link" }, "unshared_at": { "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "description": "The timestamp at which this shared link will\nexpire. This field can only be set by\nusers with paid accounts." }, "permissions": { "type": "object", "properties": { "can_download": { "type": "boolean", "example": true, "description": "If the shared link allows for downloading of files.\nThis can only be set when `access` is set to\n`open` or `company`." } } } } }, { "description": "Enables the creation of a shared link for a folder." } ] }, "folder_upload_email": { "allOf": [ { "title": "Folder upload email", "type": "object", "description": "The Write Folder Upload Email object", "properties": { "access": { "type": "string", "example": "open", "nullable": false, "enum": [ "open", "collaborators" ], "description": "When this parameter has been set, users can email files\nto the email address that has been automatically\ncreated for this folder.\n\nTo create an email address, set this property either when\ncreating or updating the folder.\n\nWhen set to `collaborators`, only emails from registered email\naddresses for collaborators will be accepted. This includes\nany email aliases a user might have registered.\n\nWhen set to `open` it will accept emails from any email\naddress." } } }, { "description": "Setting this object enables the upload email address.\n\nThis email address can be used by users to directly\nupload files directly to the folder via email.\n\nSetting the value to `null` will disable the email address." } ] }, "tags": { "type": "array", "example": [ "approved" ], "items": { "type": "string" }, "minItems": 1, "maxItems": 100, "description": "The tags for this item. These tags are shown in\nthe Box web app and mobile apps next to an item.\n\nTo add or remove a tag, retrieve the item's current tags,\nmodify them, and then update this field.\n\nThere is a limit of 100 tags per item, and 10,000\nunique tags per enterprise." }, "is_collaboration_restricted_to_enterprise": { "type": "boolean", "example": true, "description": "Specifies if new invites to this folder are restricted to users\nwithin the enterprise. This does not affect existing\ncollaborations." }, "collections": { "type": "array", "description": "An array of collections to make this folder\na member of. Currently\nwe only support the `favorites` collection.\n\nTo get the ID for a collection, use the\n[List all collections][1] endpoint.\n\nPassing an empty array `[]` or `null` will remove\nthe folder from all collections.\n\n[1]: ../advanced-files-and-folders/#get-collections", "items": { "title": "Reference", "description": "The bare basic reference for an object", "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for this object", "example": "11446498" }, "type": { "type": "string", "description": "The type for this object", "example": "file" } } } }, "can_non_owners_view_collaborators": { "type": "boolean", "example": true, "description": "Restricts collaborators who are not the owner of\nthis folder from viewing other collaborations on\nthis folder.\n\nIt also restricts non-owners from inviting new\ncollaborators.\n\nWhen setting this field to `false`, it is required\nto also set `can_non_owners_invite_collaborators` to\n`false` if it has not already been set." } } } } } }, "responses": { "200": { "description": "Returns a folder object for the updated folder\n\nNot all available fields are returned by default. Use the\n[fields](#param-fields) query parameter to explicitly request\nany specific fields.\n\nThis call will return synchronously. This holds true even when\nmoving folders with a large a large number of items in all of its\ndescendants. For very large folders, this means the call could\ntake minutes or hours to return.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder--Full" } } } }, "400": { "description": "Returns an error if some of the parameters are missing or\nnot valid, or if a folder lock is preventing a move operation.\n\n* `bad_request` when a parameter is missing or incorrect. This error also\n happens when a password is set for a shared link with an access type\n of `open`.\n* `item_name_too_long` when the folder name is too long.\n* `item_name_invalid` when the folder name contains\n non-valid characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error if the user does not have the required\naccess to perform the action.\n\n* `access_denied_insufficient_permissions`: Returned when the\n user does not have access to the folder or parent folder, or if the\n folder is being moved and a folder lock has been applied to prevent\n such operations.\n\n* `insufficient_scope`: Returned an error if the application\n does not have the right scope to update folders. Make sure\n your application has been configured to read and write all files\n and folders stored in Box.\n\n* `forbidden`: Returned when the user is not allowed to perform this\n action for other users. This can include trying to create a\n Shared Link with a `company` access level on a free account.\n\n* `forbidden_by_policy`: Returned if copying a folder is\n forbidden due to information barrier restrictions.\n\nReturns an error if there are too many actions in the request body.\n\n* `operation_limit_exceeded`: Returned when the user passes any\nparameters in addition to the `parent.id` in the request body.\nThe calls to this endpoint have to be split up.\nThe first call needs to include only the `parent.id`,\nthe next call can include other parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the folder or parent folder could not be found,\nor the authenticated user does not have access to either folder.\n\n* `not_found` when the authenticated user does not have access\n to the folder or parent folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "* `operation_blocked_temporary`: Returned if either of the destination\n or source folders is locked due to another move, copy, delete or\n restore operation in progress.\n\n The operation can be retried at a later point.\n\n* `item_name_in_use`: Returned if a folder with the name\n already exists in the parent folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the folder. This indicates that the\nfolder has changed since it was last requested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "503": { "description": "Returns an error when the operation takes longer\nthan 60 seconds. The operation will continue after\nthis response has been returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_folders_id", "summary": "Delete folder", "description": "Deletes a folder, either permanently or by moving it to\nthe trash.", "tags": [ "Folders" ], "x-box-tag": "folders", "x-box-sanitized": true, "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string", "nullable": false } }, { "name": "if-match", "description": "Ensures this item hasn't recently changed before\nmaking changes.\n\nPass in the item's last observed `etag` value\ninto this header and the endpoint will fail\nwith a `412 Precondition Failed` if it\nhas changed since.", "in": "header", "required": false, "example": "1", "schema": { "type": "string" } }, { "name": "recursive", "description": "Delete a folder that is not empty by recursively deleting the\nfolder and all of its content.", "in": "query", "required": false, "example": true, "schema": { "type": "boolean" } } ], "responses": { "204": { "description": "Returns an empty response when the folder is successfully deleted\nor moved to the trash." }, "400": { "description": "Returns an error if the user makes a bad request.\n\n* `folder_not_empty`: Returned if the folder is not empty. Use the\n `recursive` query parameter to recursively delete the folder and\n its contents.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error if the user does not have the required\naccess to perform the action.\n\n* `access_denied_insufficient_permissions`: Returned when the\n user does not have access to the folder, or when a folder lock has been\n applied to the folder to prevent deletion.\n\n* `insufficient_scope`: Returned an error if the application\n does not have the right scope to delete folders. Make sure\n your application has been configured to read and write all files\n and folders stored in Box.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the folder could not be found,\nor the authenticated user does not have access to the folder.\n\n* `not_found` when the authenticated user does not have access\n to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "* `operation_blocked_temporary`: Returned if the folder\n is locked due to another move, copy, delete or restore\n operation in progress.\n\n The operation can be retried at a later point.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the folder. This indicates that the\nfolder has changed since it was last requested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "503": { "description": "Returns an error when the operation takes longer\nthan 60 seconds. The operation will continue after\nthis response has been returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/folders/{folder_id}/items": { "get": { "operationId": "get_folders_id_items", "summary": "List items in folder", "tags": [ "Folders" ], "x-box-tag": "folders", "x-box-sanitized": true, "x-box-enable-explorer": true, "description": "Retrieves a page of items in a folder. These items can be files,\nfolders, and web links.\n\nTo request more information about the folder itself, like its size,\nplease use the [Get a folder](#get-folders-id) endpoint instead.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string", "nullable": false } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.\n\nAdditionally this field can be used to query any metadata\napplied to the file by specifying the `metadata` field as well\nas the scope and key of the template to retrieve, for example\n`?field=metadata.enterprise_12345.contractTemplate`.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "usemarker", "description": "Specifies whether to use marker-based pagination instead of\noffset-based pagination. Only one pagination method can\nbe used at a time.\n\nBy setting this value to true, the API will return a `marker` field\nthat can be passed as a parameter to this endpoint to get the next\npage of the response.", "in": "query", "required": false, "example": true, "schema": { "type": "boolean" } }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } }, { "name": "offset", "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } }, { "name": "boxapi", "description": "The URL, and optional password, for the shared link of this item.\n\nThis header can be used to access items that have not been\nexplicitly shared with a user.\n\nUse the format `shared_link=[link]` or if a password is required then\nuse `shared_link=[link]&shared_link_password=[password]`.\n\nThis header can be used on the file or folder shared, as well as on any files\nor folders nested within the item.", "example": "shared_link=[link]&shared_link_password=[password]", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "sort", "description": "Defines the **second** attribute by which items\nare sorted.\n\nItems are always sorted by their `type` first, with\nfolders listed before files, and files listed\nbefore web links.\n\nThis parameter is not supported for marker-based pagination\non the root folder (the folder with an ID of `0`).", "in": "query", "required": false, "example": "id", "schema": { "type": "string", "enum": [ "id", "name", "date", "size" ] } }, { "name": "direction", "description": "The direction to sort results in. This can be either in alphabetical ascending\n(`ASC`) or descending (`DESC`) order.", "in": "query", "required": false, "example": "ASC", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] } } ], "responses": { "200": { "description": "Returns a collection of files, folders, and web links contained in a folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Items" } } } }, "403": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the folder is not found, or the user does not\nhave access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `folder_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/folders": { "post": { "operationId": "post_folders", "summary": "Create folder", "tags": [ "Folders" ], "x-box-tag": "folders", "x-box-enable-explorer": true, "description": "Creates a new empty folder within the specified parent folder.", "parameters": [ { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "parent" ], "properties": { "name": { "type": "string", "description": "The name for the new folder.\n\nThere are some restrictions to the file name. Names containing\nnon-printable ASCII characters, forward and backward slashes\n(`/`, `\\`), as well as names with trailing spaces are\nprohibited.\n\nAdditionally, the names `.` and `..` are\nnot allowed either.", "example": "New Folder", "maxLength": 255, "minLength": 1 }, "parent": { "type": "object", "description": "The parent folder to create the new folder within.", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The ID of parent folder", "example": "0" } } }, "folder_upload_email": { "allOf": [ { "title": "Folder upload email", "type": "object", "description": "The Write Folder Upload Email object", "properties": { "access": { "type": "string", "example": "open", "nullable": false, "enum": [ "open", "collaborators" ], "description": "When this parameter has been set, users can email files\nto the email address that has been automatically\ncreated for this folder.\n\nTo create an email address, set this property either when\ncreating or updating the folder.\n\nWhen set to `collaborators`, only emails from registered email\naddresses for collaborators will be accepted. This includes\nany email aliases a user might have registered.\n\nWhen set to `open` it will accept emails from any email\naddress." } } }, { "description": "Setting this object enables the upload email address.\n\nThis email address can be used by users to directly\nupload files directly to the folder via email." } ] }, "sync_state": { "type": "string", "example": "synced", "nullable": false, "description": "Specifies whether a folder should be synced to a\nuser's device or not. This is used by Box Sync\n(discontinued) and is not used by Box Drive.", "enum": [ "synced", "not_synced", "partially_synced" ] } } } } } }, "responses": { "201": { "description": "Returns a folder object.\n\nNot all available fields are returned by default. Use the\n[fields](#param-fields) query parameter to explicitly request\nany specific fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder--Full" } } } }, "400": { "description": "Returns an error if some of the parameters are missing or\nnot valid.\n\n* `bad_request` when a parameter is missing or incorrect.\n* `item_name_too_long` when the folder name is too long.\n* `item_name_invalid` when the folder name contains\n non-valid characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error if the user does not have the required\naccess to perform the action. This might be because they\ndon't have access to the folder or parent folder, or because\nthe application does not have permission to write files and\nfolders.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the parent folder could not be found,\nor the authenticated user does not have access to the parent\nfolder.\n\n* `not_found` when the authenticated user does not have access\n to the parent folder", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "* `operation_blocked_temporary`: Returned if either of the destination\n or source folders is locked due to another move, copy, delete or\n restore operation in process.\n\n The operation can be retried at a later point.\n\n* `item_name_in_use`: Returned if a folder with the name\n already exists in the parent folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/folders/{folder_id}/copy": { "post": { "operationId": "post_folders_id_copy", "summary": "Copy folder", "x-box-enable-explorer": true, "x-box-tag": "folders", "description": "Creates a copy of a folder within a destination folder.\n\nThe original folder will not be changed.", "tags": [ "Folders" ], "parameters": [ { "name": "folder_id", "description": "The unique identifier of the folder to copy.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder with the ID `0` can not be copied.", "example": "0", "in": "path", "required": true, "schema": { "type": "string", "nullable": false } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "parent" ], "nullable": false, "properties": { "name": { "type": "string", "description": "An optional new name for the copied folder.\n\nThere are some restrictions to the file name. Names containing\nnon-printable ASCII characters, forward and backward slashes\n(`/`, `\\`), as well as names with trailing spaces are\nprohibited.\n\nAdditionally, the names `.` and `..` are\nnot allowed either.", "example": "New Folder", "maxLength": 255, "minLength": 1 }, "parent": { "type": "object", "description": "The destination folder to copy the folder to.", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The ID of parent folder", "example": "0" } } } } } } } }, "responses": { "201": { "description": "Returns a new folder object representing the copied folder.\n\nNot all available fields are returned by default. Use the\n[fields](#param-fields) query parameter to explicitly request\nany specific fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder--Full" } } } }, "304": { "description": "Returns an empty response when the `If-None-Match` header matches\nthe current `etag` value of the folder. This indicates that the folder\nhas not changed since it was last requested." }, "400": { "description": "Returns an error if some of the parameters are missing or\nnot valid.\n\n* `bad_request` when a parameter is missing.\n* `item_name_too_long` when the new folder name is too long.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error when the user does not have the\nright permissions to copy a folder.\n\n* `forbidden_by_policy`: Returned if copying a folder is\nforbidden due to information barrier restrictions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if either the source or destination folder\ncould not be found, or the authenticated user does not\nhave access to either folders.\n\n* `not_found` when the authenticated user does not have access\n to the parent folder", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error if a folder by this name already exists\nin the destination folder, or if the destination folder\nis locked.\n\n* `item_name_in_use` when a folder with the same name already\n exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "500": { "description": "Returns an error when trying to copy the root folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/folders/{folder_id}/collaborations": { "get": { "operationId": "get_folders_id_collaborations", "summary": "List folder collaborations", "description": "Retrieves a list of pending and active collaborations for a\nfolder. This returns all the users that have access to the folder\nor have been invited to the folder.", "tags": [ "Collaborations (List)" ], "x-box-tag": "list_collaborations", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string", "nullable": false } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Returns a collection of collaboration objects. If there are no\ncollaborations on this folder an empty collection will be returned.\n\nThis list includes pending collaborations, for which the `status`\nis set to `pending`, indicating invitations that have been sent but not\nyet accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collaborations" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/folders/{folder_id}/trash": { "get": { "operationId": "get_folders_id_trash", "summary": "Get trashed folder", "tags": [ "Trashed folders" ], "x-box-tag": "trashed_folders", "description": "Retrieves a folder that has been moved to the trash.\n\nPlease note that only if the folder itself has been moved to the\ntrash can it be retrieved with this API call. If instead one of\nits parent folders was moved to the trash, only that folder\ncan be inspected using the\n[`GET /folders/:id/trash`](e://get_folders_id_trash) API.\n\nTo list all items that have been moved to the trash, please\nuse the [`GET /folders/trash/items`](e://get-folders-trash-items/)\nAPI.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string", "nullable": false } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Returns the folder that was trashed,\nincluding information about when the it\nwas moved to the trash.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrashFolder" } } } }, "404": { "description": "Returns an error if the folder can not be found directly\nin the trash.\n\nPlease note that a `HTTP 404` is also returned if any of\nthe folder's parent folders have been moved to the trash.\n\nIn that case, only that parent folder can be inspected using\nthe [`GET /folders/:id/trash`](e://get_folders_id_trash) API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_folders_id_trash", "summary": "Permanently remove folder", "tags": [ "Trashed folders" ], "x-box-tag": "trashed_folders", "description": "Permanently deletes a folder that is in the trash.\nThis action cannot be undone.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string", "nullable": false } } ], "responses": { "204": { "description": "Returns an empty response when the folder was\npermanently deleted." }, "404": { "description": "Returns an error if the folder is not in the trash.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/folders/{folder_id}/metadata": { "get": { "operationId": "get_folders_id_metadata", "summary": "List metadata instances on folder", "tags": [ "Metadata instances (Folders)" ], "x-box-tag": "folder_metadata", "x-box-sanitized": true, "description": "Retrieves all metadata for a given folder. This can not be used on the root\nfolder with ID `0`.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string", "nullable": false } } ], "responses": { "200": { "description": "Returns all the metadata associated with a folder.\n\nThis API does not support pagination and will therefore always return\nall of the metadata associated to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metadatas" } } } }, "403": { "description": "Returned when the request parameters are not valid.\n\n* `forbidden` - this operation is not allowed on the Root folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the user does not have access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/folders/{folder_id}/metadata/enterprise/securityClassification-6VMVochwUWo": { "get": { "operationId": "get_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo", "summary": "Get classification on folder", "tags": [ "Classifications on folders" ], "x-box-tag": "folder_classifications", "x-box-sanitized": true, "description": "Retrieves the classification metadata instance that\nhas been applied to a folder.\n\nThis API can also be called by including the enterprise ID in the\nURL explicitly, for example\n`/folders/:id//enterprise_12345/securityClassification-6VMVochwUWo`.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string", "nullable": false } } ], "responses": { "201": { "description": "Returns an instance of the `securityClassification` metadata\ntemplate, which contains a `Box__Security__Classification__Key`\nfield that lists all the classifications available to this\nenterprise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Classification" } } } }, "403": { "description": "Returned when the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the metadata template specified\nwas not applied to this folder or the user does not have access to the\nfolder.\n\n* `instance_not_found` - The metadata template was not applied to the\nfolder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned when the method was not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo", "summary": "Add classification to folder", "tags": [ "Classifications on folders" ], "x-box-tag": "folder_classifications", "x-box-sanitized": true, "description": "Adds a classification to a folder by specifying the label of the\nclassification to add.\n\nThis API can also be called by including the enterprise ID in the\nURL explicitly, for example\n`/folders/:id//enterprise_12345/securityClassification-6VMVochwUWo`.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string", "nullable": false } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Box__Security__Classification__Key": { "type": "string", "description": "The name of the classification to apply to this folder.\n\nTo list the available classifications in an enterprise,\nuse the classification API to retrieve the\n[classification template](e://get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema)\nwhich lists all available classification keys.", "example": "Sensitive" } } } } } }, "responses": { "201": { "description": "Returns the classification template instance\nthat was applied to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Classification" } } } }, "400": { "description": "Returns an error when the request body is not valid.\n\n* `schema_validation_failed` - The request body contains a value for a for\na field that either does not exist, or for which the value or type does\nnot match the expected field type. An example might be an unknown option\nfor an `enum` or `multiSelect` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the folder or metadata template was not found.\n\n* `not_found` - The folder could not be found, or the user does not have\naccess to the folder.\n* `instance_tuple_not_found` - The metadata template was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error when an instance of this metadata template is already\npresent on the folder.\n\n* `tuple_already_exists` - An instance of them metadata template already\nexists on the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "put": { "operationId": "put_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo", "summary": "Update classification on folder", "tags": [ "Classifications on folders" ], "x-box-tag": "folder_classifications", "x-box-sanitized": true, "description": "Updates a classification on a folder.\n\nThe classification can only be updated if a classification has already been\napplied to the folder before. When editing classifications, only values are\ndefined for the enterprise will be accepted.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string", "nullable": false } } ], "requestBody": { "content": { "application/json-patch+json": { "schema": { "description": "A list containing the one change to make, to\nupdate the classification label.", "type": "array", "items": { "type": "object", "description": "The operation to perform on the classification\nmetadata template instance. In this case, it use\nused to replace the value stored for the\n`Box__Security__Classification__Key` field with a new\nvalue.", "properties": { "op": { "type": "string", "example": "replace", "description": "`replace`", "enum": [ "replace" ] }, "path": { "type": "string", "example": "/Box__Security__Classification__Key", "description": "`/Box__Security__Classification__Key`", "enum": [ "/Box__Security__Classification__Key" ] }, "value": { "type": "string", "description": "The name of the classification to apply to this folder.\n\nTo list the available classifications in an enterprise,\nuse the classification API to retrieve the\n[classification template](e://get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema)\nwhich lists all available classification keys.", "example": "Sensitive" } } } } } } }, "responses": { "200": { "description": "Returns the updated classification metadata template instance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Classification" } } } }, "400": { "description": "Returns an error when the request body is not valid.\n\n* `bad_request` - The request body format is not an array of valid JSON\nPatch operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "500": { "description": "Returns an error in some edge cases when the request body is not a valid\narray of JSON Patch items.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo", "summary": "Remove classification from folder", "tags": [ "Classifications on folders" ], "x-box-tag": "folder_classifications", "x-box-sanitized": true, "description": "Removes any classifications from a folder.\n\nThis API can also be called by including the enterprise ID in the\nURL explicitly, for example\n`/folders/:id//enterprise_12345/securityClassification-6VMVochwUWo`.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string", "nullable": false } } ], "responses": { "204": { "description": "Returns an empty response when the classification is\nsuccessfully deleted." }, "400": { "description": "Returned when the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the folder does not have any classification applied\nto it, or when the user does not have access to the\nfolder.\n\n* `instance_not_found` - An instance of the classification metadata\ntemplate with the was not found on this folder.\n* `not_found` - The folder was not found, or the user does not have access\nto the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned when the method was not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/folders/{folder_id}/metadata/{scope}/{template_key}": { "get": { "operationId": "get_folders_id_metadata_id_id", "summary": "Get metadata instance on folder", "tags": [ "Metadata instances (Folders)" ], "x-box-tag": "folder_metadata", "x-box-sanitized": true, "description": "Retrieves the instance of a metadata template that has been applied to a\nfolder. This can not be used on the root folder with ID `0`.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string", "nullable": false } }, { "name": "scope", "description": "The scope of the metadata template", "example": "global", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "global", "enterprise" ] } }, { "name": "template_key", "description": "The name of the metadata template", "example": "properties", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "An instance of the metadata template that includes\nadditional \"key:value\" pairs defined by the user or\nan application.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metadata" } } } }, "403": { "description": "Returned when the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the metadata template specified\nwas not applied to this folder or the user does not have access to the\nfolder.\n\n* `instance_not_found` - The metadata template was not applied to the\nfolder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned when the method was not allowed. This often happens when the\nfolder ID is not valid or the root folder with ID `0`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_folders_id_metadata_id_id", "summary": "Create metadata instance on folder", "tags": [ "Metadata instances (Folders)" ], "x-box-tag": "folder_metadata", "x-box-sanitized": true, "x-box-enable-explorer": false, "description": "Applies an instance of a metadata template to a folder.\n\nIn most cases only values that are present in the metadata template\nwill be accepted, except for the `global.properties` template which accepts\nany key-value pair.\n\nTo display the metadata template in the Box web app the enterprise needs to be\nconfigured to enable **Cascading Folder Level Metadata** for the user in the\nadmin console.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string", "nullable": false } }, { "name": "scope", "description": "The scope of the metadata template", "example": "global", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "global", "enterprise" ] } }, { "name": "template_key", "description": "The name of the metadata template", "example": "properties", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "name": "Aaron Levie" }, "additionalProperties": { "type": "string", "description": "A value for each of the fields that are present on the metadata\ntemplate.\n\nFor the `global.properties` template this can be an a list of zero\nor more fields, as this template allows for any generic key-value\npairs to be stored on the template.", "example": "Aaron Levie", "x-box-example-key": "name" } } } } }, "responses": { "201": { "description": "Returns the instance of the template that was applied to the folder,\nincluding the data that was applied to the template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metadata" } } } }, "400": { "description": "Returns an error when the request body is not valid.\n\n* `schema_validation_failed` - The request body contains a value for\na field that either does not exist, or for which the value or type does\nnot match the expected field type. An example might be an unknown option\nfor an `enum` or `multiSelect` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the folder or metadata template was not found.\n\n* `not_found` - The folder could not be found, or the user does not have\naccess to the folder.\n* `instance_tuple_not_found` - The metadata template was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error when an instance of this metadata template is already\npresent on the folder.\n\n* `tuple_already_exists` - An instance of them metadata template already\nexists on the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "put": { "operationId": "put_folders_id_metadata_id_id", "summary": "Update metadata instance on folder", "tags": [ "Metadata instances (Folders)" ], "x-box-tag": "folder_metadata", "x-box-sanitized": true, "description": "Updates a piece of metadata on a folder.\n\nThe metadata instance can only be updated if the template has already been\napplied to the folder before. When editing metadata, only values that match\nthe metadata template schema will be accepted.\n\nThe update is applied atomically. If any errors occur during the\napplication of the operations, the metadata instance will not be changed.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string", "nullable": false } }, { "name": "scope", "description": "The scope of the metadata template", "example": "global", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "global", "enterprise" ] } }, { "name": "template_key", "description": "The name of the metadata template", "example": "properties", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json-patch+json": { "schema": { "description": "A [JSON-Patch](https://tools.ietf.org/html/rfc6902)\nspecification for the changes to make to the metadata\ninstance.\n\nThe changes are represented as a JSON array of\noperation objects.", "type": "array", "items": { "title": "A metadata instance update operation", "description": "A [JSON-Patch](https://tools.ietf.org/html/rfc6902) operation for a\nchange to make to the metadata instance.", "type": "object", "properties": { "op": { "type": "string", "example": "add", "enum": [ "add", "replace", "remove", "test", "move", "copy" ], "description": "The type of change to perform on the template. Some\nof these are hazardous as they will change existing templates." }, "path": { "type": "string", "example": "/currentState", "description": "The location in the metadata JSON object\nto apply the changes to, in the format of a\n[JSON-Pointer](https://tools.ietf.org/html/rfc6901).\n\nThe path must always be prefixed with a `/` to represent the root\nof the template. The characters `~` and `/` are reserved\ncharacters and must be escaped in the key." }, "value": { "type": "string", "example": "reviewed", "description": "The value to be set or tested.\n\nRequired for `add`, `replace`, and `test` operations. For `add`,\nif the value exists already the previous value will be overwritten\nby the new value. For `replace`, the value must exist before\nreplacing.\n\nFor `test`, the existing value at the `path` location must match\nthe specified value." }, "from": { "type": "string", "example": "/nextState", "description": "The location in the metadata JSON object to move or copy a value\nfrom. Required for `move` or `copy` operations and must be in the\nformat of a [JSON-Pointer](https://tools.ietf.org/html/rfc6901)." } } } } } } }, "responses": { "200": { "description": "Returns the updated metadata template instance, with the\ncustom template data included.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metadata" } } } }, "400": { "description": "Returns an error when the request body is not valid.\n\n* `bad_request` - The request body format is not an array of valid JSON\nPatch objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "500": { "description": "Returns an error in some edge cases when the request body is not a valid\narray of JSON Patch items.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_folders_id_metadata_id_id", "summary": "Remove metadata instance from folder", "tags": [ "Metadata instances (Folders)" ], "x-box-tag": "folder_metadata", "x-box-sanitized": true, "description": "Deletes a piece of folder metadata.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string", "nullable": false } }, { "name": "scope", "description": "The scope of the metadata template", "example": "global", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "global", "enterprise" ] } }, { "name": "template_key", "description": "The name of the metadata template", "example": "properties", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Returns an empty response when the metadata is\nsuccessfully deleted." }, "400": { "description": "Returned when the request parameters are not valid. This may happen of the\n`scope` is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the folder does not have an instance of the metadata\ntemplate applied to it, or when the user does not have access to the\nfolder.\n\n* `instance_not_found` - An instance of the metadata template with the\ngiven `scope` and `templateKey` was not found on this folder.\n* `not_found` - The folder was not found, or the user does not have access\nto the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned when the method was not allowed. This often happens when the\nfolder ID is not valid or the root folder with ID `0`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/folders/trash/items": { "get": { "operationId": "get_folders_trash_items", "summary": "List trashed items", "tags": [ "Trashed items" ], "x-box-tag": "trashed_items", "description": "Retrieves the files and folders that have been moved\nto the trash.\n\nAny attribute in the full files or folders objects can be passed\nin with the `fields` parameter to retrieve those specific\nattributes that are not returned by default.\n\nThis endpoint defaults to use offset-based pagination, yet also supports\nmarker-based pagination using the `marker` parameter.", "parameters": [ { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } }, { "name": "offset", "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 } }, { "name": "usemarker", "description": "Specifies whether to use marker-based pagination instead of\noffset-based pagination. Only one pagination method can\nbe used at a time.\n\nBy setting this value to true, the API will return a `marker` field\nthat can be passed as a parameter to this endpoint to get the next\npage of the response.", "in": "query", "required": false, "example": true, "schema": { "type": "boolean" } }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } }, { "name": "direction", "description": "The direction to sort results in. This can be either in alphabetical ascending\n(`ASC`) or descending (`DESC`) order.", "in": "query", "required": false, "example": "ASC", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] } }, { "name": "sort", "description": "Defines the **second** attribute by which items\nare sorted.\n\nItems are always sorted by their `type` first, with\nfolders listed before files, and files listed\nbefore web links.\n\nThis parameter is not supported when using marker-based pagination.", "in": "query", "required": false, "example": "name", "schema": { "type": "string", "enum": [ "name", "date", "size" ] } } ], "responses": { "200": { "description": "Returns a list of items that have been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Items" } } } }, "400": { "description": "Returns an error if some of the parameters are missing or\nnot valid.\n\n* `invalid_parameter` can appear when the `sort`, `direction` or `offset`\nparameter is provided when using marker based pagination, or when the\n`marker` parameter is provided but `usemarker` is set to `false` or\n`null`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/folders/{folder_id}/watermark": { "get": { "operationId": "get_folders_id_watermark", "summary": "Get watermark for folder", "tags": [ "Watermarks (Folders)" ], "x-box-tag": "folder_watermarks", "description": "Retrieve the watermark for a folder.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string", "nullable": false } } ], "responses": { "200": { "description": "Returns an object containing information about the\nwatermark associated for to this folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Watermark" } } } }, "404": { "description": "Returns an error if the folder does not have a watermark applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "put": { "operationId": "put_folders_id_watermark", "summary": "Apply watermark to folder", "tags": [ "Watermarks (Folders)" ], "x-box-tag": "folder_watermarks", "description": "Applies or update a watermark on a folder.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string", "nullable": false } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "watermark" ], "properties": { "watermark": { "type": "object", "description": "The watermark to imprint on the folder", "required": [ "imprint" ], "properties": { "imprint": { "type": "string", "example": "default", "description": "The type of watermark to apply.\n\nCurrently only supports one option.", "enum": [ "default" ] } } } } } } } }, "responses": { "200": { "description": "Returns an updated watermark if a watermark already\nexisted on this folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Watermark" } } } }, "201": { "description": "Returns a new watermark if no watermark existed on\nthis folder yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Watermark" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_folders_id_watermark", "summary": "Remove watermark from folder", "tags": [ "Watermarks (Folders)" ], "x-box-tag": "folder_watermarks", "description": "Removes the watermark from a folder.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string", "nullable": false } } ], "responses": { "204": { "description": "An empty response will be returned when the watermark\nwas successfully deleted." }, "404": { "description": "Returns an error if the folder did not have\na watermark applied to it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/folder_locks": { "get": { "operationId": "get_folder_locks", "summary": "List folder locks", "tags": [ "Folder Locks" ], "x-box-tag": "folder_locks", "x-box-sanitized": true, "x-box-enable-explorer": true, "description": "Retrieves folder lock details for a given folder.\n\nYou must be authenticated as the owner or co-owner of the folder to\nuse this endpoint.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "example": "12345", "in": "query", "required": true, "schema": { "type": "string", "nullable": false } } ], "responses": { "200": { "description": "Returns details for all folder locks applied to the folder, including the\nlock type and user that applied the lock.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderLocks" } } } }, "403": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the folder is not found, or the user does not\nhave access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `folder_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_folder_locks", "summary": "Create folder lock", "tags": [ "Folder Locks" ], "x-box-tag": "folder_locks", "x-box-sanitized": true, "x-box-enable-explorer": false, "description": "Creates a folder lock on a folder, preventing it from being moved and/or\ndeleted.\n\nYou must be authenticated as the owner or co-owner of the folder to\nuse this endpoint.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "folder" ], "properties": { "locked_operations": { "type": "object", "description": "The operations to lock for the folder. If `locked_operations` is\nincluded in the request, both `move` and `delete` must also be\nincluded and both set to `true`.", "required": [ "move", "delete" ], "properties": { "move": { "type": "boolean", "description": "Whether moving the folder should be locked.", "example": true }, "delete": { "type": "boolean", "description": "Whether deleting the folder should be locked.", "example": true } } }, "folder": { "type": "object", "description": "The folder to apply the lock to.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "The content type the lock is being applied to. Only `folder`\nis supported.", "example": "folder" }, "id": { "type": "string", "description": "The ID of the folder.", "example": "1234567890" } } } } } } } }, "responses": { "200": { "description": "Returns the instance of the folder lock that was applied to the folder,\nincluding the user that applied the lock and the operations set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderLock" } } } }, "400": { "description": "Returns an error when the request body is not valid.\n\n* `schema_validation_failed` - The request body contains a value for\na field that either does not exist, or for which the value or type does\nnot match the expected field type. An example might be an unknown option\nfor an `enum` or `multiSelect` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the folder was not found.\n\n* `not_found` - The folder could not be found, the user does not have\naccess to the folder, or the user making call is not an owner or co-owner\nof folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/folder_locks/{folder_lock_id}": { "delete": { "operationId": "delete_folder_locks_id", "summary": "Delete folder lock", "description": "Deletes a folder lock on a given folder.\n\nYou must be authenticated as the owner or co-owner of the folder to\nuse this endpoint.", "tags": [ "Folder Locks" ], "x-box-tag": "folder_locks", "x-box-sanitized": true, "parameters": [ { "name": "folder_lock_id", "description": "The ID of the folder lock.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string", "nullable": false } } ], "responses": { "204": { "description": "Returns an empty response when the folder lock is successfully deleted." }, "403": { "description": "Returns an error if the user does not have the required\naccess to perform the action.\n\n* `access_denied_insufficient_permissions`: Returned when the\n user does not have access to the folder.\n\n* `insufficient_scope`: Returned an error if the application\n does not have the right scope to delete folders. Make sure\n your application has been configured to read and write all files\n and folders stored in Box.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the folder could not be found,\nor the authenticated user does not have access to the folder.\n\n* `not_found` when the authenticated user does not have access\n to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/metadata_templates": { "get": { "operationId": "get_metadata_templates", "summary": "Find metadata template by instance ID", "tags": [ "Metadata templates" ], "x-box-tag": "metadata_templates", "x-box-sanitized": true, "description": "Finds a metadata template by searching for the ID of an instance of the\ntemplate.", "parameters": [ { "name": "metadata_instance_id", "description": "The ID of an instance of the metadata template to find.", "example": "01234500-12f1-1234-aa12-b1d234cb567e", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Returns a list containing the 1 metadata template that matches the\ninstance ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataTemplates" } } } }, "400": { "description": "Returned when the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema": { "get": { "operationId": "get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema", "summary": "List all classifications", "tags": [ "Classifications" ], "x-box-tag": "classifications", "x-box-sanitized": true, "description": "Retrieves the classification metadata template and lists all the\nclassifications available to this enterprise.\n\nThis API can also be called by including the enterprise ID in the\nURL explicitly, for example\n`/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`.", "responses": { "200": { "description": "Returns the `securityClassification` metadata template, which contains\na `Box__Security__Classification__Key` field that lists all the\nclassifications available to this enterprise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClassificationTemplate" } } } }, "400": { "description": "Returned if any of the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when a template name is not correct. Please make sure\nthe URL for the request is correct.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema", "summary": "Delete all classifications", "tags": [ "Classifications" ], "x-box-tag": "classifications", "x-box-sanitized": true, "description": "Delete all classifications by deleting the classification\nmetadata template.", "responses": { "204": { "description": "Returns an empty response when the metadata\ntemplate for classifications is successfully deleted." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema#add": { "put": { "operationId": "put_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema#add", "summary": "Add classification", "tags": [ "Classifications" ], "x-box-tag": "classifications", "x-box-sanitized": true, "description": "Adds one or more new classifications to the list of classifications\navailable to the enterprise.\n\nThis API can also be called by including the enterprise ID in the\nURL explicitly, for example\n`/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`.", "requestBody": { "content": { "application/json-patch+json": { "schema": { "description": "An array that contains one or more classifications to add to\nthe enterprise's list of classifications.", "type": "array", "items": { "type": "object", "description": "A single classification to add to the enterprise.", "required": [ "op", "fieldKey", "data" ], "properties": { "op": { "type": "string", "example": "addEnumOption", "description": "`addEnumOption`" }, "fieldKey": { "type": "string", "example": "Box__Security__Classification__Key", "description": "`Box__Security__Classification__Key`" }, "data": { "type": "object", "description": "The details of the classification to add.", "required": [ "key" ], "properties": { "key": { "type": "string", "example": "Sensitive", "description": "The label of the classification as shown in the web and\nmobile interfaces. This is the only field required to\nadd a classification." }, "classification": { "type": "object", "description": "Additional details for the classification.", "properties": { "classificationDefinition": { "type": "string", "example": "Sensitive information that must not be shared.", "description": "A longer description of the classification." }, "colorID": { "type": "number", "example": 4, "description": "An internal Box identifier used to assign a color to\na classification label.\n\nMapping between a `colorID` and a color may change\nwithout notice. Currently, the color mappings are as\nfollows.\n\n* `0`: Yellow\n* `1`: Orange\n* `2`: Watermelon red\n* `3`: Purple rain\n* `4`: Light blue\n* `5`: Dark blue\n* `6`: Light green\n* `7`: Gray" } } } } } } } } } } }, "responses": { "200": { "description": "Returns the updated `securityClassification` metadata template, which\ncontains a `Box__Security__Classification__Key` field that lists all\nthe classifications available to this enterprise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClassificationTemplate" } } } }, "400": { "description": "Returned if any of the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when a template name is not correct. Please make sure\nthe URL for the request is correct.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema#update": { "put": { "operationId": "put_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema#update", "summary": "Update classification", "tags": [ "Classifications" ], "x-box-tag": "classifications", "x-box-sanitized": true, "description": "Updates the labels and descriptions of one or more classifications\navailable to the enterprise.\n\nThis API can also be called by including the enterprise ID in the\nURL explicitly, for example\n`/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`.", "requestBody": { "content": { "application/json-patch+json": { "schema": { "description": "An array that contains one or more classifications to update.", "type": "array", "items": { "type": "object", "description": "A single classification to update.", "required": [ "op", "fieldKey", "enumOptionKey", "data" ], "properties": { "op": { "type": "string", "example": "editEnumOption", "description": "`editEnumOption`" }, "fieldKey": { "type": "string", "example": "Box__Security__Classification__Key", "description": "`Box__Security__Classification__Key`" }, "enumOptionKey": { "type": "string", "example": "Sensitive", "description": "The original label of the classification to change." }, "data": { "type": "object", "description": "The details of the updated classification.", "required": [ "key" ], "properties": { "key": { "type": "string", "example": "Very Sensitive", "description": "A new label for the classification, as it will be\nshown in the web and mobile interfaces." }, "classification": { "type": "object", "description": "Additional details for the classification.", "properties": { "classificationDefinition": { "type": "string", "example": "Sensitive information that must not be shared.", "description": "A longer description of the classification." }, "colorID": { "type": "number", "example": 4, "description": "An internal Box identifier used to assign a color to\na classification label.\n\nMapping between a `colorID` and a color may change\nwithout notice. Currently, the color mappings are as\nfollows.\n\n* `0`: Yellow\n* `1`: Orange\n* `2`: Watermelon red\n* `3`: Purple rain\n* `4`: Light blue\n* `5`: Dark blue\n* `6`: Light green\n* `7`: Gray" } } } } } } } } } } }, "responses": { "200": { "description": "Returns the updated `securityClassification` metadata template, which\ncontains a `Box__Security__Classification__Key` field that lists all\nthe classifications available to this enterprise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClassificationTemplate" } } } }, "400": { "description": "Returned if any of the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when a template name is not correct. Please make sure\nthe URL for the request is correct.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema#delete": { "put": { "operationId": "put_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema#delete", "summary": "Delete classification", "tags": [ "Classifications" ], "x-box-tag": "classifications", "x-box-sanitized": true, "description": "Removes a classification from the list of classifications\navailable to the enterprise.\n\nThis API can also be called by including the enterprise ID in the\nURL explicitly, for example\n`/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`.", "requestBody": { "content": { "application/json-patch+json": { "schema": { "description": "An array that contains one or more classifications to remove.", "type": "array", "items": { "type": "object", "description": "A single classification to remove.", "required": [ "op", "fieldKey", "enumOptionKey" ], "properties": { "op": { "type": "string", "example": "removeEnumOption", "description": "`removeEnumOption`" }, "fieldKey": { "type": "string", "example": "Box__Security__Classification__Key", "description": "`Box__Security__Classification__Key`" }, "enumOptionKey": { "type": "string", "example": "Sensitive", "description": "The label of the classification to remove." } } } } } } }, "responses": { "200": { "description": "Returns the updated `securityClassification` metadata template, which\ncontains a `Box__Security__Classification__Key` field that lists all\nthe classifications available to this enterprise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClassificationTemplate" } } } }, "400": { "description": "Returned if any of the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when a template name is not correct. Please make sure\nthe URL for the request is correct.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/metadata_templates/{scope}/{template_key}/schema": { "get": { "operationId": "get_metadata_templates_id_id_schema", "summary": "Get metadata template by name", "tags": [ "Metadata templates" ], "x-box-tag": "metadata_templates", "x-box-sanitized": true, "description": "Retrieves a metadata template by its `scope` and `templateKey` values.\n\nTo find the `scope` and `templateKey` for a template, list all templates for\nan enterprise or globally, or list all templates applied to a file or folder.", "parameters": [ { "name": "scope", "description": "The scope of the metadata template", "example": "global", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "global", "enterprise" ] } }, { "name": "template_key", "description": "The name of the metadata template", "example": "properties", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the metadata template matching the `scope`\nand `template` name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataTemplate" } } } }, "400": { "description": "Returned if any of the request parameters are not valid.\n\n* `bad_request`: Often returned when the scope of the template is not\n recognised. Please make sure to use either `enterprise` or `global` as\n the `scope` value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when a template with the given `scope` and `template_key` can not\nbe found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "put": { "operationId": "put_metadata_templates_id_id_schema", "tags": [ "Metadata templates" ], "x-box-tag": "metadata_templates", "x-box-sanitized": true, "summary": "Update metadata template", "description": "Updates a metadata template.\n\nThe metadata template can only be updated if the template\nalready exists.\n\nThe update is applied atomically. If any errors occur during the\napplication of the operations, the metadata template will not be changed.", "parameters": [ { "name": "scope", "description": "The scope of the metadata template", "example": "global", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "global", "enterprise" ] } }, { "name": "template_key", "description": "The name of the metadata template", "example": "properties", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json-patch+json": { "schema": { "description": "A [JSON-Patch](https://tools.ietf.org/html/rfc6902)\nspecification for the changes to make to the metadata\ntemplate.\n\nThe changes are represented as a JSON array of\noperation objects.", "type": "array", "items": { "title": "A metadata template update operation", "description": "A [JSON-Patch](https://tools.ietf.org/html/rfc6902) operation for a\nchange to make to the metadata instance.", "type": "object", "required": [ "op" ], "properties": { "op": { "type": "string", "example": "addEnumOption", "enum": [ "editTemplate", "addField", "reorderFields", "addEnumOption", "reorderEnumOptions", "reorderMultiSelectOptions", "addMultiSelectOption", "editField", "removeField", "editEnumOption", "removeEnumOption", "editMultiSelectOption", "removeMultiSelectOption" ], "description": "The type of change to perform on the template. Some\nof these are hazardous as they will change existing templates." }, "data": { "type": "object", "description": "The data for the operation. This will vary depending on the\noperation being performed.", "example": { "name": "Aaron Levie" }, "additionalProperties": { "type": "string", "description": "The value of a custom data entry.", "example": "Aaron Levie", "x-box-example-key": "name" } }, "fieldKey": { "type": "string", "example": "category", "description": "For operations that affect a single field this defines the key of\nthe field that is affected." }, "fieldKeys": { "type": "array", "items": { "type": "string" }, "example": [ "category", "name" ], "description": "For operations that affect multiple fields this defines the keys\nof the fields that are affected." }, "enumOptionKey": { "description": "For operations that affect a single `enum` option this defines\nthe key of the option that is affected.", "type": "string", "example": "option1" }, "enumOptionKeys": { "description": "For operations that affect multiple `enum` options this defines\nthe keys of the options that are affected.", "type": "array", "items": { "type": "string" }, "example": [ "option1", "option2", "option3" ] }, "multiSelectOptionKey": { "description": "For operations that affect a single multi select option this\ndefines the key of the option that is affected.", "type": "string", "example": "option1" }, "multiSelectOptionKeys": { "description": "For operations that affect multiple multi select options this\ndefines the keys of the options that are affected.", "type": "array", "items": { "type": "string" }, "example": [ "option1", "option2", "option3" ] } } } } } } }, "responses": { "200": { "description": "Returns the updated metadata template, with the\ncustom template data included.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataTemplate" } } } }, "400": { "description": "The request body does not contain a valid metadata schema.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "The request body contains a scope that the user is not\nallowed to create templates for.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "The requested template could not be found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_metadata_templates_id_id_schema", "summary": "Remove metadata template", "tags": [ "Metadata templates" ], "x-box-tag": "metadata_templates", "x-box-sanitized": true, "description": "Delete a metadata template and its instances.\nThis deletion is permanent and can not be reversed.", "parameters": [ { "name": "scope", "description": "The scope of the metadata template", "example": "global", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "global", "enterprise" ] } }, { "name": "template_key", "description": "The name of the metadata template", "example": "properties", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Returns an empty response when the metadata\ntemplate is successfully deleted." }, "400": { "description": "Request body does not contain a valid metadata schema.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Request body contains a scope that the user is not allowed to\ncreate a template for.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/metadata_templates/{template_id}": { "get": { "operationId": "get_metadata_templates_id", "summary": "Get metadata template by ID", "tags": [ "Metadata templates" ], "x-box-tag": "metadata_templates", "x-box-sanitized": true, "description": "Retrieves a metadata template by its ID.", "parameters": [ { "name": "template_id", "schema": { "type": "string" }, "required": true, "in": "path", "example": "f7a9891f", "description": "The ID of the template" } ], "responses": { "200": { "description": "Returns the metadata template that matches the ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataTemplate" } } } }, "400": { "description": "Returned if any of the request parameters are not valid.\n\n* `bad_request`: Often returned with a message when the ID of the template\n is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataTemplate" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/metadata_templates/global": { "get": { "operationId": "get_metadata_templates_global", "summary": "List all global metadata templates", "tags": [ "Metadata templates" ], "x-box-tag": "metadata_templates", "x-box-sanitized": true, "description": "Used to retrieve all generic, global metadata templates available to all\nenterprises using Box.", "parameters": [ { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } } ], "responses": { "200": { "description": "Returns all of the metadata templates available to all enterprises\nand their corresponding schema.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataTemplates" } } } }, "400": { "description": "Returned when the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/metadata_templates/enterprise": { "get": { "operationId": "get_metadata_templates_enterprise", "summary": "List all metadata templates for enterprise", "tags": [ "Metadata templates" ], "x-box-tag": "metadata_templates", "x-box-sanitized": true, "description": "Used to retrieve all metadata templates created to be used specifically within\nthe user's enterprise", "parameters": [ { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } } ], "responses": { "200": { "description": "Returns all of the metadata templates within an enterprise\nand their corresponding schema.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataTemplates" } } } }, "400": { "description": "Returned when the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/metadata_templates/schema": { "post": { "operationId": "post_metadata_templates_schema", "summary": "Create metadata template", "tags": [ "Metadata templates" ], "description": "Creates a new metadata template that can be applied to\nfiles and folders.", "x-box-tag": "metadata_templates", "x-box-requires-admin": true, "x-box-sanitized": true, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "scope", "displayName" ], "properties": { "scope": { "type": "string", "description": "The scope of the metadata template to create. Applications can\nonly create templates for use within the authenticated user's\nenterprise.\n\nThis value needs to be set to `enterprise`, as `global` scopes can\nnot be created by applications.", "example": "enterprise" }, "templateKey": { "type": "string", "example": "productInfo", "description": "A unique identifier for the template. This identifier needs to be\nunique across the enterprise for which the metadata template is\nbeing created.\n\nWhen not provided, the API will create a unique `templateKey`\nbased on the value of the `displayName`.", "maxLength": 64, "pattern": "^[a-zA-Z_][-a-zA-Z0-9_]*$" }, "displayName": { "type": "string", "description": "The display name of the template.", "maxLength": 4096, "example": "Product Info" }, "hidden": { "type": "boolean", "example": true, "description": "Defines if this template is visible in the Box web app UI, or if\nit is purely intended for usage through the API.", "default": false }, "fields": { "type": "array", "description": "An ordered list of template fields which are part of the template.\nEach field can be a regular text field, date field, number field,\nas well as a single or multi-select list.", "items": { "title": "Metadata Field (Write)", "description": "A field within a metadata template. Fields can be a basic text, date, or\nnumber field, or a list of options.", "required": [ "type", "key", "displayName" ], "type": "object", "properties": { "type": { "type": "string", "example": "string", "description": "The type of field. The basic fields are a `string` field for text, a\n`float` field for numbers, and a `date` fields to present the user with a\ndate-time picker.\n\nAdditionally, metadata templates support an `enum` field for a basic list\nof items, and ` multiSelect` field for a similar list of items where the\nuser can select more than one value.", "enum": [ "string", "float", "date", "enum", "multiSelect" ] }, "key": { "type": "string", "example": "category", "description": "A unique identifier for the field. The identifier must\nbe unique within the template to which it belongs.", "maxLength": 256 }, "displayName": { "type": "string", "example": "Category", "description": "The display name of the field as it is shown to the user in the web and\nmobile apps.", "maxLength": 4096 }, "description": { "type": "string", "example": "The category", "description": "A description of the field. This is not shown to the user.", "maxLength": 4096 }, "hidden": { "type": "boolean", "example": true, "description": "Whether this field is hidden in the UI for the user and can only be set\nthrough the API instead." }, "options": { "description": "A list of options for this field. This is used in combination with the\n`enum` and `multiSelect` field types.", "type": "array", "items": { "title": "Metadata Option (Write)", "type": "object", "description": "An option for a Metadata Template Field.\n\nOptions only need to be provided for fields of type `enum` and `multiSelect`.\nOptions represent the value(s) a user can select for the field either through\nthe UI or through the API.", "required": [ "key" ], "properties": { "key": { "description": "The text value of the option. This represents both the display name of the\noption and the internal key used when updating templates.", "example": "Category 1", "type": "string" } } } } } } }, "copyInstanceOnItemCopy": { "type": "boolean", "description": "Whether or not to copy any metadata attached to a file or folder\nwhen it is copied. By default, metadata is not copied along with a\nfile or folder when it is copied.", "default": false, "example": true } } } } } }, "responses": { "201": { "description": "The schema representing the metadata template created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataTemplate" } } } }, "400": { "description": "Returned if the request parameters or body is not valid.\n\n* `bad_request` when the body does not contain a valid request. In many\ncases this response will include extra details on what fields are missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned when the user does not have the permission to create the metadata\ntemplate. This can happen for a few reasons, most commonly when the user\ndoes not have (co-)admin permissions, or the application tries to create a\ntemplate with the `global` scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/metadata_templates/schema#classifications": { "post": { "operationId": "post_metadata_templates_schema#classifications", "summary": "Add initial classifications", "tags": [ "Classifications" ], "x-box-tag": "classifications", "x-box-sanitized": true, "description": "When an enterprise does not yet have any classifications, this API call\ninitializes the classification template with an initial set of\nclassifications.\n\nIf an enterprise already has a classification, the template will already\nexist and instead an API call should be made to add additional\nclassifications.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "scope", "displayName" ], "properties": { "scope": { "type": "string", "description": "The scope in which to create the classifications. This should\nbe `enterprise` or `enterprise_{id}` where `id` is the unique\nID of the enterprise.", "example": "enterprise", "enum": [ "enterprise" ] }, "templateKey": { "type": "string", "example": "securityClassification-6VMVochwUWo", "description": "`securityClassification-6VMVochwUWo`", "enum": [ "securityClassification-6VMVochwUWo" ] }, "displayName": { "type": "string", "description": "`Classification`", "example": "Classification", "enum": [ "Classification" ] }, "hidden": { "type": "boolean", "example": false, "description": "`false`" }, "copyInstanceOnItemCopy": { "type": "boolean", "example": false, "description": "`false`" }, "fields": { "type": "array", "description": "The classification template holds one field, which holds\nall the valid classification values.", "items": { "type": "object", "description": "The `enum` field which holds all the valid classification\nvalues.", "properties": { "type": { "type": "string", "example": "enum", "description": "`enum`", "enum": [ "enum" ] }, "key": { "type": "string", "example": "Box__Security__Classification__Key", "description": "`Box__Security__Classification__Key`", "enum": [ "Box__Security__Classification__Key" ] }, "displayName": { "type": "string", "example": "Classification", "description": "`Classification`", "enum": [ "Classification" ] }, "hidden": { "type": "boolean", "example": false, "description": "`false`" }, "options": { "type": "array", "description": "The actual list of classifications that are present on\nthis template.", "items": { "type": "object", "description": "An individual classification.", "properties": { "key": { "type": "string", "description": "The display name and key this classification. This\nwill be show in the Box UI.", "example": "Sensitive" }, "staticConfig": { "type": "object", "description": "Additional information about the classification.", "properties": { "classification": { "type": "object", "description": "Additional information about the classification.", "properties": { "classificationDefinition": { "type": "string", "example": "Sensitive information", "description": "A longer description of the classification." }, "colorID": { "type": "number", "example": 4, "description": "An identifier used to assign a color to\na classification label.\n\nMapping between a `colorID` and a color may\nchange without notice. Currently, the color\nmappings are as follows.\n\n* `0`: Yellow\n* `1`: Orange\n* `2`: Watermelon red\n* `3`: Purple rain\n* `4`: Light blue\n* `5`: Dark blue\n* `6`: Light green\n* `7`: Gray" } } } } } } } } } } } } } } } }, "responses": { "200": { "description": "Returns a new `securityClassification` metadata template, which\ncontains a `Box__Security__Classification__Key` field that lists all\nthe classifications available to this enterprise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClassificationTemplate" } } } }, "400": { "description": "Returned if any of the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when a template name is not correct. Please make sure\nthe URL for the request is correct.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/metadata_cascade_policies": { "get": { "operationId": "get_metadata_cascade_policies", "summary": "List metadata cascade policies", "tags": [ "Metadata cascade policies" ], "x-box-tag": "metadata_cascade_policies", "x-box-sanitized": true, "description": "Retrieves a list of all the metadata cascade policies\nthat are applied to a given folder. This can not be used on the root\nfolder with ID `0`.", "parameters": [ { "name": "folder_id", "in": "query", "required": true, "schema": { "type": "string" }, "example": "31232", "description": "Specifies which folder to return policies for. This can not be used on the\nroot folder with ID `0`." }, { "name": "owner_enterprise_id", "in": "query", "schema": { "type": "string" }, "example": "31232", "description": "The ID of the enterprise ID for which to find metadata\ncascade policies. If not specified, it defaults to the\ncurrent enterprise." }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } }, { "name": "offset", "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 } } ], "responses": { "200": { "description": "Returns a list of metadata cascade policies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataCascadePolicies" } } } }, "400": { "description": "Returns an error when any of the parameters are not in a valid format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error when the folder can not be accessed. This error often\nhappens when accessing the root folder with ID `0`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the folder can not be found or the user does not\nhave access to the folder.\n\n* `not_found` - The folder could not be found or the user does not have\n access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_metadata_cascade_policies", "summary": "Create metadata cascade policy", "tags": [ "Metadata cascade policies" ], "x-box-tag": "metadata_cascade_policies", "x-box-sanitized": true, "description": "Creates a new metadata cascade policy that applies a given\nmetadata template to a given folder and automatically\ncascades it down to any files within that folder.\n\nIn order for the policy to be applied a metadata instance must first\nbe applied to the folder the policy is to be applied to.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "folder_id", "scope", "templateKey" ], "properties": { "folder_id": { "type": "string", "description": "The ID of the folder to apply the policy to. This folder will\nneed to already have an instance of the targeted metadata\ntemplate applied to it.", "example": "1234567" }, "scope": { "description": "The scope of the targeted metadata template. This template will\nneed to already have an instance applied to the targeted folder.", "example": "enterprise", "type": "string", "enum": [ "global", "enterprise" ] }, "templateKey": { "type": "string", "example": "productInfo", "description": "The key of the targeted metadata template. This template will\nneed to already have an instance applied to the targeted folder.\n\nIn many cases the template key is automatically derived\nof its display name, for example `Contract Template` would\nbecome `contractTemplate`. In some cases the creator of the\ntemplate will have provided its own template key.\n\nPlease [list the templates for an enterprise][list], or\nget all instances on a [file][file] or [folder][folder]\nto inspect a template's key.\n\n[list]: e://get-metadata-templates-enterprise\n[file]: e://get-files-id-metadata\n[folder]: e://get-folders-id-metadata" } } } } } }, "responses": { "201": { "description": "Returns a new of metadata cascade policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataCascadePolicy" } } } }, "400": { "description": "Returns an error when any of the parameters are not in a valid format.\n\n* `bad_request` - Either the `scope`, `templateKey`, or `folder_id` are\nnot in a valid format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error when trying to apply a policy to a restricted folder, for\nexample the root folder with ID `0`.\n\n* `forbidden` - Although the folder ID was valid and the user has access\nto the folder, the policy could not be applied to this folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the template or folder can not be found, or when the\nuser does not have access to the folder or template.\n\n* `instance_tuple_not_found` - The template could not be found or the user\ndoes not have access to the template.\n* `not_found` - The folder could not be found or the user\ndoes not have access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error when a policy for this folder and template is already in\nplace.\n\n* `tuple_already_exists` - A cascade policy for this combination of\n`folder_id`, `scope` and `templateKey` already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/metadata_cascade_policies/{metadata_cascade_policy_id}": { "get": { "operationId": "get_metadata_cascade_policies_id", "summary": "Get metadata cascade policy", "tags": [ "Metadata cascade policies" ], "x-box-tag": "metadata_cascade_policies", "x-box-sanitized": true, "description": "Retrieve a specific metadata cascade policy assigned to a folder.", "parameters": [ { "name": "metadata_cascade_policy_id", "description": "The ID of the metadata cascade policy.", "example": "6fd4ff89-8fc1-42cf-8b29-1890dedd26d7", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a metadata cascade policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataCascadePolicy" } } } }, "404": { "description": "Returns an error when the policy can not be found or the user does not\nhave access to the folder.\n\n* `instance_not_found` - The policy could not be found\n* `not_found` - The folder could not be found or the user does not have\n access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_metadata_cascade_policies_id", "summary": "Remove metadata cascade policy", "tags": [ "Metadata cascade policies" ], "x-box-tag": "metadata_cascade_policies", "x-box-sanitized": true, "description": "Deletes a metadata cascade policy.", "parameters": [ { "name": "metadata_cascade_policy_id", "description": "The ID of the metadata cascade policy.", "example": "6fd4ff89-8fc1-42cf-8b29-1890dedd26d7", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Returns an empty response when the policy\nis successfully deleted." }, "404": { "description": "Returns an error when the policy can not be found or the user does not\nhave access to the folder.\n\n* `instance_not_found` - The policy could not be found\n* `not_found` - The folder could not be found or the user does not have\n access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/metadata_cascade_policies/{metadata_cascade_policy_id}/apply": { "post": { "operationId": "post_metadata_cascade_policies_id_apply", "summary": "Force-apply metadata cascade policy to folder", "tags": [ "Metadata cascade policies" ], "x-box-tag": "metadata_cascade_policies", "x-box-sanitized": true, "description": "Force the metadata on a folder with a metadata cascade policy to be applied to\nall of its children. This can be used after creating a new cascade policy to\nenforce the metadata to be cascaded down to all existing files within that\nfolder.", "parameters": [ { "name": "metadata_cascade_policy_id", "required": true, "in": "path", "schema": { "type": "string" }, "description": "The ID of the cascade policy to force-apply.", "example": "6fd4ff89-8fc1-42cf-8b29-1890dedd26d7" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "conflict_resolution" ], "properties": { "conflict_resolution": { "type": "string", "enum": [ "none", "overwrite" ], "description": "Describes the desired behavior when dealing with the conflict\nwhere a metadata template already has an instance applied\nto a child.\n\n* `none` will preserve the existing value on the file\n* `overwrite` will force-apply the templates values over\n any existing values.", "example": "none" } } } } } }, "responses": { "202": { "description": "Returns an empty response when the API call was successful. The metadata\ncascade operation will be performed asynchronously.\n\nThe API call will return directly, before the cascade operation\nis complete. There is currently no API to check for the status of this\noperation." }, "404": { "description": "Returns an error when the policy can not be found or the user does not\nhave access to the folder.\n\n* `instance_not_found` - The policy could not be found\n* `not_found` - The folder could not be found or the user does not have\n access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/metadata_queries/execute_read": { "post": { "operationId": "post_metadata_queries_execute_read", "summary": "Query files/folders by metadata", "tags": [ "Search" ], "x-box-tag": "search", "x-box-sanitized": true, "x-box-enable-explorer": true, "description": "Create a search using SQL-like syntax to return items that match specific\nmetadata.\n\nBy default, this endpoint returns only the most basic info about the items for\nwhich the query matches. To get additional fields for each item, including any\nof the metadata, use the `fields` attribute in the query.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataQuery" } } } }, "responses": { "200": { "description": "Returns a list of files and folders that match this metadata query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataQueryResults" } } } }, "400": { "description": "Returns an error when the request body is not valid.\n\n* `invalid_query` - Any of the provided body parameters might be\nincorrect. This can mean the `query` is incorrect, as well as some cases\nwhere the `from` value does not represent a valid template.\n* `unexpected_json_type` - An argument from the `query` string is not\npresent in `query_param`. For example, `query` of `name = :name` requires\nthe `query_param` to include a value for the `name` argument, for example\n`{ \"name\": \"Box, Inc\" }`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when a metadata template with the given `scope` and\n`templateKey` can not be found. The error response will include extra\ndetails.\n\n* `instance_not_found` - The template was not found. Please make sure\nto use the full template scope including the enterprise ID, like\n`enterprise_12345`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/metadata_query_indices": { "get": { "operationId": "get_metadata_query_indices", "summary": "List metadata query indices", "tags": [ "Search" ], "x-box-tag": "search", "x-box-sanitized": true, "x-box-enable-explorer": true, "description": "Retrieves the metadata query indices for a given scope and template key.", "parameters": [ { "name": "scope", "description": "The scope of the metadata template", "example": "global", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "global", "enterprise" ] } }, { "name": "template_key", "description": "The name of the metadata template", "example": "properties", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a collection of metadata query indices for scope and template key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataQueryIndices" } } } }, "400": { "description": "Returns an error when any of the parameters are not in a valid format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the scope and template combination cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/comments/{comment_id}": { "get": { "operationId": "get_comments_id", "summary": "Get comment", "tags": [ "Comments" ], "x-box-tag": "comments", "description": "Retrieves the message and metadata for a specific comment, as well\nas information on the user who created the comment.", "parameters": [ { "name": "comment_id", "description": "The ID of the comment.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Returns a full comment object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment--Full" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "put": { "operationId": "put_comments_id", "summary": "Update comment", "tags": [ "Comments" ], "x-box-tag": "comments", "description": "Update the message of a comment.", "parameters": [ { "name": "comment_id", "description": "The ID of the comment.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The text of the comment to update", "example": "Review completed!" } } } } } }, "responses": { "200": { "description": "Returns the updated comment object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment--Full" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_comments_id", "summary": "Remove comment", "tags": [ "Comments" ], "x-box-tag": "comments", "description": "Permanently deletes a comment.", "parameters": [ { "name": "comment_id", "description": "The ID of the comment.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Returns an empty response when the comment has been deleted." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/comments": { "post": { "operationId": "post_comments", "tags": [ "Comments" ], "x-box-tag": "comments", "summary": "Create comment", "description": "Adds a comment by the user to a specific file, or\nas a reply to an other comment.", "parameters": [ { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "The text of the comment.\n\nTo mention a user, use the `tagged_message`\nparameter instead.", "example": "Review completed!" }, "tagged_message": { "type": "string", "description": "The text of the comment, including `@[user_id:name]`\nsomewhere in the message to mention another user, which\nwill send them an email notification, letting them know\nthey have been mentioned.\n\nThe `user_id` is the target user's ID, where the `name`\ncan be any custom phrase. In the Box UI this name will\nlink to the user's profile.\n\nIf you are not mentioning another user, use `message`\ninstead.", "example": "@[1234:John] Review completed!" }, "item": { "type": "object", "description": "The item to attach the comment to.", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The ID of the item", "example": "11446498" }, "type": { "type": "string", "description": "The type of the item that this comment will be placed on.", "example": "file", "enum": [ "file", "comment" ] } } } } } } } }, "responses": { "201": { "description": "Returns the newly created comment object.\n\nNot all available fields are returned by default. Use the\n[fields](#param-fields) query parameter to explicitly request\nany specific fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/collaborations/{collaboration_id}": { "get": { "operationId": "get_collaborations_id", "summary": "Get collaboration", "x-box-tag": "user_collaborations", "tags": [ "Collaborations" ], "description": "Retrieves a single collaboration.", "parameters": [ { "name": "collaboration_id", "description": "The ID of the collaboration", "in": "path", "required": true, "example": "1234", "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Returns a collaboration object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collaboration" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "put": { "operationId": "put_collaborations_id", "tags": [ "Collaborations" ], "x-box-tag": "user_collaborations", "summary": "Update collaboration", "description": "Updates a collaboration.\nCan be used to change the owner of an item, or to\naccept collaboration invites.", "parameters": [ { "name": "collaboration_id", "description": "The ID of the collaboration", "in": "path", "required": true, "example": "1234", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "description": "The level of access granted.", "example": "editor", "enum": [ "editor", "viewer", "previewer", "uploader", "previewer uploader", "viewer uploader", "co-owner", "owner" ] }, "status": { "type": "string", "description": "\nSet the status of a `pending` collaboration invitation,\neffectively accepting, or rejecting the invite.", "example": "accepted", "enum": [ "pending", "accepted", "rejected" ] }, "expires_at": { "type": "string", "format": "date-time", "description": "Update the expiration date for the collaboration. At this date,\nthe collaboration will be automatically removed from the item.\n\nThis feature will only work if the **Automatically remove invited\ncollaborators: Allow folder owners to extend the expiry date**\nsetting has been enabled in the **Enterprise Settings**\nof the **Admin Console**. When the setting is not enabled,\ncollaborations can not have an expiry date and a value for this\nfield will be result in an error.\n\nAdditionally, a collaboration can only be given an\nexpiration if it was created after the **Automatically remove\ninvited collaborator** setting was enabled.", "example": "2019-08-29T23:59:00-07:00" }, "can_view_path": { "type": "boolean", "description": "Determines if the invited users can see the entire parent path to\nthe associated folder. The user will not gain privileges in any\nparent folder and therefore can not see content the user is not\ncollaborated on.\n\nBe aware that this meaningfully increases the time required to load the\ninvitee's **All Files** page. We recommend you limit the number of\ncollaborations with `can_view_path` enabled to 1,000 per user.\n\nOnly owner or co-owners can invite collaborators with a `can_view_path` of\n`true`.\n\n`can_view_path` can only be used for folder collaborations.", "example": true } } } } } }, "responses": { "200": { "description": "Returns an updated collaboration object unless the owner has changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collaboration" } } } }, "204": { "description": "If the role is changed to `owner`, the collaboration is deleted\nand a new collaboration is created. The previous `owner` of\nthe old collaboration will be a `co-owner` on the new collaboration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collaboration" } } } }, "403": { "description": "Returns an error if the authenticated user does not have the right\npermissions to update the collaboration.\n\nAdditionally, this error may occur when attempting to update the\n`expires_at` field for the collaboration without the **Automatically\nremove invited collaborators: Allow folder owners to extend the expiry\ndate** setting enabled in the admin dashboard of the enterprise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_collaborations_id", "summary": "Remove collaboration", "tags": [ "Collaborations" ], "x-box-tag": "user_collaborations", "description": "Deletes a single collaboration.", "parameters": [ { "name": "collaboration_id", "description": "The ID of the collaboration", "in": "path", "required": true, "example": "1234", "schema": { "type": "string" } } ], "responses": { "204": { "description": "A blank response is returned if the collaboration was\nsuccessfully deleted." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/collaborations": { "get": { "operationId": "get_collaborations", "summary": "List pending collaborations", "tags": [ "Collaborations (List)" ], "x-box-tag": "list_collaborations", "description": "Retrieves all pending collaboration invites for this user.", "parameters": [ { "name": "status", "description": "The status of the collaborations to retrieve", "in": "query", "required": true, "example": "pending", "schema": { "type": "string", "enum": [ "pending" ] } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "offset", "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } } ], "responses": { "200": { "description": "Returns a collection of pending collaboration objects.\n\nIf the user has no pending collaborations, the collection\nwill be empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collaborations" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_collaborations", "tags": [ "Collaborations" ], "x-box-tag": "user_collaborations", "summary": "Create collaboration", "description": "Adds a collaboration for a single user or a single group to a file\nor folder.\n\nCollaborations can be created using email address, user IDs, or a\ngroup IDs.\n\nIf a collaboration is being created with a group, access to\nthis endpoint is dependent on the group's ability to be invited.\n\nIf collaboration is in `pending` status, the following fields\nare redacted:\n- `login` and `name` are hidden if a collaboration was created\nusing `user_id`,\n- `name` is hidden if a collaboration was created using `login`.", "parameters": [ { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "notify", "description": "Determines if users should receive email notification\nfor the action performed.", "in": "query", "required": false, "example": true, "schema": { "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "item", "accessible_by", "role" ], "properties": { "item": { "type": "object", "description": "The item to attach the comment to.", "required": [ "id", "type" ], "properties": { "type": { "type": "string", "description": "The type of the item that this collaboration will be\ngranted access to", "example": "file", "enum": [ "file", "folder" ] }, "id": { "type": "string", "description": "The ID of the item that will be granted access to", "example": "11446498" } } }, "accessible_by": { "type": "object", "description": "The user or group to give access to the item.", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The type of collaborator to invite.", "example": "user", "enum": [ "user", "group" ] }, "id": { "type": "string", "description": "The ID of the user or group.\n\nAlternatively, use `login` to specify a user by email\naddress.", "example": "23522323" }, "login": { "type": "string", "description": "The email address of the user to grant access to the item.\n\nAlternatively, use `id` to specify a user by user ID.", "example": "john@example.com" } } }, "role": { "type": "string", "description": "The level of access granted.", "example": "editor", "enum": [ "editor", "viewer", "previewer", "uploader", "previewer uploader", "viewer uploader", "co-owner" ] }, "can_view_path": { "type": "boolean", "description": "Determines if the invited users can see the entire parent path to\nthe associated folder. The user will not gain privileges in any\nparent folder and therefore can not see content the user is not\ncollaborated on.\n\nBe aware that this meaningfully increases the time required to load the\ninvitee's **All Files** page. We recommend you limit the number of\ncollaborations with `can_view_path` enabled to 1,000 per user.\n\nOnly owner or co-owners can invite collaborators with a `can_view_path` of\n`true`.\n\n`can_view_path` can only be used for folder collaborations.", "example": true }, "expires_at": { "type": "string", "format": "date-time", "description": "Set the expiration date for the collaboration. At this date, the\ncollaboration will be automatically removed from the item.\n\nThis feature will only work if the **Automatically remove invited\ncollaborators: Allow folder owners to extend the expiry date**\nsetting has been enabled in the **Enterprise Settings**\nof the **Admin Console**. When the setting is not enabled,\ncollaborations can not have an expiry date and a value for this\nfield will be result in an error.", "example": "2019-08-29T23:59:00-07:00" } } } } } }, "responses": { "201": { "description": "Returns a new collaboration object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collaboration" } } } }, "403": { "description": "Returns an error when the user does not have the\nright permissions to create the collaboration.\n\n* `forbidden_by_policy`: Creating a\ncollaboration is forbidden due to information\nbarrier restrictions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/search": { "get": { "operationId": "get_search", "summary": "Search for content", "tags": [ "Search" ], "x-box-tag": "search", "x-box-enable-explorer": true, "description": "Searches for files, folders, web links, and shared files across the\nusers content or across the entire enterprise.", "parameters": [ { "name": "query", "description": "The string to search for. This query is matched against item names,\ndescriptions, text content of files, and various other fields of\nthe different item types.\n\nThis parameter supports a variety of operators to further refine\nthe results returns.\n\n* `\"\"` - by wrapping a query in double quotes only exact matches are\n returned by the API. Exact searches do not return search matches\n based on specific character sequences. Instead, they return\n matches based on phrases, that is, word sequences. For example:\n A search for `\"Blue-Box\"` may return search results including\n the sequence `\"blue.box\"`, `\"Blue Box\"`, and `\"Blue-Box\"`;\n any item containing the words `Blue` and `Box` consecutively, in\n the order specified.\n* `AND` - returns items that contain both the search terms. For\n example, a search for `marketing AND BoxWorks` returns items\n that have both `marketing` and `BoxWorks` within its text in any order.\n It does not return a result that only has `BoxWorks` in its text.\n* `OR` - returns items that contain either of the search terms. For\n example, a search for `marketing OR BoxWorks` returns a result that\n has either `marketing` or `BoxWorks` within its text. Using this\n operator is not necessary as we implicitly interpret multi-word\n queries as `OR` unless another supported boolean term is used.\n* `NOT` - returns items that do not contain the search term provided.\n For example, a search for `marketing AND NOT BoxWorks` returns a result\n that has only `marketing` within its text. Results containing\n `BoxWorks` are omitted.\n\nWe do not support lower case (that is,\n`and`, `or`, and `not`) or mixed case (that is, `And`, `Or`, and `Not`)\noperators.\n\nThis field is required unless the `mdfilters` parameter is defined.", "in": "query", "required": false, "example": "sales", "schema": { "type": "string" } }, { "name": "scope", "description": "Limits the search results to either the files that the user has\naccess to, or to files available to the entire enterprise.\n\nThe scope defaults to `user_content`, which limits the search\nresults to content that is available to the currently authenticated\nuser.\n\nThe `enterprise_content` can be requested by an admin through our\nsupport channels. Once this scope has been enabled for a user, it\nwill allow that use to query for content across the entire\nenterprise and not only the content that they have access to.", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "user_content", "enterprise_content" ], "default": "user_content" }, "example": "user_content" }, { "name": "file_extensions", "description": "Limits the search results to any files that match any of the provided\nfile extensions. This list is a comma-separated list of file extensions\nwithout the dots.", "example": [ "pdf", "png", "gif" ], "in": "query", "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "created_at_range", "description": "Limits the search results to any items created within\na given date range.\n\nDate ranges are defined as comma separated RFC3339\ntimestamps.\n\nIf the the start date is omitted (`,2014-05-17T13:35:01-07:00`)\nanything created before the end date will be returned.\n\nIf the end date is omitted (`2014-05-15T13:35:01-07:00,`) the\ncurrent date will be used as the end date instead.", "example": [ "2014-05-15T13:35:01-07:00", "2014-05-17T13:35:01-07:00" ], "in": "query", "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "updated_at_range", "description": "Limits the search results to any items updated within\na given date range.\n\nDate ranges are defined as comma separated RFC3339\ntimestamps.\n\nIf the start date is omitted (`,2014-05-17T13:35:01-07:00`)\nanything updated before the end date will be returned.\n\nIf the end date is omitted (`2014-05-15T13:35:01-07:00,`) the\ncurrent date will be used as the end date instead.", "example": [ "2014-05-15T13:35:01-07:00", "2014-05-17T13:35:01-07:00" ], "in": "query", "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "size_range", "description": "Limits the search results to any items with a size within\na given file size range. This applied to files and folders.\n\nSize ranges are defined as comma separated list of a lower\nand upper byte size limit (inclusive).\n\nThe upper and lower bound can be omitted to create open ranges.", "example": [ 1000000, 5000000 ], "in": "query", "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "integer" } } }, { "name": "owner_user_ids", "description": "Limits the search results to any items that are owned\nby the given list of owners, defined as a list of comma separated\nuser IDs.\n\nThe items still need to be owned or shared with\nthe currently authenticated user for them to show up in the search\nresults. If the user does not have access to any files owned by any of\nthe users an empty result set will be returned.\n\nTo search across an entire enterprise, we recommend using the\n`enterprise_content` scope parameter which can be requested with our\nsupport team.", "example": [ "123422", "23532", "3241212" ], "in": "query", "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "recent_updater_user_ids", "description": "Limits the search results to any items that have been updated\nby the given list of users, defined as a list of comma separated\nuser IDs.\n\nThe items still need to be owned or shared with\nthe currently authenticated user for them to show up in the search\nresults. If the user does not have access to any files owned by any of\nthe users an empty result set will be returned.\n\nThis feature only searches back to the last 10 versions of an item.", "example": [ "123422", "23532", "3241212" ], "in": "query", "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "ancestor_folder_ids", "description": "Limits the search results to items within the given\nlist of folders, defined as a comma separated lists\nof folder IDs.\n\nSearch results will also include items within any subfolders\nof those ancestor folders.\n\nThe folders still need to be owned or shared with\nthe currently authenticated user. If the folder is not accessible by this\nuser, or it does not exist, a `HTTP 404` error code will be returned\ninstead.\n\nTo search across an entire enterprise, we recommend using the\n`enterprise_content` scope parameter which can be requested with our\nsupport team.", "explode": false, "example": [ "4535234", "234123235", "2654345" ], "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "content_types", "description": "Limits the search results to any items that match the search query\nfor a specific part of the file, for example the file description.\n\nContent types are defined as a comma separated lists\nof Box recognized content types. The allowed content types are as follows.\n\n* `name` - The name of the item, as defined by its `name` field.\n* `description` - The description of the item, as defined by its\n `description` field.\n* `file_content` - The actual content of the file.\n* `comments` - The content of any of the comments on a file or\n folder.\n* `tags` - Any tags that are applied to an item, as defined by its\n `tags` field.", "in": "query", "example": [ "name", "description" ], "explode": false, "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "name", "description", "file_content", "comments", "tag" ] } } }, { "name": "type", "description": "Limits the search results to any items of this type. This\nparameter only takes one value. By default the API returns\nitems that match any of these types.\n\n* `file` - Limits the search results to files\n* `folder` - Limits the search results to folders\n* `web_link` - Limits the search results to web links, also known\n as bookmarks", "example": "file", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "file", "folder", "web_link" ] } }, { "name": "trash_content", "description": "Determines if the search should look in the trash for items.\n\nBy default, this API only returns search results for items\nnot currently in the trash (`non_trashed_only`).\n\n* `trashed_only` - Only searches for items currently in the trash\n* `non_trashed_only` - Only searches for items currently not in\n the trash\n* `all_items` - Searches for both trashed and non-trashed items.", "in": "query", "required": false, "example": "non_trashed_only", "schema": { "type": "string", "default": "non_trashed_only", "enum": [ "non_trashed_only", "trashed_only", "all_items" ] } }, { "name": "mdfilters", "description": "Limits the search results to any items for which the metadata matches\nthe provided filter.\n\nThis parameter contains a list of 1 metadata template to filter\nthe search results by. This list can currently only\ncontain one entry, though this might be expanded in the future.\n\nThis parameter is required unless the `query` parameter is provided.", "in": "query", "example": [ { "scope": "enterprise", "templateKey": "contract", "filters": { "category": "online" } } ], "x-example": [ { "scope": "enterprise", "templateKey": "contract", "filters": { "category": "online", "contractValue": 1000000 } } ], "required": false, "schema": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/MetadataFilter" }, "description": "A list of metadata templates to filter the search results by.\n\nRequired unless `query` parameter is defined." } }, { "name": "sort", "description": "Defines the order in which search results are returned. This API\ndefaults to returning items by relevance unless this parameter is\nexplicitly specified.\n\n* `relevance` (default) returns the results sorted by relevance to the\nquery search term. The relevance is based on the occurrence of the search\nterm in the items name, description, content, and additional properties.\n* `modified_at` returns the results ordered in descending order by date\nat which the item was last modified.", "in": "query", "required": false, "schema": { "type": "string", "default": "relevance", "enum": [ "modified_at", "relevance" ] }, "example": "modified_at" }, { "name": "direction", "description": "Defines the direction in which search results are ordered. This API\ndefaults to returning items in descending (`DESC`) order unless this\nparameter is explicitly specified.\n\nWhen results are sorted by `relevance` the ordering is locked to returning\nitems in descending order of relevance, and this parameter is ignored.", "in": "query", "required": false, "schema": { "type": "string", "default": "DESC", "enum": [ "DESC", "ASC" ] }, "example": "ASC" }, { "name": "limit", "description": "Defines the maximum number of items to return as part of a page of\nresults.", "in": "query", "required": false, "example": 100, "schema": { "type": "integer", "format": "int64", "default": 30, "maximum": 200 } }, { "name": "include_recent_shared_links", "description": "Defines whether the search results should include any items\nthat the user recently accessed through a shared link.\n\nWhen this parameter has been set to true,\nthe format of the response of this API changes to return\na list of [Search Results with\nShared Links](r://search_results_with_shared_links)", "in": "query", "required": false, "example": true, "schema": { "type": "boolean", "default": false } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "offset", "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 } }, { "name": "deleted_user_ids", "description": "Limits the search results to items that were deleted by the given\nlist of users, defined as a list of comma separated user IDs.\n\nThe `trash_content` parameter needs to be set to `trashed_only`.\n\nIf searching in trash is not performed, an empty result set\nis returned. The items need to be owned or shared with\nthe currently authenticated user for them to show up in the search\nresults.\n\nIf the user does not have access to any files owned by\nany of the users, an empty result set is returned.\n\nData available from 2023-02-01 onwards.", "example": [ "123422", "23532", "3241212" ], "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "deleted_at_range", "description": "Limits the search results to any items deleted within a given\ndate range.\n\nDate ranges are defined as comma separated RFC3339 timestamps.\n\nIf the the start date is omitted (`2014-05-17T13:35:01-07:00`),\nanything deleted before the end date will be returned.\n\nIf the end date is omitted (`2014-05-15T13:35:01-07:00`),\nthe current date will be used as the end date instead.\n\nThe `trash_content` parameter needs to be set to `trashed_only`.\n\nIf searching in trash is not performed, then an empty result\nis returned.\n\nData available from 2023-02-01 onwards.", "example": [ "2014-05-15T13:35:01-07:00", "2014-05-17T13:35:01-07:00" ], "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Returns a collection of search results. If there are no matching\nsearch results, the `entries` array will be empty.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SearchResults" }, { "$ref": "#/components/schemas/SearchResultsWithSharedLinks" } ] } } } }, "400": { "description": "Returns an error when the request was not valid. This can have multiple\nreasons and the `context_info` object will provide you with more details.\n\n* `missing_parameter` - Please provide at least the `query` or `mdfilters`\n query parameter in a search.\n* `invalid_parameter` - Any of the fields might not be in the right\n format. This could for example mean that one of the RFC3339 dates is\n incorrect, or a string is provided where an integer is expected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error when the user does not have the permission to make\nthis API call.\n\n* The developer provided a `scope` of `enterprise_content` but did\n not request this scope to be enabled for the user through our\n support channels.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the user does not have access to an item\nmentioned in the request.\n\n* The developer provided a folder ID in `ancestor_folder_ids`\n that either does not exist or the user does not have access to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/tasks": { "post": { "operationId": "post_tasks", "tags": [ "Tasks" ], "summary": "Create task", "x-box-tag": "tasks", "x-box-sanitized": true, "description": "Creates a single task on a file. This task is not assigned to any user and\nwill need to be assigned separately.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "item" ], "properties": { "item": { "type": "object", "description": "The file to attach the task to.", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The ID of the file", "example": "11446498" }, "type": { "type": "string", "description": "`file`", "example": "file", "enum": [ "file" ] } } }, "action": { "type": "string", "description": "The action the task assignee will be prompted to do. Must be\n\n* `review` defines an approval task that can be approved or\nrejected\n* `complete` defines a general task which can be completed", "example": "review", "default": "review", "enum": [ "review", "complete" ] }, "message": { "type": "string", "default": "", "description": "An optional message to include with the task.", "example": "Please review" }, "due_at": { "type": "string", "format": "date-time", "description": "Defines when the task is due. Defaults to `null` if not\nprovided.", "example": "2012-12-12T10:53:43-08:00" }, "completion_rule": { "type": "string", "description": "Defines which assignees need to complete this task before the task\nis considered completed.\n\n* `all_assignees` (default) requires all assignees to review or\napprove the the task in order for it to be considered completed.\n* `any_assignee` accepts any one assignee to review or\napprove the the task in order for it to be considered completed.", "example": "all_assignees", "default": "all_assignees", "enum": [ "all_assignees", "any_assignee" ] } } } } } }, "responses": { "201": { "description": "Returns the newly created task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "400": { "description": "Returned if the request parameters or body is not valid.\n\n* `bad_request` when the body does not contain a valid request. This may\nbe because the `action` or `completion_rule` are not one of the allowed\nvalues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error when the user does not have the permission to create a\ntask on the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the file could not be found or the user does not\nhave access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/tasks/{task_id}": { "get": { "operationId": "get_tasks_id", "summary": "Get task", "tags": [ "Tasks" ], "x-box-tag": "tasks", "x-box-sanitized": true, "description": "Retrieves information about a specific task.", "parameters": [ { "name": "task_id", "description": "The ID of the task.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a task object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "404": { "description": "Returns an error when the task could not be found or the user does not\nhave access to the file the task is assigned to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "put": { "operationId": "put_tasks_id", "tags": [ "Tasks" ], "summary": "Update task", "x-box-tag": "tasks", "x-box-sanitized": true, "description": "Updates a task. This can be used to update a task's configuration, or to\nupdate its completion state.", "parameters": [ { "name": "task_id", "description": "The ID of the task.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "description": "The action the task assignee will be prompted to do. Must be\n\n* `review` defines an approval task that can be approved or\nrejected\n* `complete` defines a general task which can be completed", "example": "review", "enum": [ "review", "complete" ] }, "message": { "type": "string", "description": "The message included with the task.", "example": "Please review" }, "due_at": { "type": "string", "format": "date-time", "description": "When the task is due at.", "example": "2012-12-12T10:53:43-08:00" }, "completion_rule": { "type": "string", "description": "Defines which assignees need to complete this task before the task\nis considered completed.\n\n* `all_assignees` (default) requires all assignees to review or\napprove the the task in order for it to be considered completed.\n* `any_assignee` accepts any one assignee to review or\napprove the the task in order for it to be considered completed.", "example": "all_assignees", "enum": [ "all_assignees", "any_assignee" ] } } } } } }, "responses": { "200": { "description": "Returns the updated task object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "400": { "description": "Returned if the request parameters or body is not valid.\n\n* `bad_request` when the body does not contain a valid request. This may\nbe because the `action` or `completion_rule` are not one of the allowed\nvalues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error when the user does not have the permission to update a\ntask on the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the file could not be found or the user does not\nhave access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_tasks_id", "tags": [ "Tasks" ], "summary": "Remove task", "x-box-tag": "tasks", "x-box-sanitized": true, "description": "Removes a task from a file.", "parameters": [ { "name": "task_id", "description": "The ID of the task.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Returns an empty response when the task was successfully deleted." }, "404": { "description": "Returns an error when the task could not be found or the user does not\nhave access to the file the task is assigned to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/tasks/{task_id}/assignments": { "get": { "operationId": "get_tasks_id_assignments", "summary": "List task assignments", "tags": [ "Task assignments" ], "x-box-tag": "task_assignments", "x-box-sanitized": true, "description": "Lists all of the assignments for a given task.", "parameters": [ { "name": "task_id", "description": "The ID of the task.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a collection of task assignment defining what task on\na file has been assigned to which users and by who.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskAssignments" } } } }, "404": { "description": "Returns an error when the task could not be found or the user does not\nhave access to the file the task is assigned to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "500": { "description": "Returns an error if the task assignment ID was omitted in\nthe request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/task_assignments": { "post": { "operationId": "post_task_assignments", "summary": "Assign task", "tags": [ "Task assignments" ], "x-box-tag": "task_assignments", "x-box-sanitized": true, "description": "Assigns a task to a user.\n\nA task can be assigned to more than one user by creating multiple\nassignments.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "task", "assign_to" ], "properties": { "task": { "type": "object", "description": "The task to assign to a user.", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The ID of the task", "example": "11446498" }, "type": { "type": "string", "description": "The type of the item to assign.", "example": "task", "enum": [ "task" ] } } }, "assign_to": { "type": "object", "description": "The user to assign the task to.", "properties": { "id": { "type": "string", "description": "The ID of the user to assign to the\ntask.\n\nTo specify a user by their email\naddress use the `login` parameter.", "example": "3242343" }, "login": { "type": "string", "description": "The email address of the user to assign to the task.\nTo specify a user by their user ID please use the `id` parameter.", "example": "john@example.com" } } } } } } } }, "responses": { "201": { "description": "Returns a new task assignment object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskAssignment" } } } }, "403": { "description": "Returns an error if a change is attempted for a completed task or the user\ndoes not have access to the item linked to the task for the given task\nassignment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the task cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "500": { "description": "Returns an error if any of the IDs for this request were not valid, or if\nthe targeted user does not have access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/task_assignments/{task_assignment_id}": { "get": { "operationId": "get_task_assignments_id", "summary": "Get task assignment", "tags": [ "Task assignments" ], "x-box-tag": "task_assignments", "x-box-sanitized": true, "description": "Retrieves information about a task assignment.", "parameters": [ { "name": "task_assignment_id", "description": "The ID of the task assignment.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a task assignment, specifying who the task has been assigned to\nand by whom.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskAssignment" } } } }, "404": { "description": "Returns an error when the task assignment could not be found or the user\ndoes not have access to the file the task is assigned to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "put": { "operationId": "put_task_assignments_id", "summary": "Update task assignment", "tags": [ "Task assignments" ], "x-box-tag": "task_assignments", "x-box-sanitized": true, "description": "Updates a task assignment. This endpoint can be\nused to update the state of a task assigned to a user.", "parameters": [ { "name": "task_assignment_id", "description": "The ID of the task assignment.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "An optional message by the assignee that can be added to the task.", "example": "Looks good to me" }, "resolution_state": { "type": "string", "description": "The state of the task assigned to the user.\n\n* For a task with an `action` value of `complete` this can be\n`incomplete` or `completed`.\n* For a task with an `action` of `review` this can be\n`incomplete`, `approved`, or `rejected`.", "example": "completed", "enum": [ "completed", "incomplete", "approved", "rejected" ] } } } } } }, "responses": { "200": { "description": "Returns the updated task assignment object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskAssignment" } } } }, "400": { "description": "Returns an error if a resolution state is incompatible with the action\ntype of the task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the task assignment could not be found or the user\ndoes not have access to the file the task is assigned to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_task_assignments_id", "summary": "Unassign task", "tags": [ "Task assignments" ], "x-box-tag": "task_assignments", "x-box-sanitized": true, "description": "Deletes a specific task assignment.", "parameters": [ { "name": "task_assignment_id", "description": "The ID of the task assignment.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Returns an empty response when the task\nassignment was successfully deleted." }, "404": { "description": "Returns an error if the task assignment for the given ID does not exist\nor is inaccessible to your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/shared_items": { "get": { "operationId": "get_shared_items", "summary": "Find file for shared link", "tags": [ "Shared links (Files)" ], "x-box-tag": "shared_links_files", "x-box-enable-explorer": true, "description": "Returns the file represented by a shared link.\n\nA shared file can be represented by a shared link,\nwhich can originate within the current enterprise or within another.\n\nThis endpoint allows an application to retrieve information about a\nshared file when only given a shared link.\n\nThe `shared_link_permission_options` array field can be returned\nby requesting it in the `fields` query parameter.", "parameters": [ { "name": "if-none-match", "description": "Ensures an item is only returned if it has changed.\n\nPass in the item's last observed `etag` value\ninto this header and the endpoint will fail\nwith a `304 Not Modified` if the item has not\nchanged since.", "in": "header", "required": false, "example": "1", "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "boxapi", "description": "A header containing the shared link and optional password for the\nshared link.\n\nThe format for this header is as follows.\n\n`shared_link=[link]&shared_link_password=[password]`", "example": "shared_link=[link]&shared_link_password=[password]", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a full file resource if the shared link is valid and\nthe user has access to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File--Full" } } } }, "304": { "description": "Returns an empty response when the `If-None-Match` header matches\nthe current `etag` value of the folder. This indicates that the folder\nhas not changed since it was last requested." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/files/{file_id}#get_shared_link": { "get": { "operationId": "get_files_id#get_shared_link", "summary": "Get shared link for file", "tags": [ "Shared links (Files)" ], "x-box-tag": "shared_links_files", "x-box-enable-explorer": true, "x-box-sanitized": true, "description": "Gets the information for a shared link on a file.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "example": "shared_link", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the base representation of a file with the\nadditional shared link information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File--Full" }, "examples": { "default": { "value": { "id": "12345", "type": "file", "etag": "1", "shared_link": { "url": "https://app.box.com/s/kwio6b4ovt1264rnfbyqo1", "download_url": "https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf", "vanity_url": null, "vanity_name": null, "effective_access": "open", "effective_permission": "can_download", "is_password_enabled": false, "unshared_at": "2020-09-21T10:34:41-07:00", "download_count": 0, "preview_count": 0, "access": "open", "permissions": { "can_preview": true, "can_download": true, "can_edit": true } } } } } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file is not found, or the user does not\nhave access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `file_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/files/{file_id}#add_shared_link": { "put": { "operationId": "put_files_id#add_shared_link", "summary": "Add shared link to file", "tags": [ "Shared links (Files)" ], "x-box-tag": "shared_links_files", "x-box-enable-explorer": true, "x-box-sanitized": true, "description": "Adds a shared link to a file.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "example": "shared_link", "in": "query", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "shared_link": { "description": "The settings for the shared link to create on the file.\nUse an empty object (`{}`) to use the default settings for shared\nlinks.", "type": "object", "properties": { "access": { "type": "string", "description": "The level of access for the shared link. This can be\nrestricted to anyone with the link (`open`), only people\nwithin the company (`company`) and only those who\nhave been invited to the file (`collaborators`).\n\nIf not set, this field defaults to the access level specified\nby the enterprise admin. To create a shared link with this\ndefault setting pass the `shared_link` object with\nno `access` field, for example `{ \"shared_link\": {} }`.\n\nThe `company` access level is only available to paid\naccounts.", "enum": [ "open", "company", "collaborators" ], "example": "open" }, "password": { "type": "string", "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\n\nA password can only be set when `access` is set to `open`.", "example": "do-not-use-this-password" }, "vanity_name": { "type": "string", "description": "Defines a custom vanity name to use in the shared link URL,\nfor example `https://app.box.com/v/my-shared-link`.\n\nCustom URLs should not be used when sharing sensitive content\nas vanity URLs are a lot easier to guess than regular shared\nlinks.", "minLength": 12, "example": "my-shared-link" }, "unshared_at": { "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "description": "The timestamp at which this shared link will\nexpire. This field can only be set by\nusers with paid accounts. The value must be greater than the\ncurrent date and time." }, "permissions": { "type": "object", "properties": { "can_download": { "type": "boolean", "example": true, "description": "If the shared link allows for downloading of files.\nThis can only be set when `access` is set to\n`open` or `company`." }, "can_preview": { "type": "boolean", "example": true, "description": "If the shared link allows for previewing of files.\nThis value is always `true`. For shared links on folders\nthis also applies to any items in the folder." }, "can_edit": { "type": "boolean", "example": true, "description": "If the shared link allows for editing of files.\nThis can only be set when `access` is set to\n`open` or `company`.\nThis value can only be `true` is `can_download` is\nalso `true`." } } } } } } } } } }, "responses": { "200": { "description": "Returns the base representation of a file with a new shared\nlink attached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File--Full" }, "examples": { "default": { "value": { "id": "12345", "type": "file", "etag": "1", "shared_link": { "url": "https://app.box.com/s/kwio6b4ovt1264rnfbyqo1", "download_url": "https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf", "vanity_url": null, "vanity_name": null, "effective_access": "open", "effective_permission": "can_download", "is_password_enabled": false, "unshared_at": "2020-09-21T10:34:41-07:00", "download_count": 0, "preview_count": 0, "access": "open", "permissions": { "can_preview": true, "can_download": true, "can_edit": true } } } } } } } }, "400": { "description": "Returned when there is an incorrect permission combination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned if the user does not have all the permissions to complete the\nupdate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file is not found, or the user does not\nhave access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `file_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the file. This indicates that the file\nhas changed since it was last requested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/files/{file_id}#update_shared_link": { "put": { "operationId": "put_files_id#update_shared_link", "summary": "Update shared link on file", "tags": [ "Shared links (Files)" ], "x-box-tag": "shared_links_files", "x-box-enable-explorer": true, "x-box-sanitized": true, "description": "Updates a shared link on a file.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "example": "shared_link", "in": "query", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "shared_link": { "description": "The settings for the shared link to update.", "type": "object", "properties": { "access": { "type": "string", "description": "The level of access for the shared link. This can be\nrestricted to anyone with the link (`open`), only people\nwithin the company (`company`) and only those who\nhave been invited to the folder (`collaborators`).\n\nIf not set, this field defaults to the access level specified\nby the enterprise admin. To create a shared link with this\ndefault setting pass the `shared_link` object with\nno `access` field, for example `{ \"shared_link\": {} }`.\n\nThe `company` access level is only available to paid\naccounts.", "enum": [ "open", "company", "collaborators" ], "example": "open" }, "password": { "type": "string", "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\n\nA password can only be set when `access` is set to `open`.", "example": "do-not-use-this-password" }, "vanity_name": { "type": "string", "description": "Defines a custom vanity name to use in the shared link URL,\nfor example `https://app.box.com/v/my-shared-link`.\n\nCustom URLs should not be used when sharing sensitive content\nas vanity URLs are a lot easier to guess than regular shared\nlinks.", "minLength": 12, "example": "my-shared-link" }, "unshared_at": { "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "description": "The timestamp at which this shared link will\nexpire. This field can only be set by\nusers with paid accounts. The value must be greater than the\ncurrent date and time." }, "permissions": { "type": "object", "properties": { "can_download": { "type": "boolean", "example": true, "description": "If the shared link allows for downloading of files.\nThis can only be set when `access` is set to\n`open` or `company`." }, "can_preview": { "type": "boolean", "example": true, "description": "If the shared link allows for previewing of files.\nThis value is always `true`. For shared links on folders\nthis also applies to any items in the folder." }, "can_edit": { "type": "boolean", "example": true, "description": "If the shared link allows for editing of files.\nThis can only be set when `access` is set to\n`open` or `company`.\nThis value can only be `true` is `can_download` is\nalso `true`." } } } } } } } } } }, "responses": { "200": { "description": "Returns a basic representation of the file, with the updated shared\nlink attached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File--Full" }, "examples": { "default": { "value": { "id": "12345", "type": "file", "etag": "1", "shared_link": { "url": "https://app.box.com/s/kwio6b4ovt1264rnfbyqo1", "download_url": "https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf", "vanity_url": null, "vanity_name": null, "effective_access": "open", "effective_permission": "can_download", "is_password_enabled": false, "unshared_at": "2020-09-21T10:34:41-07:00", "download_count": 0, "preview_count": 0, "access": "open", "permissions": { "can_preview": true, "can_download": true, "can_edit": true } } } } } } } }, "400": { "description": "Returned when there is an incorrect permission combination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned if the user does not have all the permissions to complete the\nupdate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file is not found, or the user does not\nhave access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `file_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the file. This indicates that the file\nhas changed since it was last requested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/files/{file_id}#remove_shared_link": { "put": { "operationId": "put_files_id#remove_shared_link", "summary": "Remove shared link from file", "tags": [ "Shared links (Files)" ], "x-box-tag": "shared_links_files", "x-box-enable-explorer": true, "x-box-sanitized": true, "description": "Removes a shared link from a file.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "example": "shared_link", "in": "query", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "shared_link": { "description": "By setting this value to `null`, the shared link\nis removed from the file.", "type": "object", "example": null, "nullable": true } } } } } }, "responses": { "200": { "description": "Returns a basic representation of a file, with the shared link removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File--Full" }, "examples": { "default": { "value": { "id": "12345", "type": "file", "etag": "1", "shared_link": null } } } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned if the user does not have all the permissions to complete the\nupdate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file is not found, or the user does not\nhave access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `file_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the file. This indicates that the file\nhas changed since it was last requested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/shared_items#folders": { "get": { "operationId": "get_shared_items#folders", "summary": "Find folder for shared link", "tags": [ "Shared links (Folders)" ], "x-box-tag": "shared_links_folders", "x-box-enable-explorer": true, "description": "Return the folder represented by a shared link.\n\nA shared folder can be represented by a shared link,\nwhich can originate within the current enterprise or within another.\n\nThis endpoint allows an application to retrieve information about a\nshared folder when only given a shared link.", "parameters": [ { "name": "if-none-match", "description": "Ensures an item is only returned if it has changed.\n\nPass in the item's last observed `etag` value\ninto this header and the endpoint will fail\nwith a `304 Not Modified` if the item has not\nchanged since.", "in": "header", "required": false, "example": "1", "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "boxapi", "description": "A header containing the shared link and optional password for the\nshared link.\n\nThe format for this header is as follows.\n\n`shared_link=[link]&shared_link_password=[password]`", "example": "shared_link=[link]&shared_link_password=[password]", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a full folder resource if the shared link is valid and\nthe user has access to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder--Full" } } } }, "304": { "description": "Returns an empty response when the `If-None-Match` header matches\nthe current `etag` value of the folder. This indicates that the folder\nhas not changed since it was last requested." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/folders/{folder_id}#get_shared_link": { "get": { "operationId": "get_folders_id#get_shared_link", "summary": "Get shared link for folder", "tags": [ "Shared links (Folders)" ], "x-box-tag": "shared_links_folders", "x-box-enable-explorer": true, "x-box-sanitized": true, "description": "Gets the information for a shared link on a folder.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string", "nullable": false } }, { "name": "fields", "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "example": "shared_link", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the base representation of a folder with the\nadditional shared link information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder--Full" }, "examples": { "default": { "value": { "id": "12345", "type": "folder", "etag": "1", "shared_link": { "url": "https://app.box.com/s/kwio6b4ovt1264rnfbyqo1", "download_url": "https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf", "vanity_url": null, "vanity_name": null, "effective_access": "open", "effective_permission": "can_download", "is_password_enabled": false, "unshared_at": "2020-09-21T10:34:41-07:00", "download_count": 0, "preview_count": 0, "access": "open", "permissions": { "can_preview": true, "can_download": true, "can_edit": false } } } } } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the folder is not found, or the user does not\nhave access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `folder_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/folders/{folder_id}#add_shared_link": { "put": { "operationId": "put_folders_id#add_shared_link", "summary": "Add shared link to folder", "tags": [ "Shared links (Folders)" ], "x-box-tag": "shared_links_folders", "x-box-enable-explorer": true, "x-box-sanitized": true, "description": "Adds a shared link to a folder.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string", "nullable": false } }, { "name": "fields", "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "example": "shared_link", "in": "query", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "shared_link": { "description": "The settings for the shared link to create on the folder.\n\nUse an empty object (`{}`) to use the default settings for shared\nlinks.", "type": "object", "properties": { "access": { "type": "string", "description": "The level of access for the shared link. This can be\nrestricted to anyone with the link (`open`), only people\nwithin the company (`company`) and only those who\nhave been invited to the folder (`collaborators`).\n\nIf not set, this field defaults to the access level specified\nby the enterprise admin. To create a shared link with this\ndefault setting pass the `shared_link` object with\nno `access` field, for example `{ \"shared_link\": {} }`.\n\nThe `company` access level is only available to paid\naccounts.", "enum": [ "open", "company", "collaborators" ], "example": "open" }, "password": { "type": "string", "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\n\nA password can only be set when `access` is set to `open`.", "example": "do-not-use-this-password" }, "vanity_name": { "type": "string", "description": "Defines a custom vanity name to use in the shared link URL,\nfor example `https://app.box.com/v/my-shared-link`.\n\nCustom URLs should not be used when sharing sensitive content\nas vanity URLs are a lot easier to guess than regular shared\nlinks.", "minLength": 12, "example": "my-shared-link" }, "unshared_at": { "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "description": "The timestamp at which this shared link will\nexpire. This field can only be set by\nusers with paid accounts. The value must be greater than the\ncurrent date and time." }, "permissions": { "type": "object", "properties": { "can_download": { "type": "boolean", "example": true, "description": "If the shared link allows for downloading of files.\nThis can only be set when `access` is set to\n`open` or `company`." }, "can_preview": { "type": "boolean", "example": true, "description": "If the shared link allows for previewing of files.\nThis value is always `true`. For shared links on folders\nthis also applies to any items in the folder." }, "can_edit": { "type": "boolean", "example": false, "description": "This value can only be `false` for items\nwith a `type` of `folder`." } } } } } } } } } }, "responses": { "200": { "description": "Returns the base representation of a folder with a new shared\nlink attached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder--Full" }, "examples": { "default": { "value": { "id": "12345", "type": "folder", "etag": "1", "shared_link": { "url": "https://app.box.com/s/kwio6b4ovt1264rnfbyqo1", "download_url": "https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf", "vanity_url": null, "vanity_name": null, "effective_access": "open", "effective_permission": "can_download", "is_password_enabled": false, "unshared_at": "2020-09-21T10:34:41-07:00", "download_count": 0, "preview_count": 0, "access": "open", "permissions": { "can_preview": true, "can_download": true, "can_edit": false } } } } } } } }, "400": { "description": "Returned when there is an incorrect permission combination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned if the user does not have all the permissions to complete the\nupdate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the folder is not found, or the user does not\nhave access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `folder_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the folder. This indicates that the folder\nhas changed since it was last requested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/folders/{folder_id}#update_shared_link": { "put": { "operationId": "put_folders_id#update_shared_link", "summary": "Update shared link on folder", "tags": [ "Shared links (Folders)" ], "x-box-tag": "shared_links_folders", "x-box-enable-explorer": true, "x-box-sanitized": true, "description": "Updates a shared link on a folder.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string", "nullable": false } }, { "name": "fields", "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "example": "shared_link", "in": "query", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "shared_link": { "description": "The settings for the shared link to update.", "type": "object", "properties": { "access": { "type": "string", "description": "The level of access for the shared link. This can be\nrestricted to anyone with the link (`open`), only people\nwithin the company (`company`) and only those who\nhave been invited to the folder (`collaborators`).\n\nIf not set, this field defaults to the access level specified\nby the enterprise admin. To create a shared link with this\ndefault setting pass the `shared_link` object with\nno `access` field, for example `{ \"shared_link\": {} }`.\n\nThe `company` access level is only available to paid\naccounts.", "enum": [ "open", "company", "collaborators" ], "example": "open" }, "password": { "type": "string", "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\n\nA password can only be set when `access` is set to `open`.", "example": "do-not-use-this-password" }, "vanity_name": { "type": "string", "description": "Defines a custom vanity name to use in the shared link URL,\nfor example `https://app.box.com/v/my-shared-link`.\n\nCustom URLs should not be used when sharing sensitive content\nas vanity URLs are a lot easier to guess than regular shared\nlinks.", "minLength": 12, "example": "my-shared-link" }, "unshared_at": { "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "description": "The timestamp at which this shared link will\nexpire. This field can only be set by\nusers with paid accounts. The value must be greater than the\ncurrent date and time." }, "permissions": { "type": "object", "properties": { "can_download": { "type": "boolean", "example": true, "description": "If the shared link allows for downloading of files.\nThis can only be set when `access` is set to\n`open` or `company`." }, "can_preview": { "type": "boolean", "example": true, "description": "If the shared link allows for previewing of files.\nThis value is always `true`. For shared links on folders\nthis also applies to any items in the folder." }, "can_edit": { "type": "boolean", "example": false, "description": "This value can only be `false` for items\nwith a `type` of `folder`." } } } } } } } } } }, "responses": { "200": { "description": "Returns a basic representation of the folder, with the updated shared\nlink attached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder--Full" }, "examples": { "default": { "value": { "id": "12345", "type": "folder", "etag": "1", "shared_link": { "url": "https://app.box.com/s/kwio6b4ovt1264rnfbyqo1", "download_url": "https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf", "vanity_url": null, "vanity_name": null, "effective_access": "open", "effective_permission": "can_download", "is_password_enabled": false, "unshared_at": "2020-09-21T10:34:41-07:00", "download_count": 0, "preview_count": 0, "access": "open", "permissions": { "can_preview": true, "can_download": true, "can_edit": false } } } } } } } }, "400": { "description": "Returned when there is an incorrect permission combination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned if the user does not have all the permissions to complete the\nupdate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the folder is not found, or the user does not\nhave access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `folder_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the folder. This indicates that the folder\nhas changed since it was last requested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/folders/{folder_id}#remove_shared_link": { "put": { "operationId": "put_folders_id#remove_shared_link", "summary": "Remove shared link from folder", "tags": [ "Shared links (Folders)" ], "x-box-tag": "shared_links_folders", "x-box-enable-explorer": true, "x-box-sanitized": true, "description": "Removes a shared link from a folder.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string", "nullable": false } }, { "name": "fields", "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "example": "shared_link", "in": "query", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "shared_link": { "description": "By setting this value to `null`, the shared link\nis removed from the folder.", "type": "object", "example": null, "nullable": true } } } } } }, "responses": { "200": { "description": "Returns a basic representation of a folder, with the shared link removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder--Full" }, "examples": { "default": { "value": { "id": "12345", "type": "folder", "etag": "1", "shared_link": null } } } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned if the user does not have all the permissions to complete the\nupdate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the folder is not found, or the user does not\nhave access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `folder_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the folder. This indicates that the folder\nhas changed since it was last requested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/web_links": { "post": { "operationId": "post_web_links", "summary": "Create web link", "tags": [ "Web links" ], "x-box-tag": "web_links", "description": "Creates a web link object within a folder.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "parent", "url" ], "properties": { "url": { "type": "string", "example": "https://box.com", "description": "The URL that this web link links to. Must start with\n`\"http://\"` or `\"https://\"`." }, "parent": { "type": "object", "description": "The parent folder to create the web link within.", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The ID of parent folder", "example": "0" } } }, "name": { "type": "string", "example": "Box Website", "description": "Name of the web link. Defaults to the URL if not set." }, "description": { "type": "string", "example": "Cloud Content Management", "description": "Description of the web link." }, "shared_link": { "description": "The settings for the shared link to update.", "type": "object", "properties": { "access": { "type": "string", "description": "The level of access for the shared link. This can be\nrestricted to anyone with the link (`open`), only people\nwithin the company (`company`) and only those who\nhave been invited to the folder (`collaborators`).\n\nIf not set, this field defaults to the access level specified\nby the enterprise admin. To create a shared link with this\ndefault setting pass the `shared_link` object with\nno `access` field, for example `{ \"shared_link\": {} }`.\n\nThe `company` access level is only available to paid\naccounts.", "enum": [ "open", "company", "collaborators" ], "example": "open" }, "password": { "type": "string", "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\n\nA password can only be set when `access` is set to `open`.", "example": "do-not-use-this-password" }, "vanity_name": { "type": "string", "description": "Defines a custom vanity name to use in the shared link URL,\nfor example `https://app.box.com/v/my-shared-link`.\n\nCustom URLs should not be used when sharing sensitive content\nas vanity URLs are a lot easier to guess than regular shared\nlinks.", "minLength": 12, "example": "my-shared-link" }, "unshared_at": { "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "description": "The timestamp at which this shared link will\nexpire. This field can only be set by\nusers with paid accounts. The value must be greater than the\ncurrent date and time." } } } } } } } }, "responses": { "200": { "description": "Returns the newly created web link object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebLink" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/web_links/{web_link_id}": { "get": { "operationId": "get_web_links_id", "summary": "Get web link", "tags": [ "Web links" ], "x-box-tag": "web_links", "description": "Retrieve information about a web link.", "parameters": [ { "name": "web_link_id", "description": "The ID of the web link.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "boxapi", "description": "The URL, and optional password, for the shared link of this item.\n\nThis header can be used to access items that have not been\nexplicitly shared with a user.\n\nUse the format `shared_link=[link]` or if a password is required then\nuse `shared_link=[link]&shared_link_password=[password]`.\n\nThis header can be used on the file or folder shared, as well as on any files\nor folders nested within the item.", "example": "shared_link=[link]&shared_link_password=[password]", "in": "header", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the web link object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebLink" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_web_links_id", "summary": "Restore web link", "tags": [ "Trashed web links" ], "x-box-tag": "trashed_web_links", "description": "Restores a web link that has been moved to the trash.\n\nAn optional new parent ID can be provided to restore the web link to in case\nthe original folder has been deleted.", "parameters": [ { "name": "web_link_id", "description": "The ID of the web link.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "An optional new name for the web link.", "example": "Restored.docx", "type": "string" }, "parent": { "allOf": [ { "type": "object", "description": "The parent for this item", "properties": { "id": { "type": "string", "description": "The ID of parent item", "example": "123" } } }, { "description": "Specifies an optional ID of a folder to restore the web link\nto when the original folder no longer exists.\n\nPlease be aware that this ID will only be used if the original\nfolder no longer exists. Use this ID to provide a fallback\nlocation to restore the web link to if the original location\nhas been deleted." } ] } } } } } }, "responses": { "201": { "description": "Returns a web link object when it has been restored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrashWebLinkRestored" } } } }, "403": { "description": "Returns an error if the user does not have access to the folder\nthe web link is being restored to, or the user does not have permission\nto restore web link from the trash.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the web link is not in the trash.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error if there is an web link with the same name\nin the folder the web link is being restored to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "put": { "operationId": "put_web_links_id", "summary": "Update web link", "tags": [ "Web links" ], "x-box-tag": "web_links", "description": "Updates a web link object.", "parameters": [ { "name": "web_link_id", "description": "The ID of the web link.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "example": "https://box.com", "description": "The new URL that the web link links to. Must start with\n`\"http://\"` or `\"https://\"`." }, "parent": { "allOf": [ { "type": "object", "description": "The parent for this item", "properties": { "id": { "type": "string", "description": "The ID of parent item", "example": "123" } } }, { "description": "The new parent folder to put the web link in.\nUse this to move the web link to a different folder." } ] }, "name": { "type": "string", "example": "Box Website", "description": "A new name for the web link. Defaults to the URL if not set." }, "description": { "type": "string", "example": "Cloud Content Management", "description": "A new description of the web link." }, "shared_link": { "description": "The settings for the shared link to update.", "type": "object", "properties": { "access": { "type": "string", "description": "The level of access for the shared link. This can be\nrestricted to anyone with the link (`open`), only people\nwithin the company (`company`) and only those who\nhave been invited to the folder (`collaborators`).\n\nIf not set, this field defaults to the access level specified\nby the enterprise admin. To create a shared link with this\ndefault setting pass the `shared_link` object with\nno `access` field, for example `{ \"shared_link\": {} }`.\n\nThe `company` access level is only available to paid\naccounts.", "enum": [ "open", "company", "collaborators" ], "example": "open" }, "password": { "type": "string", "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\n\nA password can only be set when `access` is set to `open`.", "example": "do-not-use-this-password" }, "vanity_name": { "type": "string", "description": "Defines a custom vanity name to use in the shared link URL,\nfor example `https://app.box.com/v/my-shared-link`.\n\nCustom URLs should not be used when sharing sensitive content\nas vanity URLs are a lot easier to guess than regular shared\nlinks.", "minLength": 12, "example": "my-shared-link" }, "unshared_at": { "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "description": "The timestamp at which this shared link will\nexpire. This field can only be set by\nusers with paid accounts. The value must be greater than the\ncurrent date and time." } } } } } } } }, "responses": { "200": { "description": "Returns the updated web link object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebLink" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_web_links_id", "summary": "Remove web link", "tags": [ "Web links" ], "x-box-tag": "web_links", "description": "Deletes a web link.", "parameters": [ { "name": "web_link_id", "description": "The ID of the web link.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "An empty response will be returned when the web link\nwas successfully deleted." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/web_links/{web_link_id}/trash": { "get": { "operationId": "get_web_links_id_trash", "summary": "Get trashed web link", "tags": [ "Trashed web links" ], "x-box-tag": "trashed_web_links", "description": "Retrieves a web link that has been moved to the trash.", "parameters": [ { "name": "web_link_id", "description": "The ID of the web link.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Returns the web link that was trashed,\nincluding information about when the it\nwas moved to the trash.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrashWebLink" } } } }, "404": { "description": "Returns an error if the web link is not in the trash.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_web_links_id_trash", "summary": "Permanently remove web link", "tags": [ "Trashed web links" ], "x-box-tag": "trashed_web_links", "description": "Permanently deletes a web link that is in the trash.\nThis action cannot be undone.", "parameters": [ { "name": "web_link_id", "description": "The ID of the web link.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Returns an empty response when the web link was\npermanently deleted." }, "404": { "description": "Returns an error if the web link is not in the trash.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/shared_items#web_links": { "get": { "operationId": "get_shared_items#web_links", "summary": "Find web link for shared link", "tags": [ "Shared links (Web Links)" ], "x-box-tag": "shared_links_web_links", "x-box-enable-explorer": true, "description": "Returns the web link represented by a shared link.\n\nA shared web link can be represented by a shared link,\nwhich can originate within the current enterprise or within another.\n\nThis endpoint allows an application to retrieve information about a\nshared web link when only given a shared link.", "parameters": [ { "name": "if-none-match", "description": "Ensures an item is only returned if it has changed.\n\nPass in the item's last observed `etag` value\ninto this header and the endpoint will fail\nwith a `304 Not Modified` if the item has not\nchanged since.", "in": "header", "required": false, "example": "1", "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "boxapi", "description": "A header containing the shared link and optional password for the\nshared link.\n\nThe format for this header is as follows.\n\n`shared_link=[link]&shared_link_password=[password]`", "example": "shared_link=[link]&shared_link_password=[password]", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a full file resource if the shared link is valid and\nthe user has access to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebLink" } } } }, "304": { "description": "Returns an empty response when the `If-None-Match` header matches\nthe current `etag` value of the folder. This indicates that the folder\nhas not changed since it was last requested." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/web_links/{web_link_id}#get_shared_link": { "get": { "operationId": "get_web_links_id#get_shared_link", "summary": "Get shared link for web link", "tags": [ "Shared links (Web Links)" ], "x-box-tag": "shared_links_web_links", "x-box-enable-explorer": true, "x-box-sanitized": true, "description": "Gets the information for a shared link on a web link.", "parameters": [ { "name": "web_link_id", "description": "The ID of the web link.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "example": "shared_link", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the base representation of a web link with the\nadditional shared link information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebLink" }, "examples": { "default": { "value": { "id": "12345", "type": "web_link", "etag": "1", "shared_link": { "url": "https://app.box.com/s/kwio6b4ovt1264rnfbyqo1", "download_url": "https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf", "vanity_url": null, "vanity_name": null, "effective_access": "open", "effective_permission": "can_download", "is_password_enabled": false, "unshared_at": "2020-09-21T10:34:41-07:00", "download_count": 0, "preview_count": 0, "access": "open", "permissions": { "can_preview": true, "can_download": true, "can_edit": false } } } } } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file is not found, or the user does not\nhave access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `file_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/web_links/{web_link_id}#add_shared_link": { "put": { "operationId": "put_web_links_id#add_shared_link", "summary": "Add shared link to web link", "tags": [ "Shared links (Web Links)" ], "x-box-tag": "shared_links_web_links", "x-box-enable-explorer": true, "x-box-sanitized": true, "description": "Adds a shared link to a web link.", "parameters": [ { "name": "web_link_id", "description": "The ID of the web link.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "example": "shared_link", "in": "query", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "shared_link": { "description": "The settings for the shared link to create on the web link.\n\nUse an empty object (`{}`) to use the default settings for shared\nlinks.", "type": "object", "properties": { "access": { "type": "string", "description": "The level of access for the shared link. This can be\nrestricted to anyone with the link (`open`), only people\nwithin the company (`company`) and only those who\nhave been invited to the file (`collaborators`).\n\nIf not set, this field defaults to the access level specified\nby the enterprise admin. To create a shared link with this\ndefault setting pass the `shared_link` object with\nno `access` field, for example `{ \"shared_link\": {} }`.\n\nThe `company` access level is only available to paid\naccounts.", "enum": [ "open", "company", "collaborators" ], "example": "open" }, "password": { "type": "string", "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\n\nA password can only be set when `access` is set to `open`.", "example": "do-not-use-this-password" }, "vanity_name": { "type": "string", "description": "Defines a custom vanity name to use in the shared link URL,\nfor example `https://app.box.com/v/my-shared-link`.\n\nCustom URLs should not be used when sharing sensitive content\nas vanity URLs are a lot easier to guess than regular shared\nlinks.", "minLength": 12, "example": "my-shared-link" }, "unshared_at": { "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "description": "The timestamp at which this shared link will\nexpire. This field can only be set by\nusers with paid accounts. The value must be greater than the\ncurrent date and time." }, "permissions": { "type": "object", "properties": { "can_download": { "type": "boolean", "example": true, "description": "If the shared link allows for downloading of files.\nThis can only be set when `access` is set to\n`open` or `company`." }, "can_preview": { "type": "boolean", "example": true, "description": "If the shared link allows for previewing of files.\nThis value is always `true`. For shared links on folders\nthis also applies to any items in the folder." }, "can_edit": { "type": "boolean", "example": false, "description": "This value can only be `true` is `type` is `file`." } } } } } } } } } }, "responses": { "200": { "description": "Returns the base representation of a web link with a new shared\nlink attached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebLink" }, "examples": { "default": { "value": { "id": "12345", "type": "web_link", "etag": "1", "shared_link": { "url": "https://app.box.com/s/kwio6b4ovt1264rnfbyqo1", "download_url": "https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf", "vanity_url": null, "vanity_name": null, "effective_access": "open", "effective_permission": "can_download", "is_password_enabled": false, "unshared_at": "2020-09-21T10:34:41-07:00", "download_count": 0, "preview_count": 0, "access": "open", "permissions": { "can_preview": true, "can_download": true, "can_edit": false } } } } } } } }, "400": { "description": "Returned when there is an incorrect permission combination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned if the user does not have all the permissions to complete the\nupdate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file is not found, or the user does not\nhave access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `file_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the file. This indicates that the file\nhas changed since it was last requested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/web_links/{web_link_id}#update_shared_link": { "put": { "operationId": "put_web_links_id#update_shared_link", "summary": "Update shared link on web link", "tags": [ "Shared links (Web Links)" ], "x-box-tag": "shared_links_web_links", "x-box-enable-explorer": true, "x-box-sanitized": true, "description": "Updates a shared link on a web link.", "parameters": [ { "name": "web_link_id", "description": "The ID of the web link.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "example": "shared_link", "in": "query", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "shared_link": { "description": "The settings for the shared link to update.", "type": "object", "properties": { "access": { "type": "string", "description": "The level of access for the shared link. This can be\nrestricted to anyone with the link (`open`), only people\nwithin the company (`company`) and only those who\nhave been invited to the folder (`collaborators`).\n\nIf not set, this field defaults to the access level specified\nby the enterprise admin. To create a shared link with this\ndefault setting pass the `shared_link` object with\nno `access` field, for example `{ \"shared_link\": {} }`.\n\nThe `company` access level is only available to paid\naccounts.", "enum": [ "open", "company", "collaborators" ], "example": "open" }, "password": { "type": "string", "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\n\nA password can only be set when `access` is set to `open`.", "example": "do-not-use-this-password" }, "vanity_name": { "type": "string", "description": "Defines a custom vanity name to use in the shared link URL,\nfor example `https://app.box.com/v/my-shared-link`.\n\nCustom URLs should not be used when sharing sensitive content\nas vanity URLs are a lot easier to guess than regular shared\nlinks.", "minLength": 12, "example": "my-shared-link" }, "unshared_at": { "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "description": "The timestamp at which this shared link will\nexpire. This field can only be set by\nusers with paid accounts. The value must be greater than the\ncurrent date and time." }, "permissions": { "type": "object", "properties": { "can_download": { "type": "boolean", "example": true, "description": "If the shared link allows for downloading of files.\nThis can only be set when `access` is set to\n`open` or `company`." }, "can_preview": { "type": "boolean", "example": true, "description": "If the shared link allows for previewing of files.\nThis value is always `true`. For shared links on folders\nthis also applies to any items in the folder." }, "can_edit": { "type": "boolean", "example": true, "description": "This value can only be `true` is `type` is `file`." } } } } } } } } } }, "responses": { "200": { "description": "Returns a basic representation of the web link, with the updated shared\nlink attached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebLink" }, "examples": { "default": { "value": { "id": "12345", "type": "web_link", "etag": "1", "shared_link": { "url": "https://app.box.com/s/kwio6b4ovt1264rnfbyqo1", "download_url": "https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf", "vanity_url": null, "vanity_name": null, "effective_access": "open", "effective_permission": "can_download", "is_password_enabled": false, "unshared_at": "2020-09-21T10:34:41-07:00", "download_count": 0, "preview_count": 0, "access": "open", "permissions": { "can_preview": true, "can_download": true, "can_edit": false } } } } } } } }, "400": { "description": "Returned when there is an incorrect permission combination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned if the user does not have all the permissions to complete the\nupdate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file is not found, or the user does not\nhave access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `file_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the file. This indicates that the file\nhas changed since it was last requested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/web_links/{web_link_id}#remove_shared_link": { "put": { "operationId": "put_web_links_id#remove_shared_link", "summary": "Remove shared link from web link", "tags": [ "Shared links (Web Links)" ], "x-box-tag": "shared_links_web_links", "x-box-enable-explorer": true, "x-box-sanitized": true, "description": "Removes a shared link from a web link.", "parameters": [ { "name": "web_link_id", "description": "The ID of the web link.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "example": "shared_link", "in": "query", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "shared_link": { "description": "By setting this value to `null`, the shared link\nis removed from the web link.", "type": "object", "example": null, "nullable": true } } } } } }, "responses": { "200": { "description": "Returns a basic representation of a web link, with the\nshared link removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebLink" }, "examples": { "default": { "value": { "id": "12345", "type": "web_link", "etag": "1", "shared_link": null } } } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned if the user does not have all the permissions to complete the\nupdate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file is not found, or the user does not\nhave access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `file_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the file. This indicates that the file\nhas changed since it was last requested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/users": { "get": { "operationId": "get_users", "x-box-tag": "users", "summary": "List enterprise users", "tags": [ "Users" ], "description": "Returns a list of all users for the Enterprise along with their `user_id`,\n`public_name`, and `login`.\n\nThe application and the authenticated user need to\nhave the permission to look up users in the entire\nenterprise.", "parameters": [ { "name": "filter_term", "description": "Limits the results to only users who's `name` or\n`login` start with the search term.\n\nFor externally managed users, the search term needs\nto completely match the in order to find the user, and\nit will only return one user at a time.", "in": "query", "required": false, "example": "john", "schema": { "type": "string" } }, { "name": "user_type", "description": "Limits the results to the kind of user specified.\n\n* `all` returns every kind of user for whom the\n `login` or `name` partially matches the\n `filter_term`. It will only return an external user\n if the login matches the `filter_term` completely,\n and in that case it will only return that user.\n* `managed` returns all managed and app users for whom\n the `login` or `name` partially matches the\n `filter_term`.\n* `external` returns all external users for whom the\n `login` matches the `filter_term` exactly.", "in": "query", "required": false, "example": "managed", "schema": { "type": "string", "enum": [ "all", "managed", "external" ] } }, { "name": "external_app_user_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "my-user-1234", "description": "Limits the results to app users with the given\n`external_app_user_id` value.\n\nWhen creating an app user, an\n`external_app_user_id` value can be set. This value can\nthen be used in this endpoint to find any users that\nmatch that `external_app_user_id` value." }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "offset", "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } }, { "name": "usemarker", "description": "Specifies whether to use marker-based pagination instead of\noffset-based pagination. Only one pagination method can\nbe used at a time.\n\nBy setting this value to true, the API will return a `marker` field\nthat can be passed as a parameter to this endpoint to get the next\npage of the response.", "in": "query", "required": false, "example": true, "schema": { "type": "boolean" } }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns all of the users in the enterprise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Users" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_users", "summary": "Create user", "tags": [ "Users" ], "x-box-tag": "users", "description": "Creates a new managed user in an enterprise. This endpoint\nis only available to users and applications with the right\nadmin permissions.", "parameters": [ { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of the user", "example": "Aaron Levie", "maxLength": 50 }, "login": { "type": "string", "description": "The email address the user uses to log in\n\nRequired, unless `is_platform_access_only`\nis set to `true`.", "example": "boss@box.com" }, "is_platform_access_only": { "type": "boolean", "example": true, "description": "Specifies that the user is an app user." }, "role": { "type": "string", "enum": [ "coadmin", "user" ], "description": "The user’s enterprise role", "example": "user" }, "language": { "type": "string", "description": "The language of the user, formatted in modified version of the\n[ISO 639-1](/guides/api-calls/language-codes) format.", "example": "en" }, "is_sync_enabled": { "type": "boolean", "description": "Whether the user can use Box Sync", "example": true }, "job_title": { "type": "string", "description": "The user’s job title", "maxLength": 100, "example": "CEO" }, "phone": { "type": "string", "description": "The user’s phone number", "maxLength": 100, "example": "6509241374" }, "address": { "type": "string", "description": "The user’s address", "maxLength": 255, "example": "900 Jefferson Ave, Redwood City, CA 94063" }, "space_amount": { "type": "integer", "format": "int64", "description": "The user’s total available space in bytes. Set this to `-1` to\nindicate unlimited storage.", "example": 11345156112 }, "tracking_codes": { "type": "array", "items": { "$ref": "#/components/schemas/TrackingCode" }, "description": "Tracking codes allow an admin to generate reports from the\nadmin console and assign an attribute to a specific group\nof users. This setting must be enabled for an enterprise before it\ncan be used." }, "can_see_managed_users": { "type": "boolean", "example": true, "description": "Whether the user can see other enterprise users in their\ncontact list" }, "timezone": { "type": "string", "format": "timezone", "description": "The user's timezone", "example": "Africa/Bujumbura" }, "is_external_collab_restricted": { "type": "boolean", "example": true, "description": "Whether the user is allowed to collaborate with users outside\ntheir enterprise" }, "is_exempt_from_device_limits": { "type": "boolean", "example": true, "description": "Whether to exempt the user from enterprise device limits" }, "is_exempt_from_login_verification": { "type": "boolean", "example": true, "description": "Whether the user must use two-factor authentication" }, "status": { "type": "string", "enum": [ "active", "inactive", "cannot_delete_edit", "cannot_delete_edit_upload" ], "description": "The user's account status", "example": "active" }, "external_app_user_id": { "type": "string", "example": "my-user-1234", "description": "An external identifier for an app user, which can be used to look\nup the user. This can be used to tie user IDs from external\nidentity providers to Box users." } } } } } }, "responses": { "201": { "description": "Returns a user object for the newly created user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/users/me": { "get": { "operationId": "get_users_me", "x-box-tag": "users", "summary": "Get current user", "tags": [ "Users" ], "description": "Retrieves information about the user who is currently authenticated.\n\nIn the case of a client-side authenticated OAuth 2.0 application\nthis will be the user who authorized the app.\n\nIn the case of a JWT, server-side authenticated application\nthis will be the service account that belongs to the application\nby default.\n\nUse the `As-User` header to change who this API call is made on behalf of.", "parameters": [ { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Returns a single user object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User--Full" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/users/terminate_sessions": { "post": { "operationId": "post_users_terminate_sessions", "summary": "Create jobs to terminate users session", "tags": [ "Users" ], "x-box-tag": "session_termination", "description": "Validates the roles and permissions of the user,\nand creates asynchronous jobs\nto terminate the user's sessions.\nReturns the status for the POST request.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "user_ids", "user_logins" ], "properties": { "user_ids": { "example": [ "123456", "456789" ], "type": "array", "description": "A list of user IDs", "items": { "type": "string" } }, "user_logins": { "example": [ "user@sample.com", "user2@sample.com" ], "type": "array", "description": "A list of user logins", "items": { "type": "string" } } } } } } }, "responses": { "202": { "description": "Returns a message about the request status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionTerminationMessage" } } } }, "400": { "description": "Returns an error if some of the parameters are\n not valid.\n\n * `Users can not be NULL or EMPTY` when no value is provided\n * `User id format is string` when the provided user id format\n is incorrect\n * `Supported payload format is JSON` when the provided payload\n format is incorrect", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error if there are insufficient permissions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the resource could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returns an error if the rate limit is exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "500": { "description": "Returns an error if there is an internal server issue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "503": { "description": "Returns an error if the request timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/users/{user_id}": { "get": { "operationId": "get_users_id", "x-box-tag": "users", "summary": "Get user", "tags": [ "Users" ], "description": "Retrieves information about a user in the enterprise.\n\nThe application and the authenticated user need to\nhave the permission to look up users in the entire\nenterprise.\n\nThis endpoint also returns a limited set of information\nfor external users who are collaborated on content\nowned by the enterprise for authenticated users with the\nright scopes. In this case, disallowed fields will return\nnull instead.", "parameters": [ { "name": "user_id", "description": "The ID of the user.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Returns a single user object.\n\nNot all available fields are returned by default. Use the\n[fields](#param-fields) query parameter to explicitly request\nany specific fields using the [fields](#get-users-id--request--fields)\nparameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User--Full" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "put": { "operationId": "put_users_id", "summary": "Update user", "tags": [ "Users" ], "x-box-tag": "users", "x-box-enable-explorer": true, "description": "Updates a managed or app user in an enterprise. This endpoint\nis only available to users and applications with the right\nadmin permissions.", "parameters": [ { "name": "user_id", "description": "The ID of the user.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "enterprise": { "type": "string", "nullable": true, "example": null, "description": "Set this to `null` to roll the user out of the enterprise\nand make them a free user" }, "notify": { "type": "boolean", "example": true, "description": "Whether the user should receive an email when they\nare rolled out of an enterprise" }, "name": { "type": "string", "description": "The name of the user", "example": "Aaron Levie", "maxLength": 50 }, "login": { "type": "string", "description": "The email address the user uses to log in\n\nNote: If the target user's email is not confirmed, then the\nprimary login address cannot be changed.", "example": "somename@box.com" }, "role": { "type": "string", "enum": [ "coadmin", "user" ], "description": "The user’s enterprise role", "example": "user" }, "language": { "type": "string", "description": "The language of the user, formatted in modified version of the\n[ISO 639-1](/guides/api-calls/language-codes) format.", "example": "en" }, "is_sync_enabled": { "type": "boolean", "description": "Whether the user can use Box Sync", "example": true }, "job_title": { "type": "string", "description": "The user’s job title", "maxLength": 100, "example": "CEO" }, "phone": { "type": "string", "description": "The user’s phone number", "maxLength": 100, "example": "6509241374" }, "address": { "type": "string", "description": "The user’s address", "maxLength": 255, "example": "900 Jefferson Ave, Redwood City, CA 94063" }, "tracking_codes": { "type": "array", "items": { "$ref": "#/components/schemas/TrackingCode" }, "description": "Tracking codes allow an admin to generate reports from the\nadmin console and assign an attribute to a specific group\nof users. This setting must be enabled for an enterprise before it\ncan be used." }, "can_see_managed_users": { "type": "boolean", "example": true, "description": "Whether the user can see other enterprise users in their\ncontact list" }, "timezone": { "type": "string", "format": "timezone", "description": "The user's timezone", "example": "Africa/Bujumbura" }, "is_external_collab_restricted": { "type": "boolean", "example": true, "description": "Whether the user is allowed to collaborate with users outside\ntheir enterprise" }, "is_exempt_from_device_limits": { "type": "boolean", "example": true, "description": "Whether to exempt the user from enterprise device limits" }, "is_exempt_from_login_verification": { "type": "boolean", "example": true, "description": "Whether the user must use two-factor authentication" }, "is_password_reset_required": { "type": "boolean", "example": true, "description": "Whether the user is required to reset their password" }, "status": { "type": "string", "enum": [ "active", "inactive", "cannot_delete_edit", "cannot_delete_edit_upload" ], "description": "The user's account status", "example": "active" }, "space_amount": { "type": "integer", "format": "int64", "description": "The user’s total available space in bytes. Set this to `-1` to\nindicate unlimited storage.", "example": 11345156112 }, "notification_email": { "type": "object", "nullable": true, "description": "An alternate notification email address to which email\nnotifications are sent. When it's confirmed, this will be\nthe email address to which notifications are sent instead of\nto the primary email address.\n\nSet this value to `null` to remove the notification email.", "properties": { "email": { "type": "string", "example": "notifications@example.com", "description": "The email address to send the notifications to." } } }, "external_app_user_id": { "type": "string", "example": "my-user-1234", "description": "An external identifier for an app user, which can be used to look\nup the user. This can be used to tie user IDs from external\nidentity providers to Box users.\n\nNote: In order to update this field, you need to request a token\nusing the application that created the app user." } } } } } }, "responses": { "200": { "description": "Returns the updated user object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User--Full" } } } }, "400": { "description": "Returns an error if some of the parameters are missing or\nnot valid.\n\n* `invalid_parameter` when a parameter is formatted incorrectly,\n for example when the `notification_email` has an incorrectly formatted\n email address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error if the user is not allowed to make the changes.\n\n* `access_denied_insufficient_permissions` when the user does not have\n the right permissions, for example when updating the notification email\n is turned off for the enterprise.\n* `denied_by_policy` when the user does not have the right permissions\n due to the information barrier restrictions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_users_id", "x-box-tag": "users", "summary": "Delete user", "tags": [ "Users" ], "description": "Deletes a user. By default this will fail if the user\nstill owns any content. Move their owned content first\nbefore proceeding, or use the `force` field to delete\nthe user and their files.", "parameters": [ { "name": "user_id", "description": "The ID of the user.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "notify", "schema": { "type": "boolean" }, "in": "query", "example": true, "description": "Whether the user will receive email notification of\nthe deletion" }, { "name": "force", "schema": { "type": "boolean" }, "in": "query", "example": true, "description": "Whether the user should be deleted even if this user\nstill own files" } ], "responses": { "204": { "description": "Removes the user and returns an empty response." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/users/{user_id}/avatar": { "get": { "operationId": "get_users_id_avatar", "x-box-tag": "avatars", "summary": "Get user avatar", "tags": [ "User avatars" ], "description": "Retrieves an image of a the user's avatar.", "parameters": [ { "name": "user_id", "description": "The ID of the user.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "When an avatar can be found for the user the\nimage data will be returned in the body of the\nresponse.", "content": { "image/jpg": { "schema": { "type": "string", "format": "binary", "description": "The avatar" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_users_id_avatar", "x-box-tag": "avatars", "summary": "Add or update user avatar", "tags": [ "User avatars" ], "description": "Adds or updates a user avatar.", "parameters": [ { "name": "user_id", "description": "The ID of the user.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "pic" ], "properties": { "pic": { "type": "string", "format": "binary", "description": "The image file to be uploaded to Box.\nAccepted file extensions are `.jpg` or `.png`.\nThe maximum file size is 1MB." } } } } } }, "responses": { "200": { "description": "* `ok`: Returns the `pic_urls` object with URLs to existing\nuser avatars that were updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserAvatar" } } } }, "201": { "description": "* `created`: Returns the `pic_urls` object with URLS to user avatars\nuploaded to Box with the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserAvatar" } } } }, "400": { "description": "* `bad_request`: Returns an error when:\n * An image is not included in the request\n * The uploaded file is empty\n * The image size exceeds 1024 * 1024 pixels\n or 1MB\n * The file extension is other than `.jpg` or `.png`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "* `forbidden`: Returns an error if the user does not have permissions\nnecessary to upload an avatar or is not activated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "* `not_found`: Returns an error if the user\ndoes not exist or cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_users_id_avatar", "x-box-tag": "avatars", "summary": "Delete user avatar", "tags": [ "User avatars" ], "description": "Removes an existing user avatar.\nYou cannot reverse this operation.", "parameters": [ { "name": "user_id", "description": "The ID of the user.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "* `no_content`: Removes the avatar and returns an empty response." }, "403": { "description": "* `forbidden`: Returned if the user does not have necessary permissions\n or is not activated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "* `not_found`: Returned if the user or user avatar does not exist\n or cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/users/{user_id}/folders/0": { "put": { "operationId": "put_users_id_folders_0", "x-box-tag": "transfer", "summary": "Transfer owned folders", "tags": [ "Transfer folders" ], "description": "Move all of the items (files, folders and workflows) owned by a user into\nanother user's account\n\nOnly the root folder (`0`) can be transferred.\n\nFolders can only be moved across users by users with administrative\npermissions.\n\nAll existing shared links and folder-level collaborations are transferred\nduring the operation. Please note that while collaborations at the individual\nfile-level are transferred during the operation, the collaborations are\ndeleted when the original user is deleted.\n\nThis call will be performed synchronously which might lead to a slow response\nwhen the source user has a large number of items in all of its folders.\n\nIf the destination path has a metadata cascade policy attached to any of\nthe parent folders, a metadata cascade operation will be kicked off\nasynchronously.\n\nThere is currently no way to check for when this operation is finished.\n\nThe destination folder's name will be in the format `{User}'s Files and\nFolders`, where `{User}` is the display name of the user.\n\nTo make this API call your application will need to have the \"Read and write\nall files and folders stored in Box\" scope enabled.\n\nPlease make sure the destination user has access to `Relay` or `Relay Lite`,\nand has access to the files and folders involved in the workflows being\ntransferred.\n\nAdmins will receive an email when the operation is completed.", "parameters": [ { "name": "user_id", "description": "The ID of the user.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "notify", "description": "Determines if users should receive email notification\nfor the action performed.", "in": "query", "required": false, "example": true, "schema": { "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "owned_by" ], "properties": { "owned_by": { "type": "object", "description": "The user who the folder will be transferred to", "required": [ "id" ], "properties": { "id": { "type": "string", "example": "1232234", "description": "The ID of the user who the folder will be\ntransferred to" } } } } } } } }, "responses": { "200": { "description": "Returns the information for the newly created\ndestination folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder--Full" } } } }, "403": { "description": "Returns an error when folder ownership cannot be\ntransferred to another user.\n\n* `forbidden_by_policy`: Returned if ownership transfer\n is forbidden due to information barrier restrictions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/users/{user_id}/email_aliases": { "get": { "operationId": "get_users_id_email_aliases", "summary": "List user's email aliases", "tags": [ "Email aliases" ], "x-box-tag": "email_aliases", "description": "Retrieves all email aliases for a user. The collection\ndoes not include the primary login for the user.", "parameters": [ { "name": "user_id", "description": "The ID of the user.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a collection of email aliases.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailAliases" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_users_id_email_aliases", "x-box-tag": "email_aliases", "summary": "Create email alias", "tags": [ "Email aliases" ], "description": "Adds a new email alias to a user account..", "parameters": [ { "name": "user_id", "description": "The ID of the user.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "example": "alias@example.com", "description": "The email address to add to the account as an alias.\n\nNote: The domain of the email alias needs to be registered\n to your enterprise.\nSee the [domain verification guide](\n https://support.box.com/hc/en-us/articles/4408619650579-Domain-Verification\n ) for steps to add a new domain." } } } } } }, "responses": { "201": { "description": "Returns the newly created email alias object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailAlias" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/users/{user_id}/email_aliases/{email_alias_id}": { "delete": { "operationId": "delete_users_id_email_aliases_id", "x-box-tag": "email_aliases", "summary": "Remove email alias", "tags": [ "Email aliases" ], "description": "Removes an email alias from a user.", "parameters": [ { "name": "user_id", "description": "The ID of the user.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "email_alias_id", "description": "The ID of the email alias.", "example": "23432", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Removes the alias and returns an empty response." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/users/{user_id}/memberships": { "get": { "operationId": "get_users_id_memberships", "summary": "List user's groups", "x-box-tag": "memberships", "tags": [ "Group memberships" ], "description": "Retrieves all the groups for a user. Only members of this\ngroup or users with admin-level permissions will be able to\nuse this API.", "parameters": [ { "name": "user_id", "description": "The ID of the user.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } }, { "name": "offset", "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 } } ], "responses": { "200": { "description": "Returns a collection of membership objects. If there are no\nmemberships, an empty collection will be returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMemberships" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/invites": { "post": { "operationId": "post_invites", "summary": "Create user invite", "tags": [ "Invites" ], "x-box-tag": "invites", "description": "Invites an existing external user to join an enterprise.\n\nThe existing user can not be part of another enterprise and\nmust already have a Box account. Once invited, the user will receive an\nemail and are prompted to accept the invitation within the\nBox web application.\n\nThis method requires the \"Manage An Enterprise\" scope enabled for\nthe application, which can be enabled within the developer console.", "parameters": [ { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "enterprise", "actionable_by" ], "properties": { "enterprise": { "type": "object", "description": "The enterprise to invite the user to", "required": [ "id" ], "properties": { "id": { "type": "string", "example": "1232234", "description": "The ID of the enterprise" } } }, "actionable_by": { "type": "object", "description": "The user to invite", "required": [ "id" ], "properties": { "login": { "type": "string", "example": "john@example.com", "description": "The login of the invited user" } } } } } } } }, "responses": { "200": { "description": "Returns a new invite object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invite" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/invites/{invite_id}": { "get": { "operationId": "get_invites_id", "summary": "Get user invite status", "tags": [ "Invites" ], "description": "Returns the status of a user invite.", "x-box-tag": "invites", "parameters": [ { "name": "invite_id", "description": "The ID of an invite.", "example": "213723", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Returns an invite object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invite" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/groups": { "get": { "operationId": "get_groups", "summary": "List groups for enterprise", "x-box-tag": "groups", "tags": [ "Groups" ], "description": "Retrieves all of the groups for a given enterprise. The user\nmust have admin permissions to inspect enterprise's groups.", "parameters": [ { "name": "filter_term", "description": "Limits the results to only groups whose `name` starts\nwith the search term.", "in": "query", "required": false, "example": "Engineering", "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } }, { "name": "offset", "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 } } ], "responses": { "200": { "description": "Returns a collection of group objects. If there are no groups, an\nempty collection will be returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Groups" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_groups", "summary": "Create group", "tags": [ "Groups" ], "x-box-tag": "groups", "description": "Creates a new group of users in an enterprise. Only users with admin\npermissions can create new groups.", "parameters": [ { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Customer Support", "description": "The name of the new group to be created. This name must be unique\nwithin the enterprise." }, "provenance": { "type": "string", "description": "Keeps track of which external source this group is\ncoming, for example `Active Directory`, or `Okta`.\n\nSetting this will also prevent Box admins from editing\nthe group name and its members directly via the Box\nweb application.\n\nThis is desirable for one-way syncing of groups.", "maxLength": 255, "example": "Active Directory" }, "external_sync_identifier": { "type": "string", "description": "An arbitrary identifier that can be used by\nexternal group sync tools to link this Box Group to\nan external group.\n\nExample values of this field\ncould be an **Active Directory Object ID** or a **Google\nGroup ID**.\n\nWe recommend you use of this field in\norder to avoid issues when group names are updated in\neither Box or external systems.", "example": "AD:123456" }, "description": { "type": "string", "description": "A human readable description of the group.", "maxLength": 255, "example": "\"Customer Support Group - as imported from Active Directory\"" }, "invitability_level": { "type": "string", "example": "admins_only", "description": "Specifies who can invite the group to collaborate\non folders.\n\nWhen set to `admins_only` the enterprise admin, co-admins,\nand the group's admin can invite the group.\n\nWhen set to `admins_and_members` all the admins listed\nabove and group members can invite the group.\n\nWhen set to `all_managed_users` all managed users in the\nenterprise can invite the group.", "enum": [ "admins_only", "admins_and_members", "all_managed_users" ] }, "member_viewability_level": { "type": "string", "example": "admins_only", "description": "Specifies who can see the members of the group.\n\n* `admins_only` - the enterprise admin, co-admins, group's\n group admin\n* `admins_and_members` - all admins and group members\n* `all_managed_users` - all managed users in the\n enterprise", "enum": [ "admins_only", "admins_and_members", "all_managed_users" ] } } } } } }, "responses": { "201": { "description": "Returns the new group object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "409": { "description": "Returns an error a conflict is stopping the group from being created.\n\n* `invalid_parameter`: Often returned if the group name is not unique in\nthe enterprise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/groups/terminate_sessions": { "post": { "operationId": "post_groups_terminate_sessions", "summary": "Create jobs to terminate user group session", "tags": [ "Groups" ], "x-box-tag": "session_termination", "description": "Validates the roles and permissions of the group,\nand creates asynchronous jobs\nto terminate the group's sessions.\nReturns the status for the POST request.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "group_ids" ], "properties": { "group_ids": { "example": [ "123456", "456789" ], "type": "array", "description": "A list of group IDs", "items": { "type": "string" } } } } } } }, "responses": { "202": { "description": "Returns a message about the request status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionTerminationMessage" } } } }, "400": { "description": "Returns an error if some of the parameters are\nnot valid.\n\n* `Groups can not be NULL or EMPTY` when no value is provided\n* `group id format is string` when the provided group id format\nis incorrect\n* `Supported payload format is JSON` when the provided payload\nformat is incorrect", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error if there are insufficient permissions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the resource could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returns an error if the request limit is exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "500": { "description": "Returns an error if there is an internal server issue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "503": { "description": "Returns an error if the request timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/groups/{group_id}": { "get": { "operationId": "get_groups_id", "summary": "Get group", "tags": [ "Groups" ], "x-box-tag": "groups", "description": "Retrieves information about a group. Only members of this\ngroup or users with admin-level permissions will be able to\nuse this API.", "parameters": [ { "name": "group_id", "description": "The ID of the group.", "example": "57645", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Returns the group object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group--Full" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "put": { "operationId": "put_groups_id", "summary": "Update group", "tags": [ "Groups" ], "x-box-tag": "groups", "description": "Updates a specific group. Only admins of this\ngroup or users with admin-level permissions will be able to\nuse this API.", "parameters": [ { "name": "group_id", "description": "The ID of the group.", "example": "57645", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "Customer Support", "description": "The name of the new group to be created. Must be unique within the\nenterprise." }, "provenance": { "type": "string", "description": "Keeps track of which external source this group is\ncoming, for example `Active Directory`, or `Okta`.\n\nSetting this will also prevent Box admins from editing\nthe group name and its members directly via the Box\nweb application.\n\nThis is desirable for one-way syncing of groups.", "maxLength": 255, "example": "Active Directory" }, "external_sync_identifier": { "type": "string", "description": "An arbitrary identifier that can be used by\nexternal group sync tools to link this Box Group to\nan external group.\n\nExample values of this field\ncould be an **Active Directory Object ID** or a **Google\nGroup ID**.\n\nWe recommend you use of this field in\norder to avoid issues when group names are updated in\neither Box or external systems.", "example": "AD:123456" }, "description": { "type": "string", "description": "A human readable description of the group.", "maxLength": 255, "example": "\"Customer Support Group - as imported from Active Directory\"" }, "invitability_level": { "type": "string", "example": "admins_only", "description": "Specifies who can invite the group to collaborate\non folders.\n\nWhen set to `admins_only` the enterprise admin, co-admins,\nand the group's admin can invite the group.\n\nWhen set to `admins_and_members` all the admins listed\nabove and group members can invite the group.\n\nWhen set to `all_managed_users` all managed users in the\nenterprise can invite the group.", "enum": [ "admins_only", "admins_and_members", "all_managed_users" ] }, "member_viewability_level": { "type": "string", "example": "admins_only", "description": "Specifies who can see the members of the group.\n\n* `admins_only` - the enterprise admin, co-admins, group's\n group admin\n* `admins_and_members` - all admins and group members\n* `all_managed_users` - all managed users in the\n enterprise", "enum": [ "admins_only", "admins_and_members", "all_managed_users" ] } } } } } }, "responses": { "200": { "description": "Returns the updated group object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group--Full" } } } }, "409": { "description": "Returns an error a conflict is stopping the group from being created.\n\n* `invalid_parameter`: Often returned if the group name is not unique in\nthe enterprise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_groups_id", "summary": "Remove group", "tags": [ "Groups" ], "x-box-tag": "groups", "description": "Permanently deletes a group. Only users with\nadmin-level permissions will be able to use this API.", "parameters": [ { "name": "group_id", "description": "The ID of the group.", "example": "57645", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "A blank response is returned if the group was\nsuccessfully deleted." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/groups/{group_id}/memberships": { "get": { "operationId": "get_groups_id_memberships", "summary": "List members of group", "x-box-tag": "memberships", "tags": [ "Group memberships" ], "description": "Retrieves all the members for a group. Only members of this\ngroup or users with admin-level permissions will be able to\nuse this API.", "parameters": [ { "name": "group_id", "description": "The ID of the group.", "example": "57645", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } }, { "name": "offset", "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 } } ], "responses": { "200": { "description": "Returns a collection of membership objects. If there are no\nmemberships, an empty collection will be returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMemberships" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/groups/{group_id}/collaborations": { "get": { "operationId": "get_groups_id_collaborations", "summary": "List group collaborations", "x-box-tag": "list_collaborations", "tags": [ "Collaborations (List)" ], "description": "Retrieves all the collaborations for a group. The user\nmust have admin permissions to inspect enterprise's groups.\n\nEach collaboration object has details on which files or\nfolders the group has access to and with what role.", "parameters": [ { "name": "group_id", "description": "The ID of the group.", "example": "57645", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } }, { "name": "offset", "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 } } ], "responses": { "200": { "description": "Returns a collection of collaboration objects. If there are no\ncollaborations, an empty collection will be returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collaborations" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/group_memberships": { "post": { "operationId": "post_group_memberships", "summary": "Add user to group", "tags": [ "Group memberships" ], "x-box-tag": "memberships", "description": "Creates a group membership. Only users with\nadmin-level permissions will be able to use this API.", "parameters": [ { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "user", "group" ], "properties": { "user": { "type": "object", "description": "The user to add to the group.", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The ID of the user to add to the group", "example": "1434325" } } }, "group": { "type": "object", "description": "The group to add the user to.", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The ID of the group to add the user to", "example": "4545523" } } }, "role": { "type": "string", "example": "member", "description": "The role of the user in the group.", "enum": [ "member", "admin" ] }, "configurable_permissions": { "type": "object", "example": { "can_run_reports": true }, "description": "Custom configuration for the permissions an admin\nif a group will receive. This option has no effect\non members with a role of `member`.\n\nSetting these permissions overwrites the default\naccess levels of an admin.\n\nSpecifying a value of \"null\" for this object will disable\nall configurable permissions. Specifying permissions will set\nthem accordingly, omitted permissions will be enabled by default.", "additionalProperties": { "type": "boolean", "description": "A key value pair of custom permissions.", "example": true, "x-box-example-key": "can_run_reports" } } } } } } }, "responses": { "201": { "description": "Returns a new group membership object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMembership" } } } }, "403": { "description": "Returns an error when the user cannot be added\nto a group.\n\n* `forbidden_by_policy`: Adding a user\nto a group is forbidden due to information\nbarrier restrictions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/group_memberships/{group_membership_id}": { "get": { "operationId": "get_group_memberships_id", "summary": "Get group membership", "tags": [ "Group memberships" ], "x-box-tag": "memberships", "description": "Retrieves a specific group membership. Only admins of this\ngroup or users with admin-level permissions will be able to\nuse this API.", "parameters": [ { "name": "group_membership_id", "description": "The ID of the group membership.", "example": "434534", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Returns the group membership object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMembership" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "put": { "operationId": "put_group_memberships_id", "summary": "Update group membership", "tags": [ "Group memberships" ], "x-box-tag": "memberships", "description": "Updates a user's group membership. Only admins of this\ngroup or users with admin-level permissions will be able to\nuse this API.", "parameters": [ { "name": "group_membership_id", "description": "The ID of the group membership.", "example": "434534", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "example": "member", "description": "The role of the user in the group.", "enum": [ "member", "admin" ] }, "configurable_permissions": { "type": "object", "example": { "can_run_reports": true }, "description": "Custom configuration for the permissions an admin\nif a group will receive. This option has no effect\non members with a role of `member`.\n\nSetting these permissions overwrites the default\naccess levels of an admin.\n\nSpecifying a value of \"null\" for this object will disable\nall configurable permissions. Specifying permissions will set\nthem accordingly, omitted permissions will be enabled by default.", "additionalProperties": { "type": "boolean", "description": "A key value pair of custom permissions.", "example": true, "x-box-example-key": "can_run_reports" } } } } } } }, "responses": { "200": { "description": "Returns a new group membership object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMembership" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_group_memberships_id", "summary": "Remove user from group", "tags": [ "Group memberships" ], "x-box-tag": "memberships", "description": "Deletes a specific group membership. Only admins of this\ngroup or users with admin-level permissions will be able to\nuse this API.", "parameters": [ { "name": "group_membership_id", "description": "The ID of the group membership.", "example": "434534", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "A blank response is returned if the membership was\nsuccessfully deleted." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/webhooks": { "get": { "operationId": "get_webhooks", "summary": "List all webhooks", "tags": [ "Webhooks" ], "x-box-tag": "webhooks", "description": "Returns all defined webhooks for the requesting application.\n\nThis API only returns webhooks that are applied to files or folders that are\nowned by the authenticated user. This means that an admin can not see webhooks\ncreated by a service account unless the admin has access to those folders, and\nvice versa.", "parameters": [ { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } } ], "responses": { "200": { "description": "Returns a list of webhooks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks" } } } }, "403": { "description": "Returns an error if the application does not\nhave the permission to manage webhooks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_webhooks", "summary": "Create webhook", "tags": [ "Webhooks" ], "x-box-tag": "webhooks", "description": "Creates a webhook.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "target", "triggers", "address" ], "properties": { "target": { "type": "object", "description": "The item that will trigger the webhook", "properties": { "id": { "description": "The ID of the item to trigger a webhook", "type": "string", "example": "1231232" }, "type": { "description": "The type of item to trigger a webhook", "type": "string", "example": "file", "enum": [ "file", "folder" ] } } }, "address": { "type": "string", "example": "https://example.com/webhooks", "description": "The URL that is notified by this webhook" }, "triggers": { "type": "array", "example": [ "FILE.UPLOADED" ], "description": "An array of event names that this webhook is\nto be triggered for", "items": { "title": "Webhook Trigger", "example": "FILE.UPLOADED", "type": "string", "description": "The event name that triggered this webhook", "enum": [ "FILE.UPLOADED", "FILE.PREVIEWED", "FILE.DOWNLOADED", "FILE.TRASHED", "FILE.DELETED", "FILE.RESTORED", "FILE.COPIED", "FILE.MOVED", "FILE.LOCKED", "FILE.UNLOCKED", "FILE.RENAMED", "COMMENT.CREATED", "COMMENT.UPDATED", "COMMENT.DELETED", "TASK_ASSIGNMENT.CREATED", "TASK_ASSIGNMENT.UPDATED", "METADATA_INSTANCE.CREATED", "METADATA_INSTANCE.UPDATED", "METADATA_INSTANCE.DELETED", "FOLDER.CREATED", "FOLDER.RENAMED", "FOLDER.DOWNLOADED", "FOLDER.RESTORED", "FOLDER.DELETED", "FOLDER.COPIED", "FOLDER.MOVED", "FOLDER.TRASHED", "WEBHOOK.DELETED", "COLLABORATION.CREATED", "COLLABORATION.ACCEPTED", "COLLABORATION.REJECTED", "COLLABORATION.REMOVED", "COLLABORATION.UPDATED", "SHARED_LINK.DELETED", "SHARED_LINK.CREATED", "SHARED_LINK.UPDATED", "SIGN_REQUEST.COMPLETED", "SIGN_REQUEST.DECLINED", "SIGN_REQUEST.EXPIRED", "SIGN_REQUEST.SIGNER_EMAIL_BOUNCED" ] } } } } } } }, "responses": { "201": { "description": "Returns the new webhook object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "description": "Returns an error if the parameters were\nincorrect.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error if the application does not\nhave the permission to manage webhooks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the target item could\nnot be found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error if the a webhook for this\ncombination of target, application, and user\nalready exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/webhooks/{webhook_id}": { "get": { "operationId": "get_webhooks_id", "tags": [ "Webhooks" ], "x-box-tag": "webhooks", "summary": "Get webhook", "description": "Retrieves a specific webhook", "parameters": [ { "name": "webhook_id", "description": "The ID of the webhook.", "example": "3321123", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a webhook object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "403": { "description": "Returns an error if the application does not\nhave the permission to manage webhooks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the webhook could not be found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "put": { "operationId": "put_webhooks_id", "summary": "Update webhook", "tags": [ "Webhooks" ], "x-box-tag": "webhooks", "description": "Updates a webhook.", "parameters": [ { "name": "webhook_id", "description": "The ID of the webhook.", "example": "3321123", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "type": "object", "description": "The item that will trigger the webhook", "properties": { "id": { "description": "The ID of the item to trigger a webhook", "type": "string", "example": "1231232" }, "type": { "description": "The type of item to trigger a webhook", "type": "string", "example": "file", "enum": [ "file", "folder" ] } } }, "address": { "type": "string", "example": "https://example.com/webhooks", "description": "The URL that is notified by this webhook" }, "triggers": { "type": "array", "example": [ "FILE.UPLOADED" ], "description": "An array of event names that this webhook is\nto be triggered for", "items": { "title": "Webhook Trigger", "example": "FILE.UPLOADED", "type": "string", "description": "The event name that triggered this webhook", "enum": [ "FILE.UPLOADED", "FILE.PREVIEWED", "FILE.DOWNLOADED", "FILE.TRASHED", "FILE.DELETED", "FILE.RESTORED", "FILE.COPIED", "FILE.MOVED", "FILE.LOCKED", "FILE.UNLOCKED", "FILE.RENAMED", "COMMENT.CREATED", "COMMENT.UPDATED", "COMMENT.DELETED", "TASK_ASSIGNMENT.CREATED", "TASK_ASSIGNMENT.UPDATED", "METADATA_INSTANCE.CREATED", "METADATA_INSTANCE.UPDATED", "METADATA_INSTANCE.DELETED", "FOLDER.CREATED", "FOLDER.RENAMED", "FOLDER.DOWNLOADED", "FOLDER.RESTORED", "FOLDER.DELETED", "FOLDER.COPIED", "FOLDER.MOVED", "FOLDER.TRASHED", "WEBHOOK.DELETED", "COLLABORATION.CREATED", "COLLABORATION.ACCEPTED", "COLLABORATION.REJECTED", "COLLABORATION.REMOVED", "COLLABORATION.UPDATED", "SHARED_LINK.DELETED", "SHARED_LINK.CREATED", "SHARED_LINK.UPDATED", "SIGN_REQUEST.COMPLETED", "SIGN_REQUEST.DECLINED", "SIGN_REQUEST.EXPIRED", "SIGN_REQUEST.SIGNER_EMAIL_BOUNCED" ] } } } } } } }, "responses": { "200": { "description": "Returns the new webhook object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "description": "Returns an error if the parameters were\nincorrect.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error if the application does not\nhave the permission to manage webhooks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the target item or webhook\ncould not be found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error if the a webhook for this\ncombination of target, application, and user\nalready exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_webhooks_id", "summary": "Remove webhook", "tags": [ "Webhooks" ], "x-box-tag": "webhooks", "description": "Deletes a webhook.", "parameters": [ { "name": "webhook_id", "description": "The ID of the webhook.", "example": "3321123", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "An empty response will be returned when the webhook\nwas successfully deleted." }, "403": { "description": "Returns an error if the application does not\nhave the permission to manage webhooks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the webhook could not be found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/skill_invocations/{skill_id}": { "put": { "operationId": "put_skill_invocations_id", "summary": "Update all Box Skill cards on file", "tags": [ "Skills" ], "x-box-tag": "skills", "description": "An alternative method that can be used to overwrite and update all Box Skill\nmetadata cards on a file.", "parameters": [ { "name": "skill_id", "description": "The ID of the skill to apply this metadata for.", "example": "33243242", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "metadata", "file" ], "properties": { "status": { "type": "string", "description": "Defines the status of this invocation. Set this to `success` when setting Skill cards.", "example": "success", "enum": [ "invoked", "processing", "success", "transient_failure", "permanent_failure" ] }, "metadata": { "type": "object", "description": "The metadata to set for this skill. This is a list of\nBox Skills cards. These cards will overwrite any existing Box\nskill cards on the file.", "properties": { "cards": { "type": "array", "description": "A list of Box Skill cards to apply to this file.", "items": { "oneOf": [ { "$ref": "#/components/schemas/KeywordSkillCard" }, { "$ref": "#/components/schemas/TimelineSkillCard" }, { "$ref": "#/components/schemas/TranscriptSkillCard" }, { "$ref": "#/components/schemas/StatusSkillCard" } ] } } } }, "file": { "type": "object", "description": "The file to assign the cards to.", "properties": { "type": { "type": "string", "description": "`file`", "example": "file", "enum": [ "file" ] }, "id": { "type": "string", "description": "The ID of the file", "example": "3243244" } } }, "file_version": { "type": "object", "description": "The optional file version to assign the cards to.", "properties": { "type": { "type": "string", "description": "`file_version`", "example": "file_version", "enum": [ "file_version" ] }, "id": { "type": "string", "description": "The ID of the file version", "example": "731381601045" } } }, "usage": { "type": "object", "description": "A descriptor that defines what items are affected by this call.\n\nSet this to the default values when setting a card to a `success`\nstate, and leave it out in most other situations.", "properties": { "unit": { "type": "string", "example": "file", "description": "`file`" }, "value": { "type": "number", "example": 1, "description": "`1`" } } } } } } } }, "responses": { "200": { "description": "Returns an empty response when the card has been successfully updated." }, "400": { "description": "Returns an error when the request body is not valid.\n\n* `schema_validation_failed` - The request body contains a value for a for\na field that either does not exist, or for which the value or type does\nnot match the expected field type. An example might be an unknown option\nfor an `enum` or `multiSelect` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the file could not be found or the user does not\nhave access.\n\n* `not_found` - The file could not be found, or the user does not have\naccess to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/events": { "options": { "operationId": "options_events", "summary": "Get events long poll endpoint", "tags": [ "Events" ], "x-box-tag": "events", "description": "Returns a list of real-time servers that can be used for long-polling updates\nto the [event stream](#get-events).\n\nLong polling is the concept where a HTTP request is kept open until the\nserver sends a response, then repeating the process over and over to receive\nupdated responses.\n\nLong polling the event stream can only be used for user events, not for\nenterprise events.\n\nTo use long polling, first use this endpoint to retrieve a list of long poll\nURLs. Next, make a long poll request to any of the provided URLs.\n\nWhen an event occurs in monitored account a response with the value\n`new_change` will be sent. The response contains no other details as\nit only serves as a prompt to take further action such as sending a\nrequest to the [events endpoint](#get-events) with the last known\n`stream_position`.\n\nAfter the server sends this response it closes the connection. You must now\nrepeat the long poll process to begin listening for events again.\n\nIf no events occur for a while and the connection times out you will\nreceive a response with the value `reconnect`. When you receive this response\nyou’ll make another call to this endpoint to restart the process.\n\nIf you receive no events in `retry_timeout` seconds then you will need to\nmake another request to the real-time server (one of the URLs in the response\nfor this endpoint). This might be necessary due to network errors.\n\nFinally, if you receive a `max_retries` error when making a request to the\nreal-time server, you should start over by making a call to this endpoint\nfirst.", "responses": { "200": { "description": "Returns a paginated array of servers that can be used\ninstead of the regular endpoints for long-polling events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RealtimeServers" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "get": { "operationId": "get_events", "summary": "List user and enterprise events", "tags": [ "Events" ], "x-box-tag": "events", "description": "Returns up to a year of past events for a given user\nor for the entire enterprise.\n\nBy default this returns events for the authenticated user. To retrieve events\nfor the entire enterprise, set the `stream_type` to `admin_logs_streaming`\nfor live monitoring of new events, or `admin_logs` for querying across\nhistorical events. The user making the API call will\nneed to have admin privileges, and the application will need to have the\nscope `manage enterprise properties` checked.", "parameters": [ { "name": "stream_type", "description": "Defines the type of events that are returned\n\n* `all` returns everything for a user and is the default\n* `changes` returns events that may cause file tree changes\n such as file updates or collaborations.\n* `sync` is similar to `changes` but only applies to synced folders\n* `admin_logs` returns all events for an entire enterprise and\n requires the user making the API call to have admin permissions. This\n stream type is for programmatically pulling from a 1 year history of\n events across all users within the enterprise and within a\n `created_after` and `created_before` time frame. The complete history\n of events will be returned in chronological order based on the event\n time, but latency will be much higher than `admin_logs_streaming`.\n* `admin_logs_streaming` returns all events for an entire enterprise and\n requires the user making the API call to have admin permissions. This\n stream type is for polling for recent events across all users within\n the enterprise. Latency will be much lower than `admin_logs`, but\n events will not be returned in chronological order and may\n contain duplicates.", "in": "query", "example": "all", "schema": { "type": "string", "default": "all", "enum": [ "all", "changes", "sync", "admin_logs", "admin_logs_streaming" ] } }, { "name": "stream_position", "description": "The location in the event stream to start receiving events from.\n\n* `now` will return an empty list events and\nthe latest stream position for initialization.\n* `0` or `null` will return all events.", "example": "1348790499819", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "description": "Limits the number of events returned\n\nNote: Sometimes, the events less than the limit requested can be returned\neven when there may be more events remaining. This is primarily done in\nthe case where a number of events have already been retrieved and these\nretrieved events are returned rather than delaying for an unknown amount\nof time to see if there are any more results.", "in": "query", "example": 50, "schema": { "type": "integer", "format": "int64", "default": 100, "maximum": 500 } }, { "name": "event_type", "description": "A comma-separated list of events to filter by. This can only be used when\nrequesting the events with a `stream_type` of `admin_logs` or\n`adming_logs_streaming`. For any other `stream_type` this value will be\nignored.", "in": "query", "explode": false, "example": [ "ACCESS_GRANTED" ], "schema": { "type": "array", "items": { "type": "string", "description": "An event type that can be filtered by", "enum": [ "ACCESS_GRANTED", "ACCESS_REVOKED", "ADD_DEVICE_ASSOCIATION", "ADD_LOGIN_ACTIVITY_DEVICE", "ADMIN_LOGIN", "APPLICATION_CREATED", "APPLICATION_PUBLIC_KEY_ADDED", "APPLICATION_PUBLIC_KEY_DELETED", "CHANGE_ADMIN_ROLE", "CHANGE_FOLDER_PERMISSION", "COLLABORATION_ACCEPT", "COLLABORATION_EXPIRATION", "COLLABORATION_INVITE", "COLLABORATION_REMOVE", "COLLABORATION_ROLE_CHANGE", "COMMENT_CREATE", "COMMENT_DELETE", "CONTENT_WORKFLOW_ABNORMAL_DOWNLOAD_ACTIVITY", "CONTENT_WORKFLOW_AUTOMATION_ADD", "CONTENT_WORKFLOW_AUTOMATION_DELETE", "CONTENT_WORKFLOW_POLICY_ADD", "CONTENT_WORKFLOW_SHARING_POLICY_VIOLATION", "CONTENT_WORKFLOW_UPLOAD_POLICY_VIOLATION", "COPY", "DATA_RETENTION_CREATE_RETENTION", "DATA_RETENTION_REMOVE_RETENTION", "DELETE", "DELETE_USER", "DEVICE_TRUST_CHECK_FAILED", "DOWNLOAD", "EDIT", "EDIT_USER", "EMAIL_ALIAS_CONFIRM", "EMAIL_ALIAS_REMOVE", "ENTERPRISE_APP_AUTHORIZATION_UPDATE", "EXTERNAL_COLLAB_SECURITY_SETTINGS", "FAILED_LOGIN", "FILE_MARKED_MALICIOUS", "FILE_WATERMARKED_DOWNLOAD", "GROUP_ADD_ITEM", "GROUP_ADD_USER", "GROUP_CREATION", "GROUP_DELETION", "GROUP_EDITED", "GROUP_REMOVE_ITEM", "GROUP_REMOVE_USER", "ITEM_MODIFY", "ITEM_OPEN", "ITEM_SHARED_UPDATE", "ITEM_SYNC", "ITEM_UNSYNC", "LEGAL_HOLD_ASSIGNMENT_CREATE", "LEGAL_HOLD_ASSIGNMENT_DELETE", "LEGAL_HOLD_POLICY_CREATE", "LEGAL_HOLD_POLICY_DELETE", "LEGAL_HOLD_POLICY_UPDATE", "LOCK", "LOGIN", "METADATA_INSTANCE_CREATE", "METADATA_INSTANCE_DELETE", "METADATA_INSTANCE_UPDATE", "METADATA_TEMPLATE_CREATE", "METADATA_TEMPLATE_DELETE", "METADATA_TEMPLATE_UPDATE", "MOVE", "NEW_USER", "OAUTH2_ACCESS_TOKEN_REVOKE", "PREVIEW", "REMOVE_DEVICE_ASSOCIATION", "REMOVE_LOGIN_ACTIVITY_DEVICE", "RENAME", "RETENTION_POLICY_ASSIGNMENT_ADD", "SHARE", "SHARE_EXPIRATION", "SHIELD_ALERT", "SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED", "SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED_MISSING_JUSTIFICATION", "SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED", "SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED_MISSING_JUSTIFICATION", "SHIELD_JUSTIFICATION_APPROVAL", "SIGN_DOCUMENT_ASSIGNED", "SIGN_DOCUMENT_CANCELLED", "SIGN_DOCUMENT_COMPLETED", "SIGN_DOCUMENT_CONVERTED", "SIGN_DOCUMENT_CREATED", "SIGN_DOCUMENT_DECLINED", "SIGN_DOCUMENT_EXPIRED", "SIGN_DOCUMENT_SIGNED", "SIGN_DOCUMENT_VIEWED_BY_SIGNED", "SIGNER_DOWNLOADED", "SIGNER_FORWARDED", "STORAGE_EXPIRATION", "TASK_ASSIGNMENT_CREATE", "TASK_ASSIGNMENT_DELETE", "TASK_ASSIGNMENT_UPDATE", "TASK_CREATE", "TASK_UPDATE", "TERMS_OF_SERVICE_ACCEPT", "TERMS_OF_SERVICE_REJECT", "UNDELETE", "UNLOCK", "UNSHARE", "UPDATE_COLLABORATION_EXPIRATION", "UPDATE_SHARE_EXPIRATION", "UPLOAD", "USER_AUTHENTICATE_OAUTH2_ACCESS_TOKEN_CREATE", "WATERMARK_LABEL_CREATE", "WATERMARK_LABEL_DELETE" ] } } }, { "name": "created_after", "description": "The lower bound date and time to return events for. This can only be used\nwhen requesting the events with a `stream_type` of `admin_logs`. For any\nother `stream_type` this value will be ignored.", "in": "query", "example": "2012-12-12T10:53:43-08:00", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "description": "The upper bound date and time to return events for. This can only be used\nwhen requesting the events with a `stream_type` of `admin_logs`. For any\nother `stream_type` this value will be ignored.", "in": "query", "required": false, "example": "2013-12-12T10:53:43-08:00", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Returns a list of event objects.\n\nEvents objects are returned in pages, with each page (chunk)\nincluding a list of event objects. The response includes a\n`chunk_size` parameter indicating how many events were returned in this\nchunk, as well as the next `stream_position` that can be\nqueried.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Events" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/collections": { "get": { "operationId": "get_collections", "summary": "List all collections", "tags": [ "Collections" ], "x-box-tag": "collections", "description": "Retrieves all collections for a given user.\n\nCurrently, only the `favorites` collection\nis supported.", "parameters": [ { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "offset", "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } } ], "responses": { "200": { "description": "Returns all collections for the given user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collections" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/collections/{collection_id}/items": { "get": { "operationId": "get_collections_id_items", "summary": "List collection items", "tags": [ "Collections" ], "x-box-tag": "collections", "description": "Retrieves the files and/or folders contained within\nthis collection.", "parameters": [ { "name": "collection_id", "description": "The ID of the collection.", "example": "926489", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "offset", "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } } ], "responses": { "200": { "description": "Returns an array of items in the collection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Items" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/recent_items": { "get": { "operationId": "get_recent_items", "summary": "List recently accessed items", "tags": [ "Recent items" ], "description": "Returns information about the recent items accessed\nby a user, either in the last 90 days or up to the last\n1000 items accessed.", "x-box-tag": "recent_items", "x-box-enable-explorer": true, "parameters": [ { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a list recent items access by a user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecentItems" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/retention_policies": { "get": { "operationId": "get_retention_policies", "summary": "List retention policies", "tags": [ "Retention policies" ], "x-box-tag": "retention_policies", "description": "Retrieves all of the retention policies for an enterprise.", "parameters": [ { "name": "policy_name", "description": "Filters results by a case sensitive prefix of the name of\nretention policies.", "in": "query", "required": false, "example": "Sales Policy", "schema": { "type": "string" } }, { "name": "policy_type", "description": "Filters results by the type of retention policy.", "in": "query", "required": false, "example": "finite", "schema": { "type": "string", "enum": [ "finite", "indefinite" ] } }, { "name": "created_by_user_id", "description": "Filters results by the ID of the user who created policy.", "example": "21312321", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a list retention policies in the enterprise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionPolicies" } } } }, "400": { "description": "Returns a `bad_request` if a non existent `policy_type` was specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns a `not_found` error if the user specified in `created_by_user_id`\ndoes not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_retention_policies", "summary": "Create retention policy", "tags": [ "Retention policies" ], "x-box-tag": "retention_policies", "description": "Creates a retention policy.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "policy_name", "policy_type", "disposition_action" ], "properties": { "policy_name": { "type": "string", "description": "The name for the retention policy", "example": "Some Policy Name" }, "description": { "type": "string", "description": "The additional text description of the retention policy.", "example": "Policy to retain all reports for at least one month" }, "policy_type": { "type": "string", "example": "finite", "description": "The type of the retention policy. A retention\npolicy type can either be `finite`, where a\nspecific amount of time to retain the content is known\nupfront, or `indefinite`, where the amount of time\nto retain the content is still unknown.", "enum": [ "finite", "indefinite" ] }, "disposition_action": { "type": "string", "example": "permanently_delete", "description": "The disposition action of the retention policy.\n`permanently_delete` deletes the content\nretained by the policy permanently.\n`remove_retention` lifts retention policy\nfrom the content, allowing it to be deleted\nby users once the retention policy has expired.", "enum": [ "permanently_delete", "remove_retention" ] }, "retention_length": { "type": "string", "format": "int32", "example": "365", "minimum": 1, "description": "The length of the retention policy. This value\nspecifies the duration in days that the retention\npolicy will be active for after being assigned to\ncontent. If the policy has a `policy_type` of\n`indefinite`, the `retention_length` will also be\n`indefinite`." }, "retention_type": { "type": "string", "example": "modifiable", "description": "Specifies the retention type:\n\n* `modifiable`: You can modify the retention policy. For example,\nyou can add or remove folders, shorten or lengthen\nthe policy duration, or delete the assignment.\nUse this type if your retention policy\nis not related to any regulatory purposes.\n\n* `non-modifiable`: You can modify the retention policy\nonly in a limited way: add a folder, lengthen the duration,\nretire the policy, change the disposition action\nor notification settings. You cannot perform other actions,\nsuch as deleting the assignment or shortening the\npolicy duration. Use this type to ensure\ncompliance with regulatory retention policies.", "enum": [ "modifiable", "non-modifiable" ] }, "can_owner_extend_retention": { "type": "boolean", "enum": [ true, false ], "example": true, "description": "Whether the owner of a file will be allowed to\nextend the retention." }, "are_owners_notified": { "type": "boolean", "enum": [ true, false ], "example": true, "description": "Whether owner and co-owners of a file are notified\nwhen the policy nears expiration." }, "custom_notification_recipients": { "type": "array", "description": "A list of users notified when\nthe retention policy duration is about to end.", "items": { "$ref": "#/components/schemas/User--Mini" } } } } } } }, "responses": { "201": { "description": "Returns a new retention policy object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionPolicy" } } } }, "400": { "description": "Returns a `bad_request` error with the `retention_length` was\nspecified for a `infinite` retention policy, an incorrect\n`disposition_action` was set, or description exceeds maximum length of\n500 characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error if a retention policy with the given name already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/retention_policies/{retention_policy_id}": { "get": { "operationId": "get_retention_policies_id", "summary": "Get retention policy", "tags": [ "Retention policies" ], "x-box-tag": "retention_policies", "description": "Retrieves a retention policy.", "parameters": [ { "name": "retention_policy_id", "description": "The ID of the retention policy.", "example": "982312", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Returns the retention policy object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionPolicy" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "put": { "operationId": "put_retention_policies_id", "summary": "Update retention policy", "tags": [ "Retention policies" ], "x-box-tag": "retention_policies", "description": "Updates a retention policy.", "parameters": [ { "name": "retention_policy_id", "description": "The ID of the retention policy.", "example": "982312", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "policy_name": { "type": "string", "description": "The name for the retention policy", "example": "Some Policy Name" }, "description": { "type": "string", "description": "The additional text description of the retention policy.", "example": "Policy to retain all reports for at least one month" }, "disposition_action": { "type": "string", "example": "permanently_delete", "description": "The disposition action of the retention policy.\n`permanently_delete` deletes the content\nretained by the policy permanently.\n`remove_retention` lifts retention policy\nfrom the content, allowing it to be deleted\nby users once the retention policy has expired.", "enum": [ "permanently_delete", "remove_retention" ] }, "retention_type": { "type": "string", "example": "non-modifiable", "description": "Specifies the retention type:\n\n* `modifiable`: You can modify the retention policy. For example,\nyou can add or remove folders, shorten or lengthen\nthe policy duration, or delete the assignment.\nUse this type if your retention policy\nis not related to any regulatory purposes.\n* `non-modifiable`: You can modify the retention policy\nonly in a limited way: add a folder, lengthen the duration,\nretire the policy, change the disposition action\nor notification settings. You cannot perform other actions,\nsuch as deleting the assignment or shortening the\npolicy duration. Use this type to ensure\ncompliance with regulatory retention policies.\n\nWhen updating a retention policy, you can use\n`non-modifiable` type only. You can convert a\n`modifiable` policy to `non-modifiable`, but\nnot the other way around." }, "retention_length": { "type": "string", "format": "int32", "example": "365", "description": "The length of the retention policy. This value\nspecifies the duration in days that the retention\npolicy will be active for after being assigned to\ncontent. If the policy has a `policy_type` of\n`indefinite`, the `retention_length` will also be\n`indefinite`." }, "status": { "type": "string", "example": "retired", "description": "Used to retire a retention policy.\n\nIf not retiring a policy, do not include this parameter\nor set it to `null`." }, "can_owner_extend_retention": { "type": "boolean", "description": "Determines if the owner of items under the policy\ncan extend the retention when the original retention\nduration is about to end.", "example": false }, "are_owners_notified": { "type": "boolean", "description": "Determines if owners and co-owners of items\nunder the policy are notified when\nthe retention duration is about to end.", "enum": [ true, false ], "example": false }, "custom_notification_recipients": { "type": "array", "description": "A list of users notified when the retention duration is about to end.", "items": { "$ref": "#/components/schemas/User--Mini" } } } } } } }, "responses": { "200": { "description": "Returns the updated retention policy object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionPolicy" } } } }, "400": { "description": "Returns a `bad_request` if an incorrect\n`disposition_action` was set or description exceeds maximum length of\n500 characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error when a user wants to\nshorten the duration of a\nnon-modifiable policy, or to convert\na non-modifiable policy to\na modifiable one.\nNote: Lengthening policy duration\nis allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error if a retention policy with the given name already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_retention_policies_id", "summary": "Delete retention policy", "tags": [ "Retention policies" ], "x-box-tag": "retention_policies", "x-box-scopes": [ "manage_data_retention", "data_retention" ], "description": "Permanently deletes a retention policy.", "parameters": [ { "name": "retention_policy_id", "description": "The ID of the retention policy.", "example": "982312", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Returns an empty response when the policy has been deleted." }, "403": { "description": "Returns an error if the policy is non-modifiable or the user does\nnot have the required access to perform the action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the policy is not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/retention_policies/{retention_policy_id}/assignments": { "get": { "operationId": "get_retention_policies_id_assignments", "summary": "List retention policy assignments", "tags": [ "Retention policy assignments" ], "x-box-tag": "retention_policy_assignments", "description": "Returns a list of all retention policy assignments associated with a specified\nretention policy.", "parameters": [ { "name": "retention_policy_id", "description": "The ID of the retention policy.", "example": "982312", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "type", "description": "The type of the retention policy assignment to retrieve.", "in": "query", "required": false, "example": "metadata_template", "schema": { "type": "string", "enum": [ "folder", "enterprise", "metadata_template" ] } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } } ], "responses": { "200": { "description": "Returns a list of the retention policy assignments associated with the\nspecified retention policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionPolicyAssignments" } } } }, "400": { "description": "Returns an error if an unknown `type` is specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/retention_policy_assignments": { "post": { "operationId": "post_retention_policy_assignments", "summary": "Assign retention policy", "tags": [ "Retention policy assignments" ], "x-box-tag": "retention_policy_assignments", "description": "Assigns a retention policy to an item.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "policy_id", "assign_to" ], "properties": { "policy_id": { "type": "string", "description": "The ID of the retention policy to assign", "example": "173463" }, "assign_to": { "type": "object", "description": "The item to assign the policy to", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "The type of item to assign the policy to.", "example": "metadata_template", "enum": [ "enterprise", "folder", "metadata_template" ] }, "id": { "type": "string", "description": "The ID of item to assign the policy to.\nSet to `null` or omit when `type` is set to\n`enterprise`.", "example": "6564564" } } }, "filter_fields": { "type": "array", "description": "If the `assign_to` type is `metadata_template`,\nthen optionally add the `filter_fields` parameter which will\nrequire an array of objects with a field entry and a value entry.\nCurrently only one object of `field` and `value` is supported.", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "The metadata attribute key id.", "example": "a0f4ee4e-1dc1-4h90-a8a9-aef55fc681d4" }, "value": { "type": "string", "description": "The metadata attribute field id. For value, only\nenum and multiselect types are supported.", "example": "0c27b756-0p87-4fe0-a43a-59fb661ccc4e" } } } }, "start_date_field": { "description": "The date the retention policy assignment begins.\n\nIf the `assigned_to` type is `metadata_template`,\nthis field can be a date field's metadata attribute key id.", "type": "string", "example": "upload_date" } } } } } }, "responses": { "201": { "description": "Returns a new retention policy assignment object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionPolicyAssignment" } } } }, "400": { "description": "Returns an error if an `id` is specified while assigning the\nretention policy to an enterprise.\n\nReturns an error if `start_date_field` is present but `assign_to.type`\nis not `metadata_template`\n\nReturns an error if `start_date_field` is present, but belongs to a\ndifferent metadata template than the one specified in `assign_to.id`\n\nReturns an error if `start_date_field` is present, but the\n`retention_policy` has a `retention_length` of \"indefinite\"\n\nReturns an error if `start_date_field` is present, but cannot be resolved\nto a valid metadata date field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if no retention policy with the given `policy_id` exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error if a retention policy of equal or greater length has\nalready been assigned to this item.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/retention_policy_assignments/{retention_policy_assignment_id}": { "get": { "operationId": "get_retention_policy_assignments_id", "summary": "Get retention policy assignment", "tags": [ "Retention policy assignments" ], "x-box-tag": "retention_policy_assignments", "description": "Retrieves a retention policy assignment", "parameters": [ { "name": "retention_policy_assignment_id", "description": "The ID of the retention policy assignment.", "example": "1233123", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Returns the retention policy assignment object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionPolicyAssignment" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_retention_policy_assignments_id", "summary": "Remove retention policy assignment", "tags": [ "Retention policy assignments" ], "x-box-tag": "retention_policy_assignments", "description": "Removes a retention policy assignment\napplied to content.", "parameters": [ { "name": "retention_policy_assignment_id", "description": "The ID of the retention policy assignment.", "example": "1233123", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Returns an empty response when the policy assignment\nis successfully deleted." }, "403": { "description": "Returns an error when the assignment relates to\na retention policy that cannot be modified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the retention policy\nassignment does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/retention_policy_assignments/{retention_policy_assignment_id}/files_under_retention": { "get": { "operationId": "get_retention_policy_assignments_id_files_under_retention", "summary": "Get files under retention", "tags": [ "Retention policy assignments" ], "x-box-tag": "retention_policy_assignments", "description": "Returns a list of files under retention for a retention policy assignment.", "parameters": [ { "name": "retention_policy_assignment_id", "description": "The ID of the retention policy assignment.", "example": "1233123", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } } ], "responses": { "200": { "description": "Returns a list of files under retention that are associated with the\nspecified retention policy assignment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilesUnderRetention" } } } }, "400": { "description": "Returns an error if `retention_policy_assignment_id` is not specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/retention_policy_assignments/{retention_policy_assignment_id}/file_versions_under_retention": { "get": { "operationId": "get_retention_policy_assignments_id_file_versions_under_retention", "summary": "Get file versions under retention", "tags": [ "Retention policy assignments" ], "x-box-tag": "retention_policy_assignments", "description": "Returns a list of file versions under retention for a retention policy\nassignment.", "parameters": [ { "name": "retention_policy_assignment_id", "description": "The ID of the retention policy assignment.", "example": "1233123", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } } ], "responses": { "200": { "description": "Returns a list of file versions under retention that are associated with\nthe specified retention policy assignment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilesUnderRetention" } } } }, "400": { "description": "Returns an error if `retention_policy_assignment_id` is not specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/legal_hold_policies": { "get": { "operationId": "get_legal_hold_policies", "summary": "List all legal hold policies", "tags": [ "Legal hold policies" ], "x-box-tag": "legal_hold_policies", "description": "Retrieves a list of legal hold policies that belong to\nan enterprise.", "parameters": [ { "name": "policy_name", "description": "Limits results to policies for which the names start with\nthis search term. This is a case-insensitive prefix.", "in": "query", "example": "Sales Policy", "required": false, "schema": { "type": "string" } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } } ], "responses": { "200": { "description": "Returns a list of legal hold policies.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalHoldPolicies" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_legal_hold_policies", "summary": "Create legal hold policy", "tags": [ "Legal hold policies" ], "x-box-tag": "legal_hold_policies", "description": "Create a new legal hold policy.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "policy_name" ], "properties": { "policy_name": { "description": "The name of the policy.", "example": "Sales Policy", "type": "string", "maxLength": 254 }, "description": { "description": "A description for the policy.", "example": "A custom policy for the sales team", "type": "string", "maxLength": 500 }, "filter_started_at": { "description": "The filter start date.\n\nWhen this policy is applied using a `custodian` legal\nhold assignments, it will only apply to file versions\ncreated or uploaded inside of the\ndate range. Other assignment types, such as folders and\nfiles, will ignore the date filter.\n\nRequired if `is_ongoing` is set to `false`.", "example": "2012-12-12T10:53:43-08:00", "type": "string", "maxLength": 500, "format": "date-time" }, "filter_ended_at": { "description": "The filter end date.\n\nWhen this policy is applied using a `custodian` legal\nhold assignments, it will only apply to file versions\ncreated or uploaded inside of the\ndate range. Other assignment types, such as folders and\nfiles, will ignore the date filter.\n\nRequired if `is_ongoing` is set to `false`.", "example": "2012-12-18T10:53:43-08:00", "type": "string", "maxLength": 500, "format": "date-time" }, "is_ongoing": { "description": "Whether new assignments under this policy should\ncontinue applying to files even after initialization.\n\nWhen this policy is applied using a legal hold assignment,\nit will continue applying the policy to any new file versions\neven after it has been applied.\n\nFor example, if a legal hold assignment is placed on a user\ntoday, and that user uploads a file tomorrow, that file will\nget held. This will continue until the policy is retired.\n\nRequired if no filter dates are set.", "example": true, "type": "boolean" } } } } } }, "responses": { "201": { "description": "Returns a new legal hold policy object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalHoldPolicy" } } } }, "400": { "description": "Returns an error if required parameters are missing,\nor neither `is_ongoing` or filter dates are specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error if a policy with this name already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/legal_hold_policies/{legal_hold_policy_id}": { "get": { "operationId": "get_legal_hold_policies_id", "summary": "Get legal hold policy", "tags": [ "Legal hold policies" ], "x-box-tag": "legal_hold_policies", "description": "Retrieve a legal hold policy.", "parameters": [ { "name": "legal_hold_policy_id", "description": "The ID of the legal hold policy", "example": "324432", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a legal hold policy object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalHoldPolicy" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "put": { "operationId": "put_legal_hold_policies_id", "summary": "Update legal hold policy", "tags": [ "Legal hold policies" ], "x-box-tag": "legal_hold_policies", "description": "Update legal hold policy.", "parameters": [ { "name": "legal_hold_policy_id", "description": "The ID of the legal hold policy", "example": "324432", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "policy_name": { "description": "The name of the policy.", "example": "Sales Policy", "type": "string", "maxLength": 254 }, "description": { "description": "A description for the policy.", "example": "A custom policy for the sales team", "type": "string", "maxLength": 500 }, "release_notes": { "description": "Notes around why the policy was released.", "example": "Required for GDPR", "type": "string", "maxLength": 500 } } } } } }, "responses": { "200": { "description": "Returns a new legal hold policy object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalHoldPolicy" } } } }, "409": { "description": "Returns an error if a policy with this name already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_legal_hold_policies_id", "x-box-tag": "legal_hold_policies", "tags": [ "Legal hold policies" ], "summary": "Remove legal hold policy", "description": "Delete an existing legal hold policy.\n\nThis is an asynchronous process. The policy will not be\nfully deleted yet when the response returns.", "parameters": [ { "name": "legal_hold_policy_id", "description": "The ID of the legal hold policy", "example": "324432", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "A blank response is returned if the policy was\nsuccessfully deleted." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/legal_hold_policy_assignments": { "get": { "operationId": "get_legal_hold_policy_assignments", "summary": "List legal hold policy assignments", "tags": [ "Legal hold policy assignments" ], "x-box-tag": "legal_hold_policy_assignments", "description": "Retrieves a list of items a legal hold policy has been assigned to.", "parameters": [ { "name": "policy_id", "description": "The ID of the legal hold policy", "example": "324432", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "assign_to_type", "description": "Filters the results by the type of item the\npolicy was applied to.", "example": "file", "in": "query", "schema": { "type": "string", "enum": [ "file", "file_version", "folder", "user" ] } }, { "name": "assign_to_id", "description": "Filters the results by the ID of item the\npolicy was applied to.", "example": "1234323", "in": "query", "schema": { "type": "string" } }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Returns a list of legal hold policy assignments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalHoldPolicyAssignments" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_legal_hold_policy_assignments", "summary": "Assign legal hold policy", "tags": [ "Legal hold policy assignments" ], "x-box-tag": "legal_hold_policy_assignments", "description": "Assign a legal hold to a file, file version, folder, or user.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "policy_id", "assign_to" ], "properties": { "policy_id": { "description": "The ID of the policy to assign.", "example": "123244", "type": "string" }, "assign_to": { "type": "object", "description": "The item to assign the policy to", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "The type of item to assign the policy to", "example": "folder", "enum": [ "file", "file_version", "folder", "user" ] }, "id": { "type": "string", "description": "The ID of item to assign the policy to", "example": "6564564" } } } } } } } }, "responses": { "201": { "description": "Returns a new legal hold policy assignment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalHoldPolicyAssignment" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/legal_hold_policy_assignments/{legal_hold_policy_assignment_id}": { "get": { "operationId": "get_legal_hold_policy_assignments_id", "summary": "Get legal hold policy assignment", "tags": [ "Legal hold policy assignments" ], "x-box-tag": "legal_hold_policy_assignments", "description": "Retrieve a legal hold policy assignment.", "parameters": [ { "name": "legal_hold_policy_assignment_id", "description": "The ID of the legal hold policy assignment", "example": "753465", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a legal hold policy object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalHoldPolicyAssignment" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_legal_hold_policy_assignments_id", "x-box-tag": "legal_hold_policy_assignments", "tags": [ "Legal hold policy assignments" ], "summary": "Unassign legal hold policy", "description": "Remove a legal hold from an item.\n\nThis is an asynchronous process. The policy will not be\nfully removed yet when the response returns.", "parameters": [ { "name": "legal_hold_policy_assignment_id", "description": "The ID of the legal hold policy assignment", "example": "753465", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "A blank response is returned if the assignment was\nsuccessfully deleted." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/legal_hold_policy_assignments/{legal_hold_policy_assignment_id}/files_on_hold": { "get": { "operationId": "get_legal_hold_policy_assignments_id_files_on_hold", "summary": "List current file versions for legal hold policy assignment", "tags": [ "Legal hold policy assignments" ], "x-box-tag": "legal_hold_policy_assignments", "description": "Get a list of current file versions for a legal hold\nassignment.\n\nIn some cases you may want to get previous file versions instead. In these\ncases, use the `GET /legal_hold_policy_assignments/:id/file_versions_on_hold`\nAPI instead to return any previous versions of a file for this legal hold\npolicy assignment.\n\nDue to ongoing re-architecture efforts this API might not return all file\nversions held for this policy ID. Instead, this API will only return the\nlatest file version held in the newly developed architecture. The `GET\n/file_version_legal_holds` API can be used to fetch current and past versions\nof files held within the legacy architecture.\n\nThe `GET /legal_hold_policy_assignments?policy_id={id}` API can be used to\nfind a list of policy assignments for a given policy ID.", "parameters": [ { "name": "legal_hold_policy_assignment_id", "description": "The ID of the legal hold policy assignment", "example": "753465", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Returns the list of current file versions held under legal hold for a\nspecific legal hold policy assignment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileVersionLegalHolds" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/file_version_retentions": { "get": { "operationId": "get_file_version_retentions", "tags": [ "File version retentions" ], "x-box-tag": "file_version_retentions", "summary": "List file version retentions", "description": "Retrieves all file version retentions for the given enterprise.", "parameters": [ { "name": "file_id", "description": "Filters results by files with this ID.", "in": "query", "example": "43123123", "required": false, "schema": { "type": "string" } }, { "name": "file_version_id", "description": "Filters results by file versions with this ID.", "in": "query", "example": "1", "required": false, "schema": { "type": "string" } }, { "name": "policy_id", "description": "Filters results by the retention policy with this ID.", "in": "query", "required": false, "example": "982312", "schema": { "type": "string" } }, { "name": "disposition_action", "description": "Filters results by the retention policy with this disposition\naction.", "in": "query", "required": false, "example": "permanently_delete", "schema": { "type": "string", "enum": [ "permanently_delete", "remove_retention" ] } }, { "name": "disposition_before", "description": "Filters results by files that will have their disposition\ncome into effect before this date.", "in": "query", "required": false, "example": "2012-12-12T10:53:43-08:00", "schema": { "type": "string" } }, { "name": "disposition_after", "description": "Filters results by files that will have their disposition\ncome into effect after this date.", "in": "query", "required": false, "example": "2012-12-19T10:34:23-08:00", "schema": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a list of all file version retentions for the enterprise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileVersionRetentions" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/legal_hold_policy_assignments/{legal_hold_policy_assignment_id}/file_versions_on_hold": { "get": { "operationId": "get_legal_hold_policy_assignments_id_file_versions_on_hold", "summary": "List previous file versions for legal hold policy assignment", "tags": [ "Legal hold policy assignments" ], "x-box-tag": "legal_hold_policy_assignments", "description": "Get a list of previous file versions for a legal hold\nassignment.\n\nIn some cases you may only need the latest file versions instead. In these\ncases, use the `GET /legal_hold_policy_assignments/:id/files_on_hold` API\ninstead to return any current (latest) versions of a file for this legal hold\npolicy assignment.\n\nDue to ongoing re-architecture efforts this API might not return all files\nheld for this policy ID. Instead, this API will only return past file versions\nheld in the newly developed architecture. The `GET /file_version_legal_holds`\nAPI can be used to fetch current and past versions of files held within the\nlegacy architecture.\n\nThe `GET /legal_hold_policy_assignments?policy_id={id}` API can be used to\nfind a list of policy assignments for a given policy ID.", "parameters": [ { "name": "legal_hold_policy_assignment_id", "description": "The ID of the legal hold policy assignment", "example": "753465", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Returns the list of previous file versions held under legal hold for a\nspecific legal hold policy assignment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileVersionLegalHolds" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/file_version_retentions/{file_version_retention_id}": { "get": { "operationId": "get_file_version_retentions_id", "tags": [ "File version retentions" ], "x-box-tag": "file_version_retentions", "summary": "Get retention on file", "description": "Returns information about a file version retention.", "parameters": [ { "name": "file_version_retention_id", "description": "The ID of the file version retention", "in": "path", "required": true, "example": "3424234", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a file version retention object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileVersionRetention" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/file_version_legal_holds/{file_version_legal_hold_id}": { "get": { "operationId": "get_file_version_legal_holds_id", "summary": "Get file version legal hold", "tags": [ "File version legal holds" ], "x-box-tag": "file_version_legal_holds", "description": "Retrieves information about the legal hold policies\nassigned to a file version.", "parameters": [ { "name": "file_version_legal_hold_id", "description": "The ID of the file version legal hold", "in": "path", "required": true, "example": "2348213", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the legal hold policy assignments for the file version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileVersionLegalHold" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/file_version_legal_holds": { "get": { "operationId": "get_file_version_legal_holds", "summary": "List file version legal holds", "tags": [ "File version legal holds" ], "x-box-tag": "file_version_legal_holds", "description": "Get a list of file versions on legal hold for a legal hold\nassignment.\n\nDue to ongoing re-architecture efforts this API might not return all file\nversions for this policy ID.\n\nInstead, this API will only return file versions held in the legacy\narchitecture. Two new endpoints will available to request any file versions\nheld in the new architecture.\n\nFor file versions held in the new architecture, the `GET\n/legal_hold_policy_assignments/:id/file_versions_on_hold` API can be used to\nreturn all past file versions available for this policy assignment, and the\n`GET /legal_hold_policy_assignments/:id/files_on_hold` API can be used to\nreturn any current (latest) versions of a file under legal hold.\n\nThe `GET /legal_hold_policy_assignments?policy_id={id}` API can be used to\nfind a list of policy assignments for a given policy ID.\n\nOnce the re-architecture is completed this API will be deprecated.", "parameters": [ { "name": "policy_id", "description": "The ID of the legal hold policy to get the file version legal\nholds for.", "in": "query", "example": "133870", "required": true, "schema": { "type": "string" } }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } } ], "responses": { "200": { "description": "Returns the list of file version legal holds for a specific legal\nhold policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileVersionLegalHolds" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/shield_information_barriers/{shield_information_barrier_id}": { "get": { "operationId": "get_shield_information_barriers_id", "summary": "Get shield information barrier with specified ID", "tags": [ "Shield information barriers" ], "x-box-tag": "shield_information_barriers", "x-box-scopes": [ "manage_managed_users" ], "description": "Get shield information barrier based on provided ID..", "parameters": [ { "name": "shield_information_barrier_id", "description": "The ID of the shield information barrier.", "example": "1910967", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the shield information barrier object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrier" } } } }, "404": { "description": "Returns a `not_found` error if\nthe shield information barrier was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/shield_information_barriers/change_status": { "post": { "operationId": "post_shield_information_barriers_change_status", "summary": "Add changed status of shield information barrier with specified ID", "tags": [ "Shield information barriers" ], "x-box-tag": "shield_information_barriers", "x-box-scopes": [ "manage_managed_users" ], "description": "Change status of shield information barrier with the specified ID.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "string", "example": "1910967", "description": "The ID of the shield information barrier." }, "status": { "type": "string", "enum": [ "pending", "disabled" ], "example": "pending", "description": "The desired status for the shield information barrier." } } } } } }, "responses": { "200": { "description": "Returns the updated shield information barrier object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrier" } } } }, "404": { "description": "Returns a `not_found` error if the\nshield information barrier was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error if there exists Conflicts\nwith existing information barriers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/shield_information_barriers": { "get": { "operationId": "get_shield_information_barriers", "summary": "List shield information barriers", "tags": [ "Shield information barriers" ], "x-box-tag": "shield_information_barriers", "x-box-scopes": [ "manage_managed_users" ], "description": "Retrieves a list of shield information barrier objects\nfor the enterprise of JWT.", "parameters": [ { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } } ], "responses": { "200": { "description": "Returns a paginated list of\nshield information barrier objects,\nempty list if currently no barrier.", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "description": "The limit that was used for these entries.\nThis will be the same as the\n`limit` query parameter unless that\nvalue exceeded the maximum value\nallowed. The maximum value varies by API.", "example": 1000, "type": "integer", "format": "int64" }, "next_marker": { "description": "The marker for the start of the next page of results.", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "type": "string" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/ShieldInformationBarrier" } } } } } } }, "404": { "description": "Returns a `not_found` error if could not find an enterprise using JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_shield_information_barriers", "summary": "Create shield information barrier", "tags": [ "Shield information barriers" ], "x-box-tag": "shield_information_barriers", "x-box-scopes": [ "manage_managed_users" ], "description": "Creates a shield information barrier to\nseparate individuals/groups within the same\nfirm and prevents confidential information passing between them.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrier" } } } }, "responses": { "201": { "description": "Returns a new shield information barrier object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrier" } } } }, "404": { "description": "Returns an error if the enterprise was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/shield_information_barrier_reports": { "get": { "operationId": "get_shield_information_barrier_reports", "summary": "List shield information barrier reports", "tags": [ "Shield information barrier reports" ], "x-box-tag": "shield_information_barrier_reports", "x-box-scopes": [ "manage_managed_users" ], "description": "Lists shield information barrier reports with specific IDs.", "parameters": [ { "name": "shield_information_barrier_id", "description": "The ID of the shield information barrier.", "example": "1910967", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } } ], "responses": { "200": { "description": "Returns a paginated list of shield information barrier report objects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "description": "The limit that was used for these entries.\nThis will be the same as the\n`limit` query parameter unless that\nvalue exceeded the maximum value\nallowed. The maximum value varies by API.", "example": 1000, "type": "integer", "format": "int64" }, "next_marker": { "description": "The marker for the start of the next page of results.", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "type": "string" }, "entries": { "type": "array", "description": "A list of shield barrier reports.", "items": { "$ref": "#/components/schemas/ShieldInformationBarrierReport" } } } } } } }, "404": { "description": "Returns a `not_found` error if the\nshield information barrier was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_shield_information_barrier_reports", "summary": "Create shield information barrier report", "tags": [ "Shield information barrier reports" ], "x-box-tag": "shield_information_barrier_reports", "x-box-scopes": [ "manage_managed_users" ], "description": "Creates a shield information barrier report for a given barrier.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrierReference" } } } }, "responses": { "201": { "description": "Returns the shield information barrier report information object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrierReport" } } } }, "404": { "description": "Returns a `not_found` error if\nthe shield information barrier report was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns a `conflict` error if a\nshield information barrier report is currently being created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/shield_information_barrier_reports/{shield_information_barrier_report_id}": { "get": { "operationId": "get_shield_information_barrier_reports_id", "summary": "Get shield information barrier report by ID", "tags": [ "Shield information barrier reports" ], "x-box-tag": "shield_information_barrier_reports", "x-box-scopes": [ "manage_managed_users" ], "description": "Retrieves a shield information barrier report by its ID.", "parameters": [ { "name": "shield_information_barrier_report_id", "description": "The ID of the shield information barrier Report.", "example": "3423", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the shield information barrier report object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrierReport" } } } }, "404": { "description": "Returns a `not_found` error if the\nshield information barrier Report was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/shield_information_barrier_segments/{shield_information_barrier_segment_id}": { "get": { "operationId": "get_shield_information_barrier_segments_id", "summary": "Get shield information barrier segment with specified ID", "tags": [ "Shield information barrier segments" ], "x-box-tag": "shield_information_barrier_segments", "x-box-scopes": [ "manage_managed_users" ], "description": "Retrieves shield information barrier segment based on provided ID..", "parameters": [ { "name": "shield_information_barrier_segment_id", "description": "The ID of the shield information barrier segment.", "example": "3423", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the shield information barrier segment object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrierSegment" } } } }, "404": { "description": "Returns a `not_found` error if the\nshield information barrier segment was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_shield_information_barrier_segments_id", "summary": "Delete shield information barrier segment", "tags": [ "Shield information barrier segments" ], "x-box-tag": "shield_information_barrier_segments", "x-box-scopes": [ "manage_managed_users" ], "description": "Deletes the shield information barrier segment\nbased on provided ID.", "parameters": [ { "name": "shield_information_barrier_segment_id", "description": "The ID of the shield information barrier segment.", "example": "3423", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Empty body in response" }, "404": { "description": "Returns a `not_found` error if the shield information\nbarrier segment with specified ID was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "put": { "operationId": "put_shield_information_barrier_segments_id", "summary": "Update shield information barrier segment with specified ID", "tags": [ "Shield information barrier segments" ], "x-box-tag": "shield_information_barrier_segments", "x-box-scopes": [ "manage_managed_users" ], "description": "Updates the shield information barrier segment based on provided ID..", "parameters": [ { "name": "shield_information_barrier_segment_id", "description": "The ID of the shield information barrier segment.", "example": "3423", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "An object containing update(s) to be made on the Shield\nInformation Barrier Segment. Possible properties include\n'name' and 'description', the value in object is the update.", "properties": { "name": { "type": "string", "pattern": "\\S+", "example": "Investment Banking", "description": "The updated name for the shield information barrier segment." }, "description": { "type": "string", "nullable": true, "example": "'Corporate division that engages in advisory_based\nfinancial transactions on behalf of individuals,\ncorporations, and governments.'", "description": "The updated description for\nthe shield information barrier segment." } } } } } }, "responses": { "200": { "description": "Returns the updated shield information barrier segment object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrierSegment" } } } }, "404": { "description": "Returns a `not_found` error if the shield information\nBarrier Segment was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error if there exists a shield information\nBarrier Segment with the same name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/shield_information_barrier_segments": { "get": { "operationId": "get_shield_information_barrier_segments", "summary": "List shield information barrier segments", "tags": [ "Shield information barrier segments" ], "x-box-tag": "shield_information_barrier_segments", "x-box-scopes": [ "manage_managed_users" ], "description": "Retrieves a list of shield information barrier segment objects\nfor the specified Information Barrier ID.", "parameters": [ { "name": "shield_information_barrier_id", "description": "The ID of the shield information barrier.", "example": "1910967", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } } ], "responses": { "200": { "description": "Returns a paginated list of shield information barrier segment objects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "description": "The limit that was used for these entries.\nThis will be the same as the\n`limit` query parameter unless\nthat value exceeded the maximum value\nallowed. The maximum value varies by API.", "example": 1000, "type": "integer", "format": "int64" }, "next_marker": { "description": "The marker for the start of the next page of results.", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "type": "string" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/ShieldInformationBarrierSegment" } } } } } } }, "404": { "description": "Returns a `not_found` error if the shield information\nBarrier of given ID was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_shield_information_barrier_segments", "summary": "Create shield information barrier segment", "tags": [ "Shield information barrier segments" ], "x-box-tag": "shield_information_barrier_segments", "x-box-scopes": [ "manage_managed_users" ], "description": "Creates a shield information barrier segment.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "shield_information_barrier", "name" ], "properties": { "shield_information_barrier": { "$ref": "#/components/schemas/ShieldInformationBarrier--Base" }, "name": { "type": "string", "example": "Investment Banking", "description": "Name of the shield information barrier segment" }, "description": { "type": "string", "example": "'Corporate division that engages in\n advisory_based financial\ntransactions on behalf of individuals,\ncorporations, and governments.'", "description": "Description of the shield information barrier segment" } } } } } }, "responses": { "201": { "description": "Returns a new shield information barrier segment object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrierSegment" } } } }, "404": { "description": "Returns an error if the shield information barrier\nwas not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error if there exists an shield information\nbarrier segment with same name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/shield_information_barrier_segment_members/{shield_information_barrier_segment_member_id}": { "get": { "operationId": "get_shield_information_barrier_segment_members_id", "summary": "Get shield information barrier segment member by ID", "tags": [ "Shield information barrier segment members" ], "x-box-tag": "shield_information_barrier_segment_members", "x-box-scopes": [ "manage_managed_users" ], "description": "Retrieves a shield information barrier\nsegment member by its ID.", "parameters": [ { "name": "shield_information_barrier_segment_member_id", "description": "The ID of the shield information barrier segment Member.", "example": "7815", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the shield information barrier segment member object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrierSegmentMember" } } } }, "404": { "description": "Returns a `not_found` error if\nthe shield information barrier segment member was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_shield_information_barrier_segment_members_id", "summary": "Delete shield information barrier segment member by ID", "tags": [ "Shield information barrier segment members" ], "x-box-tag": "shield_information_barrier_segment_members", "x-box-scopes": [ "manage_managed_users" ], "description": "Deletes a shield information barrier\nsegment member based on provided ID.", "parameters": [ { "name": "shield_information_barrier_segment_member_id", "description": "The ID of the shield information barrier segment Member.", "example": "7815", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Returns an empty response if the\nsegment member was deleted successfully." }, "404": { "description": "Returns a `not_found` error if the\nshield information barrier segment member was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/shield_information_barrier_segment_members": { "get": { "operationId": "get_shield_information_barrier_segment_members", "summary": "List shield information barrier segment members", "tags": [ "Shield information barrier segment members" ], "x-box-tag": "shield_information_barrier_segment_members", "x-box-scopes": [ "manage_managed_users" ], "description": "Lists shield information barrier segment members\nbased on provided segment IDs.", "parameters": [ { "name": "shield_information_barrier_segment_id", "description": "The ID of the shield information barrier segment.", "example": "3423", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } } ], "responses": { "200": { "description": "Returns a paginated list of\nshield information barrier segment member objects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "description": "The limit that was used for these entries.\nThis will be the same as the\n`limit` query parameter unless that value\nexceeded the maximum value\nallowed. The maximum value varies by API.", "example": 1000, "type": "integer", "format": "int64" }, "next_marker": { "description": "The marker for the start of the next page of results.", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "type": "string" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/ShieldInformationBarrierSegmentMember" } } } } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_shield_information_barrier_segment_members", "summary": "Create shield information barrier segment member", "tags": [ "Shield information barrier segment members" ], "x-box-tag": "shield_information_barrier_segment_members", "x-box-scopes": [ "manage_managed_users" ], "description": "Creates a new shield information barrier segment member.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "shield_information_barrier_segment", "user" ], "properties": { "type": { "description": "-| A type of the shield barrier segment member.", "type": "string", "example": "shield_information_barrier_segment_member", "enum": [ "shield_information_barrier_segment_member" ] }, "shield_information_barrier": { "$ref": "#/components/schemas/ShieldInformationBarrier--Base" }, "shield_information_barrier_segment": { "type": "object", "properties": { "id": { "type": "string", "example": "432554", "description": "The ID reference of the\nrequesting shield information barrier segment." }, "type": { "type": "string", "description": "The type of the shield barrier segment for this member.", "example": "shield_information_barrier_segment", "enum": [ "shield_information_barrier_segment" ] } }, "description": "The `type` and `id` of the\nrequested shield information barrier segment." }, "user": { "allOf": [ { "$ref": "#/components/schemas/User--Base" }, { "description": "The `type` and `id` of the requested shield information barrier segment Member." } ] } } } } } }, "responses": { "201": { "description": "Returns a new shield information barrier segment Member object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrierSegmentMember" } } } }, "404": { "description": "Returns an error if the\nshield information barrier or Segment was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/shield_information_barrier_segment_restrictions/{shield_information_barrier_segment_restriction_id}": { "get": { "operationId": "get_shield_information_barrier_segment_restrictions_id", "summary": "Get shield information barrier segment restriction by ID", "tags": [ "Shield information barrier segment restrictions" ], "x-box-tag": "shield_information_barrier_segment_restrictions", "x-box-scopes": [ "manage_managed_users" ], "description": "Retrieves a shield information barrier segment\nrestriction based on provided ID.", "parameters": [ { "name": "shield_information_barrier_segment_restriction_id", "description": "The ID of the shield information barrier segment Restriction.", "example": "4563", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the shield information barrier segment\nrestriction object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrierSegmentRestriction" } } } }, "404": { "description": "Returns a `not_found` error if the\nshield information barrier segment\nrestriction was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_shield_information_barrier_segment_restrictions_id", "summary": "Delete shield information barrier segment restriction by ID", "tags": [ "Shield information barrier segment restrictions" ], "x-box-tag": "shield_information_barrier_segment_restrictions", "x-box-scopes": [ "manage_managed_users" ], "description": "Delete shield information barrier segment restriction\nbased on provided ID.", "parameters": [ { "name": "shield_information_barrier_segment_restriction_id", "description": "The ID of the shield information barrier segment Restriction.", "example": "4563", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Empty body in response" }, "404": { "description": "Returns a `not_found` error if the\nshield information barrier segment restriction was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/shield_information_barrier_segment_restrictions": { "get": { "operationId": "get_shield_information_barrier_segment_restrictions", "summary": "List shield information barrier segment restrictions", "tags": [ "Shield information barrier segment restrictions" ], "x-box-tag": "shield_information_barrier_segment_restrictions", "x-box-scopes": [ "manage_managed_users" ], "description": "Lists shield information barrier segment restrictions\nbased on provided segment ID.", "parameters": [ { "name": "shield_information_barrier_segment_id", "description": "The ID of the shield information barrier segment.", "example": "3423", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } } ], "responses": { "200": { "description": "Returns a paginated list of\nshield information barrier segment restriction objects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "description": "The limit that was used for these entries.\nThis will be the same as the\n`limit` query parameter unless\nthat value exceeded the maximum value\nallowed. The maximum value varies by API.", "example": 1000, "type": "integer", "format": "int64" }, "next_marker": { "description": "The marker for the start of the next page of results.", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "type": "string" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/ShieldInformationBarrierSegmentRestriction" } } } } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_shield_information_barrier_segment_restrictions", "summary": "Create shield information barrier segment restriction", "tags": [ "Shield information barrier segment restrictions" ], "x-box-tag": "shield_information_barrier_segment_restrictions", "x-box-scopes": [ "manage_managed_users" ], "description": "Creates a shield information barrier\nsegment restriction object.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "shield_information_barrier_segment", "restricted_segment" ], "properties": { "type": { "type": "string", "description": "The type of the shield barrier segment\nrestriction for this member.", "example": "shield_information_barrier_segment_restriction", "enum": [ "shield_information_barrier_segment_restriction" ] }, "shield_information_barrier": { "$ref": "#/components/schemas/ShieldInformationBarrier--Base" }, "shield_information_barrier_segment": { "type": "object", "properties": { "id": { "type": "string", "example": "1910967", "description": "The ID reference of the requesting\nshield information barrier segment." }, "type": { "type": "string", "description": "The type of the shield barrier segment for this member.", "example": "shield_information_barrier_segment", "enum": [ "shield_information_barrier_segment" ] } }, "description": "The `type` and `id` of the requested\nshield information barrier segment." }, "restricted_segment": { "type": "object", "properties": { "id": { "type": "string", "example": "1910967", "description": "The ID reference of the restricted\nshield information barrier segment." }, "type": { "type": "string", "example": "shield_information_barrier_segment", "description": "The type of the restricted shield\ninformation barrier segment.", "enum": [ "shield_information_barrier_segment" ] } }, "description": "The `type` and `id` of the restricted\nshield information barrier segment." } } } } } }, "responses": { "201": { "description": "Returns the newly created Shield\nInformation Barrier Segment Restriction object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrierSegmentRestriction" } } } }, "404": { "description": "Returns a `not_found` error if the\nshield information barrier or Segment was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/device_pinners/{device_pinner_id}": { "get": { "operationId": "get_device_pinners_id", "summary": "Get device pin", "tags": [ "Device pinners" ], "x-box-tag": "device_pinners", "description": "Retrieves information about an individual device pin.", "parameters": [ { "name": "device_pinner_id", "description": "The ID of the device pin", "in": "path", "required": true, "example": "2324234", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns information about a single device pin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevicePinner" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_device_pinners_id", "summary": "Remove device pin", "tags": [ "Device pinners" ], "x-box-tag": "device_pinners", "description": "Deletes an individual device pin.", "parameters": [ { "name": "device_pinner_id", "description": "The ID of the device pin", "in": "path", "required": true, "example": "2324234", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Returns an empty response when the pin has been deleted." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/enterprises/{enterprise_id}/device_pinners": { "get": { "operationId": "get_enterprises_id_device_pinners", "summary": "List enterprise device pins", "tags": [ "Device pinners" ], "x-box-tag": "device_pinners", "description": "Retrieves all the device pins within an enterprise.\n\nThe user must have admin privileges, and the application\nneeds the \"manage enterprise\" scope to make this call.", "parameters": [ { "name": "enterprise_id", "description": "The ID of the enterprise", "in": "path", "required": true, "example": "3442311", "schema": { "type": "string" } }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } }, { "name": "direction", "description": "The direction to sort results in. This can be either in alphabetical ascending\n(`ASC`) or descending (`DESC`) order.", "in": "query", "required": false, "example": "ASC", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] } } ], "responses": { "200": { "description": "Returns a list of device pins for a given enterprise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevicePinners" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/terms_of_services": { "get": { "operationId": "get_terms_of_services", "x-box-tag": "terms_of_services", "summary": "List terms of services", "tags": [ "Terms of service" ], "description": "Returns the current terms of service text and settings\nfor the enterprise.", "parameters": [ { "name": "tos_type", "description": "Limits the results to the terms of service of the given type.", "in": "query", "required": false, "example": "managed", "schema": { "type": "string", "enum": [ "external", "managed" ] } } ], "responses": { "200": { "description": "Returns a collection of terms of service text and settings for the\nenterprise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermsOfServices" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_terms_of_services", "tags": [ "Terms of service" ], "summary": "Create terms of service", "x-box-tag": "terms_of_services", "description": "Creates a terms of service for a given enterprise\nand type of user.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "text" ], "properties": { "status": { "description": "Whether this terms of service is active.", "example": "enabled", "type": "string", "enum": [ "enabled", "disabled" ] }, "tos_type": { "description": "The type of user to set the terms of\nservice for.", "example": "managed", "type": "string", "enum": [ "external", "managed" ] }, "text": { "description": "The terms of service text to display to users.\n\nThe text can be set to empty if the `status` is set to `disabled`.", "example": "By collaborating on this file you are accepting...", "type": "string" } } } } } }, "responses": { "200": { "description": "Returns a new task object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/terms_of_services/{terms_of_service_id}": { "get": { "operationId": "get_terms_of_services_id", "summary": "Get terms of service", "tags": [ "Terms of service" ], "x-box-tag": "terms_of_services", "description": "Fetches a specific terms of service.", "parameters": [ { "name": "terms_of_service_id", "description": "The ID of the terms of service.", "example": "324234", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a terms of service object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermsOfService" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "put": { "operationId": "put_terms_of_services_id", "summary": "Update terms of service", "tags": [ "Terms of service" ], "x-box-tag": "terms_of_services", "description": "Updates a specific terms of service.", "parameters": [ { "name": "terms_of_service_id", "description": "The ID of the terms of service.", "example": "324234", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "text" ], "properties": { "status": { "description": "Whether this terms of service is active.", "example": "enabled", "type": "string", "enum": [ "enabled", "disabled" ] }, "text": { "description": "The terms of service text to display to users.\n\nThe text can be set to empty if the `status` is set to `disabled`.", "example": "By collaborating on this file you are accepting...", "type": "string" } } } } } }, "responses": { "200": { "description": "Returns an updated terms of service object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermsOfService" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/terms_of_service_user_statuses": { "get": { "operationId": "get_terms_of_service_user_statuses", "summary": "List terms of service user statuses", "tags": [ "Terms of service user statuses" ], "x-box-tag": "terms_of_service_user_statuses", "description": "Retrieves an overview of users and their status for a\nterms of service, including Whether they have accepted\nthe terms and when.", "parameters": [ { "name": "tos_id", "description": "The ID of the terms of service.", "example": "324234", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "description": "Limits results to the given user ID.", "example": "123334", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a list of terms of service statuses.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermsOfServiceUserStatuses" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_terms_of_service_user_statuses", "summary": "Create terms of service status for new user", "tags": [ "Terms of service user statuses" ], "x-box-tag": "terms_of_service_user_statuses", "description": "Sets the status for a terms of service for a user.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "tos", "user", "is_accepted" ], "properties": { "tos": { "type": "object", "description": "The terms of service to set the status for.", "required": [ "id", "type" ], "properties": { "type": { "type": "string", "description": "The type of object.", "example": "terms_of_service", "enum": [ "terms_of_service" ] }, "id": { "type": "string", "description": "The ID of terms of service", "example": "1232132" } } }, "user": { "type": "object", "description": "The user to set the status for.", "required": [ "id", "type" ], "properties": { "type": { "type": "string", "description": "The type of object.", "example": "user", "enum": [ "user" ] }, "id": { "type": "string", "description": "The ID of user", "example": "3423423" } } }, "is_accepted": { "type": "boolean", "example": true, "description": "Whether the user has accepted the terms." } } } } } }, "responses": { "201": { "description": "Returns a terms of service status object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermsOfServiceUserStatus" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/terms_of_service_user_statuses/{terms_of_service_user_status_id}": { "put": { "operationId": "put_terms_of_service_user_statuses_id", "summary": "Update terms of service status for existing user", "tags": [ "Terms of service user statuses" ], "x-box-tag": "terms_of_service_user_statuses", "description": "Updates the status for a terms of service for a user.", "parameters": [ { "name": "terms_of_service_user_status_id", "description": "The ID of the terms of service status.", "example": "324234", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "is_accepted" ], "properties": { "is_accepted": { "type": "boolean", "example": true, "description": "Whether the user has accepted the terms." } } } } } }, "responses": { "200": { "description": "Returns the updated terms of service status object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermsOfServiceUserStatus" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/collaboration_whitelist_entries": { "get": { "operationId": "get_collaboration_whitelist_entries", "summary": "List allowed collaboration domains", "tags": [ "Domain restrictions for collaborations" ], "x-box-tag": "collaboration_allowlist_entries", "description": "Returns the list domains that have been deemed safe to create collaborations\nfor within the current enterprise.", "parameters": [ { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } } ], "responses": { "200": { "description": "Returns a collection of domains that are allowed for collaboration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationAllowlistEntries" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_collaboration_whitelist_entries", "summary": "Add domain to list of allowed collaboration domains", "tags": [ "Domain restrictions for collaborations" ], "x-box-tag": "collaboration_allowlist_entries", "description": "Creates a new entry in the list of allowed domains to allow\ncollaboration for.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "domain", "direction" ], "properties": { "domain": { "type": "string", "description": "The domain to add to the list of allowed domains.", "example": "example.com" }, "direction": { "type": "string", "description": "The direction in which to allow collaborations.", "example": "inbound", "enum": [ "inbound", "outbound", "both" ] } } } } } }, "responses": { "200": { "description": "Returns a new entry on the list of allowed domains.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationAllowlistEntry" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/collaboration_whitelist_entries/{collaboration_whitelist_entry_id}": { "get": { "operationId": "get_collaboration_whitelist_entries_id", "summary": "Get allowed collaboration domain", "tags": [ "Domain restrictions for collaborations" ], "x-box-tag": "collaboration_allowlist_entries", "description": "Returns a domain that has been deemed safe to create collaborations\nfor within the current enterprise.", "parameters": [ { "name": "collaboration_whitelist_entry_id", "description": "The ID of the entry in the list.", "in": "path", "required": true, "example": "213123", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns an entry on the list of allowed domains.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationAllowlistEntry" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_collaboration_whitelist_entries_id", "summary": "Remove domain from list of allowed collaboration domains", "tags": [ "Domain restrictions for collaborations" ], "x-box-tag": "collaboration_allowlist_entries", "description": "Removes a domain from the list of domains that have been deemed safe to create\ncollaborations for within the current enterprise.", "parameters": [ { "name": "collaboration_whitelist_entry_id", "description": "The ID of the entry in the list.", "in": "path", "required": true, "example": "213123", "schema": { "type": "string" } } ], "responses": { "204": { "description": "A blank response is returned if the entry was\nsuccessfully deleted." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/collaboration_whitelist_exempt_targets": { "get": { "operationId": "get_collaboration_whitelist_exempt_targets", "summary": "List users exempt from collaboration domain restrictions", "tags": [ "Domain restrictions (User exemptions)" ], "x-box-tag": "collaboration_allowlist_exempt_targets", "description": "Returns a list of users who have been exempt from the collaboration\ndomain restrictions.", "parameters": [ { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } } ], "responses": { "200": { "description": "Returns a collection of user exemptions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationAllowlistExemptTargets" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_collaboration_whitelist_exempt_targets", "summary": "Create user exemption from collaboration domain restrictions", "tags": [ "Domain restrictions (User exemptions)" ], "x-box-tag": "collaboration_allowlist_exempt_targets", "description": "Exempts a user from the restrictions set out by the allowed list of domains\nfor collaborations.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "user" ], "properties": { "user": { "type": "object", "description": "The user to exempt.", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The ID of the user to exempt.", "example": "23522323" } } } } } } } }, "responses": { "200": { "description": "Returns a new exemption entry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationAllowlistExemptTarget" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/collaboration_whitelist_exempt_targets/{collaboration_whitelist_exempt_target_id}": { "get": { "operationId": "get_collaboration_whitelist_exempt_targets_id", "summary": "Get user exempt from collaboration domain restrictions", "tags": [ "Domain restrictions (User exemptions)" ], "x-box-tag": "collaboration_allowlist_exempt_targets", "description": "Returns a users who has been exempt from the collaboration\ndomain restrictions.", "parameters": [ { "name": "collaboration_whitelist_exempt_target_id", "description": "The ID of the exemption to the list.", "in": "path", "required": true, "example": "984923", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the user's exempted from the list of collaboration domains.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationAllowlistExemptTarget" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_collaboration_whitelist_exempt_targets_id", "summary": "Remove user from list of users exempt from domain restrictions", "tags": [ "Domain restrictions (User exemptions)" ], "x-box-tag": "collaboration_allowlist_exempt_targets", "description": "Removes a user's exemption from the restrictions set out by the allowed list\nof domains for collaborations.", "parameters": [ { "name": "collaboration_whitelist_exempt_target_id", "description": "The ID of the exemption to the list.", "in": "path", "required": true, "example": "984923", "schema": { "type": "string" } } ], "responses": { "204": { "description": "A blank response is returned if the exemption was\nsuccessfully deleted." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/storage_policies": { "get": { "operationId": "get_storage_policies", "summary": "List storage policies", "tags": [ "Storage policies" ], "x-box-tag": "storage_policies", "description": "Fetches all the storage policies in the enterprise.", "parameters": [ { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "example": [ "id", "type", "name" ], "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } } ], "responses": { "200": { "description": "Returns a collection of storage policies.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoragePolicies" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/storage_policies/{storage_policy_id}": { "get": { "operationId": "get_storage_policies_id", "summary": "Get storage policy", "tags": [ "Storage policies" ], "x-box-tag": "storage_policies", "description": "Fetches a specific storage policy.", "parameters": [ { "name": "storage_policy_id", "description": "The ID of the storage policy.", "example": "34342", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a storage policy object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoragePolicy" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/storage_policy_assignments": { "get": { "operationId": "get_storage_policy_assignments", "summary": "List storage policy assignments", "tags": [ "Storage policy assignments" ], "x-box-tag": "storage_policy_assignments", "description": "Fetches all the storage policy assignment for an enterprise or user.", "parameters": [ { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } }, { "name": "resolved_for_type", "in": "query", "example": "user", "description": "The target type to return assignments for", "required": true, "schema": { "type": "string", "enum": [ "user", "enterprise" ] } }, { "name": "resolved_for_id", "in": "query", "required": true, "example": "984322", "description": "The ID of the user or enterprise to return assignments for", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a collection of storage policies for\nthe enterprise or user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoragePolicyAssignments" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_storage_policy_assignments", "summary": "Assign storage policy", "tags": [ "Storage policy assignments" ], "x-box-tag": "storage_policy_assignments", "description": "Creates a storage policy assignment for an enterprise or user.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "storage_policy", "assigned_to" ], "properties": { "storage_policy": { "type": "object", "description": "The storage policy to assign to the user or\nenterprise", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "The type to assign.", "example": "storage_policy", "enum": [ "storage_policy" ] }, "id": { "type": "string", "description": "The ID of the storage policy to assign.", "example": "1434325" } } }, "assigned_to": { "type": "object", "description": "The user or enterprise to assign the storage\npolicy to.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "The type to assign the policy to.", "example": "user", "enum": [ "user", "enterprise" ] }, "id": { "type": "string", "description": "The ID of the user or enterprise", "example": "9987987" } } } } } } } }, "responses": { "200": { "description": "Returns the new storage policy assignment created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoragePolicyAssignment" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/storage_policy_assignments/{storage_policy_assignment_id}": { "get": { "operationId": "get_storage_policy_assignments_id", "summary": "Get storage policy assignment", "tags": [ "Storage policy assignments" ], "x-box-tag": "storage_policy_assignments", "description": "Fetches a specific storage policy assignment.", "parameters": [ { "name": "storage_policy_assignment_id", "description": "The ID of the storage policy assignment.", "example": "932483", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a storage policy assignment object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoragePolicyAssignment" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "put": { "operationId": "put_storage_policy_assignments_id", "summary": "Update storage policy assignment", "tags": [ "Storage policy assignments" ], "x-box-tag": "storage_policy_assignments", "description": "Updates a specific storage policy assignment.", "parameters": [ { "name": "storage_policy_assignment_id", "description": "The ID of the storage policy assignment.", "example": "932483", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "storage_policy" ], "properties": { "storage_policy": { "type": "object", "description": "The storage policy to assign to the user or\nenterprise", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "The type to assign.", "example": "storage_policy", "enum": [ "storage_policy" ] }, "id": { "type": "string", "description": "The ID of the storage policy to assign.", "example": "1434325" } } } } } } } }, "responses": { "200": { "description": "Returns an updated storage policy assignment object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoragePolicyAssignment" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_storage_policy_assignments_id", "summary": "Unassign storage policy", "tags": [ "Storage policy assignments" ], "x-box-tag": "storage_policy_assignments", "description": "Delete a storage policy assignment.\n\nDeleting a storage policy assignment on a user\nwill have the user inherit the enterprise's default\nstorage policy.\n\nThere is a rate limit for calling this endpoint of only\ntwice per user in a 24 hour time frame.", "parameters": [ { "name": "storage_policy_assignment_id", "description": "The ID of the storage policy assignment.", "example": "932483", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Returns an empty response when the storage policy\nassignment is successfully deleted." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/zip_downloads": { "post": { "operationId": "post_zip_downloads", "summary": "Create zip download", "tags": [ "Zip Downloads" ], "x-box-tag": "zip_downloads", "x-box-reference-category": "zip_downloads", "description": "Creates a request to download multiple files and folders as a single `zip`\narchive file. This API does not return the archive but instead performs all\nthe checks to ensure that the user has access to all the items, and then\nreturns a `download_url` and a `status_url` that can be used to download the\narchive.\n\nThe limit for an archive is either the Account's upload limit or\n10,000 files, whichever is met first", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZipDownloadRequest" } } } }, "responses": { "202": { "description": "If the `zip` archive is ready to be downloaded, the API will return a\nresponse that will include a `download_url`, a `status_url`, as well as\nany conflicts that might have occurred when creating the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZipDownload" }, "examples": { "default": { "value": { "download_url": "https://dl.boxcloud.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/content", "status_url": "https://api.box.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/status", "expires_at": "2020-07-22T11:26:08Z", "name_conflicts": [ [ { "id": "12345", "type": "file", "original_name": "Report.pdf", "download_name": "3aa6a7.pdf" }, { "id": "34325", "type": "file", "original_name": "Report.pdf", "download_name": "5d53f2.pdf" } ] ] } } } } } }, "400": { "description": "Returns an error if some of the parameters are missing or\nnot valid.\n\nIn most cases, this error might happen because the JSON request body is\nnot valid JSON, any of the items has an incorrect or missing ID, any of\nthe items is not a file or folder, or the root folder with ID `0` has been\nadded to the list of folders to add to the archive.\n\nThe following is a list of common error codes for this response.\n\n* `bad_request` - the request body is missing, invalid, or both the list\nof files and folders are empty. Additionally, it this error might be\nreturned when attempting to add the root folder with ID `0` to an archive.\n* `zip_download_file_count_exceeded_limit` - the requested files and\nfolders would result in an archive with more than 10,000 files. The\nrequest will have to be split into multiple requests to reduce the number\nof files per archive.\n* `zip_download_pre_compressed_bytes_exceeded_limit` - the requested files\nand folders would result in an archive with more than the allowed download\nlimit. The request will have to be split into multiple requests to reduce\nthe size of the archive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned when an authorization header is provided but the user does not\nhave access to the items.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/zip_downloads/{zip_download_id}/content": { "get": { "operationId": "get_zip_downloads_id_content", "summary": "Download zip archive", "tags": [ "Zip Downloads" ], "x-box-tag": "zip_downloads", "x-box-reference-category": "zip_downloads", "description": "Returns the contents of a `zip` archive in binary format. This URL does not\nrequire any form of authentication and could be used in a user's browser to\ndownload the archive to a user's device.\n\nBy default, this URL is only valid for a few seconds from the creation of\nthe request for this archive. Once a download has started it can not be\nstopped and resumed, instead a new request for a zip archive would need to\nbe created.\n\nThe URL of this endpoint should not be considered as fixed. Instead, use\nthe [Create zip download](e://post_zip_downloads) API to request to create a\n`zip` archive, and then follow the `download_url` field in the response to\nthis endpoint.", "security": [], "servers": [ { "url": "https://dl.boxcloud.com/2.0", "description": "An opaque server URL for downloading zip downloads. The format\nof this URL might change over time." } ], "parameters": [ { "name": "zip_download_id", "description": "The unique identifier that represent this `zip` archive.", "example": "Lu6fA9Ob-jyysp3AAvMF4AkLEwZwAYbL=tgj2zIC=eK9RvJnJbjJl9rNh2qBgHDpyOCAOhpM=vajg2mKq8Mdd", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the content of the items requested for this download, formatted as\na stream of files and folders in a `zip` archive.", "headers": { "Content-Disposition": { "description": "The name of the archive to be downloaded", "schema": { "type": "string", "example": "attachment;filename=\"Avatars.zip\";filename*=UTF-8''Avatars.zip" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "description": "The binary content of the archive, which will include the items\nrequested for this download." } } } }, "404": { "description": "Returns an error if the ID of this download request is not valid. This\nerror can also be returned if this URL has been called before. To\nre-download this archive, please create a new request for a zip download.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returns an error if the number of concurrent zip downloads has been\nreached for either the user or the enterprise.\n\n* `user_too_many_concurrent_downloads` - the maximum of 5 parallel\ndownloads of zip archives per user has been met.\n* `enterprise_too_many_concurrent_downloads` - the maximum of 10 parallel\ndownloads of zip archives per enterprise has been met.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/zip_downloads/{zip_download_id}/status": { "get": { "operationId": "get_zip_downloads_id_status", "summary": "Get zip download status", "tags": [ "Zip Downloads" ], "x-box-tag": "zip_downloads", "x-box-reference-category": "zip_downloads", "description": "Returns the download status of a `zip` archive, allowing an application to\ninspect the progress of the download as well as the number of items that\nmight have been skipped.\n\nThis endpoint can only be accessed once the download has started.\nSubsequently this endpoint is valid for 12 hours from the start of the\ndownload.\n\nThe URL of this endpoint should not be considered as fixed. Instead, use\nthe [Create zip download](e://post_zip_downloads) API to request to create a\n`zip` archive, and then follow the `status_url` field in the response to\nthis endpoint.", "parameters": [ { "name": "zip_download_id", "description": "The unique identifier that represent this `zip` archive.", "example": "Lu6fA9Ob-jyysp3AAvMF4AkLEwZwAYbL=tgj2zIC=eK9RvJnJbjJl9rNh2qBgHDpyOCAOhpM=vajg2mKq8Mdd", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the status of the `zip` archive that is being downloaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZipDownloadStatus" } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned when an authorization header is provided but the user does not\nhave access to the items.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the ID of this download request is not valid, or if\nthe status of a download is requested before the download has been\nstarted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/sign_requests/{sign_request_id}/cancel": { "post": { "operationId": "post_sign_requests_id_cancel", "summary": "Cancel sign request", "tags": [ "Box Sign" ], "x-box-tag": "sign_requests", "description": "Cancels a sign request.", "parameters": [ { "name": "sign_request_id", "description": "The ID of the sign request", "example": "33243242", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a Sign Request object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignRequest" } } } }, "404": { "description": "Returns an error when the sign request cannot be found or the user does\nnot have access to the sign request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/sign_requests/{sign_request_id}/resend": { "post": { "operationId": "post_sign_requests_id_resend", "summary": "Resend sign request", "tags": [ "Box Sign" ], "x-box-tag": "sign_requests", "description": "Resends a sign request email to all outstanding signers.", "parameters": [ { "name": "sign_request_id", "description": "The ID of the sign request", "example": "33243242", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Returns an empty response when the API call was successful.\nThe email notifications will be sent asynchronously." }, "404": { "description": "Returns an error when the sign request cannot be found or the user does\nnot have access to the sign request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/sign_requests/{sign_request_id}": { "get": { "operationId": "get_sign_requests_id", "summary": "Get sign request by ID", "tags": [ "Box Sign" ], "x-box-tag": "sign_requests", "description": "Gets a sign request by ID.", "parameters": [ { "name": "sign_request_id", "description": "The ID of the sign request", "example": "33243242", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a sign request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignRequest" } } } }, "404": { "description": "Returns an error when the sign request cannot be found, the user does\nnot have access to the sign request, or `sign_files` and/or\n`parent_folder` is deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/sign_requests": { "get": { "operationId": "get_sign_requests", "summary": "List sign requests", "tags": [ "Box Sign" ], "x-box-tag": "sign_requests", "description": "Gets sign requests created by a user. If the `sign_files` and/or\n`parent_folder` are deleted, the sign request will not return in the list.", "parameters": [ { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } } ], "responses": { "200": { "description": "Returns a collection of sign requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignRequests" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_sign_requests", "summary": "Create sign request", "tags": [ "Box Sign" ], "x-box-tag": "sign_requests", "description": "Creates a sign request. This involves preparing a document for signing and\nsending the sign request to signers.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignRequestCreateRequest" } } } }, "responses": { "201": { "description": "Returns a Sign Request object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignRequest" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/workflows": { "get": { "operationId": "get_workflows", "summary": "List workflows", "tags": [ "Workflows" ], "x-box-tag": "workflows", "description": "Returns list of workflows that act on a given `folder ID`, and\nhave a flow with a trigger type of `WORKFLOW_MANUAL_START`.\n\nYou application must be authorized to use the `Manage Box Relay` application\nscope within the developer console in to use this endpoint.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "example": "12345", "in": "query", "required": true, "schema": { "type": "string", "nullable": false } }, { "name": "trigger_type", "description": "Type of trigger to search for.", "example": "WORKFLOW_MANUAL_START", "in": "query", "required": false, "schema": { "type": "string", "nullable": false } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the workflow.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workflows" } } } }, "400": { "description": "Returned if the trigger type is not `WORKFLOW_MANUAL_START`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the folder is not found, or the user does not\nhave access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/workflows/{workflow_id}/start": { "post": { "operationId": "post_workflows_id_start", "summary": "Starts workflow based on request body", "tags": [ "Workflows" ], "x-box-tag": "workflows", "description": "Initiates a flow with a trigger type of `WORKFLOW_MANUAL_START`.\n\nYou application must be authorized to use the `Manage Box Relay` application\nscope within the developer console.", "parameters": [ { "name": "workflow_id", "description": "The ID of the workflow.", "example": "12345", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "flow", "files", "folder" ], "properties": { "type": { "type": "string", "description": "The type of the parameters object", "example": "workflow_parameters", "enum": [ "workflow_parameters" ] }, "flow": { "type": "object", "description": "The flow that will be triggered", "properties": { "type": { "type": "string", "description": "The type of the flow object", "example": "flow" }, "id": { "type": "string", "description": "The id of the flow", "example": "123456789" } } }, "files": { "type": "array", "description": "The array of files for which the workflow should start. All files\nmust be in the workflow's configured folder.", "items": { "type": "object", "description": "A file the workflow should start for", "properties": { "type": { "type": "string", "description": "The type of the file object", "example": "file", "enum": [ "file" ] }, "id": { "type": "string", "description": "The id of the file", "example": "12345678" } } } }, "folder": { "type": "object", "description": "The folder object for which the workflow is configured.", "properties": { "type": { "type": "string", "description": "The type of the folder object", "example": "folder", "enum": [ "folder" ] }, "id": { "type": "string", "description": "The id of the folder", "example": "87654321" } } }, "outcomes": { "type": "array", "description": "A list of outcomes required to be configured at start time.", "items": { "type": "object", "description": "A configurable outcome the workflow should complete. If you\nhave a `task_completion_rule`, you may input `all_assignees` or\n`any_assignee` in the `variable_value` field. Similarly, if you\nhave a `collaborator_role`, you may input `editor`, `viewer`,\n`previewer`, `uploader`, `previewer uploader`, `viewer uploader`\n, `co-owner` in the `variable_value` field.", "properties": { "id": { "type": "string", "description": "The id of the outcome", "example": "890375782" }, "type": { "type": "string", "description": "The type of the outcome object", "example": "outcome", "enum": [ "outcome" ] }, "parameter": { "type": "string", "description": "This is a placeholder example for various objects that\ncan be passed in - refer to the guides section to find\nout more information.", "example": "placeholder" } } } } } } } } }, "responses": { "204": { "description": "Starts the workflow." }, "400": { "description": "Returns an error if some of the parameters are missing or\nnot valid.\n\n* `workflow_is_not_enabled` when the workflow is not enabled\n* `workflow_not_active_on_provided_folder` when the workflow is not\n enabled for the specified folder id\n* `parameters_provided_do_not_match_target_outcome` when the provided\n parameters do not match the expected parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error if there are insufficient permissions.\n\n* `insufficient_access` when the user does not have access rights to file\n or folder\n* `missing_relay_full_access` when the user does not have access to Relay\n Full", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the workflow could not be found,\nor the authenticated user does not have access to the workflow.\n\n* `workflow_not_found` when the workflow is not found\n* `flow_missing_or_inaccessible` when the flow is not a manual start flow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/sign_templates": { "get": { "operationId": "get_sign_templates", "summary": "List Box Sign templates", "tags": [ "templates" ], "x-box-tag": "sign_templates", "description": "Gets Box Sign templates created by a user.", "parameters": [ { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } } ], "responses": { "200": { "description": "Returns a collection of templates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignTemplates" } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/sign_templates/{template_id}": { "get": { "operationId": "get_sign_templates_id", "summary": "Get Box Sign template by ID", "tags": [ "templates" ], "x-box-tag": "sign_templates", "description": "Fetches details of a specific Box Sign template.", "parameters": [ { "name": "template_id", "description": "The ID of a Box Sign template.", "example": "123075213-7d117509-8f05-42e4-a5ef-5190a319d41d", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns details of a template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignTemplate" } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the template is not found or the user does not\nhave access to the associated template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/integration_mappings/slack": { "get": { "operationId": "get_integration_mappings_slack", "summary": "List Slack integration mappings", "tags": [ "integrationMappingsSlack" ], "x-box-tag": "integration_mappings", "x-box-scopes": [ "manage_enterprise_properties" ], "description": "Lists [Slack integration mappings](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack) in a users' enterprise.\n\nYou need Admin or Co-Admin role to\nuse this endpoint.", "parameters": [ { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 } }, { "in": "query", "name": "partner_item_type", "schema": { "type": "string", "enum": [ "channel" ], "nullable": false }, "description": "Mapped item type, for which the mapping should be returned", "example": "channel" }, { "in": "query", "name": "partner_item_id", "schema": { "type": "string", "nullable": false }, "description": "ID of the mapped item, for which the mapping should be returned", "example": "12345" }, { "in": "query", "name": "box_item_id", "schema": { "type": "string", "nullable": false }, "description": "Box item ID, for which the mappings should be returned", "example": "12345" }, { "in": "query", "name": "box_item_type", "schema": { "nullable": false, "type": "string", "enum": [ "folder" ] }, "description": "Box item type, for which the mappings should be returned", "example": "folder" }, { "in": "query", "name": "is_manually_created", "schema": { "type": "boolean", "nullable": false }, "description": "Whether the mapping has been manually created", "example": true } ], "responses": { "200": { "description": "Returns a collection of integration mappings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationMappings" } } } }, "400": { "description": "The server cannot or will not process the\nrequest due to an apparent client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns a `not_found` error if the integration mapping could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "post": { "operationId": "post_integration_mappings_slack", "summary": "Create Slack integration mapping", "tags": [ "integrationMappingsSlack", "post_integration_mappings_slack" ], "x-box-tag": "integration_mappings", "x-box-scopes": [ "manage_enterprise_properties" ], "description": "Creates a [Slack integration mapping](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack)\nby mapping a Slack channel to a Box item.\n\nYou need Admin or Co-Admin role to\nuse this endpoint.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationMappingSlackCreateRequest" } } } }, "responses": { "201": { "description": "Returns the created integration mapping.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationMapping" } } } }, "400": { "description": "Returns a `bad_request` if an incorrect `options`\nwas supplied or the Box folder cannot be\nmapped to this `partner_item_id`.\nError codes:\n* `SERVICE_ACCOUNT_IS_NOT_A_COOWNER_OR_OWNER` - service account\ndoesn't have co-owner collaboration or is\nnot an owner of the `box_item_id`,\n* `CHANNEL_ALREADY_MAPPED` - channel is already\n mapped to another `box_item_id`,\n* `CHANNEL_NOT_FOUND` - channel was not found,\n* `CHANNEL_NOT_SUITABLE_FOR_CFS` - connect channel, not\nsuitable for Box as Content layer for Slack,\n* `BOX_ENTERPRISE_MISMATCH` - Box folder must be\nowned by the enterprise, which is configured\nto use Box as Content layer for Slack,\n* `CFS_DISABLED` - Box as Content layer\nfor Slack must be enabled for a provided\nSlack workspace or organization\n* `BOX_FOLDER_EXTERNALLY_OWNED` - Box folder must\nbe internally owned to the admin's enterprise,\n* `JWT_APP_NOT_AUTHORIZED` - JWT authorization error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns a `not_found` error if the integration mapping could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/integration_mappings/slack/{integration_mapping_id}": { "put": { "operationId": "put_integration_mappings_slack_id", "summary": "Update Slack integration mapping", "tags": [ "integrationMappingsSlack" ], "x-box-tag": "integration_mappings", "x-box-scopes": [ "manage_enterprise_properties" ], "description": "Updates a [Slack integration mapping](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack).\nSupports updating the Box folder ID and options.\n\nYou need Admin or Co-Admin role to\nuse this endpoint.", "parameters": [ { "name": "integration_mapping_id", "description": "An ID of an integration mapping", "example": "11235432", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "box_item": { "nullable": false, "allOf": [ { "$ref": "#/components/schemas/IntegrationMappingBoxItemSlack" } ] }, "options": { "nullable": false, "allOf": [ { "$ref": "#/components/schemas/IntegrationMappingSlackOptions" } ] } } } } }, "description": "At least one of `box_item` and `options` must be provided." }, "responses": { "200": { "description": "Returns the updated integration mapping object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationMapping" } } } }, "400": { "description": "Returns a `bad_request` if an incorrect `options` was\nsupplied or the Box folder cannot be mapped to this `partner_item`.\nError codes:\n* `SERVICE_ACCOUNT_IS_NOT_A_COOWNER_OR_OWNER` - service account\n doesn't have co-owner collaboration or is\n not an owner of the `box_item_id`,\n* `BOX_FOLDER_EXTERNALLY_OWNED` - Box folder must be\n internally owned to the admin's enterprise,\n* `JWT_APP_NOT_AUTHORIZED` - JWT authorization error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns a `not_found` if integration mapping\nobject was not found in the database", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "operationId": "delete_integration_mappings_slack_id", "summary": "Delete Slack integration mapping", "tags": [ "integrationMappingsSlack" ], "x-box-tag": "integration_mappings", "x-box-scopes": [ "manage_enterprise_properties" ], "description": "Deletes a [Slack integration mapping](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack).\n\n\nYou need Admin or Co-Admin role to\nuse this endpoint.", "parameters": [ { "name": "integration_mapping_id", "description": "An ID of an integration mapping", "example": "11235432", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Empty body in response" }, "404": { "description": "Returns a `not_found` error if the integration mapping could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } } }, "components": { "securitySchemes": { "OAuth2Security": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://account.box.com/api/oauth2/authorize", "tokenUrl": "https://api.box.com/oauth2/token", "scopes": { "root_readonly": "Read all files and folders stored in Box", "root_readwrite": "Read and write all files and folders stored in Box", "manage_app_users": "Provision and manage app users", "manage_managed_users": "Provision and manage managed users", "manage_groups": "Manage an enterprise's groups", "manage_webhook": "Create webhooks programmatically through the API", "manage_enterprise_properties": "Manage enterprise properties", "manage_data_retention": "Manage data retention polices", "manage_legal_hold": "Manage Legal Holds" } } } } }, "schemas": { "PostOAuth2Token": { "title": "Token request", "type": "object", "description": "A request for a new OAuth 2.0 token", "required": [ "grant_type" ], "properties": { "grant_type": { "type": "string", "format": "urn", "example": "authorization_code", "description": "The type of request being made, either using a client-side obtained\nauthorization code, a refresh token, a JWT assertion, client credentials\ngrant or another access token for the purpose of downscoping a token.", "enum": [ "authorization_code", "refresh_token", "client_credentials", "urn:ietf:params:oauth:grant-type:jwt-bearer", "urn:ietf:params:oauth:grant-type:token-exchange" ] }, "client_id": { "type": "string", "description": "The Client ID of the application requesting an access token.\n\nUsed in combination with `authorization_code`, `client_credentials`, or\n`urn:ietf:params:oauth:grant-type:jwt-bearer` as the `grant_type`.", "example": "ly1nj6n11vionaie65emwzk575hnnmrk" }, "client_secret": { "type": "string", "description": "The client secret of the application requesting an access token.\n\nUsed in combination with `authorization_code`, `client_credentials`, or\n`urn:ietf:params:oauth:grant-type:jwt-bearer` as the `grant_type`.", "example": "hOzsTeFlT6ko0dme22uGbQal04SBPYc1" }, "code": { "type": "string", "format": "token", "description": "The client-side authorization code passed to your application by\nBox in the browser redirect after the user has successfully\ngranted your application permission to make API calls on their\nbehalf.\n\nUsed in combination with `authorization_code` as the `grant_type`.", "example": "n22JPxrh18m4Y0wIZPIqYZK7VRrsMTWW" }, "refresh_token": { "type": "string", "format": "token", "description": "A refresh token used to get a new access token with.\n\nUsed in combination with `refresh_token` as the `grant_type`.", "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" }, "assertion": { "type": "string", "format": "jwt", "description": "A JWT assertion for which to request a new access token.\n\nUsed in combination with `urn:ietf:params:oauth:grant-type:jwt-bearer`\nas the `grant_type`.", "example": "xxxxx.yyyyy.zzzzz" }, "subject_token": { "type": "string", "format": "token", "description": "The token to exchange for a downscoped token. This can be a regular\naccess token, a JWT assertion, or an app token.\n\nUsed in combination with `urn:ietf:params:oauth:grant-type:token-exchange`\nas the `grant_type`.", "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" }, "subject_token_type": { "type": "string", "example": "urn:ietf:params:oauth:token-type:access_token", "description": "The type of `subject_token` passed in.\n\nUsed in combination with `urn:ietf:params:oauth:grant-type:token-exchange`\nas the `grant_type`.", "enum": [ "urn:ietf:params:oauth:token-type:access_token" ] }, "actor_token": { "type": "string", "format": "token", "description": "The token used to create an annotator token.\nThis is a JWT assertion.\n\nUsed in combination with `urn:ietf:params:oauth:grant-type:token-exchange`\nas the `grant_type`.", "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" }, "actor_token_type": { "type": "string", "format": "urn", "example": "urn:ietf:params:oauth:token-type:id_token", "description": "The type of `actor_token` passed in.\n\nUsed in combination with `urn:ietf:params:oauth:grant-type:token-exchange`\nas the `grant_type`.", "enum": [ "urn:ietf:params:oauth:token-type:id_token" ] }, "scope": { "type": "string", "format": "space_delimited_list", "description": "The space-delimited list of scopes that you want apply to the\nnew access token.\n\nThe `subject_token` will need to have all of these scopes or\nthe call will error with **401 Unauthorized**.", "example": "item_upload item_preview base_explorer" }, "resource": { "type": "string", "format": "url", "description": "Full URL for the file that the token should be generated for.", "example": "https://api.box.com/2.0/files/123456" }, "box_subject_type": { "type": "string", "example": "enterprise", "description": "Used in combination with `client_credentials` as the `grant_type`.", "enum": [ "enterprise", "user" ] }, "box_subject_id": { "type": "string", "example": "123456789", "description": "Used in combination with `client_credentials` as the `grant_type`.\nValue is determined by `box_subject_type`. If `user` use user ID and if\n`enterprise` use enterprise ID." }, "box_shared_link": { "type": "string", "format": "url", "description": "Full URL of the shared link on the file or folder\nthat the token should be generated for.", "example": "https://cloud.box.com/s/123456" } } }, "PostOAuth2Token--RefreshAccessToken": { "title": "Refresh access token", "type": "object", "description": "A request to refresh an Access Token. Use this API to refresh an expired\nAccess Token using a valid Refresh Token.", "required": [ "grant_type", "client_id", "client_secret", "refresh_token" ], "properties": { "grant_type": { "type": "string", "format": "urn", "example": "refresh_token", "description": "The type of request being made, in this case a refresh request.", "enum": [ "refresh_token" ] }, "client_id": { "type": "string", "description": "The client ID of the application requesting to refresh the token.", "example": "ly1nj6n11vionaie65emwzk575hnnmrk" }, "client_secret": { "type": "string", "description": "The client secret of the application requesting to refresh the token.", "example": "hOzsTeFlT6ko0dme22uGbQal04SBPYc1" }, "refresh_token": { "type": "string", "format": "token", "description": "The refresh token to refresh.", "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" } } }, "PostOAuth2Revoke": { "title": "Token revocation request", "type": "object", "description": "A request to revoke an OAuth 2.0 token", "required": [ "grant_type" ], "properties": { "client_id": { "type": "string", "description": "The Client ID of the application requesting to revoke the\naccess token.", "example": "ly1nj6n11vionaie65emwzk575hnnmrk" }, "client_secret": { "type": "string", "description": "The client secret of the application requesting to revoke\nan access token.", "example": "hOzsTeFlT6ko0dme22uGbQal04SBPYc1" }, "token": { "type": "string", "format": "token", "description": "The access token to revoke.", "example": "n22JPxrh18m4Y0wIZPIqYZK7VRrsMTWW" } } }, "ZipDownloadRequest": { "title": "Create a `zip` archive", "type": "object", "description": "A request to create a `zip` archive to download", "required": [ "items" ], "properties": { "items": { "type": "array", "description": "A list of items to add to the `zip` archive. These can\nbe folders or files.", "items": { "type": "object", "description": "An item to add to the `zip` archive. This can be a file or a folder.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "The type of the item to add to the archive.", "example": "file", "enum": [ "file", "folder." ] }, "id": { "type": "string", "description": "The identifier of the item to add to the archive. When this item is\na folder then this can not be the root folder with ID `0`.", "example": "12345" } } } }, "download_file_name": { "type": "string", "description": "The optional name of the `zip` archive. This name will be appended by the\n`.zip` file extension, for example `January Financials.zip`.", "example": "January Financials" } } }, "MetadataQuery": { "title": "Metadata query search request", "type": "object", "description": "Create a search using SQL-like syntax to return items that match specific\nmetadata.", "required": [ "from", "ancestor_folder_id" ], "properties": { "from": { "type": "string", "description": "Specifies the template used in the query. Must be in the form\n`scope.templateKey`. Not all templates can be used in this field,\nmost notably the built-in, Box-provided classification templates\ncan not be used in a query.", "example": "enterprise_123456.someTemplate" }, "query": { "type": "string", "description": "The query to perform. A query is a logical expression that is very similar\nto a SQL `SELECT` statement. Values in the search query can be turned into\nparameters specified in the `query_param` arguments list to prevent having\nto manually insert search values into the query string.\n\nFor example, a value of `:amount` would represent the `amount` value in\n`query_params` object.", "example": "value >= :amount" }, "query_params": { "type": "object", "description": "Set of arguments corresponding to the parameters specified in the\n`query`. The type of each parameter used in the `query_params` must match\nthe type of the corresponding metadata template field.", "example": { "amount": "100" }, "additionalProperties": { "type": "string", "description": "The value for the argument being used in the metadata search.\n\nThe type of this parameter must match the type of the corresponding\nmetadata template field.", "example": "100", "x-box-example-key": "amount" } }, "ancestor_folder_id": { "type": "string", "description": "The ID of the folder that you are restricting the query to. A\nvalue of zero will return results from all folders you have access\nto. A non-zero value will only return results found in the folder\ncorresponding to the ID or in any of its subfolders.", "example": "0" }, "order_by": { "type": "array", "description": "A list of template fields and directions to sort the metadata query\nresults by.\n\nThe ordering `direction` must be the same for each item in the array.", "items": { "type": "object", "description": "An object representing one of the metadata template fields to sort the\nmetadata query results by.", "properties": { "field_key": { "type": "string", "description": "The metadata template field to order by.\n\nThe `field_key` represents the `key` value of a field from the\nmetadata template being searched for.", "example": "amount" }, "direction": { "type": "string", "description": "The direction to order by, either ascending or descending.\n\nThe `ordering` direction must be the same for each item in the\narray.", "example": "asc", "enum": [ "ASC", "DESC", "asc", "desc" ] } } } }, "limit": { "type": "integer", "description": "A value between 0 and 100 that indicates the maximum number of results\nto return for a single request. This only specifies a maximum\nboundary and will not guarantee the minimum number of results\nreturned.", "default": 100, "minimum": 0, "maximum": 100, "example": 50 }, "marker": { "type": "string", "description": "Marker to use for requesting the next page.", "example": "AAAAAmVYB1FWec8GH6yWu2nwmanfMh07IyYInaa7DZDYjgO1H4KoLW29vPlLY173OKsci6h6xGh61gG73gnaxoS+o0BbI1/h6le6cikjlupVhASwJ2Cj0tOD9wlnrUMHHw3/ISf+uuACzrOMhN6d5fYrbidPzS6MdhJOejuYlvsg4tcBYzjauP3+VU51p77HFAIuObnJT0ff" }, "fields": { "type": "array", "items": { "type": "string" }, "description": "By default, this endpoint returns only the most basic info about the items for\nwhich the query matches. This attribute can be used to specify a list of\nadditional attributes to return for any item, including its metadata.\n\nThis attribute takes a list of item fields, metadata template identifiers,\nor metadata template field identifiers.\n\nFor example:\n\n* `created_by` will add the details of the user who created the item to\nthe response.\n* `metadata..` will return the mini-representation\nof the metadata instance identified by the `scope` and `templateKey`.\n* `metadata...` will return all the mini-representation\nof the metadata instance identified by the `scope` and `templateKey` plus\nthe field specified by the `field` name. Multiple fields for the same\n`scope` and `templateKey` can be defined.", "example": [ "extension", "created_at", "item_status", "metadata.enterprise_1234.contracts", "metadata.enterprise_1234.regions.location" ] } } }, "FileRequestUpdateRequest": { "title": "File Request (Update)", "type": "object", "description": "The request body to update a file request.", "properties": { "title": { "type": "string", "description": "An optional new title for the file request. This can be\nused to change the title of the file request.\n\nThis will default to the value on the existing file request.", "example": "Please upload required documents" }, "description": { "type": "string", "description": "An optional new description for the file request. This can be\nused to change the description of the file request.\n\nThis will default to the value on the existing file request.", "example": "Please upload required documents" }, "status": { "type": "string", "description": "An optional new status of the file request.\n\nWhen the status is set to `inactive`, the file request\nwill no longer accept new submissions, and any visitor\nto the file request URL will receive a `HTTP 404` status\ncode.\n\nThis will default to the value on the existing file request.", "example": "active", "enum": [ "active", "inactive" ] }, "is_email_required": { "type": "boolean", "example": true, "description": "Whether a file request submitter is required to provide\ntheir email address.\n\nWhen this setting is set to true, the Box UI will show\nan email field on the file request form.\n\nThis will default to the value on the existing file request." }, "is_description_required": { "type": "boolean", "example": true, "description": "Whether a file request submitter is required to provide\na description of the files they are submitting.\n\nWhen this setting is set to true, the Box UI will show\na description field on the file request form.\n\nThis will default to the value on the existing file request." }, "expires_at": { "type": "string", "format": "date-time", "description": "The date after which a file request will no longer accept new\nsubmissions.\n\nAfter this date, the `status` will automatically be set to\n`inactive`.\n\nThis will default to the value on the existing file request.", "example": "2020-09-28T10:53:43-08:00" } } }, "FileRequestCopyRequest": { "title": "File Request (Copy)", "type": "object", "description": "The request body to copy a file request.", "required": [ "folder" ], "allOf": [ { "$ref": "#/components/schemas/FileRequestUpdateRequest" }, { "properties": { "folder": { "type": "object", "description": "The folder to associate the new file request to.", "required": [ "id" ], "properties": { "type": { "type": "string", "example": "folder", "description": "`folder`", "enum": [ "folder" ] }, "id": { "type": "string", "example": "42037322", "description": "The ID of the folder to associate the new\nfile request to." } } } } } ] }, "SignRequestCreateRequest": { "title": "Create a sign request", "type": "object", "description": "A request to create a sign request object", "required": [ "signers" ], "allOf": [ { "$ref": "#/components/schemas/SignRequest--Base" }, { "properties": { "source_files": { "type": "array", "items": { "$ref": "#/components/schemas/File--Base" }, "description": "List of files to create a signing document from. This is currently limited to ten files. Only the ID and type fields are required for each file.", "maxItems": 10, "nullable": true }, "signers": { "type": "array", "items": { "$ref": "#/components/schemas/SignRequestCreateSigner" }, "description": "Array of signers for the sign request. 35 is the\nmax number of signers permitted." } } } ] }, "IntegrationMappingSlackCreateRequest": { "title": "Create integration mapping request", "type": "object", "x-box-resource-id": "integration_mapping_slack_create_request", "description": "A request to create a\nSlack Integration Mapping object", "properties": { "partner_item": { "nullable": false, "allOf": [ { "$ref": "#/components/schemas/IntegrationMappingPartnerItemSlack" } ] }, "box_item": { "nullable": false, "allOf": [ { "$ref": "#/components/schemas/IntegrationMappingBoxItemSlack" } ] }, "options": { "nullable": false, "allOf": [ { "$ref": "#/components/schemas/IntegrationMappingSlackOptions" } ] } }, "required": [ "partner_item", "box_item" ] }, "ClientError": { "title": "Client error", "type": "object", "x-box-resource-id": "client_error", "description": "A generic error", "properties": { "type": { "description": "`error`", "example": "error", "type": "string", "enum": [ "error" ], "nullable": false }, "status": { "description": "The HTTP status of the response.", "example": 400, "type": "integer", "format": "int32", "nullable": false }, "code": { "description": "A Box-specific error code", "example": "item_name_invalid", "type": "string", "enum": [ "created", "accepted", "no_content", "redirect", "not_modified", "bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "precondition_failed", "too_many_requests", "internal_server_error", "unavailable", "item_name_invalid", "insufficient_scope" ] }, "message": { "description": "A short message describing the error.", "example": "Method Not Allowed", "type": "string", "nullable": false }, "context_info": { "description": "A free-form object that contains additional context\nabout the error. The possible fields are defined on\na per-endpoint basis. `message` is only one example.", "type": "object", "properties": { "message": { "type": "string", "description": "More details on the error.", "example": "Something went wrong." } } }, "help_url": { "description": "A URL that links to more information about why this error occurred.", "example": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/", "type": "string", "nullable": false }, "request_id": { "description": "A unique identifier for this response, which can be used\nwhen contacting Box support.", "type": "string", "example": "abcdef123456", "nullable": false } } }, "ConflictError": { "title": "Conflict error", "type": "object", "x-box-resource-id": "conflict_error", "x-box-tag": "uploads", "description": "The error that occurs when a file can not be created due\nto a conflict.", "allOf": [ { "$ref": "#/components/schemas/ClientError" }, { "properties": { "context_info": { "type": "object", "properties": { "conflicts": { "type": "array", "description": "A list of the file conflicts that caused this error.", "items": { "$ref": "#/components/schemas/FileConflict" } } } } } } ] }, "OAuth2Error": { "title": "OAuth 2.0 error", "type": "object", "x-box-resource-id": "oauth2_error", "x-box-tag": "authorization", "description": "An OAuth 2.0 error", "properties": { "error": { "type": "string", "example": "invalid_client", "description": "The type of the error returned." }, "error_description": { "type": "string", "example": "The client credentials are not valid", "description": "The type of the error returned." } } }, "SkillInvocation": { "title": "Skill webhook payload", "type": "object", "x-box-resource-id": "skill_invocation", "x-box-tag": "skills", "description": "The payload of a Box skill as sent to a skill's\n`invocation_url`.", "properties": { "type": { "type": "string", "description": "`skill_invocation`", "example": "skill_invocation", "enum": [ "skill_invocation" ] }, "id": { "type": "string", "description": "Unique identifier for the invocation request.", "example": "fd1d2e53-35f5-41fb-9c25-4ba326daf2f9_341016304" }, "skill": { "allOf": [ { "title": "Skill", "type": "object", "description": "An object representing a skill", "properties": { "id": { "type": "string", "description": "The unique identifier for this skill", "example": "11446498" }, "type": { "type": "string", "description": "`skill`", "example": "skill", "enum": [ "skill" ] }, "name": { "type": "string", "description": "The name of the skill", "example": "Hello World Skill" }, "api_key": { "type": "string", "description": "The client ID of the application", "example": "hxel2s12wd2h9r8ne103c4gjbqefofih" } } }, { "description": "The skill that triggered this invocation" } ] }, "token": { "type": "object", "description": "The read-only and read-write access tokens for this item", "properties": { "read": { "type": "object", "description": "The basics of an access token", "properties": { "access_token": { "type": "string", "format": "token", "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ", "description": "The requested access token." }, "expires_in": { "type": "integer", "format": "int64", "example": 3600, "description": "The time in seconds in seconds by which this token will expire." }, "token_type": { "type": "string", "enum": [ "bearer" ], "example": "bearer", "description": "The type of access token returned." }, "restricted_to": { "type": "string", "description": "The permissions that this access token permits,\nproviding a list of resources (files, folders, etc)\nand the scopes permitted for each of those resources.", "example": "[{\"scope\":\"gcm\"}, {\"scope\":\"item_upload\",\"object_id\":933941692081,\"object_type\":\"file\"}, {\"scope\":\"manage_skill_invocations\"}]" } } }, "write": { "type": "object", "description": "The basics of an access token", "properties": { "access_token": { "type": "string", "format": "token", "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ", "description": "The requested access token." }, "expires_in": { "type": "integer", "format": "int64", "example": 3600, "description": "The time in seconds in seconds by which this token will expire." }, "token_type": { "type": "string", "enum": [ "bearer" ], "example": "bearer", "description": "The type of access token returned." }, "restricted_to": { "type": "string", "description": "The permissions that this access token permits,\nproviding a list of resources (files, folders, etc)\nand the scopes permitted for each of those resources.", "example": "[{\"scope\":\"gcm\"}, {\"scope\":\"item_upload\",\"object_id\":933941692081,\"object_type\":\"file\"}, {\"scope\":\"manage_skill_invocations\"}]" } } } } }, "status": { "type": "object", "description": "The details status of this event.", "properties": { "state": { "type": "string", "example": "invoked", "description": "The state of this event.\n\n* `invoked` - Triggered the skill with event details to start\n applying skill on the file.\n* `processing` - Currently processing.\n* `success` - Completed processing with a success.\n* `transient_failure` - Encountered an issue which can be\n retried.\n* `permanent_failure` - Encountered a permanent issue and\n retry would not help.", "enum": [ "invoked", "processing", "success", "transient_failure", "permanent_failure" ] }, "message": { "type": "string", "example": "Example", "description": "Status information" }, "error_code": { "type": "string", "example": "400", "description": "Error code information, if error occurred." }, "additional_info": { "type": "string", "example": "Example", "description": "Additional status information." } } }, "created_at": { "type": "string", "format": "date-time", "description": "The time this invocation was created.", "example": "2012-12-12T10:53:43-08:00" }, "trigger": { "type": "string", "example": "FILE_CONTENT", "description": "Action that triggered the invocation" }, "enterprise": { "allOf": [ { "title": "Enterprise", "type": "object", "description": "A representation of a Box enterprise", "properties": { "id": { "type": "string", "description": "The unique identifier for this enterprise.", "example": "11446498" }, "type": { "type": "string", "description": "`enterprise`", "example": "enterprise", "enum": [ "enterprise" ] }, "name": { "description": "The name of the enterprise", "example": "Acme Inc.", "type": "string" } } }, { "description": "The enterprise that this invocation was triggered for" } ] }, "source": { "allOf": [ { "oneOf": [ { "$ref": "#/components/schemas/File" }, { "$ref": "#/components/schemas/Folder" } ] }, { "description": "The item that caused the invocation to trigger" } ] }, "event": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "description": "The event that triggered this invocation" } ] } } }, "WebhookInvocation": { "title": "Webhook (V2) payload", "type": "object", "x-box-resource-id": "webhook_invocation", "x-box-tag": "webhooks", "description": "The event that is sent to a webhook address when an event happens.", "properties": { "id": { "type": "string", "description": "The unique identifier for this webhook invocation", "example": "11446498" }, "type": { "type": "string", "description": "`webhook_event`", "example": "webhook_event", "enum": [ "webhook_event" ] }, "webhook": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "description": "The webhook object that triggered this event" } ] }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user that triggered this event" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "A timestamp identifying the time that\nthe webhook event was triggered.", "example": "2012-12-12T10:53:43-08:00" }, "trigger": { "allOf": [ { "title": "Webhook Trigger", "example": "FILE.UPLOADED", "type": "string", "description": "The event name that triggered this webhook", "enum": [ "FILE.UPLOADED", "FILE.PREVIEWED", "FILE.DOWNLOADED", "FILE.TRASHED", "FILE.DELETED", "FILE.RESTORED", "FILE.COPIED", "FILE.MOVED", "FILE.LOCKED", "FILE.UNLOCKED", "FILE.RENAMED", "COMMENT.CREATED", "COMMENT.UPDATED", "COMMENT.DELETED", "TASK_ASSIGNMENT.CREATED", "TASK_ASSIGNMENT.UPDATED", "METADATA_INSTANCE.CREATED", "METADATA_INSTANCE.UPDATED", "METADATA_INSTANCE.DELETED", "FOLDER.CREATED", "FOLDER.RENAMED", "FOLDER.DOWNLOADED", "FOLDER.RESTORED", "FOLDER.DELETED", "FOLDER.COPIED", "FOLDER.MOVED", "FOLDER.TRASHED", "WEBHOOK.DELETED", "COLLABORATION.CREATED", "COLLABORATION.ACCEPTED", "COLLABORATION.REJECTED", "COLLABORATION.REMOVED", "COLLABORATION.UPDATED", "SHARED_LINK.DELETED", "SHARED_LINK.CREATED", "SHARED_LINK.UPDATED", "SIGN_REQUEST.COMPLETED", "SIGN_REQUEST.DECLINED", "SIGN_REQUEST.EXPIRED", "SIGN_REQUEST.SIGNER_EMAIL_BOUNCED" ] }, { "description": "The event name that triggered this webhook" } ] }, "source": { "allOf": [ { "oneOf": [ { "$ref": "#/components/schemas/File" }, { "$ref": "#/components/schemas/Folder" } ] }, { "description": "The item that caused the event to trigger" } ] } } }, "AccessToken": { "title": "Access token", "type": "object", "x-box-resource-id": "access_token", "x-box-tag": "authorization", "description": "A token that can be used to make authenticated API calls.", "properties": { "access_token": { "type": "string", "format": "token", "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ", "description": "The requested access token." }, "expires_in": { "type": "integer", "format": "int64", "example": 3600, "description": "The time in seconds in seconds by which this token will expire." }, "token_type": { "type": "string", "enum": [ "bearer" ], "example": "bearer", "description": "The type of access token returned." }, "restricted_to": { "type": "array", "description": "The permissions that this access token permits,\nproviding a list of resources (files, folders, etc)\nand the scopes permitted for each of those resources.", "items": { "$ref": "#/components/schemas/FileScope" } }, "refresh_token": { "type": "string", "format": "token", "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ", "description": "The refresh token for this access token, which can be used\nto request a new access token when the current one expires." }, "issued_token_type": { "type": "string", "format": "urn", "example": "urn:ietf:params:oauth:token-type:access_token", "enum": [ "urn:ietf:params:oauth:token-type:access_token" ], "description": "The type of downscoped access token returned. This is only\nreturned if an access token has been downscoped." } } }, "Classification": { "title": "Classification", "type": "object", "x-box-resource-id": "classification", "x-box-tag": "classifications", "description": "An instance of the classification metadata template, containing\nthe classification applied to the file or folder.\n\nTo get more details about the classification applied to an item,\nrequest the classification metadata template.", "properties": { "Box__Security__Classification__Key": { "type": "string", "example": "Sensitive", "description": "The name of the classification applied to the item." }, "$parent": { "type": "string", "example": "folder_59449484661,", "description": "The identifier of the item that this metadata instance\nhas been attached to. This combines the `type` and the `id`\nof the parent in the form `{type}_{id}`." }, "$template": { "type": "string", "example": "securityClassification-6VMVochwUWo", "description": "`securityClassification-6VMVochwUWo`", "enum": [ "securityClassification-6VMVochwUWo" ] }, "$scope": { "type": "string", "example": "enterprise_27335", "description": "The scope of the enterprise that this classification has been\napplied for.\n\nThis will be in the format `enterprise_{enterprise_id}`." }, "$version": { "type": "integer", "example": 1, "description": "The version of the metadata instance. This version starts at 0 and\nincreases every time a classification is updated." }, "$type": { "type": "string", "example": "securityClassification-6VMVochwUWo-fd31537a-0f95-4d86-9f2b-5974a29978f8", "description": "The unique ID of this classification instance. This will be include\nthe name of the classification template and a unique ID." }, "$typeVersion": { "type": "number", "example": 5, "description": "The version of the metadata template. This version starts at 0 and\nincreases every time the template is updated. This is mostly for internal\nuse." }, "$canEdit": { "type": "boolean", "example": true, "description": "Whether an end user can change the classification." } } }, "ClassificationTemplate": { "title": "Classification Template", "type": "object", "x-box-resource-id": "classification_template", "x-box-tag": "classifications", "description": "A metadata template that holds the security classifications\ndefined by an enterprise.", "required": [ "type" ], "properties": { "id": { "type": "string", "example": "58063d82-4128-7b43-bba9-92f706befcdf", "description": "The ID of the classification template." }, "type": { "type": "string", "description": "`metadata_template`", "example": "metadata_template", "enum": [ "metadata_template" ], "nullable": false }, "scope": { "type": "string", "description": "The scope of the classification template. This is in the format\n`enterprise_{id}` where the `id` is the enterprise ID.", "example": "enterprise_123456" }, "templateKey": { "type": "string", "example": "securityClassification-6VMVochwUWo", "description": "`securityClassification-6VMVochwUWo`", "enum": [ "securityClassification-6VMVochwUWo" ] }, "displayName": { "type": "string", "example": "Classification", "description": "The name of this template as shown in web and mobile interfaces.", "enum": [ "Classification" ] }, "hidden": { "type": "boolean", "example": false, "description": "This template is always available in web and mobile interfaces." }, "copyInstanceOnItemCopy": { "type": "boolean", "example": true, "description": "Classifications are always copied along when the file or folder is\ncopied." }, "fields": { "type": "array", "maxItems": 1, "minItems": 1, "description": "A list of fields for this classification template. This includes\nonly one field, the `Box__Security__Classification__Key`, which defines\nthe different classifications available in this enterprise.", "items": { "type": "object", "description": "The metadata template field that represents the available\nclassifications.", "properties": { "id": { "type": "string", "example": "822227e0-47a5-921b-88a8-494760b2e6d2", "description": "The unique ID of the field." }, "type": { "type": "string", "example": "enum", "description": "`enum`", "enum": [ "enum" ] }, "key": { "type": "string", "example": "Box__Security__Classification__Key", "description": "`Box__Security__Classification__Key`", "enum": [ "Box__Security__Classification__Key" ] }, "displayName": { "type": "string", "example": "Classification", "description": "`Classification`", "enum": [ "Classification" ] }, "hidden": { "type": "boolean", "example": false, "description": "Classifications are always visible to web and mobile users." }, "options": { "type": "array", "description": "A list of classifications available in this enterprise.", "minItems": 1, "items": { "type": "object", "description": "A single classification available in this enterprise.", "properties": { "id": { "type": "string", "example": "46aea176-3483-4431-856c-6b5b13d1cc50", "description": "The unique ID of this classification." }, "key": { "type": "string", "example": "Sensitive", "description": "The display name and key for this classification." }, "staticConfig": { "type": "object", "description": "Additional information about the classification.", "properties": { "classification": { "type": "object", "description": "Additional information about the classification.\n\nThis is not an exclusive list of properties, and\nmore object fields might be returned. These fields\nare used for internal Box Shield and Box Governance\npurposes and no additional value must be derived from\nthese fields.", "properties": { "classificationDefinition": { "type": "string", "example": "Sensitive information", "description": "A longer description of the classification." }, "colorID": { "type": "number", "example": 4, "description": "An internal Box identifier used to assign a color to\na classification label.\n\nMapping between a `colorID` and a color may change\nwithout notice. Currently, the color mappings are as\nfollows.\n\n* `0`: Yellow\n* `1`: Orange\n* `2`: Watermelon red\n* `3`: Purple rain\n* `4`: Light blue\n* `5`: Dark blue\n* `6`: Light green\n* `7`: Gray" } } } } } } } } } } } } }, "Collaboration": { "title": "Collaboration", "type": "object", "x-box-resource-id": "collaboration", "x-box-tag": "user_collaborations", "description": "Collaborations define access permissions for users and groups to files and\nfolders, similar to access control lists. A collaboration object grants a\nuser or group access to a file or folder with permissions defined by a\nspecific role.", "properties": { "id": { "type": "string", "description": "The unique identifier for this collaboration.", "example": "12345678" }, "type": { "type": "string", "description": "`collaboration`", "example": "collaboration", "enum": [ "collaboration" ] }, "item": { "allOf": [ { "oneOf": [ { "$ref": "#/components/schemas/File" }, { "$ref": "#/components/schemas/Folder" }, { "$ref": "#/components/schemas/WebLink" } ] }, { "description": "The file or folder to which access is granted. The field is\n`null` when the collaboration `status` is `pending`." } ], "nullable": true }, "accessible_by": { "allOf": [ { "$ref": "#/components/schemas/User--Collaborations" }, { "description": "The user or group that is granted access." } ] }, "invite_email": { "type": "string", "nullable": true, "example": "john@example.com", "description": "The email address used to invite an unregistered collaborator, if\nthey are not a registered user." }, "role": { "type": "string", "example": "editor", "enum": [ "editor", "viewer", "previewer", "uploader", "previewer uploader", "viewer uploader", "co-owner", "owner" ], "description": "The level of access granted." }, "expires_at": { "type": "string", "nullable": true, "format": "date-time", "example": "2012-12-26T10:53:43-08:00", "description": "When the collaboration will expire, or `null` if no expiration\ndate is set." }, "status": { "type": "string", "example": "accepted", "enum": [ "accepted", "pending", "rejected" ], "description": "The status of the collaboration invitation. If the status\nis `pending`, `login` and `name` return an empty string." }, "acknowledged_at": { "type": "string", "format": "date-time", "example": "2012-12-12T10:55:20-08:00", "description": "When the `status` of the collaboration object changed to\n`accepted` or `rejected`." }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/User--Collaborations" }, { "description": "The user who created the collaboration object." }, { "example": [ { "id": 33224412 }, { "type": "user" }, { "login": "dylan@example.com" }, { "name": "Dylan Smith" } ] } ] }, "created_at": { "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "description": "When the collaboration object was created." }, "modified_at": { "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "description": "When the collaboration object was last modified." }, "acceptance_requirements_status": { "type": "object", "properties": { "terms_of_service_requirement": { "type": "object", "properties": { "is_accepted": { "type": "boolean", "nullable": true, "example": true, "description": "Whether or not the terms of service have been accepted. The\nfield is `null` when there is no terms of service required." }, "terms_of_service": { "allOf": [ { "$ref": "#/components/schemas/TermsOfService--Base" }, { "description": "The terms of service that must be accepted before the\ncollaboration can be accepted. The field is `null` when\nthere is no terms of service required." } ] } } }, "strong_password_requirement": { "type": "object", "properties": { "enterprise_has_strong_password_required_for_external_users": { "type": "boolean", "example": true, "description": "Whether or not the enterprise that owns the content requires\na strong password to collaborate on the content." }, "user_has_strong_password": { "type": "boolean", "nullable": true, "example": true, "description": "Whether or not the user has a strong password set for their\naccount. The field is `null` when a strong password is not\nrequired." } } }, "two_factor_authentication_requirement": { "type": "object", "properties": { "enterprise_has_two_factor_auth_enabled": { "type": "boolean", "example": true, "description": "Whether or not the enterprise that owns the content requires\ntwo-factor authentication to be enabled in order to\ncollaborate on the content." }, "user_has_two_factor_authentication_enabled": { "type": "boolean", "nullable": true, "example": true, "description": "Whether or not the user has two-factor authentication\nenabled. The field is `null` when two-factor\nauthentication is not required." } } } } } } }, "Collaborations": { "title": "Collaborations", "type": "object", "x-box-resource-id": "collaborations", "x-box-tag": "user_collaborations", "description": "A list of collaborations", "allOf": [ { "type": "object", "description": "The part of an API response that describes pagination", "properties": { "total_count": { "description": "One greater than the offset of the last entry in the entire collection.\nThe total number of entries in the collection may be less than\n`total_count`.\n\nThis field is only returned for calls that use offset-based pagination.\nFor marker-based paginated APIs, this field will be omitted.", "example": 5000, "type": "integer", "format": "int64" }, "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "example": 1000, "type": "integer", "format": "int64" }, "offset": { "description": "The 0-based offset of the first entry in this set. This will be the same\nas the `offset` query parameter.\n\nThis field is only returned for calls that use offset-based pagination.\nFor marker-based paginated APIs, this field will be omitted.", "example": 2000, "type": "integer", "format": "int64" }, "order": { "description": "The order by which items are returned.\n\nThis field is only returned for calls that use offset-based pagination.\nFor marker-based paginated APIs, this field will be omitted.", "type": "array", "items": { "type": "object", "description": "The order in which a pagination is ordered", "properties": { "by": { "description": "The field to order by", "example": "type", "type": "string" }, "direction": { "type": "string", "description": "The direction to order by, either ascending or descending", "example": "ASC", "enum": [ "ASC", "DESC" ] } } } } } }, { "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/Collaboration" } } } } ] }, "CollaborationAllowlistEntry": { "title": "Allowed collaboration domain", "type": "object", "x-box-resource-id": "collaboration_allowlist_entry", "x-box-tag": "collaboration_allowlist_entries", "description": "An entry that describes an approved domain for which users can collaborate\nwith files and folders in your enterprise or vice versa.", "properties": { "id": { "type": "string", "description": "The unique identifier for this entry", "example": "11446498" }, "type": { "type": "string", "description": "`collaboration_whitelist_entry`", "example": "collaboration_whitelist_entry", "enum": [ "collaboration_whitelist_entry" ] }, "domain": { "type": "string", "example": "example.com", "description": "The whitelisted domain" }, "direction": { "type": "string", "example": "both", "description": "The direction of the collaborations to allow.", "enum": [ "inbound", "outbound", "both" ] }, "enterprise": { "allOf": [ { "title": "Enterprise", "type": "object", "description": "A representation of a Box enterprise", "properties": { "id": { "type": "string", "description": "The unique identifier for this enterprise.", "example": "11446498" }, "type": { "type": "string", "description": "`enterprise`", "example": "enterprise", "enum": [ "enterprise" ] }, "name": { "description": "The name of the enterprise", "example": "Acme Inc.", "type": "string" } } }, { "description": "The enterprise this list is applied to" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "The time the entry was created at", "example": "2012-12-12T10:53:43-08:00" } } }, "CollaborationAllowlistEntries": { "title": "Allowed collaboration domains", "type": "object", "x-box-resource-id": "collaboration_allowlist_entries", "x-box-tag": "collaboration_allowlist_entries", "description": "A list of allowed domains for collaboration.", "allOf": [ { "type": "object", "description": "The part of an API response that describes marker\nbased pagination", "properties": { "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "example": 1000, "type": "integer", "format": "int64" }, "next_marker": { "description": "The marker for the start of the next page of results.", "example": 3000, "type": "integer", "format": "int64" }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "example": 1000, "type": "integer", "format": "int64" } } }, { "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/CollaborationAllowlistEntry" } } } } ] }, "CollaborationAllowlistExemptTarget": { "title": "Allowed collaboration domains user exemption", "type": "object", "x-box-resource-id": "collaboration_allowlist_exempt_target", "x-box-tag": "collaboration_allowlist_exempt_targets", "description": "The user that is exempt from any of the restrictions\nimposed by the list of allowed collaboration domains for this enterprise.", "properties": { "id": { "type": "string", "description": "The unique identifier for this exemption", "example": "11446498" }, "type": { "type": "string", "description": "`collaboration_whitelist`", "example": "collaboration_whitelist", "enum": [ "collaboration_whitelist" ] }, "enterprise": { "allOf": [ { "title": "Enterprise", "type": "object", "description": "A representation of a Box enterprise", "properties": { "id": { "type": "string", "description": "The unique identifier for this enterprise.", "example": "11446498" }, "type": { "type": "string", "description": "`enterprise`", "example": "enterprise", "enum": [ "enterprise" ] }, "name": { "description": "The name of the enterprise", "example": "Acme Inc.", "type": "string" } } }, { "description": "The enterprise this entry belongs to" } ] }, "user": { "allOf": [ { "title": "Enterprise", "type": "object", "description": "A representation of a Box enterprise", "properties": { "id": { "type": "string", "description": "The unique identifier for this enterprise.", "example": "11446498" }, "type": { "type": "string", "description": "`enterprise`", "example": "enterprise", "enum": [ "enterprise" ] }, "name": { "description": "The name of the enterprise", "example": "Acme Inc.", "type": "string" } } }, { "description": "The user that has been exempt" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "The time the entry was created", "example": "2012-12-12T10:53:43-08:00" }, "modified_at": { "type": "string", "format": "date-time", "description": "The time the entry was modified", "example": "2012-12-12T10:53:43-08:00" } } }, "CollaborationAllowlistExemptTargets": { "title": "Allowed collaboration domains user exemptions", "type": "object", "x-box-resource-id": "collaboration_allowlist_exempt_targets", "x-box-tag": "collaboration_allowlist_exempt_targets", "description": "A list of users that is exempt from any of the restrictions\nimposed by the list of allowed collaboration domains for this enterprise.", "allOf": [ { "type": "object", "description": "The part of an API response that describes marker\nbased pagination", "properties": { "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "example": 1000, "type": "integer", "format": "int64" }, "next_marker": { "description": "The marker for the start of the next page of results.", "example": 3000, "type": "integer", "format": "int64" }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "example": 1000, "type": "integer", "format": "int64" } } }, { "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/CollaborationAllowlistExemptTarget" } } } } ] }, "Collection": { "title": "Collection", "type": "object", "x-box-resource-id": "collection", "x-box-tag": "collections", "description": "A collection of items, including files and folders.\n\nCurrently, the only collection available\nis the `favorites` collection.\n\nThe contents of a collection can be explored in a\nsimilar way to which the contents of a folder is\nexplored.", "properties": { "id": { "type": "string", "description": "The unique identifier for this collection.", "example": "11446498" }, "type": { "type": "string", "description": "`collection`", "example": "collection", "enum": [ "collection" ] }, "name": { "type": "string", "description": "The name of the collection.", "enum": [ "Favorites" ], "example": "Favorites" }, "collection_type": { "type": "string", "description": "The type of the collection. This is used to\ndetermine the proper visual treatment for\ncollections.", "enum": [ "favorites" ], "example": "favorites" } } }, "Collections": { "title": "Collections", "type": "object", "x-box-resource-id": "collections", "x-box-tag": "collections", "description": "A list of collections", "allOf": [ { "type": "object", "description": "The part of an API response that describes pagination", "properties": { "total_count": { "description": "One greater than the offset of the last entry in the entire collection.\nThe total number of entries in the collection may be less than\n`total_count`.\n\nThis field is only returned for calls that use offset-based pagination.\nFor marker-based paginated APIs, this field will be omitted.", "example": 5000, "type": "integer", "format": "int64" }, "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "example": 1000, "type": "integer", "format": "int64" }, "offset": { "description": "The 0-based offset of the first entry in this set. This will be the same\nas the `offset` query parameter.\n\nThis field is only returned for calls that use offset-based pagination.\nFor marker-based paginated APIs, this field will be omitted.", "example": 2000, "type": "integer", "format": "int64" }, "order": { "description": "The order by which items are returned.\n\nThis field is only returned for calls that use offset-based pagination.\nFor marker-based paginated APIs, this field will be omitted.", "type": "array", "items": { "type": "object", "description": "The order in which a pagination is ordered", "properties": { "by": { "description": "The field to order by", "example": "type", "type": "string" }, "direction": { "type": "string", "description": "The direction to order by, either ascending or descending", "example": "ASC", "enum": [ "ASC", "DESC" ] } } } } } }, { "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/Collection" } } } } ] }, "Comment": { "title": "Comment", "type": "object", "description": "Standard representation of a comment.", "x-box-resource-id": "comment", "x-box-variant": "standard", "allOf": [ { "$ref": "#/components/schemas/Comment--Base" }, { "properties": { "is_reply_comment": { "type": "boolean", "description": "Whether or not this comment is a reply to another\ncomment", "example": true }, "message": { "type": "string", "example": "@Aaron Levie these tigers are cool!", "description": "The text of the comment, as provided by the user" }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "A mini user object representing the author of the\ncomment" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "The time this comment was created", "example": "2012-12-12T10:53:43-08:00" }, "modified_at": { "type": "string", "format": "date-time", "description": "The time this comment was last modified", "example": "2012-12-12T10:53:43-08:00" }, "item": { "allOf": [ { "title": "Reference", "description": "The bare basic reference for an object", "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for this object", "example": "11446498" }, "type": { "type": "string", "description": "The type for this object", "example": "file" } } }, { "description": "The file this comment was placed on" } ] } } } ] }, "Comments": { "title": "Comments", "type": "object", "x-box-resource-id": "comments", "x-box-tag": "comments", "description": "A list of comments", "allOf": [ { "type": "object", "description": "The part of an API response that describes pagination", "properties": { "total_count": { "description": "One greater than the offset of the last entry in the entire collection.\nThe total number of entries in the collection may be less than\n`total_count`.\n\nThis field is only returned for calls that use offset-based pagination.\nFor marker-based paginated APIs, this field will be omitted.", "example": 5000, "type": "integer", "format": "int64" }, "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "example": 1000, "type": "integer", "format": "int64" }, "offset": { "description": "The 0-based offset of the first entry in this set. This will be the same\nas the `offset` query parameter.\n\nThis field is only returned for calls that use offset-based pagination.\nFor marker-based paginated APIs, this field will be omitted.", "example": 2000, "type": "integer", "format": "int64" }, "order": { "description": "The order by which items are returned.\n\nThis field is only returned for calls that use offset-based pagination.\nFor marker-based paginated APIs, this field will be omitted.", "type": "array", "items": { "type": "object", "description": "The order in which a pagination is ordered", "properties": { "by": { "description": "The field to order by", "example": "type", "type": "string" }, "direction": { "type": "string", "description": "The direction to order by, either ascending or descending", "example": "ASC", "enum": [ "ASC", "DESC" ] } } } } } }, { "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" } } } } ] }, "Comment--Base": { "title": "Comment (Base)", "type": "object", "x-box-resource-id": "comment--base", "x-box-sanitized": true, "x-box-tag": "comments", "x-box-variants": [ "base", "standard", "full" ], "x-box-variant": "base", "description": "Base representation of a comment.", "properties": { "id": { "type": "string", "description": "The unique identifier for this comment.", "example": "11446498" }, "type": { "type": "string", "description": "`comment`", "example": "comment", "enum": [ "comment" ] } } }, "Comment--Full": { "title": "Comment (Full)", "type": "object", "x-box-resource-id": "comment--full", "x-box-variant": "full", "description": "Comments are messages created on files. Comments\ncan be made independently or created as responses to other\ncomments", "allOf": [ { "$ref": "#/components/schemas/Comment" }, { "properties": { "tagged_message": { "type": "string", "example": "@[1234567:Aaron Levie] these tigers are cool!", "description": "The string representing the comment text with\n@mentions included. @mention format is @[id:username]\nwhere `id` is user's Box ID and `username` is\ntheir display name." } } } ] }, "DevicePinner": { "title": "Device pinner", "type": "object", "x-box-resource-id": "device_pinner", "x-box-tag": "device_pinners", "description": "Device pins allow enterprises to control what devices can\nuse native Box applications.", "properties": { "id": { "type": "string", "description": "The unique identifier for this device pin.", "example": "11446498" }, "type": { "type": "string", "description": "`device_pinner`", "example": "device_pinner", "enum": [ "device_pinner" ] }, "owned_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user that the device pin belongs to" } ] }, "product_name": { "type": "string", "description": "The type of device being pinned", "example": "iPad" } } }, "DevicePinners": { "title": "Device pinners", "type": "object", "x-box-resource-id": "device_pinners", "x-box-tag": "device_pinners", "description": "A list of device pins", "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/DevicePinner" } }, "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed.", "default": 100, "example": 200, "type": "integer", "format": "int64" }, "next_marker": { "description": "The marker for the start of the next page of results.", "example": 3000, "type": "integer", "format": "int64" }, "order": { "description": "The order by which items are returned.", "type": "array", "items": { "type": "object", "description": "The order in which a pagination is ordered", "properties": { "by": { "description": "The field that is ordered by", "example": "id", "enum": [ "id" ], "type": "string" }, "direction": { "type": "string", "description": "The direction to order by, either ascending or descending", "example": "asc", "enum": [ "asc", "desc" ] } } } } } }, "EmailAlias": { "title": "Email alias", "type": "object", "x-box-resource-id": "email_alias", "x-box-tag": "email_aliases", "description": "An email alias for a user.", "properties": { "id": { "type": "string", "description": "The unique identifier for this object", "example": "11446498" }, "type": { "type": "string", "description": "`email_alias`", "example": "email_alias", "enum": [ "email_alias" ] }, "email": { "type": "string", "description": "The email address", "example": "alias@example.com" }, "is_confirmed": { "type": "boolean", "description": "Whether the email address has been confirmed", "example": true } } }, "EmailAliases": { "title": "Email aliases", "type": "object", "x-box-resource-id": "email_aliases", "x-box-tag": "email_aliases", "description": "A list of email aliases", "properties": { "total_count": { "description": "The number of email aliases.", "example": 5000, "type": "integer", "format": "int64" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/EmailAlias" } } } }, "Enterprise--Base": { "title": "Enterprise (Base)", "type": "object", "x-box-resource-id": "enterprise--base", "x-box-variants": [ "base", "mini", "standard", "full" ], "x-box-variant": "base", "description": "A mini representation of a enterprise, used when\nnested within another resource.", "properties": { "id": { "type": "string", "description": "The unique identifier for this enterprise", "example": "1910967" }, "type": { "type": "string", "description": "`enterprise`", "example": "enterprise", "nullable": false, "enum": [ "enterprise" ] } } }, "Event": { "title": "Event", "type": "object", "x-box-resource-id": "event", "x-box-tag": "events", "description": "The description of an event that happened within Box", "properties": { "type": { "description": "`event`", "type": "string", "example": "event" }, "created_at": { "type": "string", "format": "date-time", "description": "When the event object was created", "example": "2022-12-12T10:53:43-08:00" }, "recorded_at": { "type": "string", "format": "date-time", "description": "When the event object was recorded in database", "example": "2022-12-12T10:54:43-08:00" }, "event_id": { "type": "string", "example": "f82c3ba03e41f7e8a7608363cc6c0390183c3f83", "description": "The ID of the event object. You can use this to detect duplicate events" }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user that performed the action represented by the event.\nSome events may be performed by users not logged into Box.\nIn that case, not all attributes of the object are populated and the\nevent is attributed to a unknown user (`user_id = 2`)" } ] }, "event_type": { "allOf": [ { "title": "Event Type", "example": "FILE_MARKED_MALICIOUS", "type": "string", "description": "An event type that can trigger an event", "enum": [ "ACCESS_GRANTED", "ACCESS_REVOKED", "ADD_DEVICE_ASSOCIATION", "ADD_LOGIN_ACTIVITY_DEVICE", "ADMIN_LOGIN", "APPLICATION_CREATED", "APPLICATION_PUBLIC_KEY_ADDED", "APPLICATION_PUBLIC_KEY_DELETED", "CHANGE_ADMIN_ROLE", "CHANGE_FOLDER_PERMISSION", "COLLABORATION_ACCEPT", "COLLABORATION_EXPIRATION", "COLLABORATION_INVITE", "COLLABORATION_REMOVE", "COLLABORATION_ROLE_CHANGE", "COLLAB_ADD_COLLABORATOR", "COLLAB_INVITE_COLLABORATOR", "COLLAB_REMOVE_COLLABORATOR", "COLLAB_ROLE_CHANGE", "COMMENT_CREATE", "COMMENT_DELETE", "CONTENT_ACCESS", "CONTENT_WORKFLOW_ABNORMAL_DOWNLOAD_ACTIVITY", "CONTENT_WORKFLOW_AUTOMATION_ADD", "CONTENT_WORKFLOW_AUTOMATION_DELETE", "CONTENT_WORKFLOW_POLICY_ADD", "CONTENT_WORKFLOW_SHARING_POLICY_VIOLATION", "CONTENT_WORKFLOW_UPLOAD_POLICY_VIOLATION", "COPY", "DATA_RETENTION_CREATE_RETENTION", "DATA_RETENTION_REMOVE_RETENTION", "DELETE", "DELETE_USER", "DEVICE_TRUST_CHECK_FAILED", "DOWNLOAD", "EDIT", "EDIT_USER", "EMAIL_ALIAS_CONFIRM", "EMAIL_ALIAS_REMOVE", "ENABLE_TWO_FACTOR_AUTH", "ENTERPRISE_APP_AUTHORIZATION_UPDATE", "FAILED_LOGIN", "FILE_MARKED_MALICIOUS", "FILE_WATERMARKED_DOWNLOAD", "GROUP_ADD_ITEM", "GROUP_ADD_USER", "GROUP_CREATION", "GROUP_DELETION", "GROUP_EDITED", "GROUP_REMOVE_ITEM", "GROUP_REMOVE_USER", "ITEM_COPY", "ITEM_CREATE", "ITEM_DOWNLOAD", "ITEM_MAKE_CURRENT_VERSION", "ITEM_MODIFY", "ITEM_MOVE", "ITEM_OPEN", "ITEM_PREVIEW", "ITEM_RENAME", "ITEM_SHARED", "ITEM_SHARED_CREATE", "ITEM_SHARED_UNSHARE", "ITEM_SHARED_UPDATE", "ITEM_SYNC", "ITEM_TRASH", "ITEM_UNDELETE_VIA_TRASH", "ITEM_UNSYNC", "ITEM_UPLOAD", "LEGAL_HOLD_ASSIGNMENT_CREATE", "LEGAL_HOLD_ASSIGNMENT_DELETE", "LEGAL_HOLD_POLICY_CREATE", "LEGAL_HOLD_POLICY_DELETE", "LEGAL_HOLD_POLICY_UPDATE", "LOCK", "LOCK_CREATE", "LOCK_DESTROY", "LOGIN", "MASTER_INVITE_ACCEPT", "MASTER_INVITE_REJECT", "METADATA_INSTANCE_CREATE", "METADATA_INSTANCE_DELETE", "METADATA_INSTANCE_UPDATE", "METADATA_TEMPLATE_CREATE", "METADATA_TEMPLATE_DELETE", "METADATA_TEMPLATE_UPDATE", "MOVE", "NEW_USER", "PREVIEW", "REMOVE_DEVICE_ASSOCIATION", "REMOVE_LOGIN_ACTIVITY_DEVICE", "RENAME", "RETENTION_POLICY_ASSIGNMENT_ADD", "SHARE", "SHARE_EXPIRATION", "SHIELD_ALERT", "SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED", "SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED_MISSING_JUSTIFICATION", "SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED", "SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED_MISSING_JUSTIFICATION", "SHIELD_JUSTIFICATION_APPROVAL", "SIGN_DOCUMENT_ASSIGNED", "SIGN_DOCUMENT_CANCELLED", "SIGN_DOCUMENT_COMPLETED", "SIGN_DOCUMENT_CONVERTED", "SIGN_DOCUMENT_CREATED", "SIGN_DOCUMENT_DECLINED", "SIGN_DOCUMENT_EXPIRED", "SIGN_DOCUMENT_SIGNED", "SIGN_DOCUMENT_VIEWED_BY_SIGNED", "SIGNER_DOWNLOADED", "SIGNER_FORWARDED", "STORAGE_EXPIRATION", "TAG_ITEM_CREATE", "TASK_ASSIGNMENT_CREATE", "TASK_ASSIGNMENT_DELETE", "TASK_ASSIGNMENT_UPDATE", "TASK_CREATE", "TASK_UPDATE", "TERMS_OF_SERVICE_ACCEPT", "TERMS_OF_SERVICE_REJECT", "UNDELETE", "UNLOCK", "UNSHARE", "UPDATE_COLLABORATION_EXPIRATION", "UPDATE_SHARE_EXPIRATION", "UPLOAD", "USER_AUTHENTICATE_OAUTH2_ACCESS_TOKEN_CREATE", "WATERMARK_LABEL_CREATE", "WATERMARK_LABEL_DELETE" ] }, { "description": "The event type that triggered this event" } ] }, "session_id": { "type": "string", "example": "70090280850c8d2a1933c1", "description": "The session of the user that performed the action. Not all events will\npopulate this attribute." }, "source": { "allOf": [ { "oneOf": [ { "$ref": "#/components/schemas/User" }, { "$ref": "#/components/schemas/EventSource" }, { "$ref": "#/components/schemas/File" }, { "$ref": "#/components/schemas/Folder" } ] }, { "description": "The resource that triggered this event. For more information,\ncheck out the guide on event triggers." } ] }, "additional_details": { "type": "object", "example": { "key": "value" }, "description": "This object provides additional information about the event if available.\n\nThis can include how a user performed an event as well as additional\ninformation to correlate an event to external KeySafe logs. Not all events\nhave an `additional_details` object. This object is only available in the\nEnterprise Events." } } }, "Events": { "title": "Events", "type": "object", "x-box-resource-id": "events", "x-box-tag": "events", "description": "A list of event objects", "properties": { "chunk_size": { "description": "The number of events returned in this response.", "example": 2, "type": "integer", "format": "int64" }, "next_stream_position": { "description": "The stream position of the start of the next page (chunk)\nof events.", "example": "1152922976252290886", "type": "string" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } } } }, "File": { "title": "File", "type": "object", "x-box-resource-id": "file", "x-box-variant": "standard", "description": "A standard representation of a file, as returned from any\nfile API endpoints by default", "allOf": [ { "$ref": "#/components/schemas/File--Mini" }, { "properties": { "description": { "type": "string", "nullable": false, "description": "The optional description of this file", "maxLength": 256, "example": "Contract for Q1 renewal" }, "size": { "type": "integer", "nullable": false, "description": "The file size in bytes. Be careful parsing this integer as it can\nget very large and cause an integer overflow.", "example": 629644 }, "path_collection": { "allOf": [ { "title": "Path collection", "description": "A list of parent folders for an item.", "type": "object", "required": [ "total_count", "entries" ], "properties": { "total_count": { "description": "The number of folders in this list.", "example": 1, "type": "integer", "format": "int64", "nullable": false }, "entries": { "type": "array", "description": "The parent folders for this item", "nullable": false, "items": { "$ref": "#/components/schemas/Folder--Mini" } } } }, { "description": "The tree of folders that this file is contained in,\nstarting at the root." }, { "nullable": false } ] }, "created_at": { "type": "string", "format": "date-time", "nullable": false, "description": "The date and time when the file was created on Box.", "example": "2012-12-12T10:53:43-08:00" }, "modified_at": { "type": "string", "format": "date-time", "nullable": false, "description": "The date and time when the file was last updated on Box.", "example": "2012-12-12T10:53:43-08:00" }, "trashed_at": { "type": "string", "format": "date-time", "description": "The time at which this file was put in the trash.", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "purged_at": { "type": "string", "format": "date-time", "description": "The time at which this file is expected to be purged\nfrom the trash.", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "content_created_at": { "type": "string", "format": "date-time", "nullable": true, "description": "The date and time at which this file was originally\ncreated, which might be before it was uploaded to Box.", "example": "2012-12-12T10:53:43-08:00" }, "content_modified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "The date and time at which this file was last updated,\nwhich might be before it was uploaded to Box.", "example": "2012-12-12T10:53:43-08:00" }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who created this file" } ] }, "modified_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who last modified this file" }, { "nullable": false } ] }, "owned_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who owns this file" }, { "nullable": false } ] }, "shared_link": { "allOf": [ { "title": "Shared link", "description": "Shared links provide direct, read-only access to files or folder on Box.\n\nShared links with open access level allow anyone with the URL\nto access the item, while shared links with company or collaborators access\nlevels can only be accessed by appropriately authenticated Box users.", "type": "object", "required": [ "url", "accessed", "effective_access", "effective_permission", "is_password_enabled", "download_count", "preview_count" ], "properties": { "url": { "type": "string", "format": "url", "description": "The URL that can be used to access the item on Box.\n\nThis URL will display the item in Box's preview UI where the file\ncan be downloaded if allowed.\n\nThis URL will continue to work even when a custom `vanity_url`\nhas been set for this shared link.", "example": "https://www.box.com/s/vspke7y05sb214wjokpk", "nullable": false }, "download_url": { "type": "string", "format": "url", "x-box-premium-feature": true, "description": "A URL that can be used to download the file. This URL can be used in\na browser to download the file. This URL includes the file\nextension so that the file will be saved with the right file type.\n\nThis property will be `null` for folders.", "example": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg", "nullable": true }, "vanity_url": { "type": "string", "format": "url", "description": "The \"Custom URL\" that can also be used to preview the item on Box. Custom\nURLs can only be created or modified in the Box Web application.", "example": "https://acme.app.box.com/v/my_url/", "nullable": true }, "vanity_name": { "type": "string", "description": "The custom name of a shared link, as used in the `vanity_url` field.", "example": "my_url", "nullable": true }, "access": { "type": "string", "description": "The access level for this shared link.\n\n* `open` - provides access to this item to anyone with this link\n* `company` - only provides access to this item to people the same company\n* `collaborators` - only provides access to this item to people who are\n collaborators on this item\n\nIf this field is omitted when creating the shared link, the access level\nwill be set to the default access level specified by the enterprise admin.", "enum": [ "open", "company", "collaborators" ], "example": "open", "nullable": false }, "effective_access": { "type": "string", "description": "The effective access level for the shared link. This can be a more\nrestrictive access level than the value in the `access` field when the\nenterprise settings restrict the allowed access levels.", "enum": [ "open", "company", "collaborators" ], "example": "company", "nullable": false }, "effective_permission": { "type": "string", "description": "The effective permissions for this shared link.\nThese result in the more restrictive combination of\nthe share link permissions and the item permissions set\nby the administrator, the owner, and any ancestor item\nsuch as a folder.", "enum": [ "can_edit", "can_download", "can_preview", "no_access" ], "example": "can_download", "nullable": false }, "unshared_at": { "type": "string", "format": "date-time", "description": "The date and time when this link will be unshared. This field can only be\nset by users with paid accounts.", "example": "2018-04-13T13:53:23-07:00", "nullable": true }, "is_password_enabled": { "type": "boolean", "description": "Defines if the shared link requires a password to access the item.", "example": true, "nullable": false }, "permissions": { "type": "object", "description": "Defines if this link allows a user to preview, edit, and download an item.\nThese permissions refer to the shared link only and\ndo not supersede permissions applied to the item itself.", "required": [ "can_download", "can_preview", "can_edit" ], "properties": { "can_download": { "type": "boolean", "example": true, "nullable": false, "description": "Defines if the shared link allows for the item to be downloaded. For\nshared links on folders, this also applies to any items in the folder.\n\nThis value can be set to `true` when the effective access level is\nset to `open` or `company`, not `collaborators`." }, "can_preview": { "type": "boolean", "example": true, "nullable": false, "description": "Defines if the shared link allows for the item to be previewed.\n\nThis value is always `true`. For shared links on folders this also\napplies to any items in the folder." }, "can_edit": {