diff --git a/openapi.json b/openapi.json index 7d4887ec..00f231d3 100644 --- a/openapi.json +++ b/openapi.json @@ -14,7 +14,7 @@ "url": "http://www.apache.org/licenses/LICENSE-2.0" }, "version": "2.0.0", - "x-box-commit-hash": "73eface93e" + "x-box-commit-hash": "7422d8d30e" }, "servers": [ { @@ -28,23 +28,11 @@ "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", + "description": "The type of response we'd like to receive.", "required": true, "schema": { "type": "string", @@ -52,48 +40,49 @@ "enum": [ "code" ] - } + }, + "example": "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", + "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.", "required": true, "schema": { "type": "string" - } + }, + "example": "ly1nj6n11vionaie65emwzk575hnnmrk" }, { "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", + "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.", "required": false, "schema": { "type": "string", "format": "url" - } + }, + "example": "http://example.com/auth/callback" }, { "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", + "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.", "required": false, "schema": { "type": "string" - } + }, + "example": "my_state" }, { "name": "scope", - "description": "A space-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", + "description": "A space-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.", "required": false, "schema": { "type": "string" - } + }, + "example": "admin_readwrite" } ], "responses": { @@ -119,7 +108,18 @@ } } } - } + }, + "x-box-tag": "authorization", + "security": [], + "servers": [ + { + "url": "https://account.box.com/api/oauth2", + "description": "Server for client-side authentication" + } + ], + "tags": [ + "Authorization" + ] } }, "/oauth2/token": { @@ -127,17 +127,6 @@ "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": { @@ -178,7 +167,18 @@ } } } - } + }, + "x-box-tag": "authorization", + "security": [], + "servers": [ + { + "url": "https://api.box.com", + "description": "Server for server-side authentication" + } + ], + "tags": [ + "Authorization" + ] } }, "/oauth2/token#refresh": { @@ -186,18 +186,6 @@ "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": { @@ -238,7 +226,19 @@ } } } - } + }, + "x-box-tag": "authorization", + "security": [], + "servers": [ + { + "url": "https://api.box.com", + "description": "Server for server-side authentication" + } + ], + "tags": [ + "Authorization" + ], + "x-box-is-variation": true } }, "/oauth2/revoke": { @@ -246,17 +246,6 @@ "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": { @@ -290,77 +279,84 @@ } } } - } + }, + "x-box-tag": "authorization", + "security": [], + "servers": [ + { + "url": "https://api.box.com", + "description": "Server for server-side authentication" + } + ], + "tags": [ + "Authorization" + ] } }, "/files/{file_id}": { "get": { "operationId": "get_files_id", "summary": "Get file information", - "tags": [ - "Files" - ], - "x-box-tag": "files", "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "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`?fields=metadata.enterprise_12345.contractTemplate`.", "in": "query", - "example": [ - "id", - "type", - "name" - ], + "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`?fields=metadata.enterprise_12345.contractTemplate`.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false }, { "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", + "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.", "required": false, - "example": "1", "schema": { "type": "string" - } + }, + "example": "1" }, { "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", + "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.", "required": false, "schema": { "type": "string" - } + }, + "example": "shared_link=[link]&shared_link_password=[password]" }, { "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", + "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]`", "required": false, "schema": { "type": "string", "nullable": true - } + }, + "example": "[pdf]" } ], "responses": { @@ -427,44 +423,44 @@ } } } - } + }, + "x-box-tag": "files", + "tags": [ + "Files" + ] }, "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "requestBody": { @@ -475,8 +471,8 @@ "properties": { "name": { "description": "An optional new name for the file.", - "example": "Restored.docx", - "type": "string" + "type": "string", + "example": "Restored.docx" }, "parent": { "allOf": [ @@ -485,8 +481,8 @@ "description": "The parent for this item", "properties": { "id": { - "type": "string", "description": "The ID of parent item", + "type": "string", "example": "123" } } @@ -552,54 +548,54 @@ } } } - } + }, + "x-box-tag": "trashed_files", + "tags": [ + "Trashed files" + ] }, "put": { "operationId": "put_files_id", "summary": "Update file", - "tags": [ - "Files" - ], - "x-box-tag": "files", "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": 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", + "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.", "required": false, - "example": "1", "schema": { "type": "string" - } + }, + "example": "1" } ], "requestBody": { @@ -609,15 +605,15 @@ "type": "object", "properties": { "name": { - "type": "string", "description": "An optional different name for the file. This can be used to\nrename the file.", + "type": "string", "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" + "type": "string", + "example": "The latest reports. Automatically updated", + "maxLength": 256 }, "parent": { "allOf": [ @@ -626,8 +622,8 @@ "description": "The parent for this item", "properties": { "id": { - "type": "string", "description": "The ID of parent item", + "type": "string", "example": "123" } } @@ -638,46 +634,45 @@ ] }, "shared_link": { - "nullable": true, "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.", + "type": "string", + "example": "open", "enum": [ "open", "company", "collaborators" - ], - "example": "open" + ] }, "password": { - "type": "string", - "nullable": true, "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\nPasswords must now be at least eight characters\nlong and include a number, upper case letter, or\na non-numeric or non-alphabetic character.\nA password can only be set when `access` is set to `open`.", - "example": "do-n8t-use-this-Password" + "type": "string", + "example": "do-n8t-use-this-Password", + "nullable": true }, "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.", + "type": "string", "example": "my-shared-link" }, "unshared_at": { + "description": "The timestamp at which this shared link will\nexpire. This field can only be set by\nusers with paid accounts.", "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." + "example": "2012-12-12T10:53:43-08:00" }, "permissions": { "type": "object", "properties": { "can_download": { + "description": "If the shared link allows for downloading of files.\nThis can only be set when `access` is set to\n`open` or `company`.", "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`." + "example": true } } } @@ -686,42 +681,43 @@ { "description": "Defines a shared link for a file. Set this to `null` to remove\nthe shared link." } - ] + ], + "nullable": true }, "lock": { + "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.", "type": "object", "nullable": true, - "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.", + "type": "string", + "example": "lock", "enum": [ "lock" - ], - "example": "lock" + ] }, "expires_at": { + "description": "Defines the time at which the lock expires.", "type": "string", "format": "date-time", - "example": "2012-12-12T10:53:43-08:00", - "description": "Defines the time at which the lock expires." + "example": "2012-12-12T10:53:43-08:00" }, "is_download_prevented": { + "description": "Defines if the file can be downloaded while it is locked.", "type": "boolean", - "example": true, - "description": "Defines if the file can be downloaded while it is locked." + "example": true } - } + }, + "required": [ + "type" + ] }, "disposition_at": { + "description": "The retention expiration timestamp for the given file. This\ndate cannot be shortened once set on a file.", "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." + "example": "2012-12-12T10:53:43-08:00" }, "permissions": { "description": "Defines who can download a file.", @@ -739,38 +735,38 @@ } }, "collections": { - "type": "array", - "nullable": true, "description": "An array of collections to make this file\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 file from all collections.\n\n[1]: e://get-collections", + "type": "array", "items": { "title": "Reference", "description": "The bare basic reference for an object", "type": "object", "properties": { "id": { - "type": "string", "description": "The unique identifier for this object", + "type": "string", "example": "11446498" }, "type": { - "type": "string", "description": "The type for this object", + "type": "string", "example": "file" } } - } + }, + "nullable": true }, "tags": { + "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.", "type": "array", - "example": [ - "approved" - ], "items": { "type": "string" }, - "minItems": 1, + "example": [ + "approved" + ], "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." + "minItems": 1 } } } @@ -858,36 +854,36 @@ } } } - } + }, + "x-box-tag": "files", + "tags": [ + "Files" + ] }, "delete": { "operationId": "delete_files_id", "summary": "Delete file", - "tags": [ - "Files" - ], - "x-box-tag": "files", "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "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", + "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.", "required": false, - "example": "1", "schema": { "type": "string" - } + }, + "example": "1" } ], "responses": { @@ -944,7 +940,11 @@ } } } - } + }, + "x-box-tag": "files", + "tags": [ + "Files" + ] } }, "/files/{file_id}/app_item_associations": { @@ -952,53 +952,49 @@ "operationId": "get_files_id_app_item_associations", "summary": "List file app item associations", "description": "**This is a beta feature, which means that its availability might be limited.**\nReturns all app items the file is associated with. This includes app items\nassociated with ancestors of the file. Assuming the context user has access\nto the file, the type/ids are revealed even if the context user does not\nhave **View** permission on the app item.", - "tags": [ - "App item associations" - ], - "x-box-tag": "app_item_associations", "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "application_type", - "description": "If given, only return app items for this application type", - "example": "hubs", "in": "query", + "description": "If given, only return app items for this application type", "required": false, "schema": { "type": "string", "nullable": false - } + }, + "example": "hubs" } ], "responses": { @@ -1032,68 +1028,68 @@ } } } - } + }, + "x-box-tag": "app_item_associations", + "tags": [ + "App item associations" + ] } }, "/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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "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", + "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.", "required": false, "schema": { "type": "string" - } + }, + "example": "bytes=0-1024" }, { "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", + "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.", "required": false, "schema": { "type": "string" - } + }, + "example": "shared_link=[link]&shared_link_password=[password]" }, { "name": "version", - "description": "The file version to download", - "example": "4", "in": "query", + "description": "The file version to download", "required": false, "schema": { "type": "string" - } + }, + "example": "4" }, { "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", + "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.", "required": false, "schema": { "type": "string" - } + }, + "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" } ], "responses": { @@ -1102,9 +1098,9 @@ "content": { "application/octet-stream": { "schema": { + "description": "The binary content of the file", "type": "string", - "format": "binary", - "description": "The binary content of the file" + "format": "binary" } } } @@ -1142,70 +1138,64 @@ } } } - } + }, + "x-box-tag": "downloads", + "tags": [ + "Downloads" + ] }, "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\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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "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", + "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.", "required": false, - "example": "1", "schema": { "type": "string" - } + }, + "example": "1" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false }, { "name": "content-md5", + "in": "header", + "description": "An optional header containing the SHA1 hash of the file to\nensure that the file was not corrupted in transit.", "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." + "example": "134b65991ed521fcfe4724b7d814ab8ded5185dc" } ], "requestBody": { @@ -1213,37 +1203,37 @@ "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.", + "type": "string", "example": "Photo 2.0.png" }, "content_modified_at": { + "description": "Defines the time the file was last modified at.\n\nIf not set, the upload time will be used.", "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." + "example": "2012-12-12T10:53:43-08:00" } - } + }, + "required": [ + "name" + ] }, "file": { + "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", "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" + "format": "binary" } - } + }, + "required": [ + "attributes", + "file" + ] } } } @@ -1279,7 +1269,17 @@ } } } - } + }, + "x-box-tag": "uploads", + "servers": [ + { + "url": "https://upload.box.com/api/2.0", + "description": "Server for file uploads" + } + ], + "tags": [ + "Uploads" + ] } }, "/files/content": { @@ -1298,14 +1298,14 @@ "type": "object", "properties": { "name": { - "type": "string", "description": "The name for the file", + "type": "string", "example": "File.mp4" }, "size": { + "description": "The size of the file in bytes", "type": "integer", "format": "int32", - "description": "The size of the file in bytes", "example": 1024 }, "parent": { @@ -1315,8 +1315,8 @@ "description": "The parent for this item", "properties": { "id": { - "type": "string", "description": "The ID of parent item", + "type": "string", "example": "123" } } @@ -1366,46 +1366,36 @@ }, "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\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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false }, { "name": "content-md5", + "in": "header", + "description": "An optional header containing the SHA1 hash of the file to\nensure that the file was not corrupted in transit.", "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." + "example": "134b65991ed521fcfe4724b7d814ab8ded5185dc" } ], "requestBody": { @@ -1413,58 +1403,58 @@ "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", + "type": "string", "example": "Photo.png" }, "parent": { - "type": "object", "description": "The parent folder to upload the file to", - "required": [ - "id" - ], + "type": "object", "properties": { "id": { + "description": "The id of the parent folder. Use\n`0` for the user's root folder.", "type": "string", - "example": "124132", - "description": "The id of the parent folder. Use\n`0` for the user's root folder." + "example": "124132" } - } + }, + "required": [ + "id" + ] }, "content_created_at": { + "description": "Defines the time the file was originally created at.\n\nIf not set, the upload time will be used.", "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." + "example": "2012-12-12T10:53:43-08:00" }, "content_modified_at": { + "description": "Defines the time the file was last modified at.\n\nIf not set, the upload time will be used.", "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." + "example": "2012-12-12T10:53:43-08:00" } - } + }, + "required": [ + "name", + "parent" + ] }, "file": { + "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", "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" + "format": "binary" } - } + }, + "required": [ + "attributes", + "file" + ] } } } @@ -1520,34 +1510,29 @@ } } } - } + }, + "x-box-tag": "uploads", + "servers": [ + { + "url": "https://upload.box.com/api/2.0", + "description": "Server for file uploads" + } + ], + "tags": [ + "Uploads" + ] } }, "/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.", @@ -1556,16 +1541,21 @@ }, "file_size": { "description": "The total number of bytes of the file to be uploaded", - "example": 104857600, "type": "integer", - "format": "int64" + "format": "int64", + "example": 104857600 }, "file_name": { "description": "The name of new file", - "example": "Project.mov", - "type": "string" + "type": "string", + "example": "Project.mov" } - } + }, + "required": [ + "folder_id", + "file_size", + "file_name" + ] } } } @@ -1631,34 +1621,34 @@ } } } - } - } - }, - "/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" } ], + "tags": [ + "Uploads (Chunked)" + ] + } + }, + "/files/{file_id}/upload_sessions": { + "post": { + "operationId": "post_files_id_upload_sessions", + "summary": "Create upload session for existing file", + "description": "Creates an upload session for an existing 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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "requestBody": { @@ -1666,22 +1656,22 @@ "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" + "format": "int64", + "example": 104857600 }, "file_name": { "description": "The optional new name of new file", - "example": "Project.mov", - "type": "string" + "type": "string", + "example": "Project.mov" } - } + }, + "required": [ + "file_size" + ] } } } @@ -1717,41 +1707,34 @@ } } } - } + }, + "x-box-tag": "chunked_uploads", + "servers": [ + { + "url": "https://upload.box.com/api/2.0", + "description": "Server for file uploads" + } + ], + "tags": [ + "Uploads (Chunked)" + ] } }, "/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.\n\nThe actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) endpoint.", - "x-box-tag": "chunked_uploads", - "x-box-enable-explorer": false, - "servers": [ - { - "url": "https://{box-upload-server}/api/2.0", - "description": "Server for file uploads", - "variables": { - "box-upload-server": { - "description": "The server for the upload session.", - "default": "upload.box.com" - } - } - } - ], "parameters": [ { "name": "upload_session_id", - "description": "The ID of the upload session.", - "example": "D5E3F7A", "in": "path", + "description": "The ID of the upload session.", "required": true, "schema": { "type": "string" - } + }, + "example": "D5E3F7A" } ], "responses": { @@ -1775,17 +1758,8 @@ } } } - } - }, - "put": { - "operationId": "put_files_upload_sessions_id", - "summary": "Upload part of file", - "tags": [ - "Uploads (Chunked)" - ], + }, "x-box-tag": "chunked_uploads", - "x-box-enable-explorer": false, - "description": "Uploads a chunk of a file for an upload session.\n\nThe actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions)\nand [`Get upload session`](e://get-files-upload-sessions-id) endpoints.", "servers": [ { "url": "https://{box-upload-server}/api/2.0", @@ -1798,45 +1772,54 @@ } } ], + "tags": [ + "Uploads (Chunked)" + ], + "x-box-enable-explorer": false + }, + "put": { + "operationId": "put_files_upload_sessions_id", + "summary": "Upload part of file", + "description": "Uploads a chunk of a file for an upload session.\n\nThe actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions)\nand [`Get upload session`](e://get-files-upload-sessions-id) endpoints.", "parameters": [ { "name": "upload_session_id", - "description": "The ID of the upload session.", - "example": "D5E3F7A", "in": "path", + "description": "The ID of the upload session.", "required": true, "schema": { "type": "string" - } + }, + "example": "D5E3F7A" }, { "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", + "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", "required": true, "schema": { "type": "string" - } + }, + "example": "sha=fpRyg5eVQletdZqEKaFlqwBXJzM=" }, { "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", + "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.", "required": true, "schema": { "type": "string" - } + }, + "example": "bytes 8388608-16777215/445856194" } ], "requestBody": { "content": { "application/octet-stream": { "schema": { + "description": "The binary content of the file", "type": "string", - "format": "binary", - "description": "The binary content of the file" + "format": "binary" } } } @@ -1892,15 +1875,8 @@ } } } - } - }, - "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.\n\nThe actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions)\nand [`Get upload session`](e://get-files-upload-sessions-id) endpoints.", + }, + "x-box-tag": "chunked_uploads", "servers": [ { "url": "https://{box-upload-server}/api/2.0", @@ -1913,18 +1889,25 @@ } } ], - "x-box-tag": "chunked_uploads", - "x-box-enable-explorer": false, + "tags": [ + "Uploads (Chunked)" + ], + "x-box-enable-explorer": false + }, + "delete": { + "operationId": "delete_files_upload_sessions_id", + "summary": "Remove upload session", + "description": "Abort an upload session and discard all data uploaded.\n\nThis cannot be reversed.\n\nThe actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions)\nand [`Get upload session`](e://get-files-upload-sessions-id) endpoints.", "parameters": [ { "name": "upload_session_id", - "description": "The ID of the upload session.", - "example": "D5E3F7A", "in": "path", + "description": "The ID of the upload session.", "required": true, "schema": { "type": "string" - } + }, + "example": "D5E3F7A" } ], "responses": { @@ -1941,18 +1924,8 @@ } } } - } - } - }, - "/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", - "x-box-enable-explorer": false, "servers": [ { "url": "https://{box-upload-server}/api/2.0", @@ -1965,41 +1938,51 @@ } } ], + "tags": [ + "Uploads (Chunked)" + ], + "x-box-enable-explorer": false + } + }, + "/files/upload_sessions/{upload_session_id}/parts": { + "get": { + "operationId": "get_files_upload_sessions_id_parts", + "summary": "List parts", "description": "Return a list of the chunks uploaded to the upload session so far.\n\nThe actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions)\nand [`Get upload session`](e://get-files-upload-sessions-id) endpoints.", "parameters": [ { "name": "upload_session_id", - "description": "The ID of the upload session.", - "example": "D5E3F7A", "in": "path", + "description": "The ID of the upload session.", "required": true, "schema": { "type": "string" - } + }, + "example": "D5E3F7A" }, { "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", + "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.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 - } + }, + "example": 1000 }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 1000 } ], "responses": { @@ -2023,18 +2006,8 @@ } } } - } - } - }, - "/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", - "x-box-enable-explorer": false, "servers": [ { "url": "https://{box-upload-server}/api/2.0", @@ -2047,47 +2020,57 @@ } } ], + "tags": [ + "Uploads (Chunked)" + ], + "x-box-enable-explorer": false + } + }, + "/files/upload_sessions/{upload_session_id}/commit": { + "post": { + "operationId": "post_files_upload_sessions_id_commit", + "summary": "Commit upload session", "description": "Close an upload session and create a file from the uploaded chunks.\n\nThe actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions)\nand [`Get upload session`](e://get-files-upload-sessions-id) endpoints.", "parameters": [ { "name": "upload_session_id", - "description": "The ID of the upload session.", - "example": "D5E3F7A", "in": "path", + "description": "The ID of the upload session.", "required": true, "schema": { "type": "string" - } + }, + "example": "D5E3F7A" }, { "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=", + "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", "required": true, "schema": { "type": "string" - } + }, + "example": "sha=fpRyg5eVQletdZqEKaFlqwBXJzM=" }, { "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", + "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.", "required": false, - "example": "1", "schema": { "type": "string" - } + }, + "example": "1" }, { "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", + "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.", "required": false, - "example": "1", "schema": { "type": "string" - } + }, + "example": "1" } ], "requestBody": { @@ -2095,18 +2078,18 @@ "application/json": { "schema": { "type": "object", - "required": [ - "parts" - ], "properties": { "parts": { - "type": "array", "description": "The list details for the uploaded parts", + "type": "array", "items": { "$ref": "#/components/schemas/UploadPart" } } - } + }, + "required": [ + "parts" + ] } } } @@ -2163,7 +2146,24 @@ } } } - } + }, + "x-box-tag": "chunked_uploads", + "servers": [ + { + "url": "https://{box-upload-server}/api/2.0", + "description": "Server for file uploads", + "variables": { + "box-upload-server": { + "description": "The server for the upload session.", + "default": "upload.box.com" + } + } + } + ], + "tags": [ + "Uploads (Chunked)" + ], + "x-box-enable-explorer": false } }, "/files/{file_id}/copy": { @@ -2171,38 +2171,34 @@ "operationId": "post_files_id_copy", "summary": "Copy file", "description": "Creates a copy of a file.", - "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "requestBody": { @@ -2210,37 +2206,37 @@ "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.", + "type": "string", "example": "FileCopy.txt", "maxLength": 255 }, "version": { - "type": "string", "description": "An optional ID of the specific file version to copy.", + "type": "string", "example": "0" }, "parent": { - "type": "object", "description": "The destination folder to copy the file to.", - "required": [ - "id" - ], + "type": "object", "properties": { "id": { - "type": "string", "description": "The ID of folder to copy the file to.", + "type": "string", "example": "0" } - } + }, + "required": [ + "id" + ] } - } + }, + "nullable": false, + "required": [ + "parent" + ] } } } @@ -2309,7 +2305,11 @@ } } } - } + }, + "x-box-tag": "files", + "tags": [ + "Files" + ] } }, "/files/{file_id}/thumbnail.{extension}": { @@ -2317,98 +2317,94 @@ "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "name": "extension", - "description": "The file format for the thumbnail", "in": "path", + "description": "The file format for the thumbnail", "required": true, - "example": "png", "schema": { "type": "string", "enum": [ "png", "jpg" ] - } + }, + "example": "png" }, { "name": "min_height", - "description": "The minimum height of the thumbnail", "in": "query", - "example": 32, + "description": "The minimum height of the thumbnail", "schema": { "type": "integer", - "minimum": 32, - "maximum": 320 - } + "maximum": 320, + "minimum": 32 + }, + "example": 32 }, { "name": "min_width", - "description": "The minimum width of the thumbnail", "in": "query", - "example": 32, + "description": "The minimum width of the thumbnail", "schema": { "type": "integer", - "minimum": 32, - "maximum": 320 - } + "maximum": 320, + "minimum": 32 + }, + "example": 32 }, { "name": "max_height", - "description": "The maximum height of the thumbnail", "in": "query", + "description": "The maximum height of the thumbnail", "required": false, - "example": 320, "schema": { "type": "integer", - "minimum": 32, - "maximum": 320 - } + "maximum": 320, + "minimum": 32 + }, + "example": 320 }, { "name": "max_width", - "description": "The maximum width of the thumbnail", "in": "query", + "description": "The maximum width of the thumbnail", "required": false, - "example": 320, "schema": { "type": "integer", - "minimum": 32, - "maximum": 320 - } + "maximum": 320, + "minimum": 32 + }, + "example": 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": { + "image/jpg": { "schema": { + "description": "The thumbnail", "type": "string", - "format": "binary", - "description": "The thumbnail" + "format": "binary" } }, - "image/jpg": { + "image/png": { "schema": { + "description": "The thumbnail", "type": "string", - "format": "binary", - "description": "The thumbnail" + "format": "binary" } } } @@ -2484,7 +2480,11 @@ } } } - } + }, + "x-box-tag": "files", + "tags": [ + "Files" + ] } }, "/files/{file_id}/collaborations": { @@ -2492,60 +2492,56 @@ "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" } ], "responses": { @@ -2569,7 +2565,11 @@ } } } - } + }, + "x-box-tag": "list_collaborations", + "tags": [ + "Collaborations (List)" + ] } }, "/files/{file_id}/comments": { @@ -2577,62 +2577,58 @@ "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 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", + "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.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 - } + }, + "example": 1000 } ], "responses": { @@ -2656,7 +2652,11 @@ } } } - } + }, + "x-box-tag": "comments", + "tags": [ + "Comments" + ] } }, "/files/{file_id}/tasks": { @@ -2664,20 +2664,16 @@ "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", "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "responses": { @@ -2731,46 +2727,46 @@ } } } - } + }, + "x-box-tag": "tasks", + "tags": [ + "Tasks" + ] } }, "/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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "responses": { @@ -2804,26 +2800,26 @@ } } } - } + }, + "x-box-tag": "trashed_files", + "tags": [ + "Trashed files" + ] }, "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "responses": { @@ -2850,70 +2846,70 @@ } } } - } + }, + "x-box-tag": "trashed_files", + "tags": [ + "Trashed files" + ] } }, "/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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 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", + "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.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 - } + }, + "example": 1000 } ], "responses": { @@ -2937,56 +2933,56 @@ } } } - } + }, + "x-box-tag": "file_versions", + "tags": [ + "File versions" + ] } }, "/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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false }, { "name": "file_version_id", - "description": "The ID of the file version", "in": "path", + "description": "The ID of the file version", "required": true, - "example": "1234", "schema": { "type": "string" - } + }, + "example": "1234" } ], "responses": { @@ -3010,46 +3006,46 @@ } } } - } + }, + "x-box-tag": "file_versions", + "tags": [ + "File versions" + ] }, "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "name": "file_version_id", - "description": "The ID of the file version", "in": "path", + "description": "The ID of the file version", "required": true, - "example": "1234", "schema": { "type": "string" - } + }, + "example": "1234" }, { "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", + "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.", "required": false, - "example": "1", "schema": { "type": "string" - } + }, + "example": "1" } ], "responses": { @@ -3066,50 +3062,50 @@ } } } - } + }, + "x-box-tag": "file_versions", + "tags": [ + "File versions" + ] }, "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "name": "file_version_id", - "description": "The ID of the file version", "in": "path", + "description": "The ID of the file version", "required": true, - "example": "1234", "schema": { "type": "string" - } + }, + "example": "1234" } ], "requestBody": { "content": { "application/json": { "schema": { - "type": "object", "description": "The file version to be\nrestored", + "type": "object", "properties": { "trashed_at": { - "type": "string", - "nullable": true, "description": "Set this to `null` to clear\nthe date and restore the file.", - "example": null + "type": "string", + "example": null, + "nullable": true } } } @@ -3137,63 +3133,63 @@ } } } - } + }, + "x-box-tag": "file_versions", + "tags": [ + "File versions" + ] } }, "/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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "requestBody": { "content": { "application/json": { "schema": { - "type": "object", "description": "The file version to promote", + "type": "object", "properties": { "id": { - "type": "string", "description": "The file version ID", + "type": "string", "example": "11446498" }, "type": { - "type": "string", "description": "The type to promote", + "type": "string", "example": "file_version", "enum": [ "file_version" @@ -3225,28 +3221,28 @@ } } } - } + }, + "x-box-tag": "file_versions", + "tags": [ + "File versions" + ] } }, "/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", "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "responses": { @@ -3290,28 +3286,28 @@ } } } - } + }, + "x-box-tag": "file_metadata", + "tags": [ + "Metadata instances (Files)" + ] } }, "/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", "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "responses": { @@ -3365,26 +3361,26 @@ } } } - } + }, + "x-box-tag": "file_classifications", + "tags": [ + "Classifications on files" + ] }, "post": { "operationId": "post_files_id_metadata_enterprise_securityClassification-6VMVochwUWo", "summary": "Add classification to file", - "tags": [ - "Classifications on files" - ], - "x-box-tag": "file_classifications", "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "requestBody": { @@ -3394,8 +3390,8 @@ "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.", + "type": "string", "example": "Sensitive" } } @@ -3454,35 +3450,32 @@ } } } - } + }, + "x-box-tag": "file_classifications", + "tags": [ + "Classifications on files" + ] }, "put": { "operationId": "put_files_id_metadata_enterprise_securityClassification-6VMVochwUWo", "summary": "Update classification on file", - "tags": [ - "Classifications on files" - ], - "x-box-tag": "file_classifications", "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "requestBody": { "content": { "application/json-patch+json": { "schema": { - "required": [ - "items" - ], "description": "A list containing the one change to make, to\nupdate the classification label.", "type": "array", "items": { @@ -3495,28 +3488,31 @@ ], "properties": { "op": { + "description": "`replace`", "type": "string", "example": "replace", - "description": "`replace`", "enum": [ "replace" ] }, "path": { + "description": "Defines classifications \navailable in the enterprise.", "type": "string", "example": "/Box__Security__Classification__Key", - "description": "Defines classifications \navailable in the enterprise.", "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.", + "type": "string", "example": "Sensitive" } } - } + }, + "required": [ + "items" + ] } } } @@ -3562,26 +3558,26 @@ } } } - } + }, + "x-box-tag": "file_classifications", + "tags": [ + "Classifications on files" + ] }, "delete": { "operationId": "delete_files_id_metadata_enterprise_securityClassification-6VMVochwUWo", "summary": "Remove classification from file", - "tags": [ - "Classifications on files" - ], - "x-box-tag": "file_classifications", "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "responses": { @@ -3628,34 +3624,33 @@ } } } - } + }, + "x-box-tag": "file_classifications", + "tags": [ + "Classifications on files" + ] } }, "/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", "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "name": "scope", - "description": "The scope of the metadata template", - "example": "global", "in": "path", + "description": "The scope of the metadata template", "required": true, "schema": { "type": "string", @@ -3663,17 +3658,18 @@ "global", "enterprise" ] - } + }, + "example": "global" }, { "name": "template_key", - "description": "The name of the metadata template", - "example": "properties", "in": "path", + "description": "The name of the metadata template", "required": true, "schema": { "type": "string" - } + }, + "example": "properties" } ], "responses": { @@ -3727,33 +3723,31 @@ } } } - } + }, + "x-box-tag": "file_metadata", + "tags": [ + "Metadata instances (Files)" + ] }, "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-enable-explorer": false, "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "name": "scope", - "description": "The scope of the metadata template", - "example": "global", "in": "path", + "description": "The scope of the metadata template", "required": true, "schema": { "type": "string", @@ -3761,17 +3755,18 @@ "global", "enterprise" ] - } + }, + "example": "global" }, { "name": "template_key", - "description": "The name of the metadata template", - "example": "properties", "in": "path", + "description": "The name of the metadata template", "required": true, "schema": { "type": "string" - } + }, + "example": "properties" } ], "requestBody": { @@ -3849,32 +3844,32 @@ } } } - } + }, + "x-box-tag": "file_metadata", + "tags": [ + "Metadata instances (Files)" + ], + "x-box-enable-explorer": false }, "put": { "operationId": "put_files_id_metadata_id_id", "summary": "Update metadata instance on file", - "tags": [ - "Metadata instances (Files)" - ], - "x-box-tag": "file_metadata", "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "name": "scope", - "description": "The scope of the metadata template", - "example": "global", "in": "path", + "description": "The scope of the metadata template", "required": true, "schema": { "type": "string", @@ -3882,17 +3877,18 @@ "global", "enterprise" ] - } + }, + "example": "global" }, { "name": "template_key", - "description": "The name of the metadata template", - "example": "properties", "in": "path", + "description": "The name of the metadata template", "required": true, "schema": { "type": "string" - } + }, + "example": "properties" } ], "requestBody": { @@ -3907,6 +3903,7 @@ "type": "object", "properties": { "op": { + "description": "The type of change to perform on the template. Some\nof these are hazardous as they will change existing templates.", "type": "string", "example": "add", "enum": [ @@ -3916,23 +3913,22 @@ "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": { + "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.", "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." + "example": "/currentState" }, "value": { + "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.", "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." + "example": "reviewed" }, "from": { + "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).", "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)." + "example": "/nextState" } } } @@ -3981,32 +3977,31 @@ } } } - } + }, + "x-box-tag": "file_metadata", + "tags": [ + "Metadata instances (Files)" + ] }, "delete": { "operationId": "delete_files_id_metadata_id_id", "summary": "Remove metadata instance from file", - "tags": [ - "Metadata instances (Files)" - ], - "x-box-tag": "file_metadata", "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "name": "scope", - "description": "The scope of the metadata template", - "example": "global", "in": "path", + "description": "The scope of the metadata template", "required": true, "schema": { "type": "string", @@ -4014,17 +4009,18 @@ "global", "enterprise" ] - } + }, + "example": "global" }, { "name": "template_key", - "description": "The name of the metadata template", - "example": "properties", "in": "path", + "description": "The name of the metadata template", "required": true, "schema": { "type": "string" - } + }, + "example": "properties" } ], "responses": { @@ -4071,28 +4067,28 @@ } } } - } + }, + "x-box-tag": "file_metadata", + "tags": [ + "Metadata instances (Files)" + ] } }, "/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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "responses": { @@ -4116,26 +4112,26 @@ } } } - } + }, + "x-box-tag": "skills", + "tags": [ + "Skills" + ] }, "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "requestBody": { @@ -4143,13 +4139,10 @@ "application/json": { "schema": { "type": "object", - "required": [ - "cards" - ], "properties": { "cards": { - "type": "array", "description": "A list of Box Skill cards to apply to this file.", + "type": "array", "items": { "oneOf": [ { @@ -4167,7 +4160,10 @@ ] } } - } + }, + "required": [ + "cards" + ] } } } @@ -4223,26 +4219,26 @@ } } } - } + }, + "x-box-tag": "skills", + "tags": [ + "Skills" + ] }, "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "requestBody": { @@ -4256,16 +4252,16 @@ "description": "An operation that replaces an existing card.", "properties": { "op": { - "type": "string", "description": "`replace`", + "type": "string", "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.", + "type": "string", "example": "/cards/0" }, "value": { @@ -4328,26 +4324,26 @@ } } } - } + }, + "x-box-tag": "skills", + "tags": [ + "Skills" + ] }, "delete": { "operationId": "delete_files_id_metadata_global_boxSkillsCards", "summary": "Remove Box Skill cards from file", - "tags": [ - "Skills" - ], - "x-box-tag": "skills", "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "responses": { @@ -4384,28 +4380,28 @@ } } } - } + }, + "x-box-tag": "skills", + "tags": [ + "Skills" + ] } }, "/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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "responses": { @@ -4439,26 +4435,26 @@ } } } - } + }, + "x-box-tag": "file_watermarks", + "tags": [ + "Watermarks (Files)" + ] }, "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "requestBody": { @@ -4466,28 +4462,28 @@ "application/json": { "schema": { "type": "object", - "required": [ - "watermark" - ], "properties": { "watermark": { - "type": "object", "description": "The watermark to imprint on the file", - "required": [ - "imprint" - ], + "type": "object", "properties": { "imprint": { + "description": "The type of watermark to apply.\n\nCurrently only supports one option.", "type": "string", "example": "default", - "description": "The type of watermark to apply.\n\nCurrently only supports one option.", "enum": [ "default" ] } - } + }, + "required": [ + "imprint" + ] } - } + }, + "required": [ + "watermark" + ] } } } @@ -4523,26 +4519,26 @@ } } } - } + }, + "x-box-tag": "file_watermarks", + "tags": [ + "Watermarks (Files)" + ] }, "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "responses": { @@ -4569,28 +4565,28 @@ } } } - } + }, + "x-box-tag": "file_watermarks", + "tags": [ + "Watermarks (Files)" + ] } }, "/file_requests/{file_request_id}": { "get": { "operationId": "get_file_requests_id", "summary": "Get file request", - "tags": [ - "File requests" - ], - "x-box-tag": "file_requests", "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "123" } ], "responses": { @@ -4644,36 +4640,36 @@ } } } - } + }, + "x-box-tag": "file_requests", + "tags": [ + "File requests" + ] }, "put": { "operationId": "put_file_requests_id", "summary": "Update file request", - "tags": [ - "File requests" - ], - "x-box-tag": "file_requests", "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "123" }, { "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", + "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.", "required": false, - "example": "1", "schema": { "type": "string" - } + }, + "example": "1" } ], "requestBody": { @@ -4756,26 +4752,26 @@ } } } - } + }, + "x-box-tag": "file_requests", + "tags": [ + "File requests" + ] }, "delete": { "operationId": "delete_file_requests_id", "summary": "Delete file request", - "tags": [ - "File requests" - ], - "x-box-tag": "file_requests", "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "123" } ], "responses": { @@ -4822,28 +4818,28 @@ } } } - } + }, + "x-box-tag": "file_requests", + "tags": [ + "File requests" + ] } }, "/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", "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "123" } ], "requestBody": { @@ -4916,74 +4912,73 @@ } } } - } + }, + "x-box-tag": "file_requests", + "tags": [ + "File requests" + ] } }, "/folders/{folder_id}": { "get": { "operationId": "get_folders_id", "summary": "Get folder information", - "tags": [ - "Folders" - ], - "x-box-tag": "folders", "description": "Retrieves details for a folder, including the first 100 entries\nin the folder.\n\nPassing `sort`, `direction`, `offset`, and `limit`\nparameters in query allows you to manage the\nlist of returned\n[folder items](r://folder--full#param-item-collection).\n\nTo fetch more items within the folder, use the\n[Get items in a folder](e://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", + "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`.", "required": true, "schema": { "type": "string", "nullable": false - } + }, + "example": "12345" }, { "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`?fields=metadata.enterprise_12345.contractTemplate`.", "in": "query", - "example": [ - "id", - "type", - "name" - ], + "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`?fields=metadata.enterprise_12345.contractTemplate`.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false }, { "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", + "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.", "required": false, - "example": "1", "schema": { "type": "string" - } + }, + "example": "1" }, { "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", + "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.", "required": false, "schema": { "type": "string" - } + }, + "example": "shared_link=[link]&shared_link_password=[password]" }, { "name": "sort", - "description": "Defines the **second** attribute by which items\nare sorted.\n\nThe folder type affects the way the items\nare sorted:\n\n * **Standard folder**:\n Items are always sorted by\n their `type` first, with\n folders listed before files,\n and files listed\n before web links.\n\n * **Root folder**:\n This parameter is not supported\n for marker-based pagination\n on the root folder\n\n (the folder with an `id` of `0`).\n\n * **Shared folder with parent path\n to the associated folder visible to\n the collaborator**:\n Items are always sorted by\n their `type` first, with\n folders listed before files,\n and files listed\n before web links.", "in": "query", + "description": "Defines the **second** attribute by which items\nare sorted.\n\nThe folder type affects the way the items\nare sorted:\n\n * **Standard folder**:\n Items are always sorted by\n their `type` first, with\n folders listed before files,\n and files listed\n before web links.\n\n * **Root folder**:\n This parameter is not supported\n for marker-based pagination\n on the root folder\n\n (the folder with an `id` of `0`).\n\n * **Shared folder with parent path\n to the associated folder visible to\n the collaborator**:\n Items are always sorted by\n their `type` first, with\n folders listed before files,\n and files listed\n before web links.", "required": false, - "example": "id", "schema": { "type": "string", "enum": [ @@ -4992,45 +4987,46 @@ "date", "size" ] - } + }, + "example": "id" }, { "name": "direction", - "description": "The direction to sort results in. This can be either in alphabetical ascending\n(`ASC`) or descending (`DESC`) order.", "in": "query", + "description": "The direction to sort results in. This can be either in alphabetical ascending\n(`ASC`) or descending (`DESC`) order.", "required": false, - "example": "ASC", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] - } + }, + "example": "ASC" }, { "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", + "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.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 - } + }, + "example": 1000 }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 1000 } ], "responses": { @@ -5087,45 +5083,45 @@ } } } - } + }, + "x-box-tag": "folders", + "tags": [ + "Folders" + ] }, "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\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", + "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`.", "required": true, "schema": { "type": "string", "nullable": false - } + }, + "example": "12345" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "requestBody": { @@ -5136,8 +5132,8 @@ "properties": { "name": { "description": "An optional new name for the folder.", - "example": "Restored Photos", - "type": "string" + "type": "string", + "example": "Restored Photos" }, "parent": { "allOf": [ @@ -5146,8 +5142,8 @@ "description": "The parent for this item", "properties": { "id": { - "type": "string", "description": "The ID of parent item", + "type": "string", "example": "123" } } @@ -5213,55 +5209,55 @@ } } } - } + }, + "x-box-tag": "trashed_folders", + "tags": [ + "Trashed folders" + ] }, "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", "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", + "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`.", "required": true, "schema": { "type": "string", "nullable": false - } + }, + "example": "12345" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": 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", + "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.", "required": false, - "example": "1", "schema": { "type": "string" - } + }, + "example": "1" } ], "requestBody": { @@ -5271,40 +5267,40 @@ "type": "object", "properties": { "name": { - "type": "string", "description": "The optional new name for this folder.", + "type": "string", "example": "New Folder" }, "description": { - "type": "string", "description": "The optional description of this folder", - "maxLength": 256, + "type": "string", "example": "Legal contracts for the new ACME deal", + "maxLength": 256, "nullable": false }, "sync_state": { + "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.", "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" - ] + ], + "nullable": false }, "can_non_owners_invite": { + "description": "Specifies if users who are not the owner\nof the folder can invite new collaborators to the folder.", "type": "boolean", - "example": true, - "description": "Specifies if users who are not the owner\nof the folder can invite new collaborators to the folder." + "example": true }, "parent": { - "type": "object", "description": "The parent folder for this folder. Use this to move\nthe folder or to restore it out of the trash.", + "type": "object", "properties": { "id": { - "type": "string", "description": "The ID of the new parent folder", + "type": "string", "example": "0" } } @@ -5316,39 +5312,39 @@ "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.", + "type": "string", + "example": "open", "enum": [ "open", "company", "collaborators" - ], - "example": "open" + ] }, "password": { - "type": "string", - "nullable": true, "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\nPasswords must now be at least eight characters\nlong and include a number, upper case letter, or\na non-numeric or non-alphabetic character.\nA password can only be set when `access` is set to `open`.", - "example": "do-n8t-use-this-Password" + "type": "string", + "example": "do-n8t-use-this-Password", + "nullable": true }, "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.", + "type": "string", "example": "my-shared-link" }, "unshared_at": { + "description": "The timestamp at which this shared link will\nexpire. This field can only be set by\nusers with paid accounts.", "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." + "example": "2012-12-12T10:53:43-08:00" }, "permissions": { "type": "object", "properties": { "can_download": { + "description": "If the shared link allows for downloading of files.\nThis can only be set when `access` is set to\n`open` or `company`.", "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`." + "example": true } } } @@ -5360,7 +5356,6 @@ ] }, "folder_upload_email": { - "nullable": true, "allOf": [ { "title": "Folder upload email", @@ -5368,65 +5363,66 @@ "description": "The Write Folder Upload Email object", "properties": { "access": { + "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.", "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." + "nullable": false } } }, { "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." } - ] + ], + "nullable": true }, "tags": { + "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.", "type": "array", - "example": [ - "approved" - ], "items": { "type": "string" }, - "minItems": 1, + "example": [ + "approved" + ], "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." + "minItems": 1 }, "is_collaboration_restricted_to_enterprise": { + "description": "Specifies if new invites to this folder are restricted to users\nwithin the enterprise. This does not affect existing\ncollaborations.", "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." + "example": true }, "collections": { - "type": "array", - "nullable": true, "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]: e://get-collections", + "type": "array", "items": { "title": "Reference", "description": "The bare basic reference for an object", "type": "object", "properties": { "id": { - "type": "string", "description": "The unique identifier for this object", + "type": "string", "example": "11446498" }, "type": { - "type": "string", "description": "The type for this object", + "type": "string", "example": "file" } } - } + }, + "nullable": true }, "can_non_owners_view_collaborators": { + "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.", "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." + "example": true } } } @@ -5514,47 +5510,47 @@ } } } - } + }, + "x-box-tag": "folders", + "tags": [ + "Folders" + ] }, "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", "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", + "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`.", "required": true, "schema": { "type": "string", "nullable": false - } + }, + "example": "12345" }, { "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", + "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.", "required": false, - "example": "1", "schema": { "type": "string" - } + }, + "example": "1" }, { "name": "recursive", - "description": "Delete a folder that is not empty by recursively deleting the\nfolder and all of its content.", "in": "query", + "description": "Delete a folder that is not empty by recursively deleting the\nfolder and all of its content.", "required": false, - "example": true, "schema": { "type": "boolean" - } + }, + "example": true } ], "responses": { @@ -5631,7 +5627,11 @@ } } } - } + }, + "x-box-tag": "folders", + "tags": [ + "Folders" + ] } }, "/folders/{folder_id}/app_item_associations": { @@ -5639,54 +5639,50 @@ "operationId": "get_folders_id_app_item_associations", "summary": "List folder app item associations", "description": "**This is a beta feature, which means that its availability might be limited.**\nReturns all app items the folder is associated with. This includes app items\nassociated with ancestors of the folder. Assuming the context user has access\nto the folder, the type/ids are revealed even if the context user does not\nhave **View** permission on the app item.", - "tags": [ - "App item associations" - ], - "x-box-tag": "app_item_associations", "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", + "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`.", "required": true, "schema": { "type": "string", "nullable": false - } + }, + "example": "12345" }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "application_type", - "description": "If given, returns only app items for this application type", - "example": "hubs", "in": "query", + "description": "If given, returns only app items for this application type", "required": false, "schema": { "type": "string", "nullable": false - } + }, + "example": "hubs" } ], "responses": { @@ -5720,108 +5716,107 @@ } } } - } + }, + "x-box-tag": "app_item_associations", + "tags": [ + "App item associations" + ] } }, "/folders/{folder_id}/items": { "get": { "operationId": "get_folders_id_items", "summary": "List items in folder", - "tags": [ - "Folders" - ], - "x-box-tag": "folders", "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,\nuse 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", + "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`.", "required": true, "schema": { "type": "string", "nullable": false - } + }, + "example": "12345" }, { "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`?fields=metadata.enterprise_12345.contractTemplate`.", "in": "query", - "example": [ - "id", - "type", - "name" - ], + "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`?fields=metadata.enterprise_12345.contractTemplate`.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false }, { "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", + "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.", "required": false, - "example": true, "schema": { "type": "boolean" - } + }, + "example": true }, { "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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "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", + "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.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 - } + }, + "example": 1000 }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 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", + "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.", "required": false, "schema": { "type": "string" - } + }, + "example": "shared_link=[link]&shared_link_password=[password]" }, { "name": "sort", - "description": "Defines the **second** attribute by which items\nare sorted.\n\nThe folder type affects the way the items\nare sorted:\n\n * **Standard folder**:\n Items are always sorted by\n their `type` first, with\n folders listed before files,\n and files listed\n before web links.\n\n * **Root folder**:\n This parameter is not supported\n for marker-based pagination\n on the root folder\n\n (the folder with an `id` of `0`).\n\n * **Shared folder with parent path\n to the associated folder visible to\n the collaborator**:\n Items are always sorted by\n their `type` first, with\n folders listed before files,\n and files listed\n before web links.", "in": "query", + "description": "Defines the **second** attribute by which items\nare sorted.\n\nThe folder type affects the way the items\nare sorted:\n\n * **Standard folder**:\n Items are always sorted by\n their `type` first, with\n folders listed before files,\n and files listed\n before web links.\n\n * **Root folder**:\n This parameter is not supported\n for marker-based pagination\n on the root folder\n\n (the folder with an `id` of `0`).\n\n * **Shared folder with parent path\n to the associated folder visible to\n the collaborator**:\n Items are always sorted by\n their `type` first, with\n folders listed before files,\n and files listed\n before web links.", "required": false, - "example": "id", "schema": { "type": "string", "enum": [ @@ -5830,21 +5825,22 @@ "date", "size" ] - } + }, + "example": "id" }, { "name": "direction", - "description": "The direction to sort results in. This can be either in alphabetical ascending\n(`ASC`) or descending (`DESC`) order.", "in": "query", + "description": "The direction to sort results in. This can be either in alphabetical ascending\n(`ASC`) or descending (`DESC`) order.", "required": false, - "example": "ASC", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] - } + }, + "example": "ASC" } ], "responses": { @@ -5898,36 +5894,36 @@ } } } - } + }, + "x-box-tag": "folders", + "tags": [ + "Folders" + ] } }, "/folders": { "post": { "operationId": "post_folders", "summary": "Create folder", - "tags": [ - "Folders" - ], - "x-box-tag": "folders", "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "requestBody": { @@ -5935,31 +5931,27 @@ "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.", + "type": "string", "example": "New Folder", "maxLength": 255, "minLength": 1 }, "parent": { - "type": "object", "description": "The parent folder to create the new folder within.", - "required": [ - "id" - ], + "type": "object", "properties": { "id": { - "type": "string", "description": "The ID of parent folder", + "type": "string", "example": "0" } - } + }, + "required": [ + "id" + ] }, "folder_upload_email": { "allOf": [ @@ -5969,14 +5961,14 @@ "description": "The Write Folder Upload Email object", "properties": { "access": { + "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.", "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." + "nullable": false } } }, @@ -5986,17 +5978,21 @@ ] }, "sync_state": { + "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.", "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" - ] + ], + "nullable": false } - } + }, + "required": [ + "name", + "parent" + ] } } } @@ -6062,47 +6058,47 @@ } } } - } + }, + "x-box-tag": "folders", + "tags": [ + "Folders" + ] } }, "/folders/{folder_id}/copy": { "post": { "operationId": "post_folders_id_copy", "summary": "Copy folder", - "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", + "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.", "required": true, "schema": { "type": "string", "nullable": false - } + }, + "example": "0" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "requestBody": { @@ -6110,33 +6106,33 @@ "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.", + "type": "string", "example": "New Folder", "maxLength": 255, "minLength": 1 }, "parent": { - "type": "object", "description": "The destination folder to copy the folder to.", - "required": [ - "id" - ], + "type": "object", "properties": { "id": { - "type": "string", "description": "The ID of parent folder", + "type": "string", "example": "0" } - } + }, + "required": [ + "id" + ] } - } + }, + "nullable": false, + "required": [ + "parent" + ] } } } @@ -6215,7 +6211,11 @@ } } } - } + }, + "x-box-tag": "folders", + "tags": [ + "Folders" + ] } }, "/folders/{folder_id}/collaborations": { @@ -6223,39 +6223,35 @@ "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", + "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`.", "required": true, "schema": { "type": "string", "nullable": false - } + }, + "example": "12345" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "responses": { @@ -6279,47 +6275,47 @@ } } } - } + }, + "x-box-tag": "list_collaborations", + "tags": [ + "Collaborations (List)" + ] } }, "/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", + "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`.", "required": true, "schema": { "type": "string", "nullable": false - } + }, + "example": "12345" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "responses": { @@ -6353,27 +6349,27 @@ } } } - } + }, + "x-box-tag": "trashed_folders", + "tags": [ + "Trashed folders" + ] }, "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", + "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`.", "required": true, "schema": { "type": "string", "nullable": false - } + }, + "example": "12345" } ], "responses": { @@ -6400,29 +6396,29 @@ } } } - } + }, + "x-box-tag": "trashed_folders", + "tags": [ + "Trashed folders" + ] } }, "/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", "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", + "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`.", "required": true, "schema": { "type": "string", "nullable": false - } + }, + "example": "12345" } ], "responses": { @@ -6466,29 +6462,29 @@ } } } - } + }, + "x-box-tag": "folder_metadata", + "tags": [ + "Metadata instances (Folders)" + ] } }, "/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", "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", + "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`.", "required": true, "schema": { "type": "string", "nullable": false - } + }, + "example": "12345" } ], "responses": { @@ -6542,27 +6538,27 @@ } } } - } + }, + "x-box-tag": "folder_classifications", + "tags": [ + "Classifications on folders" + ] }, "post": { "operationId": "post_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo", "summary": "Add classification to folder", - "tags": [ - "Classifications on folders" - ], - "x-box-tag": "folder_classifications", "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", + "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`.", "required": true, "schema": { "type": "string", "nullable": false - } + }, + "example": "12345" } ], "requestBody": { @@ -6572,8 +6568,8 @@ "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.", + "type": "string", "example": "Sensitive" } } @@ -6632,36 +6628,33 @@ } } } - } + }, + "x-box-tag": "folder_classifications", + "tags": [ + "Classifications on folders" + ] }, "put": { "operationId": "put_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo", "summary": "Update classification on folder", - "tags": [ - "Classifications on folders" - ], - "x-box-tag": "folder_classifications", "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", + "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`.", "required": true, "schema": { "type": "string", "nullable": false - } + }, + "example": "12345" } ], "requestBody": { "content": { "application/json-patch+json": { "schema": { - "required": [ - "items" - ], "description": "A list containing the one change to make, to\nupdate the classification label.", "type": "array", "items": { @@ -6674,28 +6667,31 @@ ], "properties": { "op": { + "description": "`replace`", "type": "string", "example": "replace", - "description": "`replace`", "enum": [ "replace" ] }, "path": { + "description": "Defines classifications \navailable in the enterprise.", "type": "string", "example": "/Box__Security__Classification__Key", - "description": "Defines classifications \navailable in the enterprise.", "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.", + "type": "string", "example": "Sensitive" } } - } + }, + "required": [ + "items" + ] } } } @@ -6741,27 +6737,27 @@ } } } - } + }, + "x-box-tag": "folder_classifications", + "tags": [ + "Classifications on folders" + ] }, "delete": { "operationId": "delete_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo", "summary": "Remove classification from folder", - "tags": [ - "Classifications on folders" - ], - "x-box-tag": "folder_classifications", "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", + "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`.", "required": true, "schema": { "type": "string", "nullable": false - } + }, + "example": "12345" } ], "responses": { @@ -6808,35 +6804,34 @@ } } } - } + }, + "x-box-tag": "folder_classifications", + "tags": [ + "Classifications on folders" + ] } }, "/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", "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", + "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`.", "required": true, "schema": { "type": "string", "nullable": false - } + }, + "example": "12345" }, { "name": "scope", - "description": "The scope of the metadata template", - "example": "global", "in": "path", + "description": "The scope of the metadata template", "required": true, "schema": { "type": "string", @@ -6844,17 +6839,18 @@ "global", "enterprise" ] - } + }, + "example": "global" }, { "name": "template_key", - "description": "The name of the metadata template", - "example": "properties", "in": "path", + "description": "The name of the metadata template", "required": true, "schema": { "type": "string" - } + }, + "example": "properties" } ], "responses": { @@ -6908,34 +6904,32 @@ } } } - } + }, + "x-box-tag": "folder_metadata", + "tags": [ + "Metadata instances (Folders)" + ] }, "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-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", + "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`.", "required": true, "schema": { "type": "string", "nullable": false - } + }, + "example": "12345" }, { "name": "scope", - "description": "The scope of the metadata template", - "example": "global", "in": "path", + "description": "The scope of the metadata template", "required": true, "schema": { "type": "string", @@ -6943,17 +6937,18 @@ "global", "enterprise" ] - } + }, + "example": "global" }, { "name": "template_key", - "description": "The name of the metadata template", - "example": "properties", "in": "path", + "description": "The name of the metadata template", "required": true, "schema": { "type": "string" - } + }, + "example": "properties" } ], "requestBody": { @@ -7031,33 +7026,33 @@ } } } - } + }, + "x-box-tag": "folder_metadata", + "tags": [ + "Metadata instances (Folders)" + ], + "x-box-enable-explorer": false }, "put": { "operationId": "put_folders_id_metadata_id_id", "summary": "Update metadata instance on folder", - "tags": [ - "Metadata instances (Folders)" - ], - "x-box-tag": "folder_metadata", "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", + "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`.", "required": true, "schema": { "type": "string", "nullable": false - } + }, + "example": "12345" }, { "name": "scope", - "description": "The scope of the metadata template", - "example": "global", "in": "path", + "description": "The scope of the metadata template", "required": true, "schema": { "type": "string", @@ -7065,17 +7060,18 @@ "global", "enterprise" ] - } + }, + "example": "global" }, { "name": "template_key", - "description": "The name of the metadata template", - "example": "properties", "in": "path", + "description": "The name of the metadata template", "required": true, "schema": { "type": "string" - } + }, + "example": "properties" } ], "requestBody": { @@ -7090,6 +7086,7 @@ "type": "object", "properties": { "op": { + "description": "The type of change to perform on the template. Some\nof these are hazardous as they will change existing templates.", "type": "string", "example": "add", "enum": [ @@ -7099,23 +7096,22 @@ "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": { + "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.", "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." + "example": "/currentState" }, "value": { + "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.", "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." + "example": "reviewed" }, "from": { + "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).", "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)." + "example": "/nextState" } } } @@ -7164,33 +7160,32 @@ } } } - } + }, + "x-box-tag": "folder_metadata", + "tags": [ + "Metadata instances (Folders)" + ] }, "delete": { "operationId": "delete_folders_id_metadata_id_id", "summary": "Remove metadata instance from folder", - "tags": [ - "Metadata instances (Folders)" - ], - "x-box-tag": "folder_metadata", "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", + "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`.", "required": true, "schema": { "type": "string", "nullable": false - } + }, + "example": "12345" }, { "name": "scope", - "description": "The scope of the metadata template", - "example": "global", "in": "path", + "description": "The scope of the metadata template", "required": true, "schema": { "type": "string", @@ -7198,17 +7193,18 @@ "global", "enterprise" ] - } + }, + "example": "global" }, { "name": "template_key", - "description": "The name of the metadata template", - "example": "properties", "in": "path", + "description": "The name of the metadata template", "required": true, "schema": { "type": "string" - } + }, + "example": "properties" } ], "responses": { @@ -7255,101 +7251,100 @@ } } } - } + }, + "x-box-tag": "folder_metadata", + "tags": [ + "Metadata instances (Folders)" + ] } }, "/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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 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", + "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.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 - } + }, + "example": 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", + "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.", "required": false, - "example": true, "schema": { "type": "boolean" - } + }, + "example": true }, { "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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "direction", - "description": "The direction to sort results in. This can be either in alphabetical ascending\n(`ASC`) or descending (`DESC`) order.", "in": "query", + "description": "The direction to sort results in. This can be either in alphabetical ascending\n(`ASC`) or descending (`DESC`) order.", "required": false, - "example": "ASC", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] - } + }, + "example": "ASC" }, { "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", + "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.", "required": false, - "example": "name", "schema": { "type": "string", "enum": [ @@ -7357,7 +7352,8 @@ "date", "size" ] - } + }, + "example": "name" } ], "responses": { @@ -7391,29 +7387,29 @@ } } } - } + }, + "x-box-tag": "trashed_items", + "tags": [ + "Trashed items" + ] } }, "/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", + "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`.", "required": true, "schema": { "type": "string", "nullable": false - } + }, + "example": "12345" } ], "responses": { @@ -7447,27 +7443,27 @@ } } } - } + }, + "x-box-tag": "folder_watermarks", + "tags": [ + "Watermarks (Folders)" + ] }, "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", + "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`.", "required": true, "schema": { "type": "string", "nullable": false - } + }, + "example": "12345" } ], "requestBody": { @@ -7475,28 +7471,28 @@ "application/json": { "schema": { "type": "object", - "required": [ - "watermark" - ], "properties": { "watermark": { - "type": "object", "description": "The watermark to imprint on the folder", - "required": [ - "imprint" - ], + "type": "object", "properties": { "imprint": { + "description": "The type of watermark to apply.\n\nCurrently only supports one option.", "type": "string", "example": "default", - "description": "The type of watermark to apply.\n\nCurrently only supports one option.", "enum": [ "default" ] } - } + }, + "required": [ + "imprint" + ] } - } + }, + "required": [ + "watermark" + ] } } } @@ -7532,27 +7528,27 @@ } } } - } + }, + "x-box-tag": "folder_watermarks", + "tags": [ + "Watermarks (Folders)" + ] }, "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", + "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`.", "required": true, "schema": { "type": "string", "nullable": false - } + }, + "example": "12345" } ], "responses": { @@ -7579,29 +7575,29 @@ } } } - } + }, + "x-box-tag": "folder_watermarks", + "tags": [ + "Watermarks (Folders)" + ] } }, "/folder_locks": { "get": { "operationId": "get_folder_locks", "summary": "List folder locks", - "tags": [ - "Folder Locks" - ], - "x-box-tag": "folder_locks", "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", + "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`.", "required": true, "schema": { "type": "string", "nullable": false - } + }, + "example": "12345" } ], "responses": { @@ -7655,67 +7651,66 @@ } } } - } + }, + "x-box-tag": "folder_locks", + "tags": [ + "Folder Locks" + ] }, "post": { "operationId": "post_folder_locks", "summary": "Create folder lock", - "tags": [ - "Folder Locks" - ], - "x-box-tag": "folder_locks", - "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" - ], + "type": "object", "properties": { "move": { - "type": "boolean", "description": "Whether moving the folder should be locked.", + "type": "boolean", "example": true }, "delete": { - "type": "boolean", "description": "Whether deleting the folder should be locked.", - "example": true + "example": true, + "type": "boolean" } - } + }, + "required": [ + "move", + "delete" + ] }, "folder": { - "type": "object", "description": "The folder to apply the lock to.", - "required": [ - "type", - "id" - ], + "type": "object", "properties": { "type": { - "type": "string", "description": "The content type the lock is being applied to. Only `folder`\nis supported.", + "type": "string", "example": "folder" }, "id": { - "type": "string", "description": "The ID of the folder.", + "type": "string", "example": "1234567890" } - } + }, + "required": [ + "type", + "id" + ] } - } + }, + "required": [ + "folder" + ] } } } @@ -7761,7 +7756,12 @@ } } } - } + }, + "x-box-tag": "folder_locks", + "tags": [ + "Folder Locks" + ], + "x-box-enable-explorer": false } }, "/folder_locks/{folder_lock_id}": { @@ -7769,21 +7769,17 @@ "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", "parameters": [ { "name": "folder_lock_id", - "description": "The ID of the folder lock.", - "example": "12345", "in": "path", + "description": "The ID of the folder lock.", "required": true, "schema": { "type": "string", "nullable": false - } + }, + "example": "12345" } ], "responses": { @@ -7820,29 +7816,29 @@ } } } - } + }, + "x-box-tag": "folder_locks", + "tags": [ + "Folder Locks" + ] } }, "/metadata_templates": { "get": { "operationId": "get_metadata_templates", "summary": "Find metadata template by instance ID", - "tags": [ - "Metadata templates" - ], - "x-box-tag": "metadata_templates", "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", + "description": "The ID of an instance of the metadata template to find.", "required": true, "schema": { "type": "string", "format": "uuid" - } + }, + "example": "01234500-12f1-1234-aa12-b1d234cb567e" } ], "responses": { @@ -7876,17 +7872,17 @@ } } } - } + }, + "x-box-tag": "metadata_templates", + "tags": [ + "Metadata templates" + ] } }, "/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", "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": { @@ -7929,25 +7925,22 @@ } } } - } + }, + "x-box-tag": "classifications", + "tags": [ + "Classifications" + ] } }, "/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", "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": { "schema": { - "required": [ - "items" - ], "description": "An array that contains one or more classifications to add to\nthe enterprise's list of classifications.", "type": "array", "items": { @@ -7960,60 +7953,63 @@ ], "properties": { "op": { + "description": "The type of change to perform on the classification\nobject.", "type": "string", "example": "addEnumOption", - "description": "The type of change to perform on the classification\nobject.", "enum": [ "addEnumOption" ] }, "fieldKey": { + "description": "Defines classifications \navailable in the enterprise.", "type": "string", "example": "Box__Security__Classification__Key", - "description": "Defines classifications \navailable in the enterprise.", "enum": [ "Box__Security__Classification__Key" ] }, "data": { - "type": "object", - "required": [ - "key" - ], "description": "The details of the classification to add.", + "type": "object", "properties": { "key": { + "description": "The label of the classification as shown in the web and\nmobile interfaces. This is the only field required to\nadd a classification.", "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." + "example": "Sensitive" }, "staticConfig": { - "type": "object", "description": "A static configuration for the classification.", + "type": "object", "properties": { "classification": { - "type": "object", "description": "Additional details for the classification.", + "type": "object", "properties": { "classificationDefinition": { + "description": "A longer description of the classification.", "type": "string", - "example": "Sensitive information that must not be shared.", - "description": "A longer description of the classification." + "example": "Sensitive information that must not be shared." }, "colorID": { + "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", "type": "integer", "format": "int64", - "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" + "example": 4 } } } } } - } + }, + "required": [ + "key" + ] } } - } + }, + "required": [ + "items" + ] } } } @@ -8059,17 +8055,17 @@ } } } - } + }, + "x-box-tag": "classifications", + "tags": [ + "Classifications" + ] } }, "/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", "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": { @@ -8077,9 +8073,6 @@ "schema": { "description": "An array that contains one or more classifications to update.", "type": "array", - "required": [ - "items" - ], "items": { "type": "object", "description": "A single classification to update.", @@ -8091,65 +8084,68 @@ ], "properties": { "op": { + "description": "The type of change to perform on the classification\nobject.", "type": "string", "example": "editEnumOption", - "description": "The type of change to perform on the classification\nobject.", "enum": [ "editEnumOption" ] }, "fieldKey": { + "description": "Defines classifications \navailable in the enterprise.", "type": "string", "example": "Box__Security__Classification__Key", - "description": "Defines classifications \navailable in the enterprise.", "enum": [ "Box__Security__Classification__Key" ] }, "enumOptionKey": { + "description": "The original label of the classification to change.", "type": "string", - "example": "Sensitive", - "description": "The original label of the classification to change." + "example": "Sensitive" }, "data": { - "type": "object", - "required": [ - "key" - ], "description": "The details of the updated classification.", + "type": "object", "properties": { "key": { + "description": "A new label for the classification, as it will be\nshown in the web and mobile interfaces.", "type": "string", - "example": "Very Sensitive", - "description": "A new label for the classification, as it will be\nshown in the web and mobile interfaces." + "example": "Very Sensitive" }, "staticConfig": { - "type": "object", "description": "A static configuration for the classification.", + "type": "object", "properties": { "classification": { - "type": "object", "description": "Additional details for the classification.", + "type": "object", "properties": { "classificationDefinition": { + "description": "A longer description of the classification.", "type": "string", - "example": "Sensitive information that must not be shared.", - "description": "A longer description of the classification." + "example": "Sensitive information that must not be shared." }, "colorID": { + "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", "type": "integer", "format": "int64", - "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" + "example": 4 } } } } } - } + }, + "required": [ + "key" + ] } } - } + }, + "required": [ + "items" + ] } } } @@ -8195,24 +8191,23 @@ } } } - } + }, + "x-box-tag": "classifications", + "tags": [ + "Classifications" + ] } }, "/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", "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", + "description": "The scope of the metadata template", "required": true, "schema": { "type": "string", @@ -8220,17 +8215,18 @@ "global", "enterprise" ] - } + }, + "example": "global" }, { "name": "template_key", - "description": "The name of the metadata template", - "example": "properties", "in": "path", + "description": "The name of the metadata template", "required": true, "schema": { "type": "string" - } + }, + "example": "properties" } ], "responses": { @@ -8274,22 +8270,21 @@ } } } - } + }, + "x-box-tag": "metadata_templates", + "tags": [ + "Metadata templates" + ] }, "put": { "operationId": "put_metadata_templates_id_id_schema", - "tags": [ - "Metadata templates" - ], - "x-box-tag": "metadata_templates", "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", + "description": "The scope of the metadata template", "required": true, "schema": { "type": "string", @@ -8297,17 +8292,18 @@ "global", "enterprise" ] - } + }, + "example": "global" }, { "name": "template_key", - "description": "The name of the metadata template", - "example": "properties", "in": "path", + "description": "The name of the metadata template", "required": true, "schema": { "type": "string" - } + }, + "example": "properties" } ], "requestBody": { @@ -8325,6 +8321,7 @@ ], "properties": { "op": { + "description": "The type of change to perform on the template. Some\nof these are hazardous as they will change existing templates.", "type": "string", "example": "addEnumOption", "enum": [ @@ -8341,12 +8338,11 @@ "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.", + "type": "object", "example": { "name": "Aaron Levie" }, @@ -8364,11 +8360,12 @@ } }, "fieldKey": { + "description": "For operations that affect a single field this defines the key of\nthe field that is affected.", "type": "string", - "example": "category", - "description": "For operations that affect a single field this defines the key of\nthe field that is affected." + "example": "category" }, "fieldKeys": { + "description": "For operations that affect multiple fields this defines the keys\nof the fields that are affected.", "type": "array", "items": { "type": "string" @@ -8376,8 +8373,7 @@ "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.", @@ -8470,22 +8466,21 @@ } } } - } + }, + "x-box-tag": "metadata_templates", + "tags": [ + "Metadata templates" + ] }, "delete": { "operationId": "delete_metadata_templates_id_id_schema", "summary": "Remove metadata template", - "tags": [ - "Metadata templates" - ], - "x-box-tag": "metadata_templates", "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", + "description": "The scope of the metadata template", "required": true, "schema": { "type": "string", @@ -8493,17 +8488,18 @@ "global", "enterprise" ] - } + }, + "example": "global" }, { "name": "template_key", - "description": "The name of the metadata template", - "example": "properties", "in": "path", + "description": "The name of the metadata template", "required": true, "schema": { "type": "string" - } + }, + "example": "properties" } ], "responses": { @@ -8540,28 +8536,28 @@ } } } - } + }, + "x-box-tag": "metadata_templates", + "tags": [ + "Metadata templates" + ] } }, "/metadata_templates/{template_id}": { "get": { "operationId": "get_metadata_templates_id", "summary": "Get metadata template by ID", - "tags": [ - "Metadata templates" - ], - "x-box-tag": "metadata_templates", "description": "Retrieves a metadata template by its ID.", "parameters": [ { "name": "template_id", + "in": "path", + "description": "The ID of the template", + "required": true, "schema": { "type": "string" }, - "required": true, - "in": "path", - "example": "f7a9891f", - "description": "The ID of the template" + "example": "f7a9891f" } ], "responses": { @@ -8595,40 +8591,40 @@ } } } - } + }, + "x-box-tag": "metadata_templates", + "tags": [ + "Metadata templates" + ] } }, "/metadata_templates/global": { "get": { "operationId": "get_metadata_templates_global", "summary": "List all global metadata templates", - "tags": [ - "Metadata templates" - ], - "x-box-tag": "metadata_templates", "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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 1000 } ], "responses": { @@ -8662,40 +8658,40 @@ } } } - } + }, + "x-box-tag": "metadata_templates", + "tags": [ + "Metadata templates" + ] } }, "/metadata_templates/enterprise": { "get": { "operationId": "get_metadata_templates_enterprise", "summary": "List all metadata templates for enterprise", - "tags": [ - "Metadata templates" - ], - "x-box-tag": "metadata_templates", "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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 1000 } ], "responses": { @@ -8729,56 +8725,51 @@ } } } - } + }, + "x-box-tag": "metadata_templates", + "tags": [ + "Metadata templates" + ] } }, "/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, "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.", + "type": "string", "example": "enterprise" }, "templateKey": { + "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`.", "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" + "type": "string", + "example": "Product Info", + "maxLength": 4096 }, "hidden": { + "description": "Defines if this template is visible in the Box web app UI, or if\nit is purely intended for usage through the API.", "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.", + "type": "array", "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.", @@ -8790,9 +8781,9 @@ "type": "object", "properties": { "type": { + "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.", "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", @@ -8802,27 +8793,27 @@ ] }, "key": { + "description": "A unique identifier for the field. The identifier must\nbe unique within the template to which it belongs.", "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": { + "description": "The display name of the field as it is shown to the user in the web and\nmobile apps.", "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": { + "description": "A description of the field. This is not shown to the user.", "type": "string", "example": "The category", - "description": "A description of the field. This is not shown to the user.", "maxLength": 4096 }, "hidden": { + "description": "Whether this field is hidden in the UI for the user and can only be set\nthrough the API instead.", "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." + "example": true }, "options": { "description": "A list of options for this field. This is used in combination with the\n`enum` and `multiSelect` field types.", @@ -8837,8 +8828,8 @@ "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" + "type": "string", + "example": "Category 1" } } } @@ -8847,12 +8838,16 @@ } }, "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 + "type": "boolean", + "example": true, + "default": false } - } + }, + "required": [ + "scope", + "displayName" + ] } } } @@ -8898,67 +8893,62 @@ } } } - } + }, + "x-box-tag": "metadata_templates", + "tags": [ + "Metadata templates" + ], + "x-box-requires-admin": true } }, "/metadata_templates/schema#classifications": { "post": { "operationId": "post_metadata_templates_schema#classifications", "summary": "Add initial classifications", - "tags": [ - "Classifications" - ], - "x-box-tag": "classifications", "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", - "fields", - "templateKey" - ], "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.", + "type": "string", "example": "enterprise", "enum": [ "enterprise" ] }, "templateKey": { + "description": "Defines the list of metadata templates.", "type": "string", "example": "securityClassification-6VMVochwUWo", - "description": "Defines the list of metadata templates.", "enum": [ "securityClassification-6VMVochwUWo" ] }, "displayName": { - "type": "string", "description": "The name of the\ntemplate as shown in web and mobile interfaces.", + "type": "string", "example": "Classification", "enum": [ "Classification" ] }, "hidden": { + "description": "Determines if the classification template is\nhidden or available on web and mobile\ndevices.", "type": "boolean", - "example": false, - "description": "Determines if the classification template is\nhidden or available on web and mobile\ndevices." + "example": false }, "copyInstanceOnItemCopy": { + "description": "Determines if classifications are\ncopied along when the file or folder is\ncopied.", "type": "boolean", - "example": false, - "description": "Determines if classifications are\ncopied along when the file or folder is\ncopied." + "example": false }, "fields": { - "type": "array", "description": "The classification template requires exactly\none field, which holds\nall the valid classification values.", + "type": "array", "items": { "required": [ "type", @@ -8970,37 +8960,37 @@ "description": "The `enum` field which holds all the valid classification\nvalues.", "properties": { "type": { + "description": "The type of the field\nthat is always enum.", "type": "string", "example": "enum", - "description": "The type of the field\nthat is always enum.", "enum": [ "enum" ] }, "key": { + "description": "Defines classifications \navailable in the enterprise.", "type": "string", "example": "Box__Security__Classification__Key", - "description": "Defines classifications \navailable in the enterprise.", "enum": [ "Box__Security__Classification__Key" ] }, "displayName": { + "description": "A display name for the classification.", "type": "string", "example": "Classification", - "description": "A display name for the classification.", "enum": [ "Classification" ] }, "hidden": { + "description": "Determines if the classification\ntemplate is\nhidden or available on\nweb and mobile\ndevices.", "type": "boolean", - "example": false, - "description": "Determines if the classification\ntemplate is\nhidden or available on\nweb and mobile\ndevices." + "example": false }, "options": { - "type": "array", "description": "The actual list of classifications that are present on\nthis template.", + "type": "array", "items": { "required": [ "key" @@ -9009,28 +8999,28 @@ "description": "An individual classification.", "properties": { "key": { - "type": "string", "description": "The display name and key this classification. This\nwill be show in the Box UI.", + "type": "string", "example": "Sensitive" }, "staticConfig": { - "type": "object", "description": "Additional information about the classification.", + "type": "object", "properties": { "classification": { - "type": "object", "description": "Additional information about the classification.", + "type": "object", "properties": { "classificationDefinition": { + "description": "A longer description of the classification.", "type": "string", - "example": "Sensitive information", - "description": "A longer description of the classification." + "example": "Sensitive information" }, "colorID": { + "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", "type": "integer", "format": "int64", - "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" + "example": 4 } } } @@ -9042,7 +9032,13 @@ } } } - } + }, + "required": [ + "scope", + "displayName", + "fields", + "templateKey" + ] } } } @@ -9088,59 +9084,59 @@ } } } - } + }, + "x-box-tag": "classifications", + "tags": [ + "Classifications" + ] } }, "/metadata_cascade_policies": { "get": { "operationId": "get_metadata_cascade_policies", "summary": "List metadata cascade policies", - "tags": [ - "Metadata cascade policies" - ], - "x-box-tag": "metadata_cascade_policies", "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", + "description": "Specifies which folder to return policies for. This can not be used on the\nroot folder with ID `0`.", "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`." + "example": "31232" }, { "name": "owner_enterprise_id", "in": "query", + "description": "The ID of the enterprise ID for which to find metadata\ncascade policies. If not specified, it defaults to the\ncurrent enterprise.", "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." + "example": "31232" }, { "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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "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", + "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.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 - } + }, + "example": 1000 } ], "responses": { @@ -9194,47 +9190,47 @@ } } } - } + }, + "x-box-tag": "metadata_cascade_policies", + "tags": [ + "Metadata cascade policies" + ] }, "post": { "operationId": "post_metadata_cascade_policies", "summary": "Create metadata cascade policy", - "tags": [ - "Metadata cascade policies" - ], - "x-box-tag": "metadata_cascade_policies", "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.", + "type": "string", "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", + "example": "enterprise", "enum": [ "global", "enterprise" ] }, "templateKey": { + "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", "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" + "example": "productInfo" } - } + }, + "required": [ + "folder_id", + "scope", + "templateKey" + ] } } } @@ -9300,28 +9296,28 @@ } } } - } + }, + "x-box-tag": "metadata_cascade_policies", + "tags": [ + "Metadata cascade policies" + ] } }, "/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", "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", + "description": "The ID of the metadata cascade policy.", "required": true, "schema": { "type": "string" - } + }, + "example": "6fd4ff89-8fc1-42cf-8b29-1890dedd26d7" } ], "responses": { @@ -9355,26 +9351,26 @@ } } } - } + }, + "x-box-tag": "metadata_cascade_policies", + "tags": [ + "Metadata cascade policies" + ] }, "delete": { "operationId": "delete_metadata_cascade_policies_id", "summary": "Remove metadata cascade policy", - "tags": [ - "Metadata cascade policies" - ], - "x-box-tag": "metadata_cascade_policies", "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", + "description": "The ID of the metadata cascade policy.", "required": true, "schema": { "type": "string" - } + }, + "example": "6fd4ff89-8fc1-42cf-8b29-1890dedd26d7" } ], "responses": { @@ -9401,27 +9397,27 @@ } } } - } + }, + "x-box-tag": "metadata_cascade_policies", + "tags": [ + "Metadata cascade policies" + ] } }, "/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", "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", + "description": "The ID of the cascade policy to force-apply.", + "required": true, "schema": { "type": "string" }, - "description": "The ID of the cascade policy to force-apply.", "example": "6fd4ff89-8fc1-42cf-8b29-1890dedd26d7" } ], @@ -9430,20 +9426,20 @@ "application/json": { "schema": { "type": "object", - "required": [ - "conflict_resolution" - ], "properties": { "conflict_resolution": { + "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.", "type": "string", + "example": "none", "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" + ] } - } + }, + "required": [ + "conflict_resolution" + ] } } } @@ -9472,17 +9468,17 @@ } } } - } + }, + "x-box-tag": "metadata_cascade_policies", + "tags": [ + "Metadata cascade policies" + ] } }, "/metadata_queries/execute_read": { "post": { "operationId": "post_metadata_queries_execute_read", "summary": "Query files/folders by metadata", - "tags": [ - "Search" - ], - "x-box-tag": "search", "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": { @@ -9534,46 +9530,46 @@ } } } - } + }, + "x-box-tag": "search", + "tags": [ + "Search" + ] } }, "/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", + "description": "The ID of the comment.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "responses": { @@ -9597,44 +9593,44 @@ } } } - } + }, + "x-box-tag": "comments", + "tags": [ + "Comments" + ] }, "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", + "description": "The ID of the comment.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "requestBody": { @@ -9644,8 +9640,8 @@ "type": "object", "properties": { "message": { - "type": "string", "description": "The text of the comment to update", + "type": "string", "example": "Review completed!" } } @@ -9674,26 +9670,26 @@ } } } - } + }, + "x-box-tag": "comments", + "tags": [ + "Comments" + ] }, "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", + "description": "The ID of the comment.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "responses": { @@ -9710,37 +9706,36 @@ } } } - } + }, + "x-box-tag": "comments", + "tags": [ + "Comments" + ] } }, "/comments": { "post": { "operationId": "post_comments", - "tags": [ - "Comments" - ], - "x-box-tag": "comments", - "x-box-enable-explorer": false, "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "requestBody": { @@ -9748,46 +9743,46 @@ "application/json": { "schema": { "type": "object", - "required": [ - "message", - "item" - ], "properties": { "message": { - "type": "string", "description": "The text of the comment.\n\nTo mention a user, use the `tagged_message`\nparameter instead.", + "type": "string", "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.", + "type": "string", "example": "@[1234:John] Review completed!" }, "item": { - "type": "object", "description": "The item to attach the comment to.", - "required": [ - "id", - "type" - ], + "type": "object", "properties": { "id": { - "type": "string", "description": "The ID of the item", + "type": "string", "example": "11446498" }, "type": { - "type": "string", "description": "The type of the item that this comment will be placed on.", + "type": "string", "example": "file", "enum": [ "file", "comment" ] } - } + }, + "required": [ + "id", + "type" + ] } - } + }, + "required": [ + "message", + "item" + ] } } } @@ -9813,46 +9808,47 @@ } } } - } + }, + "x-box-tag": "comments", + "tags": [ + "Comments" + ], + "x-box-enable-explorer": false } }, "/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", + "description": "The ID of the collaboration", "required": true, - "example": "1234", "schema": { "type": "string" - } + }, + "example": "1234" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "responses": { @@ -9876,26 +9872,26 @@ } } } - } + }, + "x-box-tag": "user_collaborations", + "tags": [ + "Collaborations" + ] }, "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", + "description": "The ID of the collaboration", "required": true, - "example": "1234", "schema": { "type": "string" - } + }, + "example": "1234" } ], "requestBody": { @@ -9903,13 +9899,10 @@ "application/json": { "schema": { "type": "object", - "required": [ - "role" - ], "properties": { "role": { - "type": "string", "description": "The level of access granted.", + "type": "string", "example": "editor", "enum": [ "editor", @@ -9923,8 +9916,8 @@ ] }, "status": { - "type": "string", "description": "\nSet the status of a `pending` collaboration invitation,\neffectively accepting, or rejecting the invite.", + "type": "string", "example": "accepted", "enum": [ "pending", @@ -9933,17 +9926,20 @@ ] }, "expires_at": { + "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.", "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.", + "type": "boolean", "example": true } - } + }, + "required": [ + "role" + ] } } } @@ -9982,26 +9978,26 @@ } } } - } + }, + "x-box-tag": "user_collaborations", + "tags": [ + "Collaborations" + ] }, "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", + "description": "The ID of the collaboration", "required": true, - "example": "1234", "schema": { "type": "string" - } + }, + "example": "1234" } ], "responses": { @@ -10018,73 +10014,73 @@ } } } - } + }, + "x-box-tag": "user_collaborations", + "tags": [ + "Collaborations" + ] } }, "/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", + "description": "The status of the collaborations to retrieve", "required": true, - "example": "pending", "schema": { "type": "string", "enum": [ "pending" ] - } + }, + "example": "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false }, { "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", + "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.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 - } + }, + "example": 1000 }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 1000 } ], "responses": { @@ -10108,44 +10104,44 @@ } } } - } + }, + "x-box-tag": "list_collaborations", + "tags": [ + "Collaborations (List)" + ] }, "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false }, { "name": "notify", - "description": "Determines if users should receive email notification\nfor the action performed.", "in": "query", + "description": "Determines if users should receive email notification\nfor the action performed.", "required": false, - "example": true, "schema": { "type": "boolean" - } + }, + "example": true } ], "requestBody": { @@ -10153,19 +10149,14 @@ "application/json": { "schema": { "type": "object", - "required": [ - "item", - "accessible_by", - "role" - ], "properties": { "item": { - "type": "object", "description": "The item to attach the comment to.", + "type": "object", "properties": { "type": { - "type": "string", "description": "The type of the item that this collaboration will be\ngranted access to", + "type": "string", "example": "file", "enum": [ "file", @@ -10173,22 +10164,19 @@ ] }, "id": { - "type": "string", "description": "The ID of the item that will be granted access to", + "type": "string", "example": "11446498" } } }, "accessible_by": { - "type": "object", "description": "The user or group to give access to the item.", - "required": [ - "type" - ], + "type": "object", "properties": { "type": { - "type": "string", "description": "The type of collaborator to invite.", + "type": "string", "example": "user", "enum": [ "user", @@ -10196,20 +10184,23 @@ ] }, "id": { - "type": "string", "description": "The ID of the user or group.\n\nAlternatively, use `login` to specify a user by email\naddress.", + "type": "string", "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.", + "type": "string", "example": "john@example.com" } - } + }, + "required": [ + "type" + ] }, "role": { - "type": "string", "description": "The level of access granted.", + "type": "string", "example": "editor", "enum": [ "editor", @@ -10222,22 +10213,27 @@ ] }, "is_access_only": { + "description": "If set to `true`, collaborators have access to\nshared items, but such items won't be visible in the\nAll Files list. Additionally, collaborators won't\nsee the the path to the root folder for the\nshared item.", "type": "boolean", - "example": true, - "description": "If set to `true`, collaborators have access to\nshared items, but such items won't be visible in the\nAll Files list. Additionally, collaborators won't\nsee the the path to the root folder for the\nshared item." + "example": true }, "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.", + "type": "boolean", "example": true }, "expires_at": { + "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.", "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" } - } + }, + "required": [ + "item", + "accessible_by", + "role" + ] } } } @@ -10273,176 +10269,171 @@ } } } - } + }, + "x-box-tag": "user_collaborations", + "tags": [ + "Collaborations" + ] } }, "/search": { "get": { "operationId": "get_search", "summary": "Search for content", - "tags": [ - "Search" - ], - "x-box-tag": "search", "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", + "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.", "required": false, - "example": "sales", "schema": { "type": "string" - } + }, + "example": "sales" }, { "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", + "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.", "required": false, "schema": { "type": "string", + "default": "user_content", "enum": [ "user_content", "enterprise_content" - ], - "default": "user_content" + ] }, "example": "user_content" }, { "name": "file_extensions", + "in": "query", "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, "example": [ "pdf", "png", "gif" ], + "explode": false + }, + { + "name": "created_at_range", "in": "query", + "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.", "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" ], + "explode": false + }, + { + "name": "updated_at_range", "in": "query", + "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.", "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" ], + "explode": false + }, + { + "name": "size_range", "in": "query", + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { - "type": "string" + "type": "integer" } - } - }, - { - "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 ], + "explode": false + }, + { + "name": "owner_user_ids", "in": "query", + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { - "type": "integer" + "type": "string" } - } - }, - { - "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" ], + "explode": false + }, + { + "name": "recent_updater_user_ids", "in": "query", + "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.", "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" ], + "explode": false + }, + { + "name": "ancestor_folder_ids", "in": "query", + "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.", "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" - } - } + "explode": false }, { "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, + "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.", "required": false, "schema": { "type": "array", @@ -10456,13 +10447,17 @@ "tag" ] } - } + }, + "example": [ + "name", + "description" + ], + "explode": false }, { "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", + "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", "required": false, "schema": { "type": "string", @@ -10471,14 +10466,14 @@ "folder", "web_link" ] - } + }, + "example": "file" }, { "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", + "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.", "required": false, - "example": "non_trashed_only", "schema": { "type": "string", "default": "non_trashed_only", @@ -10487,12 +10482,22 @@ "trashed_only", "all_items" ] - } + }, + "example": "non_trashed_only" }, { "name": "mdfilters", - "description": "Limits the search results to any items for which the metadata matches the provided filter.\nThis parameter is a list that specifies exactly **one** metadata template used to filter the search results. \nThe parameter is required unless the `query` parameter is provided.", "in": "query", + "description": "Limits the search results to any items for which the metadata matches the provided filter.\nThis parameter is a list that specifies exactly **one** metadata template used to filter the search results. \nThe parameter is required unless the `query` parameter is provided.", + "required": false, + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/MetadataFilter" + }, + "maxItems": 1, + "minItems": 1 + }, "example": [ { "scope": "enterprise", @@ -10506,21 +10511,12 @@ } ] } - ], - "required": false, - "schema": { - "type": "array", - "minItems": 1, - "maxItems": 1, - "items": { - "$ref": "#/components/schemas/MetadataFilter" - } - } + ] }, { "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", + "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.", "required": false, "schema": { "type": "string", @@ -10534,8 +10530,8 @@ }, { "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", + "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.", "required": false, "schema": { "type": "string", @@ -10549,90 +10545,90 @@ }, { "name": "limit", - "description": "Defines the maximum number of items to return as part of a page of\nresults.", "in": "query", + "description": "Defines the maximum number of items to return as part of a page of\nresults.", "required": false, - "example": 100, "schema": { "type": "integer", "format": "int64", "default": 30, "maximum": 200 - } + }, + "example": 100 }, { "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", + "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)", "required": false, - "example": true, "schema": { "type": "boolean", "default": false - } + }, + "example": true }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false }, { "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", + "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.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 - } + }, + "example": 1000 }, { "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", + "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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "123422", + "23532", + "3241212" + ] }, { "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", + "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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "2014-05-15T13:35:01-07:00", + "2014-05-17T13:35:01-07:00" + ] } ], "responses": { @@ -10693,39 +10689,36 @@ } } } - } + }, + "x-box-tag": "search", + "tags": [ + "Search" + ] } }, "/tasks": { "post": { "operationId": "post_tasks", - "tags": [ - "Tasks" - ], "summary": "Create task", - "x-box-tag": "tasks", "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.", + "type": "object", "properties": { "id": { - "type": "string", "description": "The ID of the file", + "type": "string", "example": "11446498" }, "type": { - "type": "string", "description": "`file`", + "type": "string", "example": "file", "enum": [ "file" @@ -10734,8 +10727,8 @@ } }, "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", + "type": "string", "example": "review", "default": "review", "enum": [ @@ -10744,20 +10737,20 @@ ] }, "message": { - "type": "string", - "default": "", "description": "An optional message to include with the task.", - "example": "Please review" + "type": "string", + "example": "Please review", + "default": "" }, "due_at": { + "description": "Defines when the task is due. Defaults to `null` if not\nprovided.", "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.", + "type": "string", "example": "all_assignees", "default": "all_assignees", "enum": [ @@ -10765,7 +10758,10 @@ "any_assignee" ] } - } + }, + "required": [ + "item" + ] } } } @@ -10821,28 +10817,28 @@ } } } - } + }, + "x-box-tag": "tasks", + "tags": [ + "Tasks" + ] } }, "/tasks/{task_id}": { "get": { "operationId": "get_tasks_id", "summary": "Get task", - "tags": [ - "Tasks" - ], - "x-box-tag": "tasks", "description": "Retrieves information about a specific task.", "parameters": [ { "name": "task_id", - "description": "The ID of the task.", - "example": "12345", "in": "path", + "description": "The ID of the task.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "responses": { @@ -10876,26 +10872,26 @@ } } } - } + }, + "x-box-tag": "tasks", + "tags": [ + "Tasks" + ] }, "put": { "operationId": "put_tasks_id", - "tags": [ - "Tasks" - ], "summary": "Update task", - "x-box-tag": "tasks", "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", + "description": "The ID of the task.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "requestBody": { @@ -10905,8 +10901,8 @@ "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", + "type": "string", "example": "review", "enum": [ "review", @@ -10914,19 +10910,19 @@ ] }, "message": { - "type": "string", "description": "The message included with the task.", + "type": "string", "example": "Please review" }, "due_at": { + "description": "When the task is 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.", + "type": "string", "example": "all_assignees", "enum": [ "all_assignees", @@ -10989,26 +10985,26 @@ } } } - } + }, + "x-box-tag": "tasks", + "tags": [ + "Tasks" + ] }, "delete": { "operationId": "delete_tasks_id", - "tags": [ - "Tasks" - ], "summary": "Remove task", - "x-box-tag": "tasks", "description": "Removes a task from a file.", "parameters": [ { "name": "task_id", - "description": "The ID of the task.", - "example": "12345", "in": "path", + "description": "The ID of the task.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "responses": { @@ -11035,28 +11031,28 @@ } } } - } + }, + "x-box-tag": "tasks", + "tags": [ + "Tasks" + ] } }, "/tasks/{task_id}/assignments": { "get": { "operationId": "get_tasks_id_assignments", "summary": "List task assignments", - "tags": [ - "Task assignments" - ], - "x-box-tag": "task_assignments", "description": "Lists all of the assignments for a given task.", "parameters": [ { "name": "task_id", - "description": "The ID of the task.", - "example": "12345", "in": "path", + "description": "The ID of the task.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "responses": { @@ -11100,68 +11096,68 @@ } } } - } + }, + "x-box-tag": "task_assignments", + "tags": [ + "Task assignments" + ] } }, "/task_assignments": { "post": { "operationId": "post_task_assignments", "summary": "Assign task", - "tags": [ - "Task assignments" - ], - "x-box-tag": "task_assignments", "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" - ], + "type": "object", "properties": { "id": { - "type": "string", "description": "The ID of the task", + "type": "string", "example": "11446498" }, "type": { - "type": "string", "description": "The type of the item to assign.", + "type": "string", "example": "task", "enum": [ "task" ] } - } + }, + "required": [ + "id", + "type" + ] }, "assign_to": { - "type": "object", "description": "The user to assign the task to.", + "type": "object", "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.", + "type": "string", "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.", + "type": "string", "example": "john@example.com" } } } - } + }, + "required": [ + "task", + "assign_to" + ] } } } @@ -11217,28 +11213,28 @@ } } } - } + }, + "x-box-tag": "task_assignments", + "tags": [ + "Task assignments" + ] } }, "/task_assignments/{task_assignment_id}": { "get": { "operationId": "get_task_assignments_id", "summary": "Get task assignment", - "tags": [ - "Task assignments" - ], - "x-box-tag": "task_assignments", "description": "Retrieves information about a task assignment.", "parameters": [ { "name": "task_assignment_id", - "description": "The ID of the task assignment.", - "example": "12345", "in": "path", + "description": "The ID of the task assignment.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "responses": { @@ -11272,26 +11268,26 @@ } } } - } + }, + "x-box-tag": "task_assignments", + "tags": [ + "Task assignments" + ] }, "put": { "operationId": "put_task_assignments_id", "summary": "Update task assignment", - "tags": [ - "Task assignments" - ], - "x-box-tag": "task_assignments", "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", + "description": "The ID of the task assignment.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "requestBody": { @@ -11301,13 +11297,13 @@ "type": "object", "properties": { "message": { - "type": "string", "description": "An optional message by the assignee that can be added to the task.", + "type": "string", "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`.", + "type": "string", "example": "completed", "enum": [ "completed", @@ -11362,26 +11358,26 @@ } } } - } + }, + "x-box-tag": "task_assignments", + "tags": [ + "Task assignments" + ] }, "delete": { "operationId": "delete_task_assignments_id", "summary": "Unassign task", - "tags": [ - "Task assignments" - ], - "x-box-tag": "task_assignments", "description": "Deletes a specific task assignment.", "parameters": [ { "name": "task_assignment_id", - "description": "The ID of the task assignment.", - "example": "12345", "in": "path", + "description": "The ID of the task assignment.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "responses": { @@ -11408,56 +11404,56 @@ } } } - } + }, + "x-box-tag": "task_assignments", + "tags": [ + "Task assignments" + ] } }, "/shared_items": { "get": { "operationId": "get_shared_items", "summary": "Find file for shared link", - "tags": [ - "Shared links (Files)" - ], - "x-box-tag": "shared_links_files", "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", + "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.", "required": false, - "example": "1", "schema": { "type": "string" - } + }, + "example": "1" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false }, { "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", + "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]`", "required": true, "schema": { "type": "string" - } + }, + "example": "shared_link=[link]&shared_link_password=[password]" } ], "responses": { @@ -11484,38 +11480,38 @@ } } } - } + }, + "x-box-tag": "shared_links_files", + "tags": [ + "Shared links (Files)" + ] } }, "/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", "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "name": "fields", - "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", - "example": "shared_link", "in": "query", + "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "required": true, "schema": { "type": "string" - } + }, + "example": "shared_link" } ], "responses": { @@ -11596,38 +11592,38 @@ } } } - } + }, + "x-box-tag": "shared_links_files", + "tags": [ + "Shared links (Files)" + ] } }, "/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", "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "name": "fields", - "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", - "example": "shared_link", "in": "query", + "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "required": true, "schema": { "type": "string" - } + }, + "example": "shared_link" } ], "requestBody": { @@ -11641,50 +11637,50 @@ "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.", + "type": "string", + "example": "open", "enum": [ "open", "company", "collaborators" - ], - "example": "open" + ] }, "password": { - "type": "string", - "nullable": true, "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\nPasswords must now be at least eight characters\nlong and include a number, upper case letter, or\na non-numeric or non-alphabetic character.\nA password can only be set when `access` is set to `open`.", - "example": "do-n8t-use-this-Password" + "type": "string", + "example": "do-n8t-use-this-Password", + "nullable": true }, "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" + "type": "string", + "example": "my-shared-link", + "minLength": 12 }, "unshared_at": { + "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.", "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." + "example": "2012-12-12T10:53:43-08:00" }, "permissions": { "type": "object", "properties": { "can_download": { + "description": "If the shared link allows for downloading of files.\nThis can only be set when `access` is set to\n`open` or `company`.", "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`." + "example": true }, "can_preview": { + "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.", "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." + "example": true }, "can_edit": { + "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`.", "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`." + "example": true } } } @@ -11803,38 +11799,38 @@ } } } - } + }, + "x-box-tag": "shared_links_files", + "tags": [ + "Shared links (Files)" + ] } }, "/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", "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "name": "fields", - "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", - "example": "shared_link", "in": "query", + "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "required": true, "schema": { "type": "string" - } + }, + "example": "shared_link" } ], "requestBody": { @@ -11848,50 +11844,50 @@ "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.", + "type": "string", + "example": "open", "enum": [ "open", "company", "collaborators" - ], - "example": "open" + ] }, "password": { - "type": "string", - "nullable": true, "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\nPasswords must now be at least eight characters\nlong and include a number, upper case letter, or\na non-numeric or non-alphabetic character.\nA password can only be set when `access` is set to `open`.", - "example": "do-n8t-use-this-Password" + "type": "string", + "example": "do-n8t-use-this-Password", + "nullable": true }, "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" + "type": "string", + "example": "my-shared-link", + "minLength": 12 }, "unshared_at": { + "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.", "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." + "example": "2012-12-12T10:53:43-08:00" }, "permissions": { "type": "object", "properties": { "can_download": { + "description": "If the shared link allows for downloading of files.\nThis can only be set when `access` is set to\n`open` or `company`.", "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`." + "example": true }, "can_preview": { + "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.", "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." + "example": true }, "can_edit": { + "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`.", "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`." + "example": true } } } @@ -12010,38 +12006,38 @@ } } } - } + }, + "x-box-tag": "shared_links_files", + "tags": [ + "Shared links (Files)" + ] } }, "/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", "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", + "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`.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "name": "fields", - "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", - "example": "shared_link", "in": "query", + "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "required": true, "schema": { "type": "string" - } + }, + "example": "shared_link" } ], "requestBody": { @@ -12142,56 +12138,56 @@ } } } - } + }, + "x-box-tag": "shared_links_files", + "tags": [ + "Shared links (Files)" + ] } }, "/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", "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", + "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.", "required": false, - "example": "1", "schema": { "type": "string" - } + }, + "example": "1" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false }, { "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", + "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]`", "required": true, "schema": { "type": "string" - } + }, + "example": "shared_link=[link]&shared_link_password=[password]" } ], "responses": { @@ -12218,39 +12214,39 @@ } } } - } + }, + "x-box-tag": "shared_links_folders", + "tags": [ + "Shared links (Folders)" + ] } }, "/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", "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", + "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`.", "required": true, "schema": { "type": "string", "nullable": false - } + }, + "example": "12345" }, { "name": "fields", - "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", - "example": "shared_link", "in": "query", + "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "required": true, "schema": { "type": "string" - } + }, + "example": "shared_link" } ], "responses": { @@ -12331,39 +12327,39 @@ } } } - } + }, + "x-box-tag": "shared_links_folders", + "tags": [ + "Shared links (Folders)" + ] } }, "/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", "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", + "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`.", "required": true, "schema": { "type": "string", "nullable": false - } + }, + "example": "12345" }, { "name": "fields", - "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", - "example": "shared_link", "in": "query", + "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "required": true, "schema": { "type": "string" - } + }, + "example": "shared_link" } ], "requestBody": { @@ -12377,50 +12373,50 @@ "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.", + "type": "string", + "example": "open", "enum": [ "open", "company", "collaborators" - ], - "example": "open" + ] }, "password": { - "type": "string", - "nullable": true, "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\nPasswords must now be at least eight characters\nlong and include a number, upper case letter, or\na non-numeric or non-alphabetic character.\nA password can only be set when `access` is set to `open`.", - "example": "do-n8t-use-this-Password" + "type": "string", + "example": "do-n8t-use-this-Password", + "nullable": true }, "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" + "type": "string", + "example": "my-shared-link", + "minLength": 12 }, "unshared_at": { + "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.", "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." + "example": "2012-12-12T10:53:43-08:00" }, "permissions": { "type": "object", "properties": { "can_download": { + "description": "If the shared link allows for downloading of files.\nThis can only be set when `access` is set to\n`open` or `company`.", "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`." + "example": true }, "can_preview": { + "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.", "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." + "example": true }, "can_edit": { + "description": "This value can only be `false` for items\nwith a `type` of `folder`.", "type": "boolean", - "example": false, - "description": "This value can only be `false` for items\nwith a `type` of `folder`." + "example": false } } } @@ -12539,39 +12535,39 @@ } } } - } + }, + "x-box-tag": "shared_links_folders", + "tags": [ + "Shared links (Folders)" + ] } }, "/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", "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", + "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`.", "required": true, "schema": { "type": "string", "nullable": false - } + }, + "example": "12345" }, { "name": "fields", - "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", - "example": "shared_link", "in": "query", + "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "required": true, "schema": { "type": "string" - } + }, + "example": "shared_link" } ], "requestBody": { @@ -12585,49 +12581,49 @@ "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.", + "type": "string", + "example": "open", "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.\nPasswords must now be at least eight characters\nlong and include a number, upper case letter, or\na non-numeric or non-alphabetic character.\nA password can only be set when `access` is set to `open`.", + "type": "string", "example": "do-n8t-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" + "type": "string", + "example": "my-shared-link", + "minLength": 12 }, "unshared_at": { + "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.", "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." + "example": "2012-12-12T10:53:43-08:00" }, "permissions": { "type": "object", "properties": { "can_download": { + "description": "If the shared link allows for downloading of files.\nThis can only be set when `access` is set to\n`open` or `company`.", "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`." + "example": true }, "can_preview": { + "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.", "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." + "example": true }, "can_edit": { + "description": "This value can only be `false` for items\nwith a `type` of `folder`.", "type": "boolean", - "example": false, - "description": "This value can only be `false` for items\nwith a `type` of `folder`." + "example": false } } } @@ -12746,39 +12742,39 @@ } } } - } + }, + "x-box-tag": "shared_links_folders", + "tags": [ + "Shared links (Folders)" + ] } }, "/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", "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", + "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`.", "required": true, "schema": { "type": "string", "nullable": false - } + }, + "example": "12345" }, { "name": "fields", - "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", - "example": "shared_link", "in": "query", + "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "required": true, "schema": { "type": "string" - } + }, + "example": "shared_link" } ], "requestBody": { @@ -12879,58 +12875,58 @@ } } } - } + }, + "x-box-tag": "shared_links_folders", + "tags": [ + "Shared links (Folders)" + ] } }, "/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": { + "description": "The URL that this web link links to. Must start with\n`\"http://\"` or `\"https://\"`.", "type": "string", - "example": "https://box.com", - "description": "The URL that this web link links to. Must start with\n`\"http://\"` or `\"https://\"`." + "example": "https://box.com" }, "parent": { - "type": "object", "description": "The parent folder to create the web link within.", - "required": [ - "id" - ], + "type": "object", "properties": { "id": { - "type": "string", "description": "The ID of parent folder", + "type": "string", "example": "0" } - } + }, + "required": [ + "id" + ] }, "name": { + "description": "Name of the web link. Defaults to the URL if not set.", "type": "string", - "example": "Box Website", - "description": "Name of the web link. Defaults to the URL if not set." + "example": "Box Website" }, "description": { + "description": "Description of the web link.", "type": "string", - "example": "Cloud Content Management", - "description": "Description of the web link." + "example": "Cloud Content Management" } - } + }, + "required": [ + "parent", + "url" + ] } } } @@ -12956,38 +12952,38 @@ } } } - } + }, + "x-box-tag": "web_links", + "tags": [ + "Web links" + ] } }, "/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", + "description": "The ID of the web link.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "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", + "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.", "required": false, "schema": { "type": "string" - } + }, + "example": "shared_link=[link]&shared_link_password=[password]" } ], "responses": { @@ -13011,44 +13007,44 @@ } } } - } + }, + "x-box-tag": "web_links", + "tags": [ + "Web links" + ] }, "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", + "description": "The ID of the web link.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "requestBody": { @@ -13059,8 +13055,8 @@ "properties": { "name": { "description": "An optional new name for the web link.", - "example": "Restored.docx", - "type": "string" + "type": "string", + "example": "Restored.docx" }, "parent": { "allOf": [ @@ -13069,8 +13065,8 @@ "description": "The parent for this item", "properties": { "id": { - "type": "string", "description": "The ID of parent item", + "type": "string", "example": "123" } } @@ -13136,26 +13132,26 @@ } } } - } + }, + "x-box-tag": "trashed_web_links", + "tags": [ + "Trashed web links" + ] }, "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", + "description": "The ID of the web link.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "requestBody": { @@ -13165,9 +13161,9 @@ "type": "object", "properties": { "url": { + "description": "The new URL that the web link links to. Must start with\n`\"http://\"` or `\"https://\"`.", "type": "string", - "example": "https://box.com", - "description": "The new URL that the web link links to. Must start with\n`\"http://\"` or `\"https://\"`." + "example": "https://box.com" }, "parent": { "allOf": [ @@ -13176,8 +13172,8 @@ "description": "The parent for this item", "properties": { "id": { - "type": "string", "description": "The ID of parent item", + "type": "string", "example": "123" } } @@ -13188,46 +13184,46 @@ ] }, "name": { + "description": "A new name for the web link. Defaults to the URL if not set.", "type": "string", - "example": "Box Website", - "description": "A new name for the web link. Defaults to the URL if not set." + "example": "Box Website" }, "description": { + "description": "A new description of the web link.", "type": "string", - "example": "Cloud Content Management", - "description": "A new description of the web link." + "example": "Cloud Content Management" }, "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.", + "type": "string", + "example": "open", "enum": [ "open", "company", "collaborators" - ], - "example": "open" + ] }, "password": { - "type": "string", - "nullable": true, "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\nPasswords must now be at least eight characters\nlong and include a number, upper case letter, or\na non-numeric or non-alphabetic character.\nA password can only be set when `access` is set to `open`.", - "example": "do-not-use-this-password" + "type": "string", + "example": "do-not-use-this-password", + "nullable": true }, "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" + "type": "string", + "example": "my-shared-link", + "minLength": 12 }, "unshared_at": { + "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.", "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." + "example": "2012-12-12T10:53:43-08:00" } } } @@ -13257,26 +13253,26 @@ } } } - } + }, + "x-box-tag": "web_links", + "tags": [ + "Web links" + ] }, "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", + "description": "The ID of the web link.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "responses": { @@ -13293,46 +13289,46 @@ } } } - } + }, + "x-box-tag": "web_links", + "tags": [ + "Web links" + ] } }, "/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", + "description": "The ID of the web link.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "responses": { @@ -13366,26 +13362,26 @@ } } } - } + }, + "x-box-tag": "trashed_web_links", + "tags": [ + "Trashed web links" + ] }, "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", + "description": "The ID of the web link.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "responses": { @@ -13412,56 +13408,56 @@ } } } - } + }, + "x-box-tag": "trashed_web_links", + "tags": [ + "Trashed web links" + ] } }, "/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", "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", + "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.", "required": false, - "example": "1", "schema": { "type": "string" - } + }, + "example": "1" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false }, { "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", + "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]`", "required": true, "schema": { "type": "string" - } + }, + "example": "shared_link=[link]&shared_link_password=[password]" } ], "responses": { @@ -13488,38 +13484,38 @@ } } } - } + }, + "x-box-tag": "shared_links_web_links", + "tags": [ + "Shared links (Web Links)" + ] } }, "/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", "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", + "description": "The ID of the web link.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "name": "fields", - "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", - "example": "shared_link", "in": "query", + "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "required": true, "schema": { "type": "string" - } + }, + "example": "shared_link" } ], "responses": { @@ -13600,38 +13596,38 @@ } } } - } + }, + "x-box-tag": "shared_links_web_links", + "tags": [ + "Shared links (Web Links)" + ] } }, "/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", "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", + "description": "The ID of the web link.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "name": "fields", - "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", - "example": "shared_link", "in": "query", + "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "required": true, "schema": { "type": "string" - } + }, + "example": "shared_link" } ], "requestBody": { @@ -13645,50 +13641,50 @@ "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.", + "type": "string", + "example": "open", "enum": [ "open", "company", "collaborators" - ], - "example": "open" + ] }, "password": { - "type": "string", - "nullable": true, "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\nPasswords must now be at least eight characters\nlong and include a number, upper case letter, or\na non-numeric or non-alphabetic character.\nA password can only be set when `access` is set to `open`.", - "example": "do-n8t-use-this-Password" + "type": "string", + "example": "do-n8t-use-this-Password", + "nullable": true }, "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" + "type": "string", + "example": "my-shared-link", + "minLength": 12 }, "unshared_at": { + "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.", "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." + "example": "2012-12-12T10:53:43-08:00" }, "permissions": { "type": "object", "properties": { "can_download": { + "description": "If the shared link allows for downloading of files.\nThis can only be set when `access` is set to\n`open` or `company`.", "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`." + "example": true }, "can_preview": { + "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.", "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." + "example": true }, "can_edit": { + "description": "This value can only be `true` is `type` is `file`.", "type": "boolean", - "example": false, - "description": "This value can only be `true` is `type` is `file`." + "example": false } } } @@ -13807,38 +13803,38 @@ } } } - } + }, + "x-box-tag": "shared_links_web_links", + "tags": [ + "Shared links (Web Links)" + ] } }, "/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", "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", + "description": "The ID of the web link.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "name": "fields", - "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", - "example": "shared_link", "in": "query", + "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "required": true, "schema": { "type": "string" - } + }, + "example": "shared_link" } ], "requestBody": { @@ -13852,50 +13848,50 @@ "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.", + "type": "string", + "example": "open", "enum": [ "open", "company", "collaborators" - ], - "example": "open" + ] }, "password": { - "type": "string", - "nullable": true, "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\nPasswords must now be at least eight characters\nlong and include a number, upper case letter, or\na non-numeric or non-alphabetic character.\nA password can only be set when `access` is set to `open`.", - "example": "do-n8t-use-this-Password" + "type": "string", + "example": "do-n8t-use-this-Password", + "nullable": true }, "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" + "type": "string", + "example": "my-shared-link", + "minLength": 12 }, "unshared_at": { + "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.", "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." + "example": "2012-12-12T10:53:43-08:00" }, "permissions": { "type": "object", "properties": { "can_download": { + "description": "If the shared link allows for downloading of files.\nThis can only be set when `access` is set to\n`open` or `company`.", "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`." + "example": true }, "can_preview": { + "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.", "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." + "example": true }, "can_edit": { + "description": "This value can only be `true` is `type` is `file`.", "type": "boolean", - "example": true, - "description": "This value can only be `true` is `type` is `file`." + "example": true } } } @@ -14014,38 +14010,38 @@ } } } - } + }, + "x-box-tag": "shared_links_web_links", + "tags": [ + "Shared links (Web Links)" + ] } }, "/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", "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", + "description": "The ID of the web link.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "name": "fields", - "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", - "example": "shared_link", "in": "query", + "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "required": true, "schema": { "type": "string" - } + }, + "example": "shared_link" } ], "requestBody": { @@ -14146,35 +14142,34 @@ } } } - } + }, + "x-box-tag": "shared_links_web_links", + "tags": [ + "Shared links (Web Links)" + ] } }, "/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", + "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.", "required": false, - "example": "john", "schema": { "type": "string" - } + }, + "example": "john" }, { "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", + "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.", "required": false, - "example": "managed", "schema": { "type": "string", "enum": [ @@ -14182,79 +14177,80 @@ "managed", "external" ] - } + }, + "example": "managed" }, { "name": "external_app_user_id", "in": "query", + "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.", "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." + "example": "my-user-1234" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false }, { "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", + "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.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 - } + }, + "example": 1000 }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 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", + "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.", "required": false, - "example": true, "schema": { "type": "boolean" - } + }, + "example": true }, { "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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" } ], "responses": { @@ -14278,34 +14274,34 @@ } } } - } + }, + "x-box-tag": "users", + "tags": [ + "Users" + ] }, "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "requestBody": { @@ -14313,119 +14309,119 @@ "application/json": { "schema": { "type": "object", - "required": [ - "name" - ], "properties": { "name": { - "type": "string", "description": "The name of the user", + "type": "string", "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`.", + "type": "string", "example": "boss@box.com" }, "is_platform_access_only": { + "description": "Specifies that the user is an app user.", "type": "boolean", - "example": true, - "description": "Specifies that the user is an app user." + "example": true }, "role": { + "description": "The user’s enterprise role", "type": "string", + "example": "user", "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.", + "type": "string", "example": "en" }, "is_sync_enabled": { - "type": "boolean", "description": "Whether the user can use Box Sync", + "type": "boolean", "example": true }, "job_title": { - "type": "string", "description": "The user’s job title", - "maxLength": 100, - "example": "CEO" + "type": "string", + "example": "CEO", + "maxLength": 100 }, "phone": { - "type": "string", "description": "The user’s phone number", - "maxLength": 100, - "example": "6509241374" + "type": "string", + "example": "6509241374", + "maxLength": 100 }, "address": { - "type": "string", "description": "The user’s address", - "maxLength": 255, - "example": "900 Jefferson Ave, Redwood City, CA 94063" + "type": "string", + "example": "900 Jefferson Ave, Redwood City, CA 94063", + "maxLength": 255 }, "space_amount": { + "description": "The user’s total available space in bytes. Set this to `-1` to\nindicate unlimited storage.", "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": { + "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.", "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": { + "description": "Whether the user can see other enterprise users in their\ncontact list", "type": "boolean", - "example": true, - "description": "Whether the user can see other enterprise users in their\ncontact list" + "example": true }, "timezone": { + "description": "The user's timezone", "type": "string", "format": "timezone", - "description": "The user's timezone", "example": "Africa/Bujumbura" }, "is_external_collab_restricted": { + "description": "Whether the user is allowed to collaborate with users outside\ntheir enterprise", "type": "boolean", - "example": true, - "description": "Whether the user is allowed to collaborate with users outside\ntheir enterprise" + "example": true }, "is_exempt_from_device_limits": { + "description": "Whether to exempt the user from enterprise device limits", "type": "boolean", - "example": true, - "description": "Whether to exempt the user from enterprise device limits" + "example": true }, "is_exempt_from_login_verification": { + "description": "Whether the user must use two-factor authentication", "type": "boolean", - "example": true, - "description": "Whether the user must use two-factor authentication" + "example": true }, "status": { + "description": "The user's account status", "type": "string", + "example": "active", "enum": [ "active", "inactive", "cannot_delete_edit", "cannot_delete_edit_upload" - ], - "description": "The user's account status", - "example": "active" + ] }, "external_app_user_id": { + "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.", "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." + "example": "my-user-1234" } - } + }, + "required": [ + "name" + ] } } } @@ -14451,36 +14447,36 @@ } } } - } + }, + "x-box-tag": "users", + "tags": [ + "Users" + ] } }, "/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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "responses": { @@ -14504,51 +14500,51 @@ } } } - } + }, + "x-box-tag": "users", + "tags": [ + "Users" + ] } }, "/users/terminate_sessions": { "post": { "operationId": "post_users_terminate_sessions", "summary": "Create jobs to terminate users session", - "tags": [ - "Session termination" - ], - "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": { + "description": "A list of user IDs", + "type": "array", + "items": { + "type": "string" + }, "example": [ "123456", "456789" - ], + ] + }, + "user_logins": { + "description": "A list of user logins", "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" - } + ] } - } + }, + "required": [ + "user_ids", + "user_logins" + ] } } } @@ -14634,46 +14630,46 @@ } } } - } + }, + "x-box-tag": "session_termination", + "tags": [ + "Session termination" + ] } }, "/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", + "description": "The ID of the user.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "responses": { @@ -14697,44 +14693,44 @@ } } } - } + }, + "x-box-tag": "users", + "tags": [ + "Users" + ] }, "put": { "operationId": "put_users_id", "summary": "Update user", - "tags": [ - "Users" - ], - "x-box-tag": "users", "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", + "description": "The ID of the user.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "requestBody": { @@ -14744,135 +14740,135 @@ "type": "object", "properties": { "enterprise": { + "description": "Set this to `null` to roll the user out of the enterprise\nand make them a free user", "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" + "nullable": true }, "notify": { + "description": "Whether the user should receive an email when they\nare rolled out of an enterprise", "type": "boolean", - "example": true, - "description": "Whether the user should receive an email when they\nare rolled out of an enterprise" + "example": true }, "name": { - "type": "string", "description": "The name of the user", + "type": "string", "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.", + "type": "string", "example": "somename@box.com" }, "role": { + "description": "The user’s enterprise role", "type": "string", + "example": "user", "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.", + "type": "string", "example": "en" }, "is_sync_enabled": { - "type": "boolean", "description": "Whether the user can use Box Sync", + "type": "boolean", "example": true }, "job_title": { - "type": "string", "description": "The user’s job title", - "maxLength": 100, - "example": "CEO" + "type": "string", + "example": "CEO", + "maxLength": 100 }, "phone": { - "type": "string", "description": "The user’s phone number", - "maxLength": 100, - "example": "6509241374" + "type": "string", + "example": "6509241374", + "maxLength": 100 }, "address": { - "type": "string", "description": "The user’s address", - "maxLength": 255, - "example": "900 Jefferson Ave, Redwood City, CA 94063" + "type": "string", + "example": "900 Jefferson Ave, Redwood City, CA 94063", + "maxLength": 255 }, "tracking_codes": { + "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.", "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": { + "description": "Whether the user can see other enterprise users in their\ncontact list", "type": "boolean", - "example": true, - "description": "Whether the user can see other enterprise users in their\ncontact list" + "example": true }, "timezone": { + "description": "The user's timezone", "type": "string", "format": "timezone", - "description": "The user's timezone", "example": "Africa/Bujumbura" }, "is_external_collab_restricted": { + "description": "Whether the user is allowed to collaborate with users outside\ntheir enterprise", "type": "boolean", - "example": true, - "description": "Whether the user is allowed to collaborate with users outside\ntheir enterprise" + "example": true }, "is_exempt_from_device_limits": { + "description": "Whether to exempt the user from enterprise device limits", "type": "boolean", - "example": true, - "description": "Whether to exempt the user from enterprise device limits" + "example": true }, "is_exempt_from_login_verification": { + "description": "Whether the user must use two-factor authentication", "type": "boolean", - "example": true, - "description": "Whether the user must use two-factor authentication" + "example": true }, "is_password_reset_required": { + "description": "Whether the user is required to reset their password", "type": "boolean", - "example": true, - "description": "Whether the user is required to reset their password" + "example": true }, "status": { + "description": "The user's account status", "type": "string", + "example": "active", "enum": [ "active", "inactive", "cannot_delete_edit", "cannot_delete_edit_upload" - ], - "description": "The user's account status", - "example": "active" + ] }, "space_amount": { + "description": "The user’s total available space in bytes. Set this to `-1` to\nindicate unlimited storage.", "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": { + "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.", "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": { + "description": "The email address to send the notifications to.", "type": "string", - "example": "notifications@example.com", - "description": "The email address to send the notifications to." + "example": "notifications@example.com" } } }, "external_app_user_id": { + "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.", "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." + "example": "my-user-1234" } } } @@ -14920,44 +14916,44 @@ } } } - } + }, + "x-box-tag": "users", + "tags": [ + "Users" + ] }, "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", + "description": "The ID of the user.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "name": "notify", + "in": "query", + "description": "Whether the user will receive email notification of\nthe deletion", "schema": { "type": "boolean" }, - "in": "query", - "example": true, - "description": "Whether the user will receive email notification of\nthe deletion" + "example": true }, { "name": "force", + "in": "query", + "description": "Whether the user should be deleted even if this user\nstill own files", "schema": { "type": "boolean" }, - "in": "query", - "example": true, - "description": "Whether the user should be deleted even if this user\nstill own files" + "example": true } ], "responses": { @@ -14974,28 +14970,28 @@ } } } - } + }, + "x-box-tag": "users", + "tags": [ + "Users" + ] } }, "/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", + "description": "The ID of the user.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "responses": { @@ -15004,9 +15000,9 @@ "content": { "image/jpg": { "schema": { + "description": "The avatar", "type": "string", - "format": "binary", - "description": "The avatar" + "format": "binary" } } } @@ -15021,26 +15017,26 @@ } } } - } + }, + "x-box-tag": "avatars", + "tags": [ + "User avatars" + ] }, "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", + "description": "The ID of the user.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "requestBody": { @@ -15048,16 +15044,16 @@ "multipart/form-data": { "schema": { "type": "object", - "required": [ - "pic" - ], "properties": { "pic": { + "description": "The image file to be uploaded to Box.\nAccepted file extensions are `.jpg` or `.png`.\nThe maximum file size is 1MB.", "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." + "format": "binary" } - } + }, + "required": [ + "pic" + ] } } } @@ -15123,26 +15119,26 @@ } } } - } + }, + "x-box-tag": "avatars", + "tags": [ + "User avatars" + ] }, "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", + "description": "The ID of the user.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "responses": { @@ -15179,56 +15175,56 @@ } } } - } + }, + "x-box-tag": "avatars", + "tags": [ + "User avatars" + ] } }, "/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", + "description": "The ID of the user.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false }, { "name": "notify", - "description": "Determines if users should receive email notification\nfor the action performed.", "in": "query", + "description": "Determines if users should receive email notification\nfor the action performed.", "required": false, - "example": true, "schema": { "type": "boolean" - } + }, + "example": true } ], "requestBody": { @@ -15236,25 +15232,25 @@ "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" - ], + "type": "object", "properties": { "id": { + "description": "The ID of the user who the folder will be\ntransferred to", "type": "string", - "example": "1232234", - "description": "The ID of the user who the folder will be\ntransferred to" + "example": "1232234" } - } + }, + "required": [ + "id" + ] } - } + }, + "required": [ + "owned_by" + ] } } } @@ -15290,28 +15286,28 @@ } } } - } + }, + "x-box-tag": "transfer", + "tags": [ + "Transfer folders" + ] } }, "/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", + "description": "The ID of the user.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "responses": { @@ -15335,26 +15331,26 @@ } } } - } + }, + "x-box-tag": "email_aliases", + "tags": [ + "Email aliases" + ] }, "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", + "description": "The ID of the user.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "requestBody": { @@ -15362,16 +15358,16 @@ "application/json": { "schema": { "type": "object", - "required": [ - "email" - ], "properties": { "email": { + "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.", "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." + "example": "alias@example.com" } - } + }, + "required": [ + "email" + ] } } } @@ -15397,38 +15393,38 @@ } } } - } + }, + "x-box-tag": "email_aliases", + "tags": [ + "Email aliases" + ] } }, "/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", + "description": "The ID of the user.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "name": "email_alias_id", - "description": "The ID of the email alias.", - "example": "23432", "in": "path", + "description": "The ID of the email alias.", "required": true, "schema": { "type": "string" - } + }, + "example": "23432" } ], "responses": { @@ -15445,52 +15441,52 @@ } } } - } + }, + "x-box-tag": "email_aliases", + "tags": [ + "Email aliases" + ] } }, "/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", + "description": "The ID of the user.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 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", + "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.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 - } + }, + "example": 1000 } ], "responses": { @@ -15514,36 +15510,36 @@ } } } - } + }, + "x-box-tag": "memberships", + "tags": [ + "Group memberships" + ] } }, "/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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "requestBody": { @@ -15551,40 +15547,40 @@ "application/json": { "schema": { "type": "object", - "required": [ - "enterprise", - "actionable_by" - ], "properties": { "enterprise": { - "type": "object", "description": "The enterprise to invite the user to", - "required": [ - "id" - ], + "type": "object", "properties": { "id": { + "description": "The ID of the enterprise", "type": "string", - "example": "1232234", - "description": "The ID of the enterprise" + "example": "1232234" } - } + }, + "required": [ + "id" + ] }, "actionable_by": { - "type": "object", "description": "The user to invite", - "required": [ - "id" - ], + "type": "object", "properties": { "login": { + "description": "The login of the invited user", "type": "string", - "example": "john@example.com", - "description": "The login of the invited user" + "example": "john@example.com" } - } + }, + "required": [ + "id" + ] } - } + }, + "required": [ + "enterprise", + "actionable_by" + ] } } } @@ -15620,46 +15616,46 @@ } } } - } + }, + "x-box-tag": "invites", + "tags": [ + "Invites" + ] } }, "/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", + "description": "The ID of an invite.", "required": true, "schema": { "type": "string" - } + }, + "example": "213723" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "responses": { @@ -15683,70 +15679,70 @@ } } } - } + }, + "x-box-tag": "invites", + "tags": [ + "Invites" + ] } }, "/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", + "description": "Limits the results to only groups whose `name` starts\nwith the search term.", "required": false, - "example": "Engineering", "schema": { "type": "string" - } + }, + "example": "Engineering" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 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", + "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.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 - } + }, + "example": 1000 } ], "responses": { @@ -15770,34 +15766,34 @@ } } } - } + }, + "x-box-tag": "groups", + "tags": [ + "Groups" + ] }, "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "requestBody": { @@ -15805,36 +15801,33 @@ "application/json": { "schema": { "type": "object", - "required": [ - "name" - ], "properties": { "name": { + "description": "The name of the new group to be created. This name must be unique\nwithin the enterprise.", "type": "string", - "example": "Customer Support", - "description": "The name of the new group to be created. This name must be unique\nwithin the enterprise." + "example": "Customer Support" }, "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" + "type": "string", + "example": "Active Directory", + "maxLength": 255 }, "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.", + "type": "string", "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\"" + "type": "string", + "example": "\"Customer Support Group - as imported from Active Directory\"", + "maxLength": 255 }, "invitability_level": { + "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.", "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", @@ -15842,16 +15835,19 @@ ] }, "member_viewability_level": { + "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", "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" ] } - } + }, + "required": [ + "name" + ] } } } @@ -15887,39 +15883,39 @@ } } } - } + }, + "x-box-tag": "groups", + "tags": [ + "Groups" + ] } }, "/groups/terminate_sessions": { "post": { "operationId": "post_groups_terminate_sessions", "summary": "Create jobs to terminate user group session", - "tags": [ - "Session termination" - ], - "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", + "type": "array", "items": { "type": "string" - } + }, + "example": [ + "123456", + "456789" + ] } - } + }, + "required": [ + "group_ids" + ] } } } @@ -16005,46 +16001,46 @@ } } } - } + }, + "x-box-tag": "session_termination", + "tags": [ + "Session termination" + ] } }, "/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", + "description": "The ID of the group.", "required": true, "schema": { "type": "string" - } + }, + "example": "57645" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "responses": { @@ -16068,44 +16064,44 @@ } } } - } + }, + "x-box-tag": "groups", + "tags": [ + "Groups" + ] }, "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", + "description": "The ID of the group.", "required": true, "schema": { "type": "string" - } + }, + "example": "57645" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "requestBody": { @@ -16115,31 +16111,31 @@ "type": "object", "properties": { "name": { + "description": "The name of the new group to be created. Must be unique within the\nenterprise.", "type": "string", - "example": "Customer Support", - "description": "The name of the new group to be created. Must be unique within the\nenterprise." + "example": "Customer Support" }, "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" + "type": "string", + "example": "Active Directory", + "maxLength": 255 }, "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.", + "type": "string", "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\"" + "type": "string", + "example": "\"Customer Support Group - as imported from Active Directory\"", + "maxLength": 255 }, "invitability_level": { + "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.", "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", @@ -16147,9 +16143,9 @@ ] }, "member_viewability_level": { + "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", "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", @@ -16192,26 +16188,26 @@ } } } - } + }, + "x-box-tag": "groups", + "tags": [ + "Groups" + ] }, "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", + "description": "The ID of the group.", "required": true, "schema": { "type": "string" - } + }, + "example": "57645" } ], "responses": { @@ -16228,52 +16224,52 @@ } } } - } + }, + "x-box-tag": "groups", + "tags": [ + "Groups" + ] } }, "/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", + "description": "The ID of the group.", "required": true, "schema": { "type": "string" - } + }, + "example": "57645" }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 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", + "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.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 - } + }, + "example": 1000 } ], "responses": { @@ -16297,52 +16293,52 @@ } } } - } + }, + "x-box-tag": "memberships", + "tags": [ + "Group memberships" + ] } }, "/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", + "description": "The ID of the group.", "required": true, "schema": { "type": "string" - } + }, + "example": "57645" }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 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", + "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.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 - } + }, + "example": 1000 } ], "responses": { @@ -16366,36 +16362,36 @@ } } } - } + }, + "x-box-tag": "list_collaborations", + "tags": [ + "Collaborations (List)" + ] } }, "/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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "requestBody": { @@ -16403,63 +16399,63 @@ "application/json": { "schema": { "type": "object", - "required": [ - "user", - "group" - ], "properties": { "user": { - "type": "object", "description": "The user to add to the group.", - "required": [ - "id" - ], + "type": "object", "properties": { "id": { - "type": "string", "description": "The ID of the user to add to the group", + "type": "string", "example": "1434325" } - } + }, + "required": [ + "id" + ] }, "group": { - "type": "object", "description": "The group to add the user to.", - "required": [ - "id" - ], + "type": "object", "properties": { "id": { - "type": "string", "description": "The ID of the group to add the user to", + "type": "string", "example": "4545523" } - } + }, + "required": [ + "id" + ] }, "role": { + "description": "The role of the user in the group.", "type": "string", "example": "member", - "description": "The role of the user in the group.", "enum": [ "member", "admin" ] }, "configurable_permissions": { + "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.", "type": "object", - "nullable": true, "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" - } + }, + "nullable": true } - } + }, + "required": [ + "user", + "group" + ] } } } @@ -16495,46 +16491,46 @@ } } } - } + }, + "x-box-tag": "memberships", + "tags": [ + "Group memberships" + ] } }, "/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", + "description": "The ID of the group membership.", "required": true, "schema": { "type": "string" - } + }, + "example": "434534" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "responses": { @@ -16558,44 +16554,44 @@ } } } - } + }, + "x-box-tag": "memberships", + "tags": [ + "Group memberships" + ] }, "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", + "description": "The ID of the group membership.", "required": true, "schema": { "type": "string" - } + }, + "example": "434534" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "requestBody": { @@ -16605,27 +16601,27 @@ "type": "object", "properties": { "role": { + "description": "The role of the user in the group.", "type": "string", "example": "member", - "description": "The role of the user in the group.", "enum": [ "member", "admin" ] }, "configurable_permissions": { + "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.", "type": "object", - "nullable": true, "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" - } + }, + "nullable": true } } } @@ -16653,26 +16649,26 @@ } } } - } + }, + "x-box-tag": "memberships", + "tags": [ + "Group memberships" + ] }, "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", + "description": "The ID of the group membership.", "required": true, "schema": { "type": "string" - } + }, + "example": "434534" } ], "responses": { @@ -16689,40 +16685,40 @@ } } } - } + }, + "x-box-tag": "memberships", + "tags": [ + "Group memberships" + ] } }, "/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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 1000 } ], "responses": { @@ -16756,30 +16752,25 @@ } } } - } + }, + "x-box-tag": "webhooks", + "tags": [ + "Webhooks" + ] }, "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", + "type": "object", "properties": { "id": { "description": "The ID of the item to trigger a webhook", @@ -16798,16 +16789,13 @@ } }, "address": { + "description": "The URL that is notified by this webhook", "type": "string", - "example": "https://example.com/webhooks", - "description": "The URL that is notified by this webhook" + "example": "https://example.com/webhooks" }, "triggers": { - "type": "array", - "example": [ - "FILE.UPLOADED" - ], "description": "An array of event names that this webhook is\nto be triggered for", + "type": "array", "items": { "title": "Webhook Trigger", "example": "FILE.UPLOADED", @@ -16855,9 +16843,17 @@ "SIGN_REQUEST.EXPIRED", "SIGN_REQUEST.SIGNER_EMAIL_BOUNCED" ] - } + }, + "example": [ + "FILE.UPLOADED" + ] } - } + }, + "required": [ + "target", + "triggers", + "address" + ] } } } @@ -16923,28 +16919,28 @@ } } } - } + }, + "x-box-tag": "webhooks", + "tags": [ + "Webhooks" + ] } }, "/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", + "description": "The ID of the webhook.", "required": true, "schema": { "type": "string" - } + }, + "example": "3321123" } ], "responses": { @@ -16988,26 +16984,26 @@ } } } - } + }, + "x-box-tag": "webhooks", + "tags": [ + "Webhooks" + ] }, "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", + "description": "The ID of the webhook.", "required": true, "schema": { "type": "string" - } + }, + "example": "3321123" } ], "requestBody": { @@ -17017,8 +17013,8 @@ "type": "object", "properties": { "target": { - "type": "object", "description": "The item that will trigger the webhook", + "type": "object", "properties": { "id": { "description": "The ID of the item to trigger a webhook", @@ -17037,16 +17033,13 @@ } }, "address": { + "description": "The URL that is notified by this webhook", "type": "string", - "example": "https://example.com/webhooks", - "description": "The URL that is notified by this webhook" + "example": "https://example.com/webhooks" }, "triggers": { - "type": "array", - "example": [ - "FILE.UPLOADED" - ], "description": "An array of event names that this webhook is\nto be triggered for", + "type": "array", "items": { "title": "Webhook Trigger", "example": "FILE.UPLOADED", @@ -17094,7 +17087,10 @@ "SIGN_REQUEST.EXPIRED", "SIGN_REQUEST.SIGNER_EMAIL_BOUNCED" ] - } + }, + "example": [ + "FILE.UPLOADED" + ] } } } @@ -17162,26 +17158,26 @@ } } } - } + }, + "x-box-tag": "webhooks", + "tags": [ + "Webhooks" + ] }, "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", + "description": "The ID of the webhook.", "required": true, "schema": { "type": "string" - } + }, + "example": "3321123" } ], "responses": { @@ -17218,28 +17214,28 @@ } } } - } + }, + "x-box-tag": "webhooks", + "tags": [ + "Webhooks" + ] } }, "/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", + "description": "The ID of the skill to apply this metadata for.", "required": true, "schema": { "type": "string" - } + }, + "example": "33243242" } ], "requestBody": { @@ -17247,15 +17243,10 @@ "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.", + "type": "string", "example": "success", "enum": [ "invoked", @@ -17266,12 +17257,12 @@ ] }, "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.", + "type": "object", "properties": { "cards": { - "type": "array", "description": "A list of Box Skill cards to apply to this file.", + "type": "array", "items": { "oneOf": [ { @@ -17292,60 +17283,65 @@ } }, "file": { - "type": "object", "description": "The file to assign the cards to.", + "type": "object", "properties": { "type": { - "type": "string", "description": "`file`", + "type": "string", "example": "file", "enum": [ "file" ] }, "id": { - "type": "string", "description": "The ID of the file", + "type": "string", "example": "3243244" } } }, "file_version": { - "type": "object", "description": "The optional file version to assign the cards to.", + "type": "object", "properties": { "type": { - "type": "string", "description": "`file_version`", + "type": "string", "example": "file_version", "enum": [ "file_version" ] }, "id": { - "type": "string", "description": "The ID of the file version", + "type": "string", "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.", + "type": "object", "properties": { "unit": { + "description": "`file`", "type": "string", - "example": "file", - "description": "`file`" + "example": "file" }, "value": { + "description": "`1`", "type": "number", - "example": 1, - "description": "`1`" + "example": 1 } } } - } + }, + "required": [ + "status", + "metadata", + "file" + ] } } } @@ -17384,7 +17380,11 @@ } } } - } + }, + "x-box-tag": "skills", + "tags": [ + "Skills" + ] } }, "/events": { @@ -17422,17 +17422,12 @@ "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", + "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.", "schema": { "type": "string", "default": "all", @@ -17443,37 +17438,34 @@ "admin_logs", "admin_logs_streaming" ] - } + }, + "example": "all" }, { "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", + "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.", "schema": { "type": "string" - } + }, + "example": "1348790499819" }, { "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, + "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.", "schema": { "type": "integer", "format": "int64", "default": 100, "maximum": 500 - } + }, + "example": 50 }, { "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" - ], + "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.", "schema": { "type": "array", "items": { @@ -17595,28 +17587,32 @@ "WATERMARK_LABEL_DELETE" ] } - } + }, + "example": [ + "ACCESS_GRANTED" + ], + "explode": false }, { "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", + "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.", "schema": { "type": "string", "format": "date-time" - } + }, + "example": "2012-12-12T10:53:43-08:00" }, { "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", + "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.", "required": false, - "example": "2013-12-12T10:53:43-08:00", "schema": { "type": "string", "format": "date-time" - } + }, + "example": "2013-12-12T10:53:43-08:00" } ], "responses": { @@ -17640,60 +17636,60 @@ } } } - } + }, + "x-box-tag": "events", + "tags": [ + "Events" + ] } }, "/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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false }, { "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", + "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.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 - } + }, + "example": 1000 }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 1000 } ], "responses": { @@ -17717,70 +17713,70 @@ } } } - } + }, + "x-box-tag": "collections", + "tags": [ + "Collections" + ] } }, "/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", + "description": "The ID of the collection.", "required": true, "schema": { "type": "string" - } + }, + "example": "926489" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false }, { "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", + "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.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "default": 0 - } + }, + "example": 1000 }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 1000 } ], "responses": { @@ -17804,58 +17800,58 @@ } } } - } + }, + "x-box-tag": "collections", + "tags": [ + "Collections" + ] } }, "/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", "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" } ], "responses": { @@ -17879,92 +17875,92 @@ } } } - } + }, + "x-box-tag": "recent_items", + "tags": [ + "Recent items" + ] } }, "/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", + "description": "Filters results by a case sensitive prefix of the name of\nretention policies.", "required": false, - "example": "Sales Policy", "schema": { "type": "string" - } + }, + "example": "Sales Policy" }, { "name": "policy_type", - "description": "Filters results by the type of retention policy.", "in": "query", + "description": "Filters results by the type of retention policy.", "required": false, - "example": "finite", "schema": { "type": "string", "enum": [ "finite", "indefinite" ] - } + }, + "example": "finite" }, { "name": "created_by_user_id", - "description": "Filters results by the ID of the user who created policy.", - "example": "21312321", "in": "query", + "description": "Filters results by the ID of the user who created policy.", "required": false, "schema": { "type": "string" - } + }, + "example": "21312321" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 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", + "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" } ], "responses": { @@ -18008,56 +18004,53 @@ } } } - } + }, + "x-box-tag": "retention_policies", + "tags": [ + "Retention policies" + ] }, "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", + "type": "string", "example": "Some Policy Name" }, "description": { - "type": "string", "description": "The additional text description of the retention policy.", + "type": "string", "example": "Policy to retain all reports for at least one month" }, "policy_type": { + "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.", "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": { + "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.", "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": { + "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`.", + "example": "365", "oneOf": [ { "type": "string", @@ -18069,45 +18062,48 @@ "format": "int32", "nullable": false } - ], - "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`." + ] }, "retention_type": { + "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.", "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": { + "description": "Whether the owner of a file will be allowed to\nextend the retention.", "type": "boolean", + "example": true, "enum": [ true, false - ], - "example": true, - "description": "Whether the owner of a file will be allowed to\nextend the retention." + ] }, "are_owners_notified": { + "description": "Whether owner and co-owners of a file are notified\nwhen the policy nears expiration.", "type": "boolean", + "example": true, "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.", + "type": "array", "items": { "$ref": "#/components/schemas/User--Mini" } } - } + }, + "required": [ + "policy_name", + "policy_type", + "disposition_action" + ] } } } @@ -18153,46 +18149,46 @@ } } } - } + }, + "x-box-tag": "retention_policies", + "tags": [ + "Retention policies" + ] } }, "/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", + "description": "The ID of the retention policy.", "required": true, "schema": { "type": "string" - } + }, + "example": "982312" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "responses": { @@ -18216,26 +18212,26 @@ } } } - } + }, + "x-box-tag": "retention_policies", + "tags": [ + "Retention policies" + ] }, "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", + "description": "The ID of the retention policy.", "required": true, "schema": { "type": "string" - } + }, + "example": "982312" } ], "requestBody": { @@ -18245,18 +18241,20 @@ "type": "object", "properties": { "policy_name": { - "type": "string", "description": "The name for the retention policy", + "type": "string", "example": "Some Policy Name", "nullable": true }, "description": { - "type": "string", "description": "The additional text description of the retention policy.", + "type": "string", "example": "Policy to retain all reports for at least one month", "nullable": true }, "disposition_action": { + "description": "The disposition action of the retention policy.\nThis action can be `permanently_delete`, which\nwill cause the content retained by the policy\nto be permanently deleted, or `remove_retention`,\nwhich will lift the retention policy from the content,\nallowing it to be deleted by users,\nonce the retention policy has expired.\nYou can use `null` if you don't want to change `disposition_action`.", + "example": "permanently_delete", "anyOf": [ { "type": "string", @@ -18270,17 +18268,17 @@ "pattern": ".^", "nullable": true } - ], - "description": "The disposition action of the retention policy.\nThis action can be `permanently_delete`, which\nwill cause the content retained by the policy\nto be permanently deleted, or `remove_retention`,\nwhich will lift the retention policy from the content,\nallowing it to be deleted by users,\nonce the retention policy has expired.\nYou can use `null` if you don't want to change `disposition_action`.", - "example": "permanently_delete" + ] }, "retention_type": { + "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.", "type": "string", "example": "non-modifiable", - "nullable": true, - "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." + "nullable": true }, "retention_length": { + "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`.", + "example": "365", "oneOf": [ { "type": "string", @@ -18292,35 +18290,33 @@ "format": "int32", "nullable": false } - ], - "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": { + "description": "Used to retire a retention policy.\n\nIf not retiring a policy, do not include this parameter\nor set it to `null`.", "type": "string", "example": "retired", - "nullable": true, - "description": "Used to retire a retention policy.\n\nIf not retiring a policy, do not include this parameter\nor set it to `null`." + "nullable": true }, "can_owner_extend_retention": { - "type": "boolean", - "nullable": true, "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 + "type": "boolean", + "example": false, + "nullable": true }, "are_owners_notified": { - "type": "boolean", - "nullable": true, "description": "Determines if owners and co-owners of items\nunder the policy are notified when\nthe retention duration is about to end.", - "example": false + "type": "boolean", + "example": false, + "nullable": true }, "custom_notification_recipients": { - "type": "array", - "nullable": true, "description": "A list of users notified when the retention duration is about to end.", + "type": "array", "items": { "$ref": "#/components/schemas/User--Base" - } + }, + "nullable": true } } } @@ -18378,26 +18374,26 @@ } } } - } + }, + "x-box-tag": "retention_policies", + "tags": [ + "Retention policies" + ] }, "delete": { "operationId": "delete_retention_policies_id", "summary": "Delete retention policy", - "tags": [ - "Retention policies" - ], - "x-box-tag": "retention_policies", "description": "Permanently deletes a retention policy.", "parameters": [ { "name": "retention_policy_id", - "description": "The ID of the retention policy.", - "example": "982312", "in": "path", + "description": "The ID of the retention policy.", "required": true, "schema": { "type": "string" - } + }, + "example": "982312" } ], "responses": { @@ -18434,35 +18430,34 @@ } } } - } + }, + "x-box-tag": "retention_policies", + "tags": [ + "Retention policies" + ] } }, "/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", + "description": "The ID of the retention policy.", "required": true, "schema": { "type": "string" - } + }, + "example": "982312" }, { "name": "type", - "description": "The type of the retention policy assignment to retrieve.", "in": "query", + "description": "The type of the retention policy assignment to retrieve.", "required": false, - "example": "metadata_template", "schema": { "type": "string", "enum": [ @@ -18470,47 +18465,48 @@ "enterprise", "metadata_template" ] - } + }, + "example": "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false }, { "name": "marker", - "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.", "in": "query", + "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 1000 } ], "responses": { @@ -18544,43 +18540,36 @@ } } } - } + }, + "x-box-tag": "retention_policy_assignments", + "tags": [ + "Retention policy assignments" + ] } }, "/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", + "type": "string", "example": "173463" }, "assign_to": { - "type": "object", "description": "The item to assign the policy to", - "required": [ - "type" - ], + "type": "object", "properties": { "type": { - "type": "string", "description": "The type of item to assign the policy to.", + "type": "string", "example": "metadata_template", "enum": [ "enterprise", @@ -18589,27 +18578,30 @@ ] }, "id": { - "type": "string", - "nullable": true, "description": "The ID of item to assign the policy to.\nSet to `null` or omit when `type` is set to\n`enterprise`.", - "example": "6564564" + "type": "string", + "example": "6564564", + "nullable": true } - } + }, + "required": [ + "type" + ] }, "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.", + "type": "array", "items": { "type": "object", "properties": { "field": { - "type": "string", "description": "The metadata attribute key id.", + "type": "string", "example": "a0f4ee4e-1dc1-4h90-a8a9-aef55fc681d4" }, "value": { - "type": "string", "description": "The metadata attribute field id. For value, only\nenum and multiselect types are supported.", + "type": "string", "example": "0c27b756-0p87-4fe0-a43a-59fb661ccc4e" } } @@ -18620,7 +18612,11 @@ "type": "string", "example": "upload_date" } - } + }, + "required": [ + "policy_id", + "assign_to" + ] } } } @@ -18676,46 +18672,46 @@ } } } - } + }, + "x-box-tag": "retention_policy_assignments", + "tags": [ + "Retention policy assignments" + ] } }, "/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", + "description": "The ID of the retention policy assignment.", "required": true, "schema": { "type": "string" - } + }, + "example": "1233123" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "responses": { @@ -18739,26 +18735,26 @@ } } } - } + }, + "x-box-tag": "retention_policy_assignments", + "tags": [ + "Retention policy assignments" + ] }, "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", + "description": "The ID of the retention policy assignment.", "required": true, "schema": { "type": "string" - } + }, + "example": "1233123" } ], "responses": { @@ -18795,50 +18791,50 @@ } } } - } + }, + "x-box-tag": "retention_policy_assignments", + "tags": [ + "Retention policy assignments" + ] } }, "/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", + "description": "The ID of the retention policy assignment.", "required": true, "schema": { "type": "string" - } + }, + "example": "1233123" }, { "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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 1000 } ], "responses": { @@ -18872,50 +18868,50 @@ } } } - } + }, + "x-box-tag": "retention_policy_assignments", + "tags": [ + "Retention policy assignments" + ] } }, "/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", + "description": "The ID of the retention policy assignment.", "required": true, "schema": { "type": "string" - } + }, + "example": "1233123" }, { "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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 1000 } ], "responses": { @@ -18949,68 +18945,68 @@ } } } - } + }, + "x-box-tag": "retention_policy_assignments", + "tags": [ + "Retention policy assignments" + ] } }, "/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", + "description": "Limits results to policies for which the names start with\nthis search term. This is a case-insensitive prefix.", "required": false, "schema": { "type": "string" - } + }, + "example": "Sales Policy" }, { "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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false }, { "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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 1000 } ], "responses": { @@ -19034,57 +19030,57 @@ } } } - } + }, + "x-box-tag": "legal_hold_policies", + "tags": [ + "Legal hold policies" + ] }, "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", + "example": "Sales Policy", "maxLength": 254 }, "description": { "description": "A description for the policy.", - "example": "A custom policy for the sales team", "type": "string", + "example": "A custom policy for the sales team", "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" + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "maxLength": 500 }, "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" + "format": "date-time", + "example": "2012-12-18T10:53:43-08:00", + "maxLength": 500 }, "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" + "type": "boolean", + "example": true } - } + }, + "required": [ + "policy_name" + ] } } } @@ -19130,28 +19126,28 @@ } } } - } + }, + "x-box-tag": "legal_hold_policies", + "tags": [ + "Legal hold policies" + ] } }, "/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", + "description": "The ID of the legal hold policy", "required": true, "schema": { "type": "string" - } + }, + "example": "324432" } ], "responses": { @@ -19175,26 +19171,26 @@ } } } - } + }, + "x-box-tag": "legal_hold_policies", + "tags": [ + "Legal hold policies" + ] }, "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", + "description": "The ID of the legal hold policy", "required": true, "schema": { "type": "string" - } + }, + "example": "324432" } ], "requestBody": { @@ -19205,20 +19201,20 @@ "properties": { "policy_name": { "description": "The name of the policy.", - "example": "Sales Policy", "type": "string", + "example": "Sales Policy", "maxLength": 254 }, "description": { "description": "A description for the policy.", - "example": "A custom policy for the sales team", "type": "string", + "example": "A custom policy for the sales team", "maxLength": 500 }, "release_notes": { "description": "Notes around why the policy was released.", - "example": "Required for GDPR", "type": "string", + "example": "Required for GDPR", "maxLength": 500 } } @@ -19257,26 +19253,26 @@ } } } - } - }, - "delete": { - "operationId": "delete_legal_hold_policies_id", + }, "x-box-tag": "legal_hold_policies", "tags": [ "Legal hold policies" - ], + ] + }, + "delete": { + "operationId": "delete_legal_hold_policies_id", "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", + "description": "The ID of the legal hold policy", "required": true, "schema": { "type": "string" - } + }, + "example": "324432" } ], "responses": { @@ -19293,34 +19289,33 @@ } } } - } + }, + "x-box-tag": "legal_hold_policies", + "tags": [ + "Legal hold policies" + ] } }, "/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", + "description": "The ID of the legal hold policy", "required": true, "schema": { "type": "string" - } + }, + "example": "324432" }, { "name": "assign_to_type", - "description": "Filters the results by the type of item the\npolicy was applied to.", - "example": "file", "in": "query", + "description": "Filters the results by the type of item the\npolicy was applied to.", "schema": { "type": "string", "enum": [ @@ -19329,56 +19324,57 @@ "folder", "user" ] - } + }, + "example": "file" }, { "name": "assign_to_id", - "description": "Filters the results by the ID of item the\npolicy was applied to.", - "example": "1234323", "in": "query", + "description": "Filters the results by the ID of item the\npolicy was applied to.", "schema": { "type": "string" - } + }, + "example": "1234323" }, { "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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "responses": { @@ -19402,42 +19398,34 @@ } } } - } + }, + "x-box-tag": "legal_hold_policy_assignments", + "tags": [ + "Legal hold policy assignments" + ] }, "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" + "type": "string", + "example": "123244" }, "assign_to": { - "type": "object", "description": "The item to assign the policy to", - "required": [ - "type", - "id" - ], + "type": "object", "properties": { "type": { - "type": "string", "description": "The type of item to assign the policy to", + "type": "string", "example": "folder", "enum": [ "file", @@ -19447,13 +19435,21 @@ ] }, "id": { - "type": "string", "description": "The ID of item to assign the policy to", + "type": "string", "example": "6564564" } - } + }, + "required": [ + "type", + "id" + ] } - } + }, + "required": [ + "policy_id", + "assign_to" + ] } } } @@ -19479,28 +19475,28 @@ } } } - } + }, + "x-box-tag": "legal_hold_policy_assignments", + "tags": [ + "Legal hold policy assignments" + ] } }, "/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", + "description": "The ID of the legal hold policy assignment", "required": true, "schema": { "type": "string" - } + }, + "example": "753465" } ], "responses": { @@ -19524,26 +19520,26 @@ } } } - } - }, - "delete": { - "operationId": "delete_legal_hold_policy_assignments_id", + }, "x-box-tag": "legal_hold_policy_assignments", "tags": [ "Legal hold policy assignments" - ], + ] + }, + "delete": { + "operationId": "delete_legal_hold_policy_assignments_id", "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", + "description": "The ID of the legal hold policy assignment", "required": true, "schema": { "type": "string" - } + }, + "example": "753465" } ], "responses": { @@ -19560,68 +19556,68 @@ } } } - } + }, + "x-box-tag": "legal_hold_policy_assignments", + "tags": [ + "Legal hold policy assignments" + ] } }, "/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 files with 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 files with 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\nThis endpoint does not support returning any content that is on hold due to\na Custodian collaborating on a Hub.\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", + "description": "The ID of the legal hold policy assignment", "required": true, "schema": { "type": "string" - } + }, + "example": "753465" }, { "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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "responses": { @@ -19645,104 +19641,104 @@ } } } - } + }, + "x-box-tag": "legal_hold_policy_assignments", + "tags": [ + "Legal hold policy assignments" + ] } }, "/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.\n\n**Note**:\nFile retention API is now **deprecated**. \nTo get information about files and file versions under retention,\nsee [files under retention](e://get-retention-policy-assignments-id-files-under-retention) or [file versions under retention](e://get-retention-policy-assignments-id-file-versions-under-retention) endpoints.", "parameters": [ { "name": "file_id", - "description": "Filters results by files with this ID.", "in": "query", - "example": "43123123", + "description": "Filters results by files with this ID.", "required": false, "schema": { "type": "string" - } + }, + "example": "43123123" }, { "name": "file_version_id", - "description": "Filters results by file versions with this ID.", "in": "query", - "example": "1", + "description": "Filters results by file versions with this ID.", "required": false, "schema": { "type": "string" - } + }, + "example": "1" }, { "name": "policy_id", - "description": "Filters results by the retention policy with this ID.", "in": "query", + "description": "Filters results by the retention policy with this ID.", "required": false, - "example": "982312", "schema": { "type": "string" - } + }, + "example": "982312" }, { "name": "disposition_action", - "description": "Filters results by the retention policy with this disposition\naction.", "in": "query", + "description": "Filters results by the retention policy with this disposition\naction.", "required": false, - "example": "permanently_delete", "schema": { "type": "string", "enum": [ "permanently_delete", "remove_retention" ] - } + }, + "example": "permanently_delete" }, { "name": "disposition_before", - "description": "Filters results by files that will have their disposition\ncome into effect before this date.", "in": "query", + "description": "Filters results by files that will have their disposition\ncome into effect before this date.", "required": false, - "example": "2012-12-12T10:53:43-08:00", "schema": { "type": "string" - } + }, + "example": "2012-12-12T10:53:43-08:00" }, { "name": "disposition_after", - "description": "Filters results by files that will have their disposition\ncome into effect after this date.", "in": "query", + "description": "Filters results by files that will have their disposition\ncome into effect after this date.", "required": false, - "example": "2012-12-19T10:34:23-08:00", "schema": { "type": "string" - } + }, + "example": "2012-12-19T10:34:23-08:00" }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" } ], "responses": { @@ -19766,68 +19762,68 @@ } } } - } + }, + "x-box-tag": "file_version_retentions", + "tags": [ + "File version retentions" + ] } }, "/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\nThis endpoint does not support returning any content that is on hold due to\na Custodian collaborating on a Hub.\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", + "description": "The ID of the legal hold policy assignment", "required": true, "schema": { "type": "string" - } + }, + "example": "753465" }, { "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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false } ], "responses": { @@ -19851,28 +19847,28 @@ } } } - } + }, + "x-box-tag": "legal_hold_policy_assignments", + "tags": [ + "Legal hold policy assignments" + ] } }, "/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.\n\n**Note**:\nFile retention API is now **deprecated**. \nTo get information about files and file versions under retention,\nsee [files under retention](e://get-retention-policy-assignments-id-files-under-retention) or [file versions under retention](e://get-retention-policy-assignments-id-file-versions-under-retention) endpoints.", "parameters": [ { "name": "file_version_retention_id", - "description": "The ID of the file version retention", "in": "path", + "description": "The ID of the file version retention", "required": true, - "example": "3424234", "schema": { "type": "string" - } + }, + "example": "3424234" } ], "responses": { @@ -19896,28 +19892,28 @@ } } } - } + }, + "x-box-tag": "file_version_retentions", + "tags": [ + "File version retentions" + ] } }, "/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", + "description": "The ID of the file version legal hold", "required": true, - "example": "2348213", "schema": { "type": "string" - } + }, + "example": "2348213" } ], "responses": { @@ -19941,50 +19937,50 @@ } } } - } + }, + "x-box-tag": "file_version_legal_holds", + "tags": [ + "File version legal holds" + ] } }, "/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", + "description": "The ID of the legal hold policy to get the file version legal\nholds for.", "required": true, "schema": { "type": "string" - } + }, + "example": "133870" }, { "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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 1000 } ], "responses": { @@ -20008,28 +20004,28 @@ } } } - } + }, + "x-box-tag": "file_version_legal_holds", + "tags": [ + "File version legal holds" + ] } }, "/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", "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", + "description": "The ID of the shield information barrier.", "required": true, "schema": { "type": "string" - } + }, + "example": "1910967" } ], "responses": { @@ -20063,43 +20059,43 @@ } } } - } + }, + "x-box-tag": "shield_information_barriers", + "tags": [ + "Shield information barriers" + ] } }, "/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", "description": "Change status of shield information barrier with the specified ID.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", - "required": [ - "id", - "status" - ], "properties": { "id": { + "description": "The ID of the shield information barrier.", "type": "string", - "example": "1910967", - "description": "The ID of the shield information barrier." + "example": "1910967" }, "status": { + "description": "The desired status for the shield information barrier.", "type": "string", + "example": "pending", "enum": [ "pending", "disabled" - ], - "example": "pending", - "description": "The desired status for the shield information barrier." + ] } - } + }, + "required": [ + "id", + "status" + ] } } } @@ -20145,40 +20141,40 @@ } } } - } + }, + "x-box-tag": "shield_information_barriers", + "tags": [ + "Shield information barriers" + ] } }, "/shield_information_barriers": { "get": { "operationId": "get_shield_information_barriers", "summary": "List shield information barriers", - "tags": [ - "Shield information barriers" - ], - "x-box-tag": "shield_information_barriers", "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.", "in": "query", + "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 1000 } ], "responses": { @@ -20212,15 +20208,15 @@ } } } - } + }, + "x-box-tag": "shield_information_barriers", + "tags": [ + "Shield information barriers" + ] }, "post": { "operationId": "post_shield_information_barriers", "summary": "Create shield information barrier", - "tags": [ - "Shield information barriers" - ], - "x-box-tag": "shield_information_barriers", "description": "Creates a shield information barrier to\nseparate individuals/groups within the same\nfirm and prevents confidential information passing between them.", "requestBody": { "content": { @@ -20229,12 +20225,12 @@ "type": "object", "properties": { "enterprise": { + "description": "The `type` and `id` of enterprise this barrier is under.", "allOf": [ { "$ref": "#/components/schemas/Enterprise--Base" } - ], - "description": "The `type` and `id` of enterprise this barrier is under." + ] } }, "required": [ @@ -20275,50 +20271,50 @@ } } } - } + }, + "x-box-tag": "shield_information_barriers", + "tags": [ + "Shield information barriers" + ] } }, "/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", "description": "Lists shield information barrier reports.", "parameters": [ { "name": "shield_information_barrier_id", - "description": "The ID of the shield information barrier.", - "example": "1910967", "in": "query", + "description": "The ID of the shield information barrier.", "required": true, "schema": { "type": "string" - } + }, + "example": "1910967" }, { "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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 1000 } ], "responses": { @@ -20352,15 +20348,15 @@ } } } - } + }, + "x-box-tag": "shield_information_barrier_reports", + "tags": [ + "Shield information barrier reports" + ] }, "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", "description": "Creates a shield information barrier report for a given barrier.", "requestBody": { "content": { @@ -20412,28 +20408,28 @@ } } } - } + }, + "x-box-tag": "shield_information_barrier_reports", + "tags": [ + "Shield information barrier reports" + ] } }, "/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", "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", + "description": "The ID of the shield information barrier Report.", "required": true, "schema": { "type": "string" - } + }, + "example": "3423" } ], "responses": { @@ -20467,28 +20463,28 @@ } } } - } + }, + "x-box-tag": "shield_information_barrier_reports", + "tags": [ + "Shield information barrier reports" + ] } }, "/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", "description": "Retrieves shield information barrier segment based on provided ID..", "parameters": [ { "name": "shield_information_barrier_segment_id", + "in": "path", "description": "The ID of the shield information barrier segment.", - "example": "3423", "required": true, - "in": "path", "schema": { "type": "string" - } + }, + "example": "3423" } ], "responses": { @@ -20522,26 +20518,26 @@ } } } - } + }, + "x-box-tag": "shield_information_barrier_segments", + "tags": [ + "Shield information barrier segments" + ] }, "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", "description": "Deletes the shield information barrier segment\nbased on provided ID.", "parameters": [ { "name": "shield_information_barrier_segment_id", + "in": "path", "description": "The ID of the shield information barrier segment.", - "example": "3423", "required": true, - "in": "path", "schema": { "type": "string" - } + }, + "example": "3423" } ], "responses": { @@ -20568,46 +20564,46 @@ } } } - } + }, + "x-box-tag": "shield_information_barrier_segments", + "tags": [ + "Shield information barrier segments" + ] }, "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", "description": "Updates the shield information barrier segment based on provided ID..", "parameters": [ { "name": "shield_information_barrier_segment_id", + "in": "path", "description": "The ID of the shield information barrier segment.", - "example": "3423", "required": true, - "in": "path", "schema": { "type": "string" - } + }, + "example": "3423" } ], "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.", + "type": "object", "properties": { "name": { + "description": "The updated name for the shield information barrier segment.", "type": "string", - "pattern": "\\S+", "example": "Investment Banking", - "description": "The updated name for the shield information barrier segment." + "pattern": "\\S+" }, "description": { + "description": "The updated description for\nthe shield information barrier segment.", "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." + "nullable": true } } } @@ -20655,50 +20651,50 @@ } } } - } + }, + "x-box-tag": "shield_information_barrier_segments", + "tags": [ + "Shield information barrier segments" + ] } }, "/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", "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", + "description": "The ID of the shield information barrier.", "required": true, "schema": { "type": "string" - } + }, + "example": "1910967" }, { "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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 1000 } ], "responses": { @@ -20732,40 +20728,40 @@ } } } - } + }, + "x-box-tag": "shield_information_barrier_segments", + "tags": [ + "Shield information barrier segments" + ] }, "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", "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": { + "description": "Name of the shield information barrier segment", "type": "string", - "example": "Investment Banking", - "description": "Name of the shield information barrier segment" + "example": "Investment Banking" }, "description": { + "description": "Description of the shield information barrier segment", "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" + "example": "'Corporate division that engages in\n advisory_based financial\ntransactions on behalf of individuals,\ncorporations, and governments.'" } - } + }, + "required": [ + "shield_information_barrier", + "name" + ] } } } @@ -20811,28 +20807,28 @@ } } } - } + }, + "x-box-tag": "shield_information_barrier_segments", + "tags": [ + "Shield information barrier segments" + ] } }, "/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", "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", + "description": "The ID of the shield information barrier segment Member.", "required": true, "schema": { "type": "string" - } + }, + "example": "7815" } ], "responses": { @@ -20866,26 +20862,26 @@ } } } - } + }, + "x-box-tag": "shield_information_barrier_segment_members", + "tags": [ + "Shield information barrier segment members" + ] }, "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", "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", + "description": "The ID of the shield information barrier segment Member.", "required": true, "schema": { "type": "string" - } + }, + "example": "7815" } ], "responses": { @@ -20912,50 +20908,50 @@ } } } - } + }, + "x-box-tag": "shield_information_barrier_segment_members", + "tags": [ + "Shield information barrier segment members" + ] } }, "/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", "description": "Lists shield information barrier segment members\nbased on provided segment IDs.", "parameters": [ { "name": "shield_information_barrier_segment_id", + "in": "query", "description": "The ID of the shield information barrier segment.", - "example": "3423", "required": true, - "in": "query", "schema": { "type": "string" - } + }, + "example": "3423" }, { "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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 1000 } ], "responses": { @@ -20979,25 +20975,21 @@ } } } - } + }, + "x-box-tag": "shield_information_barrier_segment_members", + "tags": [ + "Shield information barrier segment members" + ] }, "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", "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.", @@ -21011,33 +21003,37 @@ "$ref": "#/components/schemas/ShieldInformationBarrier--Base" }, "shield_information_barrier_segment": { + "description": "The `type` and `id` of the\nrequested shield information barrier segment.", "type": "object", "properties": { "id": { + "description": "The ID reference of the\nrequesting shield information barrier segment.", "type": "string", - "example": "432554", - "description": "The ID reference of the\nrequesting shield information barrier segment." + "example": "432554" }, "type": { - "type": "string", "description": "The type of the shield barrier segment for this member.", + "type": "string", "example": "shield_information_barrier_segment", "enum": [ "shield_information_barrier_segment" ] } - }, - "description": "The `type` and `id` of the\nrequested shield information barrier segment." + } }, "user": { + "description": "User to which restriction will be applied.", "allOf": [ { "$ref": "#/components/schemas/User--Base" } - ], - "description": "User to which restriction will be applied." + ] } - } + }, + "required": [ + "shield_information_barrier_segment", + "user" + ] } } } @@ -21073,28 +21069,28 @@ } } } - } + }, + "x-box-tag": "shield_information_barrier_segment_members", + "tags": [ + "Shield information barrier segment members" + ] } }, "/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", "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", + "description": "The ID of the shield information barrier segment Restriction.", "required": true, "schema": { "type": "string" - } + }, + "example": "4563" } ], "responses": { @@ -21128,26 +21124,26 @@ } } } - } + }, + "x-box-tag": "shield_information_barrier_segment_restrictions", + "tags": [ + "Shield information barrier segment restrictions" + ] }, "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", "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", + "description": "The ID of the shield information barrier segment Restriction.", "required": true, "schema": { "type": "string" - } + }, + "example": "4563" } ], "responses": { @@ -21174,50 +21170,50 @@ } } } - } + }, + "x-box-tag": "shield_information_barrier_segment_restrictions", + "tags": [ + "Shield information barrier segment restrictions" + ] } }, "/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", "description": "Lists shield information barrier segment restrictions\nbased on provided segment ID.", "parameters": [ { "name": "shield_information_barrier_segment_id", + "in": "query", "description": "The ID of the shield information barrier segment.", - "example": "3423", "required": true, - "in": "query", "schema": { "type": "string" - } + }, + "example": "3423" }, { "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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 1000 } ], "responses": { @@ -21241,30 +21237,25 @@ } } } - } + }, + "x-box-tag": "shield_information_barrier_segment_restrictions", + "tags": [ + "Shield information barrier segment restrictions" + ] }, "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", "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.", + "type": "string", "example": "shield_information_barrier_segment_restriction", "enum": [ "shield_information_barrier_segment_restriction" @@ -21274,44 +21265,49 @@ "$ref": "#/components/schemas/ShieldInformationBarrier--Base" }, "shield_information_barrier_segment": { + "description": "The `type` and `id` of the requested\nshield information barrier segment.", "type": "object", "properties": { "id": { + "description": "The ID reference of the requesting\nshield information barrier segment.", "type": "string", - "example": "1910967", - "description": "The ID reference of the requesting\nshield information barrier segment." + "example": "1910967" }, "type": { - "type": "string", "description": "The type of the shield barrier segment for this member.", + "type": "string", "example": "shield_information_barrier_segment", "enum": [ "shield_information_barrier_segment" ] } - }, - "description": "The `type` and `id` of the requested\nshield information barrier segment." + } }, "restricted_segment": { + "description": "The `type` and `id` of the restricted\nshield information barrier segment.", "type": "object", "properties": { "id": { + "description": "The ID reference of the restricted\nshield information barrier segment.", "type": "string", - "example": "1910967", - "description": "The ID reference of the restricted\nshield information barrier segment." + "example": "1910967" }, "type": { + "description": "The type of the restricted shield\ninformation barrier segment.", "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." + } } - } + }, + "required": [ + "type", + "shield_information_barrier_segment", + "restricted_segment" + ] } } } @@ -21347,28 +21343,28 @@ } } } - } + }, + "x-box-tag": "shield_information_barrier_segment_restrictions", + "tags": [ + "Shield information barrier segment restrictions" + ] } }, "/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", + "description": "The ID of the device pin", "required": true, - "example": "2324234", "schema": { "type": "string" - } + }, + "example": "2324234" } ], "responses": { @@ -21392,26 +21388,26 @@ } } } - } + }, + "x-box-tag": "device_pinners", + "tags": [ + "Device pinners" + ] }, "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", + "description": "The ID of the device pin", "required": true, - "example": "2324234", "schema": { "type": "string" - } + }, + "example": "2324234" } ], "responses": { @@ -21428,64 +21424,64 @@ } } } - } + }, + "x-box-tag": "device_pinners", + "tags": [ + "Device pinners" + ] } }, "/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", + "description": "The ID of the enterprise", "required": true, - "example": "3442311", "schema": { "type": "string" - } + }, + "example": "3442311" }, { "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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 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", + "description": "The direction to sort results in. This can be either in alphabetical ascending\n(`ASC`) or descending (`DESC`) order.", "required": false, - "example": "ASC", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] - } + }, + "example": "ASC" } ], "responses": { @@ -21509,32 +21505,32 @@ } } } - } + }, + "x-box-tag": "device_pinners", + "tags": [ + "Device pinners" + ] } }, "/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", + "description": "Limits the results to the terms of service of the given type.", "required": false, - "example": "managed", "schema": { "type": "string", "enum": [ "external", "managed" ] - } + }, + "example": "managed" } ], "responses": { @@ -21558,30 +21554,26 @@ } } } - } + }, + "x-box-tag": "terms_of_services", + "tags": [ + "Terms of service" + ] }, "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", + "example": "enabled", "enum": [ "enabled", "disabled" @@ -21589,8 +21581,8 @@ }, "tos_type": { "description": "The type of user to set the terms of\nservice for.", - "example": "managed", "type": "string", + "example": "managed", "enum": [ "external", "managed" @@ -21598,10 +21590,14 @@ }, "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" + "type": "string", + "example": "By collaborating on this file you are accepting..." } - } + }, + "required": [ + "status", + "text" + ] } } } @@ -21627,28 +21623,28 @@ } } } - } + }, + "x-box-tag": "terms_of_services", + "tags": [ + "Terms of service" + ] } }, "/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", + "description": "The ID of the terms of service.", "required": true, "schema": { "type": "string" - } + }, + "example": "324234" } ], "responses": { @@ -21672,26 +21668,26 @@ } } } - } + }, + "x-box-tag": "terms_of_services", + "tags": [ + "Terms of service" + ] }, "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", + "description": "The ID of the terms of service.", "required": true, "schema": { "type": "string" - } + }, + "example": "324234" } ], "requestBody": { @@ -21699,15 +21695,11 @@ "application/json": { "schema": { "type": "object", - "required": [ - "status", - "text" - ], "properties": { "status": { "description": "Whether this terms of service is active.", - "example": "enabled", "type": "string", + "example": "enabled", "enum": [ "enabled", "disabled" @@ -21715,10 +21707,14 @@ }, "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" + "type": "string", + "example": "By collaborating on this file you are accepting..." } - } + }, + "required": [ + "status", + "text" + ] } } } @@ -21744,38 +21740,38 @@ } } } - } + }, + "x-box-tag": "terms_of_services", + "tags": [ + "Terms of service" + ] } }, "/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", + "description": "The ID of the terms of service.", "required": true, "schema": { "type": "string" - } + }, + "example": "324234" }, { "name": "user_id", - "description": "Limits results to the given user ID.", - "example": "123334", "in": "query", + "description": "Limits results to the given user ID.", "required": false, "schema": { "type": "string" - } + }, + "example": "123334" } ], "responses": { @@ -21799,79 +21795,79 @@ } } } - } + }, + "x-box-tag": "terms_of_service_user_statuses", + "tags": [ + "Terms of service user statuses" + ] }, "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" - ], + "type": "object", "properties": { "type": { - "type": "string", "description": "The type of object.", + "type": "string", "example": "terms_of_service", "enum": [ "terms_of_service" ] }, "id": { - "type": "string", "description": "The ID of terms of service", + "type": "string", "example": "1232132" } - } - }, - "user": { - "type": "object", - "description": "The user to set the status for.", + }, "required": [ "id", "type" - ], + ] + }, + "user": { + "description": "The user to set the status for.", + "type": "object", "properties": { "type": { - "type": "string", "description": "The type of object.", + "type": "string", "example": "user", "enum": [ "user" ] }, "id": { - "type": "string", "description": "The ID of user", + "type": "string", "example": "3423423" } - } + }, + "required": [ + "id", + "type" + ] }, "is_accepted": { + "description": "Whether the user has accepted the terms.", "type": "boolean", - "example": true, - "description": "Whether the user has accepted the terms." + "example": true } - } + }, + "required": [ + "tos", + "user", + "is_accepted" + ] } } } @@ -21897,28 +21893,28 @@ } } } - } + }, + "x-box-tag": "terms_of_service_user_statuses", + "tags": [ + "Terms of service user statuses" + ] } }, "/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", + "description": "The ID of the terms of service status.", "required": true, "schema": { "type": "string" - } + }, + "example": "324234" } ], "requestBody": { @@ -21926,16 +21922,16 @@ "application/json": { "schema": { "type": "object", - "required": [ - "is_accepted" - ], "properties": { "is_accepted": { + "description": "Whether the user has accepted the terms.", "type": "boolean", - "example": true, - "description": "Whether the user has accepted the terms." + "example": true } - } + }, + "required": [ + "is_accepted" + ] } } } @@ -21961,40 +21957,40 @@ } } } - } + }, + "x-box-tag": "terms_of_service_user_statuses", + "tags": [ + "Terms of service user statuses" + ] } }, "/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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 1000 } ], "responses": { @@ -22018,34 +22014,30 @@ } } } - } + }, + "x-box-tag": "collaboration_allowlist_entries", + "tags": [ + "Domain restrictions for collaborations" + ] }, "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.", + "type": "string", "example": "example.com" }, "direction": { - "type": "string", "description": "The direction in which to allow collaborations.", + "type": "string", "example": "inbound", "enum": [ "inbound", @@ -22053,7 +22045,11 @@ "both" ] } - } + }, + "required": [ + "domain", + "direction" + ] } } } @@ -22079,28 +22075,28 @@ } } } - } + }, + "x-box-tag": "collaboration_allowlist_entries", + "tags": [ + "Domain restrictions for collaborations" + ] } }, "/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", + "description": "The ID of the entry in the list.", "required": true, - "example": "213123", "schema": { "type": "string" - } + }, + "example": "213123" } ], "responses": { @@ -22124,26 +22120,26 @@ } } } - } + }, + "x-box-tag": "collaboration_allowlist_entries", + "tags": [ + "Domain restrictions for collaborations" + ] }, "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", + "description": "The ID of the entry in the list.", "required": true, - "example": "213123", "schema": { "type": "string" - } + }, + "example": "213123" } ], "responses": { @@ -22160,40 +22156,40 @@ } } } - } + }, + "x-box-tag": "collaboration_allowlist_entries", + "tags": [ + "Domain restrictions for collaborations" + ] } }, "/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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 1000 } ], "responses": { @@ -22217,40 +22213,40 @@ } } } - } + }, + "x-box-tag": "collaboration_allowlist_exempt_targets", + "tags": [ + "Domain restrictions (User exemptions)" + ] }, "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" - ], + "type": "object", "properties": { "id": { - "type": "string", "description": "The ID of the user to exempt.", + "type": "string", "example": "23522323" } - } + }, + "required": [ + "id" + ] } - } + }, + "required": [ + "user" + ] } } } @@ -22276,28 +22272,28 @@ } } } - } + }, + "x-box-tag": "collaboration_allowlist_exempt_targets", + "tags": [ + "Domain restrictions (User exemptions)" + ] } }, "/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", + "description": "The ID of the exemption to the list.", "required": true, - "example": "984923", "schema": { "type": "string" - } + }, + "example": "984923" } ], "responses": { @@ -22321,26 +22317,26 @@ } } } - } + }, + "x-box-tag": "collaboration_allowlist_exempt_targets", + "tags": [ + "Domain restrictions (User exemptions)" + ] }, "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", + "description": "The ID of the exemption to the list.", "required": true, - "example": "984923", "schema": { "type": "string" - } + }, + "example": "984923" } ], "responses": { @@ -22357,58 +22353,58 @@ } } } - } + }, + "x-box-tag": "collaboration_allowlist_exempt_targets", + "tags": [ + "Domain restrictions (User exemptions)" + ] } }, "/storage_policies": { "get": { "operationId": "get_storage_policies", "summary": "List storage policies", - "tags": [ - "Standard and Zones 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" - ], + "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.", "required": false, - "explode": false, "schema": { "type": "array", "items": { "type": "string" } - } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false }, { "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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 1000 } ], "responses": { @@ -22432,28 +22428,28 @@ } } } - } + }, + "x-box-tag": "storage_policies", + "tags": [ + "Standard and Zones Storage Policies" + ] } }, "/storage_policies/{storage_policy_id}": { "get": { "operationId": "get_storage_policies_id", "summary": "Get storage policy", - "tags": [ - "Standard and Zones 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", + "description": "The ID of the storage policy.", "required": true, "schema": { "type": "string" - } + }, + "example": "34342" } ], "responses": { @@ -22477,33 +22473,32 @@ } } } - } + }, + "x-box-tag": "storage_policies", + "tags": [ + "Standard and Zones Storage Policies" + ] } }, "/storage_policy_assignments": { "get": { "operationId": "get_storage_policy_assignments", "summary": "List storage policy assignments", - "tags": [ - "Standard and Zones 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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "resolved_for_type", "in": "query", - "example": "user", "description": "The target type to return assignments for", "required": true, "schema": { @@ -22512,17 +22507,18 @@ "user", "enterprise" ] - } + }, + "example": "user" }, { "name": "resolved_for_id", "in": "query", - "required": true, - "example": "984322", "description": "The ID of the user or enterprise to return assignments for", + "required": true, "schema": { "type": "string" - } + }, + "example": "984322" } ], "responses": { @@ -22546,60 +22542,52 @@ } } } - } + }, + "x-box-tag": "storage_policy_assignments", + "tags": [ + "Standard and Zones Storage Policy Assignments" + ] }, "post": { "operationId": "post_storage_policy_assignments", "summary": "Assign storage policy", - "tags": [ - "Standard and Zones 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" - ], + "type": "object", "properties": { "type": { - "type": "string", "description": "The type to assign.", + "type": "string", "example": "storage_policy", "enum": [ "storage_policy" ] }, "id": { - "type": "string", "description": "The ID of the storage policy to assign.", + "type": "string", "example": "1434325" } - } - }, - "assigned_to": { - "type": "object", - "description": "The user or enterprise to assign the storage\npolicy to.", + }, "required": [ "type", "id" - ], + ] + }, + "assigned_to": { + "description": "The user or enterprise to assign the storage\npolicy to.", + "type": "object", "properties": { "type": { - "type": "string", "description": "The type to assign the policy to.", + "type": "string", "example": "user", "enum": [ "user", @@ -22607,13 +22595,21 @@ ] }, "id": { - "type": "string", "description": "The ID of the user or enterprise", + "type": "string", "example": "9987987" } - } + }, + "required": [ + "type", + "id" + ] } - } + }, + "required": [ + "storage_policy", + "assigned_to" + ] } } } @@ -22639,28 +22635,28 @@ } } } - } + }, + "x-box-tag": "storage_policy_assignments", + "tags": [ + "Standard and Zones Storage Policy Assignments" + ] } }, "/storage_policy_assignments/{storage_policy_assignment_id}": { "get": { "operationId": "get_storage_policy_assignments_id", "summary": "Get storage policy assignment", - "tags": [ - "Standard and Zones 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", + "description": "The ID of the storage policy assignment.", "required": true, "schema": { "type": "string" - } + }, + "example": "932483" } ], "responses": { @@ -22684,26 +22680,26 @@ } } } - } + }, + "x-box-tag": "storage_policy_assignments", + "tags": [ + "Standard and Zones Storage Policy Assignments" + ] }, "put": { "operationId": "put_storage_policy_assignments_id", "summary": "Update storage policy assignment", - "tags": [ - "Standard and Zones 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", + "description": "The ID of the storage policy assignment.", "required": true, "schema": { "type": "string" - } + }, + "example": "932483" } ], "requestBody": { @@ -22711,34 +22707,34 @@ "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" - ], + "type": "object", "properties": { "type": { - "type": "string", "description": "The type to assign.", + "type": "string", "example": "storage_policy", "enum": [ "storage_policy" ] }, "id": { - "type": "string", "description": "The ID of the storage policy to assign.", + "type": "string", "example": "1434325" } - } + }, + "required": [ + "type", + "id" + ] } - } + }, + "required": [ + "storage_policy" + ] } } } @@ -22764,26 +22760,26 @@ } } } - } + }, + "x-box-tag": "storage_policy_assignments", + "tags": [ + "Standard and Zones Storage Policy Assignments" + ] }, "delete": { "operationId": "delete_storage_policy_assignments_id", "summary": "Unassign storage policy", - "tags": [ - "Standard and Zones 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", + "description": "The ID of the storage policy assignment.", "required": true, "schema": { "type": "string" - } + }, + "example": "932483" } ], "responses": { @@ -22800,18 +22796,17 @@ } } } - } + }, + "x-box-tag": "storage_policy_assignments", + "tags": [ + "Standard and Zones Storage Policy Assignments" + ] } }, "/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.\n\n**Note**: Downloading a large file can be\naffected by various\nfactors such as distance, network latency,\nbandwidth, and congestion, as well as packet loss\nratio and current server load.\nFor these reasons we recommend that a maximum ZIP archive\ntotal size does not exceed 25GB.", "requestBody": { "content": { @@ -22898,36 +22893,29 @@ } } } - } + }, + "x-box-tag": "zip_downloads", + "tags": [ + "Zip Downloads" + ], + "x-box-reference-category": "zip_downloads" } }, "/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", + "description": "The unique identifier that represent this `zip` archive.", "required": true, "schema": { "type": "string" - } + }, + "example": "Lu6fA9Ob-jyysp3AAvMF4AkLEwZwAYbL=tgj2zIC=eK9RvJnJbjJl9rNh2qBgHDpyOCAOhpM=vajg2mKq8Mdd" } ], "responses": { @@ -22945,9 +22933,9 @@ "content": { "application/octet-stream": { "schema": { + "description": "The binary content of the archive, which will include the items\nrequested for this download.", "type": "string", - "format": "binary", - "description": "The binary content of the archive, which will include the items\nrequested for this download." + "format": "binary" } } } @@ -22982,29 +22970,36 @@ } } } - } + }, + "x-box-tag": "zip_downloads", + "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." + } + ], + "tags": [ + "Zip Downloads" + ], + "x-box-reference-category": "zip_downloads" } }, "/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", + "description": "The unique identifier that represent this `zip` archive.", "required": true, "schema": { "type": "string" - } + }, + "example": "Lu6fA9Ob-jyysp3AAvMF4AkLEwZwAYbL=tgj2zIC=eK9RvJnJbjJl9rNh2qBgHDpyOCAOhpM=vajg2mKq8Mdd" } ], "responses": { @@ -23058,28 +23053,29 @@ } } } - } + }, + "x-box-tag": "zip_downloads", + "tags": [ + "Zip Downloads" + ], + "x-box-reference-category": "zip_downloads" } }, "/sign_requests/{sign_request_id}/cancel": { "post": { "operationId": "post_sign_requests_id_cancel", "summary": "Cancel Box Sign request", - "tags": [ - "Sign requests" - ], - "x-box-tag": "sign_requests", "description": "Cancels a sign request.", "parameters": [ { "name": "sign_request_id", - "description": "The ID of the signature request", - "example": "33243242", "in": "path", + "description": "The ID of the signature request", "required": true, "schema": { "type": "string" - } + }, + "example": "33243242" } ], "responses": { @@ -23113,28 +23109,28 @@ } } } - } + }, + "x-box-tag": "sign_requests", + "tags": [ + "Sign requests" + ] } }, "/sign_requests/{sign_request_id}/resend": { "post": { "operationId": "post_sign_requests_id_resend", "summary": "Resend Box Sign request", - "tags": [ - "Sign requests" - ], - "x-box-tag": "sign_requests", "description": "Resends a signature request email to all outstanding signers.", "parameters": [ { "name": "sign_request_id", - "description": "The ID of the signature request", - "example": "33243242", "in": "path", + "description": "The ID of the signature request", "required": true, "schema": { "type": "string" - } + }, + "example": "33243242" } ], "responses": { @@ -23161,28 +23157,28 @@ } } } - } + }, + "x-box-tag": "sign_requests", + "tags": [ + "Sign requests" + ] } }, "/sign_requests/{sign_request_id}": { "get": { "operationId": "get_sign_requests_id", "summary": "Get Box Sign request by ID", - "tags": [ - "Sign requests" - ], - "x-box-tag": "sign_requests", "description": "Gets a sign request by ID.", "parameters": [ { "name": "sign_request_id", - "description": "The ID of the signature request", - "example": "33243242", "in": "path", + "description": "The ID of the signature request", "required": true, "schema": { "type": "string" - } + }, + "example": "33243242" } ], "responses": { @@ -23216,40 +23212,40 @@ } } } - } + }, + "x-box-tag": "sign_requests", + "tags": [ + "Sign requests" + ] } }, "/sign_requests": { "get": { "operationId": "get_sign_requests", "summary": "List Box Sign requests", - "tags": [ - "Sign requests" - ], - "x-box-tag": "sign_requests", "description": "Gets signature requests created by a user. If the `sign_files` and/or\n`parent_folder` are deleted, the signature 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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 1000 } ], "responses": { @@ -23273,15 +23269,15 @@ } } } - } + }, + "x-box-tag": "sign_requests", + "tags": [ + "Sign requests" + ] }, "post": { "operationId": "post_sign_requests", "summary": "Create Box Sign request", - "tags": [ - "Sign requests" - ], - "x-box-tag": "sign_requests", "description": "Creates a signature request. This involves preparing a document for signing and\nsending the signature request to signers.", "requestBody": { "content": { @@ -23313,62 +23309,62 @@ } } } - } + }, + "x-box-tag": "sign_requests", + "tags": [ + "Sign requests" + ] } }, "/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", + "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`.", "required": true, "schema": { "type": "string", "nullable": false - } + }, + "example": "12345" }, { "name": "trigger_type", - "description": "Type of trigger to search for.", - "example": "WORKFLOW_MANUAL_START", "in": "query", + "description": "Type of trigger to search for.", "required": false, "schema": { "type": "string", "nullable": false - } + }, + "example": "WORKFLOW_MANUAL_START" }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" } ], "responses": { @@ -23412,28 +23408,28 @@ } } } - } + }, + "x-box-tag": "workflows", + "tags": [ + "Workflows" + ] } }, "/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", + "description": "The ID of the workflow.", "required": true, "schema": { "type": "string" - } + }, + "example": "12345" } ], "requestBody": { @@ -23441,86 +23437,86 @@ "application/json": { "schema": { "type": "object", - "required": [ - "flow", - "files", - "folder" - ], "properties": { "type": { - "type": "string", "description": "The type of the parameters object", + "type": "string", "example": "workflow_parameters", "enum": [ "workflow_parameters" ] }, "flow": { - "type": "object", "description": "The flow that will be triggered", + "type": "object", "properties": { "type": { - "type": "string", "description": "The type of the flow object", + "type": "string", "example": "flow" }, "id": { - "type": "string", "description": "The id of the flow", + "type": "string", "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.", + "type": "array", "items": { "type": "object", "description": "A file the workflow should start for", "properties": { "type": { - "type": "string", "description": "The type of the file object", + "type": "string", "example": "file", "enum": [ "file" ] }, "id": { - "type": "string", "description": "The id of the file", + "type": "string", "example": "12345678" } } } }, "folder": { - "type": "object", "description": "The folder object for which the workflow is configured.", + "type": "object", "properties": { "type": { - "type": "string", "description": "The type of the folder object", + "type": "string", "example": "folder", "enum": [ "folder" ] }, "id": { - "type": "string", "description": "The id of the folder", + "type": "string", "example": "87654321" } } }, "outcomes": { - "type": "array", "description": "A configurable outcome the workflow should complete.", + "type": "array", "items": { "$ref": "#/components/schemas/Outcome" } } - } + }, + "required": [ + "flow", + "files", + "folder" + ] } } } @@ -23569,40 +23565,40 @@ } } } - } + }, + "x-box-tag": "workflows", + "tags": [ + "Workflows" + ] } }, "/sign_templates": { "get": { "operationId": "get_sign_templates", "summary": "List Box Sign templates", - "tags": [ - "Sign 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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 1000 } ], "responses": { @@ -23636,28 +23632,28 @@ } } } - } + }, + "x-box-tag": "sign_templates", + "tags": [ + "Sign templates" + ] } }, "/sign_templates/{template_id}": { "get": { "operationId": "get_sign_templates_id", "summary": "Get Box Sign template by ID", - "tags": [ - "Sign 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", + "description": "The ID of a Box Sign template.", "required": true, "schema": { "type": "string" - } + }, + "example": "123075213-7d117509-8f05-42e4-a5ef-5190a319d41d" } ], "responses": { @@ -23701,44 +23697,45 @@ } } } - } + }, + "x-box-tag": "sign_templates", + "tags": [ + "Sign templates" + ] } }, "/integration_mappings/slack": { "get": { "operationId": "get_integration_mappings_slack", "summary": "List Slack integration mappings", - "tags": [ - "Integration mappings" - ], - "x-box-tag": "integration_mappings", "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", + "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`.", "required": false, - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "schema": { "type": "string" - } + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", - "description": "The maximum number of items to return per page.", "in": "query", + "description": "The maximum number of items to return per page.", "required": false, - "example": 1000, "schema": { "type": "integer", "format": "int64", "maximum": 1000 - } + }, + "example": 1000 }, { - "in": "query", "name": "partner_item_type", + "in": "query", + "description": "Mapped item type, for which the mapping should be returned", "schema": { "type": "string", "enum": [ @@ -23746,50 +23743,49 @@ ], "nullable": false }, - "description": "Mapped item type, for which the mapping should be returned", "example": "channel" }, { - "in": "query", "name": "partner_item_id", + "in": "query", + "description": "ID of the mapped item, for which the mapping should be returned", "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", + "in": "query", + "description": "Box item ID, for which the mappings should be returned", "schema": { "type": "string", "nullable": false }, - "description": "Box item ID, for which the mappings should be returned", "example": "12345" }, { - "in": "query", "name": "box_item_type", + "in": "query", + "description": "Box item type, for which the mappings should be returned", "schema": { - "nullable": false, "type": "string", "enum": [ "folder" - ] + ], + "nullable": false }, - "description": "Box item type, for which the mappings should be returned", "example": "folder" }, { - "in": "query", "name": "is_manually_created", + "in": "query", + "description": "Whether the mapping has been manually created", "schema": { "type": "boolean", "nullable": false }, - "description": "Whether the mapping has been manually created", "example": true } ], @@ -23834,15 +23830,15 @@ } } } - } + }, + "x-box-tag": "integration_mappings", + "tags": [ + "Integration mappings" + ] }, "post": { "operationId": "post_integration_mappings_slack", "summary": "Create Slack integration mapping", - "tags": [ - "Integration mappings" - ], - "x-box-tag": "integration_mappings", "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": { @@ -23894,57 +23890,57 @@ } } } - } + }, + "x-box-tag": "integration_mappings", + "tags": [ + "Integration mappings" + ] } }, "/integration_mappings/slack/{integration_mapping_id}": { "put": { "operationId": "put_integration_mappings_slack_id", "summary": "Update Slack integration mapping", - "tags": [ - "Integration mappings" - ], - "x-box-tag": "integration_mappings", "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", + "description": "An ID of an integration mapping", "required": true, "schema": { "type": "string" - } + }, + "example": "11235432" } ], "requestBody": { + "description": "At least one of `box_item` and `options` must be provided.", "content": { "application/json": { "schema": { "type": "object", "properties": { "box_item": { - "nullable": false, "allOf": [ { "$ref": "#/components/schemas/IntegrationMappingBoxItemSlack" } - ] + ], + "nullable": false }, "options": { - "nullable": false, "allOf": [ { "$ref": "#/components/schemas/IntegrationMappingSlackOptions" } - ] + ], + "nullable": false } } } } - }, - "description": "At least one of `box_item` and `options` must be provided." + } }, "responses": { "200": { @@ -23987,26 +23983,26 @@ } } } - } + }, + "x-box-tag": "integration_mappings", + "tags": [ + "Integration mappings" + ] }, "delete": { "operationId": "delete_integration_mappings_slack_id", "summary": "Delete Slack integration mapping", - "tags": [ - "Integration mappings" - ], - "x-box-tag": "integration_mappings", "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", + "description": "An ID of an integration mapping", "required": true, "schema": { "type": "string" - } + }, + "example": "11235432" } ], "responses": { @@ -24033,20 +24029,19 @@ } } } - } + }, + "x-box-tag": "integration_mappings", + "tags": [ + "Integration mappings" + ] } }, "/ai/ask": { "post": { "operationId": "post_ai_ask", "summary": "Ask question", - "x-stability-level": "beta", - "tags": [ - "AI" - ], - "x-box-tag": "ai", - "x-box-enable-explorer": false, "description": "Sends an AI request to supported LLMs and returns an answer specifically focused on the user's question given the provided context.", + "x-stability-level": "beta", "requestBody": { "content": { "application/json": { @@ -24087,20 +24082,20 @@ } } } - } + }, + "x-box-tag": "ai", + "tags": [ + "AI" + ], + "x-box-enable-explorer": false } }, "/ai/text_gen": { "post": { "operationId": "post_ai_text_gen", "summary": "Generate text", - "x-stability-level": "beta", - "tags": [ - "AI" - ], - "x-box-tag": "ai", - "x-box-enable-explorer": false, "description": "Sends an AI request to supported Large Language Models (LLMs) and returns generated text based on the provided prompt.", + "x-stability-level": "beta", "requestBody": { "content": { "application/json": { @@ -24141,27 +24136,26 @@ } } } - } + }, + "x-box-tag": "ai", + "tags": [ + "AI" + ], + "x-box-enable-explorer": false } }, "/ai_agent_default": { "get": { "operationId": "get_ai_agent_default", "summary": "Get AI agent default configuration", - "x-stability-level": "beta", - "tags": [ - "AI" - ], - "x-box-tag": "ai", - "x-box-enable-explorer": false, "description": "Get the AI agent default config", + "x-stability-level": "beta", "parameters": [ { "name": "mode", - "description": "The mode to filter the agent config to return.", "in": "query", + "description": "The mode to filter the agent config to return.", "required": true, - "example": "ask", "schema": { "type": "string", "enum": [ @@ -24170,27 +24164,28 @@ "extract", "extract_structured" ] - } + }, + "example": "ask" }, { "name": "language", - "description": "The ISO language code to return the agent config for.\nIf the language is not supported the default agent config is returned.", "in": "query", + "description": "The ISO language code to return the agent config for.\nIf the language is not supported the default agent config is returned.", "required": false, - "example": "ja", "schema": { "type": "string" - } + }, + "example": "ja" }, { "name": "model", - "description": "The model to return the default agent config for.", "in": "query", + "description": "The model to return the default agent config for.", "required": false, - "example": "openai__gpt_3_5_turbo", "schema": { "type": "string" - } + }, + "example": "openai__gpt_3_5_turbo" } ], "responses": { @@ -24237,20 +24232,20 @@ } } } - } + }, + "x-box-tag": "ai", + "tags": [ + "AI" + ], + "x-box-enable-explorer": false } }, "/ai/extract": { "post": { "operationId": "post_ai_extract", "summary": "Extract metadata (freeform)", - "x-stability-level": "beta", - "tags": [ - "AI" - ], - "x-box-tag": "ai", - "x-box-enable-explorer": false, "description": "Sends an AI request to supported Large Language Models (LLMs) and extracts metadata in form of key-value pairs.\nFreeform metadata extraction does not require any metadata template setup before sending the request.", + "x-stability-level": "beta", "requestBody": { "content": { "application/json": { @@ -24291,20 +24286,20 @@ } } } - } + }, + "x-box-tag": "ai", + "tags": [ + "AI" + ], + "x-box-enable-explorer": false } }, "/ai/extract_structured": { "post": { "operationId": "post_ai_extract_structured", "summary": "Extract metadata (structured)", - "x-stability-level": "beta", - "tags": [ - "AI" - ], - "x-box-tag": "ai", - "x-box-enable-explorer": false, "description": "Sends an AI request to supported Large Language Models (LLMs) and returns extracted metadata as a set of key-value pairs.\nFor this request, you need to use an already defined metadata template or a define a schema yourself.\nTo learn more about creating templates, see [Creating metadata templates in the Admin Console](https://support.box.com/hc/en-us/articles/360044194033-Customizing-Metadata-Templates)\nor use the [metadata template API](g://metadata/templates/create).", + "x-stability-level": "beta", "requestBody": { "content": { "application/json": { @@ -24345,1750 +24340,1178 @@ } } } - } + }, + "x-box-tag": "ai", + "tags": [ + "AI" + ], + "x-box-enable-explorer": false } } }, "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": { - "AiAsk": { - "title": "AI ask request", + "AccessToken": { + "description": "A token that can be used to make authenticated API calls.", "type": "object", - "x-box-tag": "ai", - "required": [ - "prompt", - "items", - "mode" - ], "properties": { - "mode": { + "access_token": { + "description": "The requested access token.", "type": "string", - "description": "The mode specifies if this request is for a single or multiple items. If you select `single_item_qa` the `items` array can have one element only. Selecting `multiple_item_qa` allows you to provide up to 25 items.", - "enum": [ - "multiple_item_qa", - "single_item_qa" - ], - "example": "multiple_item_qa", - "nullable": false + "format": "token", + "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" }, - "prompt": { - "type": "string", - "description": "The prompt provided by the client to be answered by the LLM. The prompt's length is limited to 10000 characters.", - "example": "What is the value provided by public APIs based on this document?" + "expires_in": { + "description": "The time in seconds by which this token will expire.", + "type": "integer", + "format": "int64", + "example": 3600 }, - "items": { - "type": "array", - "description": "The items to be processed by the LLM, often files.\n\n**Note**: Box AI handles documents with text representations up to 1MB in size, or a maximum of 25 files, whichever comes first.\nIf the file size exceeds 1MB, the first 1MB of text representation will be processed.\nIf you set `mode` parameter to `single_item_qa`, the `items` array can have one element only. ", - "minItems": 1, - "maxItems": 25, - "uniqueItems": true, - "items": { - "$ref": "#/components/schemas/AiItem--Base" - } + "token_type": { + "description": "The type of access token returned.", + "type": "string", + "example": "bearer", + "enum": [ + "bearer" + ] }, - "dialogue_history": { + "restricted_to": { + "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.", "type": "array", - "description": "The history of prompts and answers previously passed to the LLM. This provides additional context to the LLM in generating the response.", "items": { - "$ref": "#/components/schemas/AiDialogueHistory" + "$ref": "#/components/schemas/FileOrFolderScope" } }, - "include_citations": { - "type": "boolean", - "description": "A flag to indicate whether citations should be returned.", - "example": true + "refresh_token": { + "description": "The refresh token for this access token, which can be used\nto request a new access token when the current one expires.", + "type": "string", + "format": "token", + "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" }, - "ai_agent": { - "$ref": "#/components/schemas/AiAgentAsk" + "issued_token_type": { + "description": "The type of downscoped access token returned. This is only\nreturned if an access token has been downscoped.", + "type": "string", + "format": "urn", + "example": "urn:ietf:params:oauth:token-type:access_token", + "enum": [ + "urn:ietf:params:oauth:token-type:access_token" + ] } }, - "description": "AI ask request object" + "title": "Access token", + "x-box-resource-id": "access_token", + "x-box-tag": "authorization" }, - "AiTextGen": { - "title": "AI text gen request", + "AiAgentAsk": { + "description": "The AI agent used to handle queries.", "type": "object", - "x-box-tag": "ai", - "required": [ - "prompt", - "items" - ], "properties": { - "prompt": { + "type": { + "description": "The type of AI agent used to handle queries.", "type": "string", - "description": "The prompt provided by the client to be answered by the LLM. The prompt's length is limited to 10000 characters.", - "example": "Write an email to a client about the importance of public APIs." + "example": "ai_agent_ask", + "enum": [ + "ai_agent_ask" + ], + "nullable": false }, - "items": { - "type": "array", - "description": "The items to be processed by the LLM, often files.\nThe array can include **exactly one** element.\n\n**Note**: Box AI handles documents with text representations up to 1MB in size.\nIf the file size exceeds 1MB, the first 1MB of text representation will be processed.", - "minItems": 1, - "maxItems": 1, - "uniqueItems": true, - "items": { - "required": [ - "id", - "type" - ], - "type": "object", - "description": "The item to be processed by the LLM.", - "properties": { - "id": { - "type": "string", - "description": "The ID of the item.", - "example": "123" - }, - "type": { - "type": "string", - "description": "The type of the item.", - "enum": [ - "file" - ], - "example": "file" - }, - "content": { - "type": "string", - "description": "The content to use as context for generating new text or editing existing text.", - "example": "This is file content that is relevant to the text gen request." - } - } - } + "long_text": { + "$ref": "#/components/schemas/AiAgentLongTextTool" }, - "dialogue_history": { - "type": "array", - "description": "The history of prompts and answers previously passed to the LLM. This parameter provides the additional context to the LLM when generating the response.", - "items": { - "$ref": "#/components/schemas/AiDialogueHistory" - } + "basic_text": { + "$ref": "#/components/schemas/AiAgentBasicTextTool" }, - "ai_agent": { - "$ref": "#/components/schemas/AiAgentTextGen" + "long_text_multi": { + "$ref": "#/components/schemas/AiAgentLongTextTool" + }, + "basic_text_multi": { + "$ref": "#/components/schemas/AiAgentBasicTextTool" } }, - "description": "AI text gen request object" - }, - "AiExtractStructured": { - "title": "AI Extract Structured Request", - "type": "object", - "x-box-tag": "ai", "required": [ - "items" + "type" ], - "properties": { - "items": { - "type": "array", - "description": "The items to be processed by the LLM. Currently you can use files only.", - "minItems": 1, - "maxItems": 1, - "uniqueItems": true, - "items": { - "$ref": "#/components/schemas/AiItem--Base" - } + "title": "AI agent for question requests", + "x-box-resource-id": "ai_agent_ask", + "x-box-tag": "ai" + }, + "AiAgentBasicGenTool": { + "description": "AI agent basic tool used to generate text. ", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/AiAgentLongTextToolTextGen" }, - "metadata_template": { - "type": "object", - "description": "The metadata template containing the fields to extract.\nFor your request to work, you must provide either `metadata_template` or `fields`, but not both.", + { "properties": { - "template_key": { - "type": "string", - "description": "The name of the metadata template.", - "example": "invoiceTemplate" - }, - "type": { - "type": "string", - "enum": [ - "metadata_template" - ], - "description": "Value is always `metadata_template`.", - "example": "metadata_template" - }, - "scope": { + "content_template": { + "description": "How the content should be included in a request to the LLM.\nInput for `{content}` is optional, depending on the use.", "type": "string", - "description": "The scope of the metadata template that can either be global or\nenterprise. \n* The **global** scope is used for templates that are\navailable to any Box enterprise. \n* The **enterprise** scope represents templates created within a specific enterprise,\n containing the ID of that enterprise.", - "example": "enterprise_12345", - "maxLength": 40 + "example": "---{content}---" } } + } + ], + "title": "AI agent basic text generation tool", + "x-box-tag": "ai" + }, + "AiAgentBasicTextTool": { + "description": "AI agent tool used to handle basic text.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/AiAgentBasicTextToolBase" }, - "fields": { - "type": "array", - "description": "The fields to be extracted from the provided items.\nFor your request to work, you must provide either `metadata_template` or `fields`, but not both.", - "minItems": 1, - "uniqueItems": true, - "items": { - "type": "object", - "description": "The fields to be extracted from the provided items.", - "required": [ - "key" - ], - "properties": { - "key": { - "type": "string", - "description": "A unique identifier for the field.", - "example": "name" - }, - "description": { - "type": "string", - "description": "A description of the field.", - "example": "The name of the person." - }, - "displayName": { - "type": "string", - "description": "The display name of the field.", - "example": "Name" - }, - "prompt": { - "type": "string", - "description": "The context about the key that may include how to find and format it.", - "example": "Name is the first and last name from the email address" - }, - "type": { - "type": "string", - "description": "The type of the field. It include but is not limited to string, float, date, enum, and multiSelect.", - "example": "enum" - }, - "options": { - "type": "array", - "description": "A list of options for this field. This is most often used in combination with the enum and multiSelect field types.", - "items": { - "type": "object", - "required": [ - "key" - ], - "properties": { - "key": { - "type": "string", - "description": "A unique identifier for the field.", - "example": "First Name" - } - } - }, - "example": [ - { - "key": "First Name" - }, - { - "key": "Last Name" - } - ] - } + { + "properties": { + "system_message": { + "description": "System messages try to help the LLM \"understand\" its role and what it is supposed to do.", + "type": "string", + "example": "You are a helpful travel assistant specialized in budget travel" + }, + "prompt_template": { + "description": "The prompt template contains contextual information of the request and the user prompt.\nWhen passing `prompt_template` parameters, you **must include** inputs for `{user_question}` and `{content}`.\n`{current_date}` is optional, depending on the use.", + "type": "string", + "example": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.", + "maxLength": 10000, + "pattern": "(\\{user_question\\}[\\s\\S]*?\\{content\\}|\\{content\\}[\\s\\S]*?\\{user_question\\})" } } - }, - "ai_agent": { - "$ref": "#/components/schemas/AiAgentExtractStructured" } - }, - "description": "AI Extract Structured Request object." + ], + "title": "AI agent basic text tool", + "x-box-tag": "ai" }, - "AiExtract": { - "title": "AI metadata freeform extraction request", + "AiAgentBasicTextToolBase": { + "description": "AI agent tool used to handle basic text.", "type": "object", - "x-box-tag": "ai", - "required": [ - "prompt", - "items" - ], "properties": { - "prompt": { + "model": { + "description": "The model used for the AI agent for basic text. For specific model values, see the [available models list](g://box-ai/supported-models).", "type": "string", - "description": "The prompt provided to a Large Language Model (LLM) in the request. The prompt can be up to 10000 characters long and it can be an XML or a JSON schema.", - "example": "\\\"fields\\\":[{\\\"type\\\":\\\"string\\\",\\\"key\\\":\\\"name\\\",\\\"displayName\\\":\\\"Name\\\",\\\"description\\\":\\\"The customer name\\\",\\\"prompt\\\":\\\"Name is always the first word in the document\\\"},{\\\"type\\\":\\\"date\\\",\\\"key\\\":\\\"last_contacted_at\\\",\\\"displayName\\\":\\\"Last Contacted At\\\",\\\"description\\\":\\\"When this customer was last contacted at\\\"}]" + "example": "azure__openai__gpt_3_5_turbo_16k" }, - "items": { - "type": "array", - "description": "The items that LLM will process. Currently, you can use files only.", - "minItems": 1, - "maxItems": 1, - "uniqueItems": true, - "items": { - "$ref": "#/components/schemas/AiItem--Base" - } + "num_tokens_for_completion": { + "description": "The number of tokens for completion.", + "type": "integer", + "example": 8400, + "minimum": 1 }, - "ai_agent": { - "$ref": "#/components/schemas/AiAgentExtract" + "llm_endpoint_params": { + "description": "The parameters for the LLM endpoint specific to OpenAI / Google models.", + "oneOf": [ + { + "$ref": "#/components/schemas/AiLlmEndpointParamsOpenAi" + }, + { + "$ref": "#/components/schemas/AiLlmEndpointParamsGoogle" + } + ] } }, - "description": "AI metadata freeform extraction request object" + "title": "AI agent basic text tool", + "x-box-tag": "ai" }, - "PostOAuth2Token": { - "title": "Token request", + "AiAgentBasicTextToolTextGen": { + "description": "AI agent tool used to handle basic text.", "type": "object", - "description": "A request for a new OAuth 2.0 token", - "required": [ - "grant_type" + "allOf": [ + { + "$ref": "#/components/schemas/AiAgentBasicTextToolBase" + }, + { + "properties": { + "system_message": { + "description": "System messages aim at helping the LLM understand its role and what it is supposed to do.\nThe input for `{current_date}` is optional, depending on the use.", + "type": "string", + "example": "You are a helpful travel assistant specialized in budget travel" + }, + "prompt_template": { + "description": "The prompt template contains contextual information of the request and the user prompt.\n\nWhen using the `prompt_template` parameter, you **must include** input for `{user_question}`.\nInputs for `{current_date}` and `{content}` are optional, depending on the use.", + "type": "string", + "example": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. `{user_question}`", + "maxLength": 10000, + "pattern": "\\{user_question\\}" + } + } + } ], + "title": "AI agent basic text tool", + "x-box-tag": "ai" + }, + "AiAgentExtract": { + "description": "The AI agent to be used for extraction.", + "type": "object", "properties": { - "grant_type": { + "type": { + "description": "The type of AI agent to be used for extraction.", "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.", + "example": "ai_agent_extract", "enum": [ - "authorization_code", - "refresh_token", - "client_credentials", - "urn:ietf:params:oauth:grant-type:jwt-bearer", - "urn:ietf:params:oauth:grant-type:token-exchange" - ] + "ai_agent_extract" + ], + "nullable": false }, - "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" + "long_text": { + "$ref": "#/components/schemas/AiAgentLongTextTool" }, - "client_secret": { + "basic_text": { + "$ref": "#/components/schemas/AiAgentBasicTextTool" + } + }, + "required": [ + "type" + ], + "title": "AI agent for extract requests", + "x-box-resource-id": "ai_agent_extract", + "x-box-tag": "ai" + }, + "AiAgentExtractStructured": { + "description": "The AI agent to be used for structured extraction.", + "type": "object", + "properties": { + "type": { + "description": "The type of AI agent to be used for extraction.", "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" + "example": "ai_agent_extract_structured", + "enum": [ + "ai_agent_extract_structured" + ], + "nullable": false }, - "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" + "long_text": { + "$ref": "#/components/schemas/AiAgentLongTextTool" }, - "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" + "basic_text": { + "$ref": "#/components/schemas/AiAgentBasicTextTool" + } + }, + "required": [ + "type" + ], + "title": "AI agent for structured extract request", + "x-box-resource-id": "ai_agent_extract_structured", + "x-box-tag": "ai" + }, + "AiAgentLongTextTool": { + "description": "AI agent tool used to to handle longer text.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/AiAgentBasicTextTool" }, - "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" + { + "properties": { + "embeddings": { + "type": "object", + "properties": { + "model": { + "description": "The model used for the AI agent for calculating embeddings.", + "type": "string", + "example": "openai__text_embedding_ada_002" + }, + "strategy": { + "type": "object", + "properties": { + "id": { + "description": "The strategy used for the AI agent for calculating embeddings.", + "type": "string", + "example": "basic" + }, + "num_tokens_per_chunk": { + "description": "The number of tokens per chunk.", + "type": "integer", + "example": 64, + "minimum": 1 + } + } + } + } + } + } + } + ], + "title": "AI agent long text tool", + "x-box-tag": "ai" + }, + "AiAgentLongTextToolTextGen": { + "description": "AI agent tool used to to handle longer text.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/AiAgentBasicTextToolTextGen" }, - "subject_token_type": { + { + "properties": { + "embeddings": { + "type": "object", + "properties": { + "model": { + "description": "The model used for the AI agent for calculating embeddings.", + "type": "string", + "example": "openai__text_embedding_ada_002" + }, + "strategy": { + "type": "object", + "properties": { + "id": { + "description": "The strategy used for the AI agent for calculating embeddings.", + "type": "string", + "example": "basic" + }, + "num_tokens_per_chunk": { + "description": "The number of tokens per chunk.", + "type": "integer", + "example": 64, + "minimum": 1 + } + } + } + } + } + } + } + ], + "title": "AI agent long text tool", + "x-box-tag": "ai" + }, + "AiAgentTextGen": { + "description": "The AI agent used for generating text.", + "type": "object", + "properties": { + "type": { + "description": "The type of AI agent used for generating text.", "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`.", + "example": "ai_agent_text_gen", "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" + "ai_agent_text_gen" + ], + "nullable": false }, - "actor_token_type": { + "basic_gen": { + "$ref": "#/components/schemas/AiAgentBasicGenTool" + } + }, + "required": [ + "type" + ], + "title": "AI agent for text generation requests", + "x-box-resource-id": "ai_agent_text_gen", + "x-box-tag": "ai" + }, + "AiAsk": { + "description": "AI ask request object", + "type": "object", + "properties": { + "mode": { + "description": "The mode specifies if this request is for a single or multiple items. If you select `single_item_qa` the `items` array can have one element only. Selecting `multiple_item_qa` allows you to provide up to 25 items.", "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`.", + "example": "multiple_item_qa", "enum": [ - "urn:ietf:params:oauth:token-type:id_token" - ] + "multiple_item_qa", + "single_item_qa" + ], + "nullable": false }, - "scope": { + "prompt": { + "description": "The prompt provided by the client to be answered by the LLM. The prompt's length is limited to 10000 characters.", "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" + "example": "What is the value provided by public APIs based on this document?" }, - "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" + "items": { + "description": "The items to be processed by the LLM, often files.\n\n**Note**: Box AI handles documents with text representations up to 1MB in size, or a maximum of 25 files, whichever comes first.\nIf the file size exceeds 1MB, the first 1MB of text representation will be processed.\nIf you set `mode` parameter to `single_item_qa`, the `items` array can have one element only. ", + "type": "array", + "items": { + "$ref": "#/components/schemas/AiItem--Base" + }, + "maxItems": 25, + "minItems": 1, + "uniqueItems": true }, - "box_subject_type": { - "type": "string", - "example": "enterprise", - "description": "Used in combination with `client_credentials` as the `grant_type`.", - "enum": [ - "enterprise", - "user" - ] + "dialogue_history": { + "description": "The history of prompts and answers previously passed to the LLM. This provides additional context to the LLM in generating the response.", + "type": "array", + "items": { + "$ref": "#/components/schemas/AiDialogueHistory" + } }, - "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." + "include_citations": { + "description": "A flag to indicate whether citations should be returned.", + "type": "boolean", + "example": true }, - "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" + "ai_agent": { + "$ref": "#/components/schemas/AiAgentAsk" } - } - }, - "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" + "prompt", + "items", + "mode" ], + "title": "AI ask request", + "x-box-tag": "ai" + }, + "AiCitation": { + "description": "The citation of the LLM's answer reference.", + "type": "object", "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" - ] + "content": { + "description": "The specific content from where the answer was referenced.", + "example": "Public APIs are key drivers of innovation and growth.", + "type": "string" }, - "client_id": { + "id": { + "description": "The id of the item.", "type": "string", - "description": "The client ID of the application requesting to refresh the token.", - "example": "ly1nj6n11vionaie65emwzk575hnnmrk" + "example": "123" }, - "client_secret": { + "type": { + "description": "The type of the item.", "type": "string", - "description": "The client secret of the application requesting to refresh the token.", - "example": "hOzsTeFlT6ko0dme22uGbQal04SBPYc1" + "example": "file", + "enum": [ + "file" + ] }, - "refresh_token": { + "name": { + "description": "The name of the item.", "type": "string", - "format": "token", - "description": "The refresh token to refresh.", - "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" + "example": "The importance of public APIs.pdf" } - } + }, + "title": "The citation of the LLM's answer reference" }, - "PostOAuth2Revoke": { - "title": "Token revocation request", + "AiDialogueHistory": { + "description": "A context object that can hold prior prompts and answers.", "type": "object", - "description": "A request to revoke an OAuth 2.0 token", - "required": [ - "grant_type" - ], "properties": { - "client_id": { + "prompt": { + "description": "The prompt previously provided by the client and answered by the LLM.", "type": "string", - "description": "The Client ID of the application requesting to revoke the\naccess token.", - "example": "ly1nj6n11vionaie65emwzk575hnnmrk" + "example": "Make my email about public APIs sound more professional." }, - "client_secret": { + "answer": { + "description": "The answer previously provided by the LLM.", "type": "string", - "description": "The client secret of the application requesting to revoke\nan access token.", - "example": "hOzsTeFlT6ko0dme22uGbQal04SBPYc1" + "example": "Here is the first draft of your professional email about public APIs." }, - "token": { + "created_at": { + "description": "The ISO date formatted timestamp of when the previous answer to the prompt was created.", "type": "string", - "format": "token", - "description": "The access token to revoke.", - "example": "n22JPxrh18m4Y0wIZPIqYZK7VRrsMTWW" + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" } - } + }, + "title": "Dialogue history" }, - "ZipDownloadRequest": { - "title": "Create a `zip` archive", + "AiExtract": { + "description": "AI metadata freeform extraction request object", "type": "object", - "description": "A request to create a `zip` archive to download", - "required": [ - "items" - ], "properties": { + "prompt": { + "description": "The prompt provided to a Large Language Model (LLM) in the request. The prompt can be up to 10000 characters long and it can be an XML or a JSON schema.", + "type": "string", + "example": "\\\"fields\\\":[{\\\"type\\\":\\\"string\\\",\\\"key\\\":\\\"name\\\",\\\"displayName\\\":\\\"Name\\\",\\\"description\\\":\\\"The customer name\\\",\\\"prompt\\\":\\\"Name is always the first word in the document\\\"},{\\\"type\\\":\\\"date\\\",\\\"key\\\":\\\"last_contacted_at\\\",\\\"displayName\\\":\\\"Last Contacted At\\\",\\\"description\\\":\\\"When this customer was last contacted at\\\"}]" + }, "items": { + "description": "The items that LLM will process. Currently, you can use files only.", "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" - } - } - } + "$ref": "#/components/schemas/AiItem--Base" + }, + "maxItems": 1, + "minItems": 1, + "uniqueItems": true }, - "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" + "ai_agent": { + "$ref": "#/components/schemas/AiAgentExtract" } - } - }, - "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" + "prompt", + "items" ], + "title": "AI metadata freeform extraction request", + "x-box-tag": "ai" + }, + "AiExtractResponse": { + "description": "AI extract response.\nThe content of this response may vary depending on\nthe requested configuration.", + "type": "object", + "title": "AI extract response", + "x-box-resource-id": "ai_extract_response", + "x-box-tag": "ai" + }, + "AiExtractStructured": { + "description": "AI Extract Structured Request object.", + "type": "object", "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" + "items": { + "description": "The items to be processed by the LLM. Currently you can use files only.", + "type": "array", + "items": { + "$ref": "#/components/schemas/AiItem--Base" + }, + "maxItems": 1, + "minItems": 1, + "uniqueItems": true }, - "query_params": { + "metadata_template": { + "description": "The metadata template containing the fields to extract.\nFor your request to work, you must provide either `metadata_template` or `fields`, but not both.", "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" + "properties": { + "template_key": { + "description": "The name of the metadata template.", + "type": "string", + "example": "invoiceTemplate" + }, + "type": { + "description": "Value is always `metadata_template`.", + "type": "string", + "example": "metadata_template", + "enum": [ + "metadata_template" + ] + }, + "scope": { + "description": "The scope of the metadata template that can either be global or\nenterprise. \n* The **global** scope is used for templates that are\navailable to any Box enterprise. \n* The **enterprise** scope represents templates created within a specific enterprise,\n containing the ID of that enterprise.", + "type": "string", + "example": "enterprise_12345", + "maxLength": 40 + } } }, - "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": { + "fields": { + "description": "The fields to be extracted from the provided items.\nFor your request to work, you must provide either `metadata_template` or `fields`, but not both.", "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.", + "description": "The fields to be extracted from the provided items.", + "required": [ + "key" + ], "properties": { - "field_key": { + "key": { + "description": "A unique identifier for the field.", "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" + "example": "name" }, - "direction": { + "description": { + "description": "A description of the field.", "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" + "example": "The name of the person." + }, + "displayName": { + "description": "The display name of the field.", + "type": "string", + "example": "Name" + }, + "prompt": { + "description": "The context about the key that may include how to find and format it.", + "type": "string", + "example": "Name is the first and last name from the email address" + }, + "type": { + "description": "The type of the field. It include but is not limited to string, float, date, enum, and multiSelect.", + "type": "string", + "example": "enum" + }, + "options": { + "description": "A list of options for this field. This is most often used in combination with the enum and multiSelect field types.", + "type": "array", + "items": { + "type": "object", + "required": [ + "key" + ], + "properties": { + "key": { + "description": "A unique identifier for the field.", + "type": "string", + "example": "First Name" + } + } + }, + "example": [ + { + "key": "First Name" + }, + { + "key": "Last Name" + } ] } } - } - }, - "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" - ] + "minItems": 1, + "uniqueItems": true + }, + "ai_agent": { + "$ref": "#/components/schemas/AiAgentExtractStructured" } - } + }, + "required": [ + "items" + ], + "title": "AI Extract Structured Request", + "x-box-tag": "ai" }, - "FileRequestUpdateRequest": { - "title": "File Request (Update)", + "AiItem--Base": { + "description": "The item to be processed by the LLM.", "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": { + "id": { + "description": "The ID of the file.", "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" + "example": "123" }, - "status": { + "type": { + "description": "The type of the item. Currently the value can be `file` only.", "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", + "example": "file", "enum": [ - "active", - "inactive" + "file" ] }, - "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" + "content": { + "description": "The content of the item, often the text representation.", + "example": "This is file content.", + "type": "string" } - } - }, - "FileRequestCopyRequest": { - "title": "File Request (Copy)", - "type": "object", - "description": "The request body to copy a file request.", + }, "required": [ - "folder" + "id", + "type" ], - "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." - } - } - } - } - } + "title": "AI Item (Base)", + "x-box-variant": "base", + "x-box-variants": [ + "base" ] }, - "SignRequestCreateRequest": { - "title": "Create a Box Sign request", + "AiLlmEndpointParamsGoogle": { + "description": "AI LLM endpoint params Google object", "type": "object", - "description": "Creates a Box Sign request object.", - "required": [ - "signers" - ], - "allOf": [ - { - "$ref": "#/components/schemas/SignRequest--Base" + "properties": { + "type": { + "description": "The type of the AI LLM endpoint params object for Google.\nThis parameter is **required**.", + "type": "string", + "example": "google_params", + "enum": [ + "google_params" + ], + "nullable": false }, - { - "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 - }, - "signature_color": { - "type": "string", - "example": "blue", - "description": "Force a specific color for the signature (blue, black, or red)", - "enum": [ - "blue", - "black", - "red" - ], - "nullable": true - }, - "signers": { - "type": "array", - "items": { - "$ref": "#/components/schemas/SignRequestCreateSigner" - }, - "description": "Array of signers for the signature request. 35 is the\nmax number of signers permitted.\n\n**Note**: It may happen that some signers belong to conflicting [segments](r://shield-information-barrier-segment-member) (user groups).\nThis means that due to the security policies, users are assigned to segments to prevent exchanges or communication that could lead to ethical conflicts.\nIn such a case, an attempt to send the sign request will result in an error.\n\nRead more about [segments and ethical walls](https://support.box.com/hc/en-us/articles/9920431507603-Understanding-Information-Barriers#h_01GFVJEHQA06N7XEZ4GCZ9GFAQ)." - }, - "parent_folder": { - "allOf": [ - { - "$ref": "#/components/schemas/Folder--Mini" - }, - { - "description": "The destination folder to place final, signed document and signing\nlog. Only `ID` and `type` fields are required. The root folder,\nfolder ID `0`, cannot be used and can also not be null.\n\nWhen this value is not passed in when the signature request, then\nwe will use a default folder which is either the parent folder of\nthe first source file in the payload if we have the permission to\nupload to that folder or a folder called \"My Sign Requests\"." - } - ] - } - } - } - ] - }, - "IntegrationMappingSlackCreateRequest": { - "title": "Create Slack integration mapping request", - "type": "object", - "x-box-resource-id": "integration_mapping_slack_create_request", - "description": "A request to create a\nSlack Integration Mapping object", - "allOf": [ - { - "properties": { - "partner_item": { - "allOf": [ - { - "$ref": "#/components/schemas/IntegrationMappingPartnerItemSlack" - } - ], - "nullable": false - } - } + "temperature": { + "description": "The temperature is used for sampling during response generation, which occurs when `top-P` and `top-K` are applied. Temperature controls the degree of randomness in the token selection.", + "type": "number", + "example": 0, + "maximum": 2, + "minimum": 0, + "nullable": true }, - { - "type": "object", - "properties": { - "box_item": { - "allOf": [ - { - "$ref": "#/components/schemas/IntegrationMappingBoxItemSlack" - } - ], - "nullable": false - }, - "options": { - "allOf": [ - { - "$ref": "#/components/schemas/IntegrationMappingSlackOptions" - } - ], - "nullable": false - } - }, - "required": [ - "box_item" - ] + "top_p": { + "description": "`Top-P` changes how the model selects tokens for output. Tokens are selected from the most (see `top-K`) to least probable until the sum of their probabilities equals the `top-P` value.", + "type": "number", + "example": 1, + "maximum": 2, + "minimum": 0.1, + "nullable": true + }, + "top_k": { + "description": "`Top-K` changes how the model selects tokens for output. A `top-K` of 1 means the next selected token is\nthe most probable among all tokens in the model's vocabulary (also called greedy decoding),\nwhile a `top-K` of 3 means that the next token is selected from among the three most probable tokens by using temperature.", + "type": "number", + "example": 1, + "maximum": 2, + "minimum": 0.1, + "nullable": true } - ], + }, "required": [ - "partner_item" - ] + "type" + ], + "title": "AI LLM endpoint params Google", + "x-box-resource-id": "ai_llm_endpoint_params_google" }, - "ClientError": { - "title": "Client error", + "AiLlmEndpointParamsOpenAi": { + "description": "AI LLM endpoint params OpenAI object.", "type": "object", - "x-box-resource-id": "client_error", - "description": "A generic error", "properties": { "type": { - "description": "error", - "example": "error", + "description": "The type of the AI LLM endpoint params object for OpenAI.\nThis parameter is **required**.", "type": "string", + "example": "openai_params", "enum": [ - "error" + "openai_params" ], "nullable": false }, - "status": { - "description": "The HTTP status of the response.", - "example": 400, - "type": "integer", - "format": "int32", - "nullable": false + "temperature": { + "description": "What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, \nwhile lower values like 0.2 will make it more focused and deterministic. \nWe generally recommend altering this or `top_p` but not both.", + "type": "number", + "example": 0, + "maximum": 2, + "minimum": 0, + "nullable": true }, - "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" - ] + "top_p": { + "description": "An alternative to sampling with temperature, called nucleus sampling, where the model considers the results \nof the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability \nmass are considered. We generally recommend altering this or temperature but not both.", + "type": "number", + "example": 1, + "maximum": 1, + "minimum": 0.1, + "nullable": true }, - "message": { - "description": "A short message describing the error.", - "example": "Method Not Allowed", - "type": "string", - "nullable": false + "frequency_penalty": { + "description": "A number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the \ntext so far, decreasing the model's likelihood to repeat the same line verbatim.", + "type": "number", + "example": 1.5, + "maximum": 2, + "minimum": -2, + "nullable": true }, - "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", - "nullable": true, - "properties": { - "message": { - "type": "string", - "description": "More details on the error.", - "example": "Something went wrong." - } - } + "presence_penalty": { + "description": "A number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.", + "type": "number", + "example": 1.5, + "maximum": 2, + "minimum": -2, + "nullable": true }, - "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/", + "stop": { + "description": "Up to 4 sequences where the API will stop generating further tokens.", "type": "string", - "nullable": false + "example": "<|im_end|>", + "nullable": true + } + }, + "required": [ + "type" + ], + "title": "AI LLM endpoint params OpenAI", + "x-box-resource-id": "ai_llm_endpoint_params_openai" + }, + "AiResponse": { + "description": "AI response", + "type": "object", + "properties": { + "answer": { + "description": "The answer provided by the LLM.", + "type": "string", + "example": "Public APIs are important because of key and important reasons." }, - "request_id": { - "description": "A unique identifier for this response, which can be used\nwhen contacting Box support.", + "created_at": { + "description": "The ISO date formatted timestamp of when the answer to the prompt was created.", "type": "string", - "example": "abcdef123456", - "nullable": false + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "completion_reason": { + "description": "The reason the response finishes.", + "type": "string", + "example": "done" } - } + }, + "required": [ + "answer", + "created_at" + ], + "title": "AI response", + "x-box-resource-id": "ai_response", + "x-box-tag": "ai", + "x-box-variant": "standard", + "x-box-variants": [ + "standard", + "full" + ] }, - "ConflictError": { - "title": "Conflict error", + "AiResponse--Full": { + "description": "AI ask response", "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" + "$ref": "#/components/schemas/AiResponse" }, { "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" - } - } + "citations": { + "description": "The citations of the LLM's answer reference.", + "type": "array", + "items": { + "$ref": "#/components/schemas/AiCitation" } } } } + ], + "required": [ + "answer", + "created_at" + ], + "title": "AI response (Full)", + "x-box-resource-id": "ai_response--full", + "x-box-tag": "ai", + "x-box-variant": "full", + "x-box-variants": [ + "standard", + "full" ] }, - "OAuth2Error": { - "title": "OAuth 2.0 error", + "AiTextGen": { + "description": "AI text gen request object", "type": "object", - "x-box-resource-id": "oauth2_error", - "x-box-tag": "authorization", - "description": "An OAuth 2.0 error", "properties": { - "error": { + "prompt": { + "description": "The prompt provided by the client to be answered by the LLM. The prompt's length is limited to 10000 characters.", "type": "string", - "example": "invalid_client", - "description": "The type of the error returned." + "example": "Write an email to a client about the importance of public APIs." }, - "error_description": { - "type": "string", - "example": "The client credentials are not valid", - "description": "The type of the error returned." + "items": { + "description": "The items to be processed by the LLM, often files.\nThe array can include **exactly one** element.\n\n**Note**: Box AI handles documents with text representations up to 1MB in size.\nIf the file size exceeds 1MB, the first 1MB of text representation will be processed.", + "type": "array", + "items": { + "required": [ + "id", + "type" + ], + "type": "object", + "description": "The item to be processed by the LLM.", + "properties": { + "id": { + "description": "The ID of the item.", + "type": "string", + "example": "123" + }, + "type": { + "description": "The type of the item.", + "type": "string", + "example": "file", + "enum": [ + "file" + ] + }, + "content": { + "description": "The content to use as context for generating new text or editing existing text.", + "example": "This is file content that is relevant to the text gen request.", + "type": "string" + } + } + }, + "maxItems": 1, + "minItems": 1, + "uniqueItems": true + }, + "dialogue_history": { + "description": "The history of prompts and answers previously passed to the LLM. This parameter provides the additional context to the LLM when generating the response.", + "type": "array", + "items": { + "$ref": "#/components/schemas/AiDialogueHistory" + } + }, + "ai_agent": { + "$ref": "#/components/schemas/AiAgentTextGen" } - } + }, + "required": [ + "prompt", + "items" + ], + "title": "AI text gen request", + "x-box-tag": "ai" }, - "SkillInvocation": { - "title": "Skill webhook payload", + "AppItem": { + "description": "An app item represents an content object owned by an application. It can\ngroup files and folders together from different paths. That set can be shared\nvia a collaboration.", "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": { + "id": { + "description": "The unique identifier for this app item.", + "type": "string", + "example": "12345678" + }, "type": { + "description": "`app_item`", "type": "string", - "description": "`skill_invocation`", - "example": "skill_invocation", + "example": "app_item", "enum": [ - "skill_invocation" + "app_item" ] }, + "application_type": { + "description": "The type of the app that owns this app item.", + "type": "string", + "example": "hubs" + } + }, + "required": [ + "id", + "type", + "application_type" + ], + "title": "App item", + "x-box-resource-id": "app_item", + "x-box-tag": "app_item_associations" + }, + "AppItemAssociation": { + "description": "An app item association represents an association between a file or\nfolder and an app item. Associations between a folder and an app item\ncascade down to all descendants of the folder.", + "type": "object", + "properties": { "id": { + "description": "The unique identifier for this app item association.", "type": "string", - "description": "Unique identifier for the invocation request.", - "example": "fd1d2e53-35f5-41fb-9c25-4ba326daf2f9_341016304" + "example": "12345678", + "nullable": false }, - "skill": { + "type": { + "description": "`app_item_association`", + "type": "string", + "example": "app_item_association", + "enum": [ + "app_item_association" + ], + "nullable": false + }, + "app_item": { "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" - } - } + "$ref": "#/components/schemas/AppItem" }, { - "description": "The skill that triggered this invocation" + "description": "The app item which is associated with the file or folder." } - ] + ], + "nullable": false }, - "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 by which this token will expire." + "item": { + "allOf": [ + { + "oneOf": [ + { + "$ref": "#/components/schemas/File--Base" }, - "token_type": { - "type": "string", - "enum": [ - "bearer" - ], - "example": "bearer", - "description": "The type of access token returned." + { + "$ref": "#/components/schemas/Folder--Base" }, - "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\"}]" + { + "$ref": "#/components/schemas/WebLink--Base" } - } + ] }, - "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 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\"}]" - } - } + { + "description": "The file or folder which is associated with the app item." } - } - }, - "status": { + ], + "nullable": false + } + }, + "required": [ + "id", + "type", + "app_item", + "item" + ], + "title": "App item association", + "x-box-resource-id": "app_item_association", + "x-box-tag": "app_item_associations" + }, + "AppItemAssociations": { + "description": "A list of app item associations", + "type": "object", + "allOf": [ + { "type": "object", - "description": "The details status of this event.", + "description": "The part of an API response that describes marker\nbased pagination", "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" + "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.", + "type": "integer", + "format": "int64", + "example": 1000 }, - "error_code": { + "next_marker": { + "description": "The marker for the start of the next page of results.", "type": "string", - "example": "400", - "description": "Error code information, if error occurred." + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true }, - "additional_info": { + "prev_marker": { + "description": "The marker for the start of the previous page of results.", "type": "string", - "example": "Example", - "description": "Additional status information." + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true } } }, - "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" - } + { + "properties": { + "entries": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AppItemAssociation" } - }, - { - "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" } - ] + } } - } + ], + "title": "App item associations", + "x-box-resource-id": "app_item_associations", + "x-box-tag": "app_item_associations" }, - "WebhookInvocation": { - "title": "Webhook (V2) payload", + "AppItemEventSource": { + "description": "The AppItem that triggered an event in the event stream.", "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": { + "description": "The id of the `AppItem`", "type": "string", - "description": "The unique identifier for this webhook invocation", - "example": "11446498" + "example": "6374669741" }, "type": { + "description": "The type of the source that this event represents. Can only be `app_item`.\n", "type": "string", - "description": "`webhook_event`", - "example": "webhook_event", + "example": "app_item", "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" - } - ] + "app_item" + ], + "nullable": false }, - "created_at": { + "app_item_type": { + "description": "The type of the `AppItem`", "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" + "example": "hubs" }, - "trigger": { + "user": { "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" - ] + "$ref": "#/components/schemas/User--Mini" }, { - "description": "The event name that triggered this webhook" + "description": "The user that triggered the event." } ] }, - "source": { + "group": { "allOf": [ { - "oneOf": [ - { - "$ref": "#/components/schemas/File" - }, - { - "$ref": "#/components/schemas/Folder" - } - ] + "$ref": "#/components/schemas/Group--Mini" }, { - "description": "The item that caused the event to trigger" + "description": "The group that triggered the event." } ] } - } + }, + "required": [ + "id", + "type", + "app_item_type" + ], + "title": "AppItem event source", + "x-box-resource-id": "app_item_event_source" }, - "AccessToken": { - "title": "Access token", + "Classification": { + "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.", "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 by which this token will expire." - }, - "token_type": { + "Box__Security__Classification__Key": { + "description": "The name of the classification applied to the item.", "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/FileOrFolderScope" - } + "example": "Sensitive" }, - "refresh_token": { + "$parent": { + "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}`.", "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." + "example": "folder_59449484661," }, - "issued_token_type": { + "$template": { + "description": "`securityClassification-6VMVochwUWo`", "type": "string", - "format": "urn", - "example": "urn:ietf:params:oauth:token-type:access_token", + "example": "securityClassification-6VMVochwUWo", "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." - } - } - }, - "AiResponse": { - "title": "AI response", - "type": "object", - "x-box-resource-id": "ai_response", - "x-box-tag": "ai", - "x-box-variant": "standard", - "x-box-variants": [ - "standard", - "full" - ], - "required": [ - "answer", - "created_at" - ], - "properties": { - "answer": { - "type": "string", - "description": "The answer provided by the LLM.", - "example": "Public APIs are important because of key and important reasons." + "securityClassification-6VMVochwUWo" + ] }, - "created_at": { + "$scope": { + "description": "The scope of the enterprise that this classification has been\napplied for.\n\nThis will be in the format `enterprise_{enterprise_id}`.", "type": "string", - "format": "date-time", - "description": "The ISO date formatted timestamp of when the answer to the prompt was created.", - "example": "2012-12-12T10:53:43-08:00" + "example": "enterprise_27335" }, - "completion_reason": { - "type": "string", - "description": "The reason the response finishes.", - "example": "done" - } - }, - "description": "AI response" - }, - "AiResponse--Full": { - "title": "AI response (Full)", - "x-box-resource-id": "ai_response--full", - "x-box-tag": "ai", - "x-box-variant": "full", - "x-box-variants": [ - "standard", - "full" - ], - "type": "object", - "required": [ - "answer", - "created_at" - ], - "allOf": [ - { - "$ref": "#/components/schemas/AiResponse" + "$version": { + "description": "The version of the metadata instance. This version starts at 0 and\nincreases every time a classification is updated.", + "type": "integer", + "example": 1 }, - { - "properties": { - "citations": { - "type": "array", - "description": "The citations of the LLM's answer reference.", - "items": { - "$ref": "#/components/schemas/AiCitation" - } - } - } - } - ], - "description": "AI ask response" - }, - "AiExtractResponse": { - "title": "AI extract response", - "type": "object", - "x-box-resource-id": "ai_extract_response", - "x-box-tag": "ai", - "description": "AI extract response.\nThe content of this response may vary depending on\nthe requested configuration." - }, - "AiAgentAsk": { - "title": "AI agent for question requests", - "type": "object", - "x-box-resource-id": "ai_agent_ask", - "x-box-tag": "ai", - "required": [ - "type" - ], - "properties": { - "type": { + "$type": { + "description": "The unique ID of this classification instance. This will be include\nthe name of the classification template and a unique ID.", "type": "string", - "enum": [ - "ai_agent_ask" - ], - "description": "The type of AI agent used to handle queries.", - "example": "ai_agent_ask", - "nullable": false - }, - "long_text": { - "$ref": "#/components/schemas/AiAgentLongTextTool" - }, - "basic_text": { - "$ref": "#/components/schemas/AiAgentBasicTextTool" + "example": "securityClassification-6VMVochwUWo-fd31537a-0f95-4d86-9f2b-5974a29978f8" }, - "long_text_multi": { - "$ref": "#/components/schemas/AiAgentLongTextTool" + "$typeVersion": { + "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.", + "type": "number", + "example": 5 }, - "basic_text_multi": { - "$ref": "#/components/schemas/AiAgentBasicTextTool" + "$canEdit": { + "description": "Whether an end user can change the classification.", + "type": "boolean", + "example": true } }, - "description": "The AI agent used to handle queries." + "title": "Classification", + "x-box-resource-id": "classification", + "x-box-tag": "classifications" }, - "AiAgentTextGen": { - "title": "AI agent for text generation requests", + "ClassificationTemplate": { + "description": "A metadata template that holds the security classifications\ndefined by an enterprise.", "type": "object", - "x-box-tag": "ai", - "x-box-resource-id": "ai_agent_text_gen", - "required": [ - "type" - ], "properties": { - "type": { + "id": { + "description": "The ID of the classification template.", "type": "string", - "enum": [ - "ai_agent_text_gen" - ], - "description": "The type of AI agent used for generating text.", - "example": "ai_agent_text_gen", - "nullable": false + "example": "58063d82-4128-7b43-bba9-92f706befcdf" }, - "basic_gen": { - "$ref": "#/components/schemas/AiAgentBasicGenTool" - } - }, - "description": "The AI agent used for generating text." - }, - "AiAgentExtract": { - "title": "AI agent for extract requests", - "type": "object", - "x-box-tag": "ai", - "x-box-resource-id": "ai_agent_extract", - "required": [ - "type" - ], - "properties": { "type": { + "description": "`metadata_template`", "type": "string", + "example": "metadata_template", "enum": [ - "ai_agent_extract" + "metadata_template" ], - "description": "The type of AI agent to be used for extraction.", - "example": "ai_agent_extract", "nullable": false }, - "long_text": { - "$ref": "#/components/schemas/AiAgentLongTextTool" + "scope": { + "description": "The scope of the classification template. This is in the format\n`enterprise_{id}` where the `id` is the enterprise ID.", + "type": "string", + "example": "enterprise_123456" }, - "basic_text": { - "$ref": "#/components/schemas/AiAgentBasicTextTool" - } - }, - "description": "The AI agent to be used for extraction." - }, - "AiAgentExtractStructured": { - "title": "AI agent for structured extract request", - "type": "object", - "x-box-tag": "ai", - "x-box-resource-id": "ai_agent_extract_structured", - "required": [ - "type" - ], - "properties": { - "type": { + "templateKey": { + "description": "`securityClassification-6VMVochwUWo`", "type": "string", + "example": "securityClassification-6VMVochwUWo", "enum": [ - "ai_agent_extract_structured" - ], - "description": "The type of AI agent to be used for extraction.", - "example": "ai_agent_extract_structured", - "nullable": false + "securityClassification-6VMVochwUWo" + ] }, - "long_text": { - "$ref": "#/components/schemas/AiAgentLongTextTool" - }, - "basic_text": { - "$ref": "#/components/schemas/AiAgentBasicTextTool" - } - }, - "description": "The AI agent to be used for structured extraction." - }, - "AppItem": { - "title": "App item", - "type": "object", - "x-box-tag": "app_item_associations", - "x-box-resource-id": "app_item", - "description": "An app item represents an content object owned by an application. It can\ngroup files and folders together from different paths. That set can be shared\nvia a collaboration.", - "required": [ - "id", - "type", - "application_type" - ], - "properties": { - "id": { - "type": "string", - "description": "The unique identifier for this app item.", - "example": "12345678" - }, - "type": { - "type": "string", - "description": "`app_item`", - "example": "app_item", - "enum": [ - "app_item" - ] - }, - "application_type": { - "type": "string", - "description": "The type of the app that owns this app item.", - "example": "hubs" - } - } - }, - "AppItemAssociation": { - "title": "App item association", - "type": "object", - "x-box-tag": "app_item_associations", - "x-box-resource-id": "app_item_association", - "description": "An app item association represents an association between a file or\nfolder and an app item. Associations between a folder and an app item\ncascade down to all descendants of the folder.", - "required": [ - "id", - "type", - "app_item", - "item" - ], - "properties": { - "id": { - "type": "string", - "description": "The unique identifier for this app item association.", - "example": "12345678", - "nullable": false - }, - "type": { - "type": "string", - "description": "`app_item_association`", - "example": "app_item_association", - "enum": [ - "app_item_association" - ], - "nullable": false - }, - "app_item": { - "allOf": [ - { - "$ref": "#/components/schemas/AppItem" - }, - { - "description": "The app item which is associated with the file or folder." - } - ], - "nullable": false - }, - "item": { - "allOf": [ - { - "oneOf": [ - { - "$ref": "#/components/schemas/File--Base" - }, - { - "$ref": "#/components/schemas/Folder--Base" - }, - { - "$ref": "#/components/schemas/WebLink--Base" - } - ] - }, - { - "description": "The file or folder which is associated with the app item." - } - ], - "nullable": false - } - } - }, - "AppItemAssociations": { - "title": "App item associations", - "type": "object", - "x-box-tag": "app_item_associations", - "x-box-resource-id": "app_item_associations", - "description": "A list of app item associations", - "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": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", - "type": "string", - "nullable": true - }, - "prev_marker": { - "description": "The marker for the start of the previous page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", - "type": "string", - "nullable": true - } - } - }, - { - "properties": { - "entries": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AppItemAssociation" - } - } - } - } - ] - }, - "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": [ - "id", - "type", - "scope", - "displayName", - "fields", - "templateKey" - ], - "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" - ] + "displayName": { + "description": "The name of this template as shown in web and mobile interfaces.", + "type": "string", + "example": "Classification", + "enum": [ + "Classification" + ] }, "hidden": { + "description": "Determines if the\ntemplate is always available in web and mobile interfaces.", "type": "boolean", - "example": false, - "description": "Determines if the\ntemplate is always available in web and mobile interfaces." + "example": false }, "copyInstanceOnItemCopy": { + "description": "Determines if \nclassifications are\ncopied along when the file or folder is\ncopied.", "type": "boolean", - "example": true, - "description": "Determines if \nclassifications are\ncopied along when the file or folder is\ncopied." + "example": true }, "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.", + "type": "array", "items": { "type": "object", "required": [ @@ -26101,43 +25524,42 @@ "description": "The metadata template field that represents the available\nclassifications.", "properties": { "id": { + "description": "The unique ID of the field.", "type": "string", - "example": "822227e0-47a5-921b-88a8-494760b2e6d2", - "description": "The unique ID of the field." + "example": "822227e0-47a5-921b-88a8-494760b2e6d2" }, "type": { + "description": "The array item type.", "type": "string", "example": "enum", - "description": "The array item type.", "enum": [ "enum" ] }, "key": { + "description": "Defines classifications \navailable in the enterprise.", "type": "string", "example": "Box__Security__Classification__Key", - "description": "Defines classifications \navailable in the enterprise.", "enum": [ "Box__Security__Classification__Key" ] }, "displayName": { + "description": "`Classification`", "type": "string", "example": "Classification", - "description": "`Classification`", "enum": [ "Classification" ] }, "hidden": { + "description": "Classifications are always visible to web and mobile users.", "type": "boolean", - "example": false, - "description": "Classifications are always visible to web and mobile users." + "example": false }, "options": { - "type": "array", "description": "A list of classifications available in this enterprise.", - "minItems": 1, + "type": "array", "items": { "required": [ "key", @@ -26147,65 +25569,150 @@ "description": "A single classification available in this enterprise.", "properties": { "id": { + "description": "The unique ID of this classification.", "type": "string", - "example": "46aea176-3483-4431-856c-6b5b13d1cc50", - "description": "The unique ID of this classification." + "example": "46aea176-3483-4431-856c-6b5b13d1cc50" }, "key": { + "description": "The display name and key for this classification.", "type": "string", - "example": "Sensitive", - "description": "The display name and key for this classification." + "example": "Sensitive" }, "staticConfig": { - "type": "object", "description": "Additional information about the classification.", + "type": "object", "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.", + "type": "object", "properties": { "classificationDefinition": { + "description": "A longer description of the classification.", "type": "string", - "example": "Sensitive information", - "description": "A longer description of the classification." + "example": "Sensitive information" }, "colorID": { + "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", "type": "integer", "format": "int64", - "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" + "example": 4 } } } } } } - } + }, + "minItems": 1 } } + }, + "maxItems": 1, + "minItems": 1 + } + }, + "required": [ + "id", + "type", + "scope", + "displayName", + "fields", + "templateKey" + ], + "title": "Classification Template", + "x-box-resource-id": "classification_template", + "x-box-tag": "classifications" + }, + "ClientError": { + "description": "A generic error", + "type": "object", + "properties": { + "type": { + "description": "error", + "type": "string", + "example": "error", + "enum": [ + "error" + ], + "nullable": false + }, + "status": { + "description": "The HTTP status of the response.", + "type": "integer", + "format": "int32", + "example": 400, + "nullable": false + }, + "code": { + "description": "A Box-specific error code", + "type": "string", + "example": "item_name_invalid", + "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.", + "type": "string", + "example": "Method Not Allowed", + "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", + "nullable": true, + "properties": { + "message": { + "description": "More details on the error.", + "type": "string", + "example": "Something went wrong." + } } + }, + "help_url": { + "description": "A URL that links to more information about why this error occurred.", + "type": "string", + "example": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/", + "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 } - } + }, + "title": "Client error", + "x-box-resource-id": "client_error" }, "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.", - "required": [ - "id", - "type" - ], + "type": "object", "properties": { "id": { - "type": "string", "description": "The unique identifier for this collaboration.", + "type": "string", "example": "12345678" }, "type": { - "type": "string", "description": "`collaboration`", + "type": "string", "example": "collaboration", "enum": [ "collaboration" @@ -26261,12 +25768,13 @@ ] }, "invite_email": { + "description": "The email address used to invite an unregistered collaborator, if\nthey are not a registered user.", "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." + "nullable": true }, "role": { + "description": "The level of access granted.", "type": "string", "example": "editor", "enum": [ @@ -26278,36 +25786,35 @@ "viewer uploader", "co-owner", "owner" - ], - "description": "The level of access granted." + ] }, "expires_at": { + "description": "When the collaboration will expire, or `null` if no expiration\ndate is set.", "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." + "nullable": true }, "is_access_only": { + "description": "If set to `true`, collaborators have access to\nshared items, but such items won't be visible in the\nAll Files list. Additionally, collaborators won't\nsee the the path to the root folder for the\nshared item.", "type": "boolean", - "example": true, - "description": "If set to `true`, collaborators have access to\nshared items, but such items won't be visible in the\nAll Files list. Additionally, collaborators won't\nsee the the path to the root folder for the\nshared item." + "example": true }, "status": { + "description": "The status of the collaboration invitation. If the status\nis `pending`, `login` and `name` return an empty string.", "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": { + "description": "When the `status` of the collaboration object changed to\n`accepted` or `rejected`.", "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`." + "example": "2012-12-12T10:55:20-08:00" }, "created_by": { "allOf": [ @@ -26336,16 +25843,16 @@ ] }, "created_at": { + "description": "When the collaboration object was created.", "type": "string", "format": "date-time", - "example": "2012-12-12T10:53:43-08:00", - "description": "When the collaboration object was created." + "example": "2012-12-12T10:53:43-08:00" }, "modified_at": { + "description": "When the collaboration object was last modified.", "type": "string", "format": "date-time", - "example": "2012-12-12T10:53:43-08:00", - "description": "When the collaboration object was last modified." + "example": "2012-12-12T10:53:43-08:00" }, "acceptance_requirements_status": { "type": "object", @@ -26354,10 +25861,10 @@ "type": "object", "properties": { "is_accepted": { + "description": "Whether or not the terms of service have been accepted. The\nfield is `null` when there is no terms of service required.", "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." + "nullable": true }, "terms_of_service": { "allOf": [ @@ -26375,15 +25882,15 @@ "type": "object", "properties": { "enterprise_has_strong_password_required_for_external_users": { + "description": "Whether or not the enterprise that owns the content requires\na strong password to collaborate on the content.", "type": "boolean", - "example": true, - "description": "Whether or not the enterprise that owns the content requires\na strong password to collaborate on the content." + "example": true }, "user_has_strong_password": { + "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.", "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." + "nullable": true } } }, @@ -26391,28 +25898,32 @@ "type": "object", "properties": { "enterprise_has_two_factor_auth_enabled": { + "description": "Whether or not the enterprise that owns the content requires\ntwo-factor authentication to be enabled in order to\ncollaborate on the content.", "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." + "example": true }, "user_has_two_factor_authentication_enabled": { + "description": "Whether or not the user has two-factor authentication\nenabled. The field is `null` when two-factor\nauthentication is not required.", "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." + "nullable": true } } } } } - } + }, + "required": [ + "id", + "type" + ], + "title": "Collaboration", + "x-box-resource-id": "collaboration", + "x-box-tag": "user_collaborations" }, - "Collaborations": { - "title": "Collaborations", + "CollaborationAllowlistEntries": { + "description": "A list of allowed domains for collaboration.", "type": "object", - "x-box-resource-id": "collaborations", - "x-box-tag": "user_collaborations", - "description": "A list of collaborations", "allOf": [ { "type": "object", @@ -26420,114 +25931,66 @@ "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" + "format": "int64", + "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } }, - { - "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": { + "description": "A list of allowed collaboration domains", "type": "array", - "description": "A list of collaborations", "items": { - "$ref": "#/components/schemas/Collaboration" + "$ref": "#/components/schemas/CollaborationAllowlistEntry" } } } } - ] + ], + "title": "Allowed collaboration domains", + "x-box-resource-id": "collaboration_allowlist_entries", + "x-box-tag": "collaboration_allowlist_entries" }, "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.", + "type": "object", "properties": { "id": { - "type": "string", "description": "The unique identifier for this entry", + "type": "string", "example": "11446498" }, "type": { - "type": "string", "description": "`collaboration_whitelist_entry`", + "type": "string", "example": "collaboration_whitelist_entry", "enum": [ "collaboration_whitelist_entry" ] }, "domain": { + "description": "The whitelisted domain", "type": "string", - "example": "example.com", - "description": "The whitelisted domain" + "example": "example.com" }, "direction": { + "description": "The direction of the collaborations to allow.", "type": "string", "example": "both", - "description": "The direction of the collaborations to allow.", "enum": [ "inbound", "outbound", @@ -26542,13 +26005,13 @@ "description": "A representation of a Box enterprise", "properties": { "id": { - "type": "string", "description": "The unique identifier for this enterprise.", + "type": "string", "example": "11446498" }, "type": { - "type": "string", "description": "`enterprise`", + "type": "string", "example": "enterprise", "enum": [ "enterprise" @@ -26556,8 +26019,8 @@ }, "name": { "description": "The name of the enterprise", - "example": "Acme Inc.", - "type": "string" + "type": "string", + "example": "Acme Inc." } } }, @@ -26567,72 +26030,28 @@ ] }, "created_at": { + "description": "The time the entry was 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": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", - "type": "string", - "nullable": true - }, - "prev_marker": { - "description": "The marker for the start of the previous page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", - "type": "string", - "nullable": true - } - } - }, - { - "properties": { - "entries": { - "type": "array", - "description": "A list of allowed collaboration domains", - "items": { - "$ref": "#/components/schemas/CollaborationAllowlistEntry" - } - } - } - } - ] + }, + "title": "Allowed collaboration domain", + "x-box-resource-id": "collaboration_allowlist_entry", + "x-box-tag": "collaboration_allowlist_entries" }, "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.", + "type": "object", "properties": { "id": { - "type": "string", "description": "The unique identifier for this exemption", + "type": "string", "example": "11446498" }, "type": { - "type": "string", "description": "`collaboration_whitelist_exempt_target`", + "type": "string", "example": "collaboration_whitelist_exempt_target", "enum": [ "collaboration_whitelist_exempt_target" @@ -26646,13 +26065,13 @@ "description": "A representation of a Box enterprise", "properties": { "id": { - "type": "string", "description": "The unique identifier for this enterprise.", + "type": "string", "example": "11446498" }, "type": { - "type": "string", "description": "`enterprise`", + "type": "string", "example": "enterprise", "enum": [ "enterprise" @@ -26660,8 +26079,8 @@ }, "name": { "description": "The name of the enterprise", - "example": "Acme Inc.", - "type": "string" + "type": "string", + "example": "Acme Inc." } } }, @@ -26681,25 +26100,25 @@ ] }, "created_at": { + "description": "The time the entry was created", "type": "string", "format": "date-time", - "description": "The time the entry was created", "example": "2012-12-12T10:53:43-08:00" }, "modified_at": { + "description": "The time the entry was modified", "type": "string", "format": "date-time", - "description": "The time the entry was modified", "example": "2012-12-12T10:53:43-08:00" } - } + }, + "title": "Allowed collaboration domains user exemption", + "x-box-resource-id": "collaboration_allowlist_exempt_target", + "x-box-tag": "collaboration_allowlist_exempt_targets" }, "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 exempt from any of the restrictions\nimposed by the list of allowed collaboration domains for this enterprise.", + "type": "object", "allOf": [ { "type": "object", @@ -26707,20 +26126,20 @@ "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" + "format": "int64", + "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } @@ -26728,60 +26147,207 @@ { "properties": { "entries": { - "type": "array", "description": "A list of users exempt from any of the restrictions\nimposed by the list of allowed collaboration domains\nfor this enterprise.", + "type": "array", "items": { "$ref": "#/components/schemas/CollaborationAllowlistExemptTarget" } } } } - ] + ], + "title": "Allowed collaboration domains user exemptions", + "x-box-resource-id": "collaboration_allowlist_exempt_targets", + "x-box-tag": "collaboration_allowlist_exempt_targets" }, - "Collection": { - "title": "Collection", + "Collaborations": { + "description": "A list of collaborations", "type": "object", - "x-box-resource-id": "collection", - "x-box-tag": "collections", + "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.", + "type": "integer", + "format": "int64", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true + } + } + }, + { + "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.", + "type": "integer", + "format": "int64", + "example": 5000 + }, + "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.", + "type": "integer", + "format": "int64", + "example": 1000 + }, + "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.", + "type": "integer", + "format": "int64", + "example": 2000 + }, + "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", + "type": "string", + "example": "type" + }, + "direction": { + "description": "The direction to order by, either ascending or descending", + "type": "string", + "example": "ASC", + "enum": [ + "ASC", + "DESC" + ] + } + } + } + } + } + }, + { + "properties": { + "entries": { + "description": "A list of collaborations", + "type": "array", + "items": { + "$ref": "#/components/schemas/Collaboration" + } + } + } + } + ], + "title": "Collaborations", + "x-box-resource-id": "collaborations", + "x-box-tag": "user_collaborations" + }, + "CollaboratorVariable": { + "description": "A collaborator\nobject. Allows to\nspecify a list of user\nID's that are affected\nby the workflow result.", + "type": "object", + "properties": { + "type": { + "description": "Collaborator\nobject type.\n", + "type": "string", + "example": "variable", + "enum": [ + "variable" + ] + }, + "variable_type": { + "description": "Variable type \nfor the Collaborator\nobject.\n", + "type": "string", + "example": "user_list", + "enum": [ + "user_list" + ] + }, + "variable_value": { + "description": "A list of user IDs.", + "type": "array", + "items": { + "type": "object", + "required": [ + "type", + "id" + ], + "description": "User variable used\nin workflow outcomes.", + "properties": { + "type": { + "description": "The object type.", + "type": "string", + "example": "user", + "enum": [ + "user" + ] + }, + "id": { + "description": "User's ID.", + "type": "string", + "example": "636281" + } + } + } + } + }, + "required": [ + "type", + "variable_type", + "variable_value" + ], + "title": "Collaborator variable" + }, + "Collection": { "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.", + "type": "object", "properties": { "id": { - "type": "string", "description": "The unique identifier for this collection.", + "type": "string", "example": "11446498" }, "type": { - "type": "string", "description": "`collection`", + "type": "string", "example": "collection", "enum": [ "collection" ] }, "name": { - "type": "string", "description": "The name of the collection.", + "type": "string", + "example": "Favorites", "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.", + "type": "string", + "example": "favorites", "enum": [ "favorites" - ], - "example": "favorites" + ] } - } + }, + "title": "Collection", + "x-box-resource-id": "collection", + "x-box-tag": "collections" }, "Collections": { - "title": "Collections", - "type": "object", - "x-box-resource-id": "collections", - "x-box-tag": "collections", "description": "A list of collections", + "type": "object", "allOf": [ { "type": "object", @@ -26789,21 +26355,21 @@ "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" + "format": "int64", + "example": 5000 }, "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" + "format": "int64", + "example": 1000 }, "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" + "format": "int64", + "example": 2000 }, "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.", @@ -26814,12 +26380,12 @@ "properties": { "by": { "description": "The field to order by", - "example": "type", - "type": "string" + "type": "string", + "example": "type" }, "direction": { - "type": "string", "description": "The direction to order by, either ascending or descending", + "type": "string", "example": "ASC", "enum": [ "ASC", @@ -26834,22 +26400,22 @@ { "properties": { "entries": { - "type": "array", "description": "A list of collections", + "type": "array", "items": { "$ref": "#/components/schemas/Collection" } } } } - ] + ], + "title": "Collections", + "x-box-resource-id": "collections", + "x-box-tag": "collections" }, "Comment": { - "title": "Comment", - "type": "object", "description": "Standard representation of a comment.", - "x-box-resource-id": "comment", - "x-box-variant": "standard", + "type": "object", "allOf": [ { "$ref": "#/components/schemas/Comment--Base" @@ -26857,14 +26423,14 @@ { "properties": { "is_reply_comment": { - "type": "boolean", "description": "Whether or not this comment is a reply to another\ncomment", + "type": "boolean", "example": true }, "message": { + "description": "The text of the comment, as provided by the user", "type": "string", - "example": "@Aaron Levie these tigers are cool!", - "description": "The text of the comment, as provided by the user" + "example": "@Aaron Levie these tigers are cool!" }, "created_by": { "allOf": [ @@ -26877,15 +26443,15 @@ ] }, "created_at": { + "description": "The time this comment was created", "type": "string", "format": "date-time", - "description": "The time this comment was created", "example": "2012-12-12T10:53:43-08:00" }, "modified_at": { + "description": "The time this comment was last modified", "type": "string", "format": "date-time", - "description": "The time this comment was last modified", "example": "2012-12-12T10:53:43-08:00" }, "item": { @@ -26896,13 +26462,13 @@ "type": "object", "properties": { "id": { - "type": "string", "description": "The unique identifier for this object", + "type": "string", "example": "11446498" }, "type": { - "type": "string", "description": "The type for this object", + "type": "string", "example": "file" } } @@ -26914,14 +26480,63 @@ } } } - ] + ], + "title": "Comment", + "x-box-resource-id": "comment", + "x-box-variant": "standard" }, - "Comments": { - "title": "Comments", + "Comment--Base": { + "description": "Base representation of a comment.", "type": "object", - "x-box-resource-id": "comments", + "properties": { + "id": { + "description": "The unique identifier for this comment.", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`comment`", + "type": "string", + "example": "comment", + "enum": [ + "comment" + ] + } + }, + "title": "Comment (Base)", + "x-box-resource-id": "comment--base", "x-box-tag": "comments", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "standard", + "full" + ] + }, + "Comment--Full": { + "description": "Comments are messages created on files. Comments\ncan be made independently or created as responses to other\ncomments", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/Comment" + }, + { + "properties": { + "tagged_message": { + "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.", + "type": "string", + "example": "@[1234567:Aaron Levie] these tigers are cool!" + } + } + } + ], + "title": "Comment (Full)", + "x-box-resource-id": "comment--full", + "x-box-variant": "full" + }, + "Comments": { "description": "A list of comments", + "type": "object", "allOf": [ { "type": "object", @@ -26929,21 +26544,21 @@ "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" + "format": "int64", + "example": 5000 }, "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" + "format": "int64", + "example": 1000 }, "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" + "format": "int64", + "example": 2000 }, "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.", @@ -26954,12 +26569,12 @@ "properties": { "by": { "description": "The field to order by", - "example": "type", - "type": "string" + "type": "string", + "example": "type" }, "direction": { - "type": "string", "description": "The direction to order by, either ascending or descending", + "type": "string", "example": "ASC", "enum": [ "ASC", @@ -26974,80 +26589,96 @@ { "properties": { "entries": { - "type": "array", "description": "A list of comments", + "type": "array", "items": { "$ref": "#/components/schemas/Comment--Full" } } } } - ] + ], + "title": "Comments", + "x-box-resource-id": "comments", + "x-box-tag": "comments" }, - "Comment--Base": { - "title": "Comment (Base)", + "CompletionRuleVariable": { + "description": "A completion\nrule object. Determines\nif an action should be completed\nby all or any assignees.", "type": "object", - "x-box-resource-id": "comment--base", - "x-box-tag": "comments", - "x-box-variants": [ - "base", - "standard", - "full" - ], - "x-box-variant": "base", - "description": "Base representation of a comment.", "properties": { - "id": { + "type": { + "description": "Completion\nRule object type.\n", "type": "string", - "description": "The unique identifier for this comment.", - "example": "11446498" + "example": "variable", + "enum": [ + "variable" + ] }, - "type": { + "variable_type": { + "description": "Variable type\nfor the Completion\nRule object.\n", "type": "string", - "description": "`comment`", - "example": "comment", + "example": "task_completion_rule", "enum": [ - "comment" + "task_completion_rule" + ] + }, + "variable_value": { + "description": "Variable\nvalues for a completion\nrule.\n", + "type": "string", + "example": "all_assignees", + "enum": [ + "all_assignees", + "any_assignees" ] } - } + }, + "required": [ + "type", + "variable_type", + "variable_value" + ], + "title": "Completion rule variable" }, - "Comment--Full": { - "title": "Comment (Full)", + "ConflictError": { + "description": "The error that occurs when a file can not be created due\nto a conflict.", "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" + "$ref": "#/components/schemas/ClientError" }, { "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." + "context_info": { + "type": "object", + "properties": { + "conflicts": { + "description": "A list of the file conflicts that caused this error.", + "type": "array", + "items": { + "$ref": "#/components/schemas/FileConflict" + } + } + } } } } - ] + ], + "title": "Conflict error", + "x-box-resource-id": "conflict_error", + "x-box-tag": "uploads" }, "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.", + "type": "object", "properties": { "id": { - "type": "string", "description": "The unique identifier for this device pin.", + "type": "string", "example": "11446498" }, "type": { - "type": "string", "description": "`device_pinner`", + "type": "string", "example": "device_pinner", "enum": [ "device_pinner" @@ -27064,38 +26695,38 @@ ] }, "product_name": { - "type": "string", "description": "The type of device being pinned", + "type": "string", "example": "iPad" } - } + }, + "title": "Device pinner", + "x-box-resource-id": "device_pinner", + "x-box-tag": "device_pinners" }, "DevicePinners": { - "title": "Device pinners", - "type": "object", - "x-box-resource-id": "device_pinners", - "x-box-tag": "device_pinners", "description": "A list of device pins", + "type": "object", "properties": { "entries": { - "type": "array", "description": "A list of device pins", + "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" + "format": "int64", + "example": 200, + "default": 100 }, "next_marker": { "description": "The marker for the start of the next page of results.", - "example": 3000, "type": "integer", - "format": "int64" + "format": "int64", + "example": 3000 }, "order": { "description": "The order by which items are returned.", @@ -27106,15 +26737,15 @@ "properties": { "by": { "description": "The field that is ordered by", + "type": "string", "example": "id", "enum": [ "id" - ], - "type": "string" + ] }, "direction": { - "type": "string", "description": "The direction to order by, either ascending or descending", + "type": "string", "example": "asc", "enum": [ "asc", @@ -27124,97 +26755,97 @@ } } } - } + }, + "title": "Device pinners", + "x-box-resource-id": "device_pinners", + "x-box-tag": "device_pinners" }, "EmailAlias": { - "title": "Email alias", - "type": "object", - "x-box-resource-id": "email_alias", - "x-box-tag": "email_aliases", "description": "An email alias for a user.", + "type": "object", "properties": { "id": { - "type": "string", "description": "The unique identifier for this object", + "type": "string", "example": "11446498" }, "type": { - "type": "string", "description": "`email_alias`", + "type": "string", "example": "email_alias", "enum": [ "email_alias" ] }, "email": { - "type": "string", "description": "The email address", + "type": "string", "example": "alias@example.com" }, "is_confirmed": { - "type": "boolean", "description": "Whether the email address has been confirmed", + "type": "boolean", "example": true } - } + }, + "title": "Email alias", + "x-box-resource-id": "email_alias", + "x-box-tag": "email_aliases" }, "EmailAliases": { - "title": "Email aliases", - "type": "object", - "x-box-resource-id": "email_aliases", - "x-box-tag": "email_aliases", "description": "A list of email aliases", + "type": "object", "properties": { "total_count": { "description": "The number of email aliases.", - "example": 5000, "type": "integer", - "format": "int64" + "format": "int64", + "example": 5000 }, "entries": { - "type": "array", "description": "A list of email aliases", + "type": "array", "items": { "$ref": "#/components/schemas/EmailAlias" } } - } + }, + "title": "Email aliases", + "x-box-resource-id": "email_aliases", + "x-box-tag": "email_aliases" }, "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.", + "type": "object", "properties": { "id": { - "type": "string", "description": "The unique identifier for this enterprise", + "type": "string", "example": "1910967" }, "type": { - "type": "string", "description": "`enterprise`", + "type": "string", "example": "enterprise", - "nullable": false, "enum": [ "enterprise" - ] + ], + "nullable": false } - } + }, + "title": "Enterprise (Base)", + "x-box-resource-id": "enterprise--base", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "mini", + "standard", + "full" + ] }, "Event": { - "title": "Event", - "type": "object", - "x-box-resource-id": "event", - "x-box-tag": "events", "description": "The description of an event that happened within Box", + "type": "object", "properties": { "type": { "description": "`event`", @@ -27222,21 +26853,21 @@ "example": "event" }, "created_at": { + "description": "When the event object was created", "type": "string", "format": "date-time", - "description": "When the event object was created", "example": "2022-12-12T10:53:43-08:00" }, "recorded_at": { + "description": "When the event object was recorded in database", "type": "string", "format": "date-time", - "description": "When the event object was recorded in database", "example": "2022-12-12T10:54:43-08:00" }, "event_id": { + "description": "The ID of the event object. You can use this to detect duplicate events", "type": "string", - "example": "f82c3ba03e41f7e8a7608363cc6c0390183c3f83", - "description": "The ID of the event object. You can use this to detect duplicate events" + "example": "f82c3ba03e41f7e8a7608363cc6c0390183c3f83" }, "created_by": { "allOf": [ @@ -27399,9 +27030,9 @@ ] }, "session_id": { + "description": "The session of the user that performed the action. Not all events will\npopulate this attribute.", "type": "string", - "example": "70090280850c8d2a1933c1", - "description": "The session of the user that performed the action. Not all events will\npopulate this attribute." + "example": "70090280850c8d2a1933c1" }, "source": { "allOf": [ @@ -27433,54 +27064,124 @@ ] }, "additional_details": { + "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.", "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." + } } - } + }, + "title": "Event", + "x-box-resource-id": "event", + "x-box-tag": "events" }, - "Events": { - "title": "Events", + "EventSource": { + "description": "The source file or folder that triggered an event in\nthe event stream.", "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" + "item_type": { + "description": "The type of the item that the event\nrepresents. Can be `file` or `folder`.\n", + "type": "string", + "example": "file", + "enum": [ + "file", + "folder" + ], + "nullable": false }, - "next_stream_position": { - "description": "The stream position of the start of the next page (chunk)\nof events.", - "example": "1152922976252290886", - "anyOf": [ - { - "type": "string" - }, - { - "type": "number" - } - ] + "item_id": { + "description": "The unique identifier that represents the\nitem.\n", + "type": "string", + "example": "560284318361", + "nullable": false }, - "entries": { - "type": "array", - "description": "A list of events", - "items": { - "$ref": "#/components/schemas/Event" - } - } - } - }, - "File": { - "title": "File", + "item_name": { + "description": "The name of the item.\n", + "type": "string", + "example": "report.pdf", + "nullable": false + }, + "classification": { + "description": "The object containing classification information for the item that\ntriggered the event. This field will not appear if the item does not\nhave a classification set.", + "type": "object", + "properties": { + "name": { + "description": "The classification's name", + "type": "string", + "example": "Top Secret" + } + } + }, + "parent": { + "allOf": [ + { + "$ref": "#/components/schemas/Folder--Mini" + }, + { + "description": "The optional folder that this folder is located within.\n\nThis value may be `null` for some folders such as the\nroot folder or the trash folder." + } + ], + "nullable": true + }, + "owned_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who owns this item." + }, + { + "nullable": false + } + ] + } + }, + "required": [ + "item_type", + "item_id", + "item_name" + ], + "title": "Event source", + "x-box-resource-id": "event_source" + }, + "Events": { + "description": "A list of event objects", "type": "object", - "x-box-resource-id": "file", - "x-box-variant": "standard", + "properties": { + "chunk_size": { + "description": "The number of events returned in this response.", + "type": "integer", + "format": "int64", + "example": 2 + }, + "next_stream_position": { + "description": "The stream position of the start of the next page (chunk)\nof events.", + "example": "1152922976252290886", + "anyOf": [ + { + "type": "string" + }, + { + "type": "number" + } + ] + }, + "entries": { + "description": "A list of events", + "type": "array", + "items": { + "$ref": "#/components/schemas/Event" + } + } + }, + "title": "Events", + "x-box-resource-id": "events", + "x-box-tag": "events" + }, + "File": { "description": "A standard representation of a file, as returned from any\nfile API endpoints by default", + "type": "object", "allOf": [ { "$ref": "#/components/schemas/File--Mini" @@ -27488,17 +27189,17 @@ { "properties": { "description": { - "type": "string", - "nullable": false, "description": "The optional description of this file.\nIf the description exceeds 255 characters, the first 255 characters\nare set as a file description and the rest of it is ignored.", + "type": "string", + "example": "Contract for Q1 renewal", "maxLength": 255, - "example": "Contract for Q1 renewal" + "nullable": false }, "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 + "type": "integer", + "example": 629644, + "nullable": false }, "path_collection": { "allOf": [ @@ -27513,18 +27214,18 @@ "properties": { "total_count": { "description": "The number of folders in this list.", - "example": 1, "type": "integer", "format": "int64", + "example": 1, "nullable": false }, "entries": { - "type": "array", "description": "The parent folders for this item", - "nullable": false, + "type": "array", "items": { "$ref": "#/components/schemas/Folder--Mini" - } + }, + "nullable": false } } }, @@ -27537,46 +27238,46 @@ ] }, "created_at": { + "description": "The date and time when the file was created on Box.", "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" + "example": "2012-12-12T10:53:43-08:00", + "nullable": false }, "modified_at": { + "description": "The date and time when the file was last updated on Box.", "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" + "example": "2012-12-12T10:53:43-08:00", + "nullable": false }, "trashed_at": { + "description": "The time at which this file was put in the trash.", "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": { + "description": "The time at which this file is expected to be purged\nfrom the trash.", "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": { + "description": "The date and time at which this file was originally\ncreated, which might be before it was uploaded to Box.", "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" + "example": "2012-12-12T10:53:43-08:00", + "nullable": true }, "content_modified_at": { + "description": "The date and time at which this file was last updated,\nwhich might be before it was uploaded to Box.", "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" + "example": "2012-12-12T10:53:43-08:00", + "nullable": true }, "created_by": { "allOf": [ @@ -27631,119 +27332,119 @@ ], "properties": { "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.", "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": { + "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.", "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 + "nullable": true, + "x-box-premium-feature": true }, "vanity_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.", "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.", + "type": "string", "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.", + "type": "string", + "example": "open", "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.", + "type": "string", + "example": "company", "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.", + "type": "string", + "example": "can_download", "enum": [ "can_edit", "can_download", "can_preview", "no_access" ], - "example": "can_download", "nullable": false }, "unshared_at": { + "description": "The date and time when this link will be unshared. This field can only be\nset by users with paid accounts.", "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.", + "type": "boolean", "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" - ], + "type": "object", "properties": { "can_download": { + "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`.", "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`." + "nullable": false }, "can_preview": { + "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.", "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." + "nullable": false }, "can_edit": { + "description": "Defines if the shared link allows for the item to be edited.\n\nThis value can only be `true` if `can_download` is also `true` and if\nthe item has a type of `file`.", "type": "boolean", "example": false, - "nullable": false, - "description": "Defines if the shared link allows for the item to be edited.\n\nThis value can only be `true` if `can_download` is also `true` and if\nthe item has a type of `file`." + "nullable": false } - } + }, + "required": [ + "can_download", + "can_preview", + "can_edit" + ] }, "download_count": { + "description": "The number of times this item has been downloaded.", "type": "integer", "example": 3, - "description": "The number of times this item has been downloaded.", "nullable": false }, "preview_count": { + "description": "The number of times this item has been previewed.", "type": "integer", "example": 3, - "description": "The number of times this item has been previewed.", "nullable": false } } @@ -27768,72 +27469,68 @@ "nullable": true }, "item_status": { - "type": "string", "description": "Defines if this item has been deleted or not.\n\n* `active` when the item has is not in the trash\n* `trashed` when the item has been moved to the trash but not deleted\n* `deleted` when the item has been permanently deleted.", + "type": "string", + "example": "active", "enum": [ "active", "trashed", "deleted" ], - "nullable": false, - "example": "active" - } - } - } - ] - }, - "FileConflict": { - "title": "File (Conflict)", - "type": "object", - "x-box-resource-id": "file_conflict", - "x-box-tag": null, - "description": "A representation of a file that is used to show", - "allOf": [ - { - "$ref": "#/components/schemas/File--Mini" - }, - { - "properties": { - "sha1": { - "type": "string", - "example": "85136C79CBF9FE36BB9D05D0639C70C265C18D37", - "description": "The SHA1 hash of the file." - }, - "file_version": { - "$ref": "#/components/schemas/FileVersion--Mini" + "nullable": false } } } - ] + ], + "title": "File", + "x-box-resource-id": "file", + "x-box-variant": "standard" }, - "Files": { - "title": "Files", + "File--Base": { + "description": "The bare basic representation of a file, the minimal\namount of fields returned when using the `fields` query\nparameter.", "type": "object", - "x-box-resource-id": "files", - "x-box-tag": "files", - "description": "A list of files", "properties": { - "total_count": { - "description": "The number of files.", - "example": 1, - "type": "integer", - "format": "int64" + "id": { + "description": "The unique identifier that represent 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`.", + "type": "string", + "example": "12345", + "nullable": false }, - "entries": { - "type": "array", - "description": "A list of files", - "items": { - "$ref": "#/components/schemas/File--Full" - } + "etag": { + "description": "The HTTP `etag` of this file. This can be used within some API\nendpoints in the `If-Match` and `If-None-Match` headers to only\nperform changes on the file if (no) changes have happened.", + "type": "string", + "example": "1", + "nullable": true + }, + "type": { + "description": "`file`", + "type": "string", + "example": "file", + "enum": [ + "file" + ], + "nullable": false } - } + }, + "nullable": true, + "required": [ + "id", + "type" + ], + "title": "File (Base)", + "x-box-resource-id": "file--base", + "x-box-tag": "files", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "mini", + "standard", + "full" + ] }, "File--Full": { - "title": "File (Full)", - "type": "object", - "x-box-resource-id": "file--full", - "x-box-variant": "full", "description": "A full representation of a file, as can be returned from any\nfile API endpoints by default", + "type": "object", "allOf": [ { "$ref": "#/components/schemas/File" @@ -27841,14 +27538,14 @@ { "properties": { "version_number": { + "description": "The version number of this file", "type": "string", - "example": "1", - "description": "The version number of this file" + "example": "1" }, "comment_count": { + "description": "The number of comments on this file", "type": "integer", - "example": 10, - "description": "The number of comments on this file" + "example": 10 }, "permissions": { "allOf": [ @@ -27877,38 +27574,38 @@ ], "properties": { "can_delete": { - "type": "boolean", "description": "Specifies if the current user can delete this item.", + "type": "boolean", "example": true, "nullable": false }, "can_download": { - "type": "boolean", "description": "Specifies if the current user can download this item.", + "type": "boolean", "example": true, "nullable": false }, "can_invite_collaborator": { - "type": "boolean", "description": "Specifies if the current user can invite new\nusers to collaborate on this item, and if the user can\nupdate the role of a user already collaborated on this\nitem.", + "type": "boolean", "example": true, "nullable": false }, "can_rename": { - "type": "boolean", "description": "Specifies if the user can rename this item.", + "type": "boolean", "example": true, "nullable": false }, "can_set_share_access": { - "type": "boolean", "description": "Specifies if the user can change the access level of an\nexisting shared link on this item.", + "type": "boolean", "example": true, "nullable": false }, "can_share": { - "type": "boolean", "description": "Specifies if the user can create a shared link for this item.", + "type": "boolean", "example": true, "nullable": false } @@ -27917,38 +27614,38 @@ { "properties": { "can_annotate": { - "type": "boolean", "description": "Specifies if the user can place annotations on this file.", + "type": "boolean", "example": true, "nullable": false }, "can_comment": { - "type": "boolean", "description": "Specifies if the user can place comments on this file.", + "type": "boolean", "example": true, "nullable": false }, "can_preview": { - "type": "boolean", "description": "Specifies if the user can preview this file.", + "type": "boolean", "example": true, "nullable": false }, "can_upload": { - "type": "boolean", "description": "Specifies if the user can upload a new version of this file.", + "type": "boolean", "example": true, "nullable": false }, "can_view_annotations_all": { - "type": "boolean", "description": "Specifies if the user view all annotations placed on this file", + "type": "boolean", "example": true, "nullable": false }, "can_view_annotations_self": { - "type": "boolean", "description": "Specifies if the user view annotations placed by themselves\non this file", + "type": "boolean", "example": true, "nullable": false } @@ -27991,13 +27688,13 @@ "description": "The lock held on a file. A lock prevents a file from being moved,\nrenamed, or otherwise changed by anyone else than the user who created the\nlock.", "properties": { "id": { - "type": "string", "description": "The unique identifier for this lock", + "type": "string", "example": "11446498" }, "type": { - "type": "string", "description": "`lock`", + "type": "string", "example": "lock", "enum": [ "lock" @@ -28014,32 +27711,32 @@ ] }, "created_at": { + "description": "The time this lock was created at.", "type": "string", "format": "date-time", - "example": "2012-12-12T10:53:43-08:00", - "description": "The time this lock was created at." + "example": "2012-12-12T10:53:43-08:00" }, "expired_at": { + "description": "The time this lock is to expire at, which might be in the past.", "type": "string", "format": "date-time", - "example": "2012-12-12T10:53:43-08:00", - "description": "The time this lock is to expire at, which might be in the past." + "example": "2012-12-12T10:53:43-08:00" }, "is_download_prevented": { + "description": "Whether or not the file can be downloaded while locked.", "type": "boolean", - "example": true, - "description": "Whether or not the file can be downloaded while locked." + "example": true }, "app_type": { - "type": "string", "description": "If the lock is managed by an application rather than a user, this\nfield identifies the type of the application that holds the lock.\nThis is an open enum and may be extended with additional values in\nthe future.", + "type": "string", + "example": "office_wopiplus", "enum": [ "gsuite", "office_wopi", "office_wopiplus", "other" ], - "example": "office_wopiplus", "nullable": true } } @@ -28051,14 +27748,14 @@ "nullable": true }, "extension": { + "description": "Indicates the (optional) file extension for this file. By default,\nthis is set to an empty string.", "type": "string", - "example": "pdf", - "description": "Indicates the (optional) file extension for this file. By default,\nthis is set to an empty string." + "example": "pdf" }, "is_package": { + "description": "Indicates if the file is a package. Packages are commonly used\nby Mac Applications and can include iWork files.", "type": "boolean", - "example": true, - "description": "Indicates if the file is a package. Packages are commonly used\nby Mac Applications and can include iWork files." + "example": true }, "expiring_embed_link": { "allOf": [ @@ -28072,28 +27769,28 @@ "description": "The basics of an access token", "properties": { "access_token": { + "description": "The requested access token.", "type": "string", "format": "token", - "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ", - "description": "The requested access token." + "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" }, "expires_in": { + "description": "The time in seconds by which this token will expire.", "type": "integer", "format": "int64", - "example": 3600, - "description": "The time in seconds by which this token will expire." + "example": 3600 }, "token_type": { + "description": "The type of access token returned.", "type": "string", + "example": "bearer", "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.", + "type": "array", "items": { "$ref": "#/components/schemas/FileOrFolderScope" } @@ -28103,10 +27800,10 @@ { "properties": { "url": { + "description": "The actual expiring embed URL for this file, constructed\nfrom the file ID and access tokens specified in this object.", "type": "string", "format": "url", - "example": "https://cloud.app.box.com/preview/expiring_embed/...", - "description": "The actual expiring embed URL for this file, constructed\nfrom the file ID and access tokens specified in this object." + "example": "https://cloud.app.box.com/preview/expiring_embed/..." } } } @@ -28124,8 +27821,8 @@ "description": "Details about the watermark applied to this item", "properties": { "is_watermarked": { - "type": "boolean", "description": "Specifies if this item has a watermark applied.", + "type": "boolean", "example": true, "nullable": false } @@ -28137,8 +27834,8 @@ ] }, "is_accessible_via_shared_link": { - "type": "boolean", "description": "Specifies if the file can be accessed\nvia the direct shared link or a shared link\nto a parent folder.", + "type": "boolean", "example": true, "enum": [ true, @@ -28146,12 +27843,8 @@ ] }, "allowed_invitee_roles": { - "type": "array", - "example": [ - "editor" - ], - "nullable": false, "description": "A list of the types of roles that user can be invited at\nwhen sharing this file.", + "type": "array", "items": { "type": "string", "enum": [ @@ -28163,19 +27856,23 @@ "viewer uploader", "co-owner" ] - } + }, + "example": [ + "editor" + ], + "nullable": false }, "is_externally_owned": { + "description": "Specifies if this file is owned by a user outside of the\nauthenticated enterprise.", "type": "boolean", "example": true, - "nullable": false, - "description": "Specifies if this file is owned by a user outside of the\nauthenticated enterprise." + "nullable": false }, "has_collaborations": { + "description": "Specifies if this file has any other collaborators.", "type": "boolean", "example": true, - "nullable": false, - "description": "Specifies if this file has any other collaborators." + "nullable": false }, "metadata": { "allOf": [ @@ -28223,11 +27920,11 @@ ] }, "expires_at": { + "description": "When the file will automatically be deleted", "type": "string", "format": "date-time", - "nullable": true, - "description": "When the file will automatically be deleted", - "example": "2012-12-12T10:53:43-08:00" + "example": "2012-12-12T10:53:43-08:00", + "nullable": true }, "representations": { "allOf": [ @@ -28237,37 +27934,37 @@ "type": "object", "properties": { "entries": { - "type": "array", "description": "A list of files", + "type": "array", "items": { "type": "object", "description": "A file representation", "properties": { "content": { - "type": "object", "description": "An object containing the URL that can be used to actually fetch\nthe representation.", "properties": { "url_template": { + "description": "The download URL that can be used to fetch the representation.\nMake sure to make an authenticated API call to this endpoint.\n\nThis URL is a template and will require the `{+asset_path}` to\nbe replaced by a path. In general, for unpaged representations\nit can be replaced by an empty string.\n\nFor paged representations, replace the `{+asset_path}` with the\npage to request plus the extension for the file, for example\n`1.pdf`.\n\nWhen requesting the download URL the following additional\nquery params can be passed along.\n\n* `set_content_disposition_type` - Sets the\n`Content-Disposition` header in the API response with the\nspecified disposition type of either `inline` or `attachment`.\nIf not supplied, the `Content-Disposition` header is not\nincluded in the response.\n\n* `set_content_disposition_filename` - Allows the application to\n define the representation's file name used in the\n `Content-Disposition` header. If not defined, the filename\n is derived from the source file name in Box combined with the\n extension of the representation.", "type": "string", - "example": "https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567", - "description": "The download URL that can be used to fetch the representation.\nMake sure to make an authenticated API call to this endpoint.\n\nThis URL is a template and will require the `{+asset_path}` to\nbe replaced by a path. In general, for unpaged representations\nit can be replaced by an empty string.\n\nFor paged representations, replace the `{+asset_path}` with the\npage to request plus the extension for the file, for example\n`1.pdf`.\n\nWhen requesting the download URL the following additional\nquery params can be passed along.\n\n* `set_content_disposition_type` - Sets the\n`Content-Disposition` header in the API response with the\nspecified disposition type of either `inline` or `attachment`.\nIf not supplied, the `Content-Disposition` header is not\nincluded in the response.\n\n* `set_content_disposition_filename` - Allows the application to\n define the representation's file name used in the\n `Content-Disposition` header. If not defined, the filename\n is derived from the source file name in Box combined with the\n extension of the representation." + "example": "https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567" } - } + }, + "type": "object" }, "info": { - "type": "object", "description": "An object containing the URL that can be used to fetch more info\non this representation.", + "type": "object", "properties": { "url": { + "description": "The API URL that can be used to get more info on this file\nrepresentation. Make sure to make an authenticated API call\nto this endpoint.", "type": "string", - "example": "https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048", - "description": "The API URL that can be used to get more info on this file\nrepresentation. Make sure to make an authenticated API call\nto this endpoint." + "example": "https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048" } } }, "properties": { - "type": "object", "description": "An object containing the size and type of this presentation.", + "type": "object", "properties": { "dimensions": { "type": "string", @@ -28288,15 +27985,16 @@ } }, "representation": { + "description": "Indicates the file type of the returned representation.", "type": "string", - "example": "png", - "description": "Indicates the file type of the returned representation." + "example": "png" }, "status": { - "type": "object", "description": "An object containing the status of this representation.", + "type": "object", "properties": { "state": { + "description": "The status of the representation.\n\n* `success` defines the representation as ready to be viewed.\n* `viewable` defines a video to be ready for viewing.\n* `pending` defines the representation as to be generated. Retry\n this endpoint to re-check the status.\n* `none` defines that the representation will be created when\n requested. Request the URL defined in the `info` object to\n trigger this generation.", "type": "string", "example": "success", "enum": [ @@ -28304,8 +28002,7 @@ "viewable", "pending", "none" - ], - "description": "The status of the representation.\n\n* `success` defines the representation as ready to be viewed.\n* `viewable` defines a video to be ready for viewing.\n* `pending` defines the representation as to be generated. Retry\n this endpoint to re-check the status.\n* `none` defines that the representation will be created when\n requested. Request the URL defined in the `info` object to\n trigger this generation." + ] } } } @@ -28326,19 +28023,19 @@ "description": "The classification applied to an item", "properties": { "name": { + "description": "The name of the classification", "type": "string", - "example": "Top Secret", - "description": "The name of the classification" + "example": "Top Secret" }, "definition": { + "description": "An explanation of the meaning of this classification.", "type": "string", - "example": "Content that should not be shared outside the company.", - "description": "An explanation of the meaning of this classification." + "example": "Content that should not be shared outside the company." }, "color": { + "description": "The color that is used to display the\nclassification label in a user-interface. Colors are defined by the admin\nor co-admin who created the classification in the Box web app.", "type": "string", - "example": "#FF0000", - "description": "The color that is used to display the\nclassification label in a user-interface. Colors are defined by the admin\nor co-admin who created the classification in the Box web app." + "example": "#FF0000" } } }, @@ -28362,19 +28059,15 @@ ] }, "disposition_at": { + "description": "The retention expiration timestamp for the given file", "type": "string", "format": "date-time", - "nullable": true, - "description": "The retention expiration timestamp for the given file", - "example": "2012-12-12T10:53:43-08:00" + "example": "2012-12-12T10:53:43-08:00", + "nullable": true }, "shared_link_permission_options": { - "type": "array", - "example": [ - "can_preview" - ], - "nullable": true, "description": "A list of the types of roles that user can be invited at\nwhen sharing this file.", + "type": "array", "items": { "type": "string", "enum": [ @@ -28382,25 +28075,28 @@ "can_download", "can_edit" ] - } + }, + "example": [ + "can_preview" + ], + "nullable": true }, "is_associated_with_app_item": { + "description": "This field will return true if the file or any ancestor of the file\nis associated with at least one app item. Note that this will return\ntrue even if the context user does not have access to the app item(s)\nassociated with the file.", "type": "boolean", "example": true, - "nullable": false, - "description": "This field will return true if the file or any ancestor of the file\nis associated with at least one app item. Note that this will return\ntrue even if the context user does not have access to the app item(s)\nassociated with the file." + "nullable": false } } } - ] + ], + "title": "File (Full)", + "x-box-resource-id": "file--full", + "x-box-variant": "full" }, "File--Mini": { - "title": "File (Mini)", - "type": "object", - "x-box-resource-id": "file--mini", - "x-box-variant": "mini", "description": "A mini representation of a file, used when\nnested under another resource.", - "nullable": true, + "type": "object", "allOf": [ { "$ref": "#/components/schemas/File--Base" @@ -28421,16 +28117,16 @@ ] }, "name": { - "type": "string", "description": "The name of the file", + "type": "string", "example": "Contract.pdf" }, "sha1": { + "description": "The SHA1 hash of the file. This can be used to compare the contents\nof a file on Box with a local file.", "type": "string", "format": "digest", - "nullable": false, "example": "85136C79CBF9FE36BB9D05D0639C70C265C18D37", - "description": "The SHA1 hash of the file. This can be used to compare the contents\nof a file on Box with a local file." + "nullable": false }, "file_version": { "allOf": [ @@ -28444,73 +28140,93 @@ } } } - ] - }, - "File--Base": { - "title": "File (Base)", - "type": "object", - "x-box-resource-id": "file--base", - "x-box-tag": "files", - "x-box-variants": [ - "base", - "mini", - "standard", - "full" ], - "x-box-variant": "base", "nullable": true, - "description": "The bare basic representation of a file, the minimal\namount of fields returned when using the `fields` query\nparameter.", - "required": [ - "id", - "type" + "title": "File (Mini)", + "x-box-resource-id": "file--mini", + "x-box-variant": "mini" + }, + "FileConflict": { + "description": "A representation of a file that is used to show", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/File--Mini" + }, + { + "properties": { + "sha1": { + "description": "The SHA1 hash of the file.", + "type": "string", + "example": "85136C79CBF9FE36BB9D05D0639C70C265C18D37" + }, + "file_version": { + "$ref": "#/components/schemas/FileVersion--Mini" + } + } + } ], + "title": "File (Conflict)", + "x-box-resource-id": "file_conflict", + "x-box-tag": null + }, + "FileOrFolderScope": { + "description": "A relation between a resource (file or folder) and the scopes for which the resource can be accessed", + "type": "object", "properties": { - "id": { - "type": "string", - "nullable": false, - "description": "The unique identifier that represent 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" - }, - "etag": { - "type": "string", - "example": "1", - "nullable": true, - "description": "The HTTP `etag` of this file. This can be used within some API\nendpoints in the `If-Match` and `If-None-Match` headers to only\nperform changes on the file if (no) changes have happened." - }, - "type": { + "scope": { + "description": "The scopes for the resource access", "type": "string", - "description": "`file`", - "example": "file", + "example": "item_download", "enum": [ - "file" - ], - "nullable": false + "annotation_edit", + "annotation_view_all", + "annotation_view_self", + "base_explorer", + "base_picker", + "base_preview", + "base_upload", + "item_delete", + "item_download", + "item_preview", + "item_rename", + "item_share", + "item_upload" + ] + }, + "object": { + "allOf": [ + { + "oneOf": [ + { + "$ref": "#/components/schemas/Folder--Mini" + }, + { + "$ref": "#/components/schemas/File--Mini" + } + ] + }, + { + "description": "The file or folder resource" + } + ] } - } + }, + "title": "File or folder scope" }, "FileRequest": { - "title": "File Request", - "type": "object", - "x-box-resource-id": "file_request", - "x-box-tag": "file_requests", "description": "A standard representation of a file request, as returned\nfrom any file request API endpoints by default.", - "required": [ - "id", - "type", - "folder", - "created_at", - "updated_at" - ], + "type": "object", "properties": { "id": { - "type": "string", "description": "The unique identifier for this file request.", - "readOnly": true, - "example": "42037322" + "type": "string", + "example": "42037322", + "readOnly": true }, "type": { - "type": "string", "description": "`file_request`", + "type": "string", "example": "file_request", "enum": [ "file_request" @@ -28518,39 +28234,39 @@ "readOnly": true }, "title": { - "type": "string", "description": "The title of file request. This is shown\nin the Box UI to users uploading files.\n\nThis defaults to title of the file request that was\ncopied to create this file request.", + "type": "string", "example": "Please upload documents" }, "description": { - "type": "string", - "nullable": true, "description": "The optional description of this file request. This is\nshown in the Box UI to users uploading files.\n\nThis defaults to description of the file request that was\ncopied to create this file request.", - "example": "Following documents are requested for your process" + "type": "string", + "example": "Following documents are requested for your process", + "nullable": true }, "status": { + "description": "The status of the file request. This defaults\nto `active`.\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 defaults to status of file request that was\ncopied to create this file request.", "type": "string", "example": "active", - "description": "The status of the file request. This defaults\nto `active`.\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 defaults to status of file request that was\ncopied to create this file request.", "enum": [ "active", "inactive" ] }, "is_email_required": { + "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 defaults to setting of file request that was\ncopied to create this file request.", "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 defaults to setting of file request that was\ncopied to create this file request." + "example": true }, "is_description_required": { + "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 defaults to setting of file request that was\ncopied to create this file request.", "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 defaults to setting of file request that was\ncopied to create this file request." + "example": true }, "expires_at": { + "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`.", "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`.", "example": "2020-09-28T10:53:43-08:00" }, "folder": { @@ -28565,16 +28281,16 @@ "nullable": false }, "url": { - "type": "string", "description": "The generated URL for this file request. This URL can be shared\nwith users to let them upload files to the associated folder.", + "type": "string", "example": "/f/19e57f40ace247278a8e3d336678c64a", "readOnly": true }, "etag": { + "description": "The HTTP `etag` of this file. This can be used in combination with\nthe `If-Match` header when updating a file request. By providing that\nheader, a change will only be performed on the file request if the `etag`\non the file request still matches the `etag` provided in the `If-Match`\nheader.", "type": "string", "example": "1", - "nullable": true, - "description": "The HTTP `etag` of this file. This can be used in combination with\nthe `If-Match` header when updating a file request. By providing that\nheader, a change will only be performed on the file request if the `etag`\non the file request still matches the `etag` provided in the `If-Match`\nheader." + "nullable": true }, "created_by": { "allOf": [ @@ -28587,11 +28303,11 @@ ] }, "created_at": { + "description": "The date and time when the file request was created.", "type": "string", "format": "date-time", - "nullable": false, - "description": "The date and time when the file request was created.", - "example": "2020-09-28T10:53:43-08:00" + "example": "2020-09-28T10:53:43-08:00", + "nullable": false }, "updated_by": { "allOf": [ @@ -28607,152 +28323,108 @@ ] }, "updated_at": { + "description": "The date and time when the file request was last updated.", "type": "string", "format": "date-time", - "nullable": false, - "description": "The date and time when the file request was last updated.", - "example": "2020-09-28T10:53:43-08:00" + "example": "2020-09-28T10:53:43-08:00", + "nullable": false } - } + }, + "required": [ + "id", + "type", + "folder", + "created_at", + "updated_at" + ], + "title": "File Request", + "x-box-resource-id": "file_request", + "x-box-tag": "file_requests" }, - "FilesUnderRetention": { - "title": "Files under retention", + "FileRequestCopyRequest": { + "description": "The request body to copy a file request.", "type": "object", - "x-box-resource-id": "files_under_retention", - "x-box-tag": "retention_policy_assignments", - "description": "A list of files under retention.", "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": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", - "type": "string", - "nullable": true - }, - "prev_marker": { - "description": "The marker for the start of the previous page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", - "type": "string", - "nullable": true - } - } + "$ref": "#/components/schemas/FileRequestUpdateRequest" }, { "properties": { - "entries": { - "type": "array", - "description": "A list of files", - "items": { - "$ref": "#/components/schemas/File--Mini" - } + "folder": { + "description": "The folder to associate the new file request to.", + "type": "object", + "properties": { + "type": { + "description": "`folder`", + "type": "string", + "example": "folder", + "enum": [ + "folder" + ] + }, + "id": { + "description": "The ID of the folder to associate the new\nfile request to.", + "type": "string", + "example": "42037322" + } + }, + "required": [ + "id" + ] } } } - ] + ], + "required": [ + "folder" + ], + "title": "File Request (Copy)" }, - "FilesOnHold": { - "title": "Files on hold", + "FileRequestUpdateRequest": { + "description": "The request body to update a file request.", "type": "object", - "x-box-resource-id": "files_on_hold", - "x-box-tag": "legal_hold_policy_assignments", - "description": "A list of files on hold for legal policy assignment", - "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": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", - "type": "string", - "nullable": true - }, - "prev_marker": { - "description": "The marker for the start of the previous page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", - "type": "string", - "nullable": true - } - } + "properties": { + "title": { + "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.", + "type": "string", + "example": "Please upload required documents" }, - { - "properties": { - "entries": { - "type": "array", - "description": "A list of files", - "items": { - "$ref": "#/components/schemas/File--Mini" - } - } - } - } - ] - }, - "FileVersionsOnHold": { - "title": "File versions on hold", - "type": "object", - "x-box-resource-id": "file_versions_on_hold", - "x-box-tag": "legal_hold_policy_assignments", - "description": "A list of files on hold for legal policy assignment", - "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": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", - "type": "string", - "nullable": true - }, - "prev_marker": { - "description": "The marker for the start of the previous page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", - "type": "string", - "nullable": true - } - } + "description": { + "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.", + "type": "string", + "example": "Please upload required documents" }, - { - "properties": { - "entries": { - "type": "array", - "description": "A list of file versions on hold.", - "items": { - "$ref": "#/components/schemas/FileVersion" - } - } - } + "status": { + "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.", + "type": "string", + "example": "active", + "enum": [ + "active", + "inactive" + ] + }, + "is_email_required": { + "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.", + "type": "boolean", + "example": true + }, + "is_description_required": { + "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.", + "type": "boolean", + "example": true + }, + "expires_at": { + "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.", + "type": "string", + "format": "date-time", + "example": "2020-09-28T10:53:43-08:00" } - ] + }, + "title": "File Request (Update)" }, "FileVersion": { - "title": "File version", - "type": "object", - "x-box-resource-id": "file_version", - "x-box-variant": "standard", "description": "A standard representation of a file version", + "type": "object", "allOf": [ { "$ref": "#/components/schemas/FileVersion--Mini" @@ -28760,26 +28432,26 @@ { "properties": { "name": { - "type": "string", "description": "The name of the file version", + "type": "string", "example": "tigers.jpeg" }, "size": { + "description": "Size of the file version in bytes", "type": "integer", "format": "int64", - "description": "Size of the file version in bytes", "example": 629644 }, "created_at": { + "description": "When the file version object was created", "type": "string", "format": "date-time", - "description": "When the file version object was created", "example": "2012-12-12T10:53:43-08:00" }, "modified_at": { + "description": "When the file version object was last updated", "type": "string", "format": "date-time", - "description": "When the file version object was last updated", "example": "2012-12-12T10:53:43-08:00" }, "modified_by": { @@ -28793,11 +28465,11 @@ ] }, "trashed_at": { - "type": "string", "description": "When the file version object was trashed.", + "type": "string", "format": "date-time", - "nullable": true, - "example": "2012-12-12T10:53:43-08:00" + "example": "2012-12-12T10:53:43-08:00", + "nullable": true }, "trashed_by": { "allOf": [ @@ -28810,11 +28482,11 @@ ] }, "restored_at": { - "type": "string", "description": "When the file version was restored from the trash.", + "type": "string", "format": "date-time", - "nullable": true, - "example": "2012-12-12T10:53:43-08:00" + "example": "2012-12-12T10:53:43-08:00", + "nullable": true }, "restored_by": { "allOf": [ @@ -28827,11 +28499,11 @@ ] }, "purged_at": { - "type": "string", "description": "When the file version object will be permanently deleted.", + "type": "string", "format": "date-time", - "nullable": true, - "example": "2012-12-12T10:53:43-08:00" + "example": "2012-12-12T10:53:43-08:00", + "nullable": true }, "uploader_display_name": { "allOf": [ @@ -28846,69 +28518,48 @@ } } } - ] - }, - "FileVersion--Mini": { - "title": "File version (Mini)", - "type": "object", - "x-box-resource-id": "file_version--mini", - "x-box-variant": "mini", - "description": "A mini representation of a file version, used when\nnested within another resource.", - "allOf": [ - { - "$ref": "#/components/schemas/FileVersion--Base" - }, - { - "properties": { - "sha1": { - "type": "string", - "description": "The SHA1 hash of this version of the file.", - "example": "134b65991ed521fcfe4724b7d814ab8ded5185dc" - } - } - } - ] + ], + "title": "File version", + "x-box-resource-id": "file_version", + "x-box-variant": "standard" }, "FileVersion--Base": { - "title": "File version (Base)", - "type": "object", - "x-box-resource-id": "file_version--base", - "x-box-variants": [ - "base", - "mini", - "standard", - "full" - ], - "x-box-variant": "base", "description": "The bare basic representation of a file version, the minimal\namount of fields returned when using the `fields` query\nparameter.", - "required": [ - "id", - "type" - ], + "type": "object", "properties": { "id": { - "type": "string", - "nullable": false, "description": "The unique identifier that represent a file version.", - "example": "12345" + "type": "string", + "example": "12345", + "nullable": false }, "type": { - "type": "string", "description": "`file_version`", + "type": "string", "example": "file_version", "enum": [ "file_version" ], "nullable": false } - } + }, + "required": [ + "id", + "type" + ], + "title": "File version (Base)", + "x-box-resource-id": "file_version--base", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "mini", + "standard", + "full" + ] }, "FileVersion--Full": { - "title": "File version (Full)", - "type": "object", - "x-box-resource-id": "file_version--full", - "x-box-variant": "full", "description": "A full representation of a file version, as can be returned from any\nfile version API endpoints by default", + "type": "object", "allOf": [ { "$ref": "#/components/schemas/FileVersion" @@ -28916,97 +28567,50 @@ { "properties": { "version_number": { + "description": "The version number of this file version", "type": "string", - "example": "1", - "description": "The version number of this file version" + "example": "1" } } } - ] + ], + "title": "File version (Full)", + "x-box-resource-id": "file_version--full", + "x-box-variant": "full" }, - "FileVersions": { - "title": "File versions", + "FileVersion--Mini": { + "description": "A mini representation of a file version, used when\nnested within another resource.", "type": "object", - "x-box-resource-id": "file_versions", - "x-box-tag": "file_versions", - "description": "A list of file versions", "allOf": [ { - "type": "object", - "description": "The part of an API response that describes pagination", + "$ref": "#/components/schemas/FileVersion--Base" + }, + { "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", - "description": "A list of file versions", - "items": { - "$ref": "#/components/schemas/FileVersion--Full" - } + "sha1": { + "description": "The SHA1 hash of this version of the file.", + "type": "string", + "example": "134b65991ed521fcfe4724b7d814ab8ded5185dc" } } } - ] + ], + "title": "File version (Mini)", + "x-box-resource-id": "file_version--mini", + "x-box-variant": "mini" }, "FileVersionLegalHold": { - "title": "File version legal hold", - "type": "object", - "x-box-resource-id": "file_version_legal_hold", - "x-box-tag": "file_version_legal_holds", "description": "File version legal hold is an entity representing all\nholds on a File Version.", + "type": "object", "properties": { "id": { - "type": "string", "description": "The unique identifier for this file version legal hold", + "type": "string", "example": "11446498" }, "type": { - "type": "string", "description": "`file_version_legal_hold`", + "type": "string", "example": "file_version_legal_hold", "enum": [ "file_version_legal_hold" @@ -29040,19 +28644,19 @@ } }, "deleted_at": { + "description": "Time that this File-Version-Legal-Hold was\ndeleted.", "type": "string", "format": "date-time", - "description": "Time that this File-Version-Legal-Hold was\ndeleted.", "example": "2012-12-12T10:53:43-08:00" } - } + }, + "title": "File version legal hold", + "x-box-resource-id": "file_version_legal_hold", + "x-box-tag": "file_version_legal_holds" }, "FileVersionLegalHolds": { - "title": "File version legal holds", - "type": "object", - "x-box-resource-id": "file_version_legal_holds", - "x-box-tag": "file_version_legal_holds", "description": "A list of file versions with legal holds.", + "type": "object", "allOf": [ { "type": "object", @@ -29060,20 +28664,20 @@ "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" + "format": "int64", + "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } @@ -29081,31 +28685,31 @@ { "properties": { "entries": { - "type": "array", "description": "A list of file version legal holds", + "type": "array", "items": { "$ref": "#/components/schemas/FileVersionLegalHold" } } } } - ] + ], + "title": "File version legal holds", + "x-box-resource-id": "file_version_legal_holds", + "x-box-tag": "file_version_legal_holds" }, "FileVersionRetention": { - "title": "File version retention", - "type": "object", - "x-box-resource-id": "file_version_retention", - "x-box-tag": "file_version_retentions", "description": "A retention policy blocks permanent deletion of content\nfor a specified amount of time. Admins can apply policies to\nspecified folders, or an entire enterprise. A file version retention\nis a record for a retained file version. To use this feature,\nyou must have the manage retention policies scope enabled for your\nAPI key in your application management console.\n\n**Note**:\nFile retention API is now **deprecated**. \nTo get information about files and file versions under retention,\nsee [files under retention](e://get-retention-policy-assignments-id-files-under-retention) or [file versions under retention](e://get-retention-policy-assignments-id-file-versions-under-retention) endpoints.", + "type": "object", "properties": { "id": { - "type": "string", "description": "The unique identifier for this file version retention.", + "type": "string", "example": "11446498" }, "type": { - "type": "string", "description": "`file_version_retention`", + "type": "string", "example": "file_version_retention", "enum": [ "file_version_retention" @@ -29132,15 +28736,15 @@ ] }, "applied_at": { + "description": "When this file version retention object was\ncreated", "type": "string", "format": "date-time", - "description": "When this file version retention object was\ncreated", "example": "2012-12-12T10:53:43-08:00" }, "disposition_at": { + "description": "When the retention expires on this file\nversion retention", "type": "string", "format": "date-time", - "description": "When the retention expires on this file\nversion retention", "example": "2012-12-12T10:53:43-08:00" }, "winning_retention_policy": { @@ -29153,14 +28757,126 @@ } ] } - } + }, + "title": "File version retention", + "x-box-resource-id": "file_version_retention", + "x-box-tag": "file_version_retentions" }, "FileVersionRetentions": { - "title": "File version retentions", + "description": "A list of file version retentions.\n\n**Note**:\nFile retention API is now **deprecated**. \nTo get information about files and file versions under retention,\nsee [files under retention](e://get-retention-policy-assignments-id-files-under-retention) or [file versions under retention](e://get-retention-policy-assignments-id-file-versions-under-retention) endpoints.", "type": "object", + "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.", + "type": "integer", + "format": "int64", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "description": "A list of file version retentions", + "type": "array", + "items": { + "$ref": "#/components/schemas/FileVersionRetention" + } + } + } + } + ], + "title": "File version retentions", "x-box-resource-id": "file_version_retentions", - "x-box-tag": "file_version_retentions", - "description": "A list of file version retentions.\n\n**Note**:\nFile retention API is now **deprecated**. \nTo get information about files and file versions under retention,\nsee [files under retention](e://get-retention-policy-assignments-id-files-under-retention) or [file versions under retention](e://get-retention-policy-assignments-id-file-versions-under-retention) endpoints.", + "x-box-tag": "file_version_retentions" + }, + "FileVersions": { + "description": "A list of file versions", + "type": "object", + "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.", + "type": "integer", + "format": "int64", + "example": 5000 + }, + "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.", + "type": "integer", + "format": "int64", + "example": 1000 + }, + "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.", + "type": "integer", + "format": "int64", + "example": 2000 + }, + "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", + "type": "string", + "example": "type" + }, + "direction": { + "description": "The direction to order by, either ascending or descending", + "type": "string", + "example": "ASC", + "enum": [ + "ASC", + "DESC" + ] + } + } + } + } + } + }, + { + "properties": { + "entries": { + "description": "A list of file versions", + "type": "array", + "items": { + "$ref": "#/components/schemas/FileVersion--Full" + } + } + } + } + ], + "title": "File versions", + "x-box-resource-id": "file_versions", + "x-box-tag": "file_versions" + }, + "FileVersionsOnHold": { + "description": "A list of files on hold for legal policy assignment", + "type": "object", "allOf": [ { "type": "object", @@ -29168,20 +28884,130 @@ "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" + "format": "int64", + "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", + "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "description": "A list of file versions on hold.", + "type": "array", + "items": { + "$ref": "#/components/schemas/FileVersion" + } + } + } + } + ], + "title": "File versions on hold", + "x-box-resource-id": "file_versions_on_hold", + "x-box-tag": "legal_hold_policy_assignments" + }, + "Files": { + "description": "A list of files", + "type": "object", + "properties": { + "total_count": { + "description": "The number of files.", + "type": "integer", + "format": "int64", + "example": 1 + }, + "entries": { + "description": "A list of files", + "type": "array", + "items": { + "$ref": "#/components/schemas/File--Full" + } + } + }, + "title": "Files", + "x-box-resource-id": "files", + "x-box-tag": "files" + }, + "FilesOnHold": { + "description": "A list of files on hold for legal policy assignment", + "type": "object", + "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.", + "type": "integer", + "format": "int64", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", + "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "description": "A list of files", + "type": "array", + "items": { + "$ref": "#/components/schemas/File--Mini" + } + } + } + } + ], + "title": "Files on hold", + "x-box-resource-id": "files_on_hold", + "x-box-tag": "legal_hold_policy_assignments" + }, + "FilesUnderRetention": { + "description": "A list of files under retention.", + "type": "object", + "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.", + "type": "integer", + "format": "int64", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } @@ -29189,22 +29015,22 @@ { "properties": { "entries": { + "description": "A list of files", "type": "array", - "description": "A list of file version retentions", "items": { - "$ref": "#/components/schemas/FileVersionRetention" + "$ref": "#/components/schemas/File--Mini" } } } } - ] + ], + "title": "Files under retention", + "x-box-resource-id": "files_under_retention", + "x-box-tag": "retention_policy_assignments" }, "Folder": { - "title": "Folder", - "type": "object", - "x-box-resource-id": "folder", - "x-box-variant": "standard", "description": "A standard representation of a folder, as returned from any\nfolder API endpoints by default", + "type": "object", "allOf": [ { "$ref": "#/components/schemas/Folder--Mini" @@ -29212,16 +29038,16 @@ { "properties": { "created_at": { + "description": "The date and time when the folder was created. This value may\nbe `null` for some folders such as the root folder or the trash\nfolder.", "type": "string", "format": "date-time", - "nullable": true, - "description": "The date and time when the folder was created. This value may\nbe `null` for some folders such as the root folder or the trash\nfolder.", - "example": "2012-12-12T10:53:43-08:00" + "example": "2012-12-12T10:53:43-08:00", + "nullable": true }, "modified_at": { + "description": "The date and time when the folder was last updated. This value may\nbe `null` for some folders such as the root folder or the trash\nfolder.", "type": "string", "format": "date-time", - "description": "The date and time when the folder was last updated. This value may\nbe `null` for some folders such as the root folder or the trash\nfolder.", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, @@ -29240,9 +29066,9 @@ ] }, "size": { + "description": "The folder size in bytes.\n\nBe careful parsing this integer as its\nvalue can get very large.", "type": "integer", "format": "int64", - "description": "The folder size in bytes.\n\nBe careful parsing this integer as its\nvalue can get very large.", "example": 629644, "nullable": false }, @@ -29259,18 +29085,18 @@ "properties": { "total_count": { "description": "The number of folders in this list.", - "example": 1, "type": "integer", "format": "int64", + "example": 1, "nullable": false }, "entries": { - "type": "array", "description": "The parent folders for this item", - "nullable": false, + "type": "array", "items": { "$ref": "#/components/schemas/Folder--Mini" - } + }, + "nullable": false } } }, @@ -29309,32 +29135,32 @@ ] }, "trashed_at": { + "description": "The time at which this folder was put in the trash.", "type": "string", "format": "date-time", - "description": "The time at which this folder was put in the trash.", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "purged_at": { + "description": "The time at which this folder is expected to be purged\nfrom the trash.", "type": "string", "format": "date-time", - "description": "The time at which this folder is expected to be purged\nfrom the trash.", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "content_created_at": { + "description": "The date and time at which this folder was originally\ncreated.", "type": "string", "format": "date-time", - "nullable": true, - "description": "The date and time at which this folder was originally\ncreated.", - "example": "2012-12-12T10:53:43-08:00" + "example": "2012-12-12T10:53:43-08:00", + "nullable": true }, "content_modified_at": { + "description": "The date and time at which this folder was last updated.", "type": "string", "format": "date-time", - "nullable": true, - "description": "The date and time at which this folder was last updated.", - "example": "2012-12-12T10:53:43-08:00" + "example": "2012-12-12T10:53:43-08:00", + "nullable": true }, "owned_by": { "allOf": [ @@ -29366,119 +29192,119 @@ ], "properties": { "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.", "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": { + "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.", "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 + "nullable": true, + "x-box-premium-feature": true }, "vanity_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.", "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.", + "type": "string", "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.", + "type": "string", + "example": "open", "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.", + "type": "string", + "example": "company", "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.", + "type": "string", + "example": "can_download", "enum": [ "can_edit", "can_download", "can_preview", "no_access" ], - "example": "can_download", "nullable": false }, "unshared_at": { + "description": "The date and time when this link will be unshared. This field can only be\nset by users with paid accounts.", "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.", + "type": "boolean", "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" - ], + "type": "object", "properties": { "can_download": { + "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`.", "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`." + "nullable": false }, "can_preview": { + "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.", "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." + "nullable": false }, "can_edit": { + "description": "Defines if the shared link allows for the item to be edited.\n\nThis value can only be `true` if `can_download` is also `true` and if\nthe item has a type of `file`.", "type": "boolean", "example": false, - "nullable": false, - "description": "Defines if the shared link allows for the item to be edited.\n\nThis value can only be `true` if `can_download` is also `true` and if\nthe item has a type of `file`." + "nullable": false } - } + }, + "required": [ + "can_download", + "can_preview", + "can_edit" + ] }, "download_count": { + "description": "The number of times this item has been downloaded.", "type": "integer", "example": 3, - "description": "The number of times this item has been downloaded.", "nullable": false }, "preview_count": { + "description": "The number of times this item has been previewed.", "type": "integer", "example": 3, - "description": "The number of times this item has been previewed.", "nullable": false } } @@ -29490,19 +29316,19 @@ "nullable": true }, "folder_upload_email": { - "type": "object", "description": "The `folder_upload_email` parameter is not `null` if one of the following options is **true**:\n\n * The **Allow uploads to this folder via email** and the **Only allow email uploads from collaborators in this folder** are [enabled for a folder in the Admin Console](https://support.box.com/hc/en-us/articles/360043697534-Upload-to-Box-Through-Email), and the user has at least **Upload** permissions granted.\n\n * The **Allow uploads to this folder via email** setting is enabled for a folder in the Admin Console, and the **Only allow email uploads from collaborators in this folder** setting is deactivated (unchecked).\n\nIf the conditions are not met, the parameter will have the following value: `folder_upload_email: null`", + "type": "object", "nullable": true, "properties": { "access": { + "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.", "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." + "nullable": false }, "email": { "description": "The optional upload email address for this folder.", @@ -29525,15 +29351,15 @@ "nullable": true }, "item_status": { - "type": "string", "description": "Defines if this item has been deleted or not.\n\n* `active` when the item has is not in the trash\n* `trashed` when the item has been moved to the trash but not deleted\n* `deleted` when the item has been permanently deleted.", + "type": "string", + "example": "active", "enum": [ "active", "trashed", "deleted" ], - "nullable": false, - "example": "active" + "nullable": false }, "item_collection": { "allOf": [ @@ -29550,14 +29376,55 @@ } } } + ], + "title": "Folder", + "x-box-resource-id": "folder", + "x-box-variant": "standard" + }, + "Folder--Base": { + "description": "The bare basic representation of a folder, the minimal\namount of fields returned when using the `fields` query\nparameter.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting a folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folders/123`\nthe `folder_id` is `123`.", + "type": "string", + "example": "12345", + "nullable": false + }, + "etag": { + "description": "The HTTP `etag` of this folder. This can be used within some API\nendpoints in the `If-Match` and `If-None-Match` headers to only\nperform changes on the folder if (no) changes have happened.", + "type": "string", + "example": "1", + "nullable": true + }, + "type": { + "description": "`folder`", + "type": "string", + "example": "folder", + "enum": [ + "folder" + ], + "nullable": false + } + }, + "required": [ + "id", + "type" + ], + "title": "Folder (Base)", + "x-box-resource-id": "folder--base", + "x-box-tag": "folders", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "mini", + "standard", + "full" ] }, "Folder--Full": { - "title": "Folder (Full)", - "type": "object", - "x-box-resource-id": "folder--full", - "x-box-variant": "full", "description": "A full representation of a folder, as can be returned from any\nfolder API endpoints by default", + "type": "object", "allOf": [ { "$ref": "#/components/schemas/Folder" @@ -29580,10 +29447,10 @@ ] }, "has_collaborations": { + "description": "Specifies if this folder has any other collaborators.", "type": "boolean", "example": true, - "nullable": false, - "description": "Specifies if this folder has any other collaborators." + "nullable": false }, "permissions": { "allOf": [ @@ -29607,38 +29474,38 @@ ], "properties": { "can_delete": { - "type": "boolean", "description": "Specifies if the current user can delete this item.", + "type": "boolean", "example": true, "nullable": false }, "can_download": { - "type": "boolean", "description": "Specifies if the current user can download this item.", + "type": "boolean", "example": true, "nullable": false }, "can_invite_collaborator": { - "type": "boolean", "description": "Specifies if the current user can invite new\nusers to collaborate on this item, and if the user can\nupdate the role of a user already collaborated on this\nitem.", + "type": "boolean", "example": true, "nullable": false }, "can_rename": { - "type": "boolean", "description": "Specifies if the user can rename this item.", + "type": "boolean", "example": true, "nullable": false }, "can_set_share_access": { - "type": "boolean", "description": "Specifies if the user can change the access level of an\nexisting shared link on this item.", + "type": "boolean", "example": true, "nullable": false }, "can_share": { - "type": "boolean", "description": "Specifies if the user can create a shared link for this item.", + "type": "boolean", "example": true, "nullable": false } @@ -29647,8 +29514,8 @@ { "properties": { "can_upload": { - "type": "boolean", "description": "Specifies if the user can upload into this folder.", + "type": "boolean", "example": true, "nullable": false } @@ -29696,10 +29563,10 @@ ] }, "is_externally_owned": { + "description": "Specifies if this folder is owned by a user outside of the\nauthenticated enterprise.", "type": "boolean", "example": true, - "nullable": false, - "description": "Specifies if this folder is owned by a user outside of the\nauthenticated enterprise." + "nullable": false }, "metadata": { "allOf": [ @@ -29759,10 +29626,8 @@ ] }, "allowed_shared_link_access_levels": { + "description": "A list of access levels that are available\nfor this folder.\n\nFor some folders, like the root folder, this will always\nbe an empty list as sharing is not allowed at that level.", "type": "array", - "example": [ - "open" - ], "items": { "type": "string", "enum": [ @@ -29771,16 +29636,14 @@ "collaborators" ] }, - "nullable": false, - "description": "A list of access levels that are available\nfor this folder.\n\nFor some folders, like the root folder, this will always\nbe an empty list as sharing is not allowed at that level." - }, - "allowed_invitee_roles": { - "type": "array", "example": [ - "editor" + "open" ], - "nullable": false, + "nullable": false + }, + "allowed_invitee_roles": { "description": "A list of the types of roles that user can be invited at\nwhen sharing this folder.", + "type": "array", "items": { "type": "string", "enum": [ @@ -29792,7 +29655,11 @@ "viewer uploader", "co-owner" ] - } + }, + "example": [ + "editor" + ], + "nullable": false }, "watermark_info": { "allOf": [ @@ -29801,8 +29668,8 @@ "description": "Details about the watermark applied to this item", "properties": { "is_watermarked": { - "type": "boolean", "description": "Specifies if this item has a watermark applied.", + "type": "boolean", "example": true, "nullable": false } @@ -29817,8 +29684,8 @@ ] }, "is_accessible_via_shared_link": { - "type": "boolean", "description": "Specifies if the folder can be accessed\nwith the direct shared link or a shared link\nto a parent folder.", + "type": "boolean", "example": true, "enum": [ true, @@ -29826,9 +29693,9 @@ ] }, "can_non_owners_view_collaborators": { + "description": "Specifies if collaborators who are not owners\nof this folder are restricted from viewing other\ncollaborations on this folder.\n\nIt also restricts non-owners from inviting new\ncollaborators.", "type": "boolean", - "example": true, - "description": "Specifies if collaborators who are not owners\nof this folder are restricted from viewing other\ncollaborations on this folder.\n\nIt also restricts non-owners from inviting new\ncollaborators." + "example": true }, "classification": { "allOf": [ @@ -29837,19 +29704,19 @@ "description": "The classification applied to an item", "properties": { "name": { + "description": "The name of the classification", "type": "string", - "example": "Top Secret", - "description": "The name of the classification" + "example": "Top Secret" }, "definition": { + "description": "An explanation of the meaning of this classification.", "type": "string", - "example": "Content that should not be shared outside the company.", - "description": "An explanation of the meaning of this classification." + "example": "Content that should not be shared outside the company." }, "color": { + "description": "The color that is used to display the\nclassification label in a user-interface. Colors are defined by the admin\nor co-admin who created the classification in the Box web app.", "type": "string", - "example": "#FF0000", - "description": "The color that is used to display the\nclassification label in a user-interface. Colors are defined by the admin\nor co-admin who created the classification in the Box web app." + "example": "#FF0000" } } }, @@ -29862,21 +29729,21 @@ ] }, "is_associated_with_app_item": { + "description": "This field will return true if the folder or any ancestor of the\nfolder is associated with at least one app item. Note that this will\nreturn true even if the context user does not have access to the\napp item(s) associated with the folder.", "type": "boolean", "example": true, - "nullable": false, - "description": "This field will return true if the folder or any ancestor of the\nfolder is associated with at least one app item. Note that this will\nreturn true even if the context user does not have access to the\napp item(s) associated with the folder." + "nullable": false } } } - ] + ], + "title": "Folder (Full)", + "x-box-resource-id": "folder--full", + "x-box-variant": "full" }, "Folder--Mini": { - "title": "Folder (Mini)", - "type": "object", - "x-box-resource-id": "folder--mini", - "x-box-variant": "mini", "description": "A mini representation of a file version, used when\nnested under another resource.", + "type": "object", "allOf": [ { "$ref": "#/components/schemas/Folder--Base" @@ -29897,62 +29764,21 @@ ] }, "name": { - "type": "string", "description": "The name of the folder.", + "type": "string", "example": "Contracts", "nullable": false } } } - ] - }, - "Folder--Base": { - "title": "Folder (Base)", - "type": "object", - "x-box-resource-id": "folder--base", - "x-box-tag": "folders", - "x-box-variants": [ - "base", - "mini", - "standard", - "full" - ], - "x-box-variant": "base", - "description": "The bare basic representation of a folder, the minimal\namount of fields returned when using the `fields` query\nparameter.", - "required": [ - "id", - "type" ], - "properties": { - "id": { - "type": "string", - "nullable": false, - "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting a folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folders/123`\nthe `folder_id` is `123`.", - "example": "12345" - }, - "etag": { - "type": "string", - "nullable": true, - "example": "1", - "description": "The HTTP `etag` of this folder. This can be used within some API\nendpoints in the `If-Match` and `If-None-Match` headers to only\nperform changes on the folder if (no) changes have happened." - }, - "type": { - "type": "string", - "description": "`folder`", - "example": "folder", - "enum": [ - "folder" - ], - "nullable": false - } - } + "title": "Folder (Mini)", + "x-box-resource-id": "folder--mini", + "x-box-variant": "mini" }, "FolderLock": { - "title": "Folder Lock", - "type": "object", - "x-box-resource-id": "folder_lock", - "x-box-tag": "folder_locks", "description": "Folder locks define access restrictions placed by folder owners\nto prevent specific folders from being moved or deleted.", + "type": "object", "properties": { "folder": { "allOf": [ @@ -29965,13 +29791,13 @@ ] }, "id": { - "type": "string", "description": "The unique identifier for this folder lock.", + "type": "string", "example": "12345678" }, "type": { - "type": "string", "description": "The object type, always `folder_lock`.", + "type": "string", "example": "folder_lock" }, "created_by": { @@ -29985,72 +29811,73 @@ ] }, "created_at": { + "description": "When the folder lock object was created.", "type": "string", "format": "date-time", - "example": "2020-09-14T23:12:53Z", - "description": "When the folder lock object was created." + "example": "2020-09-14T23:12:53Z" }, "locked_operations": { - "type": "object", "description": "The operations that have been locked. Currently the `move`\nand `delete` operations cannot be locked separately, and both need to be\nset to `true`.\n", - "required": [ - "move", - "delete" - ], + "type": "object", "properties": { "move": { - "type": "boolean", "description": "Whether moving the folder is restricted.", - "nullable": false, - "example": true + "type": "boolean", + "example": true, + "nullable": false }, "delete": { - "type": "boolean", "description": "Whether deleting the folder is restricted.", + "example": true, "nullable": false, - "example": true + "type": "boolean" } - } + }, + "required": [ + "move", + "delete" + ] }, "lock_type": { - "type": "string", "description": "The lock type, always `freeze`.", + "type": "string", "example": "freeze" } - } + }, + "title": "Folder Lock", + "x-box-resource-id": "folder_lock", + "x-box-tag": "folder_locks" }, "FolderLocks": { - "title": "Folder Locks", - "type": "object", - "x-box-resource-id": "folder_locks", - "x-box-tag": "folder_locks", "description": "A list of folder locks", + "type": "object", "properties": { "entries": { - "type": "array", "description": "A list of folder locks", + "type": "array", "items": { "$ref": "#/components/schemas/FolderLock" } }, "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": "string" + "type": "string", + "example": "1000" }, "next_marker": { "description": "The marker for the start of the next page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true } - } + }, + "title": "Folder Locks", + "x-box-resource-id": "folder_locks", + "x-box-tag": "folder_locks" }, "GenericSource": { - "title": "Generic source", - "type": "object", - "x-box-resource-id": "generic_source", "description": "A generic event source type.", + "type": "object", "additionalProperties": { "allOf": [ {}, @@ -30058,321 +29885,74 @@ "description": "A definition of a generic\nevent source object. The set of\nparameters depends on the\nobject type. For example, a Box Shield\nevent source would have the following\nset of parameters:\n```yaml\n{\n\"barrier_id\": 123456,\n\"barrier_status\": \"ENABLED\",\n\"barrier_segments\": [\n {\n \"name\": \"8\",\n \"member_count\": 1\n },\n {\n \"name\": \"9\",\n \"member_count\": 1\n }\n ]\n} \n```\n" } ] - } + }, + "title": "Generic source", + "x-box-resource-id": "generic_source" }, - "IntegrationMapping": { - "title": "Integration mapping Slack", + "Group": { + "description": "A standard representation of a group, as returned from any\ngroup API endpoints by default", "type": "object", - "x-box-resource-id": "integration_mapping_slack", - "x-box-tag": "integration_mappings", - "x-box-variant": "standard", - "description": "A Slack specific representation of an integration\nmapping object.", "allOf": [ { - "$ref": "#/components/schemas/IntegrationMapping--Base" - }, - { - "properties": { - "integration_type": { - "type": "string", - "nullable": false, - "description": "Identifies the Box partner app,\nwith which the mapping is associated.\nCurrently only supports Slack.\n(part of the composite key together with `id`)", - "example": "slack", - "enum": [ - "slack" - ] - }, - "partner_item": { - "oneOf": [ - { - "$ref": "#/components/schemas/IntegrationMappingPartnerItemSlack" - } - ], - "nullable": false, - "example": { - "id": "C12378991223", - "type": "channel", - "slack_org_id": "E1234567" - }, - "description": "Mapped item object for Slack or Teams" - } - } + "$ref": "#/components/schemas/Group--Mini" }, { - "type": "object", "properties": { - "box_item": { - "allOf": [ - { - "$ref": "#/components/schemas/Folder--Mini" - } - ], - "description": "The Box folder, to which the object from the\npartner app domain (referenced in `partner_item_id`) is mapped", - "nullable": false - }, - "is_manually_created": { - "type": "boolean", - "example": true, - "description": "Identifies whether the mapping has\nbeen manually set\n(as opposed to being automatically created)", - "nullable": false - }, - "options": { - "nullable": false, - "allOf": [ - { - "$ref": "#/components/schemas/IntegrationMappingSlackOptions" - } - ] - }, - "created_by": { - "allOf": [ - { - "$ref": "#/components/schemas/UserIntegrationMappings" - } - ], - "description": "An object representing the user who\ncreated the integration mapping", - "nullable": false - }, - "modified_by": { - "allOf": [ - { - "$ref": "#/components/schemas/UserIntegrationMappings" - } - ], - "description": "The user who\nlast modified the integration mapping", - "nullable": false - }, "created_at": { + "description": "When the group object was created", "type": "string", "format": "date-time", - "description": "When the integration mapping object was created", - "example": "2012-12-12T10:53:43-08:00", - "nullable": false + "example": "2012-12-12T10:53:43-08:00" }, "modified_at": { + "description": "When the group object was last modified", "type": "string", "format": "date-time", - "description": "When the integration mapping object was last modified", - "example": "2012-12-12T10:53:43-08:00", - "nullable": false + "example": "2012-12-12T10:53:43-08:00" } - }, - "required": [ - "box_item" - ] + } } ], - "required": [ - "partner_item" - ] + "title": "Group", + "x-box-resource-id": "group", + "x-box-variant": "standard" }, - "IntegrationMapping--Base": { - "title": "Integration mapping (Base)", + "Group--Base": { + "description": "A base representation of a group.", "type": "object", - "x-box-resource-id": "integration_mapping--base", - "x-box-tag": "integration_mappings", - "x-box-variant": "base", - "x-box-variants": [ - "base", - "standard", - "mini" - ], - "description": "A base representation of an\nintegration mapping object.", "properties": { "id": { + "description": "The unique identifier for this object", "type": "string", - "nullable": false, - "example": "12345", - "description": "A unique identifier of a folder mapping\n(part of a composite key together\nwith `integration_type`)" + "example": "11446498" }, "type": { + "description": "`group`", "type": "string", - "example": "integration_mapping", + "example": "group", "enum": [ - "integration_mapping" - ], - "description": "Mapping type", - "nullable": false + "group" + ] } }, "required": [ "id", "type" - ] - }, - "IntegrationMappings": { - "title": "Integration mappings Slack", - "type": "object", - "x-box-resource-id": "integration_mappings_slack", - "x-box-tag": "integration_mappings", - "description": "A list of integration mapping\nobjects.", - "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": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", - "type": "string", - "nullable": true - } - } - }, - { - "properties": { - "entries": { - "type": "array", - "description": "A list of integration mappings", - "items": { - "$ref": "#/components/schemas/IntegrationMapping" - } - } - } - } - ] - }, - "Group": { - "title": "Group", - "type": "object", - "x-box-resource-id": "group", - "x-box-variant": "standard", - "description": "A standard representation of a group, as returned from any\ngroup API endpoints by default", - "allOf": [ - { - "$ref": "#/components/schemas/Group--Mini" - }, - { - "properties": { - "created_at": { - "type": "string", - "format": "date-time", - "description": "When the group object was created", - "example": "2012-12-12T10:53:43-08:00" - }, - "modified_at": { - "type": "string", - "format": "date-time", - "description": "When the group object was last modified", - "example": "2012-12-12T10:53:43-08:00" - } - } - } - ] - }, - "Groups": { - "title": "Groups", - "type": "object", - "x-box-resource-id": "groups", - "x-box-tag": "groups", - "description": "A list of groups.", - "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", - "description": "A list of groups", - "items": { - "$ref": "#/components/schemas/Group--Full" - } - } - } - } - ] - }, - "Group--Base": { + ], "title": "Group (Base)", - "type": "object", "x-box-resource-id": "group--base", "x-box-tag": "groups", + "x-box-variant": "base", "x-box-variants": [ "base", "mini", "standard", "full" - ], - "x-box-variant": "base", - "description": "A base representation of a group.", - "required": [ - "id", - "type" - ], - "properties": { - "id": { - "type": "string", - "description": "The unique identifier for this object", - "example": "11446498" - }, - "type": { - "type": "string", - "description": "`group`", - "example": "group", - "enum": [ - "group" - ] - } - } + ] }, "Group--Full": { - "title": "Group (Full)", - "type": "object", - "x-box-resource-id": "group--full", - "x-box-variant": "full", "description": "Groups contain a set of users, and can be used in place of\nusers in some operations, such as collaborations.", + "type": "object", "allOf": [ { "$ref": "#/components/schemas/Group" @@ -30380,26 +29960,26 @@ { "properties": { "provenance": { - "type": "string", "description": "Keeps track of which external source this group is\ncoming from (e.g. \"Active Directory\", \"Google Groups\",\n\"Facebook Groups\"). Setting this will\nalso prevent Box users from editing the group name\nand its members directly via the Box web application.\nThis is desirable for one-way syncing of groups.", - "maxLength": 255, - "example": "Active Directory" + "type": "string", + "example": "Active Directory", + "maxLength": 255 }, "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. Example values of this field\ncould be an Active Directory Object ID or a Google\nGroup ID. We recommend you use of this field in\norder to avoid issues when group names are updated in\neither Box or external systems.", + "type": "string", "example": "AD:123456" }, "description": { - "type": "string", "description": "Human readable description of the group.", - "maxLength": 255, - "example": "Support Group - as imported from Active Directory" + "type": "string", + "example": "Support Group - as imported from Active Directory", + "maxLength": 255 }, "invitability_level": { + "description": "Specifies who can invite the group to collaborate\non items.\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.", "type": "string", "example": "admins_only", - "description": "Specifies who can invite the group to collaborate\non items.\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", @@ -30407,9 +29987,9 @@ ] }, "member_viewability_level": { + "description": "Specifies who can view the members of the group\n(Get Memberships for 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", "type": "string", "example": "admins_only", - "description": "Specifies who can view the members of the group\n(Get Memberships for 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", @@ -30423,8 +30003,8 @@ "description": "The permissions that the authenticated user has for a group.", "properties": { "can_invite_as_collaborator": { - "type": "boolean", "description": "Specifies if the user can invite the group to collaborate on any items.", + "type": "boolean", "example": true } } @@ -30436,14 +30016,14 @@ } } } - ] + ], + "title": "Group (Full)", + "x-box-resource-id": "group--full", + "x-box-variant": "full" }, "Group--Mini": { - "title": "Group (Mini)", - "type": "object", - "x-box-resource-id": "group--mini", - "x-box-variant": "mini", "description": "Mini representation of a group, including id and name of\ngroup.", + "type": "object", "allOf": [ { "$ref": "#/components/schemas/Group--Base" @@ -30451,13 +30031,13 @@ { "properties": { "name": { - "type": "string", "description": "The name of the group", + "type": "string", "example": "Support" }, "group_type": { - "type": "string", "description": "The type of the group.", + "type": "string", "example": "managed_group", "enum": [ "managed_group", @@ -30466,23 +30046,23 @@ } } } - ] + ], + "title": "Group (Mini)", + "x-box-resource-id": "group--mini", + "x-box-variant": "mini" }, "GroupMembership": { - "title": "Group membership", - "type": "object", - "x-box-resource-id": "group_membership", - "x-box-tag": "memberships", "description": "Membership is used to signify that a user is part of a\ngroup.", + "type": "object", "properties": { "id": { - "type": "string", "description": "The unique identifier for this group membership", + "type": "string", "example": "11446498" }, "type": { - "type": "string", "description": "`group_membership`", + "type": "string", "example": "group_membership", "enum": [ "group_membership" @@ -30509,34 +30089,34 @@ ] }, "role": { + "description": "The role of the user in the group.", "type": "string", "example": "member", - "description": "The role of the user in the group.", "enum": [ "member", "admin" ] }, "created_at": { + "description": "The time this membership was created.", "type": "string", "format": "date-time", - "description": "The time this membership was created.", "example": "2012-12-12T10:53:43-08:00" }, "modified_at": { + "description": "The time this membership was last modified.", "type": "string", "format": "date-time", - "description": "The time this membership was last modified.", "example": "2012-12-12T10:53:43-08:00" } - } + }, + "title": "Group membership", + "x-box-resource-id": "group_membership", + "x-box-tag": "memberships" }, "GroupMemberships": { - "title": "Group memberships", - "type": "object", - "x-box-resource-id": "group_memberships", - "x-box-tag": "memberships", "description": "A list of group memberships.", + "type": "object", "allOf": [ { "type": "object", @@ -30544,21 +30124,21 @@ "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" + "format": "int64", + "example": 5000 }, "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" + "format": "int64", + "example": 1000 }, "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" + "format": "int64", + "example": 2000 }, "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.", @@ -30569,12 +30149,12 @@ "properties": { "by": { "description": "The field to order by", - "example": "type", - "type": "string" + "type": "string", + "example": "type" }, "direction": { - "type": "string", "description": "The direction to order by, either ascending or descending", + "type": "string", "example": "ASC", "enum": [ "ASC", @@ -30589,142 +30169,44 @@ { "properties": { "entries": { - "type": "array", "description": "A list of group memberships", + "type": "array", "items": { "$ref": "#/components/schemas/GroupMembership" } } } } - ] + ], + "title": "Group memberships", + "x-box-resource-id": "group_memberships", + "x-box-tag": "memberships" }, - "Invite": { - "title": "Invite", + "Groups": { + "description": "A list of groups.", "type": "object", - "x-box-resource-id": "invite", - "x-box-tag": "invites", - "description": "An invite for a user to an enterprise.", - "required": [ - "id", - "type" - ], - "properties": { - "id": { - "type": "string", - "description": "The unique identifier for this invite", - "example": "11446498" - }, - "type": { - "type": "string", - "description": "`invite`", - "example": "invite", - "enum": [ - "invite" - ] - }, - "invited_to": { - "title": "Enterprise", + "allOf": [ + { "type": "object", - "description": "A representation of a Box enterprise", + "description": "The part of an API response that describes pagination", "properties": { - "id": { - "type": "string", - "description": "The unique identifier for this enterprise.", - "example": "11446498" + "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.", + "type": "integer", + "format": "int64", + "example": 5000 }, - "type": { - "type": "string", - "description": "`enterprise`", - "example": "enterprise", - "enum": [ - "enterprise" - ] - }, - "name": { - "description": "The name of the enterprise", - "example": "Acme Inc.", - "type": "string" - } - } - }, - "actionable_by": { - "$ref": "#/components/schemas/User--Mini" - }, - "invited_by": { - "$ref": "#/components/schemas/User--Mini" - }, - "status": { - "description": "The status of the invite", - "type": "string", - "example": "pending" - }, - "created_at": { - "type": "string", - "format": "date-time", - "description": "When the invite was created", - "example": "2012-12-12T10:53:43-08:00" - }, - "modified_at": { - "type": "string", - "format": "date-time", - "description": "When the invite was modified.", - "example": "2012-12-12T10:53:43-08:00" - } - } - }, - "Items": { - "title": "Items", - "type": "object", - "x-box-resource-id": "items", - "x-box-tag": "folders", - "description": "A list of files, folders, and web links in\ntheir mini representation.", - "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": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", - "type": "string", - "nullable": true - }, - "prev_marker": { - "description": "The marker for the start of the previous page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", - "type": "string", - "nullable": true - } - } - }, - { - "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" + "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.", + "type": "integer", + "format": "int64", + "example": 1000 }, "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" + "format": "int64", + "example": 2000 }, "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.", @@ -30735,12 +30217,12 @@ "properties": { "by": { "description": "The field to order by", - "example": "type", - "type": "string" + "type": "string", + "example": "type" }, "direction": { - "type": "string", "description": "The direction to order by, either ascending or descending", + "type": "string", "example": "ASC", "enum": [ "ASC", @@ -30755,317 +30237,286 @@ { "properties": { "entries": { - "description": "The items in this collection.", + "description": "A list of groups", "type": "array", "items": { - "oneOf": [ - { - "$ref": "#/components/schemas/File--Full" - }, - { - "$ref": "#/components/schemas/Folder--Mini" - }, - { - "$ref": "#/components/schemas/WebLink" - } - ] + "$ref": "#/components/schemas/Group--Full" } } } } - ] + ], + "title": "Groups", + "x-box-resource-id": "groups", + "x-box-tag": "groups" }, - "LegalHoldPolicy": { - "title": "Legal hold policy", + "IntegrationMapping": { + "description": "A Slack specific representation of an integration\nmapping object.", "type": "object", - "x-box-resource-id": "legal_hold_policy", - "x-box-variant": "standard", - "description": "Legal Hold Policy information describes the basic\ncharacteristics of the Policy, such as name, description,\nand filter dates.", "allOf": [ { - "$ref": "#/components/schemas/LegalHoldPolicy--Mini" + "$ref": "#/components/schemas/IntegrationMapping--Base" }, { "properties": { - "policy_name": { - "type": "string", - "example": "Policy 4", - "description": "Name of the legal hold policy.", - "maxLength": 254 - }, - "description": { - "type": "string", - "description": "Description of the legal hold policy. Optional\nproperty with a 500 character limit.", - "maxLength": 500, - "example": "Postman created policy" - }, - "status": { + "integration_type": { + "description": "Identifies the Box partner app,\nwith which the mapping is associated.\nCurrently only supports Slack.\n(part of the composite key together with `id`)", "type": "string", - "example": "active", + "example": "slack", "enum": [ - "active", - "applying", - "releasing", - "released" + "slack" ], - "description": "* 'active' - the policy is not in a transition state\n* 'applying' - that the policy is in the process of\n being applied\n* 'releasing' - that the process is in the process\n of being released\n* 'released' - the policy is no longer active" + "nullable": false }, - "assignment_counts": { - "type": "object", - "description": "Counts of assignments within this a legal hold policy by item type", - "properties": { - "user": { - "type": "integer", - "format": "int64", - "description": "The number of users this policy is applied to", - "example": 1 - }, - "folder": { - "type": "integer", - "format": "int64", - "description": "The number of folders this policy is applied to", - "example": 2 - }, - "file": { - "type": "integer", - "format": "int64", - "description": "The number of files this policy is applied to", - "example": 3 - }, - "file_version": { - "type": "integer", - "format": "int64", - "description": "The number of file versions this policy is applied to", - "example": 4 + "partner_item": { + "description": "Mapped item object for Slack or Teams", + "example": { + "id": "C12378991223", + "type": "channel", + "slack_org_id": "E1234567" + }, + "nullable": false, + "oneOf": [ + { + "$ref": "#/components/schemas/IntegrationMappingPartnerItemSlack" } - } + ] + } + } + }, + { + "type": "object", + "properties": { + "box_item": { + "description": "The Box folder, to which the object from the\npartner app domain (referenced in `partner_item_id`) is mapped", + "allOf": [ + { + "$ref": "#/components/schemas/Folder--Mini" + } + ], + "nullable": false + }, + "is_manually_created": { + "description": "Identifies whether the mapping has\nbeen manually set\n(as opposed to being automatically created)", + "type": "boolean", + "example": true, + "nullable": false + }, + "options": { + "allOf": [ + { + "$ref": "#/components/schemas/IntegrationMappingSlackOptions" + } + ], + "nullable": false }, "created_by": { + "description": "An object representing the user who\ncreated the integration mapping", "allOf": [ { - "$ref": "#/components/schemas/User--Mini" - }, + "$ref": "#/components/schemas/UserIntegrationMappings" + } + ], + "nullable": false + }, + "modified_by": { + "description": "The user who\nlast modified the integration mapping", + "allOf": [ { - "description": "The user who created the legal hold policy object" + "$ref": "#/components/schemas/UserIntegrationMappings" } - ] + ], + "nullable": false }, "created_at": { + "description": "When the integration mapping object was created", "type": "string", "format": "date-time", - "description": "When the legal hold policy object was created", - "example": "2012-12-12T10:53:43-08:00" + "example": "2012-12-12T10:53:43-08:00", + "nullable": false }, "modified_at": { + "description": "When the integration mapping object was last modified", "type": "string", "format": "date-time", - "description": "When the legal hold policy object was modified.\nDoes not update when assignments are added or removed.", - "example": "2012-12-12T10:53:43-08:00" - }, - "deleted_at": { - "type": "string", - "format": "date-time", - "description": "When the policy release request was sent. (Because\nit can take time for a policy to fully delete, this\nisn't quite the same time that the policy is fully deleted).\n\nIf `null`, the policy was not deleted.", - "example": "2012-12-12T10:53:43-08:00" - }, - "filter_started_at": { - "type": "string", - "format": "date-time", - "description": "User-specified, optional date filter applies to\nCustodian assignments only", - "example": "2012-12-12T10:53:43-08:00" - }, - "filter_ended_at": { - "type": "string", - "format": "date-time", - "description": "User-specified, optional date filter applies to\nCustodian assignments only", - "example": "2012-12-12T10:53:43-08:00" - }, - "release_notes": { - "type": "string", - "example": "Example", - "description": "Optional notes about why the policy was created.", - "maxLength": 500 + "example": "2012-12-12T10:53:43-08:00", + "nullable": false } - } + }, + "required": [ + "box_item" + ] } - ] + ], + "required": [ + "partner_item" + ], + "title": "Integration mapping Slack", + "x-box-resource-id": "integration_mapping_slack", + "x-box-tag": "integration_mappings", + "x-box-variant": "standard" }, - "LegalHoldPolicies": { - "title": "Legal hold policies", + "IntegrationMapping--Base": { + "description": "A base representation of an\nintegration mapping object.", "type": "object", - "x-box-resource-id": "legal_hold_policies", - "x-box-tag": "legal_hold_policies", - "description": "A list of legal hold policies.", - "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": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", - "type": "string", - "nullable": true - }, - "prev_marker": { - "description": "The marker for the start of the previous page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", - "type": "string", - "nullable": true - } - } + "properties": { + "id": { + "description": "A unique identifier of a folder mapping\n(part of a composite key together\nwith `integration_type`)", + "type": "string", + "example": "12345", + "nullable": false }, - { - "properties": { - "entries": { - "type": "array", - "description": "A list of legal hold policies", - "items": { - "$ref": "#/components/schemas/LegalHoldPolicy" - } - } - } + "type": { + "description": "Mapping type", + "type": "string", + "example": "integration_mapping", + "enum": [ + "integration_mapping" + ], + "nullable": false } + }, + "required": [ + "id", + "type" + ], + "title": "Integration mapping (Base)", + "x-box-resource-id": "integration_mapping--base", + "x-box-tag": "integration_mappings", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "standard", + "mini" ] }, - "LegalHoldPolicy--Mini": { - "title": "Legal hold policy (Mini)", + "IntegrationMappingBoxItemSlack": { + "description": "The schema for an integration mapping Box item object for type Slack", "type": "object", - "x-box-resource-id": "legal_hold_policy--mini", - "x-box-tag": "legal_hold_policies", - "x-box-variants": [ - "mini", - "standard" - ], - "x-box-variant": "mini", - "description": "A mini legal hold policy", + "properties": { + "type": { + "description": "Type of the mapped item referenced in `id`", + "type": "string", + "example": "folder", + "enum": [ + "folder" + ], + "nullable": false + }, + "id": { + "description": "ID of the mapped item (of type referenced in `type`)", + "type": "string", + "example": "1234567891", + "nullable": false + } + }, "required": [ "id", "type" ], + "title": "Integration mapping Box item schema for type Slack" + }, + "IntegrationMappingPartnerItemSlack": { + "description": "The schema for an integration mapping mapped item object for type Slack.\n\nDepending if Box for Slack is installed at the org or workspace level,\nprovide **either** `slack_org_id` **or** `slack_workspace_id`.\nDo not use both parameters at the same time.", + "type": "object", "properties": { + "type": { + "description": "Type of the mapped item referenced in `id`", + "type": "string", + "example": "channel", + "enum": [ + "channel" + ], + "nullable": false + }, "id": { + "description": "ID of the mapped item (of type referenced in `type`)", "type": "string", - "description": "The unique identifier for this legal hold policy", - "example": "11446498" + "example": "C12378991223", + "nullable": false }, - "type": { + "slack_workspace_id": { + "description": "ID of the Slack workspace with which the item is associated. Use this parameter if Box for Slack is installed at a workspace level. Do not use `slack_org_id` at the same time.", "type": "string", - "description": "`legal_hold_policy`", - "example": "legal_hold_policy", - "enum": [ - "legal_hold_policy" - ] + "example": "T12352314", + "nullable": true + }, + "slack_org_id": { + "description": "ID of the Slack org with which the item is associated. Use this parameter if Box for Slack is installed at the org level. Do not use `slack_workspace_id` at the same time.", + "type": "string", + "example": "E1234567", + "nullable": true } - } + }, + "required": [ + "id", + "type" + ], + "title": "Integration mapping mapped item schema for type Slack" }, - "LegalHoldPolicyAssignment": { - "title": "Legal hold policy assignment", + "IntegrationMappingSlackCreateRequest": { + "description": "A request to create a\nSlack Integration Mapping object", "type": "object", - "x-box-resource-id": "legal_hold_policy_assignment", - "x-box-tag": "legal_hold_policy_assignments", - "description": "Legal Hold Assignments are used to assign Legal Hold\nPolicies to Users, Folders, Files, or File Versions.\n\nCreating a Legal Hold Assignment puts a hold\non the File-Versions that belong to the Assignment's\n'apply-to' entity.", "allOf": [ - { - "$ref": "#/components/schemas/LegalHoldPolicyAssignment--Base" - }, { "properties": { - "legal_hold_policy": { + "partner_item": { "allOf": [ { - "$ref": "#/components/schemas/LegalHoldPolicy--Mini" - }, - { - "description": "The policy that the legal hold policy assignment\nis part of" + "$ref": "#/components/schemas/IntegrationMappingPartnerItemSlack" } - ] - }, - "assigned_to": { + ], + "nullable": false + } + } + }, + { + "type": "object", + "properties": { + "box_item": { "allOf": [ { - "oneOf": [ - { - "$ref": "#/components/schemas/File" - }, - { - "$ref": "#/components/schemas/Folder" - }, - { - "$ref": "#/components/schemas/WebLink" - } - ] - }, - { - "description": "The item that the the legal hold policy\nis assigned to. Includes type and ID." + "$ref": "#/components/schemas/IntegrationMappingBoxItemSlack" } - ] + ], + "nullable": false }, - "assigned_by": { + "options": { "allOf": [ { - "$ref": "#/components/schemas/User--Mini" - }, - { - "description": "The user who created the legal hold policy\nassignment" + "$ref": "#/components/schemas/IntegrationMappingSlackOptions" } - ] - }, - "assigned_at": { - "type": "string", - "format": "date-time", - "description": "When the legal hold policy assignment object was\ncreated", - "example": "2012-12-12T10:53:43-08:00" - }, - "deleted_at": { - "type": "string", - "format": "date-time", - "description": "When the assignment release request was sent.\n(Because it can take time for an assignment to fully\ndelete, this isn't quite the same time that the\nassignment is fully deleted). If null, Assignment\nwas not deleted.", - "example": "2012-12-12T10:53:43-08:00" + ], + "nullable": false } - } + }, + "required": [ + "box_item" + ] } - ] + ], + "required": [ + "partner_item" + ], + "title": "Create Slack integration mapping request", + "x-box-resource-id": "integration_mapping_slack_create_request" }, - "LegalHoldPolicyAssignment--Base": { - "title": "Legal hold policy assignment (Base)", + "IntegrationMappingSlackOptions": { + "description": "The schema for an integration mapping options object for Slack type.", "type": "object", - "x-box-resource-id": "legal_hold_policy_assignment--base", - "x-box-tag": "legal_hold_policy_assignments", - "x-box-variants": [ - "base", - "standard" - ], - "x-box-variant": "base", - "description": "Legal Hold Assignments are used to assign Legal Hold\nPolicies to Users, Folders, Files, or File Versions.\n\nCreating a Legal Hold Assignment puts a hold\non the File-Versions that belong to the Assignment's\n'apply-to' entity.", "properties": { - "id": { - "type": "string", - "description": "The unique identifier for this legal hold assignment", - "example": "11446498" - }, - "type": { - "type": "string", - "description": "`legal_hold_policy_assignment`", - "example": "legal_hold_policy_assignment", - "enum": [ - "legal_hold_policy_assignment" - ] + "is_access_management_disabled": { + "description": "Indicates whether or not channel member\naccess to the underlying box item\nshould be automatically managed.\nDepending on type of channel, access is managed\nthrough creating collaborations or shared links.", + "type": "boolean", + "example": true, + "nullable": false } - } + }, + "title": "Integration mapping options for type Slack" }, - "LegalHoldPolicyAssignments": { - "title": "Legal hold policy assignments", + "IntegrationMappings": { + "description": "A list of integration mapping\nobjects.", "type": "object", - "x-box-resource-id": "legal_hold_policy_assignments", - "x-box-tag": "legal_hold_policy_assignments", - "description": "A list of legal hold policies assignments.", "allOf": [ { "type": "object", @@ -31073,20 +30524,14 @@ "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" + "format": "int64", + "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", - "type": "string", - "nullable": true - }, - "prev_marker": { - "description": "The marker for the start of the previous page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true } } @@ -31094,217 +30539,316 @@ { "properties": { "entries": { + "description": "A list of integration mappings", "type": "array", - "description": "A list of legal hold\npolicy assignments", "items": { - "$ref": "#/components/schemas/LegalHoldPolicyAssignment" + "$ref": "#/components/schemas/IntegrationMapping" } } } } - ] + ], + "title": "Integration mappings Slack", + "x-box-resource-id": "integration_mappings_slack", + "x-box-tag": "integration_mappings" }, - "Metadata": { - "title": "Metadata instance", + "Invite": { + "description": "An invite for a user to an enterprise.", "type": "object", - "x-box-resource-id": "metadata", - "x-box-tag": "file_metadata", - "x-box-variant": "standard", - "description": "An instance of a metadata template, which has been applied to a file or\nfolder.", - "allOf": [ - { - "$ref": "#/components/schemas/Metadata--Base" + "properties": { + "id": { + "description": "The unique identifier for this invite", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`invite`", + "type": "string", + "example": "invite", + "enum": [ + "invite" + ] + }, + "invited_to": { + "description": "A representation of a Box enterprise", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this enterprise.", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`enterprise`", + "type": "string", + "example": "enterprise", + "enum": [ + "enterprise" + ] + }, + "name": { + "description": "The name of the enterprise", + "type": "string", + "example": "Acme Inc." + } + }, + "title": "Enterprise" + }, + "actionable_by": { + "$ref": "#/components/schemas/User--Mini" + }, + "invited_by": { + "$ref": "#/components/schemas/User--Mini" + }, + "status": { + "description": "The status of the invite", + "type": "string", + "example": "pending" + }, + "created_at": { + "description": "When the invite was created", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "modified_at": { + "description": "When the invite was modified.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" } - ] + }, + "required": [ + "id", + "type" + ], + "title": "Invite", + "x-box-resource-id": "invite", + "x-box-tag": "invites" }, - "Metadata--Full": { - "title": "Metadata instance (Full)", + "Items": { + "description": "A list of files, folders, and web links in\ntheir mini representation.", "type": "object", - "x-box-resource-id": "metadata--full", - "x-box-variant": "full", - "description": "An instance of a metadata template, which has been applied to a file or\nfolder.", "allOf": [ { - "$ref": "#/components/schemas/Metadata" - }, - { + "type": "object", + "description": "The part of an API response that describes marker\nbased pagination", "properties": { - "$canEdit": { - "type": "boolean", - "example": true, - "description": "Whether the user can edit this metadata instance." + "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.", + "type": "integer", + "format": "int64", + "example": 1000 }, - "$id": { + "next_marker": { + "description": "The marker for the start of the next page of results.", "type": "string", - "format": "uuid", - "example": "01234500-12f1-1234-aa12-b1d234cb567e", - "maxLength": 36, - "description": "A UUID to identify the metadata instance." + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true }, - "$type": { + "prev_marker": { + "description": "The marker for the start of the previous page of results.", "type": "string", - "example": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0", - "description": "A unique identifier for the \"type\" of this instance. This is an\ninternal system property and should not be used by a client\napplication." + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true + } + } + }, + { + "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.", + "type": "integer", + "format": "int64", + "example": 5000 }, - "$typeVersion": { + "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.", "type": "integer", - "example": 2, - "description": "The last-known version of the template of the object. This is an\ninternal system property and should not be used by a client\napplication." + "format": "int64", + "example": 1000 + }, + "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.", + "type": "integer", + "format": "int64", + "example": 2000 + }, + "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", + "type": "string", + "example": "type" + }, + "direction": { + "description": "The direction to order by, either ascending or descending", + "type": "string", + "example": "ASC", + "enum": [ + "ASC", + "DESC" + ] + } + } + } } } }, { - "additionalProperties": { - "allOf": [ - {}, - { - "example": "Aaron Levie" - }, - { - "description": "A value for each of the fields that are present\non the metadata template.\nFor the `global.properties` template this can be\na list of zero or more fields,\nas this template allows for any generic key-value pairs \nto be stored stored in the template." + "properties": { + "entries": { + "description": "The items in this collection.", + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/File--Full" + }, + { + "$ref": "#/components/schemas/Folder--Mini" + }, + { + "$ref": "#/components/schemas/WebLink" + } + ] } - ], - "x-box-example-key": "name" + } } } - ] - }, - "Metadata--Base": { - "title": "Metadata instance (Base)", - "type": "object", - "x-box-resource-id": "metadata--base", - "x-box-tag": "file_metadata", - "x-box-variants": [ - "base", - "standard", - "full" ], - "x-box-variant": "base", - "description": "The base representation of a metadata instance.", - "properties": { - "$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": "marketingCollateral", - "description": "The name of the template" - }, - "$scope": { - "type": "string", - "example": "enterprise_27335", - "description": "An ID for the scope in which this template\nhas been applied. This will be `enterprise_{enterprise_id}` for templates\ndefined for use in this enterprise, and `global` for general templates\nthat are available to all enterprises using Box." - }, - "$version": { - "type": "integer", - "example": 1, - "description": "The version of the metadata instance. This version starts at 0 and\nincreases every time a user-defined property is modified." - } - } - }, - "Metadatas": { - "title": "Metadata instances", - "type": "object", - "x-box-resource-id": "metadatas", - "x-box-tag": "file_metadata", - "description": "A list of metadata instances that have been applied to a file or folder.", - "properties": { - "entries": { - "type": "array", - "description": "A list of metadata instances, as applied to this file or folder.", - "items": { - "$ref": "#/components/schemas/Metadata" - } - }, - "limit": { - "description": "The limit that was used for this page of results.", - "example": 100, - "type": "integer" - } - } + "title": "Items", + "x-box-resource-id": "items", + "x-box-tag": "folders" }, - "MetadataCascadePolicy": { - "title": "Metadata cascade policy", + "KeywordSkillCard": { + "description": "A skill card that contains a set of keywords", "type": "object", - "x-box-resource-id": "metadata_cascade_policy", - "x-box-tag": "metadata_cascade_policies", - "description": "A metadata cascade policy automatically applies a metadata template instance\nto all the files and folders within the targeted folder.", - "required": [ - "id", - "type" - ], "properties": { - "id": { + "created_at": { + "description": "The optional date and time this card was created at.", "type": "string", - "example": "6fd4ff89-8fc1-42cf-8b29-1890dedd26d7", - "description": "The ID of the metadata cascade policy object" + "format": "date-time", + "example": "2018-04-13T13:53:23-07:00" }, "type": { + "description": "`skill_card`", "type": "string", - "description": "`metadata_cascade_policy`", - "example": "metadata_cascade_policy", + "example": "skill_card", "enum": [ - "metadata_cascade_policy" + "skill_card" ] }, - "owner_enterprise": { + "skill_card_type": { + "description": "`keyword`", + "type": "string", + "example": "keyword", + "enum": [ + "keyword" + ] + }, + "skill_card_title": { + "description": "The title of the card.", + "type": "object", + "properties": { + "code": { + "description": "An optional identifier for the title.", + "type": "string", + "example": "labels" + }, + "message": { + "description": "The actual title to show in the UI.", + "type": "string", + "example": "Labels" + } + }, + "required": [ + "message" + ] + }, + "skill": { + "description": "The service that applied this metadata.", "type": "object", - "description": "The enterprise that owns this policy.", "properties": { "type": { + "description": "`service`", "type": "string", - "example": "enterprise", - "description": "`enterprise`", + "example": "service", "enum": [ - "enterprise" + "service" ] }, "id": { + "description": "A custom identifier that represent the service that\napplied this metadata.", "type": "string", - "example": "690678", - "description": "The ID of the enterprise that owns the policy." + "example": "image-recognition-service" } - } + }, + "required": [ + "type", + "id" + ] }, - "parent": { + "invocation": { + "description": "The invocation of this service, used to track\nwhich instance of a service applied the metadata.", "type": "object", - "description": "Represent the folder the policy is applied to.", "properties": { "type": { + "description": "`skill_invocation`", "type": "string", - "example": "folder", - "description": "`folder`", + "example": "skill_invocation", "enum": [ - "folder" + "skill_invocation" ] }, "id": { + "description": "A custom identifier that represent the instance of\nthe service that applied this metadata. For example,\nif your `image-recognition-service` runs on multiple\nnodes, this field can be used to identify the ID of\nthe node that was used to apply the metadata.", "type": "string", - "example": "1234567", - "description": "The ID of the folder the policy is applied to." + "example": "image-recognition-service-123" } - } - }, - "scope": { - "type": "string", - "description": "The scope of the metadata cascade policy can either be `global` or\n`enterprise_*`. The `global` scope is used for policies that are\navailable to any Box enterprise. The `enterprise_*` scope represents\npolicies that have been created within a specific enterprise, where `*`\nwill be the ID of that enterprise.", - "example": "enterprise_123456" + }, + "required": [ + "type", + "id" + ] }, - "templateKey": { - "type": "string", - "example": "productInfo", - "description": "The key of the template that is cascaded down to the folder's\nchildren.\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" + "entries": { + "description": "An list of entries in the metadata card.", + "type": "array", + "items": { + "type": "object", + "description": "An entry in the `entries` attribute of a metadata card", + "properties": { + "text": { + "description": "The text of the keyword.", + "type": "string", + "example": "keyword1" + } + } + } } - } + }, + "required": [ + "type", + "skill_card_type", + "skill", + "invocation", + "entries" + ], + "title": "Keyword Skill Card", + "x-box-resource-id": "keyword_skill_card", + "x-box-tag": "skills" }, - "MetadataCascadePolicies": { - "title": "Metadata cascade policies", + "LegalHoldPolicies": { + "description": "A list of legal hold policies.", "type": "object", - "x-box-resource-id": "metadata_cascade_policies", - "x-box-tag": "metadata_cascade_policies", - "description": "A list of metadata cascade policies.", "allOf": [ { "type": "object", @@ -31312,20 +30856,20 @@ "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" + "format": "int64", + "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } @@ -31333,296 +30877,263 @@ { "properties": { "entries": { + "description": "A list of legal hold policies", "type": "array", - "description": "A list of metadata cascade policies", "items": { - "$ref": "#/components/schemas/MetadataCascadePolicy" + "$ref": "#/components/schemas/LegalHoldPolicy" } } } } - ] + ], + "title": "Legal hold policies", + "x-box-resource-id": "legal_hold_policies", + "x-box-tag": "legal_hold_policies" }, - "MetadataQueryIndex": { - "title": "Metadata query index", + "LegalHoldPolicy": { + "description": "Legal Hold Policy information describes the basic\ncharacteristics of the Policy, such as name, description,\nand filter dates.", "type": "object", - "x-box-resource-id": "metadata_query_index", - "x-box-tag": "search", - "description": "A metadata query index", - "required": [ - "type", - "status" + "allOf": [ + { + "$ref": "#/components/schemas/LegalHoldPolicy--Mini" + }, + { + "properties": { + "policy_name": { + "description": "Name of the legal hold policy.", + "type": "string", + "example": "Policy 4", + "maxLength": 254 + }, + "description": { + "description": "Description of the legal hold policy. Optional\nproperty with a 500 character limit.", + "type": "string", + "example": "Postman created policy", + "maxLength": 500 + }, + "status": { + "description": "* 'active' - the policy is not in a transition state\n* 'applying' - that the policy is in the process of\n being applied\n* 'releasing' - that the process is in the process\n of being released\n* 'released' - the policy is no longer active", + "type": "string", + "example": "active", + "enum": [ + "active", + "applying", + "releasing", + "released" + ] + }, + "assignment_counts": { + "description": "Counts of assignments within this a legal hold policy by item type", + "type": "object", + "properties": { + "user": { + "description": "The number of users this policy is applied to", + "type": "integer", + "format": "int64", + "example": 1 + }, + "folder": { + "description": "The number of folders this policy is applied to", + "type": "integer", + "format": "int64", + "example": 2 + }, + "file": { + "description": "The number of files this policy is applied to", + "type": "integer", + "format": "int64", + "example": 3 + }, + "file_version": { + "description": "The number of file versions this policy is applied to", + "type": "integer", + "format": "int64", + "example": 4 + } + } + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who created the legal hold policy object" + } + ] + }, + "created_at": { + "description": "When the legal hold policy object was created", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "modified_at": { + "description": "When the legal hold policy object was modified.\nDoes not update when assignments are added or removed.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "deleted_at": { + "description": "When the policy release request was sent. (Because\nit can take time for a policy to fully delete, this\nisn't quite the same time that the policy is fully deleted).\n\nIf `null`, the policy was not deleted.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "filter_started_at": { + "description": "User-specified, optional date filter applies to\nCustodian assignments only", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "filter_ended_at": { + "description": "User-specified, optional date filter applies to\nCustodian assignments only", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "release_notes": { + "description": "Optional notes about why the policy was created.", + "type": "string", + "example": "Example", + "maxLength": 500 + } + } + } ], + "title": "Legal hold policy", + "x-box-resource-id": "legal_hold_policy", + "x-box-variant": "standard" + }, + "LegalHoldPolicy--Mini": { + "description": "A mini legal hold policy", + "type": "object", "properties": { "id": { + "description": "The unique identifier for this legal hold policy", "type": "string", - "example": "-9876", - "description": "The ID of the metadata query index." + "example": "11446498" }, "type": { + "description": "`legal_hold_policy`", "type": "string", - "description": "Value is always `metadata_query_index`", - "example": "metadata_query_index", - "nullable": false - }, - "status": { - "type": "string", - "description": "The status of the metadata query index", - "example": "active", + "example": "legal_hold_policy", "enum": [ - "building", - "active", - "disabled" - ], - "nullable": false - }, - "fields": { - "type": "array", - "description": "A list of template fields which make up the index.", - "items": { - "type": "object", - "description": "The field which makes up the index.", - "allOf": [ - { - "properties": { - "key": { - "type": "string", - "example": "vendor name", - "description": "The metadata template field key." - }, - "sort_direction": { - "type": "string", - "example": "asc", - "description": "The sort direction of the field.", - "enum": [ - "asc", - "desc" - ] - } - } - } - ] - } + "legal_hold_policy" + ] } - } + }, + "required": [ + "id", + "type" + ], + "title": "Legal hold policy (Mini)", + "x-box-resource-id": "legal_hold_policy--mini", + "x-box-tag": "legal_hold_policies", + "x-box-variant": "mini", + "x-box-variants": [ + "mini", + "standard" + ] }, - "MetadataQueryResults": { - "title": "Metadata query search results", + "LegalHoldPolicyAssignment": { + "description": "Legal Hold Assignments are used to assign Legal Hold\nPolicies to Users, Folders, Files, or File Versions.\n\nCreating a Legal Hold Assignment puts a hold\non the File-Versions that belong to the Assignment's\n'apply-to' entity.", "type": "object", - "x-box-tag": "search", - "x-box-resource-id": "metadata_query_results", - "description": "A page of files and folders that matched the metadata query.", - "properties": { - "entries": { - "description": "The mini representation of the files and folders that match the search\nterms.\n\nBy default, this endpoint returns only the most basic info about the\nitems. To get additional fields for each item, including any of the\nmetadata, use the `fields` attribute in the query.", - "type": "array", - "x-box-resource-variant": 1, - "items": { - "oneOf": [ - { - "$ref": "#/components/schemas/File--Full" - }, - { - "$ref": "#/components/schemas/Folder--Full" - } - ] - } - }, - "limit": { - "description": "The limit that was used for this search. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed.", - "default": 100, - "example": 100, - "type": "integer", - "format": "int64" + "allOf": [ + { + "$ref": "#/components/schemas/LegalHoldPolicyAssignment--Base" }, - "next_marker": { - "description": "The marker for the start of the next page of results.", - "example": "0!-M7487OpVfBTNBV-XsQjU50gQFlbFFu5nArMWD7Ck61GH_Qo40M1S2xN5zWZPBzEjaQS1SOjJiQoo5BsXEl1bCVLRZ2pTqo4SKp9tyqzWQK2L51KR_nC1EgF5I_TJSFw7uO2Bx4HweGETOjh5_2oPSWw5iMkM-OvGApeR0lGFO48FDKoyzJyLgz5aogxoKd8VE09CesOOnTnmZvrW0puylDc-hFjY5YLmWFBKox3SOWiSDwKFkmZGNHyjEzza1nSwbZg6CYsAdGsDwGJhuCeTNsFzP5Mo5qx9wMloS0lSPuf2CcBInbIJzl2CKlXF3FvqhANttpm2nzdBTQRSoJyJnjVBpf4Q_HjV2eb4KIZBBlLy067UCVdv2AAWQFd5E2i6s1YiGRTtgMEZntOSUYD4IYLMWWm5Ra7ke_SP32SL3GSjbBQYIyCVQ..", - "type": "string" + { + "properties": { + "legal_hold_policy": { + "allOf": [ + { + "$ref": "#/components/schemas/LegalHoldPolicy--Mini" + }, + { + "description": "The policy that the legal hold policy assignment\nis part of" + } + ] + }, + "assigned_to": { + "allOf": [ + { + "oneOf": [ + { + "$ref": "#/components/schemas/File" + }, + { + "$ref": "#/components/schemas/Folder" + }, + { + "$ref": "#/components/schemas/WebLink" + } + ] + }, + { + "description": "The item that the the legal hold policy\nis assigned to. Includes type and ID." + } + ] + }, + "assigned_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who created the legal hold policy\nassignment" + } + ] + }, + "assigned_at": { + "description": "When the legal hold policy assignment object was\ncreated", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "deleted_at": { + "description": "When the assignment release request was sent.\n(Because it can take time for an assignment to fully\ndelete, this isn't quite the same time that the\nassignment is fully deleted). If null, Assignment\nwas not deleted.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + } + } } - } + ], + "title": "Legal hold policy assignment", + "x-box-resource-id": "legal_hold_policy_assignment", + "x-box-tag": "legal_hold_policy_assignments" }, - "MetadataTemplate": { - "title": "Metadata template", + "LegalHoldPolicyAssignment--Base": { + "description": "Legal Hold Assignments are used to assign Legal Hold\nPolicies to Users, Folders, Files, or File Versions.\n\nCreating a Legal Hold Assignment puts a hold\non the File-Versions that belong to the Assignment's\n'apply-to' entity.", "type": "object", - "x-box-resource-id": "metadata_template", - "x-box-tag": "metadata_templates", - "description": "A template for metadata that can be applied to files and folders", - "required": [ - "type", - "id" - ], "properties": { "id": { + "description": "The unique identifier for this legal hold assignment", "type": "string", - "example": "58063d82-4128-7b43-bba9-92f706befcdf", - "description": "The ID of the metadata template." + "example": "11446498" }, "type": { + "description": "`legal_hold_policy_assignment`", "type": "string", - "description": "`metadata_template`", - "example": "metadata_template", + "example": "legal_hold_policy_assignment", "enum": [ - "metadata_template" - ], - "nullable": false - }, - "scope": { - "type": "string", - "description": "The scope of the metadata template can either be `global` or\n`enterprise_*`. The `global` scope is used for templates that are\navailable to any Box enterprise. The `enterprise_*` scope represents\ntemplates that have been created within a specific enterprise, where `*`\nwill be the ID of that enterprise.", - "example": "enterprise_123456" - }, - "templateKey": { - "type": "string", - "example": "productInfo", - "description": "A unique identifier for the template. This identifier is unique across\nthe `scope` of the enterprise to which the metadata template is being\napplied, yet is not necessarily unique across different enterprises.", - "maxLength": 64, - "pattern": "^[a-zA-Z_][-a-zA-Z0-9_]*$" - }, - "displayName": { - "type": "string", - "description": "The display name of the template. This can be seen in the Box web app\nand mobile apps.", - "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." - }, - "fields": { - "type": "array", - "description": "An ordered list of template fields which are part of the template. Each\nfield can be a regular text field, date field, number field, as well as a\nsingle or multi-select list.", - "items": { - "type": "object", - "description": "A field within a metadata template. Fields can be a basic text, date, or\nnumber field, or a list of options.", - "allOf": [ - { - "title": "Metadata Field (Read)", - "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.\n\n**Note**: The `integer` value is deprecated.\nIt is still present in the response,\nbut cannot be used in the POST request.", - "enum": [ - "string", - "float", - "date", - "enum", - "multiSelect", - "integer" - ] - }, - "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" - } - } - } - } - } - }, - { - "properties": { - "id": { - "type": "string", - "example": "822227e0-47a5-921b-88a8-494760b2e6d2", - "description": "The unique ID of the metadata template field." - }, - "options": { - "description": "A list of options for this field. This is used in combination\nwith the `enum` and `multiSelect` field types.", - "type": "array", - "items": { - "type": "object", - "description": "An option for a Metadata Template Field.\n\nOptions are only present for fields of type `enum` and\n`multiSelect`. Options represent the value(s) a user can\nselect for the field either through the UI or through the API.", - "allOf": [ - { - "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" - } - } - }, - { - "properties": { - "id": { - "type": "string", - "example": "45dc2849-a4a7-40a9-a751-4a699a589190", - "description": "The internal unique identifier of the the option." - } - } - } - ] - } - } - } - } - ] - } - }, - "copyInstanceOnItemCopy": { - "type": "boolean", - "description": "Whether or not to include the metadata when a file or folder is copied.", - "example": true + "legal_hold_policy_assignment" + ] } - } + }, + "title": "Legal hold policy assignment (Base)", + "x-box-resource-id": "legal_hold_policy_assignment--base", + "x-box-tag": "legal_hold_policy_assignments", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "standard" + ] }, - "MetadataTemplates": { - "title": "Metadata templates", + "LegalHoldPolicyAssignments": { + "description": "A list of legal hold policies assignments.", "type": "object", - "x-box-resource-id": "metadata_templates", - "x-box-tag": "metadata_templates", - "description": "A list of metadata templates", "allOf": [ { "type": "object", @@ -31630,20 +31141,20 @@ "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" + "format": "int64", + "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } @@ -31651,133 +31162,122 @@ { "properties": { "entries": { + "description": "A list of legal hold\npolicy assignments", "type": "array", - "description": "A list of metadata templates", "items": { - "$ref": "#/components/schemas/MetadataTemplate" + "$ref": "#/components/schemas/LegalHoldPolicyAssignment" } } } } - ] + ], + "title": "Legal hold policy assignments", + "x-box-resource-id": "legal_hold_policy_assignments", + "x-box-tag": "legal_hold_policy_assignments" }, - "RealtimeServer": { - "title": "Real-time server", + "Metadata": { + "description": "An instance of a metadata template, which has been applied to a file or\nfolder.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/Metadata--Base" + } + ], + "title": "Metadata instance", + "x-box-resource-id": "metadata", + "x-box-tag": "file_metadata", + "x-box-variant": "standard" + }, + "Metadata--Base": { + "description": "The base representation of a metadata instance.", "type": "object", - "x-box-resource-id": "realtime_server", - "description": "A real-time server that can be used for\nlong polling user events", "properties": { - "type": { - "description": "`realtime_server`", - "type": "string", - "example": "realtime_server" - }, - "url": { + "$parent": { + "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}`.", "type": "string", - "example": "http://2.realtime.services.box.net/subscribe?channel=cc807c9c4869ffb1c81a&stream_type=all", - "description": "The URL for the server." + "example": "folder_59449484661," }, - "ttl": { - "description": "The time in minutes for which this server is available", + "$template": { + "description": "The name of the template", "type": "string", - "example": "10" + "example": "marketingCollateral" }, - "max_retries": { - "description": "The maximum number of retries this server will\nallow before a new long poll should be started by\ngetting a [new list of server](#options-events).", + "$scope": { + "description": "An ID for the scope in which this template\nhas been applied. This will be `enterprise_{enterprise_id}` for templates\ndefined for use in this enterprise, and `global` for general templates\nthat are available to all enterprises using Box.", "type": "string", - "example": "10" + "example": "enterprise_27335" }, - "retry_timeout": { - "description": "The maximum number of seconds without a response\nafter which you should retry the long poll connection.\n\nThis helps to overcome network issues where the long\npoll looks to be working but no packages are coming\nthrough.", - "type": "integer", - "example": 610 - } - } - }, - "RealtimeServers": { - "title": "Real-time servers", - "type": "object", - "x-box-resource-id": "realtime_servers", - "description": "A list of real-time servers that can\nbe used for long-polling.", - "x-box-tag": "events", - "properties": { - "chunk_size": { - "description": "The number of items in this response.", - "example": 1, + "$version": { + "description": "The version of the metadata instance. This version starts at 0 and\nincreases every time a user-defined property is modified.", "type": "integer", - "format": "int64" - }, - "entries": { - "type": "array", - "description": "A list of real-time servers", - "items": { - "$ref": "#/components/schemas/RealtimeServer" - } + "example": 1 } - } + }, + "title": "Metadata instance (Base)", + "x-box-resource-id": "metadata--base", + "x-box-tag": "file_metadata", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "standard", + "full" + ] }, - "RecentItem": { - "title": "Recent item", + "Metadata--Full": { + "description": "An instance of a metadata template, which has been applied to a file or\nfolder.", "type": "object", - "x-box-resource-id": "recent_item", - "description": "A recent item accessed by a user.", - "x-box-tag": "recent_items", - "properties": { - "type": { - "type": "string", - "description": "`recent_item`", - "example": "recent_item" + "allOf": [ + { + "$ref": "#/components/schemas/Metadata" }, - "item": { - "allOf": [ - { - "oneOf": [ - { - "$ref": "#/components/schemas/File--Full" - }, - { - "$ref": "#/components/schemas/Folder--Full" - }, - { - "$ref": "#/components/schemas/WebLink" - } - ] + { + "properties": { + "$canEdit": { + "description": "Whether the user can edit this metadata instance.", + "type": "boolean", + "example": true }, - { - "description": "The item that was recently accessed." + "$id": { + "description": "A UUID to identify the metadata instance.", + "type": "string", + "format": "uuid", + "example": "01234500-12f1-1234-aa12-b1d234cb567e", + "maxLength": 36 + }, + "$type": { + "description": "A unique identifier for the \"type\" of this instance. This is an\ninternal system property and should not be used by a client\napplication.", + "type": "string", + "example": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0" + }, + "$typeVersion": { + "description": "The last-known version of the template of the object. This is an\ninternal system property and should not be used by a client\napplication.", + "type": "integer", + "example": 2 } - ] - }, - "interaction_type": { - "type": "string", - "example": "item_preview", - "description": "The most recent type of access the user performed on\nthe item.", - "enum": [ - "item_preview", - "item_upload", - "item_comment", - "item_open", - "item_modify" - ] - }, - "interacted_at": { - "type": "string", - "format": "date-time", - "description": "The time of the most recent interaction.", - "example": "2018-04-13T13:53:23-07:00" + } }, - "interaction_shared_link": { - "type": "string", - "example": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg", - "description": "If the item was accessed through a shared link it will appear here,\notherwise this will be null." + { + "additionalProperties": { + "allOf": [ + {}, + { + "example": "Aaron Levie" + }, + { + "description": "A value for each of the fields that are present\non the metadata template.\nFor the `global.properties` template this can be\na list of zero or more fields,\nas this template allows for any generic key-value pairs \nto be stored stored in the template." + } + ], + "x-box-example-key": "name" + } } - } + ], + "title": "Metadata instance (Full)", + "x-box-resource-id": "metadata--full", + "x-box-variant": "full" }, - "RecentItems": { - "title": "Recent items", + "MetadataCascadePolicies": { + "description": "A list of metadata cascade policies.", "type": "object", - "x-box-resource-id": "recent_items", - "description": "A list of recent items.", "allOf": [ { "type": "object", @@ -31785,20 +31285,20 @@ "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" + "format": "int64", + "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } @@ -31806,534 +31306,569 @@ { "properties": { "entries": { + "description": "A list of metadata cascade policies", "type": "array", - "description": "A list of recent items", "items": { - "$ref": "#/components/schemas/RecentItem" + "$ref": "#/components/schemas/MetadataCascadePolicy" } } } } - ] + ], + "title": "Metadata cascade policies", + "x-box-resource-id": "metadata_cascade_policies", + "x-box-tag": "metadata_cascade_policies" }, - "RetentionPolicies": { - "title": "Retention policies", + "MetadataCascadePolicy": { + "description": "A metadata cascade policy automatically applies a metadata template instance\nto all the files and folders within the targeted folder.", "type": "object", - "x-box-resource-id": "retention_policies", - "x-box-tag": "retention_policies", - "description": "A list of retention policies.", - "allOf": [ - { - "properties": { - "entries": { - "description": "A list in which each entry represents a retention policy object.", - "type": "array", - "items": { - "$ref": "#/components/schemas/RetentionPolicy" - } - } - } + "properties": { + "id": { + "description": "The ID of the metadata cascade policy object", + "type": "string", + "example": "6fd4ff89-8fc1-42cf-8b29-1890dedd26d7" }, - { + "type": { + "description": "`metadata_cascade_policy`", + "type": "string", + "example": "metadata_cascade_policy", + "enum": [ + "metadata_cascade_policy" + ] + }, + "owner_enterprise": { + "description": "The enterprise that owns this policy.", "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": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", - "type": "string", - "nullable": true - } - } - } - ] - }, - "RetentionPolicy": { - "title": "Retention policy", - "type": "object", - "x-box-resource-id": "retention_policy", - "x-box-tag": "retention_policies", - "x-box-variant": "standard", - "description": "A retention policy blocks permanent deletion of content\nfor a specified amount of time. Admins can create retention\npolicies and then later assign them to specific folders, metadata\ntemplates, or their entire enterprise. To use this feature, you must\nhave the manage retention policies scope enabled\nfor your API key via your application management console.", - "allOf": [ - { - "$ref": "#/components/schemas/RetentionPolicy--Mini" - }, - { - "properties": { - "description": { - "type": "string", - "example": "Policy to retain all reports for at least one month", - "description": "The additional text description of the retention policy." - }, - "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" - ] - }, - "retention_type": { - "type": "string", - "example": "non_modifiable", - "description": "Specifies the retention type:\n\n* `modifiable`: You can modify the retention policy. For example,\n you can add or remove folders, shorten or lengthen\n the policy duration, or delete the assignment.\n Use this type if your retention policy\n is not related to any regulatory purposes.\n\n* `non-modifiable`: You can modify the retention policy\n only in a limited way: add a folder, lengthen the duration,\n retire the policy, change the disposition action\n or notification settings. You cannot perform other actions,\n such as deleting the assignment or shortening the\n policy duration. Use this type to ensure\n compliance with regulatory retention policies.", - "enum": [ - "modifiable", - "non_modifiable" - ] - }, - "status": { + "type": { + "description": "`enterprise`", "type": "string", - "example": "active", - "description": "The status of the retention policy. The status of\na policy will be `active`, unless explicitly retired by an\nadministrator, in which case the status will be `retired`.\nOnce a policy has been retired, it cannot become\nactive again.", + "example": "enterprise", "enum": [ - "active", - "retired" - ] - }, - "created_by": { - "allOf": [ - { - "$ref": "#/components/schemas/User--Mini" - }, - { - "description": "A mini user object representing the user that\ncreated the retention policy." - } + "enterprise" ] }, - "created_at": { - "type": "string", - "format": "date-time", - "description": "When the retention policy object was created.", - "example": "2012-12-12T10:53:43-08:00" - }, - "modified_at": { + "id": { + "description": "The ID of the enterprise that owns the policy.", "type": "string", - "format": "date-time", - "description": "When the retention policy object was last modified.", - "example": "2012-12-12T10:53:43-08:00" - }, - "can_owner_extend_retention": { - "type": "boolean", - "description": "Determines if the owner of items under the policy\ncan extend the retention when the original\nretention duration 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.", - "example": false - }, - "custom_notification_recipients": { - "type": "array", - "description": "A list of users notified when the retention policy duration is about to end.", - "items": { - "$ref": "#/components/schemas/User--Mini" - } - }, - "assignment_counts": { - "type": "object", - "description": "Counts the retention policy assignments for each item type.", - "properties": { - "enterprise": { - "description": "The number of enterprise assignments this policy has. The maximum value is 1.", - "format": "int64", - "type": "integer", - "example": 1 - }, - "folder": { - "description": "The number of folder assignments this policy has.", - "format": "int64", - "type": "integer", - "example": 1 - }, - "metadata_template": { - "description": "The number of metadata template assignments this policy has.", - "format": "int64", - "type": "integer", - "example": 1 - } - } + "example": "690678" } } - } - ] - }, - "RetentionPolicy--Mini": { - "title": "Retention policy (Mini)", - "type": "object", - "x-box-resource-id": "retention_policy--mini", - "x-box-variant": "mini", - "description": "A mini representation of a retention policy, used when\nnested within another resource.", - "allOf": [ - { - "$ref": "#/components/schemas/RetentionPolicy--Base" }, - { + "parent": { + "description": "Represent the folder the policy is applied to.", + "type": "object", "properties": { - "policy_name": { - "type": "string", - "description": "The name given to the retention policy.", - "example": "Some Policy Name" - }, - "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`." - }, - "disposition_action": { + "type": { + "description": "`folder`", "type": "string", - "example": "permanently_delete", - "description": "The disposition action of the retention policy.\nThis action can be `permanently_delete`, which\nwill cause the content retained by the policy\nto be permanently deleted, or `remove_retention`,\nwhich will lift the retention policy from the content,\nallowing it to be deleted by users,\nonce the retention policy has expired.", + "example": "folder", "enum": [ - "permanently_delete", - "remove_retention" + "folder" ] + }, + "id": { + "description": "The ID of the folder the policy is applied to.", + "type": "string", + "example": "1234567" } } + }, + "scope": { + "description": "The scope of the metadata cascade policy can either be `global` or\n`enterprise_*`. The `global` scope is used for policies that are\navailable to any Box enterprise. The `enterprise_*` scope represents\npolicies that have been created within a specific enterprise, where `*`\nwill be the ID of that enterprise.", + "type": "string", + "example": "enterprise_123456" + }, + "templateKey": { + "description": "The key of the template that is cascaded down to the folder's\nchildren.\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", + "type": "string", + "example": "productInfo" } - ] - }, - "RetentionPolicy--Base": { - "title": "Retention policy (Base)", - "type": "object", - "x-box-resource-id": "retention_policy--base", - "x-box-tag": "retention_policies", - "x-box-variants": [ - "base", - "mini", - "standard" - ], - "x-box-variant": "base", - "description": "A base representation of a retention policy.", + }, "required": [ "id", "type" ], + "title": "Metadata cascade policy", + "x-box-resource-id": "metadata_cascade_policy", + "x-box-tag": "metadata_cascade_policies" + }, + "MetadataFieldFilterDateRange": { + "description": "Specifies which `date` field on the template to filter the search\nresults by, specifying a range of dates that can match.", + "type": "object", "properties": { - "id": { + "lt": { + "description": "Specifies the (inclusive) upper bound for the metadata field\nvalue. The value of a field must be lower than (`lt`) or\nequal to this value for the search query to match this\ntemplate.", "type": "string", - "nullable": false, - "description": "The unique identifier that represents a retention policy.", - "example": "12345" + "format": "date-time", + "example": "2017-08-01T00:00:00Z" }, - "type": { + "gt": { + "description": "Specifies the (inclusive) lower bound for the metadata field\nvalue. The value of a field must be greater than (`gt`) or\nequal to this value for the search query to match this\ntemplate.", "type": "string", - "description": "`retention_policy`", - "example": "retention_policy", - "enum": [ - "retention_policy" - ], - "nullable": false + "format": "date-time", + "example": "2016-08-01T00:00:00Z" } - } + }, + "title": "Metadata field filter (date range)", + "x-box-resource-id": "metadata_field_filter_date_range" }, - "RetentionPolicyAssignment--Base": { - "title": "Retention policy assignment (Base)", + "MetadataFieldFilterFloatRange": { + "description": "Specifies which `float` field on the template to filter the search\nresults by, specifying a range of values that can match.", "type": "object", - "x-box-resource-id": "retention_policy_assignment--base", - "x-box-tag": "retention_policy_assignments", - "x-box-variants": [ - "base", - "standard" - ], - "x-box-variant": "base", - "description": "A base representation of a retention policy assignment.", - "required": [ - "id", - "type" - ], "properties": { - "id": { - "type": "string", - "nullable": false, - "description": "The unique identifier that represents a file version.", - "example": "12345" + "lt": { + "description": "Specifies the (inclusive) upper bound for the metadata field\nvalue. The value of a field must be lower than (`lt`) or\nequal to this value for the search query to match this\ntemplate.", + "type": "number", + "example": 200000 }, - "type": { + "gt": { + "description": "Specifies the (inclusive) lower bound for the metadata field\nvalue. The value of a field must be greater than (`gt`) or\nequal to this value for the search query to match this\ntemplate.", + "type": "number", + "example": 100000 + } + }, + "title": "Metadata field filter (float range)", + "x-box-resource-id": "metadata_field_filter_float_range" + }, + "MetadataFilter": { + "description": "A metadata template used to filter the search results.", + "type": "object", + "properties": { + "scope": { + "description": "Specifies the scope of the template to filter search results by.\n\nThis will be `enterprise_{enterprise_id}` for templates defined\nfor use in this enterprise, and `global` for general templates\nthat are available to all enterprises using Box.", "type": "string", - "description": "`retention_policy_assignment`", - "example": "retention_policy_assignment", + "example": "enterprise", "enum": [ - "retention_policy_assignment" - ], - "nullable": false + "global", + "enterprise", + "enterprise_{enterprise_id}" + ] + }, + "templateKey": { + "description": "The key of the template used to filter search results.\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", + "type": "string", + "example": "contract" + }, + "filters": { + "description": "Specifies which fields on the template to filter the search\nresults by. When more than one field is specified, the query\nperforms a logical `AND` to ensure that the instance of the\ntemplate matches each of the fields specified.", + "type": "object", + "example": { + "category": "online" + }, + "additionalProperties": { + "allOf": [ + { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "title": "Metadata field filter (multi-select)", + "type": "array", + "items": { + "type": "string" + }, + "description": "Specifies the values to match for a `multiSelect` metadata\nfield. When performing a search, the query will essentially\nperform an `OR` operation to match any template where any of\nthe provided values match this field.", + "example": [ + "online", + "enterprise" + ] + }, + { + "$ref": "#/components/schemas/MetadataFieldFilterFloatRange" + }, + { + "$ref": "#/components/schemas/MetadataFieldFilterDateRange" + } + ] + }, + { + "example": "online" + }, + { + "x-box-example-key": "category" + } + ] + } } - } + }, + "title": "Metadata filter", + "x-box-resource-id": "metadata_filter", + "x-box-tag": "search" }, - "RetentionPolicyAssignment": { - "title": "Retention policy assignment", + "MetadataQuery": { + "description": "Create a search using SQL-like syntax to return items that match specific\nmetadata.", "type": "object", - "x-box-resource-id": "retention_policy_assignment", - "x-box-tag": "retention_policy_assignments", - "description": "A retention assignment represents a rule specifying\nthe files a retention policy retains.\nAssignments can retain files based on their folder or metadata,\nor hold all files in the enterprise.", - "required": [ - "id", - "type" - ], "properties": { - "id": { + "from": { + "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.", "type": "string", - "description": "The unique identifier for a retention policy assignment.", - "example": "11446498" + "example": "enterprise_123456.someTemplate" }, - "type": { + "query": { + "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.", "type": "string", - "description": "`retention_policy_assignment`", - "example": "retention_policy_assignment", - "enum": [ - "retention_policy_assignment" - ] - }, - "retention_policy": { - "allOf": [ - { - "$ref": "#/components/schemas/RetentionPolicy--Mini" - }, - { - "description": "A mini representation of a retention policy object\nthat has been assigned to the content." - } - ] + "example": "value >= :amount" }, - "assigned_to": { + "query_params": { + "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.", "type": "object", - "description": "The `type` and `id` of the content that is under\nretention. The `type` can either be `folder`\n`enterprise`, or `metadata_template`.", - "properties": { - "id": { - "type": "string", - "nullable": true, - "example": "a983f69f-e85f-4ph4-9f46-4afdf9c1af65", - "description": "The ID of the folder, enterprise, or metadata template\nthe policy is assigned to.\nSet to null or omit when type is set to enterprise." - }, - "type": { - "type": "string", - "example": "metadata_template", - "description": "The type of resource the policy is assigned to.", - "enum": [ - "folder", - "enterprise", - "metadata_template" - ] - } + "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" } }, - "filter_fields": { + "ancestor_folder_id": { + "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.", + "type": "string", + "example": "0" + }, + "order_by": { + "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.", "type": "array", - "nullable": true, - "description": "An array of field objects. Values are only returned if the `assigned_to`\ntype is `metadata_template`. Otherwise, the array is blank.", "items": { "type": "object", - "nullable": true, + "description": "An object representing one of the metadata template fields to sort the\nmetadata query results by.", "properties": { - "field": { + "field_key": { + "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.", "type": "string", - "nullable": true, - "description": "The metadata attribute key id.", - "example": "a0f4ee4e-1dc1-4h90-a8a9-aef55fc681d4" + "example": "amount" }, - "value": { + "direction": { + "description": "The direction to order by, either ascending or descending.\n\nThe `ordering` direction must be the same for each item in the\narray.", "type": "string", - "nullable": true, - "description": "The metadata attribute field id. For value, only\nenum and multiselect types are supported.", - "example": "0c27b756-0p87-4fe0-a43a-59fb661ccc4e" + "example": "asc", + "enum": [ + "ASC", + "DESC", + "asc", + "desc" + ] } } } }, - "assigned_by": { - "allOf": [ - { - "$ref": "#/components/schemas/User--Mini" - }, - { - "description": "A mini user object representing the user that\ncreated the retention policy assignment." - } - ] - }, - "assigned_at": { - "type": "string", - "format": "date-time", - "description": "When the retention policy assignment object was\ncreated.", - "example": "2012-12-12T10:53:43-08:00" + "limit": { + "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.", + "type": "integer", + "example": 50, + "default": 100, + "maximum": 100, + "minimum": 0 }, - "start_date_field": { + "marker": { + "description": "Marker to use for requesting the next page.", "type": "string", - "description": "The date the retention policy assignment begins.\nIf the `assigned_to` type is `metadata_template`,\nthis field can be a date field's metadata attribute key id.", - "example": "upload_date" - } - } - }, - "RetentionPolicyAssignments": { - "title": "Retention policy assignments", - "type": "object", - "x-box-resource-id": "retention_policy_assignments", - "x-box-tag": "retention_policy_assignments", - "description": "A list of retention policy assignments.", - "allOf": [ - { - "properties": { - "entries": { - "type": "array", - "description": "A list of retention policy assignments", - "items": { - "$ref": "#/components/schemas/RetentionPolicyAssignment" - } - } - } + "example": "AAAAAmVYB1FWec8GH6yWu2nwmanfMh07IyYInaa7DZDYjgO1H4KoLW29vPlLY173OKsci6h6xGh61gG73gnaxoS+o0BbI1/h6le6cikjlupVhASwJ2Cj0tOD9wlnrUMHHw3/ISf+uuACzrOMhN6d5fYrbidPzS6MdhJOejuYlvsg4tcBYzjauP3+VU51p77HFAIuObnJT0ff" }, - { - "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": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", - "type": "string", - "nullable": true - } - } + "fields": { + "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.", + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "extension", + "created_at", + "item_status", + "metadata.enterprise_1234.contracts", + "metadata.enterprise_1234.regions.location" + ] } - ] + }, + "required": [ + "from", + "ancestor_folder_id" + ], + "title": "Metadata query search request" }, - "ShieldInformationBarrier": { - "title": "Shield information barrier", + "MetadataQueryIndex": { + "description": "A metadata query index", "type": "object", - "x-box-resource-id": "shield_information_barrier", - "x-box-tag": "shield_information_barriers", - "x-box-variants": [ - "base", - "standard" - ], - "x-box-variant": "standard", - "description": "A standard representation of a\nshield information barrier object", "properties": { "id": { + "description": "The ID of the metadata query index.", "type": "string", - "example": "11446498", - "description": "The unique identifier for the shield information barrier" + "example": "-9876" }, "type": { + "description": "Value is always `metadata_query_index`", "type": "string", - "description": "The type of the shield information barrier", - "example": "shield_information_barrier", - "enum": [ - "shield_information_barrier" - ] - }, - "enterprise": { - "allOf": [ - { - "$ref": "#/components/schemas/Enterprise--Base" - } - ], - "description": "The `type` and `id` of enterprise this barrier is under." + "example": "metadata_query_index", + "nullable": false }, "status": { + "description": "The status of the metadata query index", "type": "string", + "example": "active", "enum": [ - "draft", - "pending", - "disabled", - "enabled", - "invalid" - ], - "description": "Status of the shield information barrier", - "example": "draft" - }, - "created_at": { - "type": "string", - "format": "date-time", - "example": "2020-06-26T18:44:45.869Z", - "description": "ISO date time string when this\nshield information barrier object was created." - }, - "created_by": { - "allOf": [ - { - "$ref": "#/components/schemas/User--Base" - } + "building", + "active", + "disabled" ], - "description": "The user who created this shield information barrier." + "nullable": false }, - "updated_at": { - "type": "string", - "format": "date-time", - "example": "2020-07-26T18:44:45.869Z", - "description": "ISO date time string when this shield information barrier was updated." + "fields": { + "description": "A list of template fields which make up the index.", + "type": "array", + "items": { + "type": "object", + "description": "The field which makes up the index.", + "allOf": [ + { + "properties": { + "key": { + "description": "The metadata template field key.", + "type": "string", + "example": "vendor name" + }, + "sort_direction": { + "description": "The sort direction of the field.", + "type": "string", + "example": "asc", + "enum": [ + "asc", + "desc" + ] + } + } + } + ] + } + } + }, + "required": [ + "type", + "status" + ], + "title": "Metadata query index", + "x-box-resource-id": "metadata_query_index", + "x-box-tag": "search" + }, + "MetadataQueryResults": { + "description": "A page of files and folders that matched the metadata query.", + "type": "object", + "properties": { + "entries": { + "description": "The mini representation of the files and folders that match the search\nterms.\n\nBy default, this endpoint returns only the most basic info about the\nitems. To get additional fields for each item, including any of the\nmetadata, use the `fields` attribute in the query.", + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/File--Full" + }, + { + "$ref": "#/components/schemas/Folder--Full" + } + ] + }, + "x-box-resource-variant": 1 }, - "updated_by": { - "allOf": [ - { - "$ref": "#/components/schemas/User--Base" - } - ], - "description": "The user that updated this shield information barrier." + "limit": { + "description": "The limit that was used for this search. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed.", + "type": "integer", + "format": "int64", + "example": 100, + "default": 100 }, - "enabled_at": { + "next_marker": { + "description": "The marker for the start of the next page of results.", "type": "string", - "format": "date-time", - "example": "2020-07-26T18:44:45.869Z", - "description": "ISO date time string when this shield information barrier was enabled." - }, - "enabled_by": { - "allOf": [ - { - "$ref": "#/components/schemas/User--Base" - }, - { - "description": "The user that enabled this shield information barrier." - } - ] + "example": "0!-M7487OpVfBTNBV-XsQjU50gQFlbFFu5nArMWD7Ck61GH_Qo40M1S2xN5zWZPBzEjaQS1SOjJiQoo5BsXEl1bCVLRZ2pTqo4SKp9tyqzWQK2L51KR_nC1EgF5I_TJSFw7uO2Bx4HweGETOjh5_2oPSWw5iMkM-OvGApeR0lGFO48FDKoyzJyLgz5aogxoKd8VE09CesOOnTnmZvrW0puylDc-hFjY5YLmWFBKox3SOWiSDwKFkmZGNHyjEzza1nSwbZg6CYsAdGsDwGJhuCeTNsFzP5Mo5qx9wMloS0lSPuf2CcBInbIJzl2CKlXF3FvqhANttpm2nzdBTQRSoJyJnjVBpf4Q_HjV2eb4KIZBBlLy067UCVdv2AAWQFd5E2i6s1YiGRTtgMEZntOSUYD4IYLMWWm5Ra7ke_SP32SL3GSjbBQYIyCVQ.." } - } + }, + "title": "Metadata query search results", + "x-box-resource-id": "metadata_query_results", + "x-box-tag": "search" }, - "ShieldInformationBarrier--Base": { - "title": "Shield information barrier (Base)", + "MetadataTemplate": { + "description": "A template for metadata that can be applied to files and folders", "type": "object", - "x-box-resource-id": "shield_information_barrier--base", - "x-box-tag": "shield_information_barriers", - "x-box-variants": [ - "base", - "standard" - ], - "x-box-variant": "base", - "description": "A base representation of a\nshield information barrier object", "properties": { "id": { + "description": "The ID of the metadata template.", "type": "string", - "example": "11446498", - "description": "The unique identifier for the shield information barrier" + "example": "58063d82-4128-7b43-bba9-92f706befcdf" }, "type": { + "description": "`metadata_template`", "type": "string", - "description": "The type of the shield information barrier", - "example": "shield_information_barrier", + "example": "metadata_template", "enum": [ - "shield_information_barrier" - ] + "metadata_template" + ], + "nullable": false + }, + "scope": { + "description": "The scope of the metadata template can either be `global` or\n`enterprise_*`. The `global` scope is used for templates that are\navailable to any Box enterprise. The `enterprise_*` scope represents\ntemplates that have been created within a specific enterprise, where `*`\nwill be the ID of that enterprise.", + "type": "string", + "example": "enterprise_123456" + }, + "templateKey": { + "description": "A unique identifier for the template. This identifier is unique across\nthe `scope` of the enterprise to which the metadata template is being\napplied, yet is not necessarily unique across different enterprises.", + "type": "string", + "example": "productInfo", + "maxLength": 64, + "pattern": "^[a-zA-Z_][-a-zA-Z0-9_]*$" + }, + "displayName": { + "description": "The display name of the template. This can be seen in the Box web app\nand mobile apps.", + "type": "string", + "example": "Product Info", + "maxLength": 4096 + }, + "hidden": { + "description": "Defines if this template is visible in the Box web app UI, or if\nit is purely intended for usage through the API.", + "type": "boolean", + "example": true + }, + "fields": { + "description": "An ordered list of template fields which are part of the template. Each\nfield can be a regular text field, date field, number field, as well as a\nsingle or multi-select list.", + "type": "array", + "items": { + "type": "object", + "description": "A field within a metadata template. Fields can be a basic text, date, or\nnumber field, or a list of options.", + "allOf": [ + { + "title": "Metadata Field (Read)", + "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": { + "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.\n\n**Note**: The `integer` value is deprecated.\nIt is still present in the response,\nbut cannot be used in the POST request.", + "type": "string", + "example": "string", + "enum": [ + "string", + "float", + "date", + "enum", + "multiSelect", + "integer" + ] + }, + "key": { + "description": "A unique identifier for the field. The identifier must\nbe unique within the template to which it belongs.", + "type": "string", + "example": "category", + "maxLength": 256 + }, + "displayName": { + "description": "The display name of the field as it is shown to the user in the web and\nmobile apps.", + "type": "string", + "example": "Category", + "maxLength": 4096 + }, + "description": { + "description": "A description of the field. This is not shown to the user.", + "type": "string", + "example": "The category", + "maxLength": 4096 + }, + "hidden": { + "description": "Whether this field is hidden in the UI for the user and can only be set\nthrough the API instead.", + "type": "boolean", + "example": true + }, + "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.", + "type": "string", + "example": "Category 1" + } + } + } + } + } + }, + { + "properties": { + "id": { + "description": "The unique ID of the metadata template field.", + "type": "string", + "example": "822227e0-47a5-921b-88a8-494760b2e6d2" + }, + "options": { + "description": "A list of options for this field. This is used in combination\nwith the `enum` and `multiSelect` field types.", + "type": "array", + "items": { + "type": "object", + "description": "An option for a Metadata Template Field.\n\nOptions are only present for fields of type `enum` and\n`multiSelect`. Options represent the value(s) a user can\nselect for the field either through the UI or through the API.", + "allOf": [ + { + "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.", + "type": "string", + "example": "Category 1" + } + } + }, + { + "properties": { + "id": { + "description": "The internal unique identifier of the the option.", + "type": "string", + "example": "45dc2849-a4a7-40a9-a751-4a699a589190" + } + } + } + ] + } + } + } + } + ] + } + }, + "copyInstanceOnItemCopy": { + "description": "Whether or not to include the metadata when a file or folder is copied.", + "type": "boolean", + "example": true } - } + }, + "required": [ + "type", + "id" + ], + "title": "Metadata template", + "x-box-resource-id": "metadata_template", + "x-box-tag": "metadata_templates" }, - "ShieldInformationBarriers": { - "title": "List of Shield Information Barriers", + "MetadataTemplates": { + "description": "A list of metadata templates", "type": "object", - "x-box-resource-id": "shield_information_barriers", - "x-box-tag": "shield_information_barriers", - "description": "List of Shield Information Barrier objects", "allOf": [ { "type": "object", @@ -32341,14 +31876,20 @@ "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" + "format": "int64", + "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", + "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } @@ -32356,406 +31897,415 @@ { "properties": { "entries": { + "description": "A list of metadata templates", "type": "array", - "description": "A list of shield information barrier objects", "items": { - "$ref": "#/components/schemas/ShieldInformationBarrier" + "$ref": "#/components/schemas/MetadataTemplate" } } } } - ] + ], + "title": "Metadata templates", + "x-box-resource-id": "metadata_templates", + "x-box-tag": "metadata_templates" }, - "ShieldInformationBarrierReport": { - "title": "Shield information barrier report", + "Metadatas": { + "description": "A list of metadata instances that have been applied to a file or folder.", "type": "object", - "x-box-resource-id": "shield_information_barrier_report", - "x-box-tag": "shield_information_barrier_reports", - "x-box-variants": [ - "base", - "standard" - ], - "x-box-variant": "standard", - "description": "A standard representation\nof a shield information barrier report object", - "allOf": [ - { - "$ref": "#/components/schemas/ShieldInformationBarrierReport--Base" - }, - { - "properties": { - "shield_information_barrier": { - "allOf": [ - { - "$ref": "#/components/schemas/ShieldInformationBarrierReference" - } - ] - }, - "status": { - "type": "string", - "enum": [ - "pending", - "error", - "done", - "cancelled" - ], - "description": "Status of the shield information report", - "example": "pending" - }, - "details": { - "allOf": [ - { - "$ref": "#/components/schemas/ShieldInformationBarrierReportDetails" - } - ] - }, - "created_at": { - "type": "string", - "format": "date-time", - "example": "2020-06-26T18:44:45.869Z", - "description": "ISO date time string when this\nshield information barrier report object was created." - }, - "created_by": { - "allOf": [ - { - "$ref": "#/components/schemas/User--Base" - }, - { - "description": "The user who created this shield information barrier report." - } - ] - }, - "updated_at": { - "type": "string", - "format": "date-time", - "example": "2020-07-26T18:44:45.869Z", - "description": "ISO date time string when this\nshield information barrier report was updated." - } + "properties": { + "entries": { + "description": "A list of metadata instances, as applied to this file or folder.", + "type": "array", + "items": { + "$ref": "#/components/schemas/Metadata" } + }, + "limit": { + "description": "The limit that was used for this page of results.", + "type": "integer", + "example": 100 } - ] + }, + "title": "Metadata instances", + "x-box-resource-id": "metadatas", + "x-box-tag": "file_metadata" }, - "ShieldInformationBarrierReport--Base": { - "title": "Shield information barrier report (Base)", + "OAuth2Error": { + "description": "An OAuth 2.0 error", "type": "object", - "x-box-resource-id": "shield_information_barrier_report--base", - "x-box-tag": "shield_information_barrier_reports", - "x-box-variants": [ - "base", - "standard" - ], - "x-box-variant": "base", - "description": "A base representation of a\nshield information barrier report object", "properties": { - "id": { + "error": { + "description": "The type of the error returned.", "type": "string", - "example": "11446498", - "description": "The unique identifier for the shield information barrier report" + "example": "invalid_client" }, - "type": { + "error_description": { + "description": "The type of the error returned.", "type": "string", - "description": "The type of the shield information barrier report", - "example": "shield_information_barrier_report", - "enum": [ - "shield_information_barrier_report" - ] - } - } - }, - "ShieldInformationBarrierReports": { - "title": "List of Shield Information Barrier Reports", - "type": "object", - "x-box-resource-id": "shield_information_barrier_reports", - "x-box-tag": "shield_information_barrier_reports", - "description": "A list of shield barrier reports.", - "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": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", - "type": "string", - "nullable": true - } - } - }, - { - "properties": { - "entries": { - "type": "array", - "description": "A list of shield information\nbarrier reports.", - "items": { - "$ref": "#/components/schemas/ShieldInformationBarrierReport" - } - } - } + "example": "The client credentials are not valid" } - ] + }, + "title": "OAuth 2.0 error", + "x-box-resource-id": "oauth2_error", + "x-box-tag": "authorization" }, - "ShieldInformationBarrierSegment": { - "title": "Shield information barrier segment", + "Outcome": { + "description": "An instance of an outcome.", "type": "object", - "x-box-resource-id": "shield_information_barrier_segment", - "x-box-tag": "shield_information_barrier_segments", - "description": "A shield information barrier segment object", "properties": { "id": { + "description": "ID of a specific outcome", "type": "string", - "example": "11446498", - "description": "The unique identifier for the shield information barrier segment" + "example": "17363629" }, - "type": { - "type": "string", - "description": "The type of the shield information barrier segment", - "example": "shield_information_barrier_segment", - "enum": [ - "shield_information_barrier_segment" + "collaborators": { + "allOf": [ + { + "$ref": "#/components/schemas/CollaboratorVariable" + }, + { + "description": "Lists collaborators\naffected by the workflow\nresult." + } ] }, - "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 advisory_based financial\n transactions on behalf of individuals, corporations, and governments.'", - "description": "Description of the shield information barrier segment" - }, - "created_at": { - "type": "string", - "format": "date-time", - "example": "2020-06-26T18:44:45.869Z", - "description": "ISO date time string when this shield information\nbarrier object was created." + "completion_rule": { + "allOf": [ + { + "$ref": "#/components/schemas/CompletionRuleVariable" + }, + { + "description": "Determines\nif an action should be completed\nby all or any assignees." + } + ] }, - "created_by": { + "file_collaborator_role": { "allOf": [ { - "$ref": "#/components/schemas/User--Base" + "$ref": "#/components/schemas/RoleVariable" }, { - "description": "The user who created this shield information barrier segment." + "description": "Determines if the\nworkflow outcome for\na file\naffects a specific\ncollaborator role." } ] }, - "updated_at": { - "type": "string", - "format": "date-time", - "example": "2020-07-26T18:44:45.869Z", - "description": "ISO date time string when this\nshield information barrier segment was updated." + "task_collaborators": { + "allOf": [ + { + "$ref": "#/components/schemas/CollaboratorVariable" + }, + { + "description": "Lists collaborators\naffected by the task workflow\nresult." + } + ] }, - "updated_by": { + "role": { "allOf": [ { - "$ref": "#/components/schemas/User--Base" + "$ref": "#/components/schemas/RoleVariable" }, { - "description": "The user that updated this shield information barrier segment." + "description": "Determines if the\nworkflow outcome\naffects a specific\ncollaborator role." } ] } - } + }, + "required": [ + "id" + ], + "title": "Outcome" }, - "ShieldInformationBarrierSegments": { - "title": "List of Shield Information Barrier Segments", + "PostOAuth2Revoke": { + "description": "A request to revoke an OAuth 2.0 token", "type": "object", - "x-box-resource-id": "shield_information_barrier_segments", - "x-box-tag": "shield_information_barrier_segments", - "description": "List of Shield Information Barrier Segment objects", - "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": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", - "type": "string", - "nullable": true - } - } + "properties": { + "client_id": { + "description": "The Client ID of the application requesting to revoke the\naccess token.", + "type": "string", + "example": "ly1nj6n11vionaie65emwzk575hnnmrk" }, - { - "properties": { - "entries": { - "type": "array", - "description": "A list of shield information barrier\nsegments", - "items": { - "$ref": "#/components/schemas/ShieldInformationBarrierSegment" - } - } - } + "client_secret": { + "description": "The client secret of the application requesting to revoke\nan access token.", + "type": "string", + "example": "hOzsTeFlT6ko0dme22uGbQal04SBPYc1" + }, + "token": { + "description": "The access token to revoke.", + "type": "string", + "format": "token", + "example": "n22JPxrh18m4Y0wIZPIqYZK7VRrsMTWW" } - ] + }, + "required": [ + "grant_type" + ], + "title": "Token revocation request" }, - "ShieldInformationBarrierSegmentMember": { - "title": "Shield information barrier segment member", + "PostOAuth2Token": { + "description": "A request for a new OAuth 2.0 token", "type": "object", - "x-box-resource-id": "shield_information_barrier_segment_member", - "x-box-tag": "shield_information_barrier_segment_members", - "x-box-variants": [ - "base", - "mini", - "standard" - ], - "x-box-variant": "standard", - "description": "A standard representation of a\nshield information barrier segment member object", - "allOf": [ - { - "$ref": "#/components/schemas/ShieldInformationBarrierSegmentMember--Mini" + "properties": { + "grant_type": { + "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.", + "type": "string", + "format": "urn", + "example": "authorization_code", + "enum": [ + "authorization_code", + "refresh_token", + "client_credentials", + "urn:ietf:params:oauth:grant-type:jwt-bearer", + "urn:ietf:params:oauth:grant-type:token-exchange" + ] }, - { - "properties": { - "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 requesting\nshield information barrier segment." - }, - "type": { - "type": "string", - "example": "shield_information_barrier_segment", - "description": "The type of the shield information barrier segment", - "enum": [ - "shield_information_barrier_segment" - ] - } - }, - "description": "The `type` and `id` of the requested\nshield information barrier segment." - }, - "user": { - "allOf": [ - { - "$ref": "#/components/schemas/User--Base" - }, - { - "description": "The `type` and `id` of the requested shield information barrier segment member." - } - ] - }, - "created_at": { - "type": "string", - "format": "date-time", - "example": "2020-06-26T18:44:45.869Z", - "description": "ISO date time string when this shield\ninformation barrier object was created." - }, - "created_by": { - "allOf": [ - { - "$ref": "#/components/schemas/User--Base" - }, - { - "description": "The user who created this shield information barrier segment member." - } - ] - }, - "updated_at": { - "type": "string", - "format": "date-time", - "example": "2020-07-26T18:44:45.869Z", - "description": "ISO date time string when this\nshield information barrier segment Member was updated." - }, - "updated_by": { - "allOf": [ - { - "$ref": "#/components/schemas/User--Base" - }, - { - "description": "The user that updated this shield information barrier segment Member." - } - ] - } - } + "client_id": { + "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`.", + "type": "string", + "example": "ly1nj6n11vionaie65emwzk575hnnmrk" + }, + "client_secret": { + "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`.", + "type": "string", + "example": "hOzsTeFlT6ko0dme22uGbQal04SBPYc1" + }, + "code": { + "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`.", + "type": "string", + "format": "token", + "example": "n22JPxrh18m4Y0wIZPIqYZK7VRrsMTWW" + }, + "refresh_token": { + "description": "A refresh token used to get a new access token with.\n\nUsed in combination with `refresh_token` as the `grant_type`.", + "type": "string", + "format": "token", + "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" + }, + "assertion": { + "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`.", + "type": "string", + "format": "jwt", + "example": "xxxxx.yyyyy.zzzzz" + }, + "subject_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`.", + "type": "string", + "format": "token", + "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" + }, + "subject_token_type": { + "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`.", + "type": "string", + "example": "urn:ietf:params:oauth:token-type:access_token", + "enum": [ + "urn:ietf:params:oauth:token-type:access_token" + ] + }, + "actor_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`.", + "type": "string", + "format": "token", + "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" + }, + "actor_token_type": { + "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`.", + "type": "string", + "format": "urn", + "example": "urn:ietf:params:oauth:token-type:id_token", + "enum": [ + "urn:ietf:params:oauth:token-type:id_token" + ] + }, + "scope": { + "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**.", + "type": "string", + "format": "space_delimited_list", + "example": "item_upload item_preview base_explorer" + }, + "resource": { + "description": "Full URL for the file that the token should be generated for.", + "type": "string", + "format": "url", + "example": "https://api.box.com/2.0/files/123456" + }, + "box_subject_type": { + "description": "Used in combination with `client_credentials` as the `grant_type`.", + "type": "string", + "example": "enterprise", + "enum": [ + "enterprise", + "user" + ] + }, + "box_subject_id": { + "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.", + "type": "string", + "example": "123456789" + }, + "box_shared_link": { + "description": "Full URL of the shared link on the file or folder\nthat the token should be generated for.", + "type": "string", + "format": "url", + "example": "https://cloud.box.com/s/123456" } - ] + }, + "required": [ + "grant_type" + ], + "title": "Token request" }, - "ShieldInformationBarrierSegmentMember--Base": { - "title": "Shield information barrier segment member (Base)", + "PostOAuth2Token--RefreshAccessToken": { + "description": "A request to refresh an Access Token. Use this API to refresh an expired\nAccess Token using a valid Refresh Token.", "type": "object", - "x-box-resource-id": "shield_information_barrier_segment_member--base", - "x-box-tag": "shield_information_barrier_segment_members", - "x-box-variants": [ - "base", - "mini", - "standard" - ], - "x-box-variant": "base", - "description": "A base representation of a\nshield information barrier segment member object", "properties": { - "id": { + "grant_type": { + "description": "The type of request being made, in this case a refresh request.", + "type": "string", + "format": "urn", + "example": "refresh_token", + "enum": [ + "refresh_token" + ] + }, + "client_id": { + "description": "The client ID of the application requesting to refresh the token.", + "type": "string", + "example": "ly1nj6n11vionaie65emwzk575hnnmrk" + }, + "client_secret": { + "description": "The client secret of the application requesting to refresh the token.", "type": "string", - "example": "11446498", - "description": "The unique identifier for the\nshield information barrier segment member" + "example": "hOzsTeFlT6ko0dme22uGbQal04SBPYc1" }, + "refresh_token": { + "description": "The refresh token to refresh.", + "type": "string", + "format": "token", + "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" + } + }, + "required": [ + "grant_type", + "client_id", + "client_secret", + "refresh_token" + ], + "title": "Refresh access token" + }, + "RealtimeServer": { + "description": "A real-time server that can be used for\nlong polling user events", + "type": "object", + "properties": { "type": { + "description": "`realtime_server`", "type": "string", - "description": "The type of the shield information barrier segment member", - "example": "shield_information_barrier_segment_member", - "enum": [ - "shield_information_barrier_segment_member" - ] + "example": "realtime_server" + }, + "url": { + "description": "The URL for the server.", + "type": "string", + "example": "http://2.realtime.services.box.net/subscribe?channel=cc807c9c4869ffb1c81a&stream_type=all" + }, + "ttl": { + "description": "The time in minutes for which this server is available", + "type": "string", + "example": "10" + }, + "max_retries": { + "description": "The maximum number of retries this server will\nallow before a new long poll should be started by\ngetting a [new list of server](#options-events).", + "type": "string", + "example": "10" + }, + "retry_timeout": { + "description": "The maximum number of seconds without a response\nafter which you should retry the long poll connection.\n\nThis helps to overcome network issues where the long\npoll looks to be working but no packages are coming\nthrough.", + "type": "integer", + "example": 610 } - } + }, + "title": "Real-time server", + "x-box-resource-id": "realtime_server" }, - "ShieldInformationBarrierSegmentMember--Mini": { - "title": "Shield information barrier segment member (Mini)", + "RealtimeServers": { + "description": "A list of real-time servers that can\nbe used for long-polling.", "type": "object", - "x-box-resource-id": "shield_information_barrier_segment_member--mini", - "x-box-tag": "shield_information_barrier_segment_members", - "x-box-variants": [ - "base", - "mini", - "standard" - ], - "x-box-variant": "mini", - "description": "A mini representation of a\nshield information barrier segment member object", - "allOf": [ - { - "$ref": "#/components/schemas/ShieldInformationBarrierSegmentMember--Base" + "properties": { + "chunk_size": { + "description": "The number of items in this response.", + "type": "integer", + "format": "int64", + "example": 1 }, - { - "properties": { - "user": { - "allOf": [ + "entries": { + "description": "A list of real-time servers", + "type": "array", + "items": { + "$ref": "#/components/schemas/RealtimeServer" + } + } + }, + "title": "Real-time servers", + "x-box-resource-id": "realtime_servers", + "x-box-tag": "events" + }, + "RecentItem": { + "description": "A recent item accessed by a user.", + "type": "object", + "properties": { + "type": { + "description": "`recent_item`", + "type": "string", + "example": "recent_item" + }, + "item": { + "allOf": [ + { + "oneOf": [ { - "$ref": "#/components/schemas/User--Base" + "$ref": "#/components/schemas/File--Full" }, { - "description": "The `type` and `id` of the requested shield information barrier segment member." + "$ref": "#/components/schemas/Folder--Full" + }, + { + "$ref": "#/components/schemas/WebLink" } ] + }, + { + "description": "The item that was recently accessed." } - } + ] + }, + "interaction_type": { + "description": "The most recent type of access the user performed on\nthe item.", + "type": "string", + "example": "item_preview", + "enum": [ + "item_preview", + "item_upload", + "item_comment", + "item_open", + "item_modify" + ] + }, + "interacted_at": { + "description": "The time of the most recent interaction.", + "type": "string", + "format": "date-time", + "example": "2018-04-13T13:53:23-07:00" + }, + "interaction_shared_link": { + "description": "If the item was accessed through a shared link it will appear here,\notherwise this will be null.", + "type": "string", + "example": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg" } - ] + }, + "title": "Recent item", + "x-box-resource-id": "recent_item", + "x-box-tag": "recent_items" }, - "ShieldInformationBarrierSegmentMembers": { - "title": "List of Shield Information Barrier Segment Members", + "RecentItems": { + "description": "A list of recent items.", "type": "object", - "x-box-resource-id": "shield_information_barrier_segment_members", - "x-box-tag": "shield_information_barrier_segment_members", - "description": "List of Shield Information Barrier Member objects", "allOf": [ { "type": "object", @@ -32763,14 +32313,20 @@ "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" + "format": "int64", + "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", + "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } @@ -32778,241 +32334,525 @@ { "properties": { "entries": { + "description": "A list of recent items", "type": "array", - "description": "A list of shield information\nbarrier segment members", "items": { - "$ref": "#/components/schemas/ShieldInformationBarrierSegmentMember" + "$ref": "#/components/schemas/RecentItem" } } } } - ] + ], + "title": "Recent items", + "x-box-resource-id": "recent_items" }, - "ShieldInformationBarrierSegmentRestriction": { - "title": "Shield information barrier segment restriction", + "RetentionPolicies": { + "description": "A list of retention policies.", "type": "object", - "x-box-resource-id": "shield_information_barrier_segment_restriction", - "x-box-tag": "shield_information_barrier_segment_restrictions", - "x-box-variants": [ - "base", - "mini", - "standard" - ], - "x-box-variant": "standard", - "description": "A standard representation of a\nsegment restriction of a shield information barrier\nobject", - "required": [ - "shield_information_barrier_segment", - "restricted_segment" + "allOf": [ + { + "properties": { + "entries": { + "description": "A list in which each entry represents a retention policy object.", + "type": "array", + "items": { + "$ref": "#/components/schemas/RetentionPolicy" + } + } + } + }, + { + "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.", + "type": "integer", + "format": "int64", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + } + } + } ], + "title": "Retention policies", + "x-box-resource-id": "retention_policies", + "x-box-tag": "retention_policies" + }, + "RetentionPolicy": { + "description": "A retention policy blocks permanent deletion of content\nfor a specified amount of time. Admins can create retention\npolicies and then later assign them to specific folders, metadata\ntemplates, or their entire enterprise. To use this feature, you must\nhave the manage retention policies scope enabled\nfor your API key via your application management console.", + "type": "object", "allOf": [ { - "$ref": "#/components/schemas/ShieldInformationBarrierSegmentRestriction--Mini" + "$ref": "#/components/schemas/RetentionPolicy--Mini" }, { "properties": { - "shield_information_barrier": { - "$ref": "#/components/schemas/ShieldInformationBarrier--Base" + "description": { + "description": "The additional text description of the retention policy.", + "type": "string", + "example": "Policy to retain all reports for at least one month" }, - "created_at": { + "policy_type": { + "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.", "type": "string", - "format": "date-time", - "example": "2020-06-26T18:44:45.869Z", - "description": "ISO date time string when this\nshield information barrier\nSegment Restriction object was created." + "example": "finite", + "enum": [ + "finite", + "indefinite" + ] + }, + "retention_type": { + "description": "Specifies the retention type:\n\n* `modifiable`: You can modify the retention policy. For example,\n you can add or remove folders, shorten or lengthen\n the policy duration, or delete the assignment.\n Use this type if your retention policy\n is not related to any regulatory purposes.\n\n* `non-modifiable`: You can modify the retention policy\n only in a limited way: add a folder, lengthen the duration,\n retire the policy, change the disposition action\n or notification settings. You cannot perform other actions,\n such as deleting the assignment or shortening the\n policy duration. Use this type to ensure\n compliance with regulatory retention policies.", + "type": "string", + "example": "non_modifiable", + "enum": [ + "modifiable", + "non_modifiable" + ] + }, + "status": { + "description": "The status of the retention policy. The status of\na policy will be `active`, unless explicitly retired by an\nadministrator, in which case the status will be `retired`.\nOnce a policy has been retired, it cannot become\nactive again.", + "type": "string", + "example": "active", + "enum": [ + "active", + "retired" + ] }, "created_by": { "allOf": [ { - "$ref": "#/components/schemas/User--Base" + "$ref": "#/components/schemas/User--Mini" }, { - "description": "The user who created this shield information barrier segment Restriction." + "description": "A mini user object representing the user that\ncreated the retention policy." } ] }, - "updated_at": { + "created_at": { + "description": "When the retention policy object was created.", "type": "string", "format": "date-time", - "example": "2020-07-26T18:44:45.869Z", - "description": "ISO date time string when this\nshield information barrier segment\nRestriction was updated." + "example": "2012-12-12T10:53:43-08:00" }, - "updated_by": { - "allOf": [ - { - "$ref": "#/components/schemas/User--Base" - }, - { - "description": "The user that updated this shield information barrier segment Restriction." - } - ] - } - } - } - ] - }, - "ShieldInformationBarrierSegmentRestriction--Base": { - "title": "Shield information barrier segment restriction (Base)", + "modified_at": { + "description": "When the retention policy object was last modified.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "can_owner_extend_retention": { + "description": "Determines if the owner of items under the policy\ncan extend the retention when the original\nretention duration is about to end.", + "type": "boolean", + "example": false + }, + "are_owners_notified": { + "description": "Determines if owners and co-owners of items\nunder the policy are notified when\nthe retention duration is about to end.", + "type": "boolean", + "example": false + }, + "custom_notification_recipients": { + "description": "A list of users notified when the retention policy duration is about to end.", + "type": "array", + "items": { + "$ref": "#/components/schemas/User--Mini" + } + }, + "assignment_counts": { + "description": "Counts the retention policy assignments for each item type.", + "type": "object", + "properties": { + "enterprise": { + "description": "The number of enterprise assignments this policy has. The maximum value is 1.", + "type": "integer", + "format": "int64", + "example": 1 + }, + "folder": { + "description": "The number of folder assignments this policy has.", + "type": "integer", + "format": "int64", + "example": 1 + }, + "metadata_template": { + "description": "The number of metadata template assignments this policy has.", + "type": "integer", + "format": "int64", + "example": 1 + } + } + } + } + } + ], + "title": "Retention policy", + "x-box-resource-id": "retention_policy", + "x-box-tag": "retention_policies", + "x-box-variant": "standard" + }, + "RetentionPolicy--Base": { + "description": "A base representation of a retention policy.", "type": "object", - "x-box-resource-id": "shield_information_barrier_segment_restriction--base", - "x-box-tag": "shield_information_barrier_segment_restrictions", + "properties": { + "id": { + "description": "The unique identifier that represents a retention policy.", + "type": "string", + "example": "12345", + "nullable": false + }, + "type": { + "description": "`retention_policy`", + "type": "string", + "example": "retention_policy", + "enum": [ + "retention_policy" + ], + "nullable": false + } + }, + "required": [ + "id", + "type" + ], + "title": "Retention policy (Base)", + "x-box-resource-id": "retention_policy--base", + "x-box-tag": "retention_policies", + "x-box-variant": "base", "x-box-variants": [ "base", "mini", "standard" + ] + }, + "RetentionPolicy--Mini": { + "description": "A mini representation of a retention policy, used when\nnested within another resource.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/RetentionPolicy--Base" + }, + { + "properties": { + "policy_name": { + "description": "The name given to the retention policy.", + "type": "string", + "example": "Some Policy Name" + }, + "retention_length": { + "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`.", + "type": "string", + "format": "int32", + "example": "365", + "minimum": 1 + }, + "disposition_action": { + "description": "The disposition action of the retention policy.\nThis action can be `permanently_delete`, which\nwill cause the content retained by the policy\nto be permanently deleted, or `remove_retention`,\nwhich will lift the retention policy from the content,\nallowing it to be deleted by users,\nonce the retention policy has expired.", + "type": "string", + "example": "permanently_delete", + "enum": [ + "permanently_delete", + "remove_retention" + ] + } + } + } ], - "x-box-variant": "base", - "description": "A base representation of\na segment restriction object for\nthe shield information barrier", - "required": [ - "shield_information_barrier_segment", - "restricted_segment" - ], + "title": "Retention policy (Mini)", + "x-box-resource-id": "retention_policy--mini", + "x-box-variant": "mini" + }, + "RetentionPolicyAssignment": { + "description": "A retention assignment represents a rule specifying\nthe files a retention policy retains.\nAssignments can retain files based on their folder or metadata,\nor hold all files in the enterprise.", + "type": "object", "properties": { + "id": { + "description": "The unique identifier for a retention policy assignment.", + "type": "string", + "example": "11446498" + }, "type": { + "description": "`retention_policy_assignment`", "type": "string", - "description": "Shield information barrier segment restriction", - "example": "shield_information_barrier_segment_restriction", + "example": "retention_policy_assignment", "enum": [ - "shield_information_barrier_segment_restriction" + "retention_policy_assignment" ] }, - "id": { + "retention_policy": { + "allOf": [ + { + "$ref": "#/components/schemas/RetentionPolicy--Mini" + }, + { + "description": "A mini representation of a retention policy object\nthat has been assigned to the content." + } + ] + }, + "assigned_to": { + "description": "The `type` and `id` of the content that is under\nretention. The `type` can either be `folder`\n`enterprise`, or `metadata_template`.", + "type": "object", + "properties": { + "id": { + "description": "The ID of the folder, enterprise, or metadata template\nthe policy is assigned to.\nSet to null or omit when type is set to enterprise.", + "type": "string", + "example": "a983f69f-e85f-4ph4-9f46-4afdf9c1af65", + "nullable": true + }, + "type": { + "description": "The type of resource the policy is assigned to.", + "type": "string", + "example": "metadata_template", + "enum": [ + "folder", + "enterprise", + "metadata_template" + ] + } + } + }, + "filter_fields": { + "description": "An array of field objects. Values are only returned if the `assigned_to`\ntype is `metadata_template`. Otherwise, the array is blank.", + "type": "array", + "items": { + "type": "object", + "nullable": true, + "properties": { + "field": { + "description": "The metadata attribute key id.", + "type": "string", + "example": "a0f4ee4e-1dc1-4h90-a8a9-aef55fc681d4", + "nullable": true + }, + "value": { + "description": "The metadata attribute field id. For value, only\nenum and multiselect types are supported.", + "type": "string", + "example": "0c27b756-0p87-4fe0-a43a-59fb661ccc4e", + "nullable": true + } + } + }, + "nullable": true + }, + "assigned_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "A mini user object representing the user that\ncreated the retention policy assignment." + } + ] + }, + "assigned_at": { + "description": "When the retention policy assignment object was\ncreated.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "start_date_field": { + "description": "The date the retention policy assignment begins.\nIf the `assigned_to` type is `metadata_template`,\nthis field can be a date field's metadata attribute key id.", "type": "string", - "example": "11446498", - "description": "The unique identifier for the\nshield information barrier segment restriction." + "example": "upload_date" } - } + }, + "required": [ + "id", + "type" + ], + "title": "Retention policy assignment", + "x-box-resource-id": "retention_policy_assignment", + "x-box-tag": "retention_policy_assignments" }, - "ShieldInformationBarrierSegmentRestriction--Mini": { - "title": "Shield information barrier segment restriction (Mini)", + "RetentionPolicyAssignment--Base": { + "description": "A base representation of a retention policy assignment.", "type": "object", - "x-box-resource-id": "shield_information_barrier_segment_restriction--mini", - "x-box-tag": "shield_information_barrier_segment_restrictions", + "properties": { + "id": { + "description": "The unique identifier that represents a file version.", + "type": "string", + "example": "12345", + "nullable": false + }, + "type": { + "description": "`retention_policy_assignment`", + "type": "string", + "example": "retention_policy_assignment", + "enum": [ + "retention_policy_assignment" + ], + "nullable": false + } + }, + "required": [ + "id", + "type" + ], + "title": "Retention policy assignment (Base)", + "x-box-resource-id": "retention_policy_assignment--base", + "x-box-tag": "retention_policy_assignments", + "x-box-variant": "base", "x-box-variants": [ "base", - "mini", "standard" - ], - "x-box-variant": "mini", - "description": "A mini representation of\na segment restriction object for\nthe shield information barrier", - "required": [ - "shield_information_barrier_segment", - "restricted_segment" - ], + ] + }, + "RetentionPolicyAssignments": { + "description": "A list of retention policy assignments.", + "type": "object", "allOf": [ - { - "$ref": "#/components/schemas/ShieldInformationBarrierSegmentRestriction--Base" - }, { "properties": { - "shield_information_barrier_segment": { - "type": "object", - "properties": { - "id": { - "type": "string", - "example": "1910967", - "description": "The ID reference of the\nrequesting shield information barrier segment." - }, - "type": { - "type": "string", - "description": "The type of the shield information barrier segment", - "example": "shield_information_barrier_segment", - "enum": [ - "shield_information_barrier_segment" - ] - } - }, - "description": "The `type` and `id` of the\nrequested shield information barrier segment." - }, - "restricted_segment": { - "type": "object", - "properties": { - "id": { - "type": "string", - "example": "1910967", - "description": "The ID reference of the\nrestricted shield information barrier segment." - }, - "type": { - "type": "string", - "description": "The type of the shield information segment", - "example": "shield_information_barrier_segment", - "enum": [ - "shield_information_barrier_segment" - ] - } - }, - "description": "The `type` and `id` of the\nrestricted shield information barrier segment." + "entries": { + "description": "A list of retention policy assignments", + "type": "array", + "items": { + "$ref": "#/components/schemas/RetentionPolicyAssignment" + } } } - } - ] - }, - "ShieldInformationBarrierSegmentRestrictions": { - "title": "List of Shield Information Barrier Segment Restrictions", - "type": "object", - "x-box-resource-id": "shield_information_barrier_segment_restrictions", - "x-box-tag": "shield_information_barrier_segment_restrictions", - "description": "List of shield information barrier segment restriction objects", - "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" + "format": "int64", + "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true } } + } + ], + "title": "Retention policy assignments", + "x-box-resource-id": "retention_policy_assignments", + "x-box-tag": "retention_policy_assignments" + }, + "RoleVariable": { + "description": "Determines if the\nworkflow outcome\naffects a specific\ncollaborator role.", + "type": "object", + "properties": { + "type": { + "description": "Role object type.\n", + "type": "string", + "example": "variable", + "enum": [ + "variable" + ] }, - { - "properties": { - "entries": { - "type": "array", - "description": "A list of shield information barrier\nsegment restriction objects", - "items": { - "$ref": "#/components/schemas/ShieldInformationBarrierSegmentRestriction" - } + "variable_type": { + "description": "The variable type used\nby the object.\n", + "type": "string", + "example": "collaborator_role", + "enum": [ + "collaborator_role" + ] + }, + "variable_value": { + "allOf": [ + { + "type": "string", + "description": "The level of access granted.", + "example": "editor", + "enum": [ + "editor", + "viewer", + "previewer", + "uploader", + "previewer uploader", + "viewer uploader", + "co-owner" + ] + }, + { + "description": "Variable values you can use\nfor the role parameter." } - } + ] } - ] + }, + "required": [ + "type", + "variable_type", + "variable_value" + ], + "title": "Role variable" }, - "SearchResults": { - "title": "Search Results", + "SearchResultWithSharedLink": { + "description": "A single of files, folder or web link that matched the search query,\nincluding the additional information about the shared link through\nwhich the item has been shared with the user.\n\nThis response format is only returned when the\n`include_recent_shared_links` query parameter has been set to `true`.", "type": "object", - "x-box-resource-id": "search_results", - "x-box-tag": "search", + "properties": { + "accessible_via_shared_link": { + "description": "The optional shared link through which the user has access to this\nitem. This value is only returned for items for which the user has\nrecently accessed the file through a shared link. For all other\nitems this value will return `null`.", + "type": "string", + "format": "url", + "example": "https://www.box.com/s/vspke7y05sb214wjokpk" + }, + "item": { + "allOf": [ + { + "oneOf": [ + { + "$ref": "#/components/schemas/File--Full" + }, + { + "$ref": "#/components/schemas/Folder--Full" + }, + { + "$ref": "#/components/schemas/WebLink" + } + ] + }, + { + "description": "The file, folder or web link that matched the\nsearch query." + } + ] + }, + "type": { + "description": "The result type. The value is always `search_result`.", + "type": "string", + "example": "search_result" + } + }, + "title": "Search Result (including Shared Link)", + "x-box-resource-id": "search_result_with_shared_link", + "x-box-tag": "search" + }, + "SearchResults": { "description": "A list of files, folders and web links that matched the search query.", - "required": [ - "type" - ], + "type": "object", "allOf": [ { "type": "object", "properties": { "total_count": { "description": "One greater than the offset of the last entry in the search results.\nThe total number of entries in the collection may be less than\n`total_count`.", - "example": 5000, "type": "integer", - "format": "int64" + "format": "int64", + "example": 5000 }, "limit": { "description": "The limit that was used for this search. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed.", - "example": 1000, "type": "integer", - "format": "int64" + "format": "int64", + "example": 1000 }, "offset": { "description": "The 0-based offset of the first entry in this set. This will be the same\nas the `offset` query parameter used.", - "example": 2000, "type": "integer", - "format": "int64" + "format": "int64", + "example": 2000 } } }, @@ -33046,38 +32886,38 @@ } } } - ] - }, - "SearchResultsWithSharedLinks": { - "title": "Search Results (including Shared Links)", - "type": "object", - "x-box-resource-id": "search_results_with_shared_links", - "x-box-tag": "search", - "description": "A list of files, folders and web links that matched the search query,\nincluding the additional information about any shared links through\nwhich the item has been shared with the user.\n\nThis response format is only returned when the `include_recent_shared_links`\nquery parameter has been set to `true`.", + ], "required": [ "type" ], + "title": "Search Results", + "x-box-resource-id": "search_results", + "x-box-tag": "search" + }, + "SearchResultsWithSharedLinks": { + "description": "A list of files, folders and web links that matched the search query,\nincluding the additional information about any shared links through\nwhich the item has been shared with the user.\n\nThis response format is only returned when the `include_recent_shared_links`\nquery parameter has been set to `true`.", + "type": "object", "allOf": [ { "type": "object", "properties": { "total_count": { "description": "One greater than the offset of the last entry in the search results.\nThe total number of entries in the collection may be less than\n`total_count`.", - "example": 5000, "type": "integer", - "format": "int64" + "format": "int64", + "example": 5000 }, "limit": { "description": "The limit that was used for this search. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed.", - "example": 1000, "type": "integer", - "format": "int64" + "format": "int64", + "example": 1000 }, "offset": { "description": "The 0-based offset of the first entry in this set. This will be the same\nas the `offset` query parameter used.", - "example": 2000, "type": "integer", - "format": "int64" + "format": "int64", + "example": 2000 } } }, @@ -33101,160 +32941,275 @@ } } } - ] - }, - "SearchResultWithSharedLink": { - "title": "Search Result (including Shared Link)", - "type": "object", - "x-box-resource-id": "search_result_with_shared_link", - "x-box-tag": "search", - "description": "A single of files, folder or web link that matched the search query,\nincluding the additional information about the shared link through\nwhich the item has been shared with the user.\n\nThis response format is only returned when the\n`include_recent_shared_links` query parameter has been set to `true`.", - "properties": { - "accessible_via_shared_link": { - "description": "The optional shared link through which the user has access to this\nitem. This value is only returned for items for which the user has\nrecently accessed the file through a shared link. For all other\nitems this value will return `null`.", - "example": "https://www.box.com/s/vspke7y05sb214wjokpk", - "type": "string", - "format": "url" - }, - "item": { - "allOf": [ - { - "oneOf": [ - { - "$ref": "#/components/schemas/File--Full" - }, - { - "$ref": "#/components/schemas/Folder--Full" - }, - { - "$ref": "#/components/schemas/WebLink" - } - ] - }, - { - "description": "The file, folder or web link that matched the\nsearch query." - } - ] - }, - "type": { - "description": "The result type. The value is always `search_result`.", - "example": "search_result", - "type": "string" - } - } + ], + "required": [ + "type" + ], + "title": "Search Results (including Shared Links)", + "x-box-resource-id": "search_results_with_shared_links", + "x-box-tag": "search" }, "SessionTerminationMessage": { - "title": "Session termination message", - "type": "object", - "x-box-resource-id": "session_termination", - "x-box-tag": "session_termination", "description": "A message informing about the\ntermination job status", + "type": "object", "properties": { "message": { - "type": "string", "description": "The unique identifier for the termination job status", + "type": "string", "example": "Request is successful, please check the admin\nevents for the status of the job" } - } + }, + "title": "Session termination message", + "x-box-resource-id": "session_termination", + "x-box-tag": "session_termination" }, - "SkillCardsMetadata": { - "title": "Skills metadata instance", + "ShieldInformationBarrier": { + "description": "A standard representation of a\nshield information barrier object", "type": "object", - "x-box-resource-id": "skill_cards_metadata", - "x-box-tag": "skills", - "description": "The metadata assigned to a using for Box skills.", "properties": { - "$canEdit": { - "type": "boolean", - "example": true, - "description": "Whether the user can edit this metadata" - }, - "$id": { + "id": { + "description": "The unique identifier for the shield information barrier", "type": "string", - "format": "uuid", - "example": "01234500-12f1-1234-aa12-b1d234cb567e", - "maxLength": 36, - "description": "A UUID to identify the metadata object" + "example": "11446498" }, - "$parent": { + "type": { + "description": "The type of the shield information barrier", "type": "string", - "example": "folder_59449484661,", - "description": "An ID for the parent folder" + "example": "shield_information_barrier", + "enum": [ + "shield_information_barrier" + ] }, - "$scope": { + "enterprise": { + "description": "The `type` and `id` of enterprise this barrier is under.", + "allOf": [ + { + "$ref": "#/components/schemas/Enterprise--Base" + } + ] + }, + "status": { + "description": "Status of the shield information barrier", "type": "string", - "example": "enterprise_27335", - "description": "An ID for the scope in which this template\nhas been applied" + "example": "draft", + "enum": [ + "draft", + "pending", + "disabled", + "enabled", + "invalid" + ] }, - "$template": { + "created_at": { + "description": "ISO date time string when this\nshield information barrier object was created.", "type": "string", - "example": "properties", - "description": "The name of the template" + "format": "date-time", + "example": "2020-06-26T18:44:45.869Z" }, - "$type": { + "created_by": { + "description": "The user who created this shield information barrier.", + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + } + ] + }, + "updated_at": { + "description": "ISO date time string when this shield information barrier was updated.", "type": "string", - "example": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0", - "description": "A unique identifier for the \"type\" of this instance. This is an internal\nsystem property and should not be used by a client application." + "format": "date-time", + "example": "2020-07-26T18:44:45.869Z" }, - "$typeVersion": { - "type": "integer", - "example": 2, - "description": "The last-known version of the template of the object. This is an internal\nsystem property and should not be used by a client application." + "updated_by": { + "description": "The user that updated this shield information barrier.", + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + } + ] }, - "$version": { - "type": "integer", - "example": 1, - "description": "The version of the metadata object. Starts at 0 and increases every time\na user-defined property is modified." + "enabled_at": { + "description": "ISO date time string when this shield information barrier was enabled.", + "type": "string", + "format": "date-time", + "example": "2020-07-26T18:44:45.869Z" }, - "cards": { - "type": "array", - "description": "A list of Box Skill cards that have been applied to this file.", - "items": { - "oneOf": [ - { - "$ref": "#/components/schemas/KeywordSkillCard" - }, - { - "$ref": "#/components/schemas/TimelineSkillCard" - }, - { - "$ref": "#/components/schemas/TranscriptSkillCard" - }, - { - "$ref": "#/components/schemas/StatusSkillCard" - } - ] - } + "enabled_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "description": "The user that enabled this shield information barrier." + } + ] } - } + }, + "title": "Shield information barrier", + "x-box-resource-id": "shield_information_barrier", + "x-box-tag": "shield_information_barriers", + "x-box-variant": "standard", + "x-box-variants": [ + "base", + "standard" + ] }, - "StoragePolicy": { - "title": "Storage policy", + "ShieldInformationBarrier--Base": { + "description": "A base representation of a\nshield information barrier object", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for the shield information barrier", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "The type of the shield information barrier", + "type": "string", + "example": "shield_information_barrier", + "enum": [ + "shield_information_barrier" + ] + } + }, + "title": "Shield information barrier (Base)", + "x-box-resource-id": "shield_information_barrier--base", + "x-box-tag": "shield_information_barriers", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "standard" + ] + }, + "ShieldInformationBarrierReference": { + "description": "A shield information barrier reference for requests and responses", + "type": "object", + "properties": { + "shield_information_barrier": { + "$ref": "#/components/schemas/ShieldInformationBarrier--Base" + } + }, + "title": "Shield information barrier reference", + "x-box-resource-id": "shield_information_barrier_reference", + "x-box-tag": "shield_information_barrier_reports" + }, + "ShieldInformationBarrierReport": { + "description": "A standard representation\nof a shield information barrier report object", "type": "object", - "x-box-resource-id": "storage_policy", - "x-box-variant": "standard", - "description": "The Storage Policy object describes the storage zone.", "allOf": [ { - "$ref": "#/components/schemas/StoragePolicy--Mini" + "$ref": "#/components/schemas/ShieldInformationBarrierReport--Base" }, { "properties": { - "name": { - "description": "A descriptive name of the region", + "shield_information_barrier": { + "allOf": [ + { + "$ref": "#/components/schemas/ShieldInformationBarrierReference" + } + ] + }, + "status": { + "description": "Status of the shield information report", "type": "string", - "example": "Montreal / Dublin" + "example": "pending", + "enum": [ + "pending", + "error", + "done", + "cancelled" + ] + }, + "details": { + "allOf": [ + { + "$ref": "#/components/schemas/ShieldInformationBarrierReportDetails" + } + ] + }, + "created_at": { + "description": "ISO date time string when this\nshield information barrier report object was created.", + "type": "string", + "format": "date-time", + "example": "2020-06-26T18:44:45.869Z" + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "description": "The user who created this shield information barrier report." + } + ] + }, + "updated_at": { + "description": "ISO date time string when this\nshield information barrier report was updated.", + "type": "string", + "format": "date-time", + "example": "2020-07-26T18:44:45.869Z" } } } + ], + "title": "Shield information barrier report", + "x-box-resource-id": "shield_information_barrier_report", + "x-box-tag": "shield_information_barrier_reports", + "x-box-variant": "standard", + "x-box-variants": [ + "base", + "standard" ] }, - "StoragePolicies": { - "title": "Storage policies", + "ShieldInformationBarrierReport--Base": { + "description": "A base representation of a\nshield information barrier report object", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for the shield information barrier report", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "The type of the shield information barrier report", + "type": "string", + "example": "shield_information_barrier_report", + "enum": [ + "shield_information_barrier_report" + ] + } + }, + "title": "Shield information barrier report (Base)", + "x-box-resource-id": "shield_information_barrier_report--base", + "x-box-tag": "shield_information_barrier_reports", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "standard" + ] + }, + "ShieldInformationBarrierReportDetails": { + "description": "Indicates which folder the report\nfile is located and any errors when generating the report.", + "type": "object", + "properties": { + "details": { + "type": "object", + "properties": { + "folder_id": { + "description": "Folder ID for locating this report", + "type": "string", + "example": "124235" + } + } + } + }, + "title": "Shield information barrier report details", + "x-box-resource-id": "shield_information_barrier_report_details", + "x-box-tag": "shield_information_barrier_reports" + }, + "ShieldInformationBarrierReports": { + "description": "A list of shield barrier reports.", "type": "object", - "x-box-resource-id": "storage_policies", - "x-box-tag": "storage_policies", - "description": "A list of storage policies.", "allOf": [ { "type": "object", @@ -33262,20 +33217,14 @@ "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" + "format": "int64", + "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", - "type": "string", - "nullable": true - }, - "prev_marker": { - "description": "The marker for the start of the previous page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true } } @@ -33283,113 +33232,235 @@ { "properties": { "entries": { + "description": "A list of shield information\nbarrier reports.", "type": "array", - "description": "A list of storage policies", "items": { - "$ref": "#/components/schemas/StoragePolicy" + "$ref": "#/components/schemas/ShieldInformationBarrierReport" } } } } - ] + ], + "title": "List of Shield Information Barrier Reports", + "x-box-resource-id": "shield_information_barrier_reports", + "x-box-tag": "shield_information_barrier_reports" }, - "StoragePolicy--Mini": { - "title": "Storage policy (Mini)", + "ShieldInformationBarrierSegment": { + "description": "A shield information barrier segment object", "type": "object", - "x-box-resource-id": "storage_policy--mini", - "x-box-tag": "storage_policies", - "x-box-variants": [ - "standard", - "mini" - ], - "x-box-variant": "mini", - "description": "A mini description of a Storage Policy object", - "required": [ - "id", - "type" - ], "properties": { "id": { + "description": "The unique identifier for the shield information barrier segment", "type": "string", - "description": "The unique identifier for this storage policy", "example": "11446498" }, "type": { + "description": "The type of the shield information barrier segment", "type": "string", - "description": "`storage_policy`", - "example": "storage_policy", + "example": "shield_information_barrier_segment", "enum": [ - "storage_policy" + "shield_information_barrier_segment" ] - } - } - }, - "StoragePolicyAssignment": { - "title": "Storage policy assignment", - "type": "object", - "x-box-resource-id": "storage_policy_assignment", - "x-box-tag": "storage_policy_assignments", - "description": "The assignment of a storage policy to a user or enterprise", - "required": [ - "id", - "type" - ], - "properties": { - "id": { + }, + "shield_information_barrier": { + "$ref": "#/components/schemas/ShieldInformationBarrier--Base" + }, + "name": { + "description": "Name of the shield information barrier segment", "type": "string", - "description": "The unique identifier for a storage policy assignment.", - "example": "ZW50ZXJwcmlzZV8xMjM0NTY3ODkw" + "example": "Investment Banking" }, - "type": { + "description": { + "description": "Description of the shield information barrier segment", "type": "string", - "description": "`storage_policy_assignment`", - "example": "storage_policy_assignment", - "enum": [ - "storage_policy_assignment" - ] + "example": "'Corporate division that engages in advisory_based financial\n transactions on behalf of individuals, corporations, and governments.'" }, - "storage_policy": { + "created_at": { + "description": "ISO date time string when this shield information\nbarrier object was created.", + "type": "string", + "format": "date-time", + "example": "2020-06-26T18:44:45.869Z" + }, + "created_by": { "allOf": [ { - "$ref": "#/components/schemas/StoragePolicy--Mini" + "$ref": "#/components/schemas/User--Base" }, { - "description": "The assigned storage policy" + "description": "The user who created this shield information barrier segment." } ] }, - "assigned_to": { + "updated_at": { + "description": "ISO date time string when this\nshield information barrier segment was updated.", + "type": "string", + "format": "date-time", + "example": "2020-07-26T18:44:45.869Z" + }, + "updated_by": { "allOf": [ { - "title": "Reference", - "description": "The bare basic reference for an object", + "$ref": "#/components/schemas/User--Base" + }, + { + "description": "The user that updated this shield information barrier segment." + } + ] + } + }, + "title": "Shield information barrier segment", + "x-box-resource-id": "shield_information_barrier_segment", + "x-box-tag": "shield_information_barrier_segments" + }, + "ShieldInformationBarrierSegmentMember": { + "description": "A standard representation of a\nshield information barrier segment member object", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/ShieldInformationBarrierSegmentMember--Mini" + }, + { + "properties": { + "shield_information_barrier": { + "$ref": "#/components/schemas/ShieldInformationBarrier--Base" + }, + "shield_information_barrier_segment": { + "description": "The `type` and `id` of the requested\nshield information barrier segment.", "type": "object", "properties": { "id": { + "description": "The ID reference of the requesting\nshield information barrier segment.", "type": "string", - "description": "The unique identifier for this object", - "example": "11446498" + "example": "432554" }, "type": { + "description": "The type of the shield information barrier segment", "type": "string", - "description": "The type for this object", - "example": "file" + "example": "shield_information_barrier_segment", + "enum": [ + "shield_information_barrier_segment" + ] } } }, - { - "description": "The enterprise or use the policy is assigned to" + "user": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "description": "The `type` and `id` of the requested shield information barrier segment member." + } + ] + }, + "created_at": { + "description": "ISO date time string when this shield\ninformation barrier object was created.", + "type": "string", + "format": "date-time", + "example": "2020-06-26T18:44:45.869Z" + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "description": "The user who created this shield information barrier segment member." + } + ] + }, + "updated_at": { + "description": "ISO date time string when this\nshield information barrier segment Member was updated.", + "type": "string", + "format": "date-time", + "example": "2020-07-26T18:44:45.869Z" + }, + "updated_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "description": "The user that updated this shield information barrier segment Member." + } + ] } + } + } + ], + "title": "Shield information barrier segment member", + "x-box-resource-id": "shield_information_barrier_segment_member", + "x-box-tag": "shield_information_barrier_segment_members", + "x-box-variant": "standard", + "x-box-variants": [ + "base", + "mini", + "standard" + ] + }, + "ShieldInformationBarrierSegmentMember--Base": { + "description": "A base representation of a\nshield information barrier segment member object", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for the\nshield information barrier segment member", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "The type of the shield information barrier segment member", + "type": "string", + "example": "shield_information_barrier_segment_member", + "enum": [ + "shield_information_barrier_segment_member" ] } - } + }, + "title": "Shield information barrier segment member (Base)", + "x-box-resource-id": "shield_information_barrier_segment_member--base", + "x-box-tag": "shield_information_barrier_segment_members", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "mini", + "standard" + ] }, - "StoragePolicyAssignments": { - "title": "Storage policy assignments", + "ShieldInformationBarrierSegmentMember--Mini": { + "description": "A mini representation of a\nshield information barrier segment member object", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/ShieldInformationBarrierSegmentMember--Base" + }, + { + "properties": { + "user": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "description": "The `type` and `id` of the requested shield information barrier segment member." + } + ] + } + } + } + ], + "title": "Shield information barrier segment member (Mini)", + "x-box-resource-id": "shield_information_barrier_segment_member--mini", + "x-box-tag": "shield_information_barrier_segment_members", + "x-box-variant": "mini", + "x-box-variants": [ + "base", + "mini", + "standard" + ] + }, + "ShieldInformationBarrierSegmentMembers": { + "description": "List of Shield Information Barrier Member objects", "type": "object", - "x-box-resource-id": "storage_policy_assignments", - "x-box-tag": "storage_policy_assignments", - "description": "A list of storage policy assignments.", "allOf": [ { "type": "object", @@ -33397,20 +33468,14 @@ "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" + "format": "int64", + "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", - "type": "string", - "nullable": true - }, - "prev_marker": { - "description": "The marker for the start of the previous page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true } } @@ -33418,505 +33483,896 @@ { "properties": { "entries": { + "description": "A list of shield information\nbarrier segment members", "type": "array", - "description": "A list of storage policy assignments", "items": { - "$ref": "#/components/schemas/StoragePolicyAssignment" + "$ref": "#/components/schemas/ShieldInformationBarrierSegmentMember" } } } } - ] + ], + "title": "List of Shield Information Barrier Segment Members", + "x-box-resource-id": "shield_information_barrier_segment_members", + "x-box-tag": "shield_information_barrier_segment_members" }, - "Task": { - "title": "Task", + "ShieldInformationBarrierSegmentRestriction": { + "description": "A standard representation of a\nsegment restriction of a shield information barrier\nobject", "type": "object", - "x-box-resource-id": "task", - "x-box-tag": "tasks", - "description": "A task allows for file-centric workflows within Box. Users can\ncreate tasks on files and assign them to other users for them to complete the\ntasks.", - "properties": { - "id": { - "type": "string", - "description": "The unique identifier for this task", - "example": "11446498" - }, - "type": { - "type": "string", - "description": "`task`", - "example": "task", - "enum": [ - "task" - ] + "allOf": [ + { + "$ref": "#/components/schemas/ShieldInformationBarrierSegmentRestriction--Mini" }, - "item": { - "allOf": [ - { - "$ref": "#/components/schemas/File--Mini" + { + "properties": { + "shield_information_barrier": { + "$ref": "#/components/schemas/ShieldInformationBarrier--Base" }, - { - "description": "The file associated with the task" - } - ] - }, - "due_at": { - "type": "string", - "format": "date-time", - "description": "When the task is due", - "example": "2012-12-12T10:53:43-08:00" - }, - "action": { - "type": "string", - "example": "review", - "description": "The type of task the task assignee will be prompted to\nperform.", - "enum": [ - "review", - "complete" - ] - }, - "message": { - "type": "string", - "description": "A message that will be included with the task", - "example": "Legal review" - }, - "task_assignment_collection": { - "allOf": [ - { - "$ref": "#/components/schemas/TaskAssignments" + "created_at": { + "description": "ISO date time string when this\nshield information barrier\nSegment Restriction object was created.", + "type": "string", + "format": "date-time", + "example": "2020-06-26T18:44:45.869Z" }, - { - "description": "A collection of task assignment objects\nassociated with the task" - } - ] - }, - "is_completed": { - "type": "boolean", - "description": "Whether the task has been completed", - "example": true - }, - "created_by": { - "allOf": [ - { - "$ref": "#/components/schemas/User--Mini" + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "description": "The user who created this shield information barrier segment Restriction." + } + ] }, - { - "description": "The user who created the task" + "updated_at": { + "description": "ISO date time string when this\nshield information barrier segment\nRestriction was updated.", + "type": "string", + "format": "date-time", + "example": "2020-07-26T18:44:45.869Z" + }, + "updated_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "description": "The user that updated this shield information barrier segment Restriction." + } + ] } - ] - }, - "created_at": { - "type": "string", - "format": "date-time", - "description": "When the task object was created", - "example": "2012-12-12T10:53:43-08:00" - }, - "completion_rule": { + } + } + ], + "required": [ + "shield_information_barrier_segment", + "restricted_segment" + ], + "title": "Shield information barrier segment restriction", + "x-box-resource-id": "shield_information_barrier_segment_restriction", + "x-box-tag": "shield_information_barrier_segment_restrictions", + "x-box-variant": "standard", + "x-box-variants": [ + "base", + "mini", + "standard" + ] + }, + "ShieldInformationBarrierSegmentRestriction--Base": { + "description": "A base representation of\na segment restriction object for\nthe shield information barrier", + "type": "object", + "properties": { + "type": { + "description": "Shield information barrier segment restriction", "type": "string", - "description": "Defines which assignees need to complete this task before the task\nis considered completed.\n\n* `all_assignees` 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", + "example": "shield_information_barrier_segment_restriction", "enum": [ - "all_assignees", - "any_assignee" + "shield_information_barrier_segment_restriction" ] + }, + "id": { + "description": "The unique identifier for the\nshield information barrier segment restriction.", + "type": "string", + "example": "11446498" } - } + }, + "required": [ + "shield_information_barrier_segment", + "restricted_segment" + ], + "title": "Shield information barrier segment restriction (Base)", + "x-box-resource-id": "shield_information_barrier_segment_restriction--base", + "x-box-tag": "shield_information_barrier_segment_restrictions", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "mini", + "standard" + ] }, - "Tasks": { - "title": "Tasks", + "ShieldInformationBarrierSegmentRestriction--Mini": { + "description": "A mini representation of\na segment restriction object for\nthe shield information barrier", "type": "object", - "x-box-resource-id": "tasks", - "x-box-tag": "tasks", - "description": "A list of tasks", - "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`.", - "example": 5000, - "type": "integer", - "format": "int64" + "allOf": [ + { + "$ref": "#/components/schemas/ShieldInformationBarrierSegmentRestriction--Base" }, - "entries": { - "type": "array", - "description": "A list of tasks", - "items": { - "$ref": "#/components/schemas/Task" + { + "properties": { + "shield_information_barrier_segment": { + "description": "The `type` and `id` of the\nrequested shield information barrier segment.", + "type": "object", + "properties": { + "id": { + "description": "The ID reference of the\nrequesting shield information barrier segment.", + "type": "string", + "example": "1910967" + }, + "type": { + "description": "The type of the shield information barrier segment", + "type": "string", + "example": "shield_information_barrier_segment", + "enum": [ + "shield_information_barrier_segment" + ] + } + } + }, + "restricted_segment": { + "description": "The `type` and `id` of the\nrestricted shield information barrier segment.", + "type": "object", + "properties": { + "id": { + "description": "The ID reference of the\nrestricted shield information barrier segment.", + "type": "string", + "example": "1910967" + }, + "type": { + "description": "The type of the shield information segment", + "type": "string", + "example": "shield_information_barrier_segment", + "enum": [ + "shield_information_barrier_segment" + ] + } + } + } } } - } + ], + "required": [ + "shield_information_barrier_segment", + "restricted_segment" + ], + "title": "Shield information barrier segment restriction (Mini)", + "x-box-resource-id": "shield_information_barrier_segment_restriction--mini", + "x-box-tag": "shield_information_barrier_segment_restrictions", + "x-box-variant": "mini", + "x-box-variants": [ + "base", + "mini", + "standard" + ] }, - "TaskAssignment": { - "title": "Task assignment", + "ShieldInformationBarrierSegmentRestrictions": { + "description": "List of shield information barrier segment restriction objects", "type": "object", - "x-box-resource-id": "task_assignment", - "x-box-tag": "task_assignments", - "description": "A task assignment defines which task is assigned to which user to complete.", - "properties": { - "id": { - "type": "string", - "description": "The unique identifier for this task assignment", - "example": "11446498" - }, - "type": { - "type": "string", - "description": "`task_assignment`", - "example": "task_assignment", - "enum": [ - "task_assignment" - ] - }, - "item": { - "allOf": [ - { - "$ref": "#/components/schemas/File--Mini" + "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.", + "type": "integer", + "format": "int64", + "example": 1000 }, - { - "description": "The file that the task has been assigned to." + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true } - ] + } }, - "assigned_to": { - "allOf": [ - { - "$ref": "#/components/schemas/User--Mini" + { + "properties": { + "entries": { + "description": "A list of shield information barrier\nsegment restriction objects", + "type": "array", + "items": { + "$ref": "#/components/schemas/ShieldInformationBarrierSegmentRestriction" + } + } + } + } + ], + "title": "List of Shield Information Barrier Segment Restrictions", + "x-box-resource-id": "shield_information_barrier_segment_restrictions", + "x-box-tag": "shield_information_barrier_segment_restrictions" + }, + "ShieldInformationBarrierSegments": { + "description": "List of Shield Information Barrier Segment objects", + "type": "object", + "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.", + "type": "integer", + "format": "int64", + "example": 1000 }, - { - "description": "The user that the task has been assigned to." + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true } - ] - }, - "message": { - "type": "string", - "example": "Please review", - "description": "A message that will is included with the task\nassignment. This is visible to the assigned user in the web and mobile\nUI." - }, - "completed_at": { - "type": "string", - "format": "date-time", - "description": "The date at which this task assignment was\ncompleted. This will be `null` if the task is not completed yet.", - "example": "2012-12-12T10:53:43-08:00" - }, - "assigned_at": { - "type": "string", - "format": "date-time", - "description": "The date at which this task was assigned to the user.", - "example": "2012-12-12T10:53:43-08:00" - }, - "reminded_at": { - "type": "string", - "format": "date-time", - "description": "The date at which the assigned user was reminded of this task\nassignment.", - "example": "2012-12-12T10:53:43-08:00" - }, - "resolution_state": { - "type": "string", - "description": "The current state of the assignment. The available states depend on\nthe `action` value of the task object.", - "example": "incomplete", - "enum": [ - "completed", - "incomplete", - "approved", - "rejected" - ] + } }, - "assigned_by": { - "allOf": [ - { - "$ref": "#/components/schemas/User--Mini" - }, - { - "description": "The user who assigned this task." + { + "properties": { + "entries": { + "description": "A list of shield information barrier\nsegments", + "type": "array", + "items": { + "$ref": "#/components/schemas/ShieldInformationBarrierSegment" + } } - ] + } } - } + ], + "title": "List of Shield Information Barrier Segments", + "x-box-resource-id": "shield_information_barrier_segments", + "x-box-tag": "shield_information_barrier_segments" }, - "TaskAssignments": { - "title": "Task assignments", + "ShieldInformationBarriers": { + "description": "List of Shield Information Barrier objects", "type": "object", - "x-box-resource-id": "task_assignments", - "x-box-tag": "task_assignments", - "description": "A list of task assignments", - "properties": { - "total_count": { - "description": "The total number of items in this collection.", - "example": 100, - "type": "integer", - "format": "int64" + "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.", + "type": "integer", + "format": "int64", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + } + } }, - "entries": { - "type": "array", - "description": "A list of task assignments", - "items": { - "$ref": "#/components/schemas/TaskAssignment" + { + "properties": { + "entries": { + "description": "A list of shield information barrier objects", + "type": "array", + "items": { + "$ref": "#/components/schemas/ShieldInformationBarrier" + } + } } } - } + ], + "title": "List of Shield Information Barriers", + "x-box-resource-id": "shield_information_barriers", + "x-box-tag": "shield_information_barriers" }, - "TermsOfService": { - "title": "Terms of service", + "SignRequest": { + "description": "A Box Sign request object.", "type": "object", - "x-box-resource-id": "terms_of_service", - "x-box-variant": "standard", - "description": "The root-level record that is supposed to represent a\nsingle Terms of Service.", "allOf": [ { - "$ref": "#/components/schemas/TermsOfService--Base" + "$ref": "#/components/schemas/SignRequest--Base" }, { "properties": { - "status": { - "description": "Whether these terms are enabled or not", + "type": { + "description": "object type", "type": "string", - "example": "enabled", + "example": "sign-request", "enum": [ - "enabled", - "disabled" + "sign-request" ] }, - "enterprise": { + "source_files": { + "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.", + "type": "array", + "items": { + "$ref": "#/components/schemas/File--Base" + } + }, + "signers": { + "description": "Array of signers for the signature request.", + "type": "array", + "items": { + "$ref": "#/components/schemas/SignRequestSigner" + } + }, + "signature_color": { + "description": "Force a specific color for the signature (blue, black, or red).", + "type": "string", + "example": "blue", + "nullable": true + }, + "id": { + "description": "Box Sign request ID.", + "type": "string", + "example": "12345" + }, + "prepare_url": { + "description": "This URL is returned if `is_document_preparation_needed` is\nset to `true` in the request. The parameter is used to prepare\nthe signature request\nusing the UI. The signature request is not\nsent until the preparation\nphase is complete.", + "type": "string", + "example": "https://prepareurl.com", + "nullable": true + }, + "signing_log": { "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" - } - } + "$ref": "#/components/schemas/File--Mini" }, { - "description": "The enterprise these terms apply to" + "description": "Reference to a file that holds a log of all signer activity for\nthe request." } ] }, - "tos_type": { - "description": "Whether to apply these terms to managed users or external users", + "status": { + "description": "Describes the status of the signature request.", "type": "string", - "example": "managed", + "example": "converting", "enum": [ - "managed", - "external" + "converting", + "created", + "sent", + "viewed", + "signed", + "cancelled", + "declined", + "error_converting", + "error_sending", + "expired", + "finalizing", + "error_finalizing" ] }, - "text": { - "description": "The text for your terms and conditions. This text could be\nempty if the `status` is set to `disabled`.", - "type": "string", - "example": "By using this service, you agree to ..." + "sign_files": { + "description": "List of files that will be signed, which are copies of the original\nsource files. A new version of these files are created as signers sign\nand can be downloaded at any point in the signing process.", + "type": "object", + "properties": { + "files": { + "type": "array", + "items": { + "$ref": "#/components/schemas/File--Mini" + } + }, + "is_ready_for_download": { + "description": "Indicates whether the `sign_files` documents are processing\nand the PDFs may be out of date. A change to any document\nrequires processing on all `sign_files`. We\nrecommended waiting until processing is finished\n(and this value is true) before downloading the PDFs.", + "type": "boolean", + "example": true + } + } }, - "created_at": { + "auto_expire_at": { + "description": "Uses `days_valid` to calculate the date and time, in GMT, the sign request will expire if unsigned.", "type": "string", "format": "date-time", - "description": "When the legal item was created", - "example": "2012-12-12T10:53:43-08:00" + "example": "2021-04-26T08:12:13.982Z", + "nullable": true }, - "modified_at": { - "type": "string", - "format": "date-time", - "description": "When the legal item was modified.", - "example": "2012-12-12T10:53:43-08:00" - } - } - } - ] - }, - "TermsOfServices": { - "title": "Terms of services", - "type": "object", - "x-box-resource-id": "terms_of_services", - "x-box-tag": "terms_of_services", - "description": "A list of terms of services", + "parent_folder": { + "allOf": [ + { + "$ref": "#/components/schemas/Folder--Mini" + }, + { + "description": "The destination folder to place final, signed document and signing\nlog.\n\nWhen this value was not passed in when the signature request was \ncreated, then we will use a default folder which is either the parent\nfolder of the first source file in the payload if we have the permission\nto upload to that folder or a folder called \"My Sign Requests\"." + } + ], + "nullable": false + } + } + } + ], + "title": "Box Sign request", + "x-box-resource-id": "sign_request", + "x-box-tag": "sign_requests", + "x-box-variant": "standard", + "x-box-variants": [ + "standard", + "base" + ] + }, + "SignRequest--Base": { + "description": "A standard representation of a signature request object.", + "type": "object", "properties": { - "total_count": { - "description": "The total number of objects.", - "example": 2, - "type": "integer", - "format": "int64" + "is_document_preparation_needed": { + "description": "Indicates if the sender should receive a `prepare_url` in the response to complete document preparation using the UI.", + "type": "boolean", + "example": true }, - "entries": { + "redirect_url": { + "description": "When specified, the signature request will be redirected to this url when a document is signed.", + "type": "string", + "example": "https://www.example.com", + "nullable": true + }, + "declined_redirect_url": { + "description": "The uri that a signer will be redirected to after declining to sign a document.", + "type": "string", + "example": "https://declined-redirect.com", + "nullable": true + }, + "are_text_signatures_enabled": { + "description": "Disables the usage of signatures generated by typing (text).", + "type": "boolean", + "example": true, + "default": true + }, + "email_subject": { + "description": "Subject of sign request email. This is cleaned by sign request. If this field is not passed, a default subject will be used.", + "type": "string", + "example": "Sign Request from Acme", + "nullable": true + }, + "email_message": { + "description": "Message to include in sign request email. The field is cleaned through sanitization of specific characters. However, some html tags are allowed. Links included in the message are also converted to hyperlinks in the email. The message may contain the following html tags including `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. If this field is not passed, a default message will be used.", + "type": "string", + "example": "Hello! Please sign the document below", + "nullable": true + }, + "are_reminders_enabled": { + "description": "Reminds signers to sign a document on day 3, 8, 13 and 18. Reminders are only sent to outstanding signers.", + "type": "boolean", + "example": true + }, + "name": { + "description": "Name of the signature request.", + "type": "string", + "example": "name" + }, + "prefill_tags": { + "description": "When a document contains sign-related tags in the content, you can prefill them using this `prefill_tags` by referencing the 'id' of the tag as the `external_id` field of the prefill tag.", "type": "array", - "description": "A list of terms of service objects", "items": { - "$ref": "#/components/schemas/TermsOfService" + "$ref": "#/components/schemas/SignRequestPrefillTag" } + }, + "days_valid": { + "description": "Set the number of days after which the created signature request will automatically expire if not completed. By default, we do not apply any expiration date on signature requests, and the signature request does not expire.", + "type": "integer", + "example": 2, + "maximum": 730, + "minimum": 0, + "nullable": true + }, + "external_id": { + "description": "This can be used to reference an ID in an external system that the sign request is related to.", + "type": "string", + "example": "123", + "nullable": true + }, + "is_phone_verification_required_to_view": { + "description": "Forces signers to verify a text message prior to viewing the document. You must specify the phone number of signers to have this setting apply to them.", + "type": "boolean", + "example": true, + "nullable": true + }, + "template_id": { + "description": "When a signature request is created from a template this field will indicate the id of that template.", + "type": "string", + "example": "123075213-af2c8822-3ef2-4952-8557-52d69c2fe9cb", + "nullable": true + }, + "external_system_name": { + "description": "Used as an optional system name to appear in the signature log next to the signers who have been assigned the `embed_url_external_id`.", + "type": "string", + "example": "Box", + "nullable": true } - } + }, + "title": "Box Sign request (Base)", + "x-box-resource-id": "sign_request--base", + "x-box-tag": "sign_requests", + "x-box-variant": "base", + "x-box-variants": [ + "standard", + "base" + ] }, - "TermsOfService--Base": { - "title": "Terms of service (Base)", + "SignRequestCreateRequest": { + "description": "Creates a Box Sign request object.", "type": "object", - "x-box-resource-id": "terms_of_service--base", - "x-box-tag": "terms_of_services", - "x-box-variants": [ - "base", - "standard" + "allOf": [ + { + "$ref": "#/components/schemas/SignRequest--Base" + }, + { + "properties": { + "source_files": { + "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.", + "type": "array", + "items": { + "$ref": "#/components/schemas/File--Base" + }, + "maxItems": 10, + "nullable": true + }, + "signature_color": { + "description": "Force a specific color for the signature (blue, black, or red)", + "type": "string", + "example": "blue", + "enum": [ + "blue", + "black", + "red" + ], + "nullable": true + }, + "signers": { + "description": "Array of signers for the signature request. 35 is the\nmax number of signers permitted.\n\n**Note**: It may happen that some signers belong to conflicting [segments](r://shield-information-barrier-segment-member) (user groups).\nThis means that due to the security policies, users are assigned to segments to prevent exchanges or communication that could lead to ethical conflicts.\nIn such a case, an attempt to send the sign request will result in an error.\n\nRead more about [segments and ethical walls](https://support.box.com/hc/en-us/articles/9920431507603-Understanding-Information-Barriers#h_01GFVJEHQA06N7XEZ4GCZ9GFAQ).", + "type": "array", + "items": { + "$ref": "#/components/schemas/SignRequestCreateSigner" + } + }, + "parent_folder": { + "allOf": [ + { + "$ref": "#/components/schemas/Folder--Mini" + }, + { + "description": "The destination folder to place final, signed document and signing\nlog. Only `ID` and `type` fields are required. The root folder,\nfolder ID `0`, cannot be used and can also not be null.\n\nWhen this value is not passed in when the signature request, then\nwe will use a default folder which is either the parent folder of\nthe first source file in the payload if we have the permission to\nupload to that folder or a folder called \"My Sign Requests\"." + } + ] + } + } + } ], - "x-box-variant": "base", - "description": "The root-level record that is supposed to represent a\nsingle Terms of Service.", "required": [ - "id", - "type" + "signers" ], + "title": "Create a Box Sign request" + }, + "SignRequestCreateSigner": { + "description": "The schema for a Signer object used in\nfor creating a Box Sign request object.", + "type": "object", "properties": { - "id": { + "email": { + "description": "Email address of the signer.\nThe email address of the signer is required when making signature requests, except when using templates that are configured to include emails.", "type": "string", - "description": "The unique identifier for this terms of service.", - "example": "11446498" + "example": "example@gmail.com", + "nullable": true }, - "type": { + "role": { + "description": "Defines the role of the signer in the signature request. A `signer`\nmust sign the document and an `approver` must approve the document. A\n`final_copy_reader` only receives the final signed document and signing\nlog.", "type": "string", - "description": "`terms_of_service`", - "example": "terms_of_service", + "example": "signer", + "default": "signer", "enum": [ - "terms_of_service" + "signer", + "approver", + "final_copy_reader" ] + }, + "is_in_person": { + "description": "Used in combination with an embed URL for a sender. After the\nsender signs, they are redirected to the next `in_person` signer.", + "type": "boolean", + "example": true + }, + "order": { + "description": "Order of the signer", + "type": "integer", + "example": 2, + "minimum": 0 + }, + "embed_url_external_user_id": { + "description": "User ID for the signer in an external application responsible\nfor authentication when accessing the embed URL.", + "type": "string", + "example": "1234", + "nullable": true + }, + "redirect_url": { + "description": "The URL that a signer will be redirected\nto after signing a document. Defining this URL\noverrides default or global redirect URL\nsettings for a specific signer.\nIf no declined redirect URL is specified,\nthis URL will be used for decline actions as well.", + "type": "string", + "example": "https://example.com", + "nullable": true + }, + "declined_redirect_url": { + "description": "The URL that a signer will be redirect\nto after declining to sign a document.\nDefining this URL overrides default or global\ndeclined redirect URL settings for a specific signer.", + "type": "string", + "example": "https://declined-example.com", + "nullable": true + }, + "login_required": { + "description": "If set to true, the signer will need to log in to a Box account\nbefore signing the request. If the signer does not have\nan existing account, they will have the option to create\na free Box account. Cannot be selected in combination with\n`verification_phone_number`.", + "type": "boolean", + "example": true, + "nullable": true + }, + "verification_phone_number": { + "description": "If set, this phone number will be used to verify the signer\nvia two-factor authentication before they are able to sign the document.\nCannot be selected in combination with `login_required`.", + "type": "string", + "example": "6314578901", + "nullable": true + }, + "password": { + "description": "If set, the signer is required to enter the password before they are able\nto sign a document. This field is write only.", + "type": "string", + "example": "SecretPassword123", + "nullable": true, + "writeOnly": true + }, + "signer_group_id": { + "description": "If set, signers who have the same value will be assigned to the same input and to the same signer group.\nA signer group is not a Box Group. It is an entity that belongs to a Sign Request and can only be\nused/accessed within this Sign Request. A signer group is expected to have more than one signer.\nIf the provided value is only used for one signer, this value will be ignored and request will be handled\nas it was intended for an individual signer. The value provided can be any string and only used to\ndetermine which signers belongs to same group. A successful response will provide a generated UUID value\ninstead for signers in the same signer group.", + "type": "string", + "example": "cd4ff89-8fc1-42cf-8b29-1890dedd26d7", + "nullable": true + }, + "suppress_notifications": { + "description": "If true, no emails about the sign request will be sent", + "type": "boolean", + "example": false, + "nullable": true } - } + }, + "title": "Signer fields used to create a Box Sign request object." }, - "TermsOfServiceUserStatus": { - "title": "Terms of service user status", + "SignRequestPrefillTag": { + "description": "Prefill tags are used to prefill placeholders with signer input data. Only\none value field can be included.", "type": "object", - "x-box-resource-id": "terms_of_service_user_status", - "x-box-tag": "terms_of_service_user_statuses", - "description": "The association between a Terms of Service and a user", - "required": [ - "id", - "type" - ], "properties": { - "id": { + "document_tag_id": { + "description": "This references the ID of a specific tag contained in a file of the signature request.", "type": "string", - "description": "The unique identifier for this terms of service user status", - "example": "11446498" + "example": "1234", + "nullable": true }, - "type": { + "text_value": { + "description": "Text prefill value", "type": "string", - "description": "`terms_of_service_user_status`", - "example": "terms_of_service_user_status", - "enum": [ - "terms_of_service_user_status" - ] - }, - "tos": { - "allOf": [ - { - "$ref": "#/components/schemas/TermsOfService--Base" - }, - { - "description": "The terms of service" - } - ] - }, - "user": { - "allOf": [ - { - "$ref": "#/components/schemas/User--Mini" - }, - { - "description": "The user" - } - ] + "example": "text", + "nullable": true }, - "is_accepted": { + "checkbox_value": { + "description": "Checkbox prefill value", "type": "boolean", "example": true, - "description": "If the user has accepted the terms of services" + "nullable": true }, - "created_at": { + "date_value": { + "description": "Date prefill value", "type": "string", - "format": "date-time", - "description": "When the legal item was created", - "example": "2012-12-12T10:53:43-08:00" + "format": "date", + "example": "2021-04-26", + "nullable": true + } + }, + "title": "Sign request prefill tag" + }, + "SignRequestSigner": { + "description": "The schema for a Signer object used\non the body of a Box Sign request object.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/SignRequestCreateSigner" }, - "modified_at": { - "type": "string", - "format": "date-time", - "description": "When the legal item was modified.", - "example": "2012-12-12T10:53:43-08:00" + { + "properties": { + "has_viewed_document": { + "description": "Set to `true` if the signer views the document", + "type": "boolean", + "example": true, + "readOnly": true + }, + "signer_decision": { + "description": "Final decision made by the signer.", + "type": "object", + "nullable": true, + "properties": { + "type": { + "description": "Type of decision made by the signer.", + "type": "string", + "example": "signed", + "enum": [ + "signed", + "declined" + ] + }, + "finalized_at": { + "description": "Date and Time that the decision was made.", + "type": "string", + "format": "date-time", + "example": "2021-04-26T08:12:13.982Z" + }, + "additional_info": { + "description": "Additional info about the decision, such as the decline reason from the signer.", + "type": "string", + "example": "Requesting changes before signing.", + "nullable": true + } + } + }, + "inputs": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SignRequestSignerInput" + }, + "readOnly": true + }, + "embed_url": { + "description": "URL to direct a signer to for signing", + "type": "string", + "example": "https://example.com", + "nullable": true, + "readOnly": true + }, + "iframeable_embed_url": { + "description": "This URL is specifically designed for\nsigning documents within an HTML `iframe` tag.\nIt will be returned in the response\nonly if the `embed_url_external_user_id`\nparameter was passed in the\n`create Box Sign request` call.", + "type": "string", + "example": "https://app.box.com/embed/sign/document/gfhr4222-a331-494b-808b-79bc7f3992a3/f14d7098-a331-494b-808b-79bc7f3992a4", + "nullable": true + } + } } - } + ], + "required": [ + "email" + ], + "title": "Signer fields for Box Sign request response" }, - "TermsOfServiceUserStatuses": { - "title": "Terms of service user statuses", + "SignRequestSignerInput": { + "description": "Input created by a Signer on a Sign Request", "type": "object", - "x-box-resource-id": "terms_of_services_user_statuses", - "x-box-tag": "terms_of_service_user_statuses", - "description": "A list of terms of service user statuses", - "properties": { - "total_count": { - "description": "The total number of objects.", - "example": 2, - "type": "integer", - "format": "int64" + "allOf": [ + { + "$ref": "#/components/schemas/SignRequestPrefillTag" }, - "entries": { - "type": "array", - "description": "A list of terms of service user statuses", - "items": { - "$ref": "#/components/schemas/TermsOfServiceUserStatus" + { + "properties": { + "type": { + "description": "Type of input", + "type": "string", + "example": "text", + "enum": [ + "signature", + "date", + "text", + "checkbox", + "radio", + "dropdown" + ] + }, + "content_type": { + "description": "Content type of input", + "type": "string", + "example": "signature", + "enum": [ + "signature", + "initial", + "stamp", + "date", + "checkbox", + "text", + "full_name", + "first_name", + "last_name", + "company", + "title", + "email", + "attachment", + "radio", + "dropdown" + ] + }, + "page_index": { + "description": "Index of page that the input is on", + "type": "integer", + "example": 4 + }, + "read_only": { + "description": "Whether this input was defined as read-only(immutable by signers) or not", + "type": "boolean", + "example": true + } } } - } + ], + "required": [ + "page_index" + ], + "title": "Sign Request Signer Input" }, - "SignTemplate": { - "title": "Box Sign template", + "SignRequests": { + "description": "A standard representation of a signature request, as returned from any Box Sign\nAPI endpoints by default.", "type": "object", - "x-box-resource-id": "sign_template", - "x-box-tag": "sign_templates", + "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.", + "type": "integer", + "format": "int64", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "description": "A list of Box Sign requests.", + "type": "array", + "items": { + "$ref": "#/components/schemas/SignRequest" + } + } + } + } + ], + "title": "Box Sign requests", + "x-box-resource-id": "sign_requests", + "x-box-tag": "sign_requests" + }, + "SignTemplate": { "description": "A Box Sign template object", + "type": "object", "allOf": [ { "properties": { "type": { + "description": "object type", "type": "string", "example": "sign-template", "enum": [ "sign-template" - ], - "description": "object type" + ] }, "id": { + "description": "Template identifier.", "type": "string", - "example": "4206996024-14944f75-c34b-478a-95a1-264b1ff80d35", - "description": "Template identifier." + "example": "4206996024-14944f75-c34b-478a-95a1-264b1ff80d35" }, "name": { + "description": "The name of the template.", "type": "string", - "nullable": true, "example": "Official contract", - "description": "The name of the template." + "nullable": true }, "email_subject": { + "description": "Subject of signature request email. This is cleaned by sign request. If this field is not passed, a default subject will be used.", "type": "string", "example": "Sign Request from Acme", - "description": "Subject of signature request email. This is cleaned by sign request. If this field is not passed, a default subject will be used.", "nullable": true }, "email_message": { + "description": "Message to include in signature request email. The field is cleaned through sanitization of specific characters. However, some html tags are allowed. Links included in the message are also converted to hyperlinks in the email. The message may contain the following html tags including `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. If this field is not passed, a default message will be used.", "type": "string", "example": "Hello! Please sign the document below", - "description": "Message to include in signature request email. The field is cleaned through sanitization of specific characters. However, some html tags are allowed. Links included in the message are also converted to hyperlinks in the email. The message may contain the following html tags including `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. If this field is not passed, a default message will be used.", "nullable": true }, "days_valid": { - "type": "integer", "description": "Set the number of days after which the created signature request will automatically expire if not completed. By default, we do not apply any expiration date on signature requests, and the signature request does not expire.", - "minimum": 0, - "maximum": 730, + "type": "integer", "example": 2, + "maximum": 730, + "minimum": 0, "nullable": true }, "parent_folder": { @@ -33930,51 +34386,51 @@ ] }, "source_files": { + "description": "List of files to create a signing document from. Only the ID and type fields are required for each file.", "type": "array", "items": { "$ref": "#/components/schemas/File--Mini" - }, - "description": "List of files to create a signing document from. Only the ID and type fields are required for each file." + } }, "are_fields_locked": { - "type": "boolean", "description": "Indicates if the template input fields are editable or not.", + "type": "boolean", "example": false }, "are_options_locked": { - "type": "boolean", "description": "Indicates if the template document options are editable or not, for example renaming the document.", + "type": "boolean", "example": true }, "are_recipients_locked": { - "type": "boolean", "description": "Indicates if the template signers are editable or not.", + "type": "boolean", "example": false }, "are_email_settings_locked": { - "type": "boolean", "description": "Indicates if the template email settings are editable or not.", + "type": "boolean", "example": true }, "are_files_locked": { - "type": "boolean", "description": "Indicates if the template files are editable or not. This includes deleting or renaming template files.", + "type": "boolean", "example": true }, "signers": { + "description": "Array of signers for the template.\n\n**Note**: It may happen that some signers specified in the template belong to conflicting [segments](r://shield-information-barrier-segment-member) (user groups).\nThis means that due to the security policies, users are assigned to segments to prevent exchanges or communication that could lead to ethical conflicts.\nIn such a case, an attempt to send a sign request based on a template that lists signers in conflicting segments will result in an error.\n\nRead more about [segments and ethical walls](https://support.box.com/hc/en-us/articles/9920431507603-Understanding-Information-Barriers#h_01GFVJEHQA06N7XEZ4GCZ9GFAQ).", "type": "array", "items": { "$ref": "#/components/schemas/TemplateSigner" - }, - "description": "Array of signers for the template.\n\n**Note**: It may happen that some signers specified in the template belong to conflicting [segments](r://shield-information-barrier-segment-member) (user groups).\nThis means that due to the security policies, users are assigned to segments to prevent exchanges or communication that could lead to ethical conflicts.\nIn such a case, an attempt to send a sign request based on a template that lists signers in conflicting segments will result in an error.\n\nRead more about [segments and ethical walls](https://support.box.com/hc/en-us/articles/9920431507603-Understanding-Information-Barriers#h_01GFVJEHQA06N7XEZ4GCZ9GFAQ)." + } }, "additional_info": { "description": "Additional information on which fields are required and which fields are not editable.", "type": "object", "properties": { "non_editable": { - "type": "array", "description": "Non editable fields.", + "type": "array", "items": { "type": "string", "enum": [ @@ -33992,19 +34448,11 @@ ] }, "required": { - "type": "object", "description": "Required fields.", + "type": "object", "properties": { "signers": { "description": "Required signer fields.", - "example": [ - [ - "email" - ], - [ - "email" - ] - ], "type": "array", "items": { "type": "array", @@ -34017,93 +34465,101 @@ "example": [ "email" ] - } + }, + "example": [ + [ + "email" + ], + [ + "email" + ] + ] } } } } }, "ready_sign_link": { - "nullable": true, "description": "Box's ready-sign link feature enables you to create a link to a signature request that you've created from a template. Use this link when you want to post a signature request on a public form — such as an email, social media post, or web page — without knowing who the signers will be. Note: The ready-sign link feature is limited to Enterprise Plus customers and not available to Box Verified Enterprises.", "type": "object", + "nullable": true, "properties": { "url": { - "type": "string", "description": "The URL that can be sent to signers.", + "type": "string", "example": "\"https://app.box.com/sign/\nready-sign-link/a1cdf2c7-fa81-4a67-8163-1e5f4dbe5178\"" }, "name": { - "type": "string", - "nullable": true, "description": "Request name.", - "example": "Official contract" + "type": "string", + "example": "Official contract", + "nullable": true }, "instructions": { - "type": "string", - "nullable": true, "description": "Extra instructions for all signers.", - "example": "Hello! Please sign the document below" + "type": "string", + "example": "Hello! Please sign the document below", + "nullable": true }, "folder_id": { + "description": "The destination folder to place final,\nsigned document and signing\nlog. Only `ID` and `type` fields are required.\nThe root folder,\nfolder ID `0`, cannot be used.", "type": "string", - "nullable": true, "example": "12345", - "description": "The destination folder to place final,\nsigned document and signing\nlog. Only `ID` and `type` fields are required.\nThe root folder,\nfolder ID `0`, cannot be used." + "nullable": true }, "is_notification_disabled": { - "type": "boolean", "description": "Whether to disable notifications when\na signer has signed.", + "type": "boolean", "example": true }, "is_active": { - "type": "boolean", "description": "Whether the ready sign link is enabled or not.", + "type": "boolean", "example": false } } }, "custom_branding": { - "nullable": true, - "type": "object", "description": "Custom branding applied to notifications\nand signature requests.", + "type": "object", + "nullable": true, "properties": { "company_name": { "description": "Name of the company", "type": "string", - "nullable": true, - "example": "Corporation inc." + "example": "Corporation inc.", + "nullable": true }, "logo_uri": { - "type": "string", - "nullable": true, "description": "Custom branding logo URI in the form of a base64 image.", - "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA\nAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A\n8AAQUBAScY42YAAAAASUVORK5CYII=" + "type": "string", + "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA\nAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A\n8AAQUBAScY42YAAAAASUVORK5CYII=", + "nullable": true }, "branding_color": { + "description": "Custom branding color in hex.", "type": "string", - "nullable": true, "example": "9E5E6F", - "description": "Custom branding color in hex." + "nullable": true }, "email_footer_text": { + "description": "Content of the email footer.", "type": "string", - "nullable": true, "example": "Contact email email@mail.com", - "description": "Content of the email footer." + "nullable": true } } } } } - ] + ], + "title": "Box Sign template", + "x-box-resource-id": "sign_template", + "x-box-tag": "sign_templates" }, "SignTemplates": { - "title": "Box Sign templates", - "type": "object", - "x-box-resource-id": "sign_templates", - "x-box-tag": "sign_templates", "description": "A list of templates, as returned from any Box Sign\nAPI endpoints by default.", + "type": "object", "allOf": [ { "type": "object", @@ -34111,20 +34567,20 @@ "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" + "format": "int64", + "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } @@ -34132,641 +34588,710 @@ { "properties": { "entries": { - "type": "array", "description": "A list of templates.", + "type": "array", "items": { "$ref": "#/components/schemas/SignTemplate" } } } } - ] + ], + "title": "Box Sign templates", + "x-box-resource-id": "sign_templates", + "x-box-tag": "sign_templates" }, - "TemplateSigner": { - "title": "Signer fields for Templates", + "SkillCardsMetadata": { + "description": "The metadata assigned to a using for Box skills.", "type": "object", - "description": "The schema for a Signer for Templates", - "allOf": [ - { - "properties": { - "inputs": { - "type": "array", - "items": { - "$ref": "#/components/schemas/TemplateSignerInput" + "properties": { + "$canEdit": { + "description": "Whether the user can edit this metadata", + "type": "boolean", + "example": true + }, + "$id": { + "description": "A UUID to identify the metadata object", + "type": "string", + "format": "uuid", + "example": "01234500-12f1-1234-aa12-b1d234cb567e", + "maxLength": 36 + }, + "$parent": { + "description": "An ID for the parent folder", + "type": "string", + "example": "folder_59449484661," + }, + "$scope": { + "description": "An ID for the scope in which this template\nhas been applied", + "type": "string", + "example": "enterprise_27335" + }, + "$template": { + "description": "The name of the template", + "type": "string", + "example": "properties" + }, + "$type": { + "description": "A unique identifier for the \"type\" of this instance. This is an internal\nsystem property and should not be used by a client application.", + "type": "string", + "example": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0" + }, + "$typeVersion": { + "description": "The last-known version of the template of the object. This is an internal\nsystem property and should not be used by a client application.", + "type": "integer", + "example": 2 + }, + "$version": { + "description": "The version of the metadata object. Starts at 0 and increases every time\na user-defined property is modified.", + "type": "integer", + "example": 1 + }, + "cards": { + "description": "A list of Box Skill cards that have been applied to this file.", + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/KeywordSkillCard" }, - "readOnly": true - }, - "email": { - "type": "string", - "description": "Email address of the signer", - "example": "example@mail.com", - "nullable": true - }, - "role": { - "type": "string", - "enum": [ - "signer", - "approver", - "final_copy_reader" - ], - "description": "Defines the role of the signer in the signature request. A role of\n`signer` needs to sign the document, a role `approver`\napproves the document and\na `final_copy_reader` role only\nreceives the final signed document and signing log.", - "example": "signer", - "default": "signer" - }, - "is_in_person": { - "type": "boolean", - "description": "Used in combination with an embed URL for a sender.\nAfter the sender signs, they will be\nredirected to the next `in_person` signer.", - "example": true - }, - "order": { - "type": "integer", - "description": "Order of the signer", - "minimum": 0, - "example": 2 - }, - "signer_group_id": { - "type": "string", - "description": "If provided, this value points signers that are assigned the same inputs and belongs to same signer group.\nA signer group is not a Box Group. It is an entity that belongs to the template itself and can only be used\nwithin Box Sign requests created from it.", - "example": "cd4ff89-8fc1-42cf-8b29-1890dedd26d7", - "nullable": true - }, - "label": { - "type": "string", - "description": "A placeholder label for the signer set by the template creator to differentiate between signers.", - "example": "Jane Doe", - "nullable": true - }, - "public_id": { - "type": "string", - "description": "An identifier for the signer. This can be used to identify a signer within the template.", - "example": "RJZYYVPR" - } + { + "$ref": "#/components/schemas/TimelineSkillCard" + }, + { + "$ref": "#/components/schemas/TranscriptSkillCard" + }, + { + "$ref": "#/components/schemas/StatusSkillCard" + } + ] } } - ] + }, + "title": "Skills metadata instance", + "x-box-resource-id": "skill_cards_metadata", + "x-box-tag": "skills" }, - "TemplateSignerInput": { - "title": "Template Signer Input", + "SkillInvocation": { + "description": "The payload of a Box skill as sent to a skill's\n`invocation_url`.", "type": "object", - "description": "Input created by a Signer on a Template", - "required": [ - "page_index" - ], - "allOf": [ - { - "$ref": "#/components/schemas/SignRequestPrefillTag" + "properties": { + "type": { + "description": "`skill_invocation`", + "type": "string", + "example": "skill_invocation", + "enum": [ + "skill_invocation" + ] }, - { - "properties": { - "type": { - "type": "string", - "enum": [ - "signature", - "date", - "text", - "checkbox", - "attachment", - "radio", - "dropdown" - ], - "description": "Type of input", - "example": "text" - }, - "content_type": { - "type": "string", - "enum": [ - "signature", - "initial", - "stamp", - "date", - "checkbox", - "text", - "full_name", - "first_name", - "last_name", - "company", - "title", - "email", - "attachment", - "radio", - "dropdown" - ], - "description": "Content type of input", - "example": "text" - }, - "is_required": { - "type": "boolean", - "description": "Whether or not the input is required.", - "example": true - }, - "page_index": { - "type": "integer", - "description": "Index of page that the input is on.", - "example": 4 - }, - "document_id": { - "type": "string", - "description": "Document identifier.", - "example": "123075213-eb54b537-8b25-445e-87c1-5a1c67d8cbd7", - "nullable": true - }, - "dropdown_choices": { - "type": "array", - "example": [ - "Yes", - "No", - "Maybe" - ], - "description": "When the input is of the type `dropdown` this values will be filled with all the dropdown options.", - "nullable": true, - "items": { - "type": "string" + "id": { + "description": "Unique identifier for the invocation request.", + "type": "string", + "example": "fd1d2e53-35f5-41fb-9c25-4ba326daf2f9_341016304" + }, + "skill": { + "allOf": [ + { + "title": "Skill", + "type": "object", + "description": "An object representing a skill", + "properties": { + "id": { + "description": "The unique identifier for this skill", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`skill`", + "type": "string", + "example": "skill", + "enum": [ + "skill" + ] + }, + "name": { + "description": "The name of the skill", + "type": "string", + "example": "Hello World Skill" + }, + "api_key": { + "description": "The client ID of the application", + "type": "string", + "example": "hxel2s12wd2h9r8ne103c4gjbqefofih" + } } }, - "group_id": { - "type": "string", - "description": "When the input is of type `radio` they can be grouped to gather with this identifier.", - "nullable": true, - "example": "da317330-225a-4c72-89ad-0d6dcaaf4df6" - }, - "coordinates": { + { + "description": "The skill that triggered this invocation" + } + ] + }, + "token": { + "description": "The read-only and read-write access tokens for this item", + "type": "object", + "properties": { + "read": { + "description": "The basics of an access token", "type": "object", - "description": "Where the input is located on a page.", "properties": { - "x": { - "type": "number", - "example": 0.672258592471358, - "description": "Relative x coordinate to the page the input is on, ranging from 0 to 1." + "access_token": { + "description": "The requested access token.", + "type": "string", + "format": "token", + "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" }, - "y": { - "type": "number", - "example": 0.18654283173599448, - "description": "Relative y coordinate to the page the input is on, ranging from 0 to 1." + "expires_in": { + "description": "The time in seconds by which this token will expire.", + "type": "integer", + "format": "int64", + "example": 3600 + }, + "token_type": { + "description": "The type of access token returned.", + "type": "string", + "example": "bearer", + "enum": [ + "bearer" + ] + }, + "restricted_to": { + "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.", + "type": "string", + "example": "[{\"scope\":\"gcm\"}, {\"scope\":\"item_upload\",\"object_id\":933941692081,\"object_type\":\"file\"}, {\"scope\":\"manage_skill_invocations\"}]" } } }, - "dimensions": { + "write": { + "description": "The basics of an access token", "type": "object", - "description": "The size of the input.", "properties": { - "width": { - "type": "number", - "example": 0.2618657937806874, - "description": "Relative width to the page the input is on, ranging from 0 to 1." + "access_token": { + "description": "The requested access token.", + "type": "string", + "format": "token", + "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" }, - "height": { - "type": "number", - "example": 0.05311728090109673, - "description": "Relative height to the page the input is on, ranging from 0 to 1." + "expires_in": { + "description": "The time in seconds by which this token will expire.", + "type": "integer", + "format": "int64", + "example": 3600 + }, + "token_type": { + "description": "The type of access token returned.", + "type": "string", + "example": "bearer", + "enum": [ + "bearer" + ] + }, + "restricted_to": { + "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.", + "type": "string", + "example": "[{\"scope\":\"gcm\"}, {\"scope\":\"item_upload\",\"object_id\":933941692081,\"object_type\":\"file\"}, {\"scope\":\"manage_skill_invocations\"}]" } } + } + } + }, + "status": { + "description": "The details status of this event.", + "type": "object", + "properties": { + "state": { + "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.", + "type": "string", + "example": "invoked", + "enum": [ + "invoked", + "processing", + "success", + "transient_failure", + "permanent_failure" + ] }, - "label": { + "message": { + "description": "Status information", "type": "string", - "description": "The label field is used especially for text, attachment, radio, and checkbox type inputs.", - "nullable": true, - "example": "Legal name" + "example": "Example" }, - "read_only": { - "type": "boolean", - "description": "Whether this input was defined as read-only(immutable by signers) or not", - "example": true + "error_code": { + "description": "Error code information, if error occurred.", + "type": "string", + "example": "400" + }, + "additional_info": { + "description": "Additional status information.", + "type": "string", + "example": "Example" } } - } - ] - }, - "TrashFile": { - "title": "Trashed File", - "type": "object", - "x-box-resource-id": "trash_file", - "x-box-tag": "trashed_files", - "description": "Represents a trashed file.", - "required": [ - "id", - "type", - "sequence_id", - "sha1", - "description", - "size", - "path_collection", - "created_at", - "modified_at", - "modified_by", - "owned_by", - "item_status" - ], - "properties": { - "id": { - "type": "string", - "nullable": false, - "description": "The unique identifier that represent 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": "123456789" }, - "etag": { + "created_at": { + "description": "The time this invocation was created.", "type": "string", - "example": "1", - "nullable": true, - "description": "The HTTP `etag` of this file. This can be used within some API\nendpoints in the `If-Match` and `If-None-Match` headers to only\nperform changes on the file if (no) changes have happened." + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" }, - "type": { + "trigger": { + "description": "Action that triggered the invocation", "type": "string", - "description": "`file`", - "example": "file", - "enum": [ - "file" - ], - "nullable": false + "example": "FILE_CONTENT" }, - "sequence_id": { + "enterprise": { "allOf": [ { - "type": "string", - "example": "3", - "nullable": true, - "description": "A numeric identifier that represents the most recent user event\nthat has been applied to this item.\n\nThis can be used in combination with the `GET /events`-endpoint\nto filter out user events that would have occurred before this\nidentifier was read.\n\nAn example would be where a Box Drive-like application\nwould fetch an item via the API, and then listen to incoming\nuser events for changes to the item. The application would\nignore any user events where the `sequence_id` in the event\nis smaller than or equal to the `sequence_id` in the originally\nfetched resource." + "title": "Enterprise", + "type": "object", + "description": "A representation of a Box enterprise", + "properties": { + "id": { + "description": "The unique identifier for this enterprise.", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`enterprise`", + "type": "string", + "example": "enterprise", + "enum": [ + "enterprise" + ] + }, + "name": { + "description": "The name of the enterprise", + "type": "string", + "example": "Acme Inc." + } + } }, { - "nullable": false + "description": "The enterprise that this invocation was triggered for" } ] }, - "name": { - "type": "string", - "description": "The name of the file", - "example": "Contract.pdf" - }, - "sha1": { - "type": "string", - "format": "digest", - "nullable": false, - "example": "85136C79CBF9FE36BB9D05D0639C70C265C18D37", - "description": "The SHA1 hash of the file. This can be used to compare the contents\nof a file on Box with a local file." - }, - "file_version": { + "source": { "allOf": [ { - "$ref": "#/components/schemas/FileVersion--Mini" + "oneOf": [ + { + "$ref": "#/components/schemas/File" + }, + { + "$ref": "#/components/schemas/Folder" + } + ] }, { - "description": "The information about the current version of the file." + "description": "The item that caused the invocation to trigger" } ] }, - "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": { + "event": { "allOf": [ { - "title": "Path collection (Trash)", - "description": "A list of parent folders for an item in the trash.", - "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": { - "description": "Array of folders for this item's path collection", - "type": "array", - "items": { - "type": "object", - "description": "The parent folder for this item", - "properties": { - "type": { - "type": "string", - "description": "`folder`", - "enum": [ - "folder" - ], - "example": "folder" - }, - "id": { - "type": "string", - "description": "The unique identifier that represent a folder.", - "example": "123456789" - }, - "sequence_id": { - "type": "string", - "nullable": true, - "example": null, - "description": "This field is null for the Trash folder" - }, - "etag": { - "type": "string", - "nullable": true, - "example": null, - "description": "This field is null for the Trash folder" - }, - "name": { - "type": "string", - "description": "The name of the Trash folder.", - "example": "Trash", - "nullable": false - } - } - } - } - } - }, - { - "description": "The tree of folders that this file is contained in,\nstarting at the root." + "$ref": "#/components/schemas/Event" }, { - "nullable": false + "description": "The event that triggered this invocation" } ] - }, + } + }, + "title": "Skill webhook payload", + "x-box-resource-id": "skill_invocation", + "x-box-tag": "skills" + }, + "StatusSkillCard": { + "description": "A Box Skill metadata card that puts a status message in the metadata sidebar.", + "type": "object", + "properties": { "created_at": { + "description": "The optional date and time this card was 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" + "example": "2018-04-13T13:53:23-07:00" }, - "trashed_at": { + "type": { + "description": "`skill_card`", "type": "string", - "format": "date-time", - "nullable": true, - "description": "The time at which this file was put in the trash.", - "example": "2012-12-12T10:53:43-08:00" + "example": "skill_card", + "enum": [ + "skill_card" + ] }, - "purged_at": { + "skill_card_type": { + "description": "`status`", "type": "string", - "format": "date-time", - "nullable": true, - "description": "The time at which this file is expected to be purged\nfrom the trash.", - "example": "2012-12-12T10:53:43-08:00" + "example": "status", + "enum": [ + "status" + ] }, - "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" + "skill_card_title": { + "description": "The title of the card.", + "type": "object", + "properties": { + "code": { + "description": "An optional identifier for the title.", + "type": "string", + "example": "status" + }, + "message": { + "description": "The actual title to show in the UI.", + "type": "string", + "example": "Status" + } + }, + "required": [ + "message" + ] }, - "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" + "status": { + "description": "Sets the status of the skill. This can be used to show a message to the user while the Skill is processing the data, or if it was not able to process the file.", + "type": "object", + "properties": { + "code": { + "description": "A code for the status of this Skill invocation. By\ndefault each of these will have their own accompanied\nmessages. These can be adjusted by setting the `message`\nvalue on this object.", + "type": "string", + "example": "success", + "enum": [ + "invoked", + "processing", + "success", + "transient_failure", + "permanent_failure" + ] + }, + "message": { + "description": "A custom message that can be provided with this status.\nThis will be shown in the web app to the end user.", + "type": "string", + "example": "We're preparing to process your file. Please hold on!" + } + }, + "required": [ + "code" + ] }, - "created_by": { - "allOf": [ - { - "$ref": "#/components/schemas/User--Mini" + "skill": { + "description": "The service that applied this metadata.", + "type": "object", + "properties": { + "type": { + "description": "`service`", + "type": "string", + "example": "service", + "enum": [ + "service" + ] }, - { - "description": "The user who created this file" + "id": { + "description": "A custom identifier that represent the service that\napplied this metadata.", + "type": "string", + "example": "image-recognition-service" } + }, + "required": [ + "type", + "id" ] }, - "modified_by": { - "allOf": [ - { - "$ref": "#/components/schemas/User--Mini" + "invocation": { + "description": "The invocation of this service, used to track\nwhich instance of a service applied the metadata.", + "type": "object", + "properties": { + "type": { + "description": "`skill_invocation`", + "type": "string", + "example": "skill_invocation", + "enum": [ + "skill_invocation" + ] }, - { - "description": "The user who last modified this file" + "id": { + "description": "A custom identifier that represent the instance of\nthe service that applied this metadata. For example,\nif your `image-recognition-service` runs on multiple\nnodes, this field can be used to identify the ID of\nthe node that was used to apply the metadata.", + "type": "string", + "example": "image-recognition-service-123" + } + }, + "required": [ + "type", + "id" + ] + } + }, + "required": [ + "type", + "skill_card_type", + "skill", + "invocation", + "status" + ], + "title": "Status Skill Card", + "x-box-resource-id": "status_skill_card", + "x-box-tag": "skills" + }, + "StoragePolicies": { + "description": "A list of storage policies.", + "type": "object", + "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.", + "type": "integer", + "format": "int64", + "example": 1000 }, - { - "nullable": false + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "description": "A list of storage policies", + "type": "array", + "items": { + "$ref": "#/components/schemas/StoragePolicy" + } + } + } + } + ], + "title": "Storage policies", + "x-box-resource-id": "storage_policies", + "x-box-tag": "storage_policies" + }, + "StoragePolicy": { + "description": "The Storage Policy object describes the storage zone.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/StoragePolicy--Mini" + }, + { + "properties": { + "name": { + "description": "A descriptive name of the region", + "type": "string", + "example": "Montreal / Dublin" } + } + } + ], + "title": "Storage policy", + "x-box-resource-id": "storage_policy", + "x-box-variant": "standard" + }, + "StoragePolicy--Mini": { + "description": "A mini description of a Storage Policy object", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this storage policy", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`storage_policy`", + "type": "string", + "example": "storage_policy", + "enum": [ + "storage_policy" ] + } + }, + "required": [ + "id", + "type" + ], + "title": "Storage policy (Mini)", + "x-box-resource-id": "storage_policy--mini", + "x-box-tag": "storage_policies", + "x-box-variant": "mini", + "x-box-variants": [ + "standard", + "mini" + ] + }, + "StoragePolicyAssignment": { + "description": "The assignment of a storage policy to a user or enterprise", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for a storage policy assignment.", + "type": "string", + "example": "ZW50ZXJwcmlzZV8xMjM0NTY3ODkw" }, - "owned_by": { + "type": { + "description": "`storage_policy_assignment`", + "type": "string", + "example": "storage_policy_assignment", + "enum": [ + "storage_policy_assignment" + ] + }, + "storage_policy": { "allOf": [ { - "$ref": "#/components/schemas/User--Mini" - }, - { - "description": "The user who owns this file" + "$ref": "#/components/schemas/StoragePolicy--Mini" }, { - "nullable": false + "description": "The assigned storage policy" } ] }, - "shared_link": { - "type": "string", - "description": "The shared link for this file. This will\nbe `null` if a file has been trashed, since the link will no longer\nbe active.", - "example": null, - "nullable": true - }, - "parent": { + "assigned_to": { "allOf": [ { - "$ref": "#/components/schemas/Folder--Mini" + "title": "Reference", + "description": "The bare basic reference for an object", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this object", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "The type for this object", + "type": "string", + "example": "file" + } + } }, { - "description": "The folder that this file is located within." + "description": "The enterprise or use the policy is assigned to" + } + ] + } + }, + "required": [ + "id", + "type" + ], + "title": "Storage policy assignment", + "x-box-resource-id": "storage_policy_assignment", + "x-box-tag": "storage_policy_assignments" + }, + "StoragePolicyAssignments": { + "description": "A list of storage policy assignments.", + "type": "object", + "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.", + "type": "integer", + "format": "int64", + "example": 1000 }, - { + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } - ] + } }, - "item_status": { - "type": "string", - "description": "Defines if this item has been deleted or not.\n\n* `active` when the item has is not in the trash\n* `trashed` when the item has been moved to the trash but not deleted\n* `deleted` when the item has been permanently deleted.", - "enum": [ - "active", - "trashed", - "deleted" - ], - "nullable": false, - "example": "trashed" + { + "properties": { + "entries": { + "description": "A list of storage policy assignments", + "type": "array", + "items": { + "$ref": "#/components/schemas/StoragePolicyAssignment" + } + } + } } - } + ], + "title": "Storage policy assignments", + "x-box-resource-id": "storage_policy_assignments", + "x-box-tag": "storage_policy_assignments" }, - "TrashFolder": { - "title": "Trashed Folder", + "Task": { + "description": "A task allows for file-centric workflows within Box. Users can\ncreate tasks on files and assign them to other users for them to complete the\ntasks.", "type": "object", - "x-box-resource-id": "trash_folder", - "x-box-tag": "trashed_folders", - "description": "Represents a trashed folder.", - "required": [ - "id", - "type", - "name", - "description", - "size", - "path_collection", - "created_by", - "modified_by", - "owned_by", - "item_status" - ], "properties": { "id": { + "description": "The unique identifier for this task", "type": "string", - "nullable": false, - "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting a folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folders/123`\nthe `folder_id` is `123`.", - "example": "123456789" - }, - "etag": { - "type": "string", - "nullable": true, - "example": "1", - "description": "The HTTP `etag` of this folder. This can be used within some API\nendpoints in the `If-Match` and `If-None-Match` headers to only\nperform changes on the folder if (no) changes have happened." + "example": "11446498" }, "type": { + "description": "`task`", "type": "string", - "description": "`folder`", - "example": "folder", + "example": "task", "enum": [ - "folder" - ], - "nullable": false + "task" + ] }, - "sequence_id": { + "item": { "allOf": [ { - "type": "string", - "example": "3", - "nullable": true, - "description": "A numeric identifier that represents the most recent user event\nthat has been applied to this item.\n\nThis can be used in combination with the `GET /events`-endpoint\nto filter out user events that would have occurred before this\nidentifier was read.\n\nAn example would be where a Box Drive-like application\nwould fetch an item via the API, and then listen to incoming\nuser events for changes to the item. The application would\nignore any user events where the `sequence_id` in the event\nis smaller than or equal to the `sequence_id` in the originally\nfetched resource." + "$ref": "#/components/schemas/File--Mini" }, { - "nullable": false + "description": "The file associated with the task" } ] }, - "name": { - "type": "string", - "description": "The name of the folder.", - "example": "Contracts", - "nullable": false - }, - "created_at": { + "due_at": { + "description": "When the task is due", "type": "string", "format": "date-time", - "nullable": true, - "description": "The date and time when the folder was created. This value may\nbe `null` for some folders such as the root folder or the trash\nfolder.", "example": "2012-12-12T10:53:43-08:00" }, - "modified_at": { + "action": { + "description": "The type of task the task assignee will be prompted to\nperform.", "type": "string", - "format": "date-time", - "description": "The date and time when the folder was last updated. This value may\nbe `null` for some folders such as the root folder or the trash\nfolder.", - "example": "2012-12-12T10:53:43-08:00", - "nullable": true + "example": "review", + "enum": [ + "review", + "complete" + ] }, - "description": { + "message": { + "description": "A message that will be included with the task", + "type": "string", + "example": "Legal review" + }, + "task_assignment_collection": { "allOf": [ { - "type": "string", - "description": "The optional description of this folder", - "maxLength": 256, - "example": "Legal contracts for the new ACME deal", - "nullable": false + "$ref": "#/components/schemas/TaskAssignments" }, { - "nullable": false + "description": "A collection of task assignment objects\nassociated with the task" } ] }, - "size": { - "type": "integer", - "format": "int64", - "description": "The folder size in bytes.\n\nBe careful parsing this integer as its\nvalue can get very large.", - "example": 629644, - "nullable": false - }, - "path_collection": { - "allOf": [ - { - "title": "Path collection (Trash)", - "description": "A list of parent folders for an item in the trash.", - "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": { - "description": "Array of folders for this item's path collection", - "type": "array", - "items": { - "type": "object", - "description": "The parent folder for this item", - "properties": { - "type": { - "type": "string", - "description": "`folder`", - "enum": [ - "folder" - ], - "example": "folder" - }, - "id": { - "type": "string", - "description": "The unique identifier that represent a folder.", - "example": "123456789" - }, - "sequence_id": { - "type": "string", - "nullable": true, - "example": null, - "description": "This field is null for the Trash folder" - }, - "etag": { - "type": "string", - "nullable": true, - "example": null, - "description": "This field is null for the Trash folder" - }, - "name": { - "type": "string", - "description": "The name of the Trash folder.", - "example": "Trash", - "nullable": false - } - } - } - } - } - }, - { - "description": "The tree of folders that this file is contained in,\nstarting at the root." - }, - { - "nullable": false - } - ] + "is_completed": { + "description": "Whether the task has been completed", + "type": "boolean", + "example": true }, "created_by": { "allOf": [ @@ -34774,632 +35299,971 @@ "$ref": "#/components/schemas/User--Mini" }, { - "description": "The user who created this folder" - }, - { - "nullable": false - } - ] - }, - "modified_by": { - "allOf": [ - { - "$ref": "#/components/schemas/User--Mini" - }, - { - "description": "The user who last modified this folder." - }, - { - "nullable": false + "description": "The user who created the task" } ] }, - "trashed_at": { - "type": "string", - "format": "date-time", - "description": "The time at which this folder 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 folder 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 folder was originally\ncreated.", - "example": "2012-12-12T10:53:43-08:00" - }, - "content_modified_at": { + "created_at": { + "description": "When the task object was created", "type": "string", "format": "date-time", - "nullable": true, - "description": "The date and time at which this folder was last updated.", "example": "2012-12-12T10:53:43-08:00" }, - "owned_by": { - "allOf": [ - { - "$ref": "#/components/schemas/User--Mini" - }, - { - "description": "The user who owns this folder." - }, - { - "nullable": false - } - ] - }, - "shared_link": { - "type": "string", - "description": "The shared link for this folder. This will\nbe `null` if a folder has been trashed, since the link will no longer\nbe active.", - "example": null, - "nullable": true - }, - "folder_upload_email": { - "type": "string", - "description": "The folder upload email for this folder. This will\nbe `null` if a folder has been trashed, since the upload will no longer\nwork.", - "example": null, - "nullable": true - }, - "parent": { - "allOf": [ - { - "$ref": "#/components/schemas/Folder--Mini" - }, - { - "description": "The optional folder that this folder is located within.\n\nThis value may be `null` for some folders such as the\nroot folder or the trash folder." - }, - { - "nullable": true - } - ] - }, - "item_status": { + "completion_rule": { + "description": "Defines which assignees need to complete this task before the task\nis considered completed.\n\n* `all_assignees` 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.", "type": "string", - "description": "Defines if this item has been deleted or not.\n\n* `active` when the item has is not in the trash\n* `trashed` when the item has been moved to the trash but not deleted\n* `deleted` when the item has been permanently deleted.", + "example": "all_assignees", "enum": [ - "active", - "trashed", - "deleted" - ], - "nullable": false, - "example": "trashed" + "all_assignees", + "any_assignee" + ] } - } + }, + "title": "Task", + "x-box-resource-id": "task", + "x-box-tag": "tasks" }, - "TrashWebLink": { - "title": "Trashed Web Link", + "TaskAssignment": { + "description": "A task assignment defines which task is assigned to which user to complete.", "type": "object", - "x-box-resource-id": "trash_web_link", - "x-box-tag": "trashed_web_links", - "description": "Represents a trashed web link.", "properties": { - "type": { - "type": "string", - "description": "`web_link`", - "example": "web_link", - "enum": [ - "web_link" - ] - }, "id": { + "description": "The unique identifier for this task assignment", "type": "string", - "description": "The unique identifier for this web link", "example": "11446498" }, - "sequence_id": { - "allOf": [ - { - "type": "string", - "example": "3", - "nullable": true, - "description": "A numeric identifier that represents the most recent user event\nthat has been applied to this item.\n\nThis can be used in combination with the `GET /events`-endpoint\nto filter out user events that would have occurred before this\nidentifier was read.\n\nAn example would be where a Box Drive-like application\nwould fetch an item via the API, and then listen to incoming\nuser events for changes to the item. The application would\nignore any user events where the `sequence_id` in the event\nis smaller than or equal to the `sequence_id` in the originally\nfetched resource." - }, - { - "nullable": false - } - ] - }, - "etag": { - "type": "string", - "example": "1", - "description": "The entity tag of this web link. Used with `If-Match`\nheaders." - }, - "name": { - "type": "string", - "description": "The name of the web link", - "example": "My Bookmark" - }, - "url": { + "type": { + "description": "`task_assignment`", "type": "string", - "example": "https://www.example.com/example/1234", - "description": "The URL this web link points to" + "example": "task_assignment", + "enum": [ + "task_assignment" + ] }, - "parent": { + "item": { "allOf": [ { - "$ref": "#/components/schemas/Folder--Mini" + "$ref": "#/components/schemas/File--Mini" }, { - "description": "The parent object the web link belongs to" + "description": "The file that the task has been assigned to." } ] }, - "description": { - "type": "string", - "example": "Example page", - "description": "The description accompanying the web link. This is\nvisible within the Box web application." - }, - "path_collection": { + "assigned_to": { "allOf": [ { - "title": "Path collection (Trash)", - "description": "A list of parent folders for an item in the trash.", - "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": { - "description": "Array of folders for this item's path collection", - "type": "array", - "items": { - "type": "object", - "description": "The parent folder for this item", - "properties": { - "type": { - "type": "string", - "description": "`folder`", - "enum": [ - "folder" - ], - "example": "folder" - }, - "id": { - "type": "string", - "description": "The unique identifier that represent a folder.", - "example": "123456789" - }, - "sequence_id": { - "type": "string", - "nullable": true, - "example": null, - "description": "This field is null for the Trash folder" - }, - "etag": { - "type": "string", - "nullable": true, - "example": null, - "description": "This field is null for the Trash folder" - }, - "name": { - "type": "string", - "description": "The name of the Trash folder.", - "example": "Trash", - "nullable": false - } - } - } - } - } - }, - { - "description": "The tree of folders that this web link is contained in,\nstarting at the root." + "$ref": "#/components/schemas/User--Mini" }, { - "nullable": false + "description": "The user that the task has been assigned to." } ] }, - "created_at": { + "message": { + "description": "A message that will is included with the task\nassignment. This is visible to the assigned user in the web and mobile\nUI.", "type": "string", - "format": "date-time", - "description": "When this file was created on Box’s servers.", - "example": "2012-12-12T10:53:43-08:00" + "example": "Please review" }, - "modified_at": { + "completed_at": { + "description": "The date at which this task assignment was\ncompleted. This will be `null` if the task is not completed yet.", "type": "string", "format": "date-time", - "description": "When this file was last updated on the Box\nservers.", "example": "2012-12-12T10:53:43-08:00" }, - "trashed_at": { + "assigned_at": { + "description": "The date at which this task was assigned to the user.", "type": "string", "format": "date-time", - "nullable": true, - "description": "When this file was last moved to the trash.", "example": "2012-12-12T10:53:43-08:00" }, - "purged_at": { + "reminded_at": { + "description": "The date at which the assigned user was reminded of this task\nassignment.", "type": "string", "format": "date-time", - "nullable": true, - "description": "When this file will be permanently deleted.", "example": "2012-12-12T10:53:43-08:00" }, - "created_by": { - "allOf": [ - { - "$ref": "#/components/schemas/User--Mini" - }, - { - "description": "The user who created this web link" - } - ] - }, - "modified_by": { - "allOf": [ - { - "$ref": "#/components/schemas/User--Mini" - }, - { - "description": "The user who last modified this web link" - } + "resolution_state": { + "description": "The current state of the assignment. The available states depend on\nthe `action` value of the task object.", + "type": "string", + "example": "incomplete", + "enum": [ + "completed", + "incomplete", + "approved", + "rejected" ] }, - "owned_by": { + "assigned_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { - "description": "The user who owns this web link" + "description": "The user who assigned this task." } ] - }, - "shared_link": { - "type": "string", - "description": "The shared link for this bookmark. This will\nbe `null` if a bookmark has been trashed, since the link will no longer\nbe active.", - "example": null, - "nullable": true - }, - "item_status": { - "type": "string", - "example": "trashed", - "enum": [ - "active", - "trashed", - "deleted" - ], - "description": "Whether this item is deleted or not. Values include `active`,\n`trashed` if the file has been moved to the trash, and `deleted` if\nthe file has been permanently deleted" } - } + }, + "title": "Task assignment", + "x-box-resource-id": "task_assignment", + "x-box-tag": "task_assignments" }, - "TrashFileRestored": { - "title": "Trashed File (Restored)", + "TaskAssignments": { + "description": "A list of task assignments", "type": "object", - "x-box-resource-id": "trash_file_restored", - "x-box-tag": "trashed_files", - "description": "Represents a file restored from the trash.", - "required": [ - "id", - "type", - "sequence_id", - "sha1", - "description", - "size", - "path_collection", - "created_at", - "modified_at", - "modified_by", - "owned_by", - "item_status" - ], "properties": { - "id": { - "type": "string", - "nullable": false, - "description": "The unique identifier that represent 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": "123456789" - }, - "etag": { - "type": "string", - "example": "1", - "nullable": true, - "description": "The HTTP `etag` of this file. This can be used within some API\nendpoints in the `If-Match` and `If-None-Match` headers to only\nperform changes on the file if (no) changes have happened." + "total_count": { + "description": "The total number of items in this collection.", + "type": "integer", + "format": "int64", + "example": 100 }, - "type": { - "type": "string", - "description": "`file`", - "example": "file", - "enum": [ - "file" - ], - "nullable": false + "entries": { + "description": "A list of task assignments", + "type": "array", + "items": { + "$ref": "#/components/schemas/TaskAssignment" + } + } + }, + "title": "Task assignments", + "x-box-resource-id": "task_assignments", + "x-box-tag": "task_assignments" + }, + "Tasks": { + "description": "A list of tasks", + "type": "object", + "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`.", + "type": "integer", + "format": "int64", + "example": 5000 }, - "sequence_id": { - "allOf": [ - { + "entries": { + "description": "A list of tasks", + "type": "array", + "items": { + "$ref": "#/components/schemas/Task" + } + } + }, + "title": "Tasks", + "x-box-resource-id": "tasks", + "x-box-tag": "tasks" + }, + "TemplateSigner": { + "description": "The schema for a Signer for Templates", + "type": "object", + "allOf": [ + { + "properties": { + "inputs": { + "type": "array", + "items": { + "$ref": "#/components/schemas/TemplateSignerInput" + }, + "readOnly": true + }, + "email": { + "description": "Email address of the signer", "type": "string", - "example": "3", - "nullable": true, - "description": "A numeric identifier that represents the most recent user event\nthat has been applied to this item.\n\nThis can be used in combination with the `GET /events`-endpoint\nto filter out user events that would have occurred before this\nidentifier was read.\n\nAn example would be where a Box Drive-like application\nwould fetch an item via the API, and then listen to incoming\nuser events for changes to the item. The application would\nignore any user events where the `sequence_id` in the event\nis smaller than or equal to the `sequence_id` in the originally\nfetched resource." + "example": "example@mail.com", + "nullable": true }, - { - "nullable": false - } - ] - }, - "name": { - "type": "string", - "description": "The name of the file", - "example": "Contract.pdf" - }, - "sha1": { - "type": "string", - "format": "digest", - "nullable": false, - "example": "85136C79CBF9FE36BB9D05D0639C70C265C18D37", - "description": "The SHA1 hash of the file. This can be used to compare the contents\nof a file on Box with a local file." - }, - "file_version": { - "allOf": [ - { - "$ref": "#/components/schemas/FileVersion--Mini" + "role": { + "description": "Defines the role of the signer in the signature request. A role of\n`signer` needs to sign the document, a role `approver`\napproves the document and\na `final_copy_reader` role only\nreceives the final signed document and signing log.", + "type": "string", + "example": "signer", + "default": "signer", + "enum": [ + "signer", + "approver", + "final_copy_reader" + ] }, - { - "description": "The information about the current version of the file." + "is_in_person": { + "description": "Used in combination with an embed URL for a sender.\nAfter the sender signs, they will be\nredirected to the next `in_person` signer.", + "type": "boolean", + "example": true + }, + "order": { + "description": "Order of the signer", + "type": "integer", + "example": 2, + "minimum": 0 + }, + "signer_group_id": { + "description": "If provided, this value points signers that are assigned the same inputs and belongs to same signer group.\nA signer group is not a Box Group. It is an entity that belongs to the template itself and can only be used\nwithin Box Sign requests created from it.", + "type": "string", + "example": "cd4ff89-8fc1-42cf-8b29-1890dedd26d7", + "nullable": true + }, + "label": { + "description": "A placeholder label for the signer set by the template creator to differentiate between signers.", + "type": "string", + "example": "Jane Doe", + "nullable": true + }, + "public_id": { + "description": "An identifier for the signer. This can be used to identify a signer within the template.", + "type": "string", + "example": "RJZYYVPR" } - ] + } + } + ], + "title": "Signer fields for Templates" + }, + "TemplateSignerInput": { + "description": "Input created by a Signer on a Template", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/SignRequestPrefillTag" }, - "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": { + "type": { + "description": "Type of input", + "type": "string", + "example": "text", + "enum": [ + "signature", + "date", + "text", + "checkbox", + "attachment", + "radio", + "dropdown" + ] + }, + "content_type": { + "description": "Content type of input", + "type": "string", + "example": "text", + "enum": [ + "signature", + "initial", + "stamp", + "date", + "checkbox", + "text", + "full_name", + "first_name", + "last_name", + "company", + "title", + "email", + "attachment", + "radio", + "dropdown" + ] + }, + "is_required": { + "description": "Whether or not the input is required.", + "type": "boolean", + "example": true + }, + "page_index": { + "description": "Index of page that the input is on.", + "type": "integer", + "example": 4 + }, + "document_id": { + "description": "Document identifier.", + "type": "string", + "example": "123075213-eb54b537-8b25-445e-87c1-5a1c67d8cbd7", + "nullable": true + }, + "dropdown_choices": { + "description": "When the input is of the type `dropdown` this values will be filled with all the dropdown options.", + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "Yes", + "No", + "Maybe" ], + "nullable": true + }, + "group_id": { + "description": "When the input is of type `radio` they can be grouped to gather with this identifier.", + "type": "string", + "example": "da317330-225a-4c72-89ad-0d6dcaaf4df6", + "nullable": true + }, + "coordinates": { + "description": "Where the input is located on a page.", + "type": "object", "properties": { - "total_count": { - "description": "The number of folders in this list.", - "example": 1, - "type": "integer", - "format": "int64", - "nullable": false + "x": { + "description": "Relative x coordinate to the page the input is on, ranging from 0 to 1.", + "type": "number", + "example": 0.672258592471358 }, - "entries": { - "type": "array", - "description": "The parent folders for this item", - "nullable": false, - "items": { - "$ref": "#/components/schemas/Folder--Mini" - } + "y": { + "description": "Relative y coordinate to the page the input is on, ranging from 0 to 1.", + "type": "number", + "example": 0.18654283173599448 } } }, - { - "description": "The tree of folders that this file is contained in,\nstarting at the root." + "dimensions": { + "description": "The size of the input.", + "type": "object", + "properties": { + "width": { + "description": "Relative width to the page the input is on, ranging from 0 to 1.", + "type": "number", + "example": 0.2618657937806874 + }, + "height": { + "description": "Relative height to the page the input is on, ranging from 0 to 1.", + "type": "number", + "example": 0.05311728090109673 + } + } }, - { - "nullable": false + "label": { + "description": "The label field is used especially for text, attachment, radio, and checkbox type inputs.", + "type": "string", + "example": "Legal name", + "nullable": true + }, + "read_only": { + "description": "Whether this input was defined as read-only(immutable by signers) or not", + "type": "boolean", + "example": true } - ] - }, - "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" + } + } + ], + "required": [ + "page_index" + ], + "title": "Template Signer Input" + }, + "TermsOfService": { + "description": "The root-level record that is supposed to represent a\nsingle Terms of Service.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/TermsOfService--Base" }, - "trashed_at": { + { + "properties": { + "status": { + "description": "Whether these terms are enabled or not", + "type": "string", + "example": "enabled", + "enum": [ + "enabled", + "disabled" + ] + }, + "enterprise": { + "allOf": [ + { + "title": "Enterprise", + "type": "object", + "description": "A representation of a Box enterprise", + "properties": { + "id": { + "description": "The unique identifier for this enterprise.", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`enterprise`", + "type": "string", + "example": "enterprise", + "enum": [ + "enterprise" + ] + }, + "name": { + "description": "The name of the enterprise", + "type": "string", + "example": "Acme Inc." + } + } + }, + { + "description": "The enterprise these terms apply to" + } + ] + }, + "tos_type": { + "description": "Whether to apply these terms to managed users or external users", + "type": "string", + "example": "managed", + "enum": [ + "managed", + "external" + ] + }, + "text": { + "description": "The text for your terms and conditions. This text could be\nempty if the `status` is set to `disabled`.", + "type": "string", + "example": "By using this service, you agree to ..." + }, + "created_at": { + "description": "When the legal item was created", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "modified_at": { + "description": "When the legal item was modified.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + } + } + } + ], + "title": "Terms of service", + "x-box-resource-id": "terms_of_service", + "x-box-variant": "standard" + }, + "TermsOfService--Base": { + "description": "The root-level record that is supposed to represent a\nsingle Terms of Service.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this terms of service.", "type": "string", - "nullable": true, - "description": "The time at which this file was put in the\ntrash - becomes `null` after restore.", - "example": null + "example": "11446498" }, - "purged_at": { + "type": { + "description": "`terms_of_service`", "type": "string", - "nullable": true, - "description": "The time at which this file is expected to be purged\nfrom the trash - becomes `null` after restore.", - "example": null - }, - "content_created_at": { + "example": "terms_of_service", + "enum": [ + "terms_of_service" + ] + } + }, + "required": [ + "id", + "type" + ], + "title": "Terms of service (Base)", + "x-box-resource-id": "terms_of_service--base", + "x-box-tag": "terms_of_services", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "standard" + ] + }, + "TermsOfServiceUserStatus": { + "description": "The association between a Terms of Service and a user", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this terms of service user status", "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" + "example": "11446498" }, - "content_modified_at": { + "type": { + "description": "`terms_of_service_user_status`", "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" - } + "example": "terms_of_service_user_status", + "enum": [ + "terms_of_service_user_status" ] }, - "modified_by": { + "tos": { "allOf": [ { - "$ref": "#/components/schemas/User--Mini" - }, - { - "description": "The user who last modified this file" + "$ref": "#/components/schemas/TermsOfService--Base" }, { - "nullable": false + "description": "The terms of service" } ] }, - "owned_by": { + "user": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { - "description": "The user who owns this file" - }, - { - "nullable": false + "description": "The user" } ] }, - "shared_link": { - "type": "string", - "description": "The shared link for this file. This will\nbe `null` if a file had been trashed, even though the original shared\nlink does become active again.", - "nullable": true, - "example": null + "is_accepted": { + "description": "If the user has accepted the terms of services", + "type": "boolean", + "example": true }, - "parent": { - "allOf": [ - { - "$ref": "#/components/schemas/Folder--Mini" - }, - { - "description": "The folder that this file is located within." - }, - { - "nullable": true - } - ] + "created_at": { + "description": "When the legal item was created", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" }, - "item_status": { + "modified_at": { + "description": "When the legal item was modified.", "type": "string", - "description": "Defines if this item has been deleted or not.\n\n* `active` when the item has is not in the trash\n* `trashed` when the item has been moved to the trash but not deleted\n* `deleted` when the item has been permanently deleted.", - "enum": [ - "active", - "trashed", - "deleted" - ], - "nullable": false, - "example": "active" + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" } - } + }, + "required": [ + "id", + "type" + ], + "title": "Terms of service user status", + "x-box-resource-id": "terms_of_service_user_status", + "x-box-tag": "terms_of_service_user_statuses" }, - "TrashFolderRestored": { - "title": "Trashed Folder (Restored)", + "TermsOfServiceUserStatuses": { + "description": "A list of terms of service user statuses", "type": "object", - "x-box-resource-id": "trash_folder_restored", - "x-box-tag": "trashed_folders", - "description": "Represents a folder restored from the trash.", "properties": { - "id": { - "type": "string", - "nullable": false, - "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting a folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folders/123`\nthe `folder_id` is `123`.", - "example": "123456789" + "total_count": { + "description": "The total number of objects.", + "type": "integer", + "format": "int64", + "example": 2 }, - "etag": { + "entries": { + "description": "A list of terms of service user statuses", + "type": "array", + "items": { + "$ref": "#/components/schemas/TermsOfServiceUserStatus" + } + } + }, + "title": "Terms of service user statuses", + "x-box-resource-id": "terms_of_services_user_statuses", + "x-box-tag": "terms_of_service_user_statuses" + }, + "TermsOfServices": { + "description": "A list of terms of services", + "type": "object", + "properties": { + "total_count": { + "description": "The total number of objects.", + "type": "integer", + "format": "int64", + "example": 2 + }, + "entries": { + "description": "A list of terms of service objects", + "type": "array", + "items": { + "$ref": "#/components/schemas/TermsOfService" + } + } + }, + "title": "Terms of services", + "x-box-resource-id": "terms_of_services", + "x-box-tag": "terms_of_services" + }, + "TimelineSkillCard": { + "description": "A Box Skill metadata card that places a list of images on a\ntimeline.", + "type": "object", + "properties": { + "created_at": { + "description": "The optional date and time this card was created at.", "type": "string", - "nullable": true, - "example": "1", - "description": "The HTTP `etag` of this folder. This can be used within some API\nendpoints in the `If-Match` and `If-None-Match` headers to only\nperform changes on the folder if (no) changes have happened." + "format": "date-time", + "example": "2018-04-13T13:53:23-07:00" }, "type": { + "description": "`skill_card`", "type": "string", - "description": "`folder`", - "example": "folder", + "example": "skill_card", "enum": [ - "folder" - ], - "nullable": false + "skill_card" + ] }, - "sequence_id": { - "allOf": [ - { + "skill_card_type": { + "description": "`timeline`", + "type": "string", + "example": "timeline", + "enum": [ + "timeline" + ] + }, + "skill_card_title": { + "description": "The title of the card.", + "type": "object", + "properties": { + "code": { + "description": "An optional identifier for the title.", "type": "string", - "example": "3", - "nullable": true, - "description": "A numeric identifier that represents the most recent user event\nthat has been applied to this item.\n\nThis can be used in combination with the `GET /events`-endpoint\nto filter out user events that would have occurred before this\nidentifier was read.\n\nAn example would be where a Box Drive-like application\nwould fetch an item via the API, and then listen to incoming\nuser events for changes to the item. The application would\nignore any user events where the `sequence_id` in the event\nis smaller than or equal to the `sequence_id` in the originally\nfetched resource." + "example": "Faces" }, - { - "nullable": false + "message": { + "description": "The actual title to show in the UI.", + "type": "string", + "example": "Faces" } + }, + "required": [ + "message" ] }, - "name": { - "type": "string", - "description": "The name of the folder.", - "example": "Contracts", - "nullable": false - }, - "created_at": { - "type": "string", - "format": "date-time", - "nullable": true, - "description": "The date and time when the folder was created. This value may\nbe `null` for some folders such as the root folder or the trash\nfolder.", - "example": "2012-12-12T10:53:43-08:00" - }, - "modified_at": { - "type": "string", - "format": "date-time", - "description": "The date and time when the folder was last updated. This value may\nbe `null` for some folders such as the root folder or the trash\nfolder.", - "example": "2012-12-12T10:53:43-08:00", - "nullable": true + "skill": { + "description": "The service that applied this metadata.", + "type": "object", + "properties": { + "type": { + "description": "`service`", + "type": "string", + "example": "service", + "enum": [ + "service" + ] + }, + "id": { + "description": "A custom identifier that represent the service that\napplied this metadata.", + "type": "string", + "example": "image-recognition-service" + } + }, + "required": [ + "type", + "id" + ] }, - "description": { - "allOf": [ - { + "invocation": { + "description": "The invocation of this service, used to track\nwhich instance of a service applied the metadata.", + "type": "object", + "properties": { + "type": { + "description": "`skill_invocation`", "type": "string", - "description": "The optional description of this folder", - "maxLength": 256, - "example": "Legal contracts for the new ACME deal", - "nullable": false + "example": "skill_invocation", + "enum": [ + "skill_invocation" + ] }, - { - "nullable": false + "id": { + "description": "A custom identifier that represent the instance of\nthe service that applied this metadata. For example,\nif your `image-recognition-service` runs on multiple\nnodes, this field can be used to identify the ID of\nthe node that was used to apply the metadata.", + "type": "string", + "example": "image-recognition-service-123" } + }, + "required": [ + "type", + "id" ] }, - "size": { + "duration": { + "description": "An total duration in seconds of the timeline.", + "type": "integer", + "example": 1000 + }, + "entries": { + "description": "A list of entries on the timeline.", + "type": "array", + "items": { + "type": "object", + "description": "An single item that's placed on multiple items on the timeline.", + "properties": { + "text": { + "description": "The text of the entry. This would be the display\nname for an item being placed on the timeline, for example the name\nof the person who was detected in a video.", + "type": "string", + "example": "John" + }, + "appears": { + "description": "Defines a list of timestamps for when this item should appear on the\ntimeline.", + "type": "array", + "items": { + "type": "object", + "description": "The timestamp for an entry.", + "properties": { + "start": { + "description": "The time in seconds when an\nentry should start appearing on a timeline.", + "type": "integer", + "example": 1 + }, + "end": { + "description": "The time in seconds when an\nentry should stop appearing on a timeline.", + "type": "integer", + "example": 20 + } + } + }, + "required": [ + "start", + "end" + ] + }, + "image_url": { + "description": "The image to show on a for an entry that appears\non a timeline. This image URL is required for every entry.\n\nThe image will be shown in a\nlist of items (for example faces), and clicking\nthe image will show the user where that entry\nappears during the duration of this entry.", + "type": "string", + "example": "https://example.com/image1.jpg" + } + } + } + } + }, + "required": [ + "type", + "skill_card_type", + "skill", + "invocation", + "entries" + ], + "title": "Timeline Skill Card", + "x-box-resource-id": "timeline_skill_card", + "x-box-tag": "skills" + }, + "TrackingCode": { + "description": "Tracking codes allow an admin to generate reports from the admin console\nand assign an attribute to a specific group of users.\nThis setting must be enabled for an enterprise before it can be used.", + "type": "object", + "properties": { + "type": { + "description": "`tracking_code`", + "type": "string", + "example": "tracking_code", + "enum": [ + "tracking_code" + ] + }, + "name": { + "description": "The name of the tracking code, which must be preconfigured in\nthe Admin Console", + "type": "string", + "example": "department" + }, + "value": { + "description": "The value of the tracking code", + "type": "string", + "example": "Sales" + } + }, + "title": "Tracking code" + }, + "TranscriptSkillCard": { + "description": "A Box Skill metadata card that adds a transcript to a file.", + "type": "object", + "properties": { + "created_at": { + "description": "The optional date and time this card was created at.", + "type": "string", + "format": "date-time", + "example": "2018-04-13T13:53:23-07:00" + }, + "type": { + "description": "`skill_card`", + "type": "string", + "example": "skill_card", + "enum": [ + "skill_card" + ] + }, + "skill_card_type": { + "description": "`transcript`", + "type": "string", + "example": "transcript", + "enum": [ + "transcript" + ] + }, + "skill_card_title": { + "description": "The title of the card.", + "type": "object", + "properties": { + "code": { + "description": "An optional identifier for the title.", + "type": "string", + "example": "my_transcripts" + }, + "message": { + "description": "The actual title to show in the UI.", + "type": "string", + "example": "My Transcripts" + } + }, + "required": [ + "message" + ] + }, + "skill": { + "description": "The service that applied this metadata.", + "type": "object", + "properties": { + "type": { + "description": "`service`", + "type": "string", + "example": "service", + "enum": [ + "service" + ] + }, + "id": { + "description": "A custom identifier that represent the service that\napplied this metadata.", + "type": "string", + "example": "transciption-service" + } + }, + "required": [ + "type", + "id" + ] + }, + "invocation": { + "description": "The invocation of this service, used to track\nwhich instance of a service applied the metadata.", + "type": "object", + "properties": { + "type": { + "description": "`skill_invocation`", + "type": "string", + "example": "skill_invocation", + "enum": [ + "skill_invocation" + ] + }, + "id": { + "description": "A custom identifier that represent the instance of\nthe service that applied this metadata. For example,\nif your `image-recognition-service` runs on multiple\nnodes, this field can be used to identify the ID of\nthe node that was used to apply the metadata.", + "type": "string", + "example": "transciption-service-123" + } + }, + "required": [ + "type", + "id" + ] + }, + "duration": { + "description": "An optional total duration in seconds.\n\nUsed with a `skill_card_type` of `transcript` or\n`timeline`.", + "type": "integer", + "example": 1000 + }, + "entries": { + "description": "An list of entries for the card. This represents the individual entries of\nthe transcription.", + "type": "array", + "items": { + "type": "object", + "description": "An entry in the `entries` attribute of a metadata card", + "properties": { + "text": { + "description": "The text of the entry. This would be the transcribed text assigned\nto the entry on the timeline.", + "type": "string", + "example": "Hi, and welcome to this video..." + }, + "appears": { + "description": "Defines when a transcribed bit of text appears. This only includes a\nstart time and no end time.", + "type": "array", + "items": { + "type": "object", + "description": "The timestamp for an entry.", + "properties": { + "start": { + "description": "The time in seconds when an\nentry should start appearing on a timeline.", + "type": "integer", + "example": 1 + } + } + }, + "required": [ + "start" + ] + } + } + } + } + }, + "required": [ + "type", + "skill_card_type", + "skill", + "invocation", + "entries" + ], + "title": "Transcript Skill Card", + "x-box-resource-id": "transcript_skill_card", + "x-box-tag": "skills" + }, + "TrashFile": { + "description": "Represents a trashed file.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier that represent 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`.", + "type": "string", + "example": "123456789", + "nullable": false + }, + "etag": { + "description": "The HTTP `etag` of this file. This can be used within some API\nendpoints in the `If-Match` and `If-None-Match` headers to only\nperform changes on the file if (no) changes have happened.", + "type": "string", + "example": "1", + "nullable": true + }, + "type": { + "description": "`file`", + "type": "string", + "example": "file", + "enum": [ + "file" + ], + "nullable": false + }, + "sequence_id": { + "allOf": [ + { + "type": "string", + "example": "3", + "nullable": true, + "description": "A numeric identifier that represents the most recent user event\nthat has been applied to this item.\n\nThis can be used in combination with the `GET /events`-endpoint\nto filter out user events that would have occurred before this\nidentifier was read.\n\nAn example would be where a Box Drive-like application\nwould fetch an item via the API, and then listen to incoming\nuser events for changes to the item. The application would\nignore any user events where the `sequence_id` in the event\nis smaller than or equal to the `sequence_id` in the originally\nfetched resource." + }, + { + "nullable": false + } + ] + }, + "name": { + "description": "The name of the file", + "type": "string", + "example": "Contract.pdf" + }, + "sha1": { + "description": "The SHA1 hash of the file. This can be used to compare the contents\nof a file on Box with a local file.", + "type": "string", + "format": "digest", + "example": "85136C79CBF9FE36BB9D05D0639C70C265C18D37", + "nullable": false + }, + "file_version": { + "allOf": [ + { + "$ref": "#/components/schemas/FileVersion--Mini" + }, + { + "description": "The information about the current version of the file." + } + ] + }, + "description": { + "description": "The optional description of this file", + "type": "string", + "example": "Contract for Q1 renewal", + "maxLength": 256, + "nullable": false + }, + "size": { + "description": "The file size in bytes. Be careful parsing this integer as it can\nget very large and cause an integer overflow.", "type": "integer", - "format": "int64", - "description": "The folder size in bytes.\n\nBe careful parsing this integer as its\nvalue can get very large.", "example": 629644, "nullable": false }, "path_collection": { "allOf": [ { - "title": "Path collection", - "description": "A list of parent folders for an item.", + "title": "Path collection (Trash)", + "description": "A list of parent folders for an item in the trash.", "type": "object", "required": [ "total_count", @@ -35408,17 +36272,50 @@ "properties": { "total_count": { "description": "The number of folders in this list.", - "example": 1, "type": "integer", "format": "int64", + "example": 1, "nullable": false }, "entries": { + "description": "Array of folders for this item's path collection", "type": "array", - "description": "The parent folders for this item", - "nullable": false, "items": { - "$ref": "#/components/schemas/Folder--Mini" + "type": "object", + "description": "The parent folder for this item", + "properties": { + "type": { + "description": "`folder`", + "type": "string", + "example": "folder", + "enum": [ + "folder" + ] + }, + "id": { + "description": "The unique identifier that represent a folder.", + "type": "string", + "example": "123456789" + }, + "sequence_id": { + "description": "This field is null for the Trash folder", + "type": "string", + "example": null, + "nullable": true + }, + "etag": { + "description": "This field is null for the Trash folder", + "type": "string", + "example": null, + "nullable": true + }, + "name": { + "description": "The name of the Trash folder.", + "type": "string", + "example": "Trash", + "nullable": false + } + } } } } @@ -35431,16 +36328,55 @@ } ] }, + "created_at": { + "description": "The date and time when the file was created on Box.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": false + }, + "modified_at": { + "description": "The date and time when the file was last updated on Box.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": false + }, + "trashed_at": { + "description": "The time at which this file was put in the trash.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "purged_at": { + "description": "The time at which this file is expected to be purged\nfrom the trash.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "content_created_at": { + "description": "The date and time at which this file was originally\ncreated, which might be before it was uploaded to Box.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "content_modified_at": { + "description": "The date and time at which this file was last updated,\nwhich might be before it was uploaded to Box.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { - "description": "The user who created this folder" - }, - { - "nullable": false + "description": "The user who created this file" } ] }, @@ -35450,46 +36386,20 @@ "$ref": "#/components/schemas/User--Mini" }, { - "description": "The user who last modified this folder." + "description": "The user who last modified this file" }, { "nullable": false } ] }, - "trashed_at": { - "type": "string", - "description": "The time at which this folder was put in the\ntrash - becomes `null` after restore.", - "example": null, - "nullable": true - }, - "purged_at": { - "type": "string", - "description": "The time at which this folder is expected to be purged\nfrom the trash - becomes `null` after restore.", - "example": null, - "nullable": true - }, - "content_created_at": { - "type": "string", - "format": "date-time", - "nullable": true, - "description": "The date and time at which this folder was originally\ncreated.", - "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 folder was last updated.", - "example": "2012-12-12T10:53:43-08:00" - }, "owned_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { - "description": "The user who owns this folder." + "description": "The user who owns this file" }, { "nullable": false @@ -35497,14 +36407,8 @@ ] }, "shared_link": { + "description": "The shared link for this file. This will\nbe `null` if a file has been trashed, since the link will no longer\nbe active.", "type": "string", - "description": "The shared link for this file. This will\nbe `null` if a folder had been trashed, even though the original shared\nlink does become active again.", - "example": null, - "nullable": true - }, - "folder_upload_email": { - "type": "string", - "description": "The folder upload email for this folder. This will\nbe `null` if a folder has been trashed, even though the original upload\nemail does become active again.", "example": null, "nullable": true }, @@ -35514,7 +36418,7 @@ "$ref": "#/components/schemas/Folder--Mini" }, { - "description": "The optional folder that this folder is located within.\n\nThis value may be `null` for some folders such as the\nroot folder or the trash folder." + "description": "The folder that this file is located within." }, { "nullable": true @@ -35522,41 +36426,59 @@ ] }, "item_status": { - "type": "string", "description": "Defines if this item has been deleted or not.\n\n* `active` when the item has is not in the trash\n* `trashed` when the item has been moved to the trash but not deleted\n* `deleted` when the item has been permanently deleted.", + "type": "string", + "example": "trashed", "enum": [ "active", "trashed", "deleted" ], - "nullable": false, - "example": "active" + "nullable": false } - } - }, - "TrashWebLinkRestored": { - "title": "Trashed Web Link (Restored)", - "type": "object", - "x-box-resource-id": "trash_web_link_restored", - "x-box-tag": "trashed_web_links", - "description": "Represents a web link restored from the trash.", + }, "required": [ + "id", + "type", "sequence_id", - "path_collection" + "sha1", + "description", + "size", + "path_collection", + "created_at", + "modified_at", + "modified_by", + "owned_by", + "item_status" ], + "title": "Trashed File", + "x-box-resource-id": "trash_file", + "x-box-tag": "trashed_files" + }, + "TrashFileRestored": { + "description": "Represents a file restored from the trash.", + "type": "object", "properties": { - "type": { + "id": { + "description": "The unique identifier that represent 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`.", "type": "string", - "description": "`web_link`", - "example": "web_link", - "enum": [ - "web_link" - ] + "example": "123456789", + "nullable": false }, - "id": { + "etag": { + "description": "The HTTP `etag` of this file. This can be used within some API\nendpoints in the `If-Match` and `If-None-Match` headers to only\nperform changes on the file if (no) changes have happened.", "type": "string", - "description": "The unique identifier for this web link", - "example": "11446498" + "example": "1", + "nullable": true + }, + "type": { + "description": "`file`", + "type": "string", + "example": "file", + "enum": [ + "file" + ], + "nullable": false }, "sequence_id": { "allOf": [ @@ -35571,35 +36493,40 @@ } ] }, - "etag": { - "type": "string", - "example": "1", - "description": "The entity tag of this web link. Used with `If-Match`\nheaders." - }, "name": { + "description": "The name of the file", "type": "string", - "description": "The name of the web link", - "example": "My Bookmark" + "example": "Contract.pdf" }, - "url": { + "sha1": { + "description": "The SHA1 hash of the file. This can be used to compare the contents\nof a file on Box with a local file.", "type": "string", - "example": "https://www.example.com/example/1234", - "description": "The URL this web link points to" + "format": "digest", + "example": "85136C79CBF9FE36BB9D05D0639C70C265C18D37", + "nullable": false }, - "parent": { + "file_version": { "allOf": [ { - "$ref": "#/components/schemas/Folder--Mini" + "$ref": "#/components/schemas/FileVersion--Mini" }, { - "description": "The parent object the web link belongs to" + "description": "The information about the current version of the file." } ] }, "description": { + "description": "The optional description of this file", "type": "string", - "example": "Example page", - "description": "The description accompanying the web link. This is\nvisible within the Box web application." + "example": "Contract for Q1 renewal", + "maxLength": 256, + "nullable": false + }, + "size": { + "description": "The file size in bytes. Be careful parsing this integer as it can\nget very large and cause an integer overflow.", + "type": "integer", + "example": 629644, + "nullable": false }, "path_collection": { "allOf": [ @@ -35614,23 +36541,23 @@ "properties": { "total_count": { "description": "The number of folders in this list.", - "example": 1, "type": "integer", "format": "int64", + "example": 1, "nullable": false }, "entries": { - "type": "array", "description": "The parent folders for this item", - "nullable": false, + "type": "array", "items": { "$ref": "#/components/schemas/Folder--Mini" - } + }, + "nullable": false } } }, { - "description": "The tree of folders that this web link is contained in,\nstarting at the root." + "description": "The tree of folders that this file is contained in,\nstarting at the root." }, { "nullable": false @@ -35638,36 +36565,52 @@ ] }, "created_at": { + "description": "The date and time when the file was created on Box.", "type": "string", "format": "date-time", - "description": "When this file was created on Box’s servers.", - "example": "2012-12-12T10:53:43-08:00" + "example": "2012-12-12T10:53:43-08:00", + "nullable": false }, "modified_at": { + "description": "The date and time when the file was last updated on Box.", "type": "string", "format": "date-time", - "description": "When this file was last updated on the Box\nservers.", - "example": "2012-12-12T10:53:43-08:00" + "example": "2012-12-12T10:53:43-08:00", + "nullable": false }, "trashed_at": { + "description": "The time at which this file was put in the\ntrash - becomes `null` after restore.", "type": "string", - "nullable": true, - "description": "The time at which this bookmark was put in the\ntrash - becomes `null` after restore.", - "example": null + "example": null, + "nullable": true }, "purged_at": { + "description": "The time at which this file is expected to be purged\nfrom the trash - becomes `null` after restore.", "type": "string", - "nullable": true, - "description": "The time at which this bookmark will be permanently\ndeleted - becomes `null` after restore.", - "example": null + "example": null, + "nullable": true }, - "created_by": { - "allOf": [ - { + "content_created_at": { + "description": "The date and time at which this file was originally\ncreated, which might be before it was uploaded to Box.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "content_modified_at": { + "description": "The date and time at which this file was last updated,\nwhich might be before it was uploaded to Box.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "created_by": { + "allOf": [ + { "$ref": "#/components/schemas/User--Mini" }, { - "description": "The user who created this web link" + "description": "The user who created this file" } ] }, @@ -35677,7 +36620,10 @@ "$ref": "#/components/schemas/User--Mini" }, { - "description": "The user who last modified this web link" + "description": "The user who last modified this file" + }, + { + "nullable": false } ] }, @@ -35687,1044 +36633,1761 @@ "$ref": "#/components/schemas/User--Mini" }, { - "description": "The user who owns this web link" + "description": "The user who owns this file" + }, + { + "nullable": false } ] }, "shared_link": { + "description": "The shared link for this file. This will\nbe `null` if a file had been trashed, even though the original shared\nlink does become active again.", "type": "string", - "description": "The shared link for this bookmark. This will\nbe `null` if a bookmark had been trashed, even though the original shared\nlink does become active again.", - "nullable": true, - "example": null + "example": null, + "nullable": true + }, + "parent": { + "allOf": [ + { + "$ref": "#/components/schemas/Folder--Mini" + }, + { + "description": "The folder that this file is located within." + }, + { + "nullable": true + } + ] }, "item_status": { + "description": "Defines if this item has been deleted or not.\n\n* `active` when the item has is not in the trash\n* `trashed` when the item has been moved to the trash but not deleted\n* `deleted` when the item has been permanently deleted.", "type": "string", - "example": "trashed", + "example": "active", "enum": [ "active", "trashed", "deleted" ], - "description": "Whether this item is deleted or not. Values include `active`,\n`trashed` if the file has been moved to the trash, and `deleted` if\nthe file has been permanently deleted" + "nullable": false } - } + }, + "required": [ + "id", + "type", + "sequence_id", + "sha1", + "description", + "size", + "path_collection", + "created_at", + "modified_at", + "modified_by", + "owned_by", + "item_status" + ], + "title": "Trashed File (Restored)", + "x-box-resource-id": "trash_file_restored", + "x-box-tag": "trashed_files" }, - "UploadPart": { - "title": "Upload part", + "TrashFolder": { + "description": "Represents a trashed folder.", "type": "object", - "x-box-resource-id": "upload_part", - "x-box-variant": "standard", - "description": "The representation of an upload\nsession chunk.", - "allOf": [ - { - "$ref": "#/components/schemas/UploadPart--Mini" + "properties": { + "id": { + "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting a folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folders/123`\nthe `folder_id` is `123`.", + "type": "string", + "example": "123456789", + "nullable": false }, - { - "properties": { - "sha1": { - "description": "The SHA1 hash of the chunk.", + "etag": { + "description": "The HTTP `etag` of this folder. This can be used within some API\nendpoints in the `If-Match` and `If-None-Match` headers to only\nperform changes on the folder if (no) changes have happened.", + "type": "string", + "example": "1", + "nullable": true + }, + "type": { + "description": "`folder`", + "type": "string", + "example": "folder", + "enum": [ + "folder" + ], + "nullable": false + }, + "sequence_id": { + "allOf": [ + { "type": "string", - "example": "134b65991ed521fcfe4724b7d814ab8ded5185dc" + "example": "3", + "nullable": true, + "description": "A numeric identifier that represents the most recent user event\nthat has been applied to this item.\n\nThis can be used in combination with the `GET /events`-endpoint\nto filter out user events that would have occurred before this\nidentifier was read.\n\nAn example would be where a Box Drive-like application\nwould fetch an item via the API, and then listen to incoming\nuser events for changes to the item. The application would\nignore any user events where the `sequence_id` in the event\nis smaller than or equal to the `sequence_id` in the originally\nfetched resource." + }, + { + "nullable": false } - } - } - ] - }, - "UploadPart--Mini": { - "title": "Upload part (Mini)", - "type": "object", - "x-box-resource-id": "upload_part--mini", - "x-box-tag": "chunked_uploads", - "x-box-variants": [ - "mini", - "standard" - ], - "x-box-variant": "mini", - "description": "The basic representation of an upload\nsession chunk.", - "properties": { - "part_id": { - "description": "The unique ID of the chunk.", + ] + }, + "name": { + "description": "The name of the folder.", "type": "string", - "example": "6F2D3486" + "example": "Contracts", + "nullable": false }, - "offset": { - "description": "The offset of the chunk within the file\nin bytes. The lower bound of the position\nof the chunk within the file.", - "type": "integer", - "format": "int64", - "example": 16777216 + "created_at": { + "description": "The date and time when the folder was created. This value may\nbe `null` for some folders such as the root folder or the trash\nfolder.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "modified_at": { + "description": "The date and time when the folder was last updated. This value may\nbe `null` for some folders such as the root folder or the trash\nfolder.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "description": { + "allOf": [ + { + "type": "string", + "description": "The optional description of this folder", + "maxLength": 256, + "example": "Legal contracts for the new ACME deal", + "nullable": false + }, + { + "nullable": false + } + ] }, "size": { - "description": "The size of the chunk in bytes.", + "description": "The folder size in bytes.\n\nBe careful parsing this integer as its\nvalue can get very large.", "type": "integer", "format": "int64", - "example": 3222784 - } - } - }, - "UploadedPart": { - "title": "Uploaded part", - "type": "object", - "x-box-resource-id": "uploaded_part", - "description": "A chunk of a file uploaded as part of\nan upload session, as returned by some endpoints.", - "x-box-tag": "chunked_uploads", - "properties": { - "part": { - "$ref": "#/components/schemas/UploadPart" - } - } - }, - "UploadParts": { - "title": "Upload parts", - "type": "object", - "x-box-resource-id": "upload_parts", - "x-box-tag": "chunked_uploads", - "description": "A list of uploaded chunks for an upload\nsession.", - "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" - ] + "example": 629644, + "nullable": false + }, + "path_collection": { + "allOf": [ + { + "title": "Path collection (Trash)", + "description": "A list of parent folders for an item in the trash.", + "type": "object", + "required": [ + "total_count", + "entries" + ], + "properties": { + "total_count": { + "description": "The number of folders in this list.", + "type": "integer", + "format": "int64", + "example": 1, + "nullable": false + }, + "entries": { + "description": "Array of folders for this item's path collection", + "type": "array", + "items": { + "type": "object", + "description": "The parent folder for this item", + "properties": { + "type": { + "description": "`folder`", + "type": "string", + "example": "folder", + "enum": [ + "folder" + ] + }, + "id": { + "description": "The unique identifier that represent a folder.", + "type": "string", + "example": "123456789" + }, + "sequence_id": { + "description": "This field is null for the Trash folder", + "type": "string", + "example": null, + "nullable": true + }, + "etag": { + "description": "This field is null for the Trash folder", + "type": "string", + "example": null, + "nullable": true + }, + "name": { + "description": "The name of the Trash folder.", + "type": "string", + "example": "Trash", + "nullable": false + } + } } } } + }, + { + "description": "The tree of folders that this file is contained in,\nstarting at the root." + }, + { + "nullable": false } - } + ] }, - { - "properties": { - "entries": { - "type": "array", - "description": "A list of uploaded chunks for an upload\nsession", - "items": { - "$ref": "#/components/schemas/UploadPart" - } + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who created this folder" + }, + { + "nullable": false } - } - } - ] - }, - "UploadSession": { - "title": "Upload session", - "type": "object", - "x-box-resource-id": "upload_session", - "description": "An upload session for chunk uploading a file.", - "x-box-tag": "chunked_uploads", - "properties": { - "id": { + ] + }, + "modified_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who last modified this folder." + }, + { + "nullable": false + } + ] + }, + "trashed_at": { + "description": "The time at which this folder was put in the trash.", "type": "string", - "description": "The unique identifier for this session", - "example": "F971964745A5CD0C001BBE4E58196BFD" + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true }, - "type": { + "purged_at": { + "description": "The time at which this folder is expected to be purged\nfrom the trash.", "type": "string", - "description": "`upload_session`", - "example": "upload_session", - "enum": [ - "upload_session" - ] + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true }, - "session_expires_at": { - "description": "The date and time when this session expires.", + "content_created_at": { + "description": "The date and time at which this folder was originally\ncreated.", "type": "string", "format": "date-time", - "example": "2012-12-12T10:53:43-08:00" + "example": "2012-12-12T10:53:43-08:00", + "nullable": true }, - "part_size": { - "type": "integer", - "format": "int64", - "example": 1024, - "description": "The size in bytes that must be used for all parts of of the\nupload.\n\nOnly the last part is allowed to be of a smaller size." + "content_modified_at": { + "description": "The date and time at which this folder was last updated.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true }, - "total_parts": { - "type": "integer", - "format": "int32", - "example": 1000, - "description": "The total number of parts expected in this upload session,\nas determined by the file size and part size." + "owned_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who owns this folder." + }, + { + "nullable": false + } + ] }, - "num_parts_processed": { - "type": "integer", - "format": "int32", - "example": 455, - "description": "The number of parts that have been uploaded and processed\nby the server. This starts at `0`.\n\nWhen committing a file files, inspecting this property can\nprovide insight if all parts have been uploaded correctly." + "shared_link": { + "description": "The shared link for this folder. This will\nbe `null` if a folder has been trashed, since the link will no longer\nbe active.", + "type": "string", + "example": null, + "nullable": true }, - "session_endpoints": { + "folder_upload_email": { + "description": "The folder upload email for this folder. This will\nbe `null` if a folder has been trashed, since the upload will no longer\nwork.", + "type": "string", + "example": null, + "nullable": true + }, + "parent": { "allOf": [ { - "title": "Session endpoints", - "description": "A list of endpoints for a chunked upload session.", - "type": "object", - "properties": { - "upload_part": { - "type": "string", - "description": "The URL to upload parts to", - "example": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD" - }, - "commit": { - "type": "string", - "description": "The URL used to commit the file", - "example": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/commit" - }, - "abort": { - "type": "string", - "description": "The URL for used to abort the session.", - "example": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD" - }, - "list_parts": { - "type": "string", - "description": "The URL users to list all parts.", - "example": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/parts" - }, - "status": { - "type": "string", - "description": "The URL used to get the status of the upload.", - "example": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD" - }, - "log_event": { - "type": "string", - "description": "The URL used to get the upload log from.", - "example": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/log" - } - } + "$ref": "#/components/schemas/Folder--Mini" }, { - "description": "A list of endpoints for this session." + "description": "The optional folder that this folder is located within.\n\nThis value may be `null` for some folders such as the\nroot folder or the trash folder." + }, + { + "nullable": true } ] + }, + "item_status": { + "description": "Defines if this item has been deleted or not.\n\n* `active` when the item has is not in the trash\n* `trashed` when the item has been moved to the trash but not deleted\n* `deleted` when the item has been permanently deleted.", + "type": "string", + "example": "trashed", + "enum": [ + "active", + "trashed", + "deleted" + ], + "nullable": false } - } + }, + "required": [ + "id", + "type", + "name", + "description", + "size", + "path_collection", + "created_by", + "modified_by", + "owned_by", + "item_status" + ], + "title": "Trashed Folder", + "x-box-resource-id": "trash_folder", + "x-box-tag": "trashed_folders" }, - "UploadUrl": { - "title": "Upload URL", + "TrashFolderRestored": { + "description": "Represents a folder restored from the trash.", "type": "object", - "x-box-resource-id": "upload_url", - "x-box-tag": "uploads", - "description": "The details for the upload session for the file.", "properties": { - "upload_url": { + "id": { + "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting a folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folders/123`\nthe `folder_id` is `123`.", "type": "string", - "example": "https://upload-las.app.box.com/api/2.0/files/content?upload_session_id=1234", - "description": "A URL for an upload session that can be used to upload\nthe file." + "example": "123456789", + "nullable": false }, - "upload_token": { + "etag": { + "description": "The HTTP `etag` of this folder. This can be used within some API\nendpoints in the `If-Match` and `If-None-Match` headers to only\nperform changes on the folder if (no) changes have happened.", "type": "string", - "example": "Pc3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQP", - "description": "An optional access token to use to upload the file" - } - } - }, - "User": { - "title": "User", - "type": "object", - "x-box-resource-id": "user", - "x-box-variant": "standard", - "description": "A standard representation of a user, as returned from any\nuser API endpoints by default", - "allOf": [ - { - "$ref": "#/components/schemas/User--Mini" + "example": "1", + "nullable": true }, - { - "properties": { - "created_at": { - "type": "string", - "format": "date-time", - "description": "When the user object was created", - "example": "2012-12-12T10:53:43-08:00" - }, - "modified_at": { - "type": "string", - "format": "date-time", - "description": "When the user object was last modified", - "example": "2012-12-12T10:53:43-08:00" - }, - "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" - }, - "timezone": { - "type": "string", - "format": "timezone", - "description": "The user's timezone", - "example": "Africa/Bujumbura" - }, - "space_amount": { - "type": "integer", - "format": "int64", - "description": "The user’s total available space amount in bytes", - "example": 11345156112 - }, - "space_used": { - "type": "integer", - "format": "int64", - "description": "The amount of space in use by the user", - "example": 1237009912 - }, - "max_upload_size": { - "type": "integer", - "format": "int64", - "description": "The maximum individual file size in bytes the user can have", - "example": 2147483648 - }, - "status": { - "type": "string", - "enum": [ - "active", - "inactive", - "cannot_delete_edit", - "cannot_delete_edit_upload" - ], - "description": "The user's account status", - "example": "active" - }, - "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": { + "description": "`folder`", + "type": "string", + "example": "folder", + "enum": [ + "folder" + ], + "nullable": false + }, + "sequence_id": { + "allOf": [ + { "type": "string", - "description": "The user’s address", - "maxLength": 255, - "example": "900 Jefferson Ave, Redwood City, CA 94063" + "example": "3", + "nullable": true, + "description": "A numeric identifier that represents the most recent user event\nthat has been applied to this item.\n\nThis can be used in combination with the `GET /events`-endpoint\nto filter out user events that would have occurred before this\nidentifier was read.\n\nAn example would be where a Box Drive-like application\nwould fetch an item via the API, and then listen to incoming\nuser events for changes to the item. The application would\nignore any user events where the `sequence_id` in the event\nis smaller than or equal to the `sequence_id` in the originally\nfetched resource." }, - "avatar_url": { + { + "nullable": false + } + ] + }, + "name": { + "description": "The name of the folder.", + "type": "string", + "example": "Contracts", + "nullable": false + }, + "created_at": { + "description": "The date and time when the folder was created. This value may\nbe `null` for some folders such as the root folder or the trash\nfolder.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "modified_at": { + "description": "The date and time when the folder was last updated. This value may\nbe `null` for some folders such as the root folder or the trash\nfolder.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "description": { + "allOf": [ + { "type": "string", - "description": "URL of the user’s avatar image", - "example": "https://www.box.com/api/avatar/large/181216415" + "description": "The optional description of this folder", + "maxLength": 256, + "example": "Legal contracts for the new ACME deal", + "nullable": false }, - "notification_email": { + { + "nullable": false + } + ] + }, + "size": { + "description": "The folder size in bytes.\n\nBe careful parsing this integer as its\nvalue can get very large.", + "type": "integer", + "format": "int64", + "example": 629644, + "nullable": false + }, + "path_collection": { + "allOf": [ + { + "title": "Path collection", + "description": "A list of parent folders for an item.", "type": "object", - "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.", - "nullable": true, + "required": [ + "total_count", + "entries" + ], "properties": { - "email": { - "type": "string", - "example": "notifications@example.com", - "description": "The email address to send the notifications to." + "total_count": { + "description": "The number of folders in this list.", + "type": "integer", + "format": "int64", + "example": 1, + "nullable": false }, - "is_confirmed": { - "type": "boolean", - "example": true, - "description": "Specifies if this email address has been confirmed." + "entries": { + "description": "The parent folders for this item", + "type": "array", + "items": { + "$ref": "#/components/schemas/Folder--Mini" + }, + "nullable": false } } - } - } - } - ] - }, - "UserAvatar": { - "title": "User avatar", - "type": "object", - "x-box-resource-id": "user_avatar", - "x-box-tag": "avatars", - "description": "A resource holding URLs to the\navatar uploaded to a Box application.", - "properties": { - "pic_urls": { - "type": "object", - "description": "Represents an object with user avatar URLs.", - "properties": { - "small": { - "type": "string", - "description": "The location of a small-sized avatar.", - "example": "https://app.box.com/index.php?rm=pic_storage_auth&pic=euks! pac3kv01!7B6R5cZLmurEV_xB-KkycPk8Oi7oENUX2O_qUtIuO4342CG IldyCto9hqiQP7uxqYU5V2w63Ft4ln4UVVLDtDZu903OqzkflY2O-Lq00 ubA29xU-RJ6b_KzJEWRYgUhX1zEl3dzWo12g8eWRE2rStf123DF7AYahNqM 1BmLmviL_nODc7SDQHedTXPAjxURUAra5BvtLe7B05AizbNXdPlCNp-LNh _S-eZ_RjDXcGO-MkRWd_3BOMHnvjf450t5BfKoJ15WhEfiMlfXH1tmouHXrsC 66cT6-pzF9E40Iir_zThqSlrFxzP_xcmXzHapr_k-0E2qr2TXp4iC396TSlEw\n" }, - "large": { - "type": "string", - "description": "The location of a large-sized avatar.", - "example": "https://app.box.com/index.php?rm=pic_storage_auth&pic=euks\npac3kv01!lipGQlQQOtCTCoB6zCOArUjVWLFJtLr5tn6aOZMCybhRx0NNuFQbVI36nw\njtEk5YjUUz1KVdVuvU2yDhu_ftK_bvxeKP1Ffrx9vKGVvJ-UJc1z32p6n2CmFzzpc\ngSoX4pnPhFgydAL-u9jDspXUGElr-htDG_HPMiE9DZjqDueOxXHy8xe22wbaPAheC\nao1emv8r_fmufaUgSndeMYmyZj-KqOYsLBrBNgdeiK5tZmPOQggAEUmyQPkrd8W92TQ6sSlIp0r" + { + "description": "The tree of folders that this file is contained in,\nstarting at the root." }, - "preview": { - "type": "string", - "description": "The location of the avatar preview.", - "example": "https://app.box.com/index.php?rm=pic_storage_auth&pic=euks!\npac3kv01!8UcNPweOOAWj2DtHk_dCQB4wJpzyPkl7mT5nHj5ZdjY92ejYCBBZc95--403b29CW\nk-8hSo_uBjh5h9QG42Ihu-cOZ-816sej1kof3SOm5gjn7qjMAx89cHjUaNK-6XasRqSNboenjZ\n04laZuV9vSH12BZGAYycIZvvQ5R66Go8xG5GTMARf2nBU84c4H_SL5iws-HeBS4oQJWOJh6FBl\nsSJDSTI74LGXqeZb3EY_As34VFC95F10uozoTOSubZmPYylPlaKXoKWk2f9wYQso1ZTN7sh-Gc\n9Kp43zMLhArIWhok0Im6FlRAuWOQ03KYgL-k4L5EZp4Gw6B7uqVRwcBbsTwMIorWq1g" + { + "nullable": false } - } - } - } - }, - "Users": { - "title": "Users", - "type": "object", - "x-box-resource-id": "users", - "x-box-tag": "users", - "description": "A list of users.", - "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" + ] + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" }, - "next_marker": { - "description": "The marker for the start of the next page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", - "type": "string", - "nullable": true + { + "description": "The user who created this folder" }, - "prev_marker": { - "description": "The marker for the start of the previous page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", - "type": "string", - "nullable": true + { + "nullable": false } - } + ] }, - { - "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" + "modified_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" }, - "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" + { + "description": "The user who last modified this folder." }, - "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" - ] - } - } - } + { + "nullable": false } - } + ] }, - { - "properties": { - "entries": { - "type": "array", - "description": "A list of users", - "items": { - "$ref": "#/components/schemas/User--Full" - } - } - } - } - ] - }, - "User--Full": { - "title": "User (Full)", - "type": "object", - "x-box-resource-id": "user--full", - "x-box-variant": "full", - "description": "A full representation of a user, as can be returned from any\nuser API endpoint.", - "allOf": [ - { - "$ref": "#/components/schemas/User" + "trashed_at": { + "description": "The time at which this folder was put in the\ntrash - becomes `null` after restore.", + "type": "string", + "example": null, + "nullable": true }, - { - "properties": { - "role": { - "type": "string", - "enum": [ - "admin", - "coadmin", - "user" - ], - "description": "The user’s enterprise role", - "example": "admin" - }, - "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\nbefore it can be used." - }, - "can_see_managed_users": { - "type": "boolean", - "example": true, - "description": "Whether the user can see other enterprise users in their contact list" - }, - "is_sync_enabled": { - "type": "boolean", - "description": "Whether the user can use Box Sync", - "example": true - }, - "is_external_collab_restricted": { - "type": "boolean", - "example": true, - "description": "Whether the user is allowed to collaborate with users outside their\nenterprise" - }, - "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" - }, - "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": "Representation of the user’s enterprise" - } - ] + "purged_at": { + "description": "The time at which this folder is expected to be purged\nfrom the trash - becomes `null` after restore.", + "type": "string", + "example": null, + "nullable": true + }, + "content_created_at": { + "description": "The date and time at which this folder was originally\ncreated.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "content_modified_at": { + "description": "The date and time at which this folder was last updated.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "owned_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" }, - "my_tags": { - "type": "array", - "items": { - "type": "string" - }, - "example": [ - "important" - ], - "description": "Tags for all files and folders owned by the user. Values returned\nwill only contain tags that were set by the requester." + { + "description": "The user who owns this folder." }, - "hostname": { - "type": "string", - "example": "https://example.app.box.com/", - "description": "The root (protocol, subdomain, domain) of any links that need to be\ngenerated for the user" + { + "nullable": false + } + ] + }, + "shared_link": { + "description": "The shared link for this file. This will\nbe `null` if a folder had been trashed, even though the original shared\nlink does become active again.", + "type": "string", + "example": null, + "nullable": true + }, + "folder_upload_email": { + "description": "The folder upload email for this folder. This will\nbe `null` if a folder has been trashed, even though the original upload\nemail does become active again.", + "type": "string", + "example": null, + "nullable": true + }, + "parent": { + "allOf": [ + { + "$ref": "#/components/schemas/Folder--Mini" }, - "is_platform_access_only": { - "type": "boolean", - "example": true, - "description": "Whether the user is an App User" + { + "description": "The optional folder that this folder is located within.\n\nThis value may be `null` for some folders such as the\nroot folder or the trash folder." }, - "external_app_user_id": { - "type": "string", - "example": "my-user-1234", - "description": "An external identifier for an app user, which can be used to look up\nthe user. This can be used to tie user IDs from external identity\nproviders to Box users." + { + "nullable": true } - } + ] + }, + "item_status": { + "description": "Defines if this item has been deleted or not.\n\n* `active` when the item has is not in the trash\n* `trashed` when the item has been moved to the trash but not deleted\n* `deleted` when the item has been permanently deleted.", + "type": "string", + "example": "active", + "enum": [ + "active", + "trashed", + "deleted" + ], + "nullable": false } - ] + }, + "title": "Trashed Folder (Restored)", + "x-box-resource-id": "trash_folder_restored", + "x-box-tag": "trashed_folders" }, - "User--Mini": { - "title": "User (Mini)", + "TrashWebLink": { + "description": "Represents a trashed web link.", "type": "object", - "x-box-resource-id": "user--mini", - "x-box-variant": "mini", - "description": "A mini representation of a user, as can be returned when nested within other\nresources.", - "allOf": [ - { - "$ref": "#/components/schemas/User--Base" + "properties": { + "type": { + "description": "`web_link`", + "type": "string", + "example": "web_link", + "enum": [ + "web_link" + ] }, - { - "properties": { - "name": { + "id": { + "description": "The unique identifier for this web link", + "type": "string", + "example": "11446498" + }, + "sequence_id": { + "allOf": [ + { "type": "string", - "description": "The display name of this user", - "example": "Aaron Levie", - "maxLength": 50, - "nullable": false + "example": "3", + "nullable": true, + "description": "A numeric identifier that represents the most recent user event\nthat has been applied to this item.\n\nThis can be used in combination with the `GET /events`-endpoint\nto filter out user events that would have occurred before this\nidentifier was read.\n\nAn example would be where a Box Drive-like application\nwould fetch an item via the API, and then listen to incoming\nuser events for changes to the item. The application would\nignore any user events where the `sequence_id` in the event\nis smaller than or equal to the `sequence_id` in the originally\nfetched resource." }, - "login": { - "type": "string", - "format": "email", - "description": "The primary email address of this user", - "example": "ceo@example.com", + { "nullable": false } - } - } - ] - }, - "User--Base": { - "title": "User (Base)", - "type": "object", - "x-box-resource-id": "user--base", - "x-box-tag": "users", - "x-box-variants": [ - "base", - "mini", - "standard", - "full" - ], - "x-box-variant": "base", - "description": "A mini representation of a user, used when\nnested within another resource.", - "required": [ - "type", - "id" - ], - "properties": { - "id": { + ] + }, + "etag": { + "description": "The entity tag of this web link. Used with `If-Match`\nheaders.", "type": "string", - "description": "The unique identifier for this user", - "example": "11446498" + "example": "1" }, - "type": { + "name": { + "description": "The name of the web link", "type": "string", - "description": "`user`", - "example": "user", - "nullable": false, + "example": "My Bookmark" + }, + "url": { + "description": "The URL this web link points to", + "type": "string", + "example": "https://www.example.com/example/1234" + }, + "parent": { + "allOf": [ + { + "$ref": "#/components/schemas/Folder--Mini" + }, + { + "description": "The parent object the web link belongs to" + } + ] + }, + "description": { + "description": "The description accompanying the web link. This is\nvisible within the Box web application.", + "type": "string", + "example": "Example page" + }, + "path_collection": { + "allOf": [ + { + "title": "Path collection (Trash)", + "description": "A list of parent folders for an item in the trash.", + "type": "object", + "required": [ + "total_count", + "entries" + ], + "properties": { + "total_count": { + "description": "The number of folders in this list.", + "type": "integer", + "format": "int64", + "example": 1, + "nullable": false + }, + "entries": { + "description": "Array of folders for this item's path collection", + "type": "array", + "items": { + "type": "object", + "description": "The parent folder for this item", + "properties": { + "type": { + "description": "`folder`", + "type": "string", + "example": "folder", + "enum": [ + "folder" + ] + }, + "id": { + "description": "The unique identifier that represent a folder.", + "type": "string", + "example": "123456789" + }, + "sequence_id": { + "description": "This field is null for the Trash folder", + "type": "string", + "example": null, + "nullable": true + }, + "etag": { + "description": "This field is null for the Trash folder", + "type": "string", + "example": null, + "nullable": true + }, + "name": { + "description": "The name of the Trash folder.", + "type": "string", + "example": "Trash", + "nullable": false + } + } + } + } + } + }, + { + "description": "The tree of folders that this web link is contained in,\nstarting at the root." + }, + { + "nullable": false + } + ] + }, + "created_at": { + "description": "When this file was created on Box’s servers.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "modified_at": { + "description": "When this file was last updated on the Box\nservers.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "trashed_at": { + "description": "When this file was last moved to the trash.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "purged_at": { + "description": "When this file will be permanently deleted.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who created this web link" + } + ] + }, + "modified_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who last modified this web link" + } + ] + }, + "owned_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who owns this web link" + } + ] + }, + "shared_link": { + "description": "The shared link for this bookmark. This will\nbe `null` if a bookmark has been trashed, since the link will no longer\nbe active.", + "type": "string", + "example": null, + "nullable": true + }, + "item_status": { + "description": "Whether this item is deleted or not. Values include `active`,\n`trashed` if the file has been moved to the trash, and `deleted` if\nthe file has been permanently deleted", + "type": "string", + "example": "trashed", "enum": [ - "user" + "active", + "trashed", + "deleted" ] } - } + }, + "title": "Trashed Web Link", + "x-box-resource-id": "trash_web_link", + "x-box-tag": "trashed_web_links" }, - "User--Collaborations": { - "title": "User (Collaborations)", + "TrashWebLinkRestored": { + "description": "Represents a web link restored from the trash.", "type": "object", - "x-box-resource-id": "user_collaborations", - "x-box-variant": "collaborations", - "description": "A mini representation of a user, can be returned only when\nthe status is `pending`.", - "allOf": [ - { - "$ref": "#/components/schemas/User--Base" + "properties": { + "type": { + "description": "`web_link`", + "type": "string", + "example": "web_link", + "enum": [ + "web_link" + ] }, - { - "properties": { - "name": { + "id": { + "description": "The unique identifier for this web link", + "type": "string", + "example": "11446498" + }, + "sequence_id": { + "allOf": [ + { "type": "string", - "description": "The display name of this user. If the collaboration status is `pending`, an empty string is returned.", - "example": "Aaron Levie", - "maxLength": 50, + "example": "3", + "nullable": true, + "description": "A numeric identifier that represents the most recent user event\nthat has been applied to this item.\n\nThis can be used in combination with the `GET /events`-endpoint\nto filter out user events that would have occurred before this\nidentifier was read.\n\nAn example would be where a Box Drive-like application\nwould fetch an item via the API, and then listen to incoming\nuser events for changes to the item. The application would\nignore any user events where the `sequence_id` in the event\nis smaller than or equal to the `sequence_id` in the originally\nfetched resource." + }, + { "nullable": false + } + ] + }, + "etag": { + "description": "The entity tag of this web link. Used with `If-Match`\nheaders.", + "type": "string", + "example": "1" + }, + "name": { + "description": "The name of the web link", + "type": "string", + "example": "My Bookmark" + }, + "url": { + "description": "The URL this web link points to", + "type": "string", + "example": "https://www.example.com/example/1234" + }, + "parent": { + "allOf": [ + { + "$ref": "#/components/schemas/Folder--Mini" }, - "login": { - "type": "string", - "format": "email", - "description": "The primary email address of this user. If the collaboration status is `pending`, an empty string is returned.", - "example": "ceo@example.com", + { + "description": "The parent object the web link belongs to" + } + ] + }, + "description": { + "description": "The description accompanying the web link. This is\nvisible within the Box web application.", + "type": "string", + "example": "Example page" + }, + "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.", + "type": "integer", + "format": "int64", + "example": 1, + "nullable": false + }, + "entries": { + "description": "The parent folders for this item", + "type": "array", + "items": { + "$ref": "#/components/schemas/Folder--Mini" + }, + "nullable": false + } + } + }, + { + "description": "The tree of folders that this web link is contained in,\nstarting at the root." + }, + { "nullable": false + } + ] + }, + "created_at": { + "description": "When this file was created on Box’s servers.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "modified_at": { + "description": "When this file was last updated on the Box\nservers.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "trashed_at": { + "description": "The time at which this bookmark was put in the\ntrash - becomes `null` after restore.", + "type": "string", + "example": null, + "nullable": true + }, + "purged_at": { + "description": "The time at which this bookmark will be permanently\ndeleted - becomes `null` after restore.", + "type": "string", + "example": null, + "nullable": true + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" }, - "is_active": { - "type": "boolean", - "example": true, - "description": "If set to `false`, the user is either deactivated or deleted." + { + "description": "The user who created this web link" } - } + ] + }, + "modified_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who last modified this web link" + } + ] + }, + "owned_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who owns this web link" + } + ] + }, + "shared_link": { + "description": "The shared link for this bookmark. This will\nbe `null` if a bookmark had been trashed, even though the original shared\nlink does become active again.", + "type": "string", + "example": null, + "nullable": true + }, + "item_status": { + "description": "Whether this item is deleted or not. Values include `active`,\n`trashed` if the file has been moved to the trash, and `deleted` if\nthe file has been permanently deleted", + "type": "string", + "example": "trashed", + "enum": [ + "active", + "trashed", + "deleted" + ] } - ] + }, + "required": [ + "sequence_id", + "path_collection" + ], + "title": "Trashed Web Link (Restored)", + "x-box-resource-id": "trash_web_link_restored", + "x-box-tag": "trashed_web_links" }, - "UserIntegrationMappings": { - "title": "User (Integration Mappings)", + "UploadPart": { + "description": "The representation of an upload\nsession chunk.", "type": "object", - "x-box-resource-id": "user_integration_mappings_reference", - "x-box-tag": "users", - "description": "A user representation for integration mappings\nAPI purposes. Fields name and login are not required.", "allOf": [ { - "$ref": "#/components/schemas/User--Base" + "$ref": "#/components/schemas/UploadPart--Mini" }, { "properties": { - "name": { - "type": "string", - "description": "The display name of this user", - "example": "Aaron Levie", - "maxLength": 50, - "nullable": false - }, - "login": { + "sha1": { + "description": "The SHA1 hash of the chunk.", "type": "string", - "format": "email", - "description": "The primary email address of this user", - "example": "ceo@example.com", - "nullable": false + "example": "134b65991ed521fcfe4724b7d814ab8ded5185dc" } } } - ] + ], + "title": "Upload part", + "x-box-resource-id": "upload_part", + "x-box-variant": "standard" }, - "Watermark": { - "title": "Watermark", + "UploadPart--Mini": { + "description": "The basic representation of an upload\nsession chunk.", "type": "object", - "x-box-resource-id": "watermark", - "x-box-tag": "file_watermarks", - "description": "A watermark is a semi-transparent overlay on an embedded file\npreview that displays a viewer's email address or user ID\nand the time of access over a file's content", "properties": { - "watermark": { - "type": "object", - "properties": { - "created_at": { - "type": "string", - "format": "date-time", - "description": "When this watermark was created", - "example": "2012-12-12T10:53:43-08:00" - }, - "modified_at": { - "type": "string", - "format": "date-time", - "description": "When this task was modified", - "example": "2012-12-12T10:53:43-08:00" - } - } + "part_id": { + "description": "The unique ID of the chunk.", + "type": "string", + "example": "6F2D3486" + }, + "offset": { + "description": "The offset of the chunk within the file\nin bytes. The lower bound of the position\nof the chunk within the file.", + "type": "integer", + "format": "int64", + "example": 16777216 + }, + "size": { + "description": "The size of the chunk in bytes.", + "type": "integer", + "format": "int64", + "example": 3222784 } - } + }, + "title": "Upload part (Mini)", + "x-box-resource-id": "upload_part--mini", + "x-box-tag": "chunked_uploads", + "x-box-variant": "mini", + "x-box-variants": [ + "mini", + "standard" + ] }, - "Webhook": { - "title": "Webhook", + "UploadParts": { + "description": "A list of uploaded chunks for an upload\nsession.", "type": "object", - "x-box-resource-id": "webhook", - "x-box-variant": "standard", - "x-box-tag": "webhooks", - "description": "Represents a configured webhook.", "allOf": [ { - "$ref": "#/components/schemas/Webhook--Mini" - }, - { + "type": "object", + "description": "The part of an API response that describes pagination", "properties": { - "created_by": { - "allOf": [ - { - "$ref": "#/components/schemas/User--Mini" - }, - { - "description": "The user who created the webhook" - } - ] + "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.", + "type": "integer", + "format": "int64", + "example": 5000 }, - "created_at": { - "type": "string", - "format": "date-time", - "description": "A timestamp identifying the time that\nthe webhook was created.", - "example": "2012-12-12T10:53:43-08:00" + "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.", + "type": "integer", + "format": "int64", + "example": 1000 }, - "address": { - "type": "string", - "example": "https://example.com/webhooks", - "description": "The URL that is notified by this webhook" + "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.", + "type": "integer", + "format": "int64", + "example": 2000 }, - "triggers": { + "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", - "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" - ] - } - } - } - } - ] + "type": "object", + "description": "The order in which a pagination is ordered", + "properties": { + "by": { + "description": "The field to order by", + "type": "string", + "example": "type" + }, + "direction": { + "description": "The direction to order by, either ascending or descending", + "type": "string", + "example": "ASC", + "enum": [ + "ASC", + "DESC" + ] + } + } + } + } + } + }, + { + "properties": { + "entries": { + "description": "A list of uploaded chunks for an upload\nsession", + "type": "array", + "items": { + "$ref": "#/components/schemas/UploadPart" + } + } + } + } + ], + "title": "Upload parts", + "x-box-resource-id": "upload_parts", + "x-box-tag": "chunked_uploads" }, - "Webhook--Mini": { - "title": "Webhook (Mini)", + "UploadSession": { + "description": "An upload session for chunk uploading a file.", "type": "object", - "x-box-resource-id": "webhook--mini", - "x-box-tag": "webhooks", - "x-box-variants": [ - "mini", - "standard" - ], - "x-box-variant": "mini", - "description": "Represents a configured webhook.", "properties": { "id": { + "description": "The unique identifier for this session", "type": "string", - "description": "The unique identifier for this webhook.", - "example": "11446498" + "example": "F971964745A5CD0C001BBE4E58196BFD" }, "type": { + "description": "`upload_session`", "type": "string", - "description": "`webhook`", - "example": "webhook", + "example": "upload_session", "enum": [ - "webhook" + "upload_session" ] }, - "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" + "session_expires_at": { + "description": "The date and time when this session expires.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "part_size": { + "description": "The size in bytes that must be used for all parts of of the\nupload.\n\nOnly the last part is allowed to be of a smaller size.", + "type": "integer", + "format": "int64", + "example": 1024 + }, + "total_parts": { + "description": "The total number of parts expected in this upload session,\nas determined by the file size and part size.", + "type": "integer", + "format": "int32", + "example": 1000 + }, + "num_parts_processed": { + "description": "The number of parts that have been uploaded and processed\nby the server. This starts at `0`.\n\nWhen committing a file files, inspecting this property can\nprovide insight if all parts have been uploaded correctly.", + "type": "integer", + "format": "int32", + "example": 455 + }, + "session_endpoints": { + "allOf": [ + { + "title": "Session endpoints", + "description": "A list of endpoints for a chunked upload session.", + "type": "object", + "properties": { + "upload_part": { + "description": "The URL to upload parts to", + "type": "string", + "example": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD" + }, + "commit": { + "description": "The URL used to commit the file", + "type": "string", + "example": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/commit" + }, + "abort": { + "description": "The URL for used to abort the session.", + "type": "string", + "example": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD" + }, + "list_parts": { + "description": "The URL users to list all parts.", + "type": "string", + "example": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/parts" + }, + "status": { + "description": "The URL used to get the status of the upload.", + "type": "string", + "example": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD" + }, + "log_event": { + "description": "The URL used to get the upload log from.", + "type": "string", + "example": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/log" + } + } }, - "type": { - "description": "The type of item to trigger a webhook", - "type": "string", - "example": "file", - "enum": [ - "file", - "folder" - ] + { + "description": "A list of endpoints for this session." } - } + ] } - } + }, + "title": "Upload session", + "x-box-resource-id": "upload_session", + "x-box-tag": "chunked_uploads" }, - "Webhooks": { - "title": "Webhooks", + "UploadUrl": { + "description": "The details for the upload session for the file.", + "type": "object", + "properties": { + "upload_url": { + "description": "A URL for an upload session that can be used to upload\nthe file.", + "type": "string", + "example": "https://upload-las.app.box.com/api/2.0/files/content?upload_session_id=1234" + }, + "upload_token": { + "description": "An optional access token to use to upload the file", + "type": "string", + "example": "Pc3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQP" + } + }, + "title": "Upload URL", + "x-box-resource-id": "upload_url", + "x-box-tag": "uploads" + }, + "UploadedPart": { + "description": "A chunk of a file uploaded as part of\nan upload session, as returned by some endpoints.", + "type": "object", + "properties": { + "part": { + "$ref": "#/components/schemas/UploadPart" + } + }, + "title": "Uploaded part", + "x-box-resource-id": "uploaded_part", + "x-box-tag": "chunked_uploads" + }, + "User": { + "description": "A standard representation of a user, as returned from any\nuser API endpoints by default", "type": "object", - "x-box-resource-id": "webhooks", - "x-box-tag": "webhooks", - "description": "A list of webhooks.", "allOf": [ { - "type": "object", - "description": "The part of an API response that describes marker\nbased pagination", + "$ref": "#/components/schemas/User--Mini" + }, + { "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, + "created_at": { + "description": "When the user object was created", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "modified_at": { + "description": "When the user object was last modified", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "language": { + "description": "The language of the user, formatted in modified version of the\n[ISO 639-1](/guides/api-calls/language-codes) format.", + "type": "string", + "example": "en" + }, + "timezone": { + "description": "The user's timezone", + "type": "string", + "format": "timezone", + "example": "Africa/Bujumbura" + }, + "space_amount": { + "description": "The user’s total available space amount in bytes", "type": "integer", - "format": "int64" + "format": "int64", + "example": 11345156112 }, - "next_marker": { - "description": "The marker for the start of the next page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "space_used": { + "description": "The amount of space in use by the user", + "type": "integer", + "format": "int64", + "example": 1237009912 + }, + "max_upload_size": { + "description": "The maximum individual file size in bytes the user can have", + "type": "integer", + "format": "int64", + "example": 2147483648 + }, + "status": { + "description": "The user's account status", "type": "string", - "nullable": true + "example": "active", + "enum": [ + "active", + "inactive", + "cannot_delete_edit", + "cannot_delete_edit_upload" + ] }, - "prev_marker": { - "description": "The marker for the start of the previous page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "job_title": { + "description": "The user’s job title", "type": "string", - "nullable": true + "example": "CEO", + "maxLength": 100 + }, + "phone": { + "description": "The user’s phone number", + "type": "string", + "example": "6509241374", + "maxLength": 100 + }, + "address": { + "description": "The user’s address", + "type": "string", + "example": "900 Jefferson Ave, Redwood City, CA 94063", + "maxLength": 255 + }, + "avatar_url": { + "description": "URL of the user’s avatar image", + "type": "string", + "example": "https://www.box.com/api/avatar/large/181216415" + }, + "notification_email": { + "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.", + "type": "object", + "nullable": true, + "properties": { + "email": { + "description": "The email address to send the notifications to.", + "type": "string", + "example": "notifications@example.com" + }, + "is_confirmed": { + "description": "Specifies if this email address has been confirmed.", + "type": "boolean", + "example": true + } + } } } + } + ], + "title": "User", + "x-box-resource-id": "user", + "x-box-variant": "standard" + }, + "User--Base": { + "description": "A mini representation of a user, used when\nnested within another resource.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this user", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`user`", + "type": "string", + "example": "user", + "enum": [ + "user" + ], + "nullable": false + } + }, + "required": [ + "type", + "id" + ], + "title": "User (Base)", + "x-box-resource-id": "user--base", + "x-box-tag": "users", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "mini", + "standard", + "full" + ] + }, + "User--Collaborations": { + "description": "A mini representation of a user, can be returned only when\nthe status is `pending`.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" }, { "properties": { - "entries": { - "type": "array", - "description": "A list of webhooks", - "items": { - "$ref": "#/components/schemas/Webhook--Mini" - } + "name": { + "description": "The display name of this user. If the collaboration status is `pending`, an empty string is returned.", + "type": "string", + "example": "Aaron Levie", + "maxLength": 50, + "nullable": false + }, + "login": { + "description": "The primary email address of this user. If the collaboration status is `pending`, an empty string is returned.", + "type": "string", + "format": "email", + "example": "ceo@example.com", + "nullable": false + }, + "is_active": { + "description": "If set to `false`, the user is either deactivated or deleted.", + "type": "boolean", + "example": true } } } - ] + ], + "title": "User (Collaborations)", + "x-box-resource-id": "user_collaborations", + "x-box-variant": "collaborations" }, - "WebLink": { - "title": "Web link", + "User--Full": { + "description": "A full representation of a user, as can be returned from any\nuser API endpoint.", "type": "object", - "x-box-resource-id": "web_link", - "x-box-variant": "standard", - "description": "Web links are objects that point to URLs. These objects\nare also known as bookmarks within the Box web application.\n\nWeb link objects are treated similarly to file objects,\nthey will also support most actions that apply to regular files.", "allOf": [ { - "$ref": "#/components/schemas/WebLink--Mini" + "$ref": "#/components/schemas/User" }, { "properties": { - "parent": { - "allOf": [ - { - "$ref": "#/components/schemas/Folder--Mini" - }, - { - "description": "The parent object the web link belongs to" - } + "role": { + "description": "The user’s enterprise role", + "type": "string", + "example": "admin", + "enum": [ + "admin", + "coadmin", + "user" ] }, - "description": { - "type": "string", - "example": "Example page", - "description": "The description accompanying the web link. This is\nvisible within the Box web application." + "tracking_codes": { + "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\nbefore it can be used.", + "type": "array", + "items": { + "$ref": "#/components/schemas/TrackingCode" + } }, - "path_collection": { + "can_see_managed_users": { + "description": "Whether the user can see other enterprise users in their contact list", + "type": "boolean", + "example": true + }, + "is_sync_enabled": { + "description": "Whether the user can use Box Sync", + "type": "boolean", + "example": true + }, + "is_external_collab_restricted": { + "description": "Whether the user is allowed to collaborate with users outside their\nenterprise", + "type": "boolean", + "example": true + }, + "is_exempt_from_device_limits": { + "description": "Whether to exempt the user from Enterprise device limits", + "type": "boolean", + "example": true + }, + "is_exempt_from_login_verification": { + "description": "Whether the user must use two-factor authentication", + "type": "boolean", + "example": true + }, + "enterprise": { "allOf": [ { - "title": "Path collection", - "description": "A list of parent folders for an item.", + "title": "Enterprise", "type": "object", - "required": [ - "total_count", - "entries" - ], + "description": "A representation of a Box enterprise", "properties": { - "total_count": { - "description": "The number of folders in this list.", - "example": 1, - "type": "integer", - "format": "int64", - "nullable": false + "id": { + "description": "The unique identifier for this enterprise.", + "type": "string", + "example": "11446498" }, - "entries": { - "type": "array", - "description": "The parent folders for this item", - "nullable": false, - "items": { - "$ref": "#/components/schemas/Folder--Mini" - } + "type": { + "description": "`enterprise`", + "type": "string", + "example": "enterprise", + "enum": [ + "enterprise" + ] + }, + "name": { + "description": "The name of the enterprise", + "type": "string", + "example": "Acme Inc." } } }, { - "description": "The tree of folders that this web link is contained in,\nstarting at the root." - }, - { - "nullable": false + "description": "Representation of the user’s enterprise" } ] }, - "created_at": { + "my_tags": { + "description": "Tags for all files and folders owned by the user. Values returned\nwill only contain tags that were set by the requester.", + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "important" + ] + }, + "hostname": { + "description": "The root (protocol, subdomain, domain) of any links that need to be\ngenerated for the user", "type": "string", - "format": "date-time", - "description": "When this file was created on Box’s servers.", - "example": "2012-12-12T10:53:43-08:00" + "example": "https://example.app.box.com/" }, - "modified_at": { + "is_platform_access_only": { + "description": "Whether the user is an App User", + "type": "boolean", + "example": true + }, + "external_app_user_id": { + "description": "An external identifier for an app user, which can be used to look up\nthe user. This can be used to tie user IDs from external identity\nproviders to Box users.", "type": "string", - "format": "date-time", - "description": "When this file was last updated on the Box\nservers.", - "example": "2012-12-12T10:53:43-08:00" + "example": "my-user-1234" + } + } + } + ], + "title": "User (Full)", + "x-box-resource-id": "user--full", + "x-box-variant": "full" + }, + "User--Mini": { + "description": "A mini representation of a user, as can be returned when nested within other\nresources.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "properties": { + "name": { + "description": "The display name of this user", + "type": "string", + "example": "Aaron Levie", + "maxLength": 50, + "nullable": false }, - "trashed_at": { + "login": { + "description": "The primary email address of this user", "type": "string", - "format": "date-time", - "nullable": true, - "description": "When this file was moved to the trash.", - "example": "2012-12-12T10:53:43-08:00" + "format": "email", + "example": "ceo@example.com", + "nullable": false + } + } + } + ], + "title": "User (Mini)", + "x-box-resource-id": "user--mini", + "x-box-variant": "mini" + }, + "UserAvatar": { + "description": "A resource holding URLs to the\navatar uploaded to a Box application.", + "type": "object", + "properties": { + "pic_urls": { + "description": "Represents an object with user avatar URLs.", + "type": "object", + "properties": { + "small": { + "description": "The location of a small-sized avatar.", + "type": "string", + "example": "https://app.box.com/index.php?rm=pic_storage_auth&pic=euks! pac3kv01!7B6R5cZLmurEV_xB-KkycPk8Oi7oENUX2O_qUtIuO4342CG IldyCto9hqiQP7uxqYU5V2w63Ft4ln4UVVLDtDZu903OqzkflY2O-Lq00 ubA29xU-RJ6b_KzJEWRYgUhX1zEl3dzWo12g8eWRE2rStf123DF7AYahNqM 1BmLmviL_nODc7SDQHedTXPAjxURUAra5BvtLe7B05AizbNXdPlCNp-LNh _S-eZ_RjDXcGO-MkRWd_3BOMHnvjf450t5BfKoJ15WhEfiMlfXH1tmouHXrsC 66cT6-pzF9E40Iir_zThqSlrFxzP_xcmXzHapr_k-0E2qr2TXp4iC396TSlEw\n" }, - "purged_at": { + "large": { + "description": "The location of a large-sized avatar.", "type": "string", - "format": "date-time", - "nullable": true, - "description": "When this file will be permanently deleted.", - "example": "2012-12-12T10:53:43-08:00" + "example": "https://app.box.com/index.php?rm=pic_storage_auth&pic=euks\npac3kv01!lipGQlQQOtCTCoB6zCOArUjVWLFJtLr5tn6aOZMCybhRx0NNuFQbVI36nw\njtEk5YjUUz1KVdVuvU2yDhu_ftK_bvxeKP1Ffrx9vKGVvJ-UJc1z32p6n2CmFzzpc\ngSoX4pnPhFgydAL-u9jDspXUGElr-htDG_HPMiE9DZjqDueOxXHy8xe22wbaPAheC\nao1emv8r_fmufaUgSndeMYmyZj-KqOYsLBrBNgdeiK5tZmPOQggAEUmyQPkrd8W92TQ6sSlIp0r" }, - "created_by": { - "allOf": [ + "preview": { + "description": "The location of the avatar preview.", + "type": "string", + "example": "https://app.box.com/index.php?rm=pic_storage_auth&pic=euks!\npac3kv01!8UcNPweOOAWj2DtHk_dCQB4wJpzyPkl7mT5nHj5ZdjY92ejYCBBZc95--403b29CW\nk-8hSo_uBjh5h9QG42Ihu-cOZ-816sej1kof3SOm5gjn7qjMAx89cHjUaNK-6XasRqSNboenjZ\n04laZuV9vSH12BZGAYycIZvvQ5R66Go8xG5GTMARf2nBU84c4H_SL5iws-HeBS4oQJWOJh6FBl\nsSJDSTI74LGXqeZb3EY_As34VFC95F10uozoTOSubZmPYylPlaKXoKWk2f9wYQso1ZTN7sh-Gc\n9Kp43zMLhArIWhok0Im6FlRAuWOQ03KYgL-k4L5EZp4Gw6B7uqVRwcBbsTwMIorWq1g" + } + } + } + }, + "title": "User avatar", + "x-box-resource-id": "user_avatar", + "x-box-tag": "avatars" + }, + "UserIntegrationMappings": { + "description": "A user representation for integration mappings\nAPI purposes. Fields name and login are not required.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "properties": { + "name": { + "description": "The display name of this user", + "type": "string", + "example": "Aaron Levie", + "maxLength": 50, + "nullable": false + }, + "login": { + "description": "The primary email address of this user", + "type": "string", + "format": "email", + "example": "ceo@example.com", + "nullable": false + } + } + } + ], + "title": "User (Integration Mappings)", + "x-box-resource-id": "user_integration_mappings_reference", + "x-box-tag": "users" + }, + "Users": { + "description": "A list of users.", + "type": "object", + "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.", + "type": "integer", + "format": "int64", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true + } + } + }, + { + "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.", + "type": "integer", + "format": "int64", + "example": 5000 + }, + "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.", + "type": "integer", + "format": "int64", + "example": 1000 + }, + "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.", + "type": "integer", + "format": "int64", + "example": 2000 + }, + "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", + "type": "string", + "example": "type" + }, + "direction": { + "description": "The direction to order by, either ascending or descending", + "type": "string", + "example": "ASC", + "enum": [ + "ASC", + "DESC" + ] + } + } + } + } + } + }, + { + "properties": { + "entries": { + "description": "A list of users", + "type": "array", + "items": { + "$ref": "#/components/schemas/User--Full" + } + } + } + } + ], + "title": "Users", + "x-box-resource-id": "users", + "x-box-tag": "users" + }, + "Watermark": { + "description": "A watermark is a semi-transparent overlay on an embedded file\npreview that displays a viewer's email address or user ID\nand the time of access over a file's content", + "type": "object", + "properties": { + "watermark": { + "type": "object", + "properties": { + "created_at": { + "description": "When this watermark was created", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "modified_at": { + "description": "When this task was modified", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + } + } + } + }, + "title": "Watermark", + "x-box-resource-id": "watermark", + "x-box-tag": "file_watermarks" + }, + "WebLink": { + "description": "Web links are objects that point to URLs. These objects\nare also known as bookmarks within the Box web application.\n\nWeb link objects are treated similarly to file objects,\nthey will also support most actions that apply to regular files.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/WebLink--Mini" + }, + { + "properties": { + "parent": { + "allOf": [ + { + "$ref": "#/components/schemas/Folder--Mini" + }, + { + "description": "The parent object the web link belongs to" + } + ] + }, + "description": { + "description": "The description accompanying the web link. This is\nvisible within the Box web application.", + "type": "string", + "example": "Example page" + }, + "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.", + "type": "integer", + "format": "int64", + "example": 1, + "nullable": false + }, + "entries": { + "description": "The parent folders for this item", + "type": "array", + "items": { + "$ref": "#/components/schemas/Folder--Mini" + }, + "nullable": false + } + } + }, + { + "description": "The tree of folders that this web link is contained in,\nstarting at the root." + }, + { + "nullable": false + } + ] + }, + "created_at": { + "description": "When this file was created on Box’s servers.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "modified_at": { + "description": "When this file was last updated on the Box\nservers.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "trashed_at": { + "description": "When this file was moved to the trash.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "purged_at": { + "description": "When this file will be permanently deleted.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "created_by": { + "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, @@ -36770,119 +38433,119 @@ ], "properties": { "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.", "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": { + "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.", "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 + "nullable": true, + "x-box-premium-feature": true }, "vanity_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.", "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.", + "type": "string", "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.", + "type": "string", + "example": "open", "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.", + "type": "string", + "example": "company", "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.", + "type": "string", + "example": "can_download", "enum": [ "can_edit", "can_download", "can_preview", "no_access" ], - "example": "can_download", "nullable": false }, "unshared_at": { + "description": "The date and time when this link will be unshared. This field can only be\nset by users with paid accounts.", "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.", + "type": "boolean", "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" - ], + "type": "object", "properties": { "can_download": { + "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`.", "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`." + "nullable": false }, "can_preview": { + "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.", "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." + "nullable": false }, "can_edit": { + "description": "Defines if the shared link allows for the item to be edited.\n\nThis value can only be `true` if `can_download` is also `true` and if\nthe item has a type of `file`.", "type": "boolean", "example": false, - "nullable": false, - "description": "Defines if the shared link allows for the item to be edited.\n\nThis value can only be `true` if `can_download` is also `true` and if\nthe item has a type of `file`." + "nullable": false } - } + }, + "required": [ + "can_download", + "can_preview", + "can_edit" + ] }, "download_count": { + "description": "The number of times this item has been downloaded.", "type": "integer", "example": 3, - "description": "The number of times this item has been downloaded.", "nullable": false }, "preview_count": { + "description": "The number of times this item has been previewed.", "type": "integer", "example": 3, - "description": "The number of times this item has been previewed.", "nullable": false } } @@ -36896,62 +38559,62 @@ ] }, "item_status": { + "description": "Whether this item is deleted or not. Values include `active`,\n`trashed` if the file has been moved to the trash, and `deleted` if\nthe file has been permanently deleted", "type": "string", "example": "active", "enum": [ "active", "trashed", "deleted" - ], - "description": "Whether this item is deleted or not. Values include `active`,\n`trashed` if the file has been moved to the trash, and `deleted` if\nthe file has been permanently deleted" + ] } } } - ] + ], + "title": "Web link", + "x-box-resource-id": "web_link", + "x-box-variant": "standard" }, "WebLink--Base": { - "title": "Web link (Base)", - "type": "object", - "x-box-resource-id": "web_link--base", - "x-box-tag": "web_links", - "x-box-variants": [ - "base", - "mini", - "standard" - ], - "x-box-variant": "base", "description": "Web links are objects that point to URLs. These objects\nare also known as bookmarks within the Box web application.\n\nWeb link objects are treated similarly to file objects,\nthey will also support most actions that apply to regular files.", - "required": [ - "id", - "type" - ], + "type": "object", "properties": { "id": { - "type": "string", "description": "The unique identifier for this web link", + "type": "string", "example": "11446498" }, "type": { - "type": "string", "description": "`web_link`", + "type": "string", "example": "web_link", "enum": [ "web_link" ] }, "etag": { + "description": "The entity tag of this web link. Used with `If-Match`\nheaders.", "type": "string", - "example": "1", - "description": "The entity tag of this web link. Used with `If-Match`\nheaders." + "example": "1" } - } + }, + "required": [ + "id", + "type" + ], + "title": "Web link (Base)", + "x-box-resource-id": "web_link--base", + "x-box-tag": "web_links", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "mini", + "standard" + ] }, "WebLink--Mini": { - "title": "Web link (Mini)", - "type": "object", - "x-box-resource-id": "web_link--mini", - "x-box-variant": "mini", "description": "Web links are objects that point to URLs. These objects\nare also known as bookmarks within the Box web application.\n\nWeb link objects are treated similarly to file objects,\nthey will also support most actions that apply to regular files.", + "type": "object", "allOf": [ { "$ref": "#/components/schemas/WebLink--Base" @@ -36959,9 +38622,9 @@ { "properties": { "url": { + "description": "The URL this web link points to", "type": "string", - "example": "https://www.example.com/example/1234", - "description": "The URL this web link points to" + "example": "https://www.example.com/example/1234" }, "sequence_id": { "allOf": [ @@ -36977,174 +38640,478 @@ ] }, "name": { - "type": "string", "description": "The name of the web link", + "type": "string", "example": "My Bookmark" } } } - ] + ], + "title": "Web link (Mini)", + "x-box-resource-id": "web_link--mini", + "x-box-variant": "mini" }, - "Workflow": { - "title": "Workflow", + "Webhook": { + "description": "Represents a configured webhook.", "type": "object", - "x-box-resource-id": "workflow", - "x-box-variant": "standard", - "description": "Box Relay Workflows are objects that represent a named collection of flows.\n\nYour application must be authorized to use the `Manage Box Relay` application\nscope within the developer console in order to use this resource.", "allOf": [ { - "$ref": "#/components/schemas/Workflow--Mini" + "$ref": "#/components/schemas/Webhook--Mini" }, { "properties": { - "flows": { + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who created the webhook" + } + ] + }, + "created_at": { + "description": "A timestamp identifying the time that\nthe webhook was created.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "address": { + "description": "The URL that is notified by this webhook", + "type": "string", + "example": "https://example.com/webhooks" + }, + "triggers": { + "description": "An array of event names that this webhook is\nto be triggered for", "type": "array", - "description": "A list of flows assigned to a workflow.", "items": { - "type": "object", - "description": "A step in a Box Relay Workflow. Each flow contains a `Trigger` and\na collection of Outcomes to perform once the conditions of a\n`Trigger` are met", - "properties": { - "id": { - "type": "string", - "description": "The identifier of the flow", - "example": "12345" - }, - "type": { - "type": "string", - "description": "The flow's resource type", - "example": "flow", - "enum": [ - "flow" - ] - }, - "trigger": { - "allOf": [ - { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The trigger's resource type", - "example": "trigger", - "enum": [ - "trigger" - ] - }, - "trigger_type": { - "type": "string", - "description": "The type of trigger selected for this flow", - "example": "WORKFLOW_MANUAL_START", - "enum": [ - "WORKFLOW_MANUAL_START" - ] - }, - "scope": { - "type": "array", - "description": "List of trigger scopes", - "items": { - "type": "object", - "description": "Object that describes where and how a Trigger condition is met", - "properties": { - "type": { - "type": "string", - "description": "The trigger scope's resource type", - "example": "trigger_scope", - "enum": [ - "trigger_scope" - ] - }, - "ref": { - "type": "string", - "description": "Indicates the path of the condition value to check", - "example": "/event/source/parameters/folder" - }, - "object": { - "type": "object", - "description": "The object the `ref` points to", - "properties": { - "type": { - "type": "string", - "description": "The type of the object", - "example": "folder", - "enum": [ - "folder" - ] - }, - "id": { - "type": "string", - "description": "The id of the object", - "example": "12345" - } - } - } - } - } - } - } - }, - { - "description": "Trigger that initiates flow" - } - ] - }, - "outcomes": { - "allOf": [ - { - "type": "array", - "items": { - "type": "object", - "description": "List of outcomes to perform once the conditions of trigger are met.", - "properties": { - "id": { - "type": "string", - "description": "The identifier of the outcome", - "example": "12345" - }, - "type": { - "type": "string", - "description": "The outcomes resource type", - "example": "outcome", - "enum": [ - "outcome" - ] - }, - "name": { - "type": "string", - "description": "The name of the outcome", - "example": "Task Approval Outcome" - }, - "action_type": { - "allOf": [ - { - "title": "Action Type", - "example": "assign_task", - "type": "string", - "description": "The type of outcome", - "enum": [ - "add_metadata", - "assign_task", - "copy_file", - "copy_folder", - "create_folder", - "delete_file", - "delete_folder", - "lock_file", - "move_file", - "move_folder", - "remove_watermark_file", - "rename_folder", - "restore_folder", - "share_file", - "share_folder", - "unlock_file", - "upload_file", - "wait_for_task", - "watermark_file", - "go_back_to_step", - "apply_file_classification", - "apply_folder_classification", - "send_notification" - ] + "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" + ] + }, + "example": [ + "FILE.UPLOADED" + ] + } + } + } + ], + "title": "Webhook", + "x-box-resource-id": "webhook", + "x-box-tag": "webhooks", + "x-box-variant": "standard" + }, + "Webhook--Mini": { + "description": "Represents a configured webhook.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this webhook.", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`webhook`", + "type": "string", + "example": "webhook", + "enum": [ + "webhook" + ] + }, + "target": { + "description": "The item that will trigger the webhook", + "type": "object", + "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" + ] + } + } + } + }, + "title": "Webhook (Mini)", + "x-box-resource-id": "webhook--mini", + "x-box-tag": "webhooks", + "x-box-variant": "mini", + "x-box-variants": [ + "mini", + "standard" + ] + }, + "WebhookInvocation": { + "description": "The event that is sent to a webhook address when an event happens.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this webhook invocation", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`webhook_event`", + "type": "string", + "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": { + "description": "A timestamp identifying the time that\nthe webhook event was triggered.", + "type": "string", + "format": "date-time", + "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" + } + ] + } + }, + "title": "Webhook (V2) payload", + "x-box-resource-id": "webhook_invocation", + "x-box-tag": "webhooks" + }, + "Webhooks": { + "description": "A list of webhooks.", + "type": "object", + "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.", + "type": "integer", + "format": "int64", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "description": "A list of webhooks", + "type": "array", + "items": { + "$ref": "#/components/schemas/Webhook--Mini" + } + } + } + } + ], + "title": "Webhooks", + "x-box-resource-id": "webhooks", + "x-box-tag": "webhooks" + }, + "Workflow": { + "description": "Box Relay Workflows are objects that represent a named collection of flows.\n\nYour application must be authorized to use the `Manage Box Relay` application\nscope within the developer console in order to use this resource.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/Workflow--Mini" + }, + { + "properties": { + "flows": { + "description": "A list of flows assigned to a workflow.", + "type": "array", + "items": { + "type": "object", + "description": "A step in a Box Relay Workflow. Each flow contains a `Trigger` and\na collection of Outcomes to perform once the conditions of a\n`Trigger` are met", + "properties": { + "id": { + "description": "The identifier of the flow", + "type": "string", + "example": "12345" + }, + "type": { + "description": "The flow's resource type", + "type": "string", + "example": "flow", + "enum": [ + "flow" + ] + }, + "trigger": { + "allOf": [ + { + "type": "object", + "properties": { + "type": { + "description": "The trigger's resource type", + "type": "string", + "example": "trigger", + "enum": [ + "trigger" + ] + }, + "trigger_type": { + "description": "The type of trigger selected for this flow", + "type": "string", + "example": "WORKFLOW_MANUAL_START", + "enum": [ + "WORKFLOW_MANUAL_START" + ] + }, + "scope": { + "description": "List of trigger scopes", + "type": "array", + "items": { + "type": "object", + "description": "Object that describes where and how a Trigger condition is met", + "properties": { + "type": { + "description": "The trigger scope's resource type", + "type": "string", + "example": "trigger_scope", + "enum": [ + "trigger_scope" + ] + }, + "ref": { + "description": "Indicates the path of the condition value to check", + "type": "string", + "example": "/event/source/parameters/folder" + }, + "object": { + "description": "The object the `ref` points to", + "type": "object", + "properties": { + "type": { + "description": "The type of the object", + "type": "string", + "example": "folder", + "enum": [ + "folder" + ] + }, + "id": { + "description": "The id of the object", + "type": "string", + "example": "12345" + } + } + } + } + } + } + } + }, + { + "description": "Trigger that initiates flow" + } + ] + }, + "outcomes": { + "allOf": [ + { + "type": "array", + "items": { + "type": "object", + "description": "List of outcomes to perform once the conditions of trigger are met.", + "properties": { + "id": { + "description": "The identifier of the outcome", + "type": "string", + "example": "12345" + }, + "type": { + "description": "The outcomes resource type", + "type": "string", + "example": "outcome", + "enum": [ + "outcome" + ] + }, + "name": { + "description": "The name of the outcome", + "type": "string", + "example": "Task Approval Outcome" + }, + "action_type": { + "allOf": [ + { + "title": "Action Type", + "example": "assign_task", + "type": "string", + "description": "The type of outcome", + "enum": [ + "add_metadata", + "assign_task", + "copy_file", + "copy_folder", + "create_folder", + "delete_file", + "delete_folder", + "lock_file", + "move_file", + "move_folder", + "remove_watermark_file", + "rename_folder", + "restore_folder", + "share_file", + "share_folder", + "unlock_file", + "upload_file", + "wait_for_task", + "watermark_file", + "go_back_to_step", + "apply_file_classification", + "apply_folder_classification", + "send_notification" + ] }, { "description": "The type of outcome" @@ -37152,27 +39119,27 @@ ] }, "if_rejected": { - "type": "array", "description": "If `action_type` is `assign_task` and the task is rejected, returns a\nlist of outcomes to complete", + "type": "array", "items": { "type": "object", "properties": { "id": { - "type": "string", "description": "The identifier of the outcome", + "type": "string", "example": "12345" }, "type": { - "type": "string", "description": "The outcomes resource type", + "type": "string", "example": "outcome", "enum": [ "outcome" ] }, "name": { - "type": "string", "description": "The name of the outcome", + "type": "string", "example": "Approval Rejection Outcome" }, "action_type": { @@ -37225,2336 +39192,364 @@ ] }, "created_at": { + "description": "When this flow was created", "type": "string", "format": "date-time", - "description": "When this flow was created", "example": "2012-12-12T10:53:43-08:00" }, "created_by": { "allOf": [ { - "$ref": "#/components/schemas/User--Base" - }, - { - "description": "The user who created this flow" - } - ] - } - } - } - } - } - } - ] - }, - "Workflow--Full": { - "title": "Workflow (Full)", - "type": "object", - "x-box-resource-id": "workflow--full", - "x-box-variant": "full", - "description": "Box Relay Workflows are objects that represent a named collection of flows.\n\nYou application must be authorized to use the `Manage Box Relay` application\nscope within the developer console in order to use this resource.", - "allOf": [ - { - "$ref": "#/components/schemas/Workflow" - }, - { - "properties": { - "created_at": { - "type": "string", - "format": "date-time", - "description": "The date and time when the workflow was created on Box", - "example": "2012-12-12T10:53:43-08:00" - }, - "modified_at": { - "type": "string", - "format": "date-time", - "description": "The date and time when the workflow was last updated on Box", - "example": "2012-12-12T10:53:43-08:00" - }, - "created_by": { - "allOf": [ - { - "$ref": "#/components/schemas/User--Base" - }, - { - "description": "The user who created this workflow" - } - ] - }, - "modified_by": { - "allOf": [ - { - "$ref": "#/components/schemas/User--Base" - }, - { - "description": "The user who last modified this workflow" - } - ] - } - } - } - ] - }, - "Workflow--Mini": { - "title": "Workflow (Mini)", - "type": "object", - "x-box-resource-id": "workflow--mini", - "x-box-tag": "workflows", - "x-box-variants": [ - "mini", - "standard", - "full" - ], - "x-box-variant": "mini", - "description": "Box Relay Workflows are objects that represent a named collection of flows.\n\nYou application must be authorized to use the `Manage Box Relay` application\nscope within the developer console in order to use this resource.", - "properties": { - "id": { - "type": "string", - "description": "The unique identifier for the workflow", - "example": "11446498" - }, - "type": { - "type": "string", - "description": "`workflow`", - "example": "workflow", - "enum": [ - "workflow" - ] - }, - "name": { - "type": "string", - "example": "New Hire Workflow", - "description": "The name of the workflow" - }, - "description": { - "type": "string", - "description": "The description for a workflow.", - "example": "This workflow sets off a new hire approval flow" - }, - "is_enabled": { - "type": "boolean", - "example": true, - "description": "Specifies if this workflow is enabled" - } - } - }, - "Workflows": { - "title": "Workflows", - "type": "object", - "x-box-resource-id": "workflows", - "x-box-tag": "workflows", - "description": "A list of workflows.\n\nYou application must be authorized to use the `Manage Box Relay` application\nscope within the developer console in order to use this resource.", - "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": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", - "type": "string", - "nullable": true - }, - "prev_marker": { - "description": "The marker for the start of the previous page of results.", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", - "type": "string", - "nullable": true - } - } - }, - { - "properties": { - "entries": { - "type": "array", - "description": "A list of workflows", - "items": { - "$ref": "#/components/schemas/Workflow" - } - } - } - } - ] - }, - "ZipDownload": { - "title": "Zip download", - "type": "object", - "x-box-resource-id": "zip_download", - "x-box-tag": "zip_downloads", - "x-box-reference-category": "zip_downloads", - "description": "Represents a successful request to create a `zip` archive of a list of files\nand folders.", - "example": { - "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" - } - ] - ] - }, - "properties": { - "download_url": { - "type": "string", - "description": "The URL that can be used to download the `zip` archive. A `Get` request to\nthis URL will start streaming the items requested. By default, this URL\nis only valid for a few seconds, until the `expires_at` time, unless a\ndownload is started after which it is valid for the duration of the\ndownload.\n\nIt is important to note that the domain and path of this URL might change\nbetween API calls, and therefore it's important to use this URL as-is.", - "example": "https://dl.boxcloud.com/2.0/zip_downloads/Lu6fA9Ob-jyysp3AAvMF4AkLEwZwAYbL=tgj2zIC=eK9RvJnJbjJl9rNh2qBgHDpyOCAOhpM=vajg2mKq8Mdd/content" - }, - "status_url": { - "type": "string", - "description": "The URL that can be used to get the status of the `zip` archive being\ndownloaded. A `Get` request to this URL will return the number of files\nin the archive as well as the number of items already downloaded or\nskipped. By default, this URL is only valid for a few seconds, until the\n`expires_at` time, unless a download is started after which the URL is\nvalid for 12 hours from the start of the download.\n\nIt is important to note that the domain and path of this URL might change\nbetween API calls, and therefore it's important to use this URL as-is.", - "example": "https://api.box.com/2.0/zip_downloads/Lu6fA9Ob-jyysp3AAvMF4AkLEwZwAYbL=tgj2zIC=eK9RvJnJbjJl9rNh2qBgHDpyOCAOhpM=vajg2mKq8Mdd/status" - }, - "expires_at": { - "type": "string", - "format": "date-time", - "description": "The time and date when this archive will expire. After this time the\n`status_url` and `download_url` will return an error.\n\nBy default, these URLs are only valid for a few seconds, unless a download\nis started after which the `download_url` is valid for the duration of the\ndownload, and the `status_url` is valid for 12 hours from the start of the\ndownload.", - "example": "2019-08-29T23:59:00-07:00" - }, - "name_conflicts": { - "type": "array", - "description": "A list of conflicts that occurred when trying to create the archive. This\nwould occur when multiple items have been requested with the\nsame name.\n\nTo solve these conflicts, the API will automatically rename an item\nand return a mapping between the original item's name and its new\nname.\n\nFor every conflict, both files will be renamed and therefore this list\nwill always be a multiple of 2.", - "items": { - "type": "array", - "description": "An individual conflict that occurred when trying to create the archive.\nThis includes an array of 2 objects, each containing the original name\nand the renamed filename of a file or folder for which the names\nconflicted.", - "items": { - "type": "object", - "description": "A file or folder for which a conflict was encountered, This object provides the type and identifier of the original item, as well as a mapping between its original name and it's new name as it will appear in the archive.", - "properties": { - "id": { - "type": "string", - "description": "The identifier of the item", - "example": "12345" - }, - "type": { - "type": "string", - "description": "The type of this item", - "example": "file", - "enum": [ - "file", - "folder" - ] - }, - "original_name": { - "type": "string", - "description": "The original name of this item", - "example": "Report.pdf" - }, - "download_name": { - "type": "string", - "description": "The new name of this item as it will appear in the\ndownloaded `zip` archive.", - "example": "3aa6a7.pdf" - } - } - } - } - } - } - }, - "ZipDownloadStatus": { - "title": "Zip download status", - "type": "object", - "x-box-resource-id": "zip_download_status", - "x-box-tag": "zip_downloads", - "x-box-reference-category": "zip_downloads", - "description": "The status of a `zip` archive being downloaded.", - "properties": { - "total_file_count": { - "type": "integer", - "description": "The total number of files in the archive.", - "example": 20, - "minimum": 0, - "maximum": 10000 - }, - "downloaded_file_count": { - "type": "integer", - "description": "The number of files that have already been downloaded.", - "example": 10, - "minimum": 0 - }, - "skipped_file_count": { - "type": "integer", - "description": "The number of files that have been skipped as they could not be\ndownloaded. In many cases this is due to permission issues that have\nsurfaced between the creation of the request for the archive and the\narchive being downloaded.", - "example": 5, - "minimum": 0 - }, - "skipped_folder_count": { - "type": "integer", - "description": "The number of folders that have been skipped as they could not be\ndownloaded. In many cases this is due to permission issues that have\nsurfaced between the creation of the request for the archive and the\narchive being downloaded.", - "example": 5, - "minimum": 0 - }, - "state": { - "type": "string", - "description": "The state of the archive being downloaded.", - "default": "in_progress", - "example": "succeeded", - "enum": [ - "in_progress", - "failed", - "succeeded" - ] - } - } - }, - "SignRequest--Base": { - "title": "Box Sign request (Base)", - "type": "object", - "x-box-resource-id": "sign_request--base", - "x-box-tag": "sign_requests", - "x-box-variants": [ - "standard", - "base" - ], - "x-box-variant": "base", - "description": "A standard representation of a signature request object.", - "properties": { - "is_document_preparation_needed": { - "type": "boolean", - "description": "Indicates if the sender should receive a `prepare_url` in the response to complete document preparation using the UI.", - "example": true - }, - "redirect_url": { - "type": "string", - "example": "https://www.example.com", - "description": "When specified, the signature request will be redirected to this url when a document is signed.", - "nullable": true - }, - "declined_redirect_url": { - "type": "string", - "example": "https://declined-redirect.com", - "description": "The uri that a signer will be redirected to after declining to sign a document.", - "nullable": true - }, - "are_text_signatures_enabled": { - "type": "boolean", - "description": "Disables the usage of signatures generated by typing (text).", - "example": true, - "default": true - }, - "email_subject": { - "type": "string", - "example": "Sign Request from Acme", - "description": "Subject of sign request email. This is cleaned by sign request. If this field is not passed, a default subject will be used.", - "nullable": true - }, - "email_message": { - "type": "string", - "example": "Hello! Please sign the document below", - "description": "Message to include in sign request email. The field is cleaned through sanitization of specific characters. However, some html tags are allowed. Links included in the message are also converted to hyperlinks in the email. The message may contain the following html tags including `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. If this field is not passed, a default message will be used.", - "nullable": true - }, - "are_reminders_enabled": { - "type": "boolean", - "description": "Reminds signers to sign a document on day 3, 8, 13 and 18. Reminders are only sent to outstanding signers.", - "example": true - }, - "name": { - "type": "string", - "example": "name", - "description": "Name of the signature request." - }, - "prefill_tags": { - "type": "array", - "items": { - "$ref": "#/components/schemas/SignRequestPrefillTag" - }, - "description": "When a document contains sign-related tags in the content, you can prefill them using this `prefill_tags` by referencing the 'id' of the tag as the `external_id` field of the prefill tag." - }, - "days_valid": { - "type": "integer", - "description": "Set the number of days after which the created signature request will automatically expire if not completed. By default, we do not apply any expiration date on signature requests, and the signature request does not expire.", - "minimum": 0, - "maximum": 730, - "example": 2, - "nullable": true - }, - "external_id": { - "type": "string", - "description": "This can be used to reference an ID in an external system that the sign request is related to.", - "example": "123", - "nullable": true - }, - "is_phone_verification_required_to_view": { - "type": "boolean", - "description": "Forces signers to verify a text message prior to viewing the document. You must specify the phone number of signers to have this setting apply to them.", - "example": true, - "nullable": true - }, - "template_id": { - "type": "string", - "example": "123075213-af2c8822-3ef2-4952-8557-52d69c2fe9cb", - "description": "When a signature request is created from a template this field will indicate the id of that template.", - "nullable": true - }, - "external_system_name": { - "type": "string", - "nullable": true, - "example": "Box", - "description": "Used as an optional system name to appear in the signature log next to the signers who have been assigned the `embed_url_external_id`." - } - } - }, - "SignRequest": { - "title": "Box Sign request", - "type": "object", - "x-box-resource-id": "sign_request", - "x-box-tag": "sign_requests", - "x-box-variants": [ - "standard", - "base" - ], - "x-box-variant": "standard", - "description": "A Box Sign request object.", - "allOf": [ - { - "$ref": "#/components/schemas/SignRequest--Base" - }, - { - "properties": { - "type": { - "type": "string", - "example": "sign-request", - "enum": [ - "sign-request" - ], - "description": "object type" - }, - "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." - }, - "signers": { - "type": "array", - "items": { - "$ref": "#/components/schemas/SignRequestSigner" - }, - "description": "Array of signers for the signature request." - }, - "signature_color": { - "type": "string", - "example": "blue", - "description": "Force a specific color for the signature (blue, black, or red).", - "nullable": true - }, - "id": { - "type": "string", - "example": "12345", - "description": "Box Sign request ID." - }, - "prepare_url": { - "type": "string", - "example": "https://prepareurl.com", - "description": "This URL is returned if `is_document_preparation_needed` is\nset to `true` in the request. The parameter is used to prepare\nthe signature request\nusing the UI. The signature request is not\nsent until the preparation\nphase is complete.", - "nullable": true - }, - "signing_log": { - "allOf": [ - { - "$ref": "#/components/schemas/File--Mini" - }, - { - "description": "Reference to a file that holds a log of all signer activity for\nthe request." - } - ] - }, - "status": { - "type": "string", - "enum": [ - "converting", - "created", - "sent", - "viewed", - "signed", - "cancelled", - "declined", - "error_converting", - "error_sending", - "expired", - "finalizing", - "error_finalizing" - ], - "example": "converting", - "description": "Describes the status of the signature request." - }, - "sign_files": { - "type": "object", - "properties": { - "files": { - "type": "array", - "items": { - "$ref": "#/components/schemas/File--Mini" - } - }, - "is_ready_for_download": { - "type": "boolean", - "example": true, - "description": "Indicates whether the `sign_files` documents are processing\nand the PDFs may be out of date. A change to any document\nrequires processing on all `sign_files`. We\nrecommended waiting until processing is finished\n(and this value is true) before downloading the PDFs." - } - }, - "description": "List of files that will be signed, which are copies of the original\nsource files. A new version of these files are created as signers sign\nand can be downloaded at any point in the signing process." - }, - "auto_expire_at": { - "type": "string", - "format": "date-time", - "example": "2021-04-26T08:12:13.982Z", - "description": "Uses `days_valid` to calculate the date and time, in GMT, the sign request will expire if unsigned.", - "nullable": true - }, - "parent_folder": { - "nullable": false, - "allOf": [ - { - "$ref": "#/components/schemas/Folder--Mini" - }, - { - "description": "The destination folder to place final, signed document and signing\nlog.\n\nWhen this value was not passed in when the signature request was \ncreated, then we will use a default folder which is either the parent\nfolder of the first source file in the payload if we have the permission\nto upload to that folder or a folder called \"My Sign Requests\"." - } - ] - } - } - } - ] - }, - "SignRequests": { - "title": "Box Sign requests", - "type": "object", - "x-box-resource-id": "sign_requests", - "x-box-tag": "sign_requests", - "description": "A standard representation of a signature request, as returned from any Box Sign\nAPI endpoints by default.", - "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": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", - "type": "string", - "nullable": true - } - } - }, - { - "properties": { - "entries": { - "type": "array", - "description": "A list of Box Sign requests.", - "items": { - "$ref": "#/components/schemas/SignRequest" - } - } - } - } - ] - }, - "AiItem--Base": { - "title": "AI Item (Base)", - "type": "object", - "required": [ - "id", - "type" - ], - "x-box-variants": [ - "base" - ], - "x-box-variant": "base", - "description": "The item to be processed by the LLM.", - "properties": { - "id": { - "type": "string", - "description": "The ID of the file.", - "example": "123" - }, - "type": { - "type": "string", - "description": "The type of the item. Currently the value can be `file` only.", - "enum": [ - "file" - ], - "example": "file" - }, - "content": { - "type": "string", - "description": "The content of the item, often the text representation.", - "example": "This is file content." - } - } - }, - "AiAgentBasicTextToolBase": { - "title": "AI agent basic text tool", - "type": "object", - "x-box-tag": "ai", - "properties": { - "model": { - "type": "string", - "description": "The model used for the AI agent for basic text. For specific model values, see the [available models list](g://box-ai/supported-models).", - "example": "azure__openai__gpt_3_5_turbo_16k" - }, - "num_tokens_for_completion": { - "type": "integer", - "description": "The number of tokens for completion.", - "example": 8400, - "minimum": 1 - }, - "llm_endpoint_params": { - "oneOf": [ - { - "$ref": "#/components/schemas/AiLlmEndpointParamsOpenAi" - }, - { - "$ref": "#/components/schemas/AiLlmEndpointParamsGoogle" - } - ], - "description": "The parameters for the LLM endpoint specific to OpenAI / Google models." - } - }, - "description": "AI agent tool used to handle basic text." - }, - "AiAgentBasicTextTool": { - "title": "AI agent basic text tool", - "type": "object", - "x-box-tag": "ai", - "allOf": [ - { - "$ref": "#/components/schemas/AiAgentBasicTextToolBase" - }, - { - "properties": { - "system_message": { - "type": "string", - "description": "System messages try to help the LLM \"understand\" its role and what it is supposed to do.", - "example": "You are a helpful travel assistant specialized in budget travel" - }, - "prompt_template": { - "type": "string", - "description": "The prompt template contains contextual information of the request and the user prompt.\nWhen passing `prompt_template` parameters, you **must include** inputs for `{user_question}` and `{content}`.\n`{current_date}` is optional, depending on the use.", - "example": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.", - "maxLength": 10000, - "pattern": "(\\{user_question\\}[\\s\\S]*?\\{content\\}|\\{content\\}[\\s\\S]*?\\{user_question\\})" - } - } - } - ], - "description": "AI agent tool used to handle basic text." - }, - "AiAgentBasicTextToolTextGen": { - "title": "AI agent basic text tool", - "type": "object", - "x-box-tag": "ai", - "allOf": [ - { - "$ref": "#/components/schemas/AiAgentBasicTextToolBase" - }, - { - "properties": { - "system_message": { - "type": "string", - "description": "System messages aim at helping the LLM understand its role and what it is supposed to do.\nThe input for `{current_date}` is optional, depending on the use.", - "example": "You are a helpful travel assistant specialized in budget travel" - }, - "prompt_template": { - "type": "string", - "description": "The prompt template contains contextual information of the request and the user prompt.\n\nWhen using the `prompt_template` parameter, you **must include** input for `{user_question}`.\nInputs for `{current_date}` and `{content}` are optional, depending on the use.", - "example": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. `{user_question}`", - "maxLength": 10000, - "pattern": "\\{user_question\\}" - } - } - } - ], - "description": "AI agent tool used to handle basic text." - }, - "AiAgentLongTextTool": { - "title": "AI agent long text tool", - "type": "object", - "x-box-tag": "ai", - "description": "AI agent tool used to to handle longer text.", - "allOf": [ - { - "$ref": "#/components/schemas/AiAgentBasicTextTool" - }, - { - "properties": { - "embeddings": { - "type": "object", - "properties": { - "model": { - "type": "string", - "example": "openai__text_embedding_ada_002", - "description": "The model used for the AI agent for calculating embeddings." - }, - "strategy": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "The strategy used for the AI agent for calculating embeddings.", - "example": "basic" - }, - "num_tokens_per_chunk": { - "type": "integer", - "description": "The number of tokens per chunk.", - "example": 64, - "minimum": 1 - } - } - } - } - } - } - } - ] - }, - "AiAgentLongTextToolTextGen": { - "title": "AI agent long text tool", - "type": "object", - "x-box-tag": "ai", - "description": "AI agent tool used to to handle longer text.", - "allOf": [ - { - "$ref": "#/components/schemas/AiAgentBasicTextToolTextGen" - }, - { - "properties": { - "embeddings": { - "type": "object", - "properties": { - "model": { - "type": "string", - "example": "openai__text_embedding_ada_002", - "description": "The model used for the AI agent for calculating embeddings." - }, - "strategy": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "The strategy used for the AI agent for calculating embeddings.", - "example": "basic" - }, - "num_tokens_per_chunk": { - "type": "integer", - "description": "The number of tokens per chunk.", - "example": 64, - "minimum": 1 - } - } - } - } - } - } - } - ] - }, - "AiAgentBasicGenTool": { - "title": "AI agent basic text generation tool", - "type": "object", - "x-box-tag": "ai", - "allOf": [ - { - "$ref": "#/components/schemas/AiAgentLongTextToolTextGen" - }, - { - "properties": { - "content_template": { - "type": "string", - "description": "How the content should be included in a request to the LLM.\nInput for `{content}` is optional, depending on the use.", - "example": "---{content}---" - } - } - } - ], - "description": "AI agent basic tool used to generate text. " - }, - "AiLlmEndpointParamsGoogle": { - "title": "AI LLM endpoint params Google", - "type": "object", - "x-box-resource-id": "ai_llm_endpoint_params_google", - "required": [ - "type" - ], - "properties": { - "type": { - "type": "string", - "description": "The type of the AI LLM endpoint params object for Google.\nThis parameter is **required**.", - "example": "google_params", - "enum": [ - "google_params" - ], - "nullable": false - }, - "temperature": { - "type": "number", - "description": "The temperature is used for sampling during response generation, which occurs when `top-P` and `top-K` are applied. Temperature controls the degree of randomness in the token selection.", - "example": 0, - "minimum": 0, - "maximum": 2, - "nullable": true - }, - "top_p": { - "type": "number", - "description": "`Top-P` changes how the model selects tokens for output. Tokens are selected from the most (see `top-K`) to least probable until the sum of their probabilities equals the `top-P` value.", - "example": 1, - "minimum": 0.1, - "maximum": 2, - "nullable": true - }, - "top_k": { - "type": "number", - "description": "`Top-K` changes how the model selects tokens for output. A `top-K` of 1 means the next selected token is\nthe most probable among all tokens in the model's vocabulary (also called greedy decoding),\nwhile a `top-K` of 3 means that the next token is selected from among the three most probable tokens by using temperature.", - "example": 1, - "minimum": 0.1, - "maximum": 2, - "nullable": true - } - }, - "description": "AI LLM endpoint params Google object" - }, - "AiLlmEndpointParamsOpenAi": { - "title": "AI LLM endpoint params OpenAI", - "type": "object", - "x-box-resource-id": "ai_llm_endpoint_params_openai", - "required": [ - "type" - ], - "properties": { - "type": { - "type": "string", - "description": "The type of the AI LLM endpoint params object for OpenAI.\nThis parameter is **required**.", - "example": "openai_params", - "enum": [ - "openai_params" - ], - "nullable": false - }, - "temperature": { - "type": "number", - "description": "What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, \nwhile lower values like 0.2 will make it more focused and deterministic. \nWe generally recommend altering this or `top_p` but not both.", - "example": 0, - "minimum": 0, - "maximum": 2, - "nullable": true - }, - "top_p": { - "type": "number", - "example": 1, - "description": "An alternative to sampling with temperature, called nucleus sampling, where the model considers the results \nof the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability \nmass are considered. We generally recommend altering this or temperature but not both.", - "minimum": 0.1, - "maximum": 1, - "nullable": true - }, - "frequency_penalty": { - "type": "number", - "description": "A number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the \ntext so far, decreasing the model's likelihood to repeat the same line verbatim.", - "minimum": -2, - "maximum": 2, - "example": 1.5, - "nullable": true - }, - "presence_penalty": { - "type": "number", - "description": "A number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.", - "minimum": -2, - "maximum": 2, - "example": 1.5, - "nullable": true - }, - "stop": { - "type": "string", - "description": "Up to 4 sequences where the API will stop generating further tokens.", - "example": "<|im_end|>", - "nullable": true - } - }, - "description": "AI LLM endpoint params OpenAI object." - }, - "AiCitation": { - "title": "The citation of the LLM's answer reference", - "type": "object", - "properties": { - "content": { - "type": "string", - "description": "The specific content from where the answer was referenced.", - "example": "Public APIs are key drivers of innovation and growth." - }, - "id": { - "type": "string", - "description": "The id of the item.", - "example": "123" - }, - "type": { - "type": "string", - "description": "The type of the item.", - "enum": [ - "file" - ], - "example": "file" - }, - "name": { - "type": "string", - "description": "The name of the item.", - "example": "The importance of public APIs.pdf" - } - }, - "description": "The citation of the LLM's answer reference." - }, - "AiDialogueHistory": { - "title": "Dialogue history", - "type": "object", - "properties": { - "prompt": { - "type": "string", - "description": "The prompt previously provided by the client and answered by the LLM.", - "example": "Make my email about public APIs sound more professional." - }, - "answer": { - "type": "string", - "description": "The answer previously provided by the LLM.", - "example": "Here is the first draft of your professional email about public APIs." - }, - "created_at": { - "type": "string", - "format": "date-time", - "description": "The ISO date formatted timestamp of when the previous answer to the prompt was created.", - "example": "2012-12-12T10:53:43-08:00" - } - }, - "description": "A context object that can hold prior prompts and answers." - }, - "CompletionRuleVariable": { - "title": "Completion rule variable", - "type": "object", - "description": "A completion\nrule object. Determines\nif an action should be completed\nby all or any assignees.", - "required": [ - "type", - "variable_type", - "variable_value" - ], - "properties": { - "type": { - "type": "string", - "enum": [ - "variable" - ], - "description": "Completion\nRule object type.\n", - "example": "variable" - }, - "variable_type": { - "type": "string", - "description": "Variable type\nfor the Completion\nRule object.\n", - "example": "task_completion_rule", - "enum": [ - "task_completion_rule" - ] - }, - "variable_value": { - "type": "string", - "description": "Variable\nvalues for a completion\nrule.\n", - "example": "all_assignees", - "enum": [ - "all_assignees", - "any_assignees" - ] - } - } - }, - "CollaboratorVariable": { - "title": "Collaborator variable", - "type": "object", - "description": "A collaborator\nobject. Allows to\nspecify a list of user\nID's that are affected\nby the workflow result.", - "required": [ - "type", - "variable_type", - "variable_value" - ], - "properties": { - "type": { - "type": "string", - "enum": [ - "variable" - ], - "description": "Collaborator\nobject type.\n", - "example": "variable" - }, - "variable_type": { - "type": "string", - "description": "Variable type \nfor the Collaborator\nobject.\n", - "example": "user_list", - "enum": [ - "user_list" - ] - }, - "variable_value": { - "type": "array", - "description": "A list of user IDs.", - "items": { - "type": "object", - "required": [ - "type", - "id" - ], - "description": "User variable used\nin workflow outcomes.", - "properties": { - "type": { - "type": "string", - "enum": [ - "user" - ], - "description": "The object type.", - "example": "user" - }, - "id": { - "type": "string", - "description": "User's ID.", - "example": "636281" - } - } - } - } - } - }, - "FileOrFolderScope": { - "title": "File or folder scope", - "type": "object", - "description": "A relation between a resource (file or folder) and the scopes for which the resource can be accessed", - "properties": { - "scope": { - "type": "string", - "description": "The scopes for the resource access", - "example": "item_download", - "enum": [ - "annotation_edit", - "annotation_view_all", - "annotation_view_self", - "base_explorer", - "base_picker", - "base_preview", - "base_upload", - "item_delete", - "item_download", - "item_preview", - "item_rename", - "item_share", - "item_upload" - ] - }, - "object": { - "allOf": [ - { - "oneOf": [ - { - "$ref": "#/components/schemas/Folder--Mini" - }, - { - "$ref": "#/components/schemas/File--Mini" - } - ] - }, - { - "description": "The file or folder resource" - } - ] - } - } - }, - "EventSource": { - "title": "Event source", - "type": "object", - "x-box-resource-id": "event_source", - "description": "The source file or folder that triggered an event in\nthe event stream.", - "required": [ - "item_type", - "item_id", - "item_name" - ], - "properties": { - "item_type": { - "type": "string", - "nullable": false, - "enum": [ - "file", - "folder" - ], - "description": "The type of the item that the event\nrepresents. Can be `file` or `folder`.\n", - "example": "file" - }, - "item_id": { - "type": "string", - "nullable": false, - "description": "The unique identifier that represents the\nitem.\n", - "example": "560284318361" - }, - "item_name": { - "type": "string", - "nullable": false, - "description": "The name of the item.\n", - "example": "report.pdf" - }, - "classification": { - "type": "object", - "description": "The object containing classification information for the item that\ntriggered the event. This field will not appear if the item does not\nhave a classification set.", - "properties": { - "name": { - "type": "string", - "description": "The classification's name", - "example": "Top Secret" - } - } - }, - "parent": { - "allOf": [ - { - "$ref": "#/components/schemas/Folder--Mini" - }, - { - "description": "The optional folder that this folder is located within.\n\nThis value may be `null` for some folders such as the\nroot folder or the trash folder." - } - ], - "nullable": true - }, - "owned_by": { - "allOf": [ - { - "$ref": "#/components/schemas/User--Mini" - }, - { - "description": "The user who owns this item." - }, - { - "nullable": false - } - ] - } - } - }, - "AppItemEventSource": { - "title": "AppItem event source", - "type": "object", - "x-box-resource-id": "app_item_event_source", - "description": "The AppItem that triggered an event in the event stream.", - "required": [ - "id", - "type", - "app_item_type" - ], - "properties": { - "id": { - "type": "string", - "description": "The id of the `AppItem`", - "example": "6374669741" - }, - "type": { - "type": "string", - "nullable": false, - "enum": [ - "app_item" - ], - "description": "The type of the source that this event represents. Can only be `app_item`.\n", - "example": "app_item" - }, - "app_item_type": { - "type": "string", - "description": "The type of the `AppItem`", - "example": "hubs" - }, - "user": { - "allOf": [ - { - "$ref": "#/components/schemas/User--Mini" - }, - { - "description": "The user that triggered the event." - } - ] - }, - "group": { - "allOf": [ - { - "$ref": "#/components/schemas/Group--Mini" - }, - { - "description": "The group that triggered the event." - } - ] - } - } - }, - "KeywordSkillCard": { - "type": "object", - "x-box-resource-id": "keyword_skill_card", - "x-box-tag": "skills", - "title": "Keyword Skill Card", - "description": "A skill card that contains a set of keywords", - "required": [ - "type", - "skill_card_type", - "skill", - "invocation", - "entries" - ], - "properties": { - "created_at": { - "type": "string", - "format": "date-time", - "example": "2018-04-13T13:53:23-07:00", - "description": "The optional date and time this card was created at." - }, - "type": { - "type": "string", - "description": "`skill_card`", - "example": "skill_card", - "enum": [ - "skill_card" - ] - }, - "skill_card_type": { - "type": "string", - "description": "`keyword`", - "example": "keyword", - "enum": [ - "keyword" - ] - }, - "skill_card_title": { - "type": "object", - "description": "The title of the card.", - "required": [ - "message" - ], - "properties": { - "code": { - "type": "string", - "example": "labels", - "description": "An optional identifier for the title." - }, - "message": { - "type": "string", - "example": "Labels", - "description": "The actual title to show in the UI." - } - } - }, - "skill": { - "type": "object", - "description": "The service that applied this metadata.", - "required": [ - "type", - "id" - ], - "properties": { - "type": { - "type": "string", - "example": "service", - "description": "`service`", - "enum": [ - "service" - ] - }, - "id": { - "type": "string", - "example": "image-recognition-service", - "description": "A custom identifier that represent the service that\napplied this metadata." - } - } - }, - "invocation": { - "type": "object", - "description": "The invocation of this service, used to track\nwhich instance of a service applied the metadata.", - "required": [ - "type", - "id" - ], - "properties": { - "type": { - "type": "string", - "example": "skill_invocation", - "description": "`skill_invocation`", - "enum": [ - "skill_invocation" - ] - }, - "id": { - "type": "string", - "example": "image-recognition-service-123", - "description": "A custom identifier that represent the instance of\nthe service that applied this metadata. For example,\nif your `image-recognition-service` runs on multiple\nnodes, this field can be used to identify the ID of\nthe node that was used to apply the metadata." - } - } - }, - "entries": { - "type": "array", - "description": "An list of entries in the metadata card.", - "items": { - "type": "object", - "description": "An entry in the `entries` attribute of a metadata card", - "properties": { - "text": { - "type": "string", - "example": "keyword1", - "description": "The text of the keyword." - } - } - } - } - } - }, - "IntegrationMappingSlackOptions": { - "title": "Integration mapping options for type Slack", - "type": "object", - "description": "The schema for an integration mapping options object for Slack type.", - "properties": { - "is_access_management_disabled": { - "type": "boolean", - "example": true, - "description": "Indicates whether or not channel member\naccess to the underlying box item\nshould be automatically managed.\nDepending on type of channel, access is managed\nthrough creating collaborations or shared links.", - "nullable": false - } - } - }, - "IntegrationMappingPartnerItemSlack": { - "title": "Integration mapping mapped item schema for type Slack", - "type": "object", - "description": "The schema for an integration mapping mapped item object for type Slack.\n\nDepending if Box for Slack is installed at the org or workspace level,\nprovide **either** `slack_org_id` **or** `slack_workspace_id`.\nDo not use both parameters at the same time.", - "properties": { - "type": { - "type": "string", - "enum": [ - "channel" - ], - "example": "channel", - "description": "Type of the mapped item referenced in `id`", - "nullable": false - }, - "id": { - "type": "string", - "example": "C12378991223", - "description": "ID of the mapped item (of type referenced in `type`)", - "nullable": false - }, - "slack_workspace_id": { - "type": "string", - "example": "T12352314", - "description": "ID of the Slack workspace with which the item is associated. Use this parameter if Box for Slack is installed at a workspace level. Do not use `slack_org_id` at the same time.", - "nullable": true - }, - "slack_org_id": { - "type": "string", - "example": "E1234567", - "description": "ID of the Slack org with which the item is associated. Use this parameter if Box for Slack is installed at the org level. Do not use `slack_workspace_id` at the same time.", - "nullable": true - } - }, - "required": [ - "id", - "type" - ] - }, - "IntegrationMappingBoxItemSlack": { - "title": "Integration mapping Box item schema for type Slack", - "type": "object", - "description": "The schema for an integration mapping Box item object for type Slack", - "properties": { - "type": { - "type": "string", - "enum": [ - "folder" - ], - "example": "folder", - "description": "Type of the mapped item referenced in `id`", - "nullable": false - }, - "id": { - "type": "string", - "example": "1234567891", - "description": "ID of the mapped item (of type referenced in `type`)", - "nullable": false - } - }, - "required": [ - "id", - "type" - ] - }, - "Outcome": { - "title": "Outcome", - "type": "object", - "description": "An instance of an outcome.", - "required": [ - "id" - ], - "properties": { - "id": { - "type": "string", - "description": "ID of a specific outcome", - "example": "17363629" - }, - "collaborators": { - "allOf": [ - { - "$ref": "#/components/schemas/CollaboratorVariable" - }, - { - "description": "Lists collaborators\naffected by the workflow\nresult." - } - ] - }, - "completion_rule": { - "allOf": [ - { - "$ref": "#/components/schemas/CompletionRuleVariable" - }, - { - "description": "Determines\nif an action should be completed\nby all or any assignees." - } - ] - }, - "file_collaborator_role": { - "allOf": [ - { - "$ref": "#/components/schemas/RoleVariable" - }, - { - "description": "Determines if the\nworkflow outcome for\na file\naffects a specific\ncollaborator role." - } - ] - }, - "task_collaborators": { - "allOf": [ - { - "$ref": "#/components/schemas/CollaboratorVariable" - }, - { - "description": "Lists collaborators\naffected by the task workflow\nresult." - } - ] - }, - "role": { - "allOf": [ - { - "$ref": "#/components/schemas/RoleVariable" - }, - { - "description": "Determines if the\nworkflow outcome\naffects a specific\ncollaborator role." - } - ] - } - } - }, - "RoleVariable": { - "title": "Role variable", - "type": "object", - "description": "Determines if the\nworkflow outcome\naffects a specific\ncollaborator role.", - "required": [ - "type", - "variable_type", - "variable_value" - ], - "properties": { - "type": { - "type": "string", - "enum": [ - "variable" - ], - "description": "Role object type.\n", - "example": "variable" - }, - "variable_type": { - "type": "string", - "description": "The variable type used\nby the object.\n", - "example": "collaborator_role", - "enum": [ - "collaborator_role" - ] - }, - "variable_value": { - "allOf": [ - { - "type": "string", - "description": "The level of access granted.", - "example": "editor", - "enum": [ - "editor", - "viewer", - "previewer", - "uploader", - "previewer uploader", - "viewer uploader", - "co-owner" - ] - }, - { - "description": "Variable values you can use\nfor the role parameter." - } - ] - } - } - }, - "TimelineSkillCard": { - "type": "object", - "x-box-resource-id": "timeline_skill_card", - "x-box-tag": "skills", - "title": "Timeline Skill Card", - "description": "A Box Skill metadata card that places a list of images on a\ntimeline.", - "required": [ - "type", - "skill_card_type", - "skill", - "invocation", - "entries" - ], - "properties": { - "created_at": { - "type": "string", - "format": "date-time", - "example": "2018-04-13T13:53:23-07:00", - "description": "The optional date and time this card was created at." - }, - "type": { - "type": "string", - "description": "`skill_card`", - "example": "skill_card", - "enum": [ - "skill_card" - ] - }, - "skill_card_type": { - "type": "string", - "description": "`timeline`", - "example": "timeline", - "enum": [ - "timeline" - ] - }, - "skill_card_title": { - "type": "object", - "description": "The title of the card.", - "required": [ - "message" - ], - "properties": { - "code": { - "type": "string", - "example": "Faces", - "description": "An optional identifier for the title." - }, - "message": { - "type": "string", - "example": "Faces", - "description": "The actual title to show in the UI." - } - } - }, - "skill": { - "type": "object", - "description": "The service that applied this metadata.", - "required": [ - "type", - "id" - ], - "properties": { - "type": { - "type": "string", - "example": "service", - "description": "`service`", - "enum": [ - "service" - ] - }, - "id": { - "type": "string", - "example": "image-recognition-service", - "description": "A custom identifier that represent the service that\napplied this metadata." - } - } - }, - "invocation": { - "type": "object", - "description": "The invocation of this service, used to track\nwhich instance of a service applied the metadata.", - "required": [ - "type", - "id" - ], - "properties": { - "type": { - "type": "string", - "example": "skill_invocation", - "description": "`skill_invocation`", - "enum": [ - "skill_invocation" - ] - }, - "id": { - "type": "string", - "example": "image-recognition-service-123", - "description": "A custom identifier that represent the instance of\nthe service that applied this metadata. For example,\nif your `image-recognition-service` runs on multiple\nnodes, this field can be used to identify the ID of\nthe node that was used to apply the metadata." - } - } - }, - "duration": { - "type": "integer", - "example": 1000, - "description": "An total duration in seconds of the timeline." - }, - "entries": { - "type": "array", - "description": "A list of entries on the timeline.", - "items": { - "type": "object", - "description": "An single item that's placed on multiple items on the timeline.", - "properties": { - "text": { - "type": "string", - "example": "John", - "description": "The text of the entry. This would be the display\nname for an item being placed on the timeline, for example the name\nof the person who was detected in a video." - }, - "appears": { - "type": "array", - "description": "Defines a list of timestamps for when this item should appear on the\ntimeline.", - "required": [ - "start", - "end" - ], - "items": { - "type": "object", - "description": "The timestamp for an entry.", - "properties": { - "start": { - "type": "integer", - "example": 1, - "description": "The time in seconds when an\nentry should start appearing on a timeline." - }, - "end": { - "type": "integer", - "example": 20, - "description": "The time in seconds when an\nentry should stop appearing on a timeline." - } - } - } - }, - "image_url": { - "type": "string", - "description": "The image to show on a for an entry that appears\non a timeline. This image URL is required for every entry.\n\nThe image will be shown in a\nlist of items (for example faces), and clicking\nthe image will show the user where that entry\nappears during the duration of this entry.", - "example": "https://example.com/image1.jpg" - } - } - } - } - } - }, - "TranscriptSkillCard": { - "type": "object", - "x-box-resource-id": "transcript_skill_card", - "x-box-tag": "skills", - "title": "Transcript Skill Card", - "description": "A Box Skill metadata card that adds a transcript to a file.", - "required": [ - "type", - "skill_card_type", - "skill", - "invocation", - "entries" - ], - "properties": { - "created_at": { - "type": "string", - "format": "date-time", - "example": "2018-04-13T13:53:23-07:00", - "description": "The optional date and time this card was created at." - }, - "type": { - "type": "string", - "description": "`skill_card`", - "example": "skill_card", - "enum": [ - "skill_card" - ] - }, - "skill_card_type": { - "type": "string", - "description": "`transcript`", - "example": "transcript", - "enum": [ - "transcript" - ] - }, - "skill_card_title": { - "type": "object", - "description": "The title of the card.", - "required": [ - "message" - ], - "properties": { - "code": { - "type": "string", - "example": "my_transcripts", - "description": "An optional identifier for the title." - }, - "message": { - "type": "string", - "example": "My Transcripts", - "description": "The actual title to show in the UI." - } - } - }, - "skill": { - "type": "object", - "description": "The service that applied this metadata.", - "required": [ - "type", - "id" - ], - "properties": { - "type": { - "type": "string", - "example": "service", - "description": "`service`", - "enum": [ - "service" - ] - }, - "id": { - "type": "string", - "example": "transciption-service", - "description": "A custom identifier that represent the service that\napplied this metadata." - } - } - }, - "invocation": { - "type": "object", - "description": "The invocation of this service, used to track\nwhich instance of a service applied the metadata.", - "required": [ - "type", - "id" - ], - "properties": { - "type": { - "type": "string", - "example": "skill_invocation", - "description": "`skill_invocation`", - "enum": [ - "skill_invocation" - ] - }, - "id": { - "type": "string", - "example": "transciption-service-123", - "description": "A custom identifier that represent the instance of\nthe service that applied this metadata. For example,\nif your `image-recognition-service` runs on multiple\nnodes, this field can be used to identify the ID of\nthe node that was used to apply the metadata." - } - } - }, - "duration": { - "type": "integer", - "example": 1000, - "description": "An optional total duration in seconds.\n\nUsed with a `skill_card_type` of `transcript` or\n`timeline`." - }, - "entries": { - "type": "array", - "description": "An list of entries for the card. This represents the individual entries of\nthe transcription.", - "items": { - "type": "object", - "description": "An entry in the `entries` attribute of a metadata card", - "properties": { - "text": { - "type": "string", - "example": "Hi, and welcome to this video...", - "description": "The text of the entry. This would be the transcribed text assigned\nto the entry on the timeline." - }, - "appears": { - "type": "array", - "description": "Defines when a transcribed bit of text appears. This only includes a\nstart time and no end time.", - "required": [ - "start" - ], - "items": { - "type": "object", - "description": "The timestamp for an entry.", - "properties": { - "start": { - "type": "integer", - "example": 1, - "description": "The time in seconds when an\nentry should start appearing on a timeline." - } - } - } - } - } - } - } - } - }, - "StatusSkillCard": { - "type": "object", - "x-box-resource-id": "status_skill_card", - "x-box-tag": "skills", - "title": "Status Skill Card", - "description": "A Box Skill metadata card that puts a status message in the metadata sidebar.", - "required": [ - "type", - "skill_card_type", - "skill", - "invocation", - "status" - ], - "properties": { - "created_at": { - "type": "string", - "format": "date-time", - "example": "2018-04-13T13:53:23-07:00", - "description": "The optional date and time this card was created at." - }, - "type": { - "type": "string", - "description": "`skill_card`", - "example": "skill_card", - "enum": [ - "skill_card" - ] - }, - "skill_card_type": { - "type": "string", - "description": "`status`", - "example": "status", - "enum": [ - "status" - ] - }, - "skill_card_title": { - "type": "object", - "description": "The title of the card.", - "required": [ - "message" - ], - "properties": { - "code": { - "type": "string", - "example": "status", - "description": "An optional identifier for the title." - }, - "message": { - "type": "string", - "example": "Status", - "description": "The actual title to show in the UI." - } - } - }, - "status": { - "type": "object", - "description": "Sets the status of the skill. This can be used to show a message to the user while the Skill is processing the data, or if it was not able to process the file.", - "required": [ - "code" - ], - "properties": { - "code": { - "type": "string", - "description": "A code for the status of this Skill invocation. By\ndefault each of these will have their own accompanied\nmessages. These can be adjusted by setting the `message`\nvalue on this object.", - "example": "success", - "enum": [ - "invoked", - "processing", - "success", - "transient_failure", - "permanent_failure" - ] - }, - "message": { - "type": "string", - "description": "A custom message that can be provided with this status.\nThis will be shown in the web app to the end user.", - "example": "We're preparing to process your file. Please hold on!" - } - } - }, - "skill": { - "type": "object", - "description": "The service that applied this metadata.", - "required": [ - "type", - "id" - ], - "properties": { - "type": { - "type": "string", - "example": "service", - "description": "`service`", - "enum": [ - "service" - ] - }, - "id": { - "type": "string", - "example": "image-recognition-service", - "description": "A custom identifier that represent the service that\napplied this metadata." - } - } - }, - "invocation": { - "type": "object", - "description": "The invocation of this service, used to track\nwhich instance of a service applied the metadata.", - "required": [ - "type", - "id" - ], - "properties": { - "type": { - "type": "string", - "example": "skill_invocation", - "description": "`skill_invocation`", - "enum": [ - "skill_invocation" - ] - }, - "id": { - "type": "string", - "example": "image-recognition-service-123", - "description": "A custom identifier that represent the instance of\nthe service that applied this metadata. For example,\nif your `image-recognition-service` runs on multiple\nnodes, this field can be used to identify the ID of\nthe node that was used to apply the metadata." - } - } - } - } - }, - "SignRequestCreateSigner": { - "title": "Signer fields used to create a Box Sign request object.", - "type": "object", - "description": "The schema for a Signer object used in\nfor creating a Box Sign request object.", - "properties": { - "email": { - "type": "string", - "description": "Email address of the signer.\nThe email address of the signer is required when making signature requests, except when using templates that are configured to include emails.", - "example": "example@gmail.com", - "nullable": true - }, - "role": { - "type": "string", - "enum": [ - "signer", - "approver", - "final_copy_reader" - ], - "description": "Defines the role of the signer in the signature request. A `signer`\nmust sign the document and an `approver` must approve the document. A\n`final_copy_reader` only receives the final signed document and signing\nlog.", - "example": "signer", - "default": "signer" - }, - "is_in_person": { - "type": "boolean", - "description": "Used in combination with an embed URL for a sender. After the\nsender signs, they are redirected to the next `in_person` signer.", - "example": true - }, - "order": { - "type": "integer", - "description": "Order of the signer", - "minimum": 0, - "example": 2 - }, - "embed_url_external_user_id": { - "type": "string", - "description": "User ID for the signer in an external application responsible\nfor authentication when accessing the embed URL.", - "example": "1234", - "nullable": true - }, - "redirect_url": { - "type": "string", - "description": "The URL that a signer will be redirected\nto after signing a document. Defining this URL\noverrides default or global redirect URL\nsettings for a specific signer.\nIf no declined redirect URL is specified,\nthis URL will be used for decline actions as well.", - "example": "https://example.com", - "nullable": true - }, - "declined_redirect_url": { - "type": "string", - "description": "The URL that a signer will be redirect\nto after declining to sign a document.\nDefining this URL overrides default or global\ndeclined redirect URL settings for a specific signer.", - "example": "https://declined-example.com", - "nullable": true - }, - "login_required": { - "type": "boolean", - "description": "If set to true, the signer will need to log in to a Box account\nbefore signing the request. If the signer does not have\nan existing account, they will have the option to create\na free Box account. Cannot be selected in combination with\n`verification_phone_number`.", - "example": true, - "nullable": true - }, - "verification_phone_number": { - "type": "string", - "description": "If set, this phone number will be used to verify the signer\nvia two-factor authentication before they are able to sign the document.\nCannot be selected in combination with `login_required`.", - "example": "6314578901", - "nullable": true - }, - "password": { - "type": "string", - "writeOnly": true, - "description": "If set, the signer is required to enter the password before they are able\nto sign a document. This field is write only.", - "example": "SecretPassword123", - "nullable": true - }, - "signer_group_id": { - "type": "string", - "description": "If set, signers who have the same value will be assigned to the same input and to the same signer group.\nA signer group is not a Box Group. It is an entity that belongs to a Sign Request and can only be\nused/accessed within this Sign Request. A signer group is expected to have more than one signer.\nIf the provided value is only used for one signer, this value will be ignored and request will be handled\nas it was intended for an individual signer. The value provided can be any string and only used to\ndetermine which signers belongs to same group. A successful response will provide a generated UUID value\ninstead for signers in the same signer group.", - "example": "cd4ff89-8fc1-42cf-8b29-1890dedd26d7", - "nullable": true - }, - "suppress_notifications": { - "type": "boolean", - "nullable": true, - "example": false, - "description": "If true, no emails about the sign request will be sent" - } - } - }, - "SignRequestPrefillTag": { - "title": "Sign request prefill tag", - "type": "object", - "description": "Prefill tags are used to prefill placeholders with signer input data. Only\none value field can be included.", - "properties": { - "document_tag_id": { - "type": "string", - "example": "1234", - "description": "This references the ID of a specific tag contained in a file of the signature request.", - "nullable": true - }, - "text_value": { - "type": "string", - "example": "text", - "description": "Text prefill value", - "nullable": true - }, - "checkbox_value": { - "type": "boolean", - "example": true, - "description": "Checkbox prefill value", - "nullable": true - }, - "date_value": { - "type": "string", - "format": "date", - "example": "2021-04-26", - "description": "Date prefill value", - "nullable": true + "$ref": "#/components/schemas/User--Base" + }, + { + "description": "The user who created this flow" + } + ] + } + } + } + } + } } - } + ], + "title": "Workflow", + "x-box-resource-id": "workflow", + "x-box-variant": "standard" }, - "SignRequestSignerInput": { - "title": "Sign Request Signer Input", + "Workflow--Full": { + "description": "Box Relay Workflows are objects that represent a named collection of flows.\n\nYou application must be authorized to use the `Manage Box Relay` application\nscope within the developer console in order to use this resource.", "type": "object", - "description": "Input created by a Signer on a Sign Request", - "required": [ - "page_index" - ], "allOf": [ { - "$ref": "#/components/schemas/SignRequestPrefillTag" + "$ref": "#/components/schemas/Workflow" }, { "properties": { - "type": { + "created_at": { + "description": "The date and time when the workflow was created on Box", "type": "string", - "enum": [ - "signature", - "date", - "text", - "checkbox", - "radio", - "dropdown" - ], - "description": "Type of input", - "example": "text" + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" }, - "content_type": { + "modified_at": { + "description": "The date and time when the workflow was last updated on Box", "type": "string", - "enum": [ - "signature", - "initial", - "stamp", - "date", - "checkbox", - "text", - "full_name", - "first_name", - "last_name", - "company", - "title", - "email", - "attachment", - "radio", - "dropdown" - ], - "description": "Content type of input", - "example": "signature" + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" }, - "page_index": { - "type": "integer", - "description": "Index of page that the input is on", - "example": 4 + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "description": "The user who created this workflow" + } + ] }, - "read_only": { - "type": "boolean", - "description": "Whether this input was defined as read-only(immutable by signers) or not", - "example": true + "modified_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "description": "The user who last modified this workflow" + } + ] } } } + ], + "title": "Workflow (Full)", + "x-box-resource-id": "workflow--full", + "x-box-variant": "full" + }, + "Workflow--Mini": { + "description": "Box Relay Workflows are objects that represent a named collection of flows.\n\nYou application must be authorized to use the `Manage Box Relay` application\nscope within the developer console in order to use this resource.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for the workflow", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`workflow`", + "type": "string", + "example": "workflow", + "enum": [ + "workflow" + ] + }, + "name": { + "description": "The name of the workflow", + "type": "string", + "example": "New Hire Workflow" + }, + "description": { + "description": "The description for a workflow.", + "type": "string", + "example": "This workflow sets off a new hire approval flow" + }, + "is_enabled": { + "description": "Specifies if this workflow is enabled", + "type": "boolean", + "example": true + } + }, + "title": "Workflow (Mini)", + "x-box-resource-id": "workflow--mini", + "x-box-tag": "workflows", + "x-box-variant": "mini", + "x-box-variants": [ + "mini", + "standard", + "full" ] }, - "SignRequestSigner": { - "title": "Signer fields for Box Sign request response", + "Workflows": { + "description": "A list of workflows.\n\nYou application must be authorized to use the `Manage Box Relay` application\nscope within the developer console in order to use this resource.", "type": "object", - "description": "The schema for a Signer object used\non the body of a Box Sign request object.", - "required": [ - "email" - ], "allOf": [ { - "$ref": "#/components/schemas/SignRequestCreateSigner" - }, - { + "type": "object", + "description": "The part of an API response that describes marker\nbased pagination", "properties": { - "has_viewed_document": { - "type": "boolean", - "readOnly": true, - "example": true, - "description": "Set to `true` if the signer views the document" - }, - "signer_decision": { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "signed", - "declined" - ], - "example": "signed", - "description": "Type of decision made by the signer." - }, - "finalized_at": { - "type": "string", - "format": "date-time", - "example": "2021-04-26T08:12:13.982Z", - "description": "Date and Time that the decision was made." - }, - "additional_info": { - "type": "string", - "example": "Requesting changes before signing.", - "description": "Additional info about the decision, such as the decline reason from the signer.", - "nullable": true - } - }, - "description": "Final decision made by the signer.", - "nullable": true - }, - "inputs": { - "type": "array", - "items": { - "$ref": "#/components/schemas/SignRequestSignerInput" - }, - "readOnly": true + "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.", + "type": "integer", + "format": "int64", + "example": 1000 }, - "embed_url": { + "next_marker": { + "description": "The marker for the start of the next page of results.", "type": "string", - "readOnly": true, - "example": "https://example.com", - "description": "URL to direct a signer to for signing", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, - "iframeable_embed_url": { + "prev_marker": { + "description": "The marker for the start of the previous page of results.", "type": "string", - "nullable": true, - "example": "https://app.box.com/embed/sign/document/gfhr4222-a331-494b-808b-79bc7f3992a3/f14d7098-a331-494b-808b-79bc7f3992a4", - "description": "This URL is specifically designed for\nsigning documents within an HTML `iframe` tag.\nIt will be returned in the response\nonly if the `embed_url_external_user_id`\nparameter was passed in the\n`create Box Sign request` call." + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true } } - } - ] - }, - "ShieldInformationBarrierReference": { - "title": "Shield information barrier reference", - "type": "object", - "x-box-resource-id": "shield_information_barrier_reference", - "x-box-tag": "shield_information_barrier_reports", - "description": "A shield information barrier reference for requests and responses", - "properties": { - "shield_information_barrier": { - "$ref": "#/components/schemas/ShieldInformationBarrier--Base" - } - } - }, - "ShieldInformationBarrierReportDetails": { - "title": "Shield information barrier report details", - "type": "object", - "x-box-resource-id": "shield_information_barrier_report_details", - "x-box-tag": "shield_information_barrier_reports", - "description": "Indicates which folder the report\nfile is located and any errors when generating the report.", - "properties": { - "details": { - "type": "object", + }, + { "properties": { - "folder_id": { - "type": "string", - "example": "124235", - "description": "Folder ID for locating this report" + "entries": { + "description": "A list of workflows", + "type": "array", + "items": { + "$ref": "#/components/schemas/Workflow" + } } } } - } + ], + "title": "Workflows", + "x-box-resource-id": "workflows", + "x-box-tag": "workflows" }, - "TrackingCode": { - "title": "Tracking code", + "ZipDownload": { + "description": "Represents a successful request to create a `zip` archive of a list of files\nand folders.", "type": "object", - "description": "Tracking codes allow an admin to generate reports from the admin console\nand assign an attribute to a specific group of users.\nThis setting must be enabled for an enterprise before it can be used.", "properties": { - "type": { + "download_url": { + "description": "The URL that can be used to download the `zip` archive. A `Get` request to\nthis URL will start streaming the items requested. By default, this URL\nis only valid for a few seconds, until the `expires_at` time, unless a\ndownload is started after which it is valid for the duration of the\ndownload.\n\nIt is important to note that the domain and path of this URL might change\nbetween API calls, and therefore it's important to use this URL as-is.", "type": "string", - "description": "`tracking_code`", - "example": "tracking_code", - "enum": [ - "tracking_code" - ] + "example": "https://dl.boxcloud.com/2.0/zip_downloads/Lu6fA9Ob-jyysp3AAvMF4AkLEwZwAYbL=tgj2zIC=eK9RvJnJbjJl9rNh2qBgHDpyOCAOhpM=vajg2mKq8Mdd/content" }, - "name": { + "status_url": { + "description": "The URL that can be used to get the status of the `zip` archive being\ndownloaded. A `Get` request to this URL will return the number of files\nin the archive as well as the number of items already downloaded or\nskipped. By default, this URL is only valid for a few seconds, until the\n`expires_at` time, unless a download is started after which the URL is\nvalid for 12 hours from the start of the download.\n\nIt is important to note that the domain and path of this URL might change\nbetween API calls, and therefore it's important to use this URL as-is.", "type": "string", - "description": "The name of the tracking code, which must be preconfigured in\nthe Admin Console", - "example": "department" + "example": "https://api.box.com/2.0/zip_downloads/Lu6fA9Ob-jyysp3AAvMF4AkLEwZwAYbL=tgj2zIC=eK9RvJnJbjJl9rNh2qBgHDpyOCAOhpM=vajg2mKq8Mdd/status" }, - "value": { + "expires_at": { + "description": "The time and date when this archive will expire. After this time the\n`status_url` and `download_url` will return an error.\n\nBy default, these URLs are only valid for a few seconds, unless a download\nis started after which the `download_url` is valid for the duration of the\ndownload, and the `status_url` is valid for 12 hours from the start of the\ndownload.", "type": "string", - "description": "The value of the tracking code", - "example": "Sales" + "format": "date-time", + "example": "2019-08-29T23:59:00-07:00" + }, + "name_conflicts": { + "description": "A list of conflicts that occurred when trying to create the archive. This\nwould occur when multiple items have been requested with the\nsame name.\n\nTo solve these conflicts, the API will automatically rename an item\nand return a mapping between the original item's name and its new\nname.\n\nFor every conflict, both files will be renamed and therefore this list\nwill always be a multiple of 2.", + "type": "array", + "items": { + "type": "array", + "description": "An individual conflict that occurred when trying to create the archive.\nThis includes an array of 2 objects, each containing the original name\nand the renamed filename of a file or folder for which the names\nconflicted.", + "items": { + "type": "object", + "description": "A file or folder for which a conflict was encountered, This object provides the type and identifier of the original item, as well as a mapping between its original name and it's new name as it will appear in the archive.", + "properties": { + "id": { + "description": "The identifier of the item", + "type": "string", + "example": "12345" + }, + "type": { + "description": "The type of this item", + "type": "string", + "example": "file", + "enum": [ + "file", + "folder" + ] + }, + "original_name": { + "description": "The original name of this item", + "type": "string", + "example": "Report.pdf" + }, + "download_name": { + "description": "The new name of this item as it will appear in the\ndownloaded `zip` archive.", + "type": "string", + "example": "3aa6a7.pdf" + } + } + } + } } - } + }, + "example": { + "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" + } + ] + ] + }, + "title": "Zip download", + "x-box-reference-category": "zip_downloads", + "x-box-resource-id": "zip_download", + "x-box-tag": "zip_downloads" }, - "MetadataFilter": { - "title": "Metadata filter", + "ZipDownloadRequest": { + "description": "A request to create a `zip` archive to download", "type": "object", - "x-box-resource-id": "metadata_filter", - "x-box-tag": "search", - "description": "A metadata template used to filter the search results.", "properties": { - "scope": { - "description": "Specifies the scope of the template to filter search results by.\n\nThis will be `enterprise_{enterprise_id}` for templates defined\nfor use in this enterprise, and `global` for general templates\nthat are available to all enterprises using Box.", - "type": "string", - "example": "enterprise", - "enum": [ - "global", - "enterprise", - "enterprise_{enterprise_id}" - ] - }, - "templateKey": { - "description": "The key of the template used to filter search results.\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", - "type": "string", - "example": "contract" - }, - "filters": { - "type": "object", - "description": "Specifies which fields on the template to filter the search\nresults by. When more than one field is specified, the query\nperforms a logical `AND` to ensure that the instance of the\ntemplate matches each of the fields specified.", - "example": { - "category": "online" - }, - "additionalProperties": { - "allOf": [ - { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "title": "Metadata field filter (multi-select)", - "type": "array", - "items": { - "type": "string" - }, - "description": "Specifies the values to match for a `multiSelect` metadata\nfield. When performing a search, the query will essentially\nperform an `OR` operation to match any template where any of\nthe provided values match this field.", - "example": [ - "online", - "enterprise" - ] - }, - { - "$ref": "#/components/schemas/MetadataFieldFilterFloatRange" - }, - { - "$ref": "#/components/schemas/MetadataFieldFilterDateRange" - } + "items": { + "description": "A list of items to add to the `zip` archive. These can\nbe folders or files.", + "type": "array", + "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": { + "description": "The type of the item to add to the archive.", + "type": "string", + "example": "file", + "enum": [ + "file", + "folder" ] }, - { - "example": "online" - }, - { - "x-box-example-key": "category" + "id": { + "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`.", + "type": "string", + "example": "12345" } - ] + } } - } - } - }, - "MetadataFieldFilterFloatRange": { - "title": "Metadata field filter (float range)", - "type": "object", - "x-box-resource-id": "metadata_field_filter_float_range", - "description": "Specifies which `float` field on the template to filter the search\nresults by, specifying a range of values that can match.", - "properties": { - "lt": { - "description": "Specifies the (inclusive) upper bound for the metadata field\nvalue. The value of a field must be lower than (`lt`) or\nequal to this value for the search query to match this\ntemplate.", - "type": "number", - "example": 200000 }, - "gt": { - "description": "Specifies the (inclusive) lower bound for the metadata field\nvalue. The value of a field must be greater than (`gt`) or\nequal to this value for the search query to match this\ntemplate.", - "type": "number", - "example": 100000 + "download_file_name": { + "description": "The optional name of the `zip` archive. This name will be appended by the\n`.zip` file extension, for example `January Financials.zip`.", + "type": "string", + "example": "January Financials" } - } + }, + "required": [ + "items" + ], + "title": "Create a `zip` archive" }, - "MetadataFieldFilterDateRange": { - "title": "Metadata field filter (date range)", + "ZipDownloadStatus": { + "description": "The status of a `zip` archive being downloaded.", "type": "object", - "x-box-resource-id": "metadata_field_filter_date_range", - "description": "Specifies which `date` field on the template to filter the search\nresults by, specifying a range of dates that can match.", "properties": { - "lt": { - "description": "Specifies the (inclusive) upper bound for the metadata field\nvalue. The value of a field must be lower than (`lt`) or\nequal to this value for the search query to match this\ntemplate.", - "type": "string", - "format": "date-time", - "example": "2017-08-01T00:00:00Z" + "total_file_count": { + "description": "The total number of files in the archive.", + "type": "integer", + "example": 20, + "maximum": 10000, + "minimum": 0 }, - "gt": { - "description": "Specifies the (inclusive) lower bound for the metadata field\nvalue. The value of a field must be greater than (`gt`) or\nequal to this value for the search query to match this\ntemplate.", + "downloaded_file_count": { + "description": "The number of files that have already been downloaded.", + "type": "integer", + "example": 10, + "minimum": 0 + }, + "skipped_file_count": { + "description": "The number of files that have been skipped as they could not be\ndownloaded. In many cases this is due to permission issues that have\nsurfaced between the creation of the request for the archive and the\narchive being downloaded.", + "type": "integer", + "example": 5, + "minimum": 0 + }, + "skipped_folder_count": { + "description": "The number of folders that have been skipped as they could not be\ndownloaded. In many cases this is due to permission issues that have\nsurfaced between the creation of the request for the archive and the\narchive being downloaded.", + "type": "integer", + "example": 5, + "minimum": 0 + }, + "state": { + "description": "The state of the archive being downloaded.", "type": "string", - "format": "date-time", - "example": "2016-08-01T00:00:00Z" + "example": "succeeded", + "default": "in_progress", + "enum": [ + "in_progress", + "failed", + "succeeded" + ] + } + }, + "title": "Zip download status", + "x-box-reference-category": "zip_downloads", + "x-box-resource-id": "zip_download_status", + "x-box-tag": "zip_downloads" + } + }, + "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" + } } } } } }, - "security": [ - { - "OAuth2Security": [] - } - ], "tags": [ { "name": "AI", @@ -39910,5 +39905,10 @@ "externalDocs": { "description": "Box Developer Documentation", "url": "https://developer.box.com" - } + }, + "security": [ + { + "OAuth2Security": [] + } + ] } \ No newline at end of file